Merge pull request #790 from input-output-hk/jpraynaud/752-update-era-documentation

Update Era Switch documentation

Author: jpraynaud

docs/blog/2023-03-02-era-switch-feature/index.md

@@ -5,18 +5,26 @@ authors:
 tags: [era, era activation, era markers, era switch, hard fork]
 ---
 
+**Update 2023/03/08**: The Era Switch behavior has been activated on the `pre-release-preview` network.
+
 ### An new Era Switch behavior will be introduced soon to the Mithril networks
 
 **Epic**: `Implement eras behavior switch #707](Implement eras behavior switch` [#707](https://github.com/input-output-hk/mithril/issues/707)
 
-:warning: The Era Switch is not deployed yet to the `pre-release-preview` and `release-preprod` network. A special announcement will be made on the **moria** Discord channel when a new release condaidate distribution is ready.
+:warning: The Era Switch is not deployed yet to the `pre-release-preview` and `release-preprod` network. A special announcement will be made on the **moria** Discord channel when a new release candidate distribution is ready.
 
 In order to guarantee that any breaking change of the Mithril nodes does not break the Certificate Chain and the that new snapshots are consistently produced, the Mithril team has developped an Era Switch Behavior. This mechanism enables to embed new features in the signer and aggregator nodes prior ro releasing them. Also the activation of these new features will take place in a coordinated manner: all the eligible nodes will hot switch to a new era at the same Cardano epoch transition. To do so, the nodes rely on a transaction that is stored on the Cardano chain that provides era markers with the associated activations epochs for the eras.
 
 :fire: Activating this feature will require an update of configuration of the signer nodes after updating their binary:
 - The `ERA_READER_ADAPTER_TYPE` env var must be set to `cardano-chain`
 - The `ERA_READER_ADAPTER_PARAMS` env var must be set to the result of the command `jq -nc --arg address $(wget -q -O - **YOUR_ERA_READER_ADDRESS**) --arg verification_key $(wget -q -O - **YOUR_ERA_READER_VERIFICATION_KEY**) '{"address": $address, "verification_key": $verification_key}'` (the ****YOUR_ERA_READER_ADDRESS**** and ****YOUR_ERA_READER_VERIFICATION_KEY**** are values provided in the networks configuration matrix)
 
+Here is the configuration values that should be used on `pre-release-preview`:
+```bash
+ERA_READER_ADAPTER_TYPE=cardano-chain
+ERA_READER_ADAPTER_PARAMS={"address":"addr_test1qrv5xfwh043mlc3vk5d97s4nmhxu7cmleyssvhx37gkfyejfe8d38v3vsfgetjafgrsdc49krug8wf04h5rmtengtejqlxrksk","verification_key":"5b35352c3232382c3134342c38372c3133382c3133362c34382c382c31342c3138372c38352c3134382c39372c3233322c3235352c3232392c33382c3234342c3234372c3230342c3139382c31332c33312c3232322c32352c3136342c35322c3130322c39312c3132302c3230382c3134375d"}
+```
+
 All theses information will be available at the updated [`Run a Mithril Signer node (SPO)`](https://mithril.network/doc/manual/getting-started/run-signer-node) guide.
 
 Here is a schema that illustrates the era switch behavior:

docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md

@@ -39,7 +39,7 @@ This is the node of the **Mithril Network** responsible for collecting individua
 
 * 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 `3.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.40`. Run `sqlite3 --version` to check your version.
 
 ## Download source
 
@@ -124,6 +124,7 @@ Usage: mithril-aggregator [OPTIONS] <COMMAND>
 
 Commands:
   genesis  Genesis tools
+  era      Era tools
   serve    Server runtime mode
   help     Print this message or the help of the given subcommand(s)
 
@@ -137,9 +138,9 @@ Options:
       --config-directory <CONFIG_DIRECTORY>
           Directory where configuration file is located [default: ./config]
   -h, --help
-          Print help information
+          Print help
   -V, --version
-          Print version information
+          Print version
 ```
 
 Run 'serve' command in release with default configuration
@@ -160,7 +161,7 @@ Run 'serve' command in release with a custom configuration via env vars
 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
+## Release build and run binary 'era' command
 
 Build in release with default configuration
 
@@ -171,60 +172,80 @@ make build
 Display the help menu
 
 ```bash
-./mithril-aggregator genesis --help
+./mithril-aggregator era --help
 ```
 
 You should see
 
 ```bash
-mithril-aggregator-genesis 
-Genesis tools
+Era tools
 
-USAGE:
-    mithril-aggregator genesis <SUBCOMMAND>
+Usage: mithril-aggregator era <COMMAND>
 
-OPTIONS:
-    -h, --help    Print help information
+Commands:
+  list               Era list command
+  generate-tx-datum  Era tx datum generate command
+  help               Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help  Print help
+```
+
+Run 'era list' to list the supported eras embedded in the binary
+
+```bash
+./mithril-aggregator era list
+```
 
-SUBCOMMANDS:
-    bootstrap    Genesis certificate bootstrap command
-    export       Genesis certificate export command
-    help         Print this message or the help of the given subcommand(s)
-    import       Genesis certificate import command
+You should see something like
 
+```bash
+Supported Eras:
+[
+    Thales,
+]
 ```
 
-Run 'genesis bootstrap' command in release with default configuration, **only in test mode**.
-This allows the Mithril Aggregator node to bootstrap a `Genesis Certificate`. After this operation, the Mithril Aggregator will be able to produce new snapshots and certificates.
+:::tip
+
+You can use the `--json` option in order to display results in `JSON` format for the `list` command:
 
 ```bash
-./mithril-aggregator genesis bootstrap
+./mithril-aggregator era list --json
 ```
 
-Or with a specific `Genesis Secret Key`, **only in test mode**.
+You should see something like
 
 ```bash
-./mithril-aggregator genesis bootstrap --genesis-secret-key **YOUR_SECRET_KEY**
+["thales"]
 ```
 
-Run 'genesis export' command in release with default configuration.
-This allows the Mithril Aggregator node to export the `Genesis Payload` that needs to be signed (and later reimported) of the `Genesis Certificate`. The signature of the `Genesis Payload` must be done manually with the owner of the `Genesis Secret Key`.
+:::
+
+Run 'era generate-tx-datum' to generate the transaction datum file to be stored on the Cardano chain that will provide era markers to the 'cardano-chain' era reader adapter
+
+**Case 1**: There is only one supported era in the code, create the datum file with
 
 ```bash
-./mithril-aggregator genesis export --target-path **YOUR_TARGET_PATH**
+./mithril-aggregator era generate-tx-datum --current-era-epoch **EPOCH_AT_WHICH_CURRENT_ERA_STARTS** --era-markers-secret-key **YOUR_ERA_ACTIVATION_SECRET_KEY**
 ```
 
-Run 'genesis import' command in release with default configuration.
-This allows the Mithril Aggregator node to import the signed payload of the `Genesis Certificate` and create it in the store. After this operation, the Mithril Aggregator will be able to produce new snapshots and certificates.
+You should see something like
 
 ```bash
-./mithril-aggregator genesis import --signed-payload-path **YOUR_SIGNED_PAYLOAD_PATH**
+{"constructor":0,"fields":[{"bytes":"5b7b226e223a227468616c6573222c2265223a317d5d"},{"bytes":"a58fe8e336f465ded3bba7c5a7afe5b5a26f2fb65b7c4e6e742e680645f13df28bf2b63a61cc72d9c826be490e2c1f1098d955df503580a4e899b5173884e30e"}]}
 ```
 
-Run 'genesis import' command in release with a custom configuration via env vars
+**Case 2**: There are two supported era in the code, in order to announce the upcoming era (i.e. the activation epoch of this era is not known yet), run the command
 
 ```bash
-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**
+./mithril-aggregator era generate-tx-datum --current-era-epoch **EPOCH_AT_WHICH_CURRENT_ERA_STARTS** --era-markers-secret-key **YOUR_ERA_ACTIVATION_SECRET_KEY**
+```
+
+**Case 3**: There are two supported era in the code, in order to activate the era switch at a following epoch (i.e. the activation epoch of this era known), run the command
+
+```bash
+./mithril-aggregator era generate-tx-datum --current-era-epoch **EPOCH_AT_WHICH_CURRENT_ERA_STARTS** --next-era-epoch **EPOCH_AT_WHICH_NEXT_ERA_STARTS** --era-markers-secret-key **YOUR_ERA_ACTIVATION_SECRET_KEY**
 ```
 
 :::tip
@@ -238,6 +259,7 @@ If you want to dig deeper, you can get access to several level of logs from the
 
 :::
 
+
 <CompiledBinaries />
 
 ## Build and run Docker container
@@ -265,6 +287,8 @@ Here are the subcommands available:
 | **genesis export** | Export genesis payload to sign with genesis secret key |
 | **genesis import** | Import genesis signature (payload signed with genesis secret key) and create & import a genesis certificate in the store |
 | **genesis bootstrap** | Bootstrap a genesis certificate (test only usage) |
+| **era list** | List the supported eras |
+| **era generate-tx-datum** | Generate era markers transaction datum to be stored on chain |
 
 ## Configuration parameters
 
@@ -304,6 +328,8 @@ General parameters:
 | `snapshot_bucket_name` | - | - | `SNAPSHOT_BUCKET_NAME` | Name of the bucket where the snapshots are stored  | - | `snapshot-bucket` | :heavy_check_mark: | Required if `snapshot_uploader_type` is `gcp`
 | `run_interval` | - | - | `RUN_INTERVAL` | Interval between two runtime cycles in ms | - | `60000` | :heavy_check_mark: |
 | `url_snapshot_manifest` | - | - | `URL_SNAPSHOT_MANIFEST` | Snapshots manifest location | - | Only if `snapshot_store_type` is `gcp`, else it should be `` | :heavy_check_mark: |
+| `era_reader_adapter_type` | `--era-reader-adapter-type` | - | `ERA_READER_ADAPTER_TYPE` | Era reader adapter type that can be `cardano-chain`, `file` or `bootstrap`. | `bootstrap` | - | - |
+| `era_reader_adapter_params` | `--era-reader-adapter-params` | - | `ERA_READER_ADAPTER_PARAMS` | Era reader adapter params that is an optional JSON encoded parameters structure that is expected depending on the `era_reader_adapter_type` parameter | - | - | - |
 
 `genesis bootstrap` command:
 
@@ -315,10 +341,24 @@ General parameters:
 
 | Parameter | Command Line (long) |  Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
-| `signed-payload-path` | `--signed-payload-path` | - | - | Path of the payload to import. | - | - | - | - |
+| `signed_payload_path` | `--signed-payload-path` | - | - | Path of the payload to import. | - | - | - | - |
 
 `genesis export` command:
 
 | Parameter | Command Line (long) |  Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
-| `target-path` | `--target-path` | - | - | Path of the file to export the payload to. | - | - | - | - |
+| `target_path` | `--target-path` | - | - | Path of the file to export the payload to. | - | - | - | - |
+
+`era list` command:
+
+| Parameter | Command Line (long) |  Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
+|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
+| `json` | `--json` | - | - | Export the supported era list to JSON format. | - | - | - | - |
+
+`era generate-tx-datum` command:
+
+| Parameter | Command Line (long) |  Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
+|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
+| `current_era_epoch` | `--current-era-epoch` | - | `CURRENT_ERA_EPOCH` | Epoch at which current era starts. | - | - | - | :heavy_check_mark: |
+| `next_era_epoch` | `--next-era-epoch` | - | `NEXT_ERA_EPOCH` | Epoch at which the next era starts. If not specified and an upcoming era is available, it will announce the next era. If specified, it must be strictly greater than `current-epoch-era` | - | - | - | - |
+| `era_markers_secret_key` | `--era-markers-secret-key` | - | `ERA_MARKERS_SECRET_KEY` | Era Markers Secret Key that is used to verify the authenticity of the era markers on chain. | - | - | - | :heavy_check_mark: |

docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md

@@ -209,3 +209,5 @@ Here is a list of the available parameters:
 | `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) | - | - | - |
 | `operational_certificate_path` | - | - | `OPERATIONAL_CERTIFICATE_PATH` | Path to the `Cardano Operational Certificate` file. Mandatory in `Pool Id Certification Mode` where the owner is verified (experimental, soon to be stable & preferred mode) | - | - | - |
+| `era_reader_adapter_type` | `--era-reader-adapter-type` | - | `ERA_READER_ADAPTER_TYPE` | Era reader adapter type that can be `cardano-chain`, `file` or `bootstrap`. | `bootstrap` | - | - |
+| `era_reader_adapter_params` | `--era-reader-adapter-params` | - | `ERA_READER_ADAPTER_PARAMS` | Era reader adapter params that is an optional JSON encoded parameters structure that is expected depending on the `era_reader_adapter_type` parameter | - | - | - |

docs/versioned_docs/version-maintained/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 `3.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.40`. Run `sqlite3 --version` to check your version.
 
 ## Download source
 

docs/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md

@@ -51,6 +51,8 @@ For more information about the **Mithril Protocol**, please refer to the [About
 
 * Ensure the SQLite3 version is at least `3.35` (released Apr. 2021)
 
+* Install a recent version of `jq` (version `1.6+`) `apt install jq`
+
 ## Mithril Keys Certification
 
 
@@ -195,7 +197,8 @@ Replace this value with the correct user. We assume that the user used to run th
   * `CARDANO_CLI_PATH=/app/bin/cardano-cli`: replace with the path to the `cardano-cli` executable
   * `DATA_STORES_DIRECTORY=/opt/mithril/stores`: replace with the path to a folder where the **Mithril Signer** will store its data (`/opt/mithril/stores` e.g.)
   * `STORE_RETENTION_LIMIT`: if set, this will limit the number of records in some internal stores (5 is a good fit).
-
+  * `ERA_READER_ADAPTER_TYPE=cardano-chain`: replace `cardano-chain` with the era reader adapter type used in your Mithril network
+  * `ERA_READER_ADAPTER_PARAMS={"address": "...", "verification_key": "..."}`: replace `{"address": "...", "verification_key": "..."}` with the era reader params that you need to compute by running the command `jq -nc --arg address $(wget -q -O - **YOUR_ERA_READER_ADDRESS**) --arg verification_key $(wget -q -O - **YOUR_ERA_READER_VERIFICATION_KEY**) '{"address": $address, "verification_key": $verification_key}'`
 :::
 
 First create an env file that will be used by the service:
@@ -212,6 +215,8 @@ CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket
 CARDANO_CLI_PATH=/app/bin/cardano-cli
 DATA_STORES_DIRECTORY=/opt/mithril/stores
 STORE_RETENTION_LIMIT=5
+ERA_READER_ADAPTER_TYPE=**YOUR_ERA_READER_ADAPTER_TYPE**
+ERA_READER_ADAPTER_PARAMS=**YOUR_ERA_READER_ADAPTER_PARAMS**
 EOF'
 ```