Skip to content

Commit c0fa486

Browse files
dlachaumedlachaume
authored
Merge pull request #1889 from input-output-hk/dlachaume/1844/document-cardano-stake-distribution
Document Cardano Stake Distribution
2 parents ebfe895 + 23c2f48 commit c0fa486

File tree

13 files changed

+222
-4
lines changed

13 files changed

+222
-4
lines changed

‎Cargo.lock

Lines changed: 14 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ resolver = "2"
44

55
members = [
66
"demo/protocol-demo",
7+
"examples/client-cardano-stake-distribution",
78
"examples/client-cardano-transaction",
89
"examples/client-mithril-stake-distribution",
910
"examples/client-snapshot",

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ It is responsible for handling the different types of data certified by Mithril,
1515

1616
- [**Snapshot**](../../../glossary.md#snapshot): list and get.
1717
- [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get.
18-
- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs
18+
- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs.
19+
- [**Cardano stake distribution**](../../../glossary.md#stake-distribution): list, get and get by epoch.
1920
- [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
2021

2122
:::

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ It is responsible for handling the different types of data certified by Mithril,
1515

1616
- [**Snapshot**](../../../glossary.md#snapshot): list, get, download tarball and record statistics.
1717
- [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get.
18+
- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs.
19+
- [**Cardano stake distribution**](../../../glossary.md#stake-distribution): list, get and get by epoch.
1820
- [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
1921

2022
:::

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@ Commands:
131131
cardano-db Cardano db management (alias: cdb)
132132
mithril-stake-distribution Mithril Stake Distribution management (alias: msd)
133133
cardano-transaction [unstable] Cardano transactions management (alias: ctx)
134+
cardano-stake-distribution [unstable] Cardano stake distribution management (alias: csd)
134135
help Print this message or the help of the given subcommand(s)
135136

136137
Options:
@@ -259,6 +260,12 @@ mithril_client --unstable cardano-transaction snapshot show $CARDANO_TRANSACTION
259260

260261
# 9- Certify that given list of transactions hashes are included in the Cardano transactions set
261262
mithril_client --unstable cardano-transaction certify $TRANSACTION_HASH_1,$TRANSACTION_HASH_2
263+
264+
# 10- List Cardano stake distributions
265+
mithril_client --unstable cardano-stake-distribution list
266+
267+
# 11 - Download and verify the given Cardano stake distribution from its hash or epoch
268+
mithril_client --unstable cardano-stake-distribution download $UNIQUE_IDENTIFIER
262269
```
263270

264271
### Local image
@@ -305,6 +312,14 @@ Here are the subcommands available:
305312
| **snapshot show** | Shows information about a Cardano transactions snapshot |
306313
| **help** | Prints this message or the help for the given subcommand(s) |
307314

315+
### Cardano stake distribution
316+
317+
| Subcommand | Performed action |
318+
| ------------ | ----------------------------------------------------------- |
319+
| **download** | Downloads and verifies Cardano stake distribution |
320+
| **help** | Prints this message or the help for the given subcommand(s) |
321+
| **list** | Lists available Cardano stake distributions |
322+
308323
## Configuration parameters
309324

310325
The configuration parameters can be set in either of the following ways:
@@ -379,3 +394,16 @@ Here is a list of the available parameters:
379394
| --------------------- | ----------------------- | :------------------: | --------------------- | ----------------------------------------------- | ------------- | ------- | :----------------: |
380395
| `transactions_hashes` | `--transactions_hashes` | - | `TRANSACTIONS_HASHES` | Cardano transactions hashes separated by commas | - | - | :heavy_check_mark: |
381396
| `json` | `--json` | - | - | Enable JSON output for progress logs | - | - | - |
397+
398+
`cardano-stake-distribution list` command:
399+
400+
| Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
401+
| --------- | ------------------- | :------------------: | -------------------- | -------------------------------------- | ------------- | ------- | :-------: |
402+
| `json` | `--json` | - | - | Enable JSON output for command results | - | - | - |
403+
404+
`cardano-stake-distribution download` command:
405+
406+
| Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
407+
| ------------------- | --------------------- | :------------------: | -------------------- | -------------------------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
408+
| `unique_identifier` | `--unique-identifier` | - | - | Epoch or hash of the Cardano stake distribution artifact or `latest` for the latest artifact | - | - | :heavy_check_mark: |
409+
| `download_dir` | `--download-dir` | - | - | Directory where the Cardano stake distribution will be downloaded | . | - | - |

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
target/
2+
client-cardano-stake-distribution
3+
.DS_Store

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[package]
2+
name = "client-cardano-stake-distribution"
3+
description = "Mithril client cardano stake distribution example"
4+
version = "0.1.0"
5+
authors = ["dev@iohk.io", "mithril-dev@iohk.io"]
6+
documentation = "https://mithril.network/doc"
7+
edition = "2021"
8+
homepage = "https://mithril.network"
9+
license = "Apache-2.0"
10+
repository = "https://github.com/input-output-hk/mithril/"
11+
12+
[dependencies]
13+
anyhow = "1.0.79"
14+
clap = { version = "4.4.18", features = ["derive", "env"] }
15+
mithril-client = { path = "../../mithril-client", features = ["unstable"] }
16+
slog = "2.7.0"
17+
slog-async = "2.8.0"
18+
slog-term = "2.9.0"
19+
tokio = { version = "1.37.0", features = ["full"] }

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Mithril client library example: Cardano stake distribution
2+
3+
## Description
4+
5+
This example shows how to implement a Mithril client and use the features related to the `Cardano stake distribution` type.
6+
7+
In this example, the client interacts by default with a real aggregator on the network `testing-preview` to:
8+
9+
- list the available Cardano stake distributions
10+
- get a single Cardano stake distribution
11+
- verify a certificate chain
12+
- compute a message for a Cardano stake distribution
13+
- verify that the certificate signs the computed message
14+
15+
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.
16+
17+
## Build and run the example
18+
19+
```bash
20+
# Build from the crate directory
21+
cargo build
22+
23+
# Run from the crate directory
24+
cargo run
25+
26+
# Run with your custom network configuration
27+
AGGREGATOR_ENDPOINT=YOUR_AGGREGATOR_ENDPOINT GENESIS_VERIFICATION_KEY=YOUR_GENESIS_VERIFICATION_KEY cargo run
28+
29+
# Example with 'pre-release-preview' network
30+
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
31+
```
32+
33+
## Links
34+
35+
- **Developer documentation**: https://docs.rs/mithril-client/latest/mithril_client/
36+
- **Crates.io**: https://crates.io/crates/mithril-client

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
//! This example shows how to implement a Mithril client and use its features.
2+
//!
3+
//! In this example, the client interacts by default with a real aggregator (`testing-preview`) to get the data.
4+
5+
use anyhow::anyhow;
6+
use clap::Parser;
7+
use slog::info;
8+
use std::sync::Arc;
9+
10+
use mithril_client::{ClientBuilder, MessageBuilder, MithrilResult};
11+
12+
#[derive(Parser, Debug)]
13+
#[command(version)]
14+
pub struct Args {
15+
/// Genesis verification key.
16+
#[clap(
17+
long,
18+
env = "GENESIS_VERIFICATION_KEY",
19+
default_value = "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d"
20+
)]
21+
genesis_verification_key: String,
22+
23+
/// Aggregator endpoint URL.
24+
#[clap(
25+
long,
26+
env = "AGGREGATOR_ENDPOINT",
27+
default_value = "https://aggregator.testing-preview.api.mithril.network/aggregator"
28+
)]
29+
aggregator_endpoint: String,
30+
}
31+
32+
#[tokio::main]
33+
async fn main() -> MithrilResult<()> {
34+
let args = Args::parse();
35+
let logger = build_logger();
36+
let client =
37+
ClientBuilder::aggregator(&args.aggregator_endpoint, &args.genesis_verification_key)
38+
.with_logger(logger.clone())
39+
.build()?;
40+
41+
let cardano_stake_distributions = client.cardano_stake_distribution().list().await?;
42+
info!(
43+
logger,
44+
"Fetched Cardano stake distributions:\n{cardano_stake_distributions:#?}",
45+
);
46+
47+
let last_epoch = cardano_stake_distributions
48+
.first()
49+
.ok_or(anyhow!(
50+
"No Cardano stake distributions could be listed from aggregator: '{}'",
51+
args.aggregator_endpoint
52+
))?
53+
.epoch;
54+
55+
let cardano_stake_distribution = client
56+
.cardano_stake_distribution()
57+
.get_by_epoch(last_epoch)
58+
.await?
59+
.ok_or(anyhow!(
60+
"A Cardano stake distribution should exist for hash '{last_epoch}'"
61+
))?;
62+
info!(
63+
logger,
64+
"Fetched details of last Cardano stake distribution:\n{cardano_stake_distribution:#?}",
65+
);
66+
67+
info!(
68+
logger,
69+
"Checking certificate chain of the last Cardano stake distribution ...",
70+
);
71+
let certificate = client
72+
.certificate()
73+
.verify_chain(&cardano_stake_distribution.certificate_hash)
74+
.await?;
75+
info!(
76+
logger,
77+
"Certificate chain is valid, checking that the last certificate, hash '{}', \
78+
effectively matches Cardano stake distribution '{}'",
79+
certificate.hash,
80+
cardano_stake_distribution.hash
81+
);
82+
83+
let message = MessageBuilder::new()
84+
.compute_cardano_stake_distribution_message(&certificate, &cardano_stake_distribution)?;
85+
86+
if certificate.match_message(&message) {
87+
info!(
88+
logger,
89+
"Certificate '{}' matches Cardano stake distribution '{}'",
90+
certificate.hash,
91+
cardano_stake_distribution.hash
92+
);
93+
Ok(())
94+
} else {
95+
Err(anyhow::anyhow!(
96+
"Certificate and message did not match:\ncertificate_message: '{}'\n computed_message: '{}'",
97+
certificate.signed_message,
98+
message.compute_hash()
99+
))
100+
}
101+
}
102+
103+
fn build_logger() -> slog::Logger {
104+
use slog::Drain;
105+
106+
let decorator = slog_term::TermDecorator::new().build();
107+
let drain = slog_term::FullFormat::new(decorator).build().fuse();
108+
let drain = slog_async::Async::new(drain).build().fuse();
109+
110+
slog::Logger::root(Arc::new(drain), slog::o!())
111+
}

‎mithril-client-wasm/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
- The different types of available data certified by Mithril are:
88
- Snapshot: list and get.
99
- Mithril stake distribution: list and get.
10-
- Cardano transactions: list & get snapshots, get proofs
10+
- Cardano transactions: list & get snapshots, get proofs.
11+
- Cardano stake distribution: list, get and get by epoch.
1112
- Certificate: list, get, and chain validation.
1213

1314
## Installation

0 commit comments

Comments
 (0)