Merge pull request #1349 from input-output-hk/ensemble/1311-mithril-client-common-crates-publish

Mithril client and common crates preparation for publication

Author: jpraynaud

.github/workflows/ci.yml

@@ -353,8 +353,9 @@ jobs:
   publish-crate-test:
     strategy:
       fail-fast: false
+      max-parallel: 1
       matrix:
-        package: [ mithril-stm ]
+        package: [ mithril-stm, mithril-common, mithril-client ]
 
     runs-on: ubuntu-22.04
     needs:

.github/workflows/pre-release.yml

@@ -227,8 +227,9 @@ jobs:
   publish-crate-test:
     strategy:
       fail-fast: false
+      max-parallel: 1
       matrix:
-        package: [ mithril-stm ]
+        package: [ mithril-stm, mithril-common, mithril-client ]
 
     runs-on: ubuntu-22.04
     steps:

.github/workflows/release.yml

@@ -166,9 +166,10 @@ jobs:
 
   publish-crate:
     strategy:
-      fail-fast: false
+      fail-fast: true
+      max-parallel: 1
       matrix:
-        package: [ mithril-stm ]
+        package: [ mithril-stm, mithril-common, mithril-client ]
         include:
         - package: mithril-stm
           api_token_secret_name: CRATES_IO_API_TOKEN

CONTRIBUTING.md

@@ -3,7 +3,7 @@
 Thanks for considering contributing and help us on creating the Mithril protocol!
 
 The best way to contribute right now is to try things out and provide feedback,
-but we also accept contributions to the documentation and the obviously to the
+but we also accept contributions to the documentation and obviously to the
 code itself.
 
 This document contains guidelines to help you get started and how to make sure

Cargo.lock

@@ -56,7 +56,9 @@ This repository consists of the following parts:
 
 * [**Mithril aggregator**](./mithril-aggregator): the node of the **Mithril network** responsible for collecting individual signatures from the **Mithril signers** and aggregating them into a multi-signature. The **Mithril aggregator** uses this ability to provide certified snapshots of the **Cardano** blockchain.
 
-* [**Mithril client**](./mithril-client): the node of the **Mithril network** responsible for retrieving the certified artifacts produced by the **Mithril network**, eg the **Cardano** chain certified snapshots used to securely restore a **Cardano node**.
+* [**Mithril client**](./mithril-client): this is the **client** library that can be used by developers to interact with Mithril certified data in their applications.
+
+* [**Mithril client CLI**](./mithril-client-cli): the CLI used for retrieving the certified artifacts produced by the **Mithril network**, eg the **Cardano** chain certified snapshots used to securely restore a **Cardano node**.
 
 * [**Mithril common**](./mithril-common): this is the **common** library that is used by the **Mithril network** nodes.
 

README.md

@@ -29,7 +29,8 @@ To learn more about the **Mithril protocol**, please refer to the [about Mithril
 | **Mithril common** | The **common** library used by **Mithril network** nodes. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-common) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_common/index.html) | -
 | **Mithril STM** | The **core** library that implements the cryptographic engine for the **Mithril** protocol. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-stm) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_stm/index.html) | -
 | **Mithril aggregator** | The node within the **Mithril network** responsible for collecting individual signatures from the **Mithril signers** and aggregating them into a multi-signature. This capability enables the **Mithril aggregator** to provide certified snapshots of the **Cardano** blockchain. | [: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:](/aggregator-api)
-| **Mithril client** | The node within the **Mithril network** responsible for restoring the **Cardano** blockchain on an empty node from a certified snapshot. | [: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/index.html) | -
+| **Mithril client CLI** | The node within the **Mithril network** responsible for restoring the **Cardano** blockchain on an empty node from a certified snapshot. | [: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) | -
+| **Mithril client** | The library that can be used by developers to interact with Mithril certified data in their applications. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_client/index.html) | -
 | **Mithril signer** | The node responsible for producing individual signatures that are collected and aggregated by the **Mithril aggregator**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-signer) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_signer/index.html) | -
 | **Mithril devnet** | The private **Mithril/Cardano network** used to create a **Mithril network** on top of a private **Cardano network**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/blob/main/mithril-test-lab/mithril-devnet) | - | -
 | **Mithril end to end** | The tool used to run test scenarios against a **Mithril devnet**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/blob/main/mithril-explorer) | - | -

docs/website/root/manual/developer-docs/references.md

@@ -1,13 +1,14 @@
 [package]
 name = "mithril-client"
-version = "0.5.4"
-description = "Mithril Client library"
+version = "0.5.5"
+description = "Mithril client library"
 authors = { workspace = true }
 edition = { workspace = true }
-documentation = { workspace = true }
 homepage = { workspace = true }
 license = { workspace = true }
 repository = { workspace = true }
+categories = ["cryptography"]
+include = ["**/*.rs", "Cargo.toml", "README.md", ".gitignore"]
 
 [lib]
 crate-type = ["lib", "cdylib", "staticlib"]
