Document Cardano Stake Distribution

Cargo.toml

@@ -4,6 +4,7 @@ resolver = "2"
 
 members = [
   "demo/protocol-demo",
+  "examples/client-cardano-stake-distribution",
   "examples/client-cardano-transaction",
   "examples/client-mithril-stake-distribution",
   "examples/client-snapshot",

docs/website/root/manual/developer-docs/nodes/mithril-client-library-wasm.md

@@ -15,7 +15,8 @@ It is responsible for handling the different types of data certified by Mithril,
 
 - [**Snapshot**](../../../glossary.md#snapshot): list and get.
 - [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get.
-- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs
+- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs.
+- [**Cardano stake distribution**](../../../glossary.md#stake-distribution): list, get and get by epoch.
 - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
 
 :::

docs/website/root/manual/developer-docs/nodes/mithril-client-library.md

@@ -15,6 +15,8 @@ It is responsible for handling the different types of data certified by Mithril,
 
 - [**Snapshot**](../../../glossary.md#snapshot): list, get, download tarball and record statistics.
 - [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get.
+- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs.
+- [**Cardano stake distribution**](../../../glossary.md#stake-distribution): list, get and get by epoch.
 - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
 
 :::

docs/website/root/manual/developer-docs/nodes/mithril-client.md

@@ -131,6 +131,7 @@ Commands:
   cardano-db                  Cardano db management (alias: cdb)
   mithril-stake-distribution  Mithril Stake Distribution management (alias: msd)
   cardano-transaction         [unstable] Cardano transactions management (alias: ctx)
+  cardano-stake-distribution  [unstable] Cardano stake distribution management (alias: csd)
   help                        Print this message or the help of the given subcommand(s)
 
 Options:
@@ -259,6 +260,12 @@ mithril_client --unstable cardano-transaction snapshot show $CARDANO_TRANSACTION
 
 # 9- Certify that given list of transactions hashes are included in the Cardano transactions set
 mithril_client --unstable cardano-transaction certify $TRANSACTION_HASH_1,$TRANSACTION_HASH_2
+
+# 10- List Cardano stake distributions
+mithril_client --unstable cardano-stake-distribution list
+
+# 11 - Download and verify the given Cardano stake distribution from its hash or epoch
+mithril_client --unstable cardano-stake-distribution download $UNIQUE_IDENTIFIER
 ```
 
 ### Local image
@@ -305,6 +312,14 @@ Here are the subcommands available:
 | **snapshot show** | Shows information about a Cardano transactions snapshot                                       |
 | **help**          | Prints this message or the help for the given subcommand(s)                                   |
 
+### Cardano stake distribution
+
+| Subcommand   | Performed action                                            |
+| ------------ | ----------------------------------------------------------- |
+| **download** | Downloads and verifies Cardano stake distribution           |
+| **help**     | Prints this message or the help for the given subcommand(s) |
+| **list**     | Lists available Cardano stake distributions                 |
+
 ## Configuration parameters
 
 The configuration parameters can be set in either of the following ways:
@@ -379,3 +394,16 @@ Here is a list of the available parameters:
 | --------------------- | ----------------------- | :------------------: | --------------------- | ----------------------------------------------- | ------------- | ------- | :----------------: |
 | `transactions_hashes` | `--transactions_hashes` |          -           | `TRANSACTIONS_HASHES` | Cardano transactions hashes separated by commas | -             | -       | :heavy_check_mark: |
 | `json`                | `--json`                |          -           | -                     | Enable JSON output for progress logs            | -             | -       |         -          |
+
+`cardano-stake-distribution list` command:
+
+| Parameter | Command line (long) | Command line (short) | Environment variable | Description                            | Default value | Example | Mandatory |
+| --------- | ------------------- | :------------------: | -------------------- | -------------------------------------- | ------------- | ------- | :-------: |
+| `json`    | `--json`            |          -           | -                    | Enable JSON output for command results | -             | -       |     -     |
+
+`cardano-stake-distribution download` command:
+
+| Parameter           | Command line (long)   | Command line (short) | Environment variable | Description                                                                                  | Default value | Example |     Mandatory      |
+| ------------------- | --------------------- | :------------------: | -------------------- | -------------------------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
+| `unique_identifier` | `--unique-identifier` |          -           | -                    | Epoch or hash of the Cardano stake distribution artifact or `latest` for the latest artifact | -             | -       | :heavy_check_mark: |
+| `download_dir`      | `--download-dir`      |          -           | -                    | Directory where the Cardano stake distribution will be downloaded                            | .             | -       |         -          |

examples/client-cardano-stake-distribution/.gitignore

@@ -0,0 +1,3 @@
+target/
+client-cardano-stake-distribution
+.DS_Store

examples/client-cardano-stake-distribution/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "client-cardano-stake-distribution"
+description = "Mithril client cardano stake distribution example"
+version = "0.1.0"
+authors = ["dev@iohk.io", "mithril-dev@iohk.io"]
+documentation = "https://mithril.network/doc"
+edition = "2021"
+homepage = "https://mithril.network"
+license = "Apache-2.0"
+repository = "https://github.com/input-output-hk/mithril/"
+
+[dependencies]
+anyhow = "1.0.79"
+clap = { version = "4.4.18", features = ["derive", "env"] }
+mithril-client = { path = "../../mithril-client", features = ["unstable"] }
+slog = "2.7.0"
+slog-async = "2.8.0"
+slog-term = "2.9.0"
+tokio = { version = "1.37.0", features = ["full"] }

examples/client-cardano-stake-distribution/README.md

@@ -0,0 +1,36 @@
+# Mithril client library example: Cardano stake distribution
+
+## Description
+
+This example shows how to implement a Mithril client and use the features related to the `Cardano stake distribution` type.
+
+In this example, the client interacts by default with a real aggregator on the network `testing-preview` to:
+
+- list the available Cardano stake distributions
+- get a single Cardano stake distribution
+- verify a certificate chain
+- compute a message for a Cardano stake distribution
+- verify that the certificate signs the computed message
+
+The crates [`slog`](https://docs.rs/slog/latest/slog/) and [`slog_term`](https://docs.rs/slog-term/latest/slog_term/) are used to report the progress to the console.
+
+## Build and run the example
+
+```bash
+# Build from the crate directory
+cargo build
+
+# Run from the crate directory
+cargo run
+
+# Run with your custom network configuration
+AGGREGATOR_ENDPOINT=YOUR_AGGREGATOR_ENDPOINT GENESIS_VERIFICATION_KEY=YOUR_GENESIS_VERIFICATION_KEY cargo run
+
+# Example with 'pre-release-preview' network
+AGGREGATOR_ENDPOINT=https://aggregator.pre-release-preview.api.mithril.network/aggregator GENESIS_VERIFICATION_KEY=$(curl -s https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey) cargo run
+```
+
+## Links
+
+- **Developer documentation**: https://docs.rs/mithril-client/latest/mithril_client/
+- **Crates.io**: https://crates.io/crates/mithril-client

examples/client-cardano-stake-distribution/src/main.rs

@@ -0,0 +1,111 @@
+//! This example shows how to implement a Mithril client and use its features.
+//!
+//! In this example, the client interacts by default with a real aggregator (`testing-preview`) to get the data.
+
+use anyhow::anyhow;
+use clap::Parser;
+use slog::info;
+use std::sync::Arc;
+
+use mithril_client::{ClientBuilder, MessageBuilder, MithrilResult};
+
+#[derive(Parser, Debug)]
+#[command(version)]
+pub struct Args {
+    /// Genesis verification key.
+    #[clap(
+        long,
+        env = "GENESIS_VERIFICATION_KEY",
+        default_value = "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d"
+    )]
+    genesis_verification_key: String,
+
+    /// Aggregator endpoint URL.
+    #[clap(
+        long,
+        env = "AGGREGATOR_ENDPOINT",
+        default_value = "https://aggregator.testing-preview.api.mithril.network/aggregator"
+    )]
+    aggregator_endpoint: String,
+}
+
+#[tokio::main]
+async fn main() -> MithrilResult<()> {
+    let args = Args::parse();
+    let logger = build_logger();
+    let client =
+        ClientBuilder::aggregator(&args.aggregator_endpoint, &args.genesis_verification_key)
+            .with_logger(logger.clone())
+            .build()?;
+
+    let cardano_stake_distributions = client.cardano_stake_distribution().list().await?;
+    info!(
+        logger,
+        "Fetched Cardano stake distributions:\n{cardano_stake_distributions:#?}",
+    );
+
+    let last_epoch = cardano_stake_distributions
+        .first()
+        .ok_or(anyhow!(
+            "No Cardano stake distributions could be listed from aggregator: '{}'",
+            args.aggregator_endpoint
+        ))?
+        .epoch;
+
+    let cardano_stake_distribution = client
+        .cardano_stake_distribution()
+        .get_by_epoch(last_epoch)
+        .await?
+        .ok_or(anyhow!(
+            "A Cardano stake distribution should exist for hash '{last_epoch}'"
+        ))?;
+    info!(
+        logger,
+        "Fetched details of last Cardano stake distribution:\n{cardano_stake_distribution:#?}",
+    );
+
+    info!(
+        logger,
+        "Checking certificate chain of the last Cardano stake distribution ...",
+    );
+    let certificate = client
+        .certificate()
+        .verify_chain(&cardano_stake_distribution.certificate_hash)
+        .await?;
+    info!(
+        logger,
+        "Certificate chain is valid, checking that the last certificate, hash '{}', \
+        effectively matches Cardano stake distribution '{}'",
+        certificate.hash,
+        cardano_stake_distribution.hash
+    );
+
+    let message = MessageBuilder::new()
+        .compute_cardano_stake_distribution_message(&certificate, &cardano_stake_distribution)?;
+
+    if certificate.match_message(&message) {
+        info!(
+            logger,
+            "Certificate '{}' matches Cardano stake distribution '{}'",
+            certificate.hash,
+            cardano_stake_distribution.hash
+        );
+        Ok(())
+    } else {
+        Err(anyhow::anyhow!(
+            "Certificate and message did not match:\ncertificate_message: '{}'\n computed_message: '{}'",
+            certificate.signed_message,
+            message.compute_hash()
+        ))
+    }
+}
+
+fn build_logger() -> slog::Logger {
+    use slog::Drain;
+
+    let decorator = slog_term::TermDecorator::new().build();
+    let drain = slog_term::FullFormat::new(decorator).build().fuse();
+    let drain = slog_async::Async::new(drain).build().fuse();
+
+    slog::Logger::root(Arc::new(drain), slog::o!())
+}

mithril-client-wasm/README.md

@@ -7,7 +7,8 @@
 - The different types of available data certified by Mithril are:
   - Snapshot: list and get.
   - Mithril stake distribution: list and get.
-  - Cardano transactions: list & get snapshots, get proofs
+  - Cardano transactions: list & get snapshots, get proofs.
+  - Cardano stake distribution: list, get and get by epoch.
   - Certificate: list, get, and chain validation.
 
 ## Installation

mithril-client-wasm/npm/README.md

@@ -7,6 +7,8 @@
 - The different types of available data certified by Mithril are:
   - Snapshot: list and get.
   - Mithril stake distribution: list and get.
+  - Cardano transactions: list & get snapshots, get proofs.
+  - Cardano stake distribution: list, get and get by epoch.
   - Certificate: list, get, and chain validation.
 
 ## Example

mithril-client/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-client"
-version = "0.8.12"
+version = "0.8.13"
 description = "Mithril client library"
 authors = { workspace = true }
 edition = { workspace = true }

mithril-client/src/aggregator_client.rs

@@ -22,6 +22,7 @@ use tokio::sync::RwLock;
 use mithril_common::entities::{ClientError, ServerError};
 use mithril_common::MITHRIL_API_VERSION_HEADER;
 
+#[cfg(feature = "unstable")]
 use crate::common::Epoch;
 use crate::{MithrilError, MithrilResult};