diff --git a/README.md b/README.md index 51cdbed77..6067233ce 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,72 @@ [![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) +## 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. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 8a7f8b203..c8222268a 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -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) diff --git a/book/src/dev/overview.md b/book/src/dev/overview.md index 042b9fd65..8ad854033 100644 --- a/book/src/dev/overview.md +++ b/book/src/dev/overview.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): diff --git a/book/src/user/install.md b/book/src/user/install.md index 5ee1399fa..532f34fe8 100644 --- a/book/src/user/install.md +++ b/book/src/user/install.md @@ -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. \ No newline at end of file +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`. diff --git a/book/src/user/requirements.md b/book/src/user/requirements.md new file mode 100644 index 000000000..c0e8664c4 --- /dev/null +++ b/book/src/user/requirements.md @@ -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. diff --git a/book/src/user/run.md b/book/src/user/run.md index 32a6d9ef0..520e78fad 100644 --- a/book/src/user/run.md +++ b/book/src/user/run.md @@ -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. \ No newline at end of file +- `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. +