@@ -20,7 +21,7 @@ chrono = { version = "0.4.31", features = ["serde"] }
 flate2 = "1.0.27"
 flume = "0.11.0"
 futures = "0.3.28"
-mithril-common = { path = "../mithril-common" }
+mithril-common = { path = "../mithril-common", version = "0.2.133" }
 reqwest = { version = "0.11.22", features = ["json", "stream"] }
 semver = "1.0.19"
 serde = { version = "1.0.188", features = ["derive"] }
@@ -35,7 +36,9 @@ zstd = "0.13.0"
 [dev-dependencies]
 httpmock = "0.6.8"
 indicatif = { version = "0.17.7", features = ["tokio"] }
-mithril-common = { path = "../mithril-common", features = ["test_http_server"] }
+mithril-common = { path = "../mithril-common", version = "0.2.133", features = [
+    "test_http_server",
+] }
 mockall = "0.11.4"
 slog-async = "2.8.0"
 slog-scope = "4.4.0"

mithril-client/Cargo.toml

@@ -1,6 +1,63 @@
-# Mithril Client
+# Mithril-client ![crates.io](https://img.shields.io/crates/v/mithril-client.svg) [![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](LICENSE-APACHE) [![Discord](https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square)](https://discord.gg/5kaErDKDRq)
 
-## Documentation
-:rocket: The documentation is available at [`Mithril client library`](https://mithril.network/doc/next/manual/developer-docs/nodes/mithril-client-library) with Mithril
+**This is a work in progress** 🛠 
 
-:bulb: A guide on how to [`Bootstrap a Cardano Node`](https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node) with Mithril
+* `mithril-client` defines all the tooling necessary to manipulate Mithril certified types available from a Mithril aggregator.
+
+* The different types of available data certified by Mithril are:
+    * Snapshot: list, get and download tarball.
+    * Mithril stake distribution: list and get.
+    * Certificate: list, get, and chain validation.
+
+## Example
+
+Below is a basic example of how to use most of the functions exposed by the Mithril client library:
+
+```rust
+use mithril_client::{ClientBuilder, MessageBuilder};
+use std::path::Path;
+
+#[tokio::main]
+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(())
+}
+```
+
+## Getting Help
+First, check our [Developer documentation](https://mithril.network/doc/manual/developer-docs/nodes/mithril-client-library). 
+
+If you need more information, feel free to join IOG's Technical Community [discord server](https://discord.gg/5kaErDKDRq).
+
+## Contributing
+
+Thanks for considering contributing and help us on creating the Mithril protocol!
+
+The best way to contribute right now is to try things out and provide feedback,
+but we also accept contributions to the documentation and obviously to the
+code itself.
+
+When contributing to this project and interacting with others, please follow our [Code of Conduct](https://github.com/input-output-hk/mithril/blob/main/CODE-OF-CONDUCT.md) and our [Contributing Guidelines](https://github.com/input-output-hk/mithril/blob/main/CONTRIBUTING.md).

mithril-client/README.md

@@ -1,12 +1,13 @@
 [package]
 name = "mithril-common"
-version = "0.2.133"
+version = "0.2.134"
+description = "Common types, interfaces, and utilities for Mithril nodes."
 authors = { workspace = true }
 edition = { workspace = true }
-documentation = { workspace = true }
 homepage = { workspace = true }
 license = { workspace = true }
 repository = { workspace = true }
+include = ["**/*.rs", "Cargo.toml", "README.md", ".gitignore"]
 
 [lib]
 crate-type = ["lib", "cdylib", "staticlib"]
@@ -48,18 +49,24 @@ slog = "2.7.0"
 sqlite = { version = "0.31.1", features = ["bundled"] }
 strum = { version = "0.25.0", features = ["derive"] }
 thiserror = "1.0.49"
-tokio = { version = "1.32.0", features = ["fs", "io-util", "process", "rt", "sync"] }
+tokio = { version = "1.32.0", features = [
+    "fs",
+    "io-util",
+    "process",
+    "rt",
+    "sync",
+] }
 typetag = "0.2.13"
 walkdir = "2.4.0"
 warp = { version = "0.3.6", optional = true }
 
 [target.'cfg(not(windows))'.dependencies]
 # non-windows: use default rug backend
-mithril-stm = { path = "../mithril-stm" }
+mithril-stm = { path = "../mithril-stm", version = "0.3.8" }
 
 [target.'cfg(windows)'.dependencies]
 # Windows doesn't support rug backend, fallback to num-integer
-mithril-stm = { path = "../mithril-stm", default-features = false, features = [
+mithril-stm = { path = "../mithril-stm", version = "0.3.8", default-features = false, features = [
     "num-integer-backend",
 ] }
 
@@ -83,9 +90,7 @@ default = []
 
 allow_skip_signer_certification = []
 # portable feature avoids SIGILL crashes on CPUs not supporting Intel ADX instruction set when built on CPUs that support it
-portable = [
-    "mithril-stm/portable",
-]
+portable = ["mithril-stm/portable"]
 
 # Enable all tests tools
 test_tools = ["apispec", "test_http_server"]