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

mithril_client/cardano_database_client/
mod.rs
