Merge pull request #593 from input-output-hk/jpraynaud/fix-doc-mithri…

…l-networks Enhance Mithril Networks documentation
input-output-hk · Nov 14, 2022 · 9714e2c · 9714e2c
2 parents 7024503 + b624838
commit 9714e2c
Show file tree

Hide file tree

Showing 14 changed files with 73 additions and 81 deletions.
diff --git a/docs/root/manual/developer-docs/nodes/mithril-aggregator.md b/docs/root/manual/developer-docs/nodes/mithril-aggregator.md
@@ -2,6 +2,8 @@
 sidebar_position: 1
 ---
 
+import NetworksMatrix from '../../../../shared/networks-matrix.md';
+
 # Mithril Aggregator Node
 
 :::info
@@ -18,15 +20,9 @@ This is the node of the **Mithril Network** responsible for collecting individua
 
 :::
 
-:::tip
-
-The [Mithril test networks](../../../manual/developer-docs/references.md#mithril-networks) are:
-
-* `preview`: Test network with magic id `2`, implemented on the IOG hosted Mithril Aggregator
-* `preprod`: Test network with magic id `1`, not implemented yet on the IOG hosted Mithril Aggregator
-* `testnet`: Legacy test network with magic id `1097911063`, used to be on the IOG hosted Mithril Aggregator, now deprecated
+:::note Mithril Networks
 
-In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, but you need to replace it with the identifier of the network that runs on your Cardano node
+<NetworksMatrix />
 
 :::
 
@@ -42,7 +38,7 @@ In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, bu
 
 * Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `apt install libssl-dev`
 
-* Ensure SQLite3 library is installed on your system and its version is at least `1.35` (released Apr. 2021) on Debian/Ubuntu: `apt install libsqlite3` and `sqlite3 --version`.
+* Ensure SQLite3 library is installed on your system and its version is at least `3.35` (released Apr. 2021) on Debian/Ubuntu: `apt install libsqlite3` and `sqlite3 --version`.
 
 ## Download source
 
@@ -157,7 +153,7 @@ Run 'serve' command in release with a specific mode
 Run 'serve' command in release with a custom configuration via env vars
 
 ```bash
-GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey) RUN_INTERVAL=60000 NETWORK=**YOUR_TEST_NETWORK** ./mithril-aggregator serve
+GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) RUN_INTERVAL=60000 NETWORK=**YOUR_CARDANO_NETWORK** ./mithril-aggregator serve
 ```
 
 ## Release build and run binary 'genesis' command
@@ -224,7 +220,7 @@ This allows the Mithril Aggregator node to import the signed payload of the `Gen
 Run 'genesis import' command in release with a custom configuration via env vars
 
 ```bash
-GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey) RUN_INTERVAL=60000 NETWORK=**YOUR_TEST_NETWORK** ./mithril-aggregator genesis import --signed-payload-path **YOUR_SIGNED_PAYLOAD_PATH**
+GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) RUN_INTERVAL=60000 NETWORK=**YOUR_CARDANO_NETWORK** ./mithril-aggregator genesis import --signed-payload-path **YOUR_SIGNED_PAYLOAD_PATH**
 ```
 
 :::tip

diff --git a/docs/root/manual/developer-docs/nodes/mithril-client.md b/docs/root/manual/developer-docs/nodes/mithril-client.md
@@ -2,6 +2,8 @@
 sidebar_position: 3
 ---
 
+import NetworksMatrix from '../../../../shared/networks-matrix.md';
+
 # Mithril Client Node
 
 :::info
@@ -20,18 +22,13 @@ This is the node of the **Mithril Network** responsible for restoring the **Card
 
 :::
 
-:::tip
-
-The [Mithril test networks](../../../manual/developer-docs/references.md#mithril-networks) are:
+:::note Mithril Networks
 
-* `preview`: Test network with magic id `2`, implemented on the IOG hosted Mithril Aggregator
-* `preprod`: Test network with magic id `1`, not implemented yet on the IOG hosted Mithril Aggregator
-* `testnet`: Legacy test network with magic id `1097911063`, used to be on the IOG hosted Mithril Aggregator, now deprecated
-
-In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, but you need to replace it with the identifier of the network that runs on your Cardano node
+<NetworksMatrix />
 
 :::
 
+
 ## Resources
 
 | Node | Source Repository | Rust Documentation | Docker Packages |
@@ -159,7 +156,7 @@ Run in release with a specific mode
 Run in release with a custom configuration via env vars
 
 ```bash
-GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey) NETWORK=**YOUR_TEST_NETWORK** AGGREGATOR_ENDPOINT=https://aggregator.api.mithril.network/aggregator ./mithril-client
+GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) NETWORK=**YOUR_CARDANO_NETWORK** AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT** ./mithril-client
 ```
 
 :::tip
@@ -223,6 +220,6 @@ Here is a list of the available parameters:
 | `verbose` | `--verbose` | `-v` | `VERBOSE` | Verbosity level | - | Parsed from number of occurrences: `-v` for `Warning`, `-vv` for `Info`, `-vvv` for `Debug` and `-vvvv` for `Trace` | :heavy_check_mark: |
 | `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.api.mithril.network/aggregator` | :heavy_check_mark: |
+| `aggregator_endpoint` | `--aggregator-endpoint` | - | `AGGREGATOR_ENDPOINT` | Aggregator node endpoint | - | `https://aggregator.pre-release-preview.api.mithril.network/aggregator` | :heavy_check_mark: |
 | `genesis_verification_key` | - | - | `GENESIS_VERIFICATION_KEY` | Genesis verification key | - | - | :heavy_check_mark: |
 | `json_output` | `--json` | `-j` | - | Enable JSON output | no | - | - |
diff --git a/docs/root/manual/developer-docs/nodes/mithril-signer.md b/docs/root/manual/developer-docs/nodes/mithril-signer.md
@@ -2,6 +2,8 @@
 sidebar_position: 2
 ---
 
+import NetworksMatrix from '../../../../shared/networks-matrix.md';
+
 # Mithril Signer Node
 
 :::info
@@ -20,15 +22,9 @@ This is the node of the **Mithril Network** responsible for producing individual
 
 :::
 
