Skip to content

Rotate documentation #1527

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 26, 2024
Merged

Rotate documentation #1527

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/website/versioned_docs/version-maintained/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
31 changes: 31 additions & 0 deletions ...s/version-maintained/manual/developer-docs/nodes/mithril-client-library-wasm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

:::
Expand Down Expand Up @@ -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).
Expand Down
73 changes: 59 additions & 14 deletions ...versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -29,7 +31,6 @@ Mithril client is responsible for restoring the **Cardano** blockchain on an emp

:::


## Resources

| Node | Source repository | Rust documentation | Docker packages |
Expand All @@ -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`

Expand All @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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:
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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: |
Expand Down Expand Up @@ -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 | - | - | - |
8 changes: 4 additions & 4 deletions ...rsioned_docs/version-maintained/manual/getting-started/SPO-on-boarding-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

:::

Expand Down