Merge pull request #1527 from input-output-hk/ensemble/rotate-documentation

Rotate documentation

Author: dlachaume

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.

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).

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] <COMMAND>
+Usage: mithril-client [OPTIONS] <COMMAND>
 
 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 <RUN_MODE>
@@ -136,17 +139,18 @@ Options:
       --config-directory <CONFIG_DIRECTORY>
           Directory where configuration file is located [default: ./config]
       --aggregator-endpoint <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 <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 | - | - | - |

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.
 
 :::