Module cardano_database_client 

A client to retrieve Cardano databases data from an Aggregator.

In order to do so it defines a CardanoDatabaseClient which exposes the following features:

• get: get a Cardano database data from its hash
• list: get the list of available Cardano database
• download_unpack: download and unpack a Cardano database snapshot for a given immutable files range
• download_and_verify_digests: download and verify the digests of the immutable files in a Cardano database snapshot

Get a Cardano database

To get a Cardano database using the ClientBuilder.

use mithril_client::ClientBuilder;

let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
let cardano_database = client.cardano_database_v2().get("CARDANO_DATABASE_HASH").await?.unwrap();

println!(
    "Cardano database hash={}, merkle_root={}, immutable_file_number={:?}",
    cardano_database.hash,
    cardano_database.merkle_root,
    cardano_database.beacon.immutable_file_number
);

List available Cardano databases

To list available Cardano databases using the ClientBuilder.

use mithril_client::ClientBuilder;

let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
let cardano_databases = client.cardano_database_v2().list().await?;

for cardano_database in cardano_databases {
    println!("Cardano database hash={}, immutable_file_number={}", cardano_database.hash, cardano_database.beacon.immutable_file_number);
}

List available Cardano databases filtered by an epoch

To list available Cardano databases using the ClientBuilder.

use mithril_client::{ClientBuilder, common::Epoch};

let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;

// For a specific epoch
let cardano_databases = client.cardano_database_v2().list_by_epoch(Epoch(8)).await?;
// For the latest epoch known by the Mithril aggregator
let cardano_databases = client.cardano_database_v2().list_for_latest_epoch().await?;
// For the latest epoch known by the Mithril aggregator with an offset
let cardano_databases = client.cardano_database_v2().list_for_latest_epoch_with_offset(4).await?;

for cardano_database in cardano_databases {
    println!("Cardano database hash={}, immutable_file_number={}", cardano_database.hash, cardano_database.beacon.immutable_file_number);
}

Download a Cardano database snapshot

Note: Available on crate feature fs only.

To download a partial or a full Cardano database folder the ClientBuilder.

use mithril_client::{ClientBuilder, cardano_database_client::{ImmutableFileRange, DownloadUnpackOptions}};
use std::path::Path;

let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
let cardano_database_snapshot = client.cardano_database_v2().get("CARDANO_DATABASE_HASH").await?.unwrap();

// Note: the directory must already exist, and the user running the binary must have read/write access to it.
let target_directory = Path::new("/home/user/download/");
let immutable_file_range = ImmutableFileRange::Range(3, 6);
let download_unpack_options = DownloadUnpackOptions {
    allow_override: true,
    include_ancillary: true,
    ..DownloadUnpackOptions::default()
};
client
    .cardano_database_v2()
    .download_unpack(
        &cardano_database_snapshot,
        &immutable_file_range,
        &target_directory,
        download_unpack_options,
    )
    .await?;

Compute a Merkle proof for a Cardano database snapshot

Note: Available on crate feature fs only.

To compute proof of membership of downloaded immutable files in a Cardano database folder the ClientBuilder.

use mithril_client::{ClientBuilder, MessageBuilder, cardano_database_client::{ImmutableFileRange, DownloadUnpackOptions}};
use std::path::Path;

let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
let cardano_database_snapshot = client.cardano_database_v2().get("CARDANO_DATABASE_HASH").await?.unwrap();
let certificate = client.certificate().verify_chain(&cardano_database_snapshot.certificate_hash).await?;

// Note: the directory must already exist, and the user running the binary must have read/write access to it.
let target_directory = Path::new("/home/user/download/");
let immutable_file_range = ImmutableFileRange::Full;
let download_unpack_options = DownloadUnpackOptions {
    allow_override: true,
    include_ancillary: true,
    ..DownloadUnpackOptions::default()
};
client
    .cardano_database_v2()
    .download_unpack(
        &cardano_database_snapshot,
        &immutable_file_range,
        &target_directory,
        download_unpack_options,
    )
    .await?;

let verified_digests = client
    .cardano_database_v2()
    .download_and_verify_digests(
        &certificate,
        &cardano_database_snapshot)
    .await?;

let allow_missing_immutables_files = false;
let merkle_proof = client
   .cardano_database_v2()
   .verify_cardano_database(
       &certificate,
      &cardano_database_snapshot,
      &immutable_file_range,
     allow_missing_immutables_files,
     &target_directory,
     &verified_digests
 ).await?;


let message = MessageBuilder::new().compute_cardano_database_message(
        &certificate,
        &merkle_proof,
    ).await?;

Structs

CardanoDatabaseClient

HTTP client for CardanoDatabase API from the Aggregator

DownloadUnpackOptions

Options for downloading and unpacking a Cardano database

ImmutableVerificationResult

Type containing the lists of immutable files that are missing or tampered.

VerifiedDigests

Represents the verified digests and the Merkle tree built from them.

Enums

CardanoDatabaseVerificationError

Cardano database Verification related errors.

ImmutableFileRange

Immutable file range representation