diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ce697ef8898..464d438d3e2 100644 --- a/.github/workflows/ci.yml +++ b/.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: diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml index 6c3487184ac..2a13273304c 100644 --- a/.github/workflows/pre-release.yml +++ b/.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: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1f6191b63ef..4f0114f0457 100644 --- a/.github/workflows/release.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ffb80a863d..1c25e572edc 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/Cargo.lock b/Cargo.lock index b7c1ac43149..f85183c377c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2219,7 +2219,7 @@ dependencies = [ [[package]] name = "mithril-client" -version = "0.5.4" +version = "0.5.5" dependencies = [ "anyhow", "async-recursion", @@ -2289,7 +2289,7 @@ dependencies = [ [[package]] name = "mithril-common" -version = "0.2.133" +version = "0.2.134" dependencies = [ "anyhow", "async-trait", @@ -2389,7 +2389,7 @@ dependencies = [ [[package]] name = "mithril-stm" -version = "0.3.8" +version = "0.3.9" dependencies = [ "bincode", "blake2 0.10.6", diff --git a/README.md b/README.md index 4e0dccf8570..48d8af7f4f4 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/website/root/manual/developer-docs/references.md b/docs/website/root/manual/developer-docs/references.md index 76465c33984..11406389ecf 100644 --- a/docs/website/root/manual/developer-docs/references.md +++ b/docs/website/root/manual/developer-docs/references.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) | - | - diff --git a/mithril-client/Cargo.toml b/mithril-client/Cargo.toml index 46559338a31..3719323be42 100644 --- a/mithril-client/Cargo.toml +++ b/mithril-client/Cargo.toml @@ -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" diff --git a/mithril-client/README.md b/mithril-client/README.md index 617f376a579..a144d5228f2 100644 --- a/mithril-client/README.md +++ b/mithril-client/README.md @@ -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). \ No newline at end of file diff --git a/mithril-common/Cargo.toml b/mithril-common/Cargo.toml index 90bc07515de..e78c22fda38 100644 --- a/mithril-common/Cargo.toml +++ b/mithril-common/Cargo.toml @@ -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"] diff --git a/mithril-common/README.md b/mithril-common/README.md new file mode 100644 index 00000000000..91368cf7a1c --- /dev/null +++ b/mithril-common/README.md @@ -0,0 +1,6 @@ +# Mithril-common ![crates.io](https://img.shields.io/crates/v/mithril-common.svg) [![Discord](https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square)](https://discord.gg/5kaErDKDRq) + + +**This is a work in progress** 🛠 + +This crate contains common utility types and testing infrastructure used in the implementation of the Mithril nodes. \ No newline at end of file diff --git a/mithril-stm/Cargo.toml b/mithril-stm/Cargo.toml index 03ea1dec892..15b5a7f35bc 100644 --- a/mithril-stm/Cargo.toml +++ b/mithril-stm/Cargo.toml @@ -1,9 +1,8 @@ [package] name = "mithril-stm" -version = "0.3.8" +version = "0.3.9" edition = { workspace = true } authors = { workspace = true } -documentation = { workspace = true } homepage = { workspace = true } license = { workspace = true } repository = { workspace = true } diff --git a/mithril-stm/README.md b/mithril-stm/README.md index 13a07650ee0..fd354f9720d 100644 --- a/mithril-stm/README.md +++ b/mithril-stm/README.md @@ -1,7 +1,7 @@ -# Mithril-stm ![CI workflow](https://github.com/input-output-hk/mithril/actions/workflows/ci.yml/badge.svg) ![crates.io](https://img.shields.io/crates/v/mithril_stm.svg) +# Mithril-stm ![CI workflow](https://github.com/input-output-hk/mithril/actions/workflows/ci.yml/badge.svg) ![crates.io](https://img.shields.io/crates/v/mithril_stm.svg) [![Discord](https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square)](https://discord.gg/5kaErDKDRq) -**This is a work in progress** :hammer_and_wrench:s +**This is a work in progress** 🛠 * `mithril-stm` is a Rust implementation of the scheme described in the paper [Mithril: Stake-based Threshold Multisignatures](https://eprint.iacr.org/2021/916.pdf) by Pyrros Chaidos and Aggelos Kiayias. * The BLS12-381 signature library [blst](https://github.com/supranational/blst) is used as the backend for the implementation of STM.