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:
teor
GitHub
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
|
||||
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=<name> ...
|
||||
```
|
||||
|
||||
### 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
|
||||
|
|
|
|||
|
|
@ -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<SocketAddr>,
|
||||
|
||||
/// 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<SocketAddr>,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,18 +1,90 @@
|
|||
//! 
|
||||
//!
|
||||
//! 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")]
|
||||
|
|
|
|||
Loading…
Reference in New Issue