Merge pull request #1332 from input-output-hk/ensemble/1311/redesign_mithril_client_api

Redesign mithril client api

Author: Alenar

.github/workflows/ci.yml

@@ -36,14 +36,17 @@ jobs:
       # We separate the build in 2 steps as we want to avoid side effects with Rust feature unification.
       - name: Cargo build - Tooling
         shell: bash
-        run: cargo build --features portable --release --workspace --exclude mithril-aggregator --exclude mithril-client-cli --exclude mithril-signer --exclude mithril-stm
+        run: |
+          cargo build --features portable --release --workspace \
+              --exclude mithril-aggregator --exclude mithril-client-cli \
+              --exclude mithril-client --exclude mithril-signer \
+              --exclude mithril-stm
 
       - name: Build Mithril workspace & publish artifacts
         uses: ./.github/workflows/actions/build-upload-mithril-artifact
         with:
-          binaries-build-args: --bin mithril-aggregator --bin mithril-signer --bin mithril-client --features build-binary
-          libraries-build-args: --package mithril-stm --package mithril-client-cli
-          common-build-args: --features bundle_openssl
+          binaries-build-args: --bin mithril-aggregator --bin mithril-signer --bin mithril-client --features bundle_openssl
+          libraries-build-args: --package mithril-stm --package mithril-client
 
       - name: Build Debian packages
         shell: bash
@@ -82,15 +85,13 @@ jobs:
         include:
         # Only build client on windows & mac
         - os: macos-12
-          binaries-build-args: --bin mithril-client --features build-binary
-          libraries-build-args: --package mithril-stm --package mithril-client-cli
-          common-build-args: --features bundle_openssl
+          binaries-build-args: --bin mithril-client --features bundle_openssl
+          libraries-build-args: --package mithril-stm --package mithril-client
         - os: windows-latest
           # Use `--bins --package <package>` instead of `--bin <package>`, otherwise the 'windows' compatibility
           # hack in mithril common cargo.toml doesn't apply (we have no idea why).
-          binaries-build-args: --bins --package mithril-client-cli --features build-binary
-          libraries-build-args: --package mithril-stm --package mithril-client-cli --no-default-features --features num-integer-backend
-          common-build-args: --features bundle_openssl
+          binaries-build-args: --bins --package mithril-client-cli --features bundle_openssl
+          libraries-build-args: --package mithril-stm --package mithril-client --no-default-features --features num-integer-backend
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -120,9 +121,9 @@ jobs:
             test-args: --features portable --workspace
           # Only test client on windows & mac (since its the only binaries supported for those os for now)
           - os: macos-12
-            test-args: -p mithril-client-cli
+            test-args: --package mithril-client --package mithril-client-cli
           - os: windows-latest
-            test-args: -p mithril-client-cli
+            test-args: --package mithril-client --package mithril-client-cli
 
     runs-on: ${{ matrix.os }}
 
@@ -144,7 +145,10 @@ jobs:
 
       - name: Run doc tests
         run: cargo test --doc ${{ matrix.test-args }}
-          
+
+      - name: Ensure examples build
+        run: cargo build --examples ${{ matrix.test-args }}
+
       - name: Rename junit file to include runner info
         shell: bash
         if: success() || failure()

.github/workflows/docs.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Generate cargo doc
         run: |
           cargo doc --no-deps -p mithril-stm -p mithril-common -p mithril-aggregator \
-                    -p mithril-signer -p mithril-client-cli --message-format=json \
+                    -p mithril-signer -p mithril-client -p mithril-client-cli --message-format=json \
                     | clippy-sarif | tee rust-cargo-doc-results.sarif | sarif-fmt
           
           # Update tool sarif metadata from "clippy" to "cargo-doc" (since it's set this way by clippy-sarif)

Cargo.lock

