doc(features): Document optional `zebrad` features and clean up README (#4680)
* Document configs that need compile-time features * Document features in zebrad/src/lib.rs * Link to the feature list from the README * Remove some outdated README info * Move some detailed README info to the `zebrad` crate docs
This commit is contained in:
parent
2103f36dea
commit
ad524f2589
68
README.md
68
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
|
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
|
keeping Zcash working by validating and broadcasting transactions, and maintaining
|
||||||
the Zcash blockchain state in a distributed manner.
|
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
|
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
|
### Using Zebra
|
||||||
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.
|
|
||||||
|
|
||||||
The original Zcash node is named `zcashd` and is developed by the Electric Coin
|
You would want to run Zebra if you want to contribute to the
|
||||||
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
|
|
||||||
Zcash network: the more nodes are run, the more reliable the network will be
|
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.
|
in terms of speed and resistance to denial of service attacks, for example.
|
||||||
|
|
||||||
These are some of the advantages or benefits of Zebra:
|
Zebra aims to be
|
||||||
|
[faster, more secure, and more easily extensible](https://doc.zebra.zfnd.org/zebrad/index.html#zebra-advantages)
|
||||||
- Better performance: since it was implemented from scratch in an async, parallelized way, Zebra
|
than other Zcash implementations.
|
||||||
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.
|
|
||||||
|
|
||||||
## Beta Releases
|
## 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`,
|
Zebra's network stack is interoperable with `zcashd`,
|
||||||
and Zebra implements all the features required to reach Zcash network consensus.
|
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.
|
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:
|
But it may not validate any:
|
||||||
- Undocumented rules derived from Bitcoin
|
- Undocumented rules derived from Bitcoin
|
||||||
|
@ -106,7 +76,7 @@ for your platform:
|
||||||
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-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)
|
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
|
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).
|
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=<name> ...
|
||||||
|
```
|
||||||
|
|
||||||
### System Requirements
|
### System Requirements
|
||||||
|
|
||||||
The recommended requirements for compiling and running `zebrad` are:
|
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
|
## 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:
|
||||||
- [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)
|
- [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
|
- We used to test with Windows Server 2019, but not anymore; see issue for details
|
||||||
|
|
||||||
|
@ -217,7 +194,6 @@ Features:
|
||||||
- Wallet functionality
|
- Wallet functionality
|
||||||
|
|
||||||
Performance and Reliability:
|
Performance and Reliability:
|
||||||
- Reliable syncing on Testnet
|
|
||||||
- Reliable syncing under poor network conditions
|
- Reliable syncing under poor network conditions
|
||||||
- Additional batch verification
|
- Additional batch verification
|
||||||
- Performance tuning
|
- Performance tuning
|
||||||
|
|
|
@ -95,11 +95,15 @@ pub struct TracingSection {
|
||||||
|
|
||||||
/// The address used for an ad-hoc RPC endpoint allowing dynamic control of the tracing filter.
|
/// 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.
|
/// If this is set to None, the endpoint is disabled.
|
||||||
pub endpoint_addr: Option<SocketAddr>,
|
pub endpoint_addr: Option<SocketAddr>,
|
||||||
|
|
||||||
/// Controls whether to write a flamegraph of tracing spans.
|
/// 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
|
/// If this is set to None, flamegraphs are disabled. Otherwise, it specifies
|
||||||
/// an output file path, as described below.
|
/// 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
|
/// The use_journald flag sends tracing events to systemd-journald, on Linux
|
||||||
/// distributions that use systemd.
|
/// distributions that use systemd.
|
||||||
|
///
|
||||||
|
/// Install Zebra using `cargo install --features=journald` to enable this config.
|
||||||
pub use_journald: bool,
|
pub use_journald: bool,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -147,6 +153,8 @@ impl Default for TracingSection {
|
||||||
pub struct MetricsSection {
|
pub struct MetricsSection {
|
||||||
/// The address used for the Prometheus metrics endpoint.
|
/// 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`.
|
/// The endpoint is disabled if this is set to `None`.
|
||||||
pub endpoint_addr: Option<SocketAddr>,
|
pub endpoint_addr: Option<SocketAddr>,
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,18 +1,90 @@
|
||||||
//! ![Zebra logotype](https://zfnd.org/wp-content/uploads/2022/03/zebra-logotype.png)
|
//! ![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-*`
|
//! The `zebrad` binary uses a collection of `zebra-*` crates,
|
||||||
//! libraries implementing the different components of a Zcash node (networking,
|
//! which implement the different components of a Zcash node
|
||||||
//! chain structures, consensus rules, etc), and a `zebrad` binary which uses them.
|
//! (networking, chain structures, validation, rpc, etc).
|
||||||
//!
|
|
||||||
//! 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.
|
|
||||||
//!
|
//!
|
||||||
//! [Rendered docs from the `main` branch](https://doc.zebra.zfnd.org).
|
//! [Rendered docs from the `main` branch](https://doc.zebra.zfnd.org).
|
||||||
//!
|
|
||||||
//! [Join us on the Zcash Foundation Engineering Discord](https://discord.gg/na6QZNd).
|
//! [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_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")]
|
#![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")]
|
||||||
|
|
Loading…
Reference in New Issue