-:::tip
-
-The [Mithril test networks](../../../manual/developer-docs/references.md#mithril-networks) are:
-
-* `preview`: Test network with magic id `2`, implemented on the IOG hosted Mithril Aggregator
-* `preprod`: Test network with magic id `1`, not implemented yet on the IOG hosted Mithril Aggregator
-* `testnet`: Legacy test network with magic id `1097911063`, used to be on the IOG hosted Mithril Aggregator, now deprecated
+:::note Mithril Networks
 
-In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, but you need to replace it with the identifier of the network that runs on your Cardano node
+<NetworksMatrix />
 
 :::
 
@@ -44,7 +40,7 @@ In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, bu
 
 * Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `apt install libssl-dev`
 
-* Ensure SQLite3 library is installed on your system and its version is at least `1.35` (released Apr. 2021) on Debian/Ubuntu: `apt install libsqlite3` and `sqlite3 --version`.
+* Ensure SQLite3 library is installed on your system and its version is at least `3.35` (released Apr. 2021) on Debian/Ubuntu: `apt install libsqlite3` and `sqlite3 --version`.
 
 ## Download source
 
@@ -142,7 +138,7 @@ Run in release with a specific mode
 Run in release with a custom configuration via env vars
 
 ```bash
-NETWORK=**YOUR_TEST_NETWORK** AGGREGATOR_ENDPOINT=https://aggregator.api.mithril.network/aggregator ./mithril-signer
+NETWORK=**YOUR_CARDANO_NETWORK** AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT** ./mithril-signer
 ```
 
 :::tip
@@ -188,7 +184,7 @@ Here is a list of the available parameters:
 `network_magic` | - | - | `NETWORK_MAGIC` | Cardano Network Magic number (for `testnet` and `devnet`) | - | `1097911063` or `42` | - |
 | `party_id` | - | - | `PARTY_ID` | Party Id of the signer, usually the `Pool Id` of the SPO | - | `pool1pxaqe80sqpde7902er5kf6v0c7y0sv6d5g676766v2h829fvs3x` | - | Mandatory in `Pool Id Declaration Mode`  where the owner is not verified (soon to be deprecated)
 | `run_interval` | - | - | `RUN_INTERVAL` | Interval between two runtime cycles in ms | - | `60000` | :heavy_check_mark: |
-| `aggregator_endpoint` | - | - | `AGGREGATOR_ENDPOINT` | Aggregator node endpoint | - | `https://aggregator.api.mithril.network/aggregator` | :heavy_check_mark: |
+| `aggregator_endpoint` | - | - | `AGGREGATOR_ENDPOINT` | Aggregator node endpoint | - | `https://aggregator.pre-release-preview.api.mithril.network/aggregator` | :heavy_check_mark: |
 | `data_stores_directory` | - | - | `DATA_STORES_DIRECTORY` | Directory to store signer data (Stakes, Protocol initializers, ...) | - | `./mithril-signer/stores` | :heavy_check_mark: |
 | `store_retention_limit` | - | - | `STORE_RETENTION_LIMIT` | Maximum number of records in stores. If not set, no limit is set. | - | - | - |
 | `kes_secret_key_path` | - | - | `KES_SECRET_KEY_PATH` | Path to the `Cardano KES Secret Key` file. Mandatory in `Pool Id Certification Mode` where the owner is verified (experimental, soon to be stable & preferred mode) | - | - | - |

diff --git a/docs/root/manual/developer-docs/references.md b/docs/root/manual/developer-docs/references.md
@@ -2,6 +2,8 @@
 sidebar_position: 2
 ---
 
+import NetworksMatrix from '../../../shared/networks-matrix.md';
+
 # API Reference
 
 Welcome to the Mithril API references doc!
@@ -20,17 +22,7 @@ For more information about the **Mithril Protocol**, please refer to the [About
 
 ## Mithril Networks
 
-Here is an up to date list of all the Mithril Networks and their status
-> Last update: 11/02/2022
-
-| Mithril Network | Cardano Network | Magic Id | Supported | Aggregator Endpoint | Genesis Verification Key | Note
-|------------|------------|:-----------:|:------------:|:-----------------:|:------------------:|:------------|
-| `release-mainnet` | `mainnet` | - | :x: | - | - | Not supported yet
-| `release-preprod` | `preprod` | `1` | :heavy_check_mark: | [:arrow_upper_right:](https://aggregator.release-preprod.api.mithril.network/aggregator) | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey) | Works on re-spun `preprod` network
-| `pre-release-preview` | `preview` | `2` | :heavy_check_mark: | [:arrow_upper_right:](https://aggregator.pre-release-preview.api.mithril.network/aggregator) | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey) | Works on re-spun `preview` network
-| `testing-preview` | `preview` | `2` | :heavy_check_mark: | [:arrow_upper_right:](https://aggregator.testing-preview.api.mithril.network/aggregator) | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey) | Works on re-spun `preview` network
-| `dev-devnet` | `devnet` | `42` | :heavy_check_mark: | [:arrow_upper_right:](http://localhost:8080/aggregator) | - | Supported on the `devnet` only
-| `-` | `testnet` | `1097911063` | :x: | - | - | Decommissioned, not supported anymore
+<NetworksMatrix />
 
 ## Dependencies List
 

diff --git a/docs/root/manual/getting-started/bootstrap-cardano-node.md b/docs/root/manual/getting-started/bootstrap-cardano-node.md
@@ -2,6 +2,8 @@
 sidebar_position: 1
 ---
 
+import NetworksMatrix from '../../../shared/networks-matrix.md';
+
 # Bootstrap a Cardano Node
 
 :::info
@@ -10,15 +12,9 @@ Thanks to a **Mithril Client** connected to a **Mithril Aggregator**, you will r
 
 :::
 
-:::tip
-
-The [Mithril test networks](../../manual/developer-docs/references.md#mithril-networks) are:
-
-* `preview`: Test network with magic id `2`, implemented on the IOG hosted Mithril Aggregator
-* `preprod`: Test network with magic id `1`, not implemented yet on the IOG hosted Mithril Aggregator
-* `testnet`: Legacy test network with magic id `1097911063`, used to be on the IOG hosted Mithril Aggregator, now deprecated
+:::note Mithril Networks
 
-In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, but you need to replace it with the identifier of the network that runs on your Cardano node
+<NetworksMatrix />
 
 :::
 
@@ -120,13 +116,13 @@ If you want to dig deeper, you can get access to several level of logs from the
 
 ```bash
 # Cardano network
-NETWORK=**YOUR_TEST_NETWORK**
+NETWORK=**YOUR_CARDANO_NETWORK**
 
 # Aggregator API endpoint URL
-AGGREGATOR_ENDPOINT=https://aggregator.api.mithril.network/aggregator
+AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
 
 # Genesis verification key
-GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey)
+GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**)
 
 # Digest of the latest produced snapshot for convenience of the demo
 # You can also modify this variable and set it to the value of the digest of a snapshot that you can retrieve at step 2
@@ -225,7 +221,7 @@ docker run -v cardano-node-ipc:/ipc -v cardano-node-data:/data --mount type=bind
 Launch an empty Cardano node and make it live in minutes!
 
 ```bash
-docker run -v cardano-node-ipc:/ipc -v cardano-node-data:/data --mount type=bind,source="$(pwd)/data/testnet/$SNAPSHOT_DIGEST/db",target=/data/db/ -e NETWORK=**YOUR_TEST_NETWORK** inputoutput/cardano-node
+docker run -v cardano-node-ipc:/ipc -v cardano-node-data:/data --mount type=bind,source="$(pwd)/data/testnet/$SNAPSHOT_DIGEST/db",target=/data/db/ -e NETWORK=**YOUR_CARDANO_NETWORK** inputoutput/cardano-node
 ```
 
 You will see the node start by validating the files injested from the snapshot archive

diff --git a/docs/root/manual/getting-started/run-mithril-devnet.md b/docs/root/manual/getting-started/run-mithril-devnet.md
@@ -39,7 +39,7 @@ More information about this private Cardano/Mithril `devnet` is available [here]
 
 * Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `apt install libssl-dev`
 
-* Ensure SQLite3 library is installed on your system and its version is at least `1.35` (released Apr. 2021) on Debian/Ubuntu: `apt install libsqlite3` and `sqlite3 --version`.
+* Ensure SQLite3 library is installed on your system and its version is at least `3.35` (released Apr. 2021) on Debian/Ubuntu: `apt install libsqlite3` and `sqlite3 --version`.
 
 ## Download source
 

diff --git a/docs/root/manual/getting-started/run-signer-node.md b/docs/root/manual/getting-started/run-signer-node.md
@@ -2,6 +2,8 @@
 sidebar_position: 2
 ---
 
+import NetworksMatrix from '../../../shared/networks-matrix.md';
+
 # Run a Mithril Signer node (SPO)
 
 :::info
@@ -10,15 +12,9 @@ In this guide, you will learn how to setup a **Mithril Signer** on top of a **Ca
 
 :::
 
-:::tip
-
-The [Mithril test networks](../../manual/developer-docs/references.md#mithril-networks) are:
-
-* `preview`: Test network with magic id `2`, implemented on the IOG hosted Mithril Aggregator
-* `preprod`: Test network with magic id `1`, not implemented yet on the IOG hosted Mithril Aggregator
-* `testnet`: Legacy test network with magic id `1097911063`, used to be on the IOG hosted Mithril Aggregator, now deprecated
+:::note Mithril Networks
 
-In this documentation, we use the generic `**YOUR_TEST_NETWORK**` identifier, but you need to replace it with the identifier of the network that runs on your Cardano node
+<NetworksMatrix />
 
 :::
 
@@ -54,7 +50,7 @@ For more information about the **Mithril Protocol**, please refer to the [About
 
 * Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `apt install libssl-dev`
 
-* Ensure the SQLite3 version is at lease `1.35` (released Apr. 2021)
+* Ensure the SQLite3 version is at lease `3.35` (released Apr. 2021)
 
 ## Mithril Keys Certification
 
@@ -194,8 +190,8 @@ First create an env file that will be used by the service:
 ```bash
 sudo bash -c 'cat > /opt/mithril/mithril-signer.env << EOF
 PARTY_ID=**YOUR_POOL_ID_BECH32**
-NETWORK=**YOUR_TEST_NETWORK**
-AGGREGATOR_ENDPOINT=https://aggregator.api.mithril.network/aggregator
+NETWORK=**YOUR_CARDANO_NETWORK**
+AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
 RUN_INTERVAL=60000
 DB_DIRECTORY=/cardano/db
 CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket
@@ -211,8 +207,8 @@ EOF'
 sudo bash -c 'cat > /opt/mithril/mithril-signer.env << EOF
 KES_SECRET_KEY_PATH=**YOUR_KES_SECRET_KEY_PATH**
 OPERATIONAL_CERTIFICATE_PATH=**YOUR_OPERATIONAL_CERTIFICATE_PATH**
-NETWORK=**YOUR_TEST_NETWORK**
-AGGREGATOR_ENDPOINT=https://aggregator.api.mithril.network/aggregator
+NETWORK=**YOUR_CARDANO_NETWORK**
+AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
 RUN_INTERVAL=60000
 DB_DIRECTORY=/cardano/db
 CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket

diff --git a/docs/shared/networks-matrix.md b/docs/shared/networks-matrix.md
@@ -0,0 +1,17 @@
+Here is an up to date list of all the **Mithril Networks**, their configurations and their status:
+
+> Last update: 11/14/2022
+
+| Mithril Network | Cardano Network | Magic Id | Supported | Aggregator Endpoint | Genesis Verification Key | Note
+|------------|------------|:-----------:|:------------:|:-----------------:|:------------------:|:------------|
+| `release-mainnet` | `mainnet` | - | :x: | - | - | Not supported yet
+| `release-preprod` | `preprod` | `1` | :heavy_check_mark: | [:arrow_upper_right:](https://aggregator.release-preprod.api.mithril.network/aggregator "https://aggregator.release-preprod.api.mithril.network/aggregator") | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey "https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey") | Stable Release
+| `pre-release-preview` | `preview` | `2` | :heavy_check_mark: | [:arrow_upper_right:](https://aggregator.pre-release-preview.api.mithril.network/aggregator "https://aggregator.pre-release-preview.api.mithril.network/aggregator") | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey "https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey") | Unstable Pre-Release
+| `testing-preview` | `preview` | `2` | :heavy_check_mark: | [:arrow_upper_right:](https://aggregator.testing-preview.api.mithril.network/aggregator "https://aggregator.testing-preview.api.mithril.network/aggregator") | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey "https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey") | Unstable Testing (devs only)
+| `dev-devnet` | `devnet` | `42` | :heavy_check_mark: | [:arrow_upper_right:](http://localhost:8080/aggregator "http://localhost:8080/aggregator") | - | Supported on the `devnet` only
+| `-` | `testnet` | `1097911063` | :x: | [:arrow_upper_right:](https://aggregator.api.mithril.network/aggregator "https://aggregator.api.mithril.network/aggregator") | [:arrow_upper_right:](https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey "https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey") | Decommissioned, not supported anymore
+
+:warning: In this documentation, we use the generic:
+* ****YOUR_CARDANO_NETWORK**** identifier, but you need to replace it with the name of the network that runs on your Cardano node (e.g. `preprod`)
+* ****YOUR_AGGREGATOR_ENDPOINT**** identifier, but you need to replace it with the endpoint of an aggregator that runs on the Cardano network you target (e.g. `https://aggregator.release-preprod.api.mithril.network/aggregator`)
+* ****YOUR_GENESIS_VERIFICATION_KEY**** identifier, but you need to replace it with the genesis verification key url that runs on the Cardano network you target (e.g. `https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_genesis.vkey`)