@@ -5,6 +5,7 @@ resolver = "2"
 members = [
   "demo/protocol-demo",
   "mithril-aggregator",
+  "mithril-client",
   "mithril-client-cli",
   "mithril-common",
   "mithril-signer",

Cargo.toml

@@ -1,4 +1,4 @@
-COMPONENTS = mithril-common mithril-stm mithril-aggregator mithril-client-cli mithril-signer demo/protocol-demo mithril-test-lab/mithril-end-to-end
+COMPONENTS = mithril-common mithril-stm mithril-aggregator mithril-client mithril-client-cli mithril-signer demo/protocol-demo mithril-test-lab/mithril-end-to-end
 GOALS := $(or $(MAKECMDGOALS),all)
 
 .PHONY: $(GOALS) $(COMPONENTS)

Makefile

@@ -207,6 +207,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
+        additionalLanguages: ['rust', 'toml'],
       },
       mermaid: {
         theme: { light: 'base', dark: 'base' },

docs/website/docusaurus.config.js

@@ -31,7 +31,7 @@ Mithril aggregator is responsible for collecting individual signatures from the
 
 | Node | Source repository | Rust documentation | Docker packages | REST API
 |:-:|:-----------------:|:------------------:|:---------------:|
-**Mithril aggregator** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-aggregator) | [:arrow_upper_right:](https://mithril.network/mithril-aggregator/doc/mithril_aggregator/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-aggregator) | [:arrow_upper_right:](/aggregator-api)
+**Mithril aggregator** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-aggregator) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_aggregator/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-aggregator) | [:arrow_upper_right:](/aggregator-api)
 
 ## Pre-requisites
 

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

@@ -9,7 +9,12 @@ import CompiledBinaries from '../../../compiled-binaries.md'
 
 :::info
 
