diff --git a/docs/website/versioned_docs/version-maintained/glossary.md b/docs/website/versioned_docs/version-maintained/glossary.md index 342303402a6..1f5256bcd68 100644 --- a/docs/website/versioned_docs/version-maintained/glossary.md +++ b/docs/website/versioned_docs/version-maintained/glossary.md @@ -24,6 +24,12 @@ A Cardano node is a node that runs in a [Cardano network](#cardano-network). The A Cardano key pair is an asymmetric key pair used to identify a [stake pool operator](#stake-pool-operator-spo) on the [Cardano network](#cardano-network). +## Cardano transaction + +A Cardano transaction proof is a cryptographic proof that a sub-set of Cardano transactions is included in the Cardano transactions set. It is generated upon request from a [Mithril client](#mithril-client) and is signed by a [certificate](#certificate). + +A Cardano transactions set commitment represents, in a succinct way, the Cardano transactions set that was signed by Mithril at a given [Beacon](#beacon). + ## Certificate The Mithril aggregator combines the produced [multi-signature](#multi-signature) and some metadata into a Mithril certificate that will be later used by the [Mithril client](#mithril-client) to verify the authenticity of a [snapshot](#snapshot). The certificates are chained so that the [stake distribution](#stake-distribution) used to create the signatures is verifiably genuine. diff --git a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library-wasm.md b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library-wasm.md index ecf3aee4ab9..230c3c24155 100644 --- a/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library-wasm.md +++ b/docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library-wasm.md @@ -14,6 +14,7 @@ Mithril client library WASM can be used by Javascript developers to use the Mith It is responsible for handling the different types of data certified by Mithril, and available through a Mithril aggregator: - [**Snapshot**](../../../glossary.md#snapshot): list and get. - [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get. +- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get commitments, get proofs - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation. ::: @@ -113,6 +114,36 @@ let valid_stake_distribution_message = await client.verify_message_match_certifi console.log("valid_stake_distribution_message:", valid_stake_distribution_message); ``` +If the aggregator signs **CardanoTransactions**, you can add the code below to the previous example: + +:::tip + +You can verify that the aggregator signs **CardanoTransactions** by running the command below: + +```bash +wget -q -O - YOUR_AGGREGATOR_ENDPOINT | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])' +``` + +For example with the aggregator on `testing-sanchonet` Mithril network: + +```bash +wget -q -O - https://aggregator.testing-sanchonet.api.mithril.network/aggregator | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])' +``` + +::: + +```js +const proof = await client.unstable.get_cardano_transaction_proofs(["CARDANO_TRANSACTION_HASH_1", "CARDANO_TRANSACTION_HASH_2"]); +console.log("Proof tx hash", proof.transactions_hashes); +console.log("Proof certificate hash", proof.certificate_hash); + +let proof_certificate = await client.verify_certificate_chain(proof.certificate_hash); +console.log("verify_certificate_chain OK, last_certificate_from_chain:", proof_certificate); + +let valid_cardano_transaction_proof = await client.unstable.verify_cardano_transaction_proof_then_compute_message(proof, proof_certificate); +console.log("valid_cardano_transaction_proof:", valid_cardano_transaction_proof); +``` + :::tip You can read the complete [Rust developer documentation](https://mithril.network/rust-doc/mithril_client_wasm/index.html). 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 9646844ef43..af08c0ff1fe 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 @@ -15,9 +15,11 @@ Mithril client is responsible for restoring the **Cardano** blockchain on an emp :::tip -* For more information about the **Mithril network**, please see the [architecture](../../../mithril/mithril-network/architecture.md) overview. +* 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). +* 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. @@ -29,7 +31,6 @@ Mithril client is responsible for restoring the **Cardano** blockchain on an emp ::: - ## Resources | Node | Source repository | Rust documentation | Docker packages | @@ -38,7 +39,8 @@ Mithril client is responsible for restoring the **Cardano** blockchain on an emp ## Pre-requisites -* Install the latest stable version of the [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain. +* 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` @@ -64,7 +66,7 @@ Switch to the desired branch/tag: git checkout **YOUR_BUILD_BRANCH_OR_TAG** ``` -Change the directory: +Change the directory: ```bash cd mithril/mithril-client-cli @@ -119,14 +121,15 @@ Display the help menu: You should see: ```bash -This program shows, downloads, and verifies certified blockchain artifacts. +This program shows, downloads and verifies certified blockchain artifacts. -Usage: mithril-client-cli [OPTIONS] +Usage: mithril-client [OPTIONS] Commands: - snapshot Snapshot commands - mithril-stake-distribution Mithril stake distribution management (alias: msd) - help Print this message or the help for the given subcommand(s) + snapshot Snapshot management + mithril-stake-distribution Mithril Stake Distribution management (alias: msd) + cardano-transaction [unstable] Cardano transactions management (alias: ctx) + help Print this message or the help of the given subcommand(s) Options: --run-mode @@ -136,17 +139,18 @@ Options: --config-directory Directory where configuration file is located [default: ./config] --aggregator-endpoint - Override configuration Aggregator endpoint URL + Override configuration Aggregator endpoint URL [env: AGGREGATOR_ENDPOINT=] --log-format-json Enable JSON output for logs displayed according to verbosity level --log-output Redirect the logs to a file + --unstable + Enable unstable commands (such as Cardano Transactions) -h, --help Print help -V, --version Print version - ``` Run in release mode with the default configuration: @@ -196,7 +200,8 @@ If you wish to delve deeper and access several levels of logs from the Mithril c ### Registry image -A list of available images on the registry can be found [here](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client). +A list of available images on the registry can be +found [here](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client). To prepare the environment variables, retrieve the values from the above **Mithril networks** table. @@ -246,6 +251,15 @@ mithril_client mithril-stake-distribution list # 6- Download and verify the given Mithril stake distribution mithril_client mithril-stake-distribution download $MITHRIL_STAKE_DISTRIBUTION_ARTIFACT_HASH + +# 7- List Cardano transaction commitments +mithril_client --unstable cardano-transaction commitment list + +# 8- Show detailed information about a Cardano transaction commitment +mithril_client --unstable cardano-transaction commitment show $CARDANO_TRANSACTION_COMMITMENT_HASH + +# 9- Certify that given list of transactions hashes are included in the Cardano transactions set +mithril_client --unstable cardano-transaction certify $TRANSACTION_HASH_1,$TRANSACTION_HASH_2 ``` ### Local image @@ -283,11 +297,21 @@ Here are the subcommands available: | **help** | Prints this message or the help for the given subcommand(s)| | **list** | Lists available Mithril stake distributions| +### Cardano transactions + +| Subcommand | Performed action | +|------------|------------------| +| **certify** | Certifies that given list of transactions hashes are included in the Cardano transactions set| +| **commitment list** | Lists available Cardano transactions commitments| +| **commitment show** | Shows information about a Cardano transactions commitment| +| **help** | Prints this message or the help for the given subcommand(s)| + ## Configuration parameters The configuration parameters can be set in either of the following ways: -1. In a configuration file, depending on the `--run-mode` parameter. If the runtime mode is `testnet`, the file is located in `./conf/testnet.json`. +1. In a configuration file, depending on the `--run-mode` parameter. If the runtime mode is `testnet`, the file is + located in `./conf/testnet.json`. 2. The value can be overridden by an environment variable with the parameter name in uppercase. @@ -296,6 +320,7 @@ Here is a list of the available parameters: | Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory | |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:| | `verbose` | `--verbose` | `-v` | `VERBOSE` | Verbosity level | - | Parsed from the number of occurrences: `-v` for `Warning`, `-vv` for `Info`, `-vvv` for `Debug` and `-vvvv` for `Trace` | :heavy_check_mark: | +| `unstable` | `--unstable` | - | - | Enable unstable commands | - | - | - | | `run_mode` | `--run-mode` | - | `RUN_MODE` | Runtime mode | `dev` | - | :heavy_check_mark: | | `network` | - | - | `NETWORK` | Cardano network | - | `testnet` or `mainnet` or `devnet` | :heavy_check_mark: | | `aggregator_endpoint` | `--aggregator-endpoint` | - | `AGGREGATOR_ENDPOINT` | Aggregator node endpoint | - | `https://aggregator.pre-release-preview.api.mithril.network/aggregator` | :heavy_check_mark: | @@ -336,3 +361,23 @@ Here is a list of the available parameters: |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:| | `artifact_hash` | `--artifact-hash` | - | - | Hash of the Mithril stake distribution artifact or `latest` for the latest artifact | - | - | :heavy_check_mark: | | `download_dir` | `--download-dir` | - | - | Directory where the Mithril stake distribution will be downloaded | . | - | - | + +`cardano-transaction commitment show` command: + +| Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory | +|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:| +| `hash` | `--hash` | - | `HASH` | Cardano transaction commitment hash or `latest` for the latest Cardano transaction commitment | - | - | :heavy_check_mark: | +| `json` | `--json` | - | - | Enable JSON output for command results | - | - | - | + +`cardano-transaction commitment list` command: + +| Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory | +|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:| +| `json` | `--json` | - | - | Enable JSON output for command results | - | - | - | + +`cardano-transaction certify` command: + +| Parameter | Command line (long) | Command line (short) | Environment variable | Description | Default value | Example | Mandatory | +|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:| +| `transactions_hashes` | `--transactions_hashes` | - | `TRANSACTIONS_HASHES` | Cardano transactions hashes separated by commas | - | - | :heavy_check_mark: | +| `json` | `--json` | - | - | Enable JSON output for progress logs | - | - | - | diff --git a/docs/website/versioned_docs/version-maintained/manual/getting-started/SPO-on-boarding-guide.md b/docs/website/versioned_docs/version-maintained/manual/getting-started/SPO-on-boarding-guide.md index ce579f4d13a..59a2a260ab7 100644 --- a/docs/website/versioned_docs/version-maintained/manual/getting-started/SPO-on-boarding-guide.md +++ b/docs/website/versioned_docs/version-maintained/manual/getting-started/SPO-on-boarding-guide.md @@ -47,13 +47,13 @@ Each **Mithril network** has its own configuration, which can be found in the [C ## Step 2: Get Mithril ready for `mainnet` -:::info +:::warning -This step is **optional**, but **strongly recommended**. +This step is **mandatory**. You must complete it before moving forward to **Step 3**. ::: -To get ready for `mainnet`, you should: +To get ready for `mainnet`, you need to: - Be an active SPO on the Cardano `preprod` network for at least one epoch or five days. - Set up a **Mithril signer** node on Mithril's `release-preprod` network by following the [**Run a Mithril signer node (SPO)**](run-signer-node.md) guide. - You **must** run the **Production** deployment model. @@ -68,7 +68,7 @@ Each **Mithril network** has its own configuration, which can be found in the [C :::warning -This step is **mandatory**. It is **strongly recommended** to complete **Step 2** beforehand. +This step is **mandatory**. You must have completed **Step 2** before. :::