diff --git a/docs/runbook/recompute-certificates-hash/README.md b/docs/runbook/recompute-certificates-hash/README.md index e75ef6a624d..c01d73f3c28 100644 --- a/docs/runbook/recompute-certificates-hash/README.md +++ b/docs/runbook/recompute-certificates-hash/README.md @@ -25,6 +25,7 @@ ssh curry@$MITHRIL_VM Once connected to the aggregator VM, export the environment variables: ```bash export CARDANO_NETWORK=**CARDANO_NETWORK** +export MITHRIL_DISTRIBUTION_LINUX_PKG=**MITHRIL_DISTRIBUTION_LINUX_PKG** ``` And copy the SQLite database file `aggregator.sqlite3`: @@ -94,11 +95,6 @@ Make sure that the certificate chain is valid (wait for the state machine to go docker logs -f --tail 1000 mithril-aggregator ``` -Then disconnect from the aggregator VM: -```bash -exit -``` - ## Cleanup the temp directory Remove the temp directory: @@ -106,9 +102,15 @@ Remove the temp directory: rm -rf /home/curry/temp ``` -## Rollback procedure +## Exit from the VM +Then disconnect from the aggregator VM: +```bash +exit +``` -If the recomputation fails, you can rollback the database. +## Databse rollback procedure + +If the recomputation fails, you can rollback the database,and try again the process. First, stop the aggregator: ```bash @@ -125,11 +127,6 @@ Then, start the aggregator: docker start mithril-aggregator ``` -Make sure that the certificate chain is valid (wait for the state machiene to go into the state `READY`): -```bash -docker logs -f --tail 1000 mithril-aggregator -``` - Then disconnect from the aggregator VM: ```bash exit diff --git a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md index c8a68eef6d0..4d38b0f9366 100644 --- a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md +++ b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md @@ -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 diff --git a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library.md b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library.md new file mode 100644 index 00000000000..dcc36a08460 --- /dev/null +++ b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library.md @@ -0,0 +1,165 @@ +--- +sidebar_position: 4 +--- + +import NetworksMatrix from '../../../networks-matrix.md'; +import CompiledBinaries from '../../../compiled-binaries.md' + +# Mithril client library + +:::info + +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. + +::: + +:::tip + +* For more information about the **Mithril network**, please see the [architecture](../../../mithril/mithril-network/architecture.md) overview. + +* For more information about the **Mithril client** node, please see [this overview](../../../mithril/mithril-network/client.md). + +* Check out the [`Bootstrap a Cardano node`](../../getting-started/bootstrap-cardano-node.md) guide. + +::: + +:::note Mithril networks + + + +::: + +## Resources + +| 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 + +* Install the latest stable version of the [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain. + +* Install OpenSSL development libraries. For example, on Ubuntu/Debian/Mint, run `apt install libssl-dev` + +## Installation + +:::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 +``` + +:::info + +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. + +::: + +## Using Mithril client library + +Below is a basic example of how to use most of the functions exposed by the Mithril client library: + +```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("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(()) +} +``` + +:::info + +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). + +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 --features fs +``` + +::: + +Here is a working example of the code using the configuration parameters of the `release-preprod` network: + +```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(()) +} +``` + +:::tip + +You can read the complete [developer documentation](https://mithril.network/rust-doc/mithril_client/index.html). + +::: \ No newline at end of file diff --git a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md index efefe96bcc6..9a99906e911 100644 --- a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md +++ b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.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) | [: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 @@ -67,7 +67,7 @@ git checkout **YOUR_BUILD_BRANCH_OR_TAG** Change the directory: ```bash -cd mithril/mithril-client +cd mithril/mithril-client-cli ``` ## Development testing and building @@ -113,7 +113,7 @@ make build Display the help menu: ```bash -./mithril-client --help +./mithril-client-cli --help ``` You should see: @@ -121,7 +121,7 @@ You should see: ```bash This program shows, downloads, and verifies certified blockchain artifacts. -Usage: mithril-client [OPTIONS] +Usage: mithril-client-cli [OPTIONS] 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 ``` ::: diff --git a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md index 60ad2a347c6..3b6f908ff8e 100644 --- a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md +++ b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md @@ -33,7 +33,7 @@ Mithril signer is responsible for producing individual signatures that are colle | Node | Source repository | Rust documentation | Docker packages | |:-:|:-----------------:|:------------------:|:---------------:| -**Mithril signer** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-signer) | [:arrow_upper_right:](https://mithril.network/mithril-signer/doc/mithril_signer/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-signer) +**Mithril signer** | [: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) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-signer) ## Pre-requisites diff --git a/docs/website/versioned_docs/version-maintained/manual/developer-docs/references.md b/docs/website/versioned_docs/version-maintained/manual/developer-docs/references.md index 34c0ef50f36..11406389ecf 100644 --- a/docs/website/versioned_docs/version-maintained/manual/developer-docs/references.md +++ b/docs/website/versioned_docs/version-maintained/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) | [: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/docs/website/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md b/docs/website/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md index 980f56f39e5..56573cc6806 100644 --- a/docs/website/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md +++ b/docs/website/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md @@ -71,7 +71,7 @@ git checkout **YOUR_BUILD_BRANCH_OR_TAG** Change the directory: ```bash -cd mithril/mithril-client +cd mithril/mithril-client-cli ``` Run tests (optional): diff --git a/docs/website/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md b/docs/website/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md index c4bbf66fe85..a915f40e4ea 100644 --- a/docs/website/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md +++ b/docs/website/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md @@ -224,7 +224,7 @@ sudo mv mithril-signer /opt/mithril * `User=cardano`: Replace this value with the correct user. We assume that the user used to run the **Cardano node** is `cardano`. The **Mithril signer** must imperatively run with the same user. -* In the `/opt/mithril/mithril-signer/service.env` env file: +* In the `/opt/mithril/mithril-signer.env` env file: * `KES_SECRET_KEY_PATH=/cardano/keys/kes.skey`: replace `/cardano/keys/kes.skey` with the path to your Cardano `KES secret key` file * `OPERATIONAL_CERTIFICATE_PATH=/cardano/cert/opcert.cert`: replace `/cardano/cert/opcert.cert` with the path to your Cardano `operational certificate` file * `DB_DIRECTORY=/cardano/db`: replace `/cardano/db` with the path to the database folder of the **Cardano node** (the one in `--database-path`)