-Mithril Client Library can be used by Rust developers to use the Mithril Network in their applications.
+Mithril client library can be used by Rust developers to use the Mithril network in their applications.
+
+It is responsible for handling the different types of data certified by Mithril, and available through a Mithril aggregator:
+- [**Snapshot**](../../../glossary.md#snapshot): list, get and download tarball.
+- [**Mithril stake distribution**](../../../glossary#stake-distribution): list and get.
+- [**Certificate**](../../../glossary#certificate): list, get, and chain validation.
 
 :::
 
@@ -31,15 +36,9 @@ Mithril Client Library can be used by Rust developers to use the Mithril Network
 
 ## Resources
 
-| Node | Source repository | Rust documentation | Docker packages |
-|:-:|:-----------------:|:------------------:|:---------------:|
-**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
-
-## Resources
-
-| Node | Source repository | Rust documentation | Docker packages |
-|:-:|:-----------------:|:------------------:|:---------------:|
-**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
+| Node | Source repository | Rust documentation |
+|:-:|:-----------------:|:------------------:|
+**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) |
 
 ## Pre-requisites
 
@@ -49,56 +48,112 @@ Mithril Client Library can be used by Rust developers to use the Mithril Network
 
 ## Installation
 
-In your project crate, use `cargo` to add [mithril-client](https://crates.io/crates/mithril-client) as a dependency:
+:::caution
+
+Mithril client library has not yet been published on [crates.io](https://crates.io/), so you won't be able to follow the procedure below. The crate will be published soon.
+
+For now, you can experiment it by adding the dependency manually in the Cargo.toml of your project:
+
+```toml title="/Cargo.toml"
+mithril-client = { git = "https://github.com/input-output-hk/mithril.git" }
+```
+
+:::
+
+In your project, use `cargo` to add [mithril-client](https://crates.io/crates/mithril-client) crate as a dependency:
 
 ```bash
 cargo add mithril-client
 ```
 
-It will add the latest version of the Mithril client library.
+:::info
 
-Mithril client is an asynchronous library. It has been tested with the crate [tokio](https://crates.io/crates/tokio), In the Cargo.toml of your project, add the following dependency:
+Mithril client is an asynchronous library, you will need a runtime to execute your futures. We recommend to use the crate [tokio](https://crates.io/crates/tokio), as the library has been tested with it.
 
-```toml
-tokio = { version = "1.32.0", features = ["full"] }
-``````
+:::
 
-## Using Mithril Client Library
+## Using Mithril client library
 
-If the goal is just to use the existing certificates, it is easier to use the `Client` structure:
+Below is a basic example of how to use most of the functions exposed by the Mithril client library:
 
-```rust
-use mithril_client::client::Client;
-use mithril_client::common::*;
+```rust title="/src/main.rs"
+use mithril_client::{ClientBuilder, MessageBuilder};
+use std::path::Path;
 
 #[tokio::main]
-async fn main() -> StdResult<()> {
-    let client = Client::new("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").await?;
-    let response = client.list_mithril_stake_distributions().await?;
-
-    for mithril_stake_distribution in response {
-        println!("Stake distribution hash = '{}'.", mithril_stake_distribution.hash);
-    }
-
+async fn main() -> mithril_client::MithrilResult<()> {
+    let client = ClientBuilder::aggregator("YOUR_AGGREGATOR_ENDPOINT", "YOUR_GENESIS_VERIFICATION_KEY").build()?;
+    
+    let snapshots = client.snapshot().list().await?;
+    
+    let last_digest = snapshots.first().unwrap().digest.as_ref();
+    let snapshot = client.snapshot().get(last_digest).await?.unwrap();
+    
+    let certificate = client
+        .certificate()
+        .verify_chain(&snapshot.certificate_hash)
+        .await?;
+    
+    // Note: the directory must already exist, and the user running this code must have read/write access to it.
+    let target_directory = Path::new("YOUR_TARGET_DIRECTORY");
+    client
+        .snapshot()
+        .download_unpack(&snapshot, target_directory)
+        .await?;
+    
+    let message = MessageBuilder::new()
+        .compute_snapshot_message(&certificate, target_directory)
+        .await?;
+    assert!(certificate.match_message(&message));
+    
     Ok(())
 }
 ```
 
-Here is an example of the code for the release-preprod network:
+:::info
 
-```rust
-use mithril_client::client::Client;
-use mithril_client::common::*;
+Snapshot download and certificate chain validation can take quite some time even with a fast computer and network. We have implemented a feedback mechanism for them, more details on it are available in the [feedback sub-module](https://mithril.network/rust-doc/mithril_client/feedback/index.html).
 
-#[tokio::main]
-async fn main() -> StdResult<()> {
-    let client = Client::new("https://aggregator.release-mainnet.api.mithril.network/aggregator", "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d").await?;
-    let response = client.list_mithril_stake_distributions().await?;
+An example of implementation with the crate [indicatif](https://crates.io/crates/indicatif) is available in the [Mithril repository](https://github.com/input-output-hk/mithril/tree/main/mithril-client/examples/snapshot_list_get_show_download_verify.rs). To run it, execute the following command:
+
+```bash
+cargo run --example snapshot_list_get_show_download_verify 
+```
+
+:::
+
+Here is a working example of the code using the configuration parameters of the `release-preprod` network:
 
-    for mithril_stake_distribution in response {
-        println!("Stake distribution hash = '{}'.", mithril_stake_distribution.hash);
-    }
+```rust title="/src/main.rs"
+use mithril_client::{ClientBuilder, MessageBuilder};
+use std::path::Path;
 
+#[tokio::main]
+async fn main() -> mithril_client::MithrilResult<()> {
+    let client = ClientBuilder::aggregator("https://aggregator.release-preprod.api.mithril.network/aggregator", "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d").build()?;
+    
+    let snapshots = client.snapshot().list().await?;
+    
+    let last_digest = snapshots.first().unwrap().digest.as_ref();
+    let snapshot = client.snapshot().get(last_digest).await?.unwrap();
+    
+    let certificate = client
+        .certificate()
+        .verify_chain(&snapshot.certificate_hash)
+        .await?;
+    
+    // Note: the directory must already exist, and the user running this code must have read/write access to it.
+    let target_directory = Path::new(".");
+    client
+        .snapshot()
+        .download_unpack(&snapshot, target_directory)
+        .await?;
+    
+    let message = MessageBuilder::new()
+        .compute_snapshot_message(&certificate, target_directory)
+        .await?;
+    assert!(certificate.match_message(&message));
+    
     Ok(())
 }
 ```

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

@@ -34,7 +34,7 @@ Mithril client is responsible for restoring the **Cardano** blockchain on an emp
 
 | Node | Source repository | Rust documentation | Docker packages |
 |:-:|:-----------------:|:------------------:|:---------------:|
-**Mithril client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
+**Mithril client CLI** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client-cli) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_client_cli/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
 
 ## Pre-requisites
 
@@ -113,15 +113,15 @@ make build
 Display the help menu:
 
 ```bash
-./mithril-client --help
+./mithril-client-cli --help
 ```
 
 You should see:
 
 ```bash
 This program shows, downloads, and verifies certified blockchain artifacts.
 
-Usage: mithril-client [OPTIONS] <COMMAND>
+Usage: mithril-client-cli [OPTIONS] <COMMAND>
 
 Commands:
   snapshot                    Snapshot commands
@@ -148,13 +148,13 @@ Options:
 Run in release mode with the default configuration:
 
 ```bash
-./mithril-client
+./mithril-client-cli
 ```
 
 Run in release mode with a specific mode:
 
 ```bash
-./mithril-client --run-mode preview
+./mithril-client-cli --run-mode preview
 ```
 
 Run in release mode with a custom configuration using environment variables:
@@ -168,7 +168,7 @@ GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) NETWO
 To display results in JSON format for the `list` and `show` commands, simply use the `--json` (or `-j`) option:
 
 ```bash
-./mithril-client snapshot list --json
+./mithril-client-cli snapshot list --json
 ```
 
 :::