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:
Conrado Gouvea
GitHub
parent
78529bd009
commit
4367b232fc
246
README.md
246
README.md
|
|
@ -6,13 +6,72 @@
|
|||
[](https://codecov.io/gh/ZcashFoundation/zebra)
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
[Zebra](https://zebra.zfnd.org/) is the Zcash Foundation's independent,
|
||||
consensus-compatible implementation of the Zcash protocol, currently under
|
||||
development. Please [join us on Discord](https://discord.gg/na6QZNd) if you'd
|
||||
consensus-compatible implementation of a Zcash node, currently under
|
||||
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!
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
details.
|
||||
|
||||
### Getting Started
|
||||
## Getting Started
|
||||
|
||||
Building `zebrad` requires [Rust](https://www.rust-lang.org/tools/install),
|
||||
[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).
|
||||
- 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`
|
||||
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
|
||||
For more detailed instructions, refer to the [documentation](https://zebra.zfnd.org/user/install.html).
|
||||
|
||||
### 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.
|
||||
The recommended requirements for compiling and running `zebrad` are:
|
||||
- 4+ CPU cores
|
||||
- 16+ GB RAM
|
||||
- 50GB+ available disk space for finalized state
|
||||
- 100+ Mbps network connections
|
||||
|
||||
We continuously test that our builds and tests pass on:
|
||||
- Windows Server 2019
|
||||
|
|
@ -107,71 +158,54 @@ We continuously test that our builds and tests pass on:
|
|||
- 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.
|
||||
|
||||
For more detailed requirements, refer to the [documentation](https://zebra.zfnd.org/user/requirements.html).
|
||||
|
||||
### 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
|
||||
- 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.
|
||||
For more detailed information, refer to the [documentation](https://zebra.zfnd.org/user/run.html).
|
||||
|
||||
### Current Features
|
||||
## Current Features
|
||||
|
||||
Network:
|
||||
- synchronize the chain from peers
|
||||
- maintain a transaction mempool
|
||||
- download gossiped blocks and transactions from peers
|
||||
- answer inbound peer requests for hashes, headers, blocks and transactions
|
||||
- Synchronize the chain from peers
|
||||
- Maintain a transaction mempool
|
||||
- Download gossiped blocks and transactions from peers
|
||||
- Answer inbound peer requests for hashes, headers, blocks and transactions
|
||||
|
||||
State:
|
||||
- persist block, transaction, UTXO, and nullifier indexes
|
||||
- handle chain reorganizations
|
||||
- Persist block, transaction, UTXO, and nullifier indexes
|
||||
- Handle chain reorganizations
|
||||
|
||||
Proof of Work:
|
||||
- validate equihash, block difficulty threshold, and difficulty adjustment
|
||||
- validate transaction merkle roots
|
||||
- Validate equihash, block difficulty threshold, and difficulty adjustment
|
||||
- Validate transaction merkle roots
|
||||
|
||||
Validating proof of work increases the cost of creating a consensus split
|
||||
between `zebrad` and `zcashd`.
|
||||
|
||||
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:
|
||||
- block and transaction structure
|
||||
- checkpoint-based verification up to and including Canopy activation
|
||||
- transaction validation (incomplete)
|
||||
- transaction cryptography (incomplete)
|
||||
- transaction scripts (incomplete)
|
||||
- batch verification (incomplete)
|
||||
- Block and transaction structure
|
||||
- Checkpoint-based verification up to and including Canopy activation
|
||||
- Transaction validation (incomplete)
|
||||
- Transaction cryptography (incomplete)
|
||||
- Transaction scripts (incomplete)
|
||||
- Batch verification (incomplete)
|
||||
|
||||
### 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)
|
||||
|
||||
### Known Issues
|
||||
## Known Issues
|
||||
|
||||
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)
|
||||
|
|
@ -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.
|
||||
|
||||
Features:
|
||||
- full consensus rule validation
|
||||
- wallet functionality
|
||||
- Full consensus rule validation
|
||||
- Wallet functionality
|
||||
- RPC functionality
|
||||
|
||||
Performance and Reliability:
|
||||
- reliable syncing on Testnet
|
||||
- reliable syncing under poor network conditions
|
||||
- batch verification
|
||||
- performance tuning
|
||||
- Reliable syncing on Testnet
|
||||
- Reliable syncing under poor network conditions
|
||||
- Batch verification
|
||||
- Performance tuning
|
||||
|
||||
## 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
|
||||
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
|
||||
|
||||
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)
|
||||
- [User Documentation](user.md)
|
||||
- [Zebra System Requirements](user/requirements.md)
|
||||
- [Installing Zebra](user/install.md)
|
||||
- [Running Zebra](user/run.md)
|
||||
- [Tracing Zebra](user/tracing.md)
|
||||
|
|
|
|||
|
|
@ -1,10 +1,8 @@
|
|||
Design Overview
|
||||
---------------------
|
||||
# Design Overview
|
||||
|
||||
This document sketches the future design for Zebra.
|
||||
|
||||
Desiderata
|
||||
==========
|
||||
## Desiderata
|
||||
|
||||
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
|
||||
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
|
||||
lightweight applications like light wallets. Those applications
|
||||
should use a light client protocol.
|
||||
|
||||
Internal Structure
|
||||
==================
|
||||
## Architecture
|
||||
|
||||
The following is a list of internal component libraries (crates), and
|
||||
a description of functional responsibility.
|
||||
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.
|
||||
|
||||
`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.
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- definitions of commonly used data structures, e.g.,
|
||||
- `Block`,
|
||||
|
|
@ -62,18 +127,17 @@ None: these are the core data structure definitions.
|
|||
- `ZcashSerialize` and `ZcashDeserialize`, which perform
|
||||
consensus-critical serialization logic.
|
||||
|
||||
### Exported types
|
||||
#### Exported types
|
||||
|
||||
- [...]
|
||||
|
||||
`zebra-network`
|
||||
----------------
|
||||
### `zebra-network`
|
||||
|
||||
### Internal Dependencies
|
||||
#### Internal Dependencies
|
||||
|
||||
- `zebra-chain`
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- definition of a well structured, internal request/response protocol
|
||||
- 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
|
||||
- tokio codec for Bitcoin/Zcash message encoding.
|
||||
|
||||
### Exported types
|
||||
#### Exported types
|
||||
|
||||
- `Request`, an enum representing all possible requests 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
|
||||
routing outbound requests to appropriate peers.
|
||||
|
||||
`zebra-state`
|
||||
----------------
|
||||
### `zebra-state`
|
||||
|
||||
### Internal Dependencies
|
||||
#### Internal Dependencies
|
||||
|
||||
- `zebra-chain` for data structure definitions.
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- block storage API
|
||||
- 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
|
||||
support backpressure.
|
||||
|
||||
### Exported types
|
||||
#### Exported types
|
||||
|
||||
- `Request`, an enum representing all possible requests in the internal protocol;
|
||||
- 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
|
||||
encapsulated.
|
||||
|
||||
`zebra-script`
|
||||
---------------
|
||||
### `zebra-script`
|
||||
|
||||
### Internal Dependencies
|
||||
#### Internal Dependencies
|
||||
|
||||
- ??? depends on how it's implemented internally
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- the minimal Bitcoin script implementation required for Zcash
|
||||
- script parsing
|
||||
- context-free script validation
|
||||
|
||||
### Notes
|
||||
#### Notes
|
||||
|
||||
This can wrap an existing script implementation at the beginning.
|
||||
|
||||
If this existed in a "good" way, we could use it to implement tooling
|
||||
for Zcash script inspection, debugging, etc.
|
||||
|
||||
### Questions
|
||||
#### Questions
|
||||
|
||||
- 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-state` to read and update the state database.
|
||||
- `zebra-script` for script parsing and validation.
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- consensus-specific parameters (network magics, genesis block, pow
|
||||
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
|
||||
support backpressure and batch validation.
|
||||
|
||||
### Exported types
|
||||
#### Exported types
|
||||
|
||||
- `block::init() -> impl Service`, the main entry-point for block
|
||||
verification.
|
||||
|
|
@ -212,60 +273,57 @@ for Zcash script inspection, debugging, etc.
|
|||
The `init` entrypoints return `Service`s that can be used to
|
||||
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-network` possibly? for definitions of network messages?
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- rpc interface
|
||||
|
||||
### Exported types
|
||||
#### Exported types
|
||||
|
||||
- [...]
|
||||
|
||||
`zebra-client`
|
||||
-----------------
|
||||
### `zebra-client`
|
||||
|
||||
### Internal Dependencies
|
||||
#### Internal Dependencies
|
||||
|
||||
- `zebra-chain` for structure definitions
|
||||
- `zebra-state` for transaction queries and client/wallet state storage
|
||||
- `zebra-script` possibly? for constructing transactions
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- implementation of some event a user might trigger
|
||||
- would be used to implement a full wallet
|
||||
- create transactions, monitors shielded wallet state, etc.
|
||||
|
||||
### Notes
|
||||
#### Notes
|
||||
|
||||
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
|
||||
function call to RPC, this means that it will be possible for us to isolate
|
||||
all client code to a subprocess.
|
||||
|
||||
### Exported types
|
||||
#### Exported types
|
||||
|
||||
- [...]
|
||||
|
||||
`zebrad`
|
||||
---------
|
||||
### `zebrad`
|
||||
|
||||
Abscissa-based application which loads configs, all application components,
|
||||
and connects them to each other.
|
||||
|
||||
### Responsible for
|
||||
#### Responsible for
|
||||
|
||||
- actually running the server
|
||||
- connecting functionality in dependencies
|
||||
|
||||
### Internal Dependencies
|
||||
#### Internal Dependencies
|
||||
|
||||
- `zebra-chain`
|
||||
- `zebra-network`
|
||||
|
|
@ -274,8 +332,7 @@ and connects them to each other.
|
|||
- `zebra-client`
|
||||
- `zebra-rpc`
|
||||
|
||||
Unassigned functionality
|
||||
------------------------
|
||||
### Unassigned functionality
|
||||
|
||||
Responsibility for this functionality needs to be assigned to one of
|
||||
the modules above (subject to discussion):
|
||||
|
|
|
|||
|
|
@ -1,13 +1,35 @@
|
|||
# Installing Zebra
|
||||
|
||||
Zebra is still under development, so there is no supported packaging or
|
||||
install mechanism. To run Zebra, check out the git repository:
|
||||
```
|
||||
git clone https://github.com/ZcashFoundation/zebra
|
||||
```
|
||||
and then run
|
||||
```
|
||||
cargo build
|
||||
```
|
||||
`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:
|
||||
|
||||
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.
|
||||
|
|
@ -16,4 +16,25 @@ structure, and documentation for all of the config options can be found
|
|||
- `0`: Application exited successfully
|
||||
- `1`: Application exited unsuccessfully
|
||||
- `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