mithril_client/
lib.rs

1#![warn(missing_docs)]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3// TODO: Remove this allow once migration from deprecated AggregatorClient types is complete
4#![allow(deprecated)]
5
6//! Define all the tooling necessary to manipulate Mithril certified types from a
7//! [Mithril Aggregator](https://mithril.network/rust-doc/mithril_aggregator/index.html).
8//!
9//! It handles the different types that can be queried to a Mithril aggregator:
10//!
11//! - [Cardano Database v1 (aka Snapshot)][snapshot_client]: list, get, download archive and record statistics.
12//! - [Cardano Database v2][cardano_database_client] list, get, download archive and record statistics.
13//! - [Cardano transactions][cardano_transaction_client] list & get snapshot, get proofs.
14//! - [Cardano stake distribution][cardano_stake_distribution_client] list, get and get by epoch.
15//! - [Mithril stake distribution][mithril_stake_distribution_client] list and get.
16//! - [Certificates][certificate_client] list, get, and chain validation.
17//! - [MithrilEraClient][era]: retrieve the current Mithril era.
18//!
19//! The [Client] aggregates the queries of all of those types.
20//!
21//! **NOTE:** Snapshot download and Certificate chain validation can take quite some time even with a fast
22//! computer and network.
23//! For those a feedback mechanism is available, more details on it in the [feedback] submodule.
24//!
25//! # Example
26//!
27//! Below is an example describing the usage of most of the library's functions together:
28//!
29//! **Note:** _Snapshot download and the compute snapshot message functions are available using crate feature_ **fs**.
30//!
31//! ```no_run
32//! # #[cfg(feature = "fs")]
33//! # async fn run() -> mithril_client::MithrilResult<()> {
34//! use mithril_client::{ClientBuilder, MessageBuilder};
35//! use std::path::Path;
36//!
37//! let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
38//!
39//! let snapshots = client.snapshot().list().await?;
40//!
41//! let last_digest = snapshots.first().unwrap().digest.as_ref();
42//! let snapshot = client.snapshot().get(last_digest).await?.unwrap();
43//!
44//! let certificate = client
45//!     .certificate()
46//!     .verify_chain(&snapshot.certificate_hash)
47//!     .await?;
48//!
49//! // Note: the directory must already exist, and the user running the binary must have read/write access to it.
50//! let target_directory = Path::new("/home/user/download/");
51//! client
52//!     .snapshot()
53//!     .download_unpack(&snapshot, &target_directory)
54//!     .await?;
55//!
56//! if let Err(e) = client.snapshot().add_statistics(&snapshot).await {
57//!     println!("Could not increment snapshot download statistics: {:?}", e);
58//! }
59//!
60//! let message = MessageBuilder::new()
61//!     .compute_snapshot_message(&certificate, &target_directory)
62//!     .await?;
63//!
64//! assert!(certificate.match_message(&message));
65//! #    Ok(())
66//! # }
67//! ```
68//!
69//! ## Optional Features
70//!
71//! The following are a list of [Cargo features](https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-features-section) that can be
72//! enabled or disabled:
73//!
74//! - **fs**: Enables file system related functionalities.
75//! - **unstable**: Enables experimental or in-development `mithril-client` features that may change.
76//! - **rug-backend** *(enabled by default)*: Enables usage of `rug` numerical backend in `mithril-stm` (dependency of `mithril-common`).
77//! - **num-integer-backend**: Enables usage of `num-integer` numerical backend in `mithril-stm` (dependency of `mithril-common`).
78//!
79//! To allow fine tuning of the http queries, the following [Reqwest](https://docs.rs/reqwest/latest/reqwest/#optional-features) features are re-exported:
80//! - **native-tls** *(enabled by default)*: Enables TLS functionality provided by `native-tls`.
81//! - **native-tls-vendored**: Enables the `vendored` feature of `native-tls`.
82//! - **native-tls-alpn**: Enables the `alpn` feature of `native-tls`.
83//! - **rustls-tls**: Enables TLS functionality provided by `rustls`.
84//!   Equivalent to `rustls-tls-webpki-roots`.
85//! - **rustls-tls-manual-roots**: Enables TLS functionality provided by `rustls`,
86//!   without setting any root certificates. Roots have to be specified manually.
87//! - **rustls-tls-webpki-roots**: Enables TLS functionality provided by `rustls`,
88//!   while using root certificates from the `webpki-roots` crate.
89//! - **rustls-tls-native-roots**: Enables TLS functionality provided by `rustls`,
90//!   while using root certificates from the `rustls-native-certs` crate.
91//! - **enable-http-compression** *(enabled by default)*: Enables compressed traffic with `reqwest`.
92
93macro_rules! cfg_fs {
94    ($($item:item)*) => {
95        $(
96            #[cfg(feature = "fs")]
97            #[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
98            $item
99        )*
100    }
101}
102
103#[allow(unused_macros)]
104macro_rules! cfg_unstable {
105    ($($item:item)*) => {
106        $(
107            #[cfg(feature = "unstable")]
108            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
109            $item
110        )*
111    }
112}
113
114#[allow(unused_macros)]
115macro_rules! cfg_fs_unstable {
116    ($($item:item)*) => {
117        $(
118            #[cfg(all(feature = "unstable", feature = "fs"))]
119            #[cfg_attr(docsrs, doc(cfg(all(feature = "unstable", feature = "fs"))))]
120            $item
121        )*
122    }
123}
124
125#[deprecated(since = "0.12.33", note = "Will be removed soon")]
126pub mod aggregator_client;
127pub mod cardano_database_client;
128pub mod cardano_stake_distribution_client;
129pub mod cardano_transaction_client;
130pub mod certificate_client;
131mod client;
132pub mod era;
133pub mod feedback;
134mod message;
135pub mod mithril_stake_distribution_client;
136pub mod snapshot_client;
137cfg_fs! {
138    pub mod file_downloader;
139}
140
141mod type_alias;
142mod utils;
143
144pub use client::*;
145pub use message::*;
146pub use type_alias::*;
147
148#[cfg(test)]
149pub(crate) mod test_utils {
150    mithril_common::define_test_logger!();
151}