diff --git a/README.md b/README.md index 25b4d0801..2fb665d94 100644 --- a/README.md +++ b/README.md @@ -25,51 +25,25 @@ 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. + +[Zcash](https://doc.zebra.zfnd.org/zebrad/index.html#about-zcash) +is a cryptocurrency designed to preserve the user's privacy. +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. + 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 new 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. +### Using Zebra -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 and maintain the Zcash network together. - -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 +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 the advantages or benefits of Zebra: - -- Better performance: since it was implemented from scratch in an async, parallelized way, Zebra - 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 memory-safety and correctness 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 for the Zcash network. -- Dev accessibility: supports more developers, which gives new developers - options for contributing to Zcash protocol development. -- Runtime safety: with an independent implementation, the detection of consensus bugs - can happen quicker, reducing the risk of consensus splits. -- 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. +Zebra aims to be +[faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages) +than other Zcash implementations. ## Beta Releases @@ -78,11 +52,7 @@ Every few weeks, we release a new Zebra beta [release](https://github.com/ZcashF Zebra's network stack is interoperable with `zcashd`, and Zebra implements all the features required to reach Zcash network consensus. -The goals of the beta release series are for Zebra to act as a fully validating Zcash node, -for all active consensus rules as of NU5 activation. - Currently, Zebra validates all of the Zcash consensus rules for the NU5 network upgrade. -(As of the second NU5 activation on testnet.) But it may not validate any: - Undocumented rules derived from Bitcoin @@ -106,7 +76,7 @@ for your platform: 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-beta.11 zebrad` +3. Run `cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0-beta.11 zebrad` 4. Run `zebrad start` (see [Running Zebra](https://zebra.zfnd.org/user/run.html) for more information) If you're interested in testing out `zebrad` please feel free, but keep in mind @@ -114,6 +84,15 @@ that there is a lot of key functionality still missing. For more detailed instructions, refer to the [documentation](https://zebra.zfnd.org/user/install.html). +### Optional Features + +For performance reasons, some debugging and monitoring features are disabled in release builds. + +You can [enable these features](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-feature-flags) using: +```sh +cargo install --features= ... +``` + ### System Requirements The recommended requirements for compiling and running `zebrad` are: @@ -206,8 +185,6 @@ So Zebra's state should always be valid, unless your OS or disk hardware is corr ## Known Issues There are a few bugs in Zebra that we're still working on fixing: -- [Old state versions are not deleted #1213](https://github.com/ZcashFoundation/zebra/issues/1213) - - When Zebra changes its state format, it does not delete the old state directory. You can delete old state directories if you need the space. - [No Windows support #3801](https://github.com/ZcashFoundation/zebra/issues/3801) - We used to test with Windows Server 2019, but not anymore; see issue for details @@ -217,7 +194,6 @@ Features: - Wallet functionality Performance and Reliability: -- Reliable syncing on Testnet - Reliable syncing under poor network conditions - Additional batch verification - Performance tuning diff --git a/zebrad/src/config.rs b/zebrad/src/config.rs index 3e2cad9c3..4dfb77599 100644 --- a/zebrad/src/config.rs +++ b/zebrad/src/config.rs @@ -95,11 +95,15 @@ pub struct TracingSection { /// The address used for an ad-hoc RPC endpoint allowing dynamic control of the tracing filter. /// + /// Install Zebra using `cargo install --features=filter-reload` to enable this config. + /// /// If this is set to None, the endpoint is disabled. pub endpoint_addr: Option, /// Controls whether to write a flamegraph of tracing spans. /// + /// Install Zebra using `cargo install --features=flamegraph` to enable this config. + /// /// If this is set to None, flamegraphs are disabled. Otherwise, it specifies /// an output file path, as described below. /// @@ -125,6 +129,8 @@ pub struct TracingSection { /// The use_journald flag sends tracing events to systemd-journald, on Linux /// distributions that use systemd. + /// + /// Install Zebra using `cargo install --features=journald` to enable this config. pub use_journald: bool, } @@ -147,6 +153,8 @@ impl Default for TracingSection { pub struct MetricsSection { /// The address used for the Prometheus metrics endpoint. /// + /// Install Zebra using `cargo install --features=prometheus` to enable this config. + /// /// The endpoint is disabled if this is set to `None`. pub endpoint_addr: Option, } diff --git a/zebrad/src/lib.rs b/zebrad/src/lib.rs index 2ce4ed1e6..c3fab383b 100644 --- a/zebrad/src/lib.rs +++ b/zebrad/src/lib.rs @@ -1,18 +1,90 @@ //! ![Zebra logotype](https://zfnd.org/wp-content/uploads/2022/03/zebra-logotype.png) //! -//! Hello! I am Zebra, an ongoing Rust implementation of a Zcash node. +//! Zebra is a Zcash node written in Rust. //! -//! Zebra is a work in progress. It is developed as a collection of `zebra-*` -//! libraries implementing the different components of a Zcash node (networking, -//! chain structures, consensus rules, etc), and a `zebrad` binary which uses them. -//! -//! Most of our work so far has gone into `zebra-network`, building a new -//! networking stack for Zcash, and `zebra-chain`, building foundational data -//! structures. +//! The `zebrad` binary uses a collection of `zebra-*` crates, +//! which implement the different components of a Zcash node +//! (networking, chain structures, validation, rpc, etc). //! //! [Rendered docs from the `main` branch](https://doc.zebra.zfnd.org). -//! //! [Join us on the Zcash Foundation Engineering Discord](https://discord.gg/na6QZNd). +//! +//! ## About Zcash +//! +//! 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 new 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. +//! +//! ## Alternative Implementations +//! +//! 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 and maintain the Zcash network together. +//! +//! ## Zebra Advantages +//! +//! These are some of the advantages or benefits of Zebra: +//! +//! - Better performance: since it was implemented from scratch in an async, parallelized way, Zebra +//! 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 memory-safety and correctness 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 for the Zcash network. +//! - Dev accessibility: supports more developers, which gives new developers +//! options for contributing to Zcash protocol development. +//! - Runtime safety: with an independent implementation, the detection of consensus bugs +//! can happen quicker, reducing the risk of consensus splits. +//! - 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. +//! +//! ## Zebra Feature Flags +//! +//! The following `zebrad` feature flags are available at compile time: +//! +//! ### Metrics +//! +//! * `prometheus`: export metrics to prometheus. +//! +//! Read the [metrics](https://zebra.zfnd.org/user/metrics.html) section of the book +//! for more details. +//! +//! ### Tracing +//! +//! Sending traces to different subscribers: +//! * `journald`: send tracing spans and events to `systemd-journald`. +//! * `sentry`: send crash and panic events to sentry.io. +//! * `flamegraph`: generate a flamegraph of tracing spans. +//! +//! Changing the traces that are collected: +//! * `filter-reload`: dynamically reload tracing filters at runtime. +//! * `error-debug`: enable extra debugging in release builds. +//! * `tokio-console`: enable tokio's `console-subscriber`. +//! * A set of features that [skip verbose tracing]. +//! The default features ignore `debug` and `trace` logs in release builds. +//! +//! Read the [tracing](https://zebra.zfnd.org/user/tracing.html) section of the book +//! for more details. +//! +//! [ignore verbose tracing]: https://docs.rs/tracing/0.1.35/tracing/level_filters/index.html#compile-time-filters +//! +//! ### Testing +//! +//! * `proptest-impl`: enable randomised test data generation. +//! * `lightwalletd-grpc-tests`: enable Zebra JSON-RPC tests that query `lightwalletd` using gRPC. #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")] #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")]