Merge pull request #1930 from input-output-hk/jpraynaud/1901-rotate-doc-distribution-2437

Docs: rotate documentation for `2437` distribution

Author: jpraynaud

docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library-wasm.md

@@ -15,7 +15,8 @@ It is responsible for handling the different types of data certified by Mithril,
 
 - [**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 snapshots, get proofs
+- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs.
+- [**Cardano stake distribution**](../../../glossary.md#stake-distribution): list, get and get by epoch.
 - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
 
 :::
@@ -93,10 +94,11 @@ broadcast_channel.onmessage = (e) => {
 
 await initMithrilClient();
 
-let client = await new MithrilClient(
-  aggregator_endpoint,
-  genesis_verification_key,
-);
+let client = new MithrilClient(aggregator_endpoint, genesis_verification_key, {
+  // The following option activates the unstable features of the client.
+  // Unstable features will trigger an error if this option is not set.
+  unstable: true,
+});
 let mithril_stake_distributions_list =
   await client.list_mithril_stake_distributions();
 console.log("stake distributions:", mithril_stake_distributions_list);
@@ -145,6 +147,28 @@ console.log(
 );
 ```
 
+:::tip Adding Custom HTTP Headers
+
+You can customize the HTTP headers sent by the Mithril client. This is particularly useful in scenarios where the Mithril client is used with a proxy, as it allows you to include headers like **Authorization** or custom headers for specific use cases. Below is an example of how to set custom headers:
+
+```js
+let http_headers_map = new Map();
+http_headers_map.set("Authorization", "Bearer YourBearerToken");
+http_headers_map.set("X-Custom-Header", "YourCustomHeaderValue");
+
+let client_options = {
+  http_headers: http_headers_map,
+};
+
+let client = new MithrilClient(
+  aggregator_endpoint,
+  genesis_verification_key,
+  client_options,
+);
+```
+
+:::
+
 If the aggregator signs **CardanoTransactions**, you can add the code below to the previous example:
 
 :::tip
@@ -155,16 +179,16 @@ You can verify that the aggregator signs **CardanoTransactions** by running the
 wget -q -O - YOUR_AGGREGATOR_ENDPOINT | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])'
 ```
 
-For example with the aggregator on `testing-sanchonet` Mithril network:
+For example with the aggregator on `pre-release-preview` Mithril network:
 
 ```bash
-wget -q -O - https://aggregator.testing-sanchonet.api.mithril.network/aggregator | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])'
+wget -q -O - https://aggregator.pre-release-preview.api.mithril.network/aggregator | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])'
 ```
 
 :::
 
 ```js
-const proof = await client.unstable.get_cardano_transaction_proofs([
+const proof = await client.get_cardano_transaction_proofs([
   "CARDANO_TRANSACTION_HASH_1",
   "CARDANO_TRANSACTION_HASH_2",
 ]);
@@ -180,7 +204,7 @@ console.log(
 );
 
 let valid_cardano_transaction_proof =
-  await client.unstable.verify_cardano_transaction_proof_then_compute_message(
+  await client.verify_cardano_transaction_proof_then_compute_message(
     proof,
     proof_certificate,
   );
@@ -190,8 +214,68 @@ console.log(
 );
 ```
 
+With the same logic as above, if the aggregator signs **CardanoStakeDistribution**, you can add the code below to the previous example:
+
 :::tip
 
-You can read the complete [Rust developer documentation](https://mithril.network/rust-doc/mithril_client_wasm/index.html).
+You can verify that the aggregator signs **CardanoStakeDistribution** by running the command below:
+
+```bash
+wget -q -O - YOUR_AGGREGATOR_ENDPOINT | jq '.capabilities.signed_entity_types | contains(["CardanoStakeDistribution"])'
+```
+
+For example with the aggregator on `testing-preview` Mithril network:
+
+```bash
+wget -q -O - https://aggregator.testing-preview.api.mithril.network/aggregator | jq '.capabilities.signed_entity_types | contains(["CardanoStakeDistribution"])'
+```
 
 :::
+
+```js
+let cardano_stake_distributions_list =
+  await client.list_cardano_stake_distributions();
+console.log("cardano stake distributions:", cardano_stake_distributions_list);
+
+let last_cardano_stake_distribution =
+  await client.get_cardano_stake_distribution(
+    cardano_stake_distributions_list[0].hash,
+  );
+console.log(
+  "last_cardano_stake_distribution:",
+  last_cardano_stake_distribution,
+);
+
+let certificate = await client.get_mithril_certificate(
+  last_cardano_stake_distribution.certificate_hash,
+);
+console.log("certificate:", certificate);
+
+let last_certificate_from_chain = await client.verify_certificate_chain(
+  certificate.hash,
+);
+console.log(
+  "verify certificate chain OK, last_certificate_from_chain:",
+  last_certificate_from_chain,
+);
+
+let cardano_stake_distribution_message =
+  await client.compute_cardano_stake_distribution_message(
+    certificate,
+    last_cardano_stake_distribution,
+  );
+console.log(
+  "cardano_stake_distribution_message:",
+  cardano_stake_distribution_message,
+);
+
+let valid_cardano_stake_distribution_message =
+  await client.verify_message_match_certificate(
+    cardano_stake_distribution_message,
+    last_certificate_from_chain,
+  );
+console.log(
+  "valid_cardano_stake_distribution_message:",
+  valid_cardano_stake_distribution_message,
+);
+```

docs/website/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client-library.md

@@ -15,6 +15,8 @@ It is responsible for handling the different types of data certified by Mithril,
 
 - [**Snapshot**](../../../glossary.md#snapshot): list, get, download tarball and record statistics.
 - [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get.
+- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs.
+- [**Cardano stake distribution**](../../../glossary.md#stake-distribution): list, get and get by epoch.
 - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
 
 :::

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

@@ -131,6 +131,7 @@ Commands:
   cardano-db                  Cardano db management (alias: cdb)
   mithril-stake-distribution  Mithril Stake Distribution management (alias: msd)
   cardano-transaction         [unstable] Cardano transactions management (alias: ctx)
+  cardano-stake-distribution  [unstable] Cardano stake distribution management (alias: csd)
   help                        Print this message or the help of the given subcommand(s)
 
 Options:
@@ -259,6 +260,12 @@ mithril_client --unstable cardano-transaction snapshot show $CARDANO_TRANSACTION
 
 # 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
+
+# 10- List Cardano stake distributions
+mithril_client --unstable cardano-stake-distribution list
+
+# 11 - Download and verify the given Cardano stake distribution from its hash or epoch
+mithril_client --unstable cardano-stake-distribution download $UNIQUE_IDENTIFIER
 ```
 
 ### Local image
@@ -305,6 +312,14 @@ Here are the subcommands available:
 | **snapshot show** | Shows information about a Cardano transactions snapshot                                       |
 | **help**          | Prints this message or the help for the given subcommand(s)                                   |
 
+### Cardano stake distribution
+
+| Subcommand   | Performed action                                            |
+| ------------ | ----------------------------------------------------------- |
+| **download** | Downloads and verifies Cardano stake distribution           |
+| **help**     | Prints this message or the help for the given subcommand(s) |
+| **list**     | Lists available Cardano stake distributions                 |
+
 ## Configuration parameters
 
 The configuration parameters can be set in either of the following ways:
@@ -379,3 +394,16 @@ Here is a list of the available parameters:
 | --------------------- | ----------------------- | :------------------: | --------------------- | ----------------------------------------------- | ------------- | ------- | :----------------: |
 | `transactions_hashes` | `--transactions_hashes` |          -           | `TRANSACTIONS_HASHES` | Cardano transactions hashes separated by commas | -             | -       | :heavy_check_mark: |
 | `json`                | `--json`                |          -           | -                     | Enable JSON output for progress logs            | -             | -       |         -          |
+
+`cardano-stake-distribution 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-stake-distribution download` command:
+
+| Parameter           | Command line (long)   | Command line (short) | Environment variable | Description                                                                                  | Default value | Example |     Mandatory      |
+| ------------------- | --------------------- | :------------------: | -------------------- | -------------------------------------------------------------------------------------------- | ------------- | ------- | :----------------: |
+| `unique_identifier` | `--unique-identifier` |          -           | -                    | Epoch or hash of the Cardano stake distribution artifact or `latest` for the latest artifact | -             | -       | :heavy_check_mark: |
+| `download_dir`      | `--download-dir`      |          -           | -                    | Directory where the Cardano stake distribution will be downloaded                            | .             | -       |         -          |