Crate mithril_client

Expand description

Define all the tooling necessary to manipulate Mithril certified types from a Mithril Aggregator.

It handles the different types that can be queried to a Mithril aggregator:

Cardano Database v2 list, get, download archive and record statistics.
Cardano transactions list & get snapshot, get proofs.
Cardano stake distribution list, get and get by epoch.
Mithril stake distribution list and get.
Certificates list, get, and chain validation.
MithrilEraClient: retrieve the current Mithril era.

The Client aggregates the queries of all of those types.

NOTE: Snapshot download and Certificate chain validation can take quite some time even with a fast computer and network. For those a feedback mechanism is available, more details on it in the feedback submodule.

§Example

Below is an example describing the usage of most of the library’s functions together:

Note: Snapshot download and the compute snapshot message functions are available using crate feature fs.

use mithril_client::{ClientBuilder, MessageBuilder};
use mithril_client::cardano_database_client::{DownloadUnpackOptions, ImmutableFileRange};
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::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?;

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

let full_restoration = immutable_file_range == ImmutableFileRange::Full;
let include_ancillary = download_unpack_options.include_ancillary;
let number_of_immutable_files_restored =
    immutable_file_range.length(cardano_database_snapshot.beacon.immutable_file_number);
if let Err(error) = client
    .cardano_database_v2()
    .add_statistics(
        full_restoration,
        include_ancillary,
        number_of_immutable_files_restored,
    )
    .await
{
    println!("Could not increment snapshot download statistics: {error:?}");
}

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?;

assert!(certificate.match_message(&message));

§Optional Features

The following is a list of Cargo features that can be enabled or disabled:

fs: Enables file system-related functionalities.
unstable: Enables experimental or in-development mithril-client features that may change.
rug-backend: Enables usage of rug numerical backend in mithril-stm (dependency of mithril-common).
num-integer-backend: Enables usage of num-integer numerical backend in mithril-stm (dependency of mithril-common).

To allow fine-tuning of the http queries, the following Reqwest features are re-exported. No TLS backend is enabled by default: you must enable at least one of the TLS-related features below, otherwise the crate will fail to compile.

native-tls: Enables TLS functionality provided by native-tls.
native-tls-vendored: Enables the vendored feature of native-tls.
native-tls-no-alpn: Enables native-tls without its alpn feature.
native-tls-vendored-no-alpn: Enables the vendored feature of native-tls without its alpn feature.
rustls: Enables TLS functionality provided by rustls.
rustls-no-provider: Enables TLS functionality provided by rustls without setting aws-lc-rs as its TLS provider.

Modules§

cardano_block_clientunstable: A client to retrieve from an aggregator cryptographic proofs of membership for a subset of Cardano blocks.
cardano_database_client: A client to retrieve Cardano databases data from an aggregator.
cardano_stake_distribution_client: A client to retrieve Cardano stake distributions data from an aggregator.
cardano_transaction_client: A client to retrieve from an aggregator cryptographic proofs of membership for a subset of Cardano transactions.
cardano_transaction_v2_clientunstable: A client to retrieve from an aggregator cryptographic proofs of membership for a subset of Cardano transactions.
certificate_client: A client which retrieves and validates certificates from an aggregator.
common: mithril-common re-exports
era: A client to retrieve the current Mithril era.
feedback: Long task feedbacks
file_downloaderfs: File downloader module.
mithril_stake_distribution_client: A client to retrieve Mithril stake distributions data from an aggregator.

Structs§

CardanoBlockunstable: Cardano block message representation
CardanoBlocksProofsunstable: A cryptographic proof for a set of Cardano blocks
CardanoBlocksTransactionsSnapshotunstable: Message structure of a Cardano Blocks and Transactions snapshot
CardanoBlocksTransactionsSnapshotListItemunstable: Message structure of a Cardano Transactions Snapshot list item
CardanoDatabaseSnapshot: A Cardano node database snapshot
CardanoDatabaseSnapshotListItem: List items of Cardano node database snapshot
CardanoStakeDistribution: A Cardano stake distribution. Message structure of a Cardano Stake Distribution
CardanoStakeDistributionListItem: List item of Cardano stake distributions. Message structure of a Cardano Stake Distribution list item
CardanoTransactionunstable: Cardano transaction message representation
CardanoTransactionSnapshot: A snapshot that allow to know up to which point of time Mithril have certified Cardano transactions. Message structure of a Cardano Transactions snapshot
CardanoTransactionSnapshotListItem: List item of a Cardano transaction snapshot. Message structure of a Cardano Transactions Snapshot list item
CardanoTransactionsProofs: A cryptographic proof for a set of Cardano transactions
CardanoTransactionsProofsV2unstable: A cryptographic proof for a set of Cardano transactions
CardanoTransactionsSetProof: A cryptographic proof of a set of Cardano transactions is included in the global Cardano transactions set
Client: Structure that aggregates the available clients for each of the Mithril types of certified data.
ClientBuilder: Builder that can be used to create a Client easily or with custom dependencies.
ClientOptions: Options that can be used to configure the client.
MessageBuilder: A MessageBuilder can be used to compute the message of Mithril artifacts.
MithrilCertificate: A Mithril certificate.
MithrilCertificateListItem: List item of Mithril certificates
MithrilCertificateListItemMetadata: CertificateListItemMessage represents the metadata associated to a CertificateListItemMessage
MithrilCertificateMetadata: CertificateMetadata represents the metadata associated to a Certificate
MithrilSigner: An individual signer of a Mithril certificate
MithrilStakeDistribution: A Mithril stake distribution.
MithrilStakeDistributionListItem: List item of Mithril stake distributions.
MkSetProofunstable: A cryptographic proof that a set of items is included in a Merkle tree
Snapshot: A Mithril snapshot of a Cardano Node database.
SnapshotListItem: List item of Mithril snapshots
VerifiedCardanoBlocksunstable: Blocks successfully verified by CardanoBlocksProofsMessage::verify.
VerifiedCardanoTransactions: Set of transactions verified by CardanoTransactionsProofsMessage::verify.
VerifiedCardanoTransactionsV2unstable: Transactions successfully verified by CardanoTransactionsProofsV2Message::verify.

Enums§

AggregatorDiscoveryType: The type of discovery to use to find the aggregator to connect to.
GenesisVerificationKey: The genesis verification key.
RequiredAggregatorCapabilitiesNon-target_family=wasm: Required capabilities for an aggregator. Required capabilities for an aggregator.
VerifyCardanoTransactionsProofsError: Error encountered or produced by the cardano transaction proof verification.
VerifyProofsV2Errorunstable: Error encountered or produced by the verification of a set of proofs.

Type Aliases§

MithrilError: Mithril error type, an alias of anyhow::Error
MithrilResult: Mithril result type, an alias of anyhow::Result