Improve documentation for Beta release (#2894)
* Improve documentation * Incorporate text about Zebra from the last newsletter * Organize README and user docs * Add table of contents, organize heading levels * Fix link * capitalize list items * fix table of contents * format spacing issue Co-authored-by: Alfredo Garcia <oxarbitrage@gmail.com>
This commit is contained in:
parent
78529bd009
commit
4367b232fc
246
README.md
246
README.md
|
@ -6,13 +6,72 @@
|
||||||
[![codecov](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg)](https://codecov.io/gh/ZcashFoundation/zebra)
|
[![codecov](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg)](https://codecov.io/gh/ZcashFoundation/zebra)
|
||||||
![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)
|
![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- [Contents](#contents)
|
||||||
|
- [About](#about)
|
||||||
|
- [Beta Releases](#beta-releases)
|
||||||
|
- [Getting Started](#getting-started)
|
||||||
|
- [Current Features](#current-features)
|
||||||
|
- [Known Issues](#known-issues)
|
||||||
|
- [Future Work](#future-work)
|
||||||
|
- [Documentation](#documentation)
|
||||||
|
- [Security](#security)
|
||||||
|
- [License](#license)
|
||||||
|
|
||||||
## About
|
## About
|
||||||
|
|
||||||
[Zebra](https://zebra.zfnd.org/) is the Zcash Foundation's independent,
|
[Zebra](https://zebra.zfnd.org/) is the Zcash Foundation's independent,
|
||||||
consensus-compatible implementation of the Zcash protocol, currently under
|
consensus-compatible implementation of a Zcash node, currently under
|
||||||
development. Please [join us on Discord](https://discord.gg/na6QZNd) if you'd
|
development. It can be used to join the Zcash peer-to-peer network, which helps
|
||||||
|
keeping Zcash working by validating and broadcasting transactions, and maintaining
|
||||||
|
the Zcash blockchain state in a distributed manner.
|
||||||
|
Please [join us on Discord](https://discord.gg/na6QZNd) if you'd
|
||||||
like to find out more or get involved!
|
like to find out more or get involved!
|
||||||
|
|
||||||
|
Zcash is a cryptocurrency designed to preserve the user's privacy. Like most
|
||||||
|
cryptocurrencies, it works by a collection of software nodes run by members of
|
||||||
|
the Zcash community or any other interested parties. The nodes talk to each
|
||||||
|
other in peer-to-peer fashion in order to maintain the state of the Zcash
|
||||||
|
blockchain. They also communicate with miners who create news blocks. When a
|
||||||
|
Zcash user sends Zcash, their wallet broadcasts transactions to these nodes
|
||||||
|
which will eventually reach miners, and the mined transaction will then go
|
||||||
|
through Zcash nodes until they reach the recipient's wallet which will report
|
||||||
|
the received Zcash to the recipient.
|
||||||
|
|
||||||
|
The original Zcash node is named `zcashd` and is developed by the Electric Coin
|
||||||
|
Company as a fork of the original Bitcoin node. Zebra, on the other hand, is
|
||||||
|
an independent Zcash node implementation developed from scratch. Since they
|
||||||
|
implement the same protocol, `zcashd` and Zebra nodes can communicate with each
|
||||||
|
other.
|
||||||
|
|
||||||
|
If you just want to send and receive Zcash then you don't need to use Zebra
|
||||||
|
directly. You can download a Zcash wallet application which will handle that
|
||||||
|
for you. (Eventually, Zebra can be used by wallets to implement their
|
||||||
|
functionality.) You would want to run Zebra if you want to contribute to the
|
||||||
|
Zcash network: the more nodes are run, the more reliable the network will be
|
||||||
|
in terms of speed and resistance to denial of service attacks, for example.
|
||||||
|
|
||||||
|
These are some of advantages or benefits of Zebra:
|
||||||
|
|
||||||
|
- Better performance: since it was implemented from scratch, Zebra was able to be
|
||||||
|
implemented in a manner that is currently faster than `zcashd`.
|
||||||
|
- Better security: since it is developed in a memory-safe language (Rust), Zebra
|
||||||
|
is less likely to be affected by security bugs that could compromise the
|
||||||
|
environment where it is run.
|
||||||
|
- Better governance: with a new node deployment, there will be more developers
|
||||||
|
who can implement different features.
|
||||||
|
- Dev accessibility: there will be more developers which gives new developers
|
||||||
|
options for contributing to protocol development.
|
||||||
|
- Runtime safety: the detection of consensus bugs can happen quicker, preventing
|
||||||
|
the likelihood of black swan events.
|
||||||
|
- Spec safety: with several node implementations, it is much easier to notice
|
||||||
|
bugs and ambiguity in protocol specification.
|
||||||
|
- User options: different nodes present different features and tradeoffs for
|
||||||
|
users to decide on their preferred options.
|
||||||
|
- Additional contexts: wider target deployments for people to use a consensus
|
||||||
|
node in more contexts e.g. mobile, wasm, etc.
|
||||||
|
|
||||||
## Beta Releases
|
## Beta Releases
|
||||||
|
|
||||||
Every few weeks, we release a new Zebra beta [release](https://github.com/ZcashFoundation/zebra/releases).
|
Every few weeks, we release a new Zebra beta [release](https://github.com/ZcashFoundation/zebra/releases).
|
||||||
|
@ -62,44 +121,36 @@ unreliable on Testnet, and under less-than-perfect network conditions. See
|
||||||
our [current features](#current-features) and [roadmap](#future-work) for
|
our [current features](#current-features) and [roadmap](#future-work) for
|
||||||
details.
|
details.
|
||||||
|
|
||||||
### Getting Started
|
## Getting Started
|
||||||
|
|
||||||
Building `zebrad` requires [Rust](https://www.rust-lang.org/tools/install),
|
Building `zebrad` requires [Rust](https://www.rust-lang.org/tools/install),
|
||||||
[libclang](https://clang.llvm.org/get_started.html), and a C++ compiler.
|
[libclang](https://clang.llvm.org/get_started.html), and a C++ compiler.
|
||||||
|
|
||||||
#### Detailed Build and Run Instructions
|
### Build and Run Instructions
|
||||||
|
|
||||||
|
`zebrad` is still under development, so there is no supported packaging or
|
||||||
|
install mechanism. To run `zebrad`, follow the instructions to compile `zebrad`
|
||||||
|
for your platform:
|
||||||
|
|
||||||
1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).
|
1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).
|
||||||
- Using `rustup` installs the stable Rust toolchain, which `zebrad` targets.
|
|
||||||
2. Install Zebra's build dependencies:
|
2. Install Zebra's build dependencies:
|
||||||
- **libclang:** the `libclang`, `libclang-dev`, `llvm`, or `llvm-dev` packages, depending on your package manager
|
- **libclang:** the `libclang`, `libclang-dev`, `llvm`, or `llvm-dev` packages, depending on your package manager
|
||||||
- **clang** or another C++ compiler: `g++`, `Xcode`, or `MSVC`
|
- **clang** or another C++ compiler: `g++`, `Xcode`, or `MSVC`
|
||||||
3. Run `cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-alpha.19 zebrad`
|
3. Run `cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-alpha.19 zebrad`
|
||||||
4. Run `zebrad start`
|
4. Run `zebrad start` (see [Running Zebra](user/run.md) for more information)
|
||||||
|
|
||||||
If you're interested in testing out `zebrad` please feel free, but keep in mind
|
If you're interested in testing out `zebrad` please feel free, but keep in mind
|
||||||
that there is a lot of key functionality still missing.
|
that there is a lot of key functionality still missing.
|
||||||
|
|
||||||
#### Build Troubleshooting
|
For more detailed instructions, refer to the [documentation](https://zebra.zfnd.org/user/install.html).
|
||||||
|
|
||||||
If you're having trouble with:
|
|
||||||
- **dependencies:**
|
|
||||||
- install both `libclang` and `clang` - they are usually different packages
|
|
||||||
- use `cargo install` without `--locked` to build with the latest versions of each dependency
|
|
||||||
- **libclang:** check out the [clang-sys documentation](https://github.com/KyleMayes/clang-sys#dependencies)
|
|
||||||
- **g++ or MSVC++:** try using clang or Xcode instead
|
|
||||||
- **rustc:** use rustc 1.48 or later
|
|
||||||
- Zebra does not have a minimum supported Rust version (MSRV) policy yet
|
|
||||||
|
|
||||||
### System Requirements
|
### System Requirements
|
||||||
|
|
||||||
We usually build `zebrad` on systems with:
|
The recommended requirements for compiling and running `zebrad` are:
|
||||||
- 2+ CPU cores
|
- 4+ CPU cores
|
||||||
- 7+ GB RAM
|
- 16+ GB RAM
|
||||||
- 14+ GB of disk space
|
- 50GB+ available disk space for finalized state
|
||||||
|
- 100+ Mbps network connections
|
||||||
On many-core machines (like, 32-core) the build is very fast; on 2-core machines
|
|
||||||
it's less fast.
|
|
||||||
|
|
||||||
We continuously test that our builds and tests pass on:
|
We continuously test that our builds and tests pass on:
|
||||||
- Windows Server 2019
|
- Windows Server 2019
|
||||||
|
@ -107,71 +158,54 @@ We continuously test that our builds and tests pass on:
|
||||||
- Ubuntu 18.04 / the latest LTS
|
- Ubuntu 18.04 / the latest LTS
|
||||||
- Debian Buster
|
- Debian Buster
|
||||||
|
|
||||||
We usually run `zebrad` on systems with:
|
|
||||||
- 4+ CPU cores
|
|
||||||
- 16+ GB RAM
|
|
||||||
- 50GB+ available disk space for finalized state
|
|
||||||
- 100+ Mbps network connections
|
|
||||||
|
|
||||||
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
||||||
tested its exact limits yet.
|
tested its exact limits yet.
|
||||||
|
|
||||||
|
For more detailed requirements, refer to the [documentation](https://zebra.zfnd.org/user/requirements.html).
|
||||||
|
|
||||||
### Network Ports and Data Usage
|
### Network Ports and Data Usage
|
||||||
|
|
||||||
By default, Zebra uses the following inbound TCP listener ports:
|
By default, Zebra uses the following inbound TCP listener ports:
|
||||||
- 8233 on Mainnet
|
- 8233 on Mainnet
|
||||||
- 18233 on Testnet
|
- 18233 on Testnet
|
||||||
|
|
||||||
If Zebra is configured with a specific [`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr),
|
|
||||||
it will advertise this address to other nodes for inbound connections.
|
|
||||||
|
|
||||||
Zebra makes outbound connections to peers on any port.
|
|
||||||
But `zcashd` prefers peers on the default ports,
|
|
||||||
so that it can't be used for DDoS attacks on other networks.
|
|
||||||
|
|
||||||
`zebrad`'s typical network usage is:
|
`zebrad`'s typical network usage is:
|
||||||
- initial sync: 30 GB download
|
- Initial sync: 30 GB download
|
||||||
- ongoing updates: 10-50 MB upload and download per day, depending on peer requests
|
- Ongoing updates: 10-50 MB upload and download per day, depending on peer requests
|
||||||
|
|
||||||
The major constraint we've found on `zebrad` performance is the network weather,
|
For more detailed information, refer to the [documentation](https://zebra.zfnd.org/user/run.html).
|
||||||
especially the ability to make good connections to other Zcash network peers.
|
|
||||||
|
|
||||||
### Current Features
|
## Current Features
|
||||||
|
|
||||||
Network:
|
Network:
|
||||||
- synchronize the chain from peers
|
- Synchronize the chain from peers
|
||||||
- maintain a transaction mempool
|
- Maintain a transaction mempool
|
||||||
- download gossiped blocks and transactions from peers
|
- Download gossiped blocks and transactions from peers
|
||||||
- answer inbound peer requests for hashes, headers, blocks and transactions
|
- Answer inbound peer requests for hashes, headers, blocks and transactions
|
||||||
|
|
||||||
State:
|
State:
|
||||||
- persist block, transaction, UTXO, and nullifier indexes
|
- Persist block, transaction, UTXO, and nullifier indexes
|
||||||
- handle chain reorganizations
|
- Handle chain reorganizations
|
||||||
|
|
||||||
Proof of Work:
|
Proof of Work:
|
||||||
- validate equihash, block difficulty threshold, and difficulty adjustment
|
- Validate equihash, block difficulty threshold, and difficulty adjustment
|
||||||
- validate transaction merkle roots
|
- Validate transaction merkle roots
|
||||||
|
|
||||||
Validating proof of work increases the cost of creating a consensus split
|
Validating proof of work increases the cost of creating a consensus split
|
||||||
between `zebrad` and `zcashd`.
|
between `zebrad` and `zcashd`.
|
||||||
|
|
||||||
This release also implements some other Zcash consensus rules, to check that
|
This release also implements some other Zcash consensus rules, to check that
|
||||||
Zebra's [validation architecture](#architecture) supports future work on a
|
Zebra's [validation architecture](https://zebra.zfnd.org/dev/overview.html#architecture)
|
||||||
|
supports future work on a
|
||||||
full validating node:
|
full validating node:
|
||||||
- block and transaction structure
|
- Block and transaction structure
|
||||||
- checkpoint-based verification up to and including Canopy activation
|
- Checkpoint-based verification up to and including Canopy activation
|
||||||
- transaction validation (incomplete)
|
- Transaction validation (incomplete)
|
||||||
- transaction cryptography (incomplete)
|
- Transaction cryptography (incomplete)
|
||||||
- transaction scripts (incomplete)
|
- Transaction scripts (incomplete)
|
||||||
- batch verification (incomplete)
|
- Batch verification (incomplete)
|
||||||
|
|
||||||
### Dependencies
|
## Known Issues
|
||||||
|
|
||||||
Zebra primarily depends on pure Rust crates, and some Rust/C++ crates:
|
|
||||||
- [rocksdb](https://crates.io/crates/rocksdb)
|
|
||||||
- [zcash_script](https://crates.io/crates/zcash_script)
|
|
||||||
|
|
||||||
### Known Issues
|
|
||||||
|
|
||||||
There are a few bugs in Zebra that we're still working on fixing:
|
There are a few bugs in Zebra that we're still working on fixing:
|
||||||
- [When Zebra receives an unexpected network message from a peer, it disconnects from that peer #2107](https://github.com/ZcashFoundation/zebra/issues/2107)
|
- [When Zebra receives an unexpected network message from a peer, it disconnects from that peer #2107](https://github.com/ZcashFoundation/zebra/issues/2107)
|
||||||
|
@ -197,15 +231,15 @@ This phased approach allows us to test Zebra's independent implementation of the
|
||||||
consensus rules, before asking users to entrust it with their funds.
|
consensus rules, before asking users to entrust it with their funds.
|
||||||
|
|
||||||
Features:
|
Features:
|
||||||
- full consensus rule validation
|
- Full consensus rule validation
|
||||||
- wallet functionality
|
- Wallet functionality
|
||||||
- RPC functionality
|
- RPC functionality
|
||||||
|
|
||||||
Performance and Reliability:
|
Performance and Reliability:
|
||||||
- reliable syncing on Testnet
|
- Reliable syncing on Testnet
|
||||||
- reliable syncing under poor network conditions
|
- Reliable syncing under poor network conditions
|
||||||
- batch verification
|
- Batch verification
|
||||||
- performance tuning
|
- Performance tuning
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
|
@ -216,80 +250,6 @@ documentation](https://doc.zebra.zfnd.org) for the external API of our crates,
|
||||||
as well as [internal documentation](https://doc-internal.zebra.zfnd.org) for
|
as well as [internal documentation](https://doc-internal.zebra.zfnd.org) for
|
||||||
private APIs.
|
private APIs.
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
Unlike `zcashd`, which originated as a Bitcoin Core fork and inherited its
|
|
||||||
monolithic architecture, Zebra has a modular, library-first design, with the
|
|
||||||
intent that each component can be independently reused outside of the `zebrad`
|
|
||||||
full node. For instance, the `zebra-network` crate containing the network stack
|
|
||||||
can also be used to implement anonymous transaction relay, network crawlers, or
|
|
||||||
other functionality, without requiring a full node.
|
|
||||||
|
|
||||||
At a high level, the fullnode functionality required by `zebrad` is factored
|
|
||||||
into several components:
|
|
||||||
|
|
||||||
- [`zebra-chain`](https://doc.zebra.zfnd.org/zebra_chain/index.html), providing
|
|
||||||
definitions of core data structures for Zcash, such as blocks, transactions,
|
|
||||||
addresses, etc., and related functionality. It also contains the
|
|
||||||
implementation of the consensus-critical serialization formats used in Zcash.
|
|
||||||
The data structures in `zebra-chain` are defined to enforce
|
|
||||||
[*structural validity*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages)
|
|
||||||
by making invalid states unrepresentable. For instance, the
|
|
||||||
`Transaction` enum has variants for each transaction version, and it's
|
|
||||||
impossible to construct a transaction with, e.g., spend or output
|
|
||||||
descriptions but no binding signature, or, e.g., a version 2 (Sprout)
|
|
||||||
transaction with Sapling proofs. Currently, `zebra-chain` is oriented
|
|
||||||
towards verifying transactions, but will be extended to support creating them
|
|
||||||
in the future.
|
|
||||||
|
|
||||||
- [`zebra-network`](https://doc.zebra.zfnd.org/zebra_network/index.html),
|
|
||||||
providing an asynchronous, multithreaded implementation of the Zcash network
|
|
||||||
protocol inherited from Bitcoin. In contrast to `zcashd`, each peer
|
|
||||||
connection has a separate state machine, and the crate translates the
|
|
||||||
external network protocol into a stateless, request/response-oriented
|
|
||||||
protocol for internal use. The crate provides two interfaces:
|
|
||||||
- an auto-managed connection pool that load-balances local node requests
|
|
||||||
over available peers, and sends peer requests to a local inbound service,
|
|
||||||
and
|
|
||||||
- a `connect_isolated` method that produces a peer connection completely
|
|
||||||
isolated from all other node state. This can be used, for instance, to
|
|
||||||
safely relay data over Tor, without revealing distinguishing information.
|
|
||||||
|
|
||||||
- [`zebra-script`](https://doc.zebra.zfnd.org/zebra_script/index.html) provides
|
|
||||||
script validation. Currently, this is implemented by linking to the C++
|
|
||||||
script verification code from `zcashd`, but in the future we may implement a
|
|
||||||
pure-Rust script implementation.
|
|
||||||
|
|
||||||
- [`zebra-consensus`](https://doc.zebra.zfnd.org/zebra_consensus/index.html)
|
|
||||||
performs [*semantic validation*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages)
|
|
||||||
of blocks and transactions: all consensus
|
|
||||||
rules that can be checked independently of the chain state, such as
|
|
||||||
verification of signatures, proofs, and scripts. Internally, the library
|
|
||||||
uses [`tower-batch`](https://doc.zebra.zfnd.org/tower_batch/index.html) to
|
|
||||||
perform automatic, transparent batch processing of contemporaneous
|
|
||||||
verification requests.
|
|
||||||
|
|
||||||
- [`zebra-state`](https://doc.zebra.zfnd.org/zebra_state/index.html) is
|
|
||||||
responsible for storing, updating, and querying the chain state. The state
|
|
||||||
service is responsible for [*contextual verification*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages):
|
|
||||||
all consensus rules
|
|
||||||
that check whether a new block is a valid extension of an existing chain,
|
|
||||||
such as updating the nullifier set or checking that transaction inputs remain
|
|
||||||
unspent.
|
|
||||||
|
|
||||||
- [`zebrad`](https://doc.zebra.zfnd.org/zebrad/index.html) contains the full
|
|
||||||
node, which connects these components together and implements logic to handle
|
|
||||||
inbound requests from peers and the chain sync process.
|
|
||||||
|
|
||||||
- `zebra-rpc` and `zebra-client` will eventually contain the RPC and wallet
|
|
||||||
functionality, but as mentioned above, our goal is to implement replication
|
|
||||||
of chain state first before asking users to entrust Zebra with their funds.
|
|
||||||
|
|
||||||
All of these components can be reused as independent libraries, and all
|
|
||||||
communication between stateful components is handled internally by
|
|
||||||
[internal asynchronous RPC abstraction](https://docs.rs/tower/)
|
|
||||||
("microservices in one process").
|
|
||||||
|
|
||||||
## Security
|
## Security
|
||||||
|
|
||||||
Zebra has a [responsible disclosure policy](https://github.com/ZcashFoundation/zebra/blob/main/SECURITY.md), which we encourage security researchers to follow.
|
Zebra has a [responsible disclosure policy](https://github.com/ZcashFoundation/zebra/blob/main/SECURITY.md), which we encourage security researchers to follow.
|
||||||
|
|
|
@ -2,6 +2,7 @@
|
||||||
|
|
||||||
[Zebra](README.md)
|
[Zebra](README.md)
|
||||||
- [User Documentation](user.md)
|
- [User Documentation](user.md)
|
||||||
|
- [Zebra System Requirements](user/requirements.md)
|
||||||
- [Installing Zebra](user/install.md)
|
- [Installing Zebra](user/install.md)
|
||||||
- [Running Zebra](user/run.md)
|
- [Running Zebra](user/run.md)
|
||||||
- [Tracing Zebra](user/tracing.md)
|
- [Tracing Zebra](user/tracing.md)
|
||||||
|
|
|
@ -1,10 +1,8 @@
|
||||||
Design Overview
|
# Design Overview
|
||||||
---------------------
|
|
||||||
|
|
||||||
This document sketches the future design for Zebra.
|
This document sketches the future design for Zebra.
|
||||||
|
|
||||||
Desiderata
|
## Desiderata
|
||||||
==========
|
|
||||||
|
|
||||||
The following are general desiderata for Zebra:
|
The following are general desiderata for Zebra:
|
||||||
|
|
||||||
|
@ -30,26 +28,93 @@ The following are general desiderata for Zebra:
|
||||||
* Zebra should checkpoint on Canopy activation and drop all
|
* Zebra should checkpoint on Canopy activation and drop all
|
||||||
Sprout-related functionality not required post-Canopy.
|
Sprout-related functionality not required post-Canopy.
|
||||||
|
|
||||||
### Non-Goals
|
## Non-Goals
|
||||||
|
|
||||||
* Zebra keeps a copy of the chain state, so it isn't intended for
|
* Zebra keeps a copy of the chain state, so it isn't intended for
|
||||||
lightweight applications like light wallets. Those applications
|
lightweight applications like light wallets. Those applications
|
||||||
should use a light client protocol.
|
should use a light client protocol.
|
||||||
|
|
||||||
Internal Structure
|
## Architecture
|
||||||
==================
|
|
||||||
|
|
||||||
The following is a list of internal component libraries (crates), and
|
Unlike `zcashd`, which originated as a Bitcoin Core fork and inherited its
|
||||||
a description of functional responsibility.
|
monolithic architecture, Zebra has a modular, library-first design, with the
|
||||||
|
intent that each component can be independently reused outside of the `zebrad`
|
||||||
|
full node. For instance, the `zebra-network` crate containing the network stack
|
||||||
|
can also be used to implement anonymous transaction relay, network crawlers, or
|
||||||
|
other functionality, without requiring a full node.
|
||||||
|
|
||||||
`zebra-chain`
|
At a high level, the fullnode functionality required by `zebrad` is factored
|
||||||
--------------
|
into several components:
|
||||||
|
|
||||||
### Internal Dependencies
|
- [`zebra-chain`](https://doc.zebra.zfnd.org/zebra_chain/index.html), providing
|
||||||
|
definitions of core data structures for Zcash, such as blocks, transactions,
|
||||||
|
addresses, etc., and related functionality. It also contains the
|
||||||
|
implementation of the consensus-critical serialization formats used in Zcash.
|
||||||
|
The data structures in `zebra-chain` are defined to enforce
|
||||||
|
[*structural validity*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages)
|
||||||
|
by making invalid states unrepresentable. For instance, the
|
||||||
|
`Transaction` enum has variants for each transaction version, and it's
|
||||||
|
impossible to construct a transaction with, e.g., spend or output
|
||||||
|
descriptions but no binding signature, or, e.g., a version 2 (Sprout)
|
||||||
|
transaction with Sapling proofs. Currently, `zebra-chain` is oriented
|
||||||
|
towards verifying transactions, but will be extended to support creating them
|
||||||
|
in the future.
|
||||||
|
|
||||||
|
- [`zebra-network`](https://doc.zebra.zfnd.org/zebra_network/index.html),
|
||||||
|
providing an asynchronous, multithreaded implementation of the Zcash network
|
||||||
|
protocol inherited from Bitcoin. In contrast to `zcashd`, each peer
|
||||||
|
connection has a separate state machine, and the crate translates the
|
||||||
|
external network protocol into a stateless, request/response-oriented
|
||||||
|
protocol for internal use. The crate provides two interfaces:
|
||||||
|
- an auto-managed connection pool that load-balances local node requests
|
||||||
|
over available peers, and sends peer requests to a local inbound service,
|
||||||
|
and
|
||||||
|
- a `connect_isolated` method that produces a peer connection completely
|
||||||
|
isolated from all other node state. This can be used, for instance, to
|
||||||
|
safely relay data over Tor, without revealing distinguishing information.
|
||||||
|
|
||||||
|
- [`zebra-script`](https://doc.zebra.zfnd.org/zebra_script/index.html) provides
|
||||||
|
script validation. Currently, this is implemented by linking to the C++
|
||||||
|
script verification code from `zcashd`, but in the future we may implement a
|
||||||
|
pure-Rust script implementation.
|
||||||
|
|
||||||
|
- [`zebra-consensus`](https://doc.zebra.zfnd.org/zebra_consensus/index.html)
|
||||||
|
performs [*semantic validation*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages)
|
||||||
|
of blocks and transactions: all consensus
|
||||||
|
rules that can be checked independently of the chain state, such as
|
||||||
|
verification of signatures, proofs, and scripts. Internally, the library
|
||||||
|
uses [`tower-batch`](https://doc.zebra.zfnd.org/tower_batch/index.html) to
|
||||||
|
perform automatic, transparent batch processing of contemporaneous
|
||||||
|
verification requests.
|
||||||
|
|
||||||
|
- [`zebra-state`](https://doc.zebra.zfnd.org/zebra_state/index.html) is
|
||||||
|
responsible for storing, updating, and querying the chain state. The state
|
||||||
|
service is responsible for [*contextual verification*](https://zebra.zfnd.org/dev/rfcs/0002-parallel-verification.html#verification-stages):
|
||||||
|
all consensus rules
|
||||||
|
that check whether a new block is a valid extension of an existing chain,
|
||||||
|
such as updating the nullifier set or checking that transaction inputs remain
|
||||||
|
unspent.
|
||||||
|
|
||||||
|
- [`zebrad`](https://doc.zebra.zfnd.org/zebrad/index.html) contains the full
|
||||||
|
node, which connects these components together and implements logic to handle
|
||||||
|
inbound requests from peers and the chain sync process.
|
||||||
|
|
||||||
|
- `zebra-rpc` and `zebra-client` will eventually contain the RPC and wallet
|
||||||
|
functionality, but as mentioned above, our goal is to implement replication
|
||||||
|
of chain state first before asking users to entrust Zebra with their funds.
|
||||||
|
|
||||||
|
All of these components can be reused as independent libraries, and all
|
||||||
|
communication between stateful components is handled internally by
|
||||||
|
[internal asynchronous RPC abstraction](https://docs.rs/tower/)
|
||||||
|
("microservices in one process").
|
||||||
|
|
||||||
|
### `zebra-chain`
|
||||||
|
|
||||||
|
#### Internal Dependencies
|
||||||
|
|
||||||
None: these are the core data structure definitions.
|
None: these are the core data structure definitions.
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- definitions of commonly used data structures, e.g.,
|
- definitions of commonly used data structures, e.g.,
|
||||||
- `Block`,
|
- `Block`,
|
||||||
|
@ -62,18 +127,17 @@ None: these are the core data structure definitions.
|
||||||
- `ZcashSerialize` and `ZcashDeserialize`, which perform
|
- `ZcashSerialize` and `ZcashDeserialize`, which perform
|
||||||
consensus-critical serialization logic.
|
consensus-critical serialization logic.
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- [...]
|
- [...]
|
||||||
|
|
||||||
`zebra-network`
|
### `zebra-network`
|
||||||
----------------
|
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- `zebra-chain`
|
- `zebra-chain`
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- definition of a well structured, internal request/response protocol
|
- definition of a well structured, internal request/response protocol
|
||||||
- provides an abstraction for "this node" and "the network" using the
|
- provides an abstraction for "this node" and "the network" using the
|
||||||
|
@ -83,7 +147,7 @@ None: these are the core data structure definitions.
|
||||||
Bitcoin/Zcash protocol
|
Bitcoin/Zcash protocol
|
||||||
- tokio codec for Bitcoin/Zcash message encoding.
|
- tokio codec for Bitcoin/Zcash message encoding.
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- `Request`, an enum representing all possible requests in the internal protocol;
|
- `Request`, an enum representing all possible requests in the internal protocol;
|
||||||
- `Response`, an enum representing all possible responses in the internal protocol;
|
- `Response`, an enum representing all possible responses in the internal protocol;
|
||||||
|
@ -103,14 +167,13 @@ All peerset management (finding new peers, creating new outbound
|
||||||
connections, etc) is completely encapsulated, as is responsibility for
|
connections, etc) is completely encapsulated, as is responsibility for
|
||||||
routing outbound requests to appropriate peers.
|
routing outbound requests to appropriate peers.
|
||||||
|
|
||||||
`zebra-state`
|
### `zebra-state`
|
||||||
----------------
|
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- `zebra-chain` for data structure definitions.
|
- `zebra-chain` for data structure definitions.
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- block storage API
|
- block storage API
|
||||||
- operates on parsed block structs
|
- operates on parsed block structs
|
||||||
|
@ -127,7 +190,7 @@ routing outbound requests to appropriate peers.
|
||||||
- providing `tower::Service` interfaces for all of the above to
|
- providing `tower::Service` interfaces for all of the above to
|
||||||
support backpressure.
|
support backpressure.
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- `Request`, an enum representing all possible requests in the internal protocol;
|
- `Request`, an enum representing all possible requests in the internal protocol;
|
||||||
- blocks can be accessed via their chain height or hash
|
- blocks can be accessed via their chain height or hash
|
||||||
|
@ -141,44 +204,42 @@ send requests for the chain state.
|
||||||
All state management (adding blocks, getting blocks by index or hash) is completely
|
All state management (adding blocks, getting blocks by index or hash) is completely
|
||||||
encapsulated.
|
encapsulated.
|
||||||
|
|
||||||
`zebra-script`
|
### `zebra-script`
|
||||||
---------------
|
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- ??? depends on how it's implemented internally
|
- ??? depends on how it's implemented internally
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- the minimal Bitcoin script implementation required for Zcash
|
- the minimal Bitcoin script implementation required for Zcash
|
||||||
- script parsing
|
- script parsing
|
||||||
- context-free script validation
|
- context-free script validation
|
||||||
|
|
||||||
### Notes
|
#### Notes
|
||||||
|
|
||||||
This can wrap an existing script implementation at the beginning.
|
This can wrap an existing script implementation at the beginning.
|
||||||
|
|
||||||
If this existed in a "good" way, we could use it to implement tooling
|
If this existed in a "good" way, we could use it to implement tooling
|
||||||
for Zcash script inspection, debugging, etc.
|
for Zcash script inspection, debugging, etc.
|
||||||
|
|
||||||
### Questions
|
#### Questions
|
||||||
|
|
||||||
- How does this interact with NU4 script changes?
|
- How does this interact with NU4 script changes?
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- [...]
|
- [...]
|
||||||
|
|
||||||
`zebra-consensus`
|
### `zebra-consensus`
|
||||||
------------------
|
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- `zebra-chain` for data structures and parsing.
|
- `zebra-chain` for data structures and parsing.
|
||||||
- `zebra-state` to read and update the state database.
|
- `zebra-state` to read and update the state database.
|
||||||
- `zebra-script` for script parsing and validation.
|
- `zebra-script` for script parsing and validation.
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- consensus-specific parameters (network magics, genesis block, pow
|
- consensus-specific parameters (network magics, genesis block, pow
|
||||||
parameters, etc) that determine the network consensus
|
parameters, etc) that determine the network consensus
|
||||||
|
@ -199,7 +260,7 @@ for Zcash script inspection, debugging, etc.
|
||||||
- providing `tower::Service` interfaces for all of the above to
|
- providing `tower::Service` interfaces for all of the above to
|
||||||
support backpressure and batch validation.
|
support backpressure and batch validation.
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- `block::init() -> impl Service`, the main entry-point for block
|
- `block::init() -> impl Service`, the main entry-point for block
|
||||||
verification.
|
verification.
|
||||||
|
@ -212,60 +273,57 @@ for Zcash script inspection, debugging, etc.
|
||||||
The `init` entrypoints return `Service`s that can be used to
|
The `init` entrypoints return `Service`s that can be used to
|
||||||
verify blocks or transactions, and add them to the relevant state.
|
verify blocks or transactions, and add them to the relevant state.
|
||||||
|
|
||||||
`zebra-rpc`
|
### `zebra-rpc`
|
||||||
------------
|
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- `zebra-chain` for data structure definitions
|
- `zebra-chain` for data structure definitions
|
||||||
- `zebra-network` possibly? for definitions of network messages?
|
- `zebra-network` possibly? for definitions of network messages?
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- rpc interface
|
- rpc interface
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- [...]
|
- [...]
|
||||||
|
|
||||||
`zebra-client`
|
### `zebra-client`
|
||||||
-----------------
|
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- `zebra-chain` for structure definitions
|
- `zebra-chain` for structure definitions
|
||||||
- `zebra-state` for transaction queries and client/wallet state storage
|
- `zebra-state` for transaction queries and client/wallet state storage
|
||||||
- `zebra-script` possibly? for constructing transactions
|
- `zebra-script` possibly? for constructing transactions
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- implementation of some event a user might trigger
|
- implementation of some event a user might trigger
|
||||||
- would be used to implement a full wallet
|
- would be used to implement a full wallet
|
||||||
- create transactions, monitors shielded wallet state, etc.
|
- create transactions, monitors shielded wallet state, etc.
|
||||||
|
|
||||||
### Notes
|
#### Notes
|
||||||
|
|
||||||
Communication between the client code and the rest of the node should be done
|
Communication between the client code and the rest of the node should be done
|
||||||
by a tower service interface. Since the `Service` trait can abstract from a
|
by a tower service interface. Since the `Service` trait can abstract from a
|
||||||
function call to RPC, this means that it will be possible for us to isolate
|
function call to RPC, this means that it will be possible for us to isolate
|
||||||
all client code to a subprocess.
|
all client code to a subprocess.
|
||||||
|
|
||||||
### Exported types
|
#### Exported types
|
||||||
|
|
||||||
- [...]
|
- [...]
|
||||||
|
|
||||||
`zebrad`
|
### `zebrad`
|
||||||
---------
|
|
||||||
|
|
||||||
Abscissa-based application which loads configs, all application components,
|
Abscissa-based application which loads configs, all application components,
|
||||||
and connects them to each other.
|
and connects them to each other.
|
||||||
|
|
||||||
### Responsible for
|
#### Responsible for
|
||||||
|
|
||||||
- actually running the server
|
- actually running the server
|
||||||
- connecting functionality in dependencies
|
- connecting functionality in dependencies
|
||||||
|
|
||||||
### Internal Dependencies
|
#### Internal Dependencies
|
||||||
|
|
||||||
- `zebra-chain`
|
- `zebra-chain`
|
||||||
- `zebra-network`
|
- `zebra-network`
|
||||||
|
@ -274,8 +332,7 @@ and connects them to each other.
|
||||||
- `zebra-client`
|
- `zebra-client`
|
||||||
- `zebra-rpc`
|
- `zebra-rpc`
|
||||||
|
|
||||||
Unassigned functionality
|
### Unassigned functionality
|
||||||
------------------------
|
|
||||||
|
|
||||||
Responsibility for this functionality needs to be assigned to one of
|
Responsibility for this functionality needs to be assigned to one of
|
||||||
the modules above (subject to discussion):
|
the modules above (subject to discussion):
|
||||||
|
|
|
@ -1,13 +1,35 @@
|
||||||
# Installing Zebra
|
# Installing Zebra
|
||||||
|
|
||||||
Zebra is still under development, so there is no supported packaging or
|
`zebrad` is still under development, so there is no supported packaging or
|
||||||
install mechanism. To run Zebra, check out the git repository:
|
install mechanism. To run `zebrad`, follow the instructions to compile `zebrad`
|
||||||
```
|
for your platform:
|
||||||
git clone https://github.com/ZcashFoundation/zebra
|
|
||||||
```
|
|
||||||
and then run
|
|
||||||
```
|
|
||||||
cargo build
|
|
||||||
```
|
|
||||||
|
|
||||||
Be aware that Zebra is still in an extremely early stage of development.
|
1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).
|
||||||
|
- Using `rustup` installs the stable Rust toolchain, which `zebrad` targets.
|
||||||
|
2. Install Zebra's build dependencies:
|
||||||
|
- **libclang:** the `libclang`, `libclang-dev`, `llvm`, or `llvm-dev` packages, depending on your package manager
|
||||||
|
- **clang** or another C++ compiler: `g++`, `Xcode`, or `MSVC`
|
||||||
|
3. Run `cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-alpha.19 zebrad`
|
||||||
|
4. Run `zebrad start` (see [Running Zebra](user/run.md) for more information)
|
||||||
|
|
||||||
|
If you're interested in testing out `zebrad` please feel free, but keep in mind
|
||||||
|
that there is a lot of key functionality still missing.
|
||||||
|
|
||||||
|
#### Build Troubleshooting
|
||||||
|
|
||||||
|
If you're having trouble with:
|
||||||
|
- **dependencies:**
|
||||||
|
- install both `libclang` and `clang` - they are usually different packages
|
||||||
|
- use `cargo install` without `--locked` to build with the latest versions of each dependency
|
||||||
|
- **libclang:** check out the [clang-sys documentation](https://github.com/KyleMayes/clang-sys#dependencies)
|
||||||
|
- **g++ or MSVC++:** try using clang or Xcode instead
|
||||||
|
- **rustc:** use rustc 1.48 or later
|
||||||
|
- Zebra does not have a minimum supported Rust version (MSRV) policy yet
|
||||||
|
|
||||||
|
### Dependencies
|
||||||
|
|
||||||
|
Zebra primarily depends on pure Rust crates, and some Rust/C++ crates:
|
||||||
|
- [rocksdb](https://crates.io/crates/rocksdb)
|
||||||
|
- [zcash_script](https://crates.io/crates/zcash_script)
|
||||||
|
|
||||||
|
They will be automatically built along with `zebrad`.
|
||||||
|
|
|
@ -0,0 +1,24 @@
|
||||||
|
# System Requirements
|
||||||
|
|
||||||
|
We usually build `zebrad` on systems with:
|
||||||
|
- 2+ CPU cores
|
||||||
|
- 7+ GB RAM
|
||||||
|
- 14+ GB of disk space
|
||||||
|
|
||||||
|
On many-core machines (like, 32-core) the build is very fast; on 2-core machines
|
||||||
|
it's less fast.
|
||||||
|
|
||||||
|
We continuously test that our builds and tests pass on:
|
||||||
|
- Windows Server 2019
|
||||||
|
- macOS Big Sur 11.0
|
||||||
|
- Ubuntu 18.04 / the latest LTS
|
||||||
|
- Debian Buster
|
||||||
|
|
||||||
|
We usually run `zebrad` on systems with:
|
||||||
|
- 4+ CPU cores
|
||||||
|
- 16+ GB RAM
|
||||||
|
- 50GB+ available disk space for finalized state
|
||||||
|
- 100+ Mbps network connections
|
||||||
|
|
||||||
|
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
||||||
|
tested its exact limits yet.
|
|
@ -17,3 +17,24 @@ structure, and documentation for all of the config options can be found
|
||||||
- `1`: Application exited unsuccessfully
|
- `1`: Application exited unsuccessfully
|
||||||
- `2`: Application crashed
|
- `2`: Application crashed
|
||||||
- `zebrad` may also return platform-dependent codes.
|
- `zebrad` may also return platform-dependent codes.
|
||||||
|
|
||||||
|
## Network Ports and Data Usage
|
||||||
|
|
||||||
|
By default, Zebra uses the following inbound TCP listener ports:
|
||||||
|
- 8233 on Mainnet
|
||||||
|
- 18233 on Testnet
|
||||||
|
|
||||||
|
If Zebra is configured with a specific [`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr),
|
||||||
|
it will advertise this address to other nodes for inbound connections.
|
||||||
|
|
||||||
|
Zebra makes outbound connections to peers on any port.
|
||||||
|
But `zcashd` prefers peers on the default ports,
|
||||||
|
so that it can't be used for DDoS attacks on other networks.
|
||||||
|
|
||||||
|
`zebrad`'s typical network usage is:
|
||||||
|
- initial sync: 30 GB download
|
||||||
|
- ongoing updates: 10-50 MB upload and download per day, depending on peer requests
|
||||||
|
|
||||||
|
The major constraint we've found on `zebrad` performance is the network weather,
|
||||||
|
especially the ability to make good connections to other Zcash network peers.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue