zebrad/lib.rs
1//! 
2//!
3//! Zebra is a Zcash full node written in Rust. Follow the [introductory
4//! page](https://zebra.zfnd.org/index.html#documentation) in the Zebra Book to learn more.
5//!
6//! ## About Zcash
7//!
8//! Zcash is a cryptocurrency designed to preserve the user's privacy. Like most
9//! cryptocurrencies, it works by a collection of software nodes run by members of
10//! the Zcash community or any other interested parties. The nodes talk to each
11//! other in peer-to-peer fashion in order to maintain the state of the Zcash
12//! blockchain. They also communicate with miners who create new blocks. When a
13//! Zcash user sends Zcash, their wallet broadcasts transactions to these nodes
14//! which will eventually reach miners, and the mined transaction will then go
15//! through Zcash nodes until they reach the recipient's wallet which will report
16//! the received Zcash to the recipient.
17//!
18//! ## Alternative Implementations
19//!
20//! The original Zcash node is named `zcashd` and is developed by the Electric Coin
21//! Company as a fork of the original Bitcoin node. Zebra, on the other hand, is
22//! an independent Zcash node implementation developed from scratch. Since they
23//! implement the same protocol, `zcashd` and Zebra nodes can communicate with each
24//! other and maintain the Zcash network together.
25//!
26//! ## Zebra Advantages
27//!
28//! These are some of the advantages or benefits of Zebra:
29//!
30//! - Better performance: since it was implemented from scratch in an async, parallelized way, Zebra
31//! is currently faster than `zcashd`.
32//! - Better security: since it is developed in a memory-safe language (Rust), Zebra
33//! is less likely to be affected by memory-safety and correctness security bugs that
34//! could compromise the environment where it is run.
35//! - Better governance: with a new node deployment, there will be more developers
36//! who can implement different features for the Zcash network.
37//! - Dev accessibility: supports more developers, which gives new developers
38//! options for contributing to Zcash protocol development.
39//! - Runtime safety: with an independent implementation, the detection of consensus bugs
40//! can happen quicker, reducing the risk of consensus splits.
41//! - Spec safety: with several node implementations, it is much easier to notice
42//! bugs and ambiguity in protocol specification.
43//! - User options: different nodes present different features and tradeoffs for
44//! users to decide on their preferred options.
45//! - Additional contexts: wider target deployments for people to use a consensus
46//! node in more contexts e.g. mobile, wasm, etc.
47//!
48//! ## Configuration
49//!
50//! The command below places the generated `zebrad.toml` config file in the default preferences directory of Linux:
51//!
52//! ```console
53//! zebrad generate -o ~/.config/zebrad.toml
54//! ```
55//!
56//! See [`config::ZebradConfig`] for other OSes default locations or more information about how to configure Zebra.
57//!
58//! ## Zebra Feature Flags
59//!
60//! The following [Cargo
61//! features](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options)
62//! are available at compile time:
63//!
64//! ### Metrics
65//!
66//! * configuring a `tracing.progress_bar`: shows key metrics in the terminal using progress bars,
67//! and automatically configures Zebra to send logs to a file.
68//! (The `progress-bar` feature is activated by default.)
69//! * `prometheus`: export metrics to prometheus.
70//!
71//! Read the [metrics](https://zebra.zfnd.org/user/metrics.html) section of the book
72//! for more details.
73//!
74//! ### Tracing
75//!
76//! Sending traces to different subscribers:
77//! * configuring a `tracing.log_file`: appends traces to a file on disk.
78//! * `journald`: send tracing spans and events to `systemd-journald`.
79//! * `sentry`: send crash and panic events to sentry.io.
80//! * `flamegraph`: generate a flamegraph of tracing spans.
81//!
82//! Changing the traces that are collected:
83//! * `filter-reload`: dynamically reload tracing filters at runtime.
84//! * `error-debug`: enable extra debugging in release builds.
85//! * `tokio-console`: enable tokio's `console-subscriber` (needs [specific compiler flags])
86//! * A set of features that [skip verbose tracing].
87//! The default features ignore `debug` and `trace` logs in release builds.
88//!
89//! Read the [tracing](https://zebra.zfnd.org/user/tracing.html) section of the book
90//! for more details.
91//!
92//! [skip verbose tracing]: https://docs.rs/tracing/0.1.35/tracing/level_filters/index.html#compile-time-filters
93//! [specific compiler flags]: https://zebra.zfnd.org/dev/tokio-console.html#setup
94//!
95//! ### Testing
96//!
97//! * `proptest-impl`: enable randomised test data generation.
98//! * `lightwalletd-grpc-tests`: enable Zebra JSON-RPC tests that query `lightwalletd` using gRPC.
99//!
100//! ### Experimental
101//!
102//! * `elasticsearch`: save block data into elasticsearch database. Read the [elasticsearch](https://zebra.zfnd.org/user/elasticsearch.html)
103//! section of the book for more details.
104//! * `shielded-scan`: enable experimental support for scanning shielded transactions. Read the [shielded-scan](https://zebra.zfnd.org/user/shielded-scan.html)
105//! section of the book for more details.
106//! * `internal-miner`: enable experimental support for mining inside Zebra, without an external
107//! mining pool. This feature is only supported on testnet. Use a GPU or ASIC on mainnet for
108//! efficient mining.
109//!
110//! ## Zebra crates
111//!
112//! [The Zebra monorepo](https://github.com/ZcashFoundation/zebra) is a collection of the following
113//! crates:
114//!
115//! - [tower-batch-control](https://docs.rs/tower-batch-control/latest/tower_batch_control/)
116//! - [tower-fallback](https://docs.rs/tower-fallback/latest/tower_fallback/)
117//! - [zebra-chain](https://docs.rs/zebra-chain/latest/zebra_chain/)
118//! - [zebra-consensus](https://docs.rs/zebra-consensus/latest/zebra_consensus/)
119//! - [zebra-network](https://docs.rs/zebra-network/latest/zebra_network/)
120//! - [zebra-node-services](https://docs.rs/zebra-node-services/latest/zebra_node_services/)
121//! - [zebra-rpc](https://docs.rs/zebra-rpc/latest/zebra_rpc/)
122//! - [zebra-scan](https://docs.rs/zebra-scan/latest/zebra_scan/)
123//! - [zebra-script](https://docs.rs/zebra-script/latest/zebra_script/)
124//! - [zebra-state](https://docs.rs/zebra-state/latest/zebra_state/)
125//! - [zebra-test](https://docs.rs/zebra-test/latest/zebra_test/)
126//! - [zebra-utils](https://docs.rs/zebra-utils/latest/zebra_utils/)
127//! - [zebrad](https://docs.rs/zebrad/latest/zebrad/)
128//!
129//! The links in the list above point to the documentation of the public APIs of the crates. For
130//! the documentation of the internal APIs, follow <https://doc-internal.zebra.zfnd.org> that lists
131//! all Zebra crates as well in the left sidebar.
132
133#![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")]
134#![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")]
135#![doc(html_root_url = "https://docs.rs/zebrad")]
136// Tracing causes false positives on this lint:
137// https://github.com/tokio-rs/tracing/issues/553
138#![allow(clippy::cognitive_complexity)]
139
140#[macro_use]
141extern crate tracing;
142
143/// Error type alias to make working with tower traits easier.
144///
145/// Note: the 'static lifetime bound means that the *type* cannot have any
146/// non-'static lifetimes, (e.g., when a type contains a borrow and is
147/// parameterized by 'a), *not* that the object itself has 'static lifetime.
148pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
149
150pub mod application;
151pub mod commands;
152pub mod components;
153pub mod config;
154pub mod prelude;
155
156#[cfg(feature = "sentry")]
157pub mod sentry;