mithril_client/cardano_database_client/
mod.rs

1//! A client to retrieve Cardano databases data from an Aggregator.
2//!
3//! In order to do so it defines a [CardanoDatabaseClient] which exposes the following features:
4//!  - [get][CardanoDatabaseClient::get]: get a Cardano database data from its hash
5//!  - [list][CardanoDatabaseClient::list]: get the list of available Cardano database
6//!  - [download_unpack][CardanoDatabaseClient::download_unpack]: download and unpack a Cardano database snapshot for a given immutable files range
7//!  - [compute_merkle_proof][CardanoDatabaseClient::compute_merkle_proof]: compute a Merkle proof for a given Cardano database snapshot and a given immutable files range
8//!
9//! # Get a Cardano database
10//!
11//! To get a Cardano database using the [ClientBuilder][crate::client::ClientBuilder].
12//!
13//! ```no_run
14//! # async fn run() -> mithril_client::MithrilResult<()> {
15//! use mithril_client::ClientBuilder;
16//!
17//! let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
18//! let cardano_database = client.cardano_database_v2().get("CARDANO_DATABASE_HASH").await?.unwrap();
19//!
20//! println!(
21//!     "Cardano database hash={}, merkle_root={}, immutable_file_number={:?}",
22//!     cardano_database.hash,
23//!     cardano_database.merkle_root,
24//!     cardano_database.beacon.immutable_file_number
25//! );
26//! #    Ok(())
27//! # }
28//! ```
29//!
30//! # List available Cardano databases
31//!
32//! To list available Cardano databases using the [ClientBuilder][crate::client::ClientBuilder].
33//!
34//! ```no_run
35//! # async fn run() -> mithril_client::MithrilResult<()> {
36//! use mithril_client::ClientBuilder;
37//!
38//! let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
39//! let cardano_databases = client.cardano_database_v2().list().await?;
40//!
41//! for cardano_database in cardano_databases {
42//!     println!("Cardano database hash={}, immutable_file_number={}", cardano_database.hash, cardano_database.beacon.immutable_file_number);
43//! }
44//! #    Ok(())
45//! # }
46//! ```
47//!
48//! # Download a Cardano database snapshot
49//! **Note:** _Available on crate feature_ **fs** _only._
50//!
51//! To download a partial or a full Cardano database folder the [ClientBuilder][crate::client::ClientBuilder].
52//!
53//! ```no_run
54//! # #[cfg(feature = "fs")]
55//! # async fn run() -> mithril_client::MithrilResult<()> {
56//! use mithril_client::{ClientBuilder, cardano_database_client::{ImmutableFileRange, DownloadUnpackOptions}};
57//! use std::path::Path;
58//!
59//! let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
60//! let cardano_database_snapshot = client.cardano_database_v2().get("CARDANO_DATABASE_HASH").await?.unwrap();
61//!
62//! // Note: the directory must already exist, and the user running the binary must have read/write access to it.
63//! let target_directory = Path::new("/home/user/download/");
64//! let immutable_file_range = ImmutableFileRange::Range(3, 6);
65//! let download_unpack_options = DownloadUnpackOptions {
66//!     allow_override: true,
67//!     include_ancillary: true,
68//!     ..DownloadUnpackOptions::default()
69//! };
70//! client
71//!     .cardano_database_v2()
72//!     .download_unpack(
73//!         &cardano_database_snapshot,
74//!         &immutable_file_range,
75//!         &target_directory,
76//!         download_unpack_options,
77//!     )
78//!     .await?;
79//! #
80//! #    Ok(())
81//! # }
82//! ```
83//! # Compute a Merkle proof for a Cardano database snapshot
84//! **Note:** _Available on crate feature_ **fs** _only._
85//!
86//! To compute proof of membership of downloaded immutable files in a Cardano database folder the [ClientBuilder][crate::client::ClientBuilder].
87//!
88//! ```no_run
89//! # #[cfg(feature = "fs")]
90//! # async fn run() -> mithril_client::MithrilResult<()> {
91//! use mithril_client::{ClientBuilder, cardano_database_client::{ImmutableFileRange, DownloadUnpackOptions}};
92//! use std::path::Path;
93//!
94//! let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
95//! let cardano_database_snapshot = client.cardano_database_v2().get("CARDANO_DATABASE_HASH").await?.unwrap();
96//! let certificate = client.certificate().verify_chain(&cardano_database_snapshot.certificate_hash).await?;
97//!
98//! // Note: the directory must already exist, and the user running the binary must have read/write access to it.
99//! let target_directory = Path::new("/home/user/download/");
100//! let immutable_file_range = ImmutableFileRange::Full;
101//! let download_unpack_options = DownloadUnpackOptions {
102//!     allow_override: true,
103//!     include_ancillary: true,
104//!     ..DownloadUnpackOptions::default()
105//! };
106//! client
107//!     .cardano_database_v2()
108//!     .download_unpack(
109//!         &cardano_database_snapshot,
110//!         &immutable_file_range,
111//!         &target_directory,
112//!         download_unpack_options,
113//!     )
114//!     .await?;
115//!
116//! let merkle_proof = client
117//!     .cardano_database_v2()
118//!     .compute_merkle_proof(&certificate, &cardano_database_snapshot, &immutable_file_range, &target_directory)
119//!     .await?;
120//! #
121//! #    Ok(())
122//! # }
123//! ```
124mod api;
125mod fetch;
126mod statistics;
127
128#[cfg(test)]
129pub(crate) use api::test_dependency_injector::CardanoDatabaseClientDependencyInjector;
130pub use api::CardanoDatabaseClient;
131
132cfg_fs! {
133    mod immutable_file_range;
134    mod download_unpack;
135    mod proving;
136
137    pub use download_unpack::DownloadUnpackOptions;
138    pub use immutable_file_range::ImmutableFileRange;
139}
mithril_client/cardano_database_client/mod.rs

mithril_client/cardano_database_client/
mod.rs
