diff --git a/.github/workflows/actions/build-upload-mithril-artifact/action.yml b/.github/workflows/actions/build-upload-mithril-artifact/action.yml
index 75d770db00e..87b5764b54c 100644
--- a/.github/workflows/actions/build-upload-mithril-artifact/action.yml
+++ b/.github/workflows/actions/build-upload-mithril-artifact/action.yml
@@ -25,7 +25,7 @@ runs:
with:
name: mithril-distribution-${{ runner.os }}-${{ runner.arch }}
path: |
- target/release/libmithril.*
+ target/release/libmithril_stm.*
target/release/libmithril_common.*
target/release/mithril-aggregator
target/release/mithril-aggregator.exe
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e7309d00482..accd8667409 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,14 +1,17 @@
name: CI
on:
- push:
- branches: # only run on branch push, tag push will be ignored
- - '**'
+ pull_request:
+ types: [opened, reopened, synchronize, closed]
paths-ignore: # ignore docs only changes since they use a dedicated workflows: docs.yml
- 'docs/**'
- 'mithril-explorer/**'
- '.github/workflows/docs.yml'
+concurrency:
+ group: ci-build-test-${{ github.ref }}
+ cancel-in-progress: true
+
jobs:
build-ubuntu-X64:
runs-on: ubuntu-22.04
@@ -245,12 +248,11 @@ jobs:
packages: write
env:
- PUSH_PACKAGES: ${{ github.ref == 'refs/heads/main' || startsWith('refs/heads/hotfix', github.ref) }}
+ PUSH_PACKAGES: ${{ github.event.action == 'closed' && github.event.pull_request.merged == true && (github.base_ref == 'main' || startsWith('hotfix', github.base_ref)) }}
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository_owner }}/${{ matrix.project }}
DOCKER_FILE: ./${{ matrix.project }}/Dockerfile.ci
CONTEXT: .
- GITHUB_REF: ${{ github.ref}}
steps:
- name: Checkout
@@ -270,7 +272,7 @@ jobs:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
unstable
- type=raw,value={{branch}}-{{sha}}
+ type=raw,value=${{ github.base_ref }}-{{sha}}
- name: Download built artifacts
uses: actions/download-artifact@v3
@@ -287,7 +289,7 @@ jobs:
tags: ${{ steps.meta.outputs.tags }}
unstable-release:
- if: github.ref == 'refs/heads/main' || startsWith('refs/heads/hotfix', github.ref)
+ if: github.event.action == 'closed' && github.event.pull_request.merged == true && (github.base_ref == 'main' || startsWith('hotfix', github.base_ref))
runs-on: ubuntu-22.04
needs:
- build
@@ -374,9 +376,9 @@ jobs:
mithril_api_domain: api.mithril.network
mithril_protocol_parameters: |
{
- k = 5
- m = 100
- phi_f = 0.65
+ k = 2422
+ m = 20973
+ phi_f = 0.2
}
mithril_signers: |
{
@@ -412,7 +414,7 @@ jobs:
uses: actions/checkout@v3
- name: Get Docker image id
- run: echo "DOCKER_IMAGE_ID=${{ github.head_ref || github.ref_name }}-$(echo ${{ github.sha }} | cut -c1-7)" >> $GITHUB_ENV
+ run: echo "DOCKER_IMAGE_ID=${{ github.base_ref }}-$(echo ${{ github.sha }} | cut -c1-7)" >> $GITHUB_ENV
- name: Prepare service account credentials
run: |
@@ -456,7 +458,7 @@ jobs:
GOOGLE_APPLICATION_CREDENTIALS=./google-application-credentials.json terraform plan --var-file=./env.variables.tfvars
- name: Terraform Apply
- if: github.ref == 'refs/heads/main'
+ if: github.event.action == 'closed' && github.event.pull_request.merged == true && github.base_ref == 'main'
run: |
GOOGLE_APPLICATION_CREDENTIALS=./google-application-credentials.json terraform apply -auto-approve --var-file=./env.variables.tfvars
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 6af35a9e5db..5290730c98b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,9 +1,12 @@
name: Documentations & Explorer
on:
- push:
- branches: # only run on branch push, tag push will be ignored
- - '**'
+ pull_request:
+ types: [opened, reopened, synchronize, closed]
+
+concurrency:
+ group: ci-docs-${{ github.ref }}
+ cancel-in-progress: true
jobs:
cargo-doc:
@@ -21,7 +24,7 @@ jobs:
uses: actions-rs/cargo@v1
with:
command: doc
- args: --no-deps -p mithril -p mithril-common -p mithril-aggregator -p mithril-signer -p mithril-client
+ args: --no-deps -p mithril-stm -p mithril-common -p mithril-aggregator -p mithril-signer -p mithril-client
- name: Publish Mithril-rust-doc
uses: actions/upload-artifact@v3
@@ -113,7 +116,7 @@ jobs:
out/*
publish-docs:
- if: github.ref == 'refs/heads/main'
+ if: github.event.action == 'closed' && github.event.pull_request.merged == true && github.base_ref == 'main'
runs-on: ubuntu-22.04
needs:
- cargo-doc
diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml
index 82dab4c4c0c..ad3f27d8f48 100644
--- a/.github/workflows/pre-release.yml
+++ b/.github/workflows/pre-release.yml
@@ -89,6 +89,29 @@ jobs:
title: Mithril v${{ github.ref_name }}
files: package/*
+ - name: Prepare crates versions table
+ run: |
+ cat > ./versions-manifest.txt << EOF
+
+ ## Crates Versions
+ | Crate | Version |
+ |---------- |-------------|
+ EOF
+
+ cargo metadata --quiet --no-deps | \
+ jq -r '.packages | sort_by(.name) | .[] | select([.name] | inside(["mithrildemo", "mithril-end-to-end"]) | not) | "| \(.name) | `\(.version)` |"' \
+ >> ./versions-manifest.txt
+
+ - name: Update release body with crates versions table
+ id: update_release
+ uses: tubone24/update_release@v1.3.1
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ TAG_NAME: ${{ github.ref_name }}
+ with:
+ is_append_body: true
+ body_path: ./versions-manifest.txt
+
build-push-docker:
runs-on: ubuntu-22.04
strategy:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0e5f0271be7..e688810c254 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -60,6 +60,63 @@ jobs:
push: true
tags: ${{ steps.meta.outputs.tags }}
+ check-deploy-crates-io:
+ runs-on: ubuntu-22.04
+ outputs:
+ should-deploy: ${{ steps.check_version.outputs.should_deploy }}
+ steps:
+ - name: Checkout sources
+ uses: actions/checkout@v3
+
+ - name: Check crate latest version
+ id: check_version
+ run: |
+ LATEST_REMOTE_VERSION=$(wget -q -O - https://crates.io/api/v1/crates/mithril-stm | jq -r '.crate.newest_version')
+ LOCAL_VERSION=$(cargo metadata --quiet --no-deps | jq -r '.packages[] | select(.name=="mithril-stm") | .version')
+ echo "Latest crate.io version: $LATEST_REMOTE_VERSION"
+ echo "Local version: $LOCAL_VERSION"
+
+ if [ "$LOCAL_VERSION" != "$LATEST_REMOTE_VERSION" ]; then
+ echo "Local version is newer than remote version: we will publish to crates.io"
+ echo "should_deploy=true" >> $GITHUB_OUTPUT
+ else
+ echo "Local version and remote version are the same: no need to publish to crates.io"
+ echo "should_deploy=false" >> $GITHUB_OUTPUT
+ fi
+
+ deploy-crates-io:
+ runs-on: ubuntu-22.04
+ needs: check-deploy-crates-io
+ if: needs.check-deploy-crates-io.outputs.should-deploy == 'true'
+ steps:
+ - name: Checkout sources
+ uses: actions/checkout@v3
+
+ - name: Install stable toolchain
+ uses: actions-rs/toolchain@v1
+ with:
+ profile: minimal
+ toolchain: stable
+
+ - name: Cargo publish dry run
+ uses: actions-rs/cargo@v1
+ with:
+ command: publish
+ args: -p mithril-stm --dry-run
+
+ - name: Cargo package list
+ uses: actions-rs/cargo@v1
+ with:
+ command: package
+ args: -p mithril-stm --list
+
+ # We use the '--dry-run' arg until we have a valid CRATES_IO_API_TOKEN to avoid the workflow to crash
+ - name: Cargo publish
+ uses: actions-rs/cargo@v1
+ with:
+ command: publish
+ args: -p mithril-stm --token ${{ secrets.CRATES_IO_API_TOKEN }} --dry-run
+
deploy-release:
strategy:
fail-fast: false
diff --git a/.github/workflows/scripts/edit-cargo-toml-version.py b/.github/workflows/scripts/edit-cargo-toml-version.py
index 935b6acf35e..bce5ab13016 100644
--- a/.github/workflows/scripts/edit-cargo-toml-version.py
+++ b/.github/workflows/scripts/edit-cargo-toml-version.py
@@ -20,7 +20,7 @@ def append_label_to_cargo_toml_version(cargo_toml_path, label: str, dry_run: boo
print("No package section (probably a workspace file), skipping this Cargo.toml")
return
- new_version = f"{cargo_toml['package']['version'].split('-', 1)[0]}-{label}"
+ new_version = f"{cargo_toml['package']['version'].split('+', 1)[0]}+{label}"
print(f"{cargo_toml_path} new version: {new_version}")
if not dry_run:
diff --git a/.gitignore b/.gitignore
index c343e76428f..2685dee72eb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,10 +1,10 @@
mithril.cabal
.stack-work/
.direnv/
-mithril-core/c-tests/tests
-mithril-core/c-tests/tests.dSYM/
+mithril-stm/c-tests/tests
+mithril-stm/c-tests/tests.dSYM/
*~
-mithril-core/proptest-regressions/
+mithril-stm/proptest-regressions/
*.dump
.tmp/
.s.PGSQL*
diff --git a/Cargo.lock b/Cargo.lock
index f25c1a677c4..865e8a2d826 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1933,28 +1933,6 @@ dependencies = [
"windows-sys 0.42.0",
]
-[[package]]
-name = "mithril"
-version = "0.1.0"
-dependencies = [
- "bincode",
- "blake2 0.10.5",
- "blst",
- "criterion",
- "digest 0.10.6",
- "hex",
- "num-bigint 0.4.3",
- "num-rational",
- "num-traits",
- "proptest",
- "rand_chacha 0.3.1",
- "rand_core 0.6.4",
- "rayon",
- "rug",
- "serde",
- "thiserror",
-]
-
[[package]]
name = "mithril-aggregator"
version = "0.1.2"
@@ -2028,7 +2006,7 @@ dependencies = [
"http",
"jsonschema",
"kes-summed-ed25519",
- "mithril",
+ "mithril-stm",
"mockall",
"nom",
"rand_chacha 0.2.2",
@@ -2097,6 +2075,28 @@ dependencies = [
"tokio",
]
+[[package]]
+name = "mithril-stm"
+version = "0.1.0"
+dependencies = [
+ "bincode",
+ "blake2 0.10.5",
+ "blst",
+ "criterion",
+ "digest 0.10.6",
+ "hex",
+ "num-bigint 0.4.3",
+ "num-rational",
+ "num-traits",
+ "proptest",
+ "rand_chacha 0.3.1",
+ "rand_core 0.6.4",
+ "rayon",
+ "rug",
+ "serde",
+ "thiserror",
+]
+
[[package]]
name = "mithrildemo"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 54c8694b9b3..4984864dd85 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -7,8 +7,8 @@ members = [
"mithril-aggregator",
"mithril-client",
"mithril-common",
- "mithril-core",
"mithril-signer",
+ "mithril-stm",
"mithril-test-lab/mithril-end-to-end"
]
diff --git a/Makefile b/Makefile
index aff05ac8352..e743a27e12b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-COMPONENTS = mithril-common mithril-core mithril-aggregator mithril-client mithril-signer demo/protocol-demo mithril-test-lab
+COMPONENTS = mithril-common mithril-stm mithril-aggregator mithril-client mithril-signer demo/protocol-demo mithril-test-lab
GOALS := $(or $(MAKECMDGOALS),all)
.PHONY: $(GOALS) $(COMPONENTS)
diff --git a/README.md b/README.md
index 6b79e69c4ff..3c3683947b9 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ This repository is sliced in the following parts:
* [**Mithril Common**](./mithril-common): this is the **common** library that is used by the **Mithril Network** nodes.
-* [**Mithril Core**](./mithril-core): the **core** library that implements **Mithril** protocol cryptographic engine.
+* [**Mithril STM**](./mithril-stm): the **core** library that implements **Mithril** protocol cryptographic engine.
* [**Mithril Explorer**](./mithril-explorer): the **explorer** website that connects to a **Mithril Aggregator** and displays its **Certificate Chain**.
diff --git a/docs/Makefile b/docs/Makefile
index cc41be4541b..b96c3fe57a0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -20,4 +20,14 @@ clean:
rm yarn.lock || true
upgrade: clean install
- yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest redocusaurus@latest
\ No newline at end of file
+ yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest redocusaurus@latest
+
+update-current:
+ # Use docusaurus command to create a new version using a temporary name
+ yarn run docusaurus docs:version updated
+ # cleanup previous file & replace it with the updated ones
+ rm -rf versioned_docs/version-maintained versioned_sidebars/version-maintained-sidebars.json
+ mv versioned_docs/version-updated versioned_docs/version-maintained
+ mv versioned_sidebars/version-updated-sidebars.json versioned_sidebars/version-maintained-sidebars.json
+ # Remove the entry for the temporary version in the versions.json file
+ sed -i '/updated/d' versions.json
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
index e6986ad9a75..11d761013cd 100644
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -33,7 +33,21 @@ const config = {
path: 'root',
routeBasePath: '/',
sidebarPath: require.resolve('./sidebars.js'),
- editUrl: 'https://github.com/input-output-hk/mithril/edit/main/docs',
+ editUrl: ({docPath}) => {
+ // We want users to submit doc updates to the upstream/next version!
+ // Otherwise we risk losing the update on the next release.
+ return `https://github.com/input-output-hk/mithril/edit/main/docs/root/${docPath}`;
+ },
+ lastVersion: 'maintained',
+ versions: {
+ current: {
+ label: 'Next 🚧',
+ banner: 'unreleased',
+ },
+ maintained: {
+ label: 'Current',
+ }
+ },
},
blog: {
path: 'blog/',
@@ -113,6 +127,11 @@ const config = {
label: 'About Mithril',
position: 'left',
},
+ {
+ type: 'docsVersionDropdown',
+ position: 'right',
+ dropdownActiveClassDisabled: true,
+ },
{
label: 'Explorer',
to: 'https://mithril.network/explorer',
diff --git a/docs/root/manual/developer-docs/nodes/mithril-aggregator.md b/docs/root/manual/developer-docs/nodes/mithril-aggregator.md
index 9556d758efc..2598bf047ac 100644
--- a/docs/root/manual/developer-docs/nodes/mithril-aggregator.md
+++ b/docs/root/manual/developer-docs/nodes/mithril-aggregator.md
@@ -2,7 +2,7 @@
sidebar_position: 1
---
-import NetworksMatrix from '../../../../shared/networks-matrix.md';
+import NetworksMatrix from '../../../networks-matrix.md';
# Mithril Aggregator Node
diff --git a/docs/root/manual/developer-docs/nodes/mithril-client.md b/docs/root/manual/developer-docs/nodes/mithril-client.md
index 448015b114e..8135f8bf1f3 100644
--- a/docs/root/manual/developer-docs/nodes/mithril-client.md
+++ b/docs/root/manual/developer-docs/nodes/mithril-client.md
@@ -2,7 +2,7 @@
sidebar_position: 3
---
-import NetworksMatrix from '../../../../shared/networks-matrix.md';
+import NetworksMatrix from '../../../networks-matrix.md';
# Mithril Client Node
diff --git a/docs/root/manual/developer-docs/nodes/mithril-signer.md b/docs/root/manual/developer-docs/nodes/mithril-signer.md
index 8c725941965..5bf7c51052e 100644
--- a/docs/root/manual/developer-docs/nodes/mithril-signer.md
+++ b/docs/root/manual/developer-docs/nodes/mithril-signer.md
@@ -2,7 +2,7 @@
sidebar_position: 2
---
-import NetworksMatrix from '../../../../shared/networks-matrix.md';
+import NetworksMatrix from '../../../networks-matrix.md';
# Mithril Signer Node
diff --git a/docs/root/manual/developer-docs/references.md b/docs/root/manual/developer-docs/references.md
index 46ae5d0e513..03fbf6fe612 100644
--- a/docs/root/manual/developer-docs/references.md
+++ b/docs/root/manual/developer-docs/references.md
@@ -2,7 +2,7 @@
sidebar_position: 2
---
-import NetworksMatrix from '../../../shared/networks-matrix.md';
+import NetworksMatrix from '../../networks-matrix.md';
# API Reference
@@ -29,7 +29,7 @@ For more information about the **Mithril Protocol**, please refer to the [About
| Dependency | Description | Source Repository | Rust Documentation | REST API
|------------|-------------|:-----------------:|:------------------:|:------------:|
| **Mithril Common** | This is the **common** library that is used by the **Mithril Network** nodes. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-common) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_common/index.html) | -
-| **Mithril Core** | The **core** library that implements **Mithril** protocol cryptographic engine. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-core) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril/index.html) | -
+| **Mithril STM** | The **core** library that implements **Mithril** protocol cryptographic engine. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-stm) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_stm/index.html) | -
| **Mithril Aggregator** | The node of the **Mithril Network** responsible for collecting individual signatures from the **Mithril Signers** and aggregate them into a multisignature. The **Mithril Aggregator** uses this ability to provide certified snapshots of the **Cardano** blockchain. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-aggregator) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_aggregator/index.html) | [:arrow_upper_right:](/aggregator-api)
| **Mithril Client** | The node of the **Mithril Network** responsible for restoring the **Cardano** blockchain on an empty node from a certified snapshot. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_client/index.html) | -
| **Mithril Signer** | The node of the **Mithril Network** responsible for producing individual signatures that are collected and aggregated by the **Mithril Aggregator**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-signer) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_signer/index.html) | -
diff --git a/docs/root/manual/getting-started/bootstrap-cardano-node.md b/docs/root/manual/getting-started/bootstrap-cardano-node.md
index 71c7dddf470..f424b6114ab 100644
--- a/docs/root/manual/getting-started/bootstrap-cardano-node.md
+++ b/docs/root/manual/getting-started/bootstrap-cardano-node.md
@@ -2,7 +2,7 @@
sidebar_position: 1
---
-import NetworksMatrix from '../../../shared/networks-matrix.md';
+import NetworksMatrix from '../../networks-matrix.md';
# Bootstrap a Cardano Node
@@ -18,6 +18,13 @@ Thanks to a **Mithril Client** connected to a **Mithril Aggregator**, you will r
:::
+# Video demonstration
+
+In this video you will see how fast the bootstrapping of a Cardano node with Mithril is compared to classical bootstrapping (benchmark done on mainnet with Daedalus wallet).
+
+
+
+
## Pre-requisites
* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
diff --git a/docs/root/manual/getting-started/run-signer-node.md b/docs/root/manual/getting-started/run-signer-node.md
index fd8aa9cef55..422e8977ee6 100644
--- a/docs/root/manual/getting-started/run-signer-node.md
+++ b/docs/root/manual/getting-started/run-signer-node.md
@@ -2,7 +2,7 @@
sidebar_position: 2
---
-import NetworksMatrix from '../../../shared/networks-matrix.md';
+import NetworksMatrix from '../../networks-matrix.md';
# Run a Mithril Signer node (SPO)
@@ -35,10 +35,10 @@ For more information about the **Mithril Protocol**, please refer to the [About
## What you'll need
* Operating a **Cardano Node** as a **Stake Pool**:
- * **Stable**: The Cardano `Pool Id` in a `BECH32` format such as `pool1frevxe70aqw2ce58c0muyesnahl88nfjjsp25h85jwakzgd2g2l`
- * **Experimental**:
+ * **Stable**:
* The Cardano `Operational Certificate` file of the pool
* The Cardano `KES Secret Key` file of the pool
+ * **Deprecated**: The Cardano `Pool Id` in a `BECH32` format such as `pool1frevxe70aqw2ce58c0muyesnahl88nfjjsp25h85jwakzgd2g2l`
* Access to the file system of a `relay` **Cardano Node** running on the `testnet`:
* Read rights on the `Database` folder (`--database-path` setting of the **Cardano Node**)
@@ -62,13 +62,7 @@ Your feedback is very important, so feel free to contact us on the #moria channe
:::
-### Stable mode: Declare your Pool Id
-
-In this stable mode, the Cardano `Pool Id` that you specify is not strictly verified. It is associated to Cardano stakes based on your declaration. This mode is soon to be deprecated and replaced by the certification mode below.
-
-This is the default mode presented in the setup of this document, it is displayed with a specific **Stable** mention.
-
-### Experimental mode: Certify your Pool Id
+### Stable mode: Certify your Pool Id
In this mode, you declare your Cardano `Operational Certificate` file and `KES Secret Key` file which allows to:
@@ -76,7 +70,13 @@ In this mode, you declare your Cardano `Operational Certificate` file and `KES S
* Verify that you are the owner of the `PoolId`, and thus of the associated stakes used by Mithril protocol
* Verify that you are the owner of the Mithril `Signer Secret Key`, and thus allowed to contribute to the multi-signatures and certificate production of the Mithril network
-This mode is displayed with a specific **Experimental** mention in this document.
+This mode is displayed with a specific **Stable** mention in this document.
+
+### Deprecated mode: Declare your Pool Id
+
+In this mode, the Cardano `Pool Id` that you specify is not strictly verified. It is associated to Cardano stakes based on your declaration. This mode is deprecated and replaced by the certification mode above.
+
+This mode is presented in the setup of this document with a specific **Deprecated** mention.
## Building your own executable
@@ -165,16 +165,16 @@ sudo mv mithril-signer /opt/mithril
Replace this value with the correct user. We assume that the user used to run the **Cardano Node** is `cardano`. The **Mithril Signer** must imperatively run with the same user.
* **Stable mode**: in the `/opt/mithril/mithril-signer/service.env` env file:
- * `PARTY_ID=YOUR_POOL_ID_BECH32`: replace `YOUR_POOL_ID_BECH32` with your BECH32 `Pool Id`
+ * `KES_SECRET_KEY_PATH=/cardano/keys/kes.skey`: replace `/cardano/keys/kes.skey` with the path to your Cardano `KES Secret Key` file
+ * `OPERATIONAL_CERTIFICATE_PATH=/cardano/cert/opcert.cert`: replace `/cardano/cert/opcert.cert` with the path to your Cardano `Operational Certificate` file
* `DB_DIRECTORY=/cardano/db`: replace `/cardano/db` with the path to the database folder of the **Cardano Node** (the one in `--database-path`)
* `CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket`: replace with the path to the IPC file (`CARDANO_NODE_SOCKET_PATH` env var)
* `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).
-* :boom: **Experimental mode**: in the `/opt/mithril/mithril-signer/service.env` env file:
- * `KES_SECRET_KEY_PATH=/cardano/keys/kes.skey`: replace `/cardano/keys/kes.skey` with the path to your Cardano `KES Secret Key` file
- * `OPERATIONAL_CERTIFICATE_PATH=/cardano/cert/pool.cert`: replace `/cardano/cert/pool.cert` with the path to your Cardano `Operational Certificate` file
+* **Deprecated mode**: in the `/opt/mithril/mithril-signer/service.env` env file:
+ * `PARTY_ID=YOUR_POOL_ID_BECH32`: replace `YOUR_POOL_ID_BECH32` with your BECH32 `Pool Id`
* `DB_DIRECTORY=/cardano/db`: replace `/cardano/db` with the path to the database folder of the **Cardano Node** (the one in `--database-path`)
* `CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket`: replace with the path to the IPC file (`CARDANO_NODE_SOCKET_PATH` env var)
* `CARDANO_CLI_PATH=/app/bin/cardano-cli`: replace with the path to the `cardano-cli` executable
@@ -189,7 +189,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**
+KES_SECRET_KEY_PATH=**YOUR_KES_SECRET_KEY_PATH**
+OPERATIONAL_CERTIFICATE_PATH=**YOUR_OPERATIONAL_CERTIFICATE_PATH**
NETWORK=**YOUR_CARDANO_NETWORK**
AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
RUN_INTERVAL=60000
@@ -201,12 +202,11 @@ STORE_RETENTION_LIMIT=5
EOF'
```
-* :boom: **Experimental mode**:
+* **Deprecated mode**:
```bash
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**
+PARTY_ID=**YOUR_POOL_ID_BECH32**
NETWORK=**YOUR_CARDANO_NETWORK**
AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
RUN_INTERVAL=60000
diff --git a/docs/shared/networks-matrix.md b/docs/root/networks-matrix.md
similarity index 97%
rename from docs/shared/networks-matrix.md
rename to docs/root/networks-matrix.md
index 426d7d42ab4..0f6c5debb59 100644
--- a/docs/shared/networks-matrix.md
+++ b/docs/root/networks-matrix.md
@@ -1,3 +1,9 @@
+---
+unlisted: true
+hide_title: true
+hide_table_of_contents: true
+---
+
Here is an up to date list of all the **Mithril Networks**, their configurations and their status:
> Last update: 11/14/2022
diff --git a/docs/sidebars.js b/docs/sidebars.js
index f6368f60f04..b714f63b507 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -1,14 +1,3 @@
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
-
// @ts-check
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
diff --git a/docs/versioned_docs/version-maintained/glossary.md b/docs/versioned_docs/version-maintained/glossary.md
new file mode 100644
index 00000000000..65aa985cf5c
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/glossary.md
@@ -0,0 +1,103 @@
+---
+sidebar_position: 1
+---
+
+# Glossary
+
+Here is a comprehensive list of definitions for some common terms used in this guide.
+
+## Beacon
+
+A **Beacon** represents a point of the Blockchain for which a [**Mithril Certificate**](#certificate) is created. It embeds at least the version of the [**Cardano Network**](#cardano-network) that is targeted, and the associated [**epoch**](#epoch) and [**immutable file number**](#immutable-file-number).
+
+## Cardano Network
+
+The **Cardano Network** is a **Proof-of-Stake** Blockchain platform that supports the ADA cryptocurrency.
+
+> More information is available [here](https://docs.cardano.org/introduction)
+
+## Cardano Node
+
+A **Cardano Node** is a node that runs in a [**Cardano Network**](#cardano-network). There are several types of nodes, among them are **Cardano Full Nodes** that hold a copy of the whole Blockchain. They can be used by **Wallets**, [**Stake Pool Operator**](#stake-pool-operator-spo), **Exchanges** or **Dapps**. One of the use cases of the [**Mithril Network**](#mithril-network) is to bootsrap rapidly a **Cardano Full Node**.
+
+## Cardano Key Pair
+
+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).
+
+## Certificate
+
+The **Mithril Aggregator** combines the produced [**multi signature**](#multi-signature) and some metadata into a [**Mithril Certificate**](#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.
+
+> More information is available [here](./mithril/mithril-protocol/certificates.md)
+
+## Epoch
+
+The [**Cardano Network**](#cardano-network) uses **Epochs** to group blocks computed in a certain amount of time (approximately 5 days). It is part of the design of its **Proof-of-Stake** consensus **Ouroboros**. At the end of each epoch, the [**stake distribution**](#stake-distribution) of the ending epoch is computed.
+
+## Immutable File Number
+
+Inside a the database of a [**Cardano Node**](#cardano-node), the Blockchain state is stored in **Immutable files** which never change once committed. These immutable files are designed so that they are deterministically produced and thus are the same on any **Cardano Node**. These files are created by following an incremental number, the **Immutable File Number** and there are three different immutable files for each number (i.e. _chunk_, _primary_ and _secondary_). Only the files up to the penultimate **Immutable File Number** are considered as committed and final, the last **Immutable File Number** files are constantly evolving. The [**Snapshots**](#snapshot) produced by the [**Mithril Network**](#mithril-network) rely on these **immutable files**.
+
+## Individual Signature
+
+For each [**Beacon**](#beacon), the [**Mithril Signers**](#mithril-signer) will compute on their end a message representing the Blockchain state, and sign it with their **Verification Keys** in order to create an [**Individual Signature**](#individual-signature). Upon winning one or multiple lotteries, the **Mithril Signer** will be able to use this **Individual Signature** to participate in the creation of a [**Multi Signature**](#multi-signature).
+
+> More information is available [here](./mithril/mithril-protocol/protocol.md)
+
+## Mithril Aggregator
+
+The **Mithril Aggregator** is a trustless node of the [**Mithril Network**](#mithril-network) that orchestrates the work of the [**Mithril Signer**](#mithril-signer) nodes and that gathers their [**individual signatures**](#individual-signature) to produce [**Mithril multi signatures**](#multi-signature) and their associated [**certificates**](#certificate).
+
+It is also in charge of creating and storing the [**snapshot**](#snapshot) archive.
+
+> More information is available [here](./mithril/mithril-network/aggregator.md)
+
+## Mithril Client
+
+The **Mithril Client** node of the [**Mithril Network**](#mithril-network) is used to restore a [**Cardano full node**](#cardano-node) by retrieving, from a [**Mithril Aggregator**](#mithril-aggregator), a remote [**snapshot**](#snapshot), its [**certificate**](#certificate) chain and by verifying their validity thanks to the Mithril cryptographic primitives.
+
+> More information is available [here](./mithril/mithril-network/client.md)
+
+## Mithril Network
+
+In its current version, the **Mithril Network** is a network of nodes responsible for creating [**Snapshots**](#snapshot) and [**Certificates**](#certificate) that enable fast bootstrap of a [**Cardano Node**](#cardano-node). It runs on top of the [**Cardano Network**](#cardano-network).
+
+> More information is available [here](./mithril/mithril-network/architecture.md)
+
+## Mithril Protocol
+
+The **Mithril Protocol** allows **stakeholders** in a **Proof-of-Stake** Blockchain network to individually **sign messages** that are aggregated into a **multi signature** which guarantees that they represent a minimum share of the total stakes.
+
+> More information is available [here](./mithril/mithril-protocol/protocol.md)
+
+## Mithril Signer
+
+The **Mithril Signer** is a node of the [**Mithril Network**](#mithril-network) that works transparently on top of the [**Stake Pool Operator**](#stake-pool-operator-spo) Cardano nodes and which individually signs the ledger state.
+
+> More information is available [here](./mithril/mithril-network/signer.md)
+
+## Multi Signature
+
+The **Mithril Multi Signature** is an aggregate of [**Individual Signatures**](#individual-signature) which guarantees that a minimum share of the total stakes has participated in its creation.
+
+> More information is available [here](./mithril/mithril-protocol/protocol.md)
+
+## Snapshot
+
+A Mithril Snapshot is a signed archive of the Blockchain state that can be used by [**Mithril Clients**](#mithril-client) to restore a [**Cardano Full Node**](#cardano-node). It is uniquely identified by its fingerprint or **Digest** which is part of the message signed by the [**Mithril Network**](#mithril-network).
+
+## Stake Distribution
+
+The **Cardano Stake Distribution** is the list of all the [**Stake Pool Operators**](#stake-pool-operator-spo) **Pool Id** addresses and their associated **Stakes Share** of the total **Stakes** of the [**Cardano Network**](#cardano-network).
+
+The **Mithril Stake Distribution** is the list of all the [**Stake Pool Operators**](#stake-pool-operator-spo) (that are running a [**Mithril Signer**](#mithril-signer)) **Pool Id** addresses, their associated **Stakes Share** of the total **Stakes** of the [**Cardano Network**](#cardano-network), and their signing [**Verification Key**](#verification-key).
+
+## Stake Pool Operator (SPO)
+
+A **Stake Pool Operator**, also known as a **SPO**, represents a party that holds (via delegation) **Stakes** in the [**Cardano Network**](#cardano-network). The stakes entitle it to participate in the block production thanks to the Cardano consensus mechanism.
+
+## Verification Key
+
+In order to create [**Individual Signatures**](#individual-signature), the [**Mithril Signers**](#mithril-signer) must register their signing public key: the **Verification Keys**. To garantee their genuineness, they are signed by the associated [**Cardano Key Pair**](#cardano-key-pair). It is worth mentioning that a [**Mithril Signer**](#mithril-signer) must be aware of the **Verification Keys** of all the other **Mithril Signers** in order to produce valid **Individual Signatures**.
+
+> More information is available [here](./mithril/mithril-protocol/protocol.md)
diff --git a/docs/versioned_docs/version-maintained/manual/developer-docs/_category_.json b/docs/versioned_docs/version-maintained/manual/developer-docs/_category_.json
new file mode 100644
index 00000000000..17753a830e1
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/developer-docs/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Developer Docs",
+ "collapsible": true,
+ "collapsed": false,
+ "position": 3,
+ "link": {
+ "type": "generated-index",
+ "title": "Developer Docs Topics"
+ }
+}
\ No newline at end of file
diff --git a/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/_category_.json b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/_category_.json
new file mode 100644
index 00000000000..2c132ff6bd4
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Mithril Network Nodes",
+ "collapsible": true,
+ "collapsed": false,
+ "position": 1,
+ "link": {
+ "type": "generated-index",
+ "title": "Mithril Network Nodes"
+ }
+}
\ No newline at end of file
diff --git a/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md
new file mode 100644
index 00000000000..2598bf047ac
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md
@@ -0,0 +1,318 @@
+---
+sidebar_position: 1
+---
+
+import NetworksMatrix from '../../../networks-matrix.md';
+
+# Mithril Aggregator Node
+
+:::info
+
+This is the node of the **Mithril Network** responsible for collecting individual signatures from the **Mithril Signers** and aggregate them into a multi-signature. The **Mithril Aggregator** uses this ability to provide certified snapshots of the **Cardano** blockchain.
+
+:::
+
+:::tip
+
+* For more information about the **Mithril Network**, please refer to the [Architecture](../../../mithril/mithril-network/architecture.md) page.
+
+* For more information about the **Mithril Aggregator**, please refer to the [Aggregator Node](../../../mithril/mithril-network/aggregator.md) page.
+
+:::
+
+:::note Mithril Networks
+
+
+
+:::
+
+## Resources
+
+| Node | Source Repository | Rust Documentation | Docker Packages | REST API
+|:-:|:-----------------:|:------------------:|:---------------:|
+**Mithril Aggregator** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-aggregator) | [:arrow_upper_right:](https://mithril.network/mithril-aggregator/doc/mithril_aggregator/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-aggregator) | [:arrow_upper_right:](/aggregator-api)
+
+## Pre-requisites
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version)
+
+* 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`.
+
+## Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+Change directory
+
+```bash
+cd mithril/mithril-aggregator
+```
+
+## Development test and build
+
+Run tests
+
+```bash
+make test
+```
+
+Create the help menu
+
+```bash
+make help
+```
+
+Generate the Rust documentation
+
+```bash
+make doc
+```
+
+Run in debug mode with default configuration
+
+```bash
+make debug
+```
+
+## Release build and run binary 'serve' command
+
+Build and run in release with default configuration
+
+```bash
+make run
+```
+
+Or, build only in release
+
+```bash
+make build
+```
+
+Display the help menu
+
+```bash
+./mithril-aggregator --help
+```
+
+You should see
+
+```bash
+mithril-aggregator
+Mithril Aggregator Node
+
+USAGE:
+ mithril-aggregator [OPTIONS]
+
+OPTIONS:
+ --config-directory
+ Directory where configuration file is located [default: ./config]
+
+ --db-directory
+ Directory where stores are located
+
+ -h, --help
+ Print help information
+
+ -r, --run-mode
+ Run Mode [default: dev]
+
+ -v, --verbose
+ Verbosity level
+
+SUBCOMMANDS:
+ genesis Genesis certificate command Genesis command selecter
+ help Print this message or the help of the given subcommand(s)
+ serve Server runtime mode
+
+```
+
+Run 'serve' command in release with default configuration
+
+```bash
+./mithril-aggregator serve
+```
+
+Run 'serve' command in release with a specific mode
+
+```bash
+./mithril-aggregator -r preview serve
+```
+
+Run 'serve' command in release with a custom configuration via env vars
+
+```bash
+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
+
+Build in release with default configuration
+
+```bash
+make build
+```
+
+Display the help menu
+
+```bash
+./mithril-aggregator genesis --help
+```
+
+You should see
+
+```bash
+mithril-aggregator-genesis
+Genesis tools
+
+USAGE:
+ mithril-aggregator genesis
+
+OPTIONS:
+ -h, --help Print help information
+
+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
+
+```
+
+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.
+
+```bash
+./mithril-aggregator genesis bootstrap
+```
+
+Or with a specific `Genesis Secret Key`, **only in test mode**.
+
+```bash
+./mithril-aggregator genesis bootstrap --genesis-secret-key **YOUR_SECRET_KEY**
+```
+
+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`.
+
+```bash
+./mithril-aggregator genesis export --target-path **YOUR_TARGET_PATH**
+```
+
+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.
+
+```bash
+./mithril-aggregator genesis import --signed-payload-path **YOUR_SIGNED_PAYLOAD_PATH**
+```
+
+Run 'genesis import' command in release with a custom configuration via env vars
+
+```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**
+```
+
+:::tip
+
+If you want to dig deeper, you can get access to several level of logs from the Mithril Aggregator:
+
+* Add `-v` for some logs (WARN)
+* Add `-vv` for more logs (INFO)
+* Add `-vvv` for even more logs (DEBUG)
+* Add `-vvvv` for all logs (TRACE)
+
+:::
+
+## Build and run Docker container
+
+Build a local Docker image
+
+```bash
+make docker-build
+```
+
+Run a local Docker container
+
+```bash
+make docker-run
+```
+
+## Subcommands
+
+Here are the subcommands available:
+
+| Subcommand | Performed action |
+|------------|------------------|
+| **serve** | Aggregator runs its HTTP server in nominal mode and orchestrates multi signatures production |
+| **help** | Print this message or the help of the given subcommand(s) |
+| **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) |
+
+## Configuration parameters
+
+The configuration parameters are set either:
+
+* In a configuration file (depending on the `--run-mode` parameter). If runtime mode is `testnet` the file is located in `./conf/testnet.json`.
+* The value can be overridden by an environment variable whose name is the parameter name uppercased.
+
+Here is a list of the available parameters.
+
+General parameters:
+
+| Parameter | Command Line (long) | Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
+|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
+| `cardano_cli_path` | - | - | `CARDANO_CLI_PATH` | Cardano CLI tool path | - | `cardano-cli` | :heavy_check_mark: |
+| `cardano_node_socket_path` | - | - | `CARDANO_NODE_SOCKET_PATH` | Path of the socket used by the Cardano CLI tool to communicate with the Cardano node | - | `/tmp/cardano.sock` | :heavy_check_mark: |
+| `config_directory` | `--config-directory` | - | - | Directory of the configuration file | `./config` | - | - |
+| `data_stores_directory` | - | - | `data_stores_directory` | Directory to store Aggregator data (Certificates, Snapshots, Protocol Parameters, ...) | - | `./mithril-aggregator/stores` | :heavy_check_mark: |
+| `db_directory` | `--db-directory` | - | `DB_DIRECTORY` | Directory of the **Cardano Node** stores | `/db` | - | :heavy_check_mark: |
+| `genesis_verification_key` | - | - | `GENESIS_VERIFICATION_KEY` | Genesis verification key | - | - | :heavy_check_mark: |
+| `network` | - | - | `NETWORK` | Cardano network | - | `testnet` or `mainnet` or `devnet` | :heavy_check_mark: |
+| `network_magic` | - | - | `NETWORK_MAGIC` | Cardano Network Magic number (for `testnet` and `devnet`) | - | `1097911063` or `42` | - |
+| `protocol_parameters` | - | - | `PROTOCOL_PARAMETERS__K`, `PROTOCOL_PARAMETERS__M`, and `PROTOCOL_PARAMETERS__PHI_F` | Mithril Protocol Parameters | - | `{ k: 5, m: 100, phi_f: 0.65 }` | :heavy_check_mark: |
+| `run_mode` | `--run-mode` | `-r` | `RUN_MODE` | Runtime mode | `dev` | - | :heavy_check_mark: |
+| `store_retention_limit` | - | - | `STORE_RETENTION_LIMIT` | Maximum number of records in stores. If not set, no limit is set. | - | - | - |
+| `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: |
+
+`serve` command:
+
+| Parameter | Command Line (long) | Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
+|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
+| `server_ip` | `--server-ip` | - | `SERVER_IP` | Listening server IP | `0.0.0.0` | - | :heavy_check_mark: |
+| `server_port` | `--server-port` | - | `SERVER_PORT` | Listening server port | `8080` | - | :heavy_check_mark: |
+| `snapshot_directory` | `--snapshot-directory` | - | `SNAPSHOT_DIRECTORY` | Directory to store local snapshots of the **Cardano Node** | `.` | - | :heavy_check_mark: |
+| `snapshot_store_type` | - | - | `SNAPSHOT_STORE_TYPE` | Type of snapshot store to use | - | `gcp` or `local` | :heavy_check_mark: |
+| `snapshot_uploader_type` | - | - | `SNAPSHOT_UPLOADER_TYPE` | Type of snapshot uploader to use | - | `gcp` or `local` | :heavy_check_mark: |
+| `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: |
+
+`genesis bootstrap` command:
+
+| Parameter | Command Line (long) | Command Line (short) | Environment Variable | Description | Default Value | Example | Mandatory |
+|-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
+| `genesis_secret_key` | - | - | `GENESIS_SECRET_KEY` | Genesis secret key, :warning: for test only | - | - | - |
+
+`genesis import` command:
+
+| 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. | - | - | - | - |
+
+`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. | - | - | - | - |
diff --git a/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md
new file mode 100644
index 00000000000..8135f8bf1f3
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md
@@ -0,0 +1,225 @@
+---
+sidebar_position: 3
+---
+
+import NetworksMatrix from '../../../networks-matrix.md';
+
+# Mithril Client Node
+
+:::info
+
+This is the node of the **Mithril Network** responsible for restoring the **Cardano** blockchain on an empty node from a certified snapshot.
+
+:::
+
+:::tip
+
+* For more information about the **Mithril Network**, please refer to the [Architecture](../../../mithril/mithril-network/architecture.md) page.
+
+* For more information about the **Mithril Client**, please refer to the [Client Node](../../../mithril/mithril-network/client.md) page.
+
+* Checkout the [`Bootstrap a Cardano Node`](../../getting-started/bootstrap-cardano-node.md) guide.
+
+:::
+
+:::note Mithril Networks
+
+
+
+:::
+
+
+## Resources
+
+| Node | Source Repository | Rust Documentation | Docker Packages |
+|:-:|:-----------------:|:------------------:|:---------------:|
+**Mithril Client** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client) | [:arrow_upper_right:](https://mithril.network/mithril-client/doc/mithril_client/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
+
+## Pre-requisites
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version)
+
+* Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `apt install libssl-dev`
+
+## Download source
+
+Download from GitHub (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+Change directory
+
+```bash
+cd mithril/mithril-client
+```
+
+## Development test and build
+
+Run tests
+
+```bash
+make test
+```
+
+Create the help menu
+
+```bash
+make help
+```
+
+Generate the Rust documentation
+
+```bash
+make doc
+```
+
+Run in debug mode with default configuration
+
+```bash
+make debug
+```
+
+## Release build and run binary
+
+Build and run in release with default configuration
+
+```bash
+make run
+```
+
+Or, build only in release
+
+```bash
+make build
+```
+
+Display the help menu
+
+```bash
+./mithril-client --help
+```
+
+You should see
+
+```bash
+mithril-client
+This program downloads, checks and restores certified blockchain snapshots.
+
+USAGE:
+ mithril-client [OPTIONS]
+
+OPTIONS:
+ --aggregator-endpoint
+ Override configuration Aggregator endpoint URL
+
+ --config-directory
+ Directory where configuration file is located [default: ./config]
+
+ -h, --help
+ Print help information
+
+ --run-mode
+ Run Mode [env: RUN_MODE=] [default: dev]
+
+ -v, --verbose
+ Verbosity level (-v=warning, -vv=info, -vvv=debug)
+
+SUBCOMMANDS:
+ download Download a snapshot
+ help Print this message or the help of the given subcommand(s)
+ list List available snapshots
+ restore Restore a snapshot
+ show Show detailed informations about a snapshot
+
+```
+
+Run in release with default configuration
+
+```bash
+./mithril-client
+```
+
+Run in release with a specific mode
+
+```bash
+./mithril-client --run-mode preview
+```
+
+Run in release with a custom configuration via env vars
+
+```bash
+GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) NETWORK=**YOUR_CARDANO_NETWORK** AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT** ./mithril-client
+```
+
+:::tip
+
+You can use the `--json` (or `-j`) option in order to display results in `JSON` format for the `list` and `show` commands:
+
+```bash
+./mithril-client list --json
+```
+
+:::
+
+:::tip
+
+If you want to dig deeper, you can get access to several level of logs from the Mithril Client:
+
+* Add `-v` for some logs (WARN)
+* Add `-vv` for more logs (INFO)
+* Add `-vvv` for even more logs (DEBUG)
+* Add `-vvvv` for all logs (TRACE)
+
+:::
+
+## Build and run Docker container
+
+Build a local Docker image
+
+```bash
+make docker-build
+```
+
+Run a local Docker container
+
+```bash
+make docker-run
+```
+
+## Subcommands
+
+Here are the subcommands available:
+
+| Subcommand | Performed action |
+|------------|------------------|
+| **download** | Download a snapshot|
+| **help** | Print this message or the help of the given subcommand(s)|
+| **list** | List available snapshots|
+| **restore** | Restore a snapshot|
+| **show** | Informations about a snapshot|
+
+## Configuration parameters
+
+The configuration parameters are set either:
+
+* In a configuration file (depending on the `--run-mode` parameter). If runtime mode is `testnet` the file is located in `./conf/testnet.json`.
+* The value can be overridden by an environment variable whose name is the parameter name uppercased.
+
+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 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.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/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md
new file mode 100644
index 00000000000..5bf7c51052e
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-signer.md
@@ -0,0 +1,191 @@
+---
+sidebar_position: 2
+---
+
+import NetworksMatrix from '../../../networks-matrix.md';
+
+# Mithril Signer Node
+
+:::info
+
+This is the node of the **Mithril Network** responsible for producing individual signatures that are collected and aggregated by the **Mithril Aggregator**.
+
+:::
+
+:::tip
+
+* For more information about the **Mithril Network**, please refer to the [Architecture](../../../mithril/mithril-network/architecture.md) page.
+
+* For more information about the **Mithril Signer**, please refer to the [Signer Node](../../../mithril/mithril-network/signer.md) page.
+
+* Checkout the [`Run a Mithril Signer node (SPO)`](../../getting-started/run-mithril-devnet.md) guide.
+
+:::
+
+:::note Mithril Networks
+
+
+
+:::
+
+## Resources
+
+| Node | Source Repository | Rust Documentation | Docker Packages |
+|:-:|:-----------------:|:------------------:|:---------------:|
+**Mithril Signer** | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-signer) | [:arrow_upper_right:](https://mithril.network/mithril-signer/doc/mithril_signer/index.html) | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/pkgs/container/mithril-signer)
+
+## Pre-requisites
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version)
+
+* 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`.
+
+## Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+Change directory
+
+```bash
+cd mithril/mithril-signer
+```
+
+## Development test and build
+
+Run tests
+
+```bash
+make test
+```
+
+Create the help menu
+
+```bash
+make help
+```
+
+Generate the Rust documentation
+
+```bash
+make doc
+```
+
+Run in debug mode with default configuration
+
+```bash
+make debug
+```
+
+## Release build and run binary
+
+Build and run in release with default configuration
+
+```bash
+make run
+```
+
+Or, build only in release
+
+```bash
+make build
+```
+
+Display the help menu
+
+```bash
+./mithril-signer --help
+```
+
+You should see
+
+```bash
+mithril-signer
+An implementation of a Mithril Signer
+
+USAGE:
+ mithril-signer [OPTIONS]
+
+OPTIONS:
+ -h, --help Print help information
+ -r, --run-mode Run Mode [default: dev]
+ -v, --verbose Verbosity level
+```
+
+Run in release with default configuration
+
+```bash
+./mithril-signer
+```
+
+Run in release with a specific mode
+
+```bash
+./mithril-signer -r preview
+```
+
+Run in release with a custom configuration via env vars
+
+```bash
+NETWORK=**YOUR_CARDANO_NETWORK** AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT** ./mithril-signer
+```
+
+:::tip
+
+If you want to dig deeper, you can get access to several level of logs from the Mithril Signer:
+
+* Add `-v` for some logs (WARN)
+* Add `-vv` for more logs (INFO)
+* Add `-vvv` for even more logs (DEBUG)
+* Add `-vvvv` for all logs (TRACE)
+
+:::
+
+## Build and run Docker container
+
+Build a local Docker image
+
+```bash
+make docker-build
+```
+
+Run a local Docker container
+
+```bash
+make docker-run
+```
+
+## Configuration parameters
+
+The configuration parameters are set either:
+
+* In a configuration file (depending on the `--run-mode` parameter). If runtime mode is `testnet` the file is located in `./conf/testnet.json`.
+* The value can be overridden by an environment variable whose name is the parameter name uppercased.
+
+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 number of occurrences: `-v` for `Warning`, `-vv` for `Info`, `-vvv` for `Debug` and `-vvvv` for `Trace` | :heavy_check_mark: |
+| `run_mode` | `--run-mode` | `-r` | `RUN_MODE` | Runtime mode | `dev` | - | :heavy_check_mark: |
+| `db_directory` | `--db-directory` | - | `DB_DIRECTORY` | Directory to snapshot from the **Cardano Node** | `/db` | - | :heavy_check_mark: |
+| `network` | - | - | `NETWORK` | Cardano network | - | `testnet` or `mainnet` or `devnet` | :heavy_check_mark: |
+`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.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) | - | - | - |
+| `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) | - | - | - |
diff --git a/docs/versioned_docs/version-maintained/manual/developer-docs/references.md b/docs/versioned_docs/version-maintained/manual/developer-docs/references.md
new file mode 100644
index 00000000000..03fbf6fe612
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/developer-docs/references.md
@@ -0,0 +1,40 @@
+---
+sidebar_position: 2
+---
+
+import NetworksMatrix from '../../networks-matrix.md';
+
+# API Reference
+
+Welcome to the Mithril API references doc!
+
+:::info
+
+This page gathers the external developer documentations available for Mithril. They are intended for a technical audience only.
+
+:::
+
+:::tip
+
+For more information about the **Mithril Protocol**, please refer to the [About Mithril](../../mithril/intro.md) section.
+
+:::
+
+## Mithril Networks
+
+
+
+## Dependencies List
+
+| Dependency | Description | Source Repository | Rust Documentation | REST API
+|------------|-------------|:-----------------:|:------------------:|:------------:|
+| **Mithril Common** | This is the **common** library that is used by the **Mithril Network** nodes. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-common) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_common/index.html) | -
+| **Mithril STM** | The **core** library that implements **Mithril** protocol cryptographic engine. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-stm) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_stm/index.html) | -
+| **Mithril Aggregator** | The node of the **Mithril Network** responsible for collecting individual signatures from the **Mithril Signers** and aggregate them into a multisignature. The **Mithril Aggregator** uses this ability to provide certified snapshots of the **Cardano** blockchain. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-aggregator) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_aggregator/index.html) | [:arrow_upper_right:](/aggregator-api)
+| **Mithril Client** | The node of the **Mithril Network** responsible for restoring the **Cardano** blockchain on an empty node from a certified snapshot. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-client) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_client/index.html) | -
+| **Mithril Signer** | The node of the **Mithril Network** responsible for producing individual signatures that are collected and aggregated by the **Mithril Aggregator**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/tree/main/mithril-signer) | [:arrow_upper_right:](https://mithril.network/rust-doc/mithril_signer/index.html) | -
+| **Mithril Devnet** | The private **Mithril/Cardano Network** used to scaffold a **Mithril Network** on top of a private **Cardano Network**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/blob/main/mithril-test-lab/mithril-devnet) | - | -
+| **Mithril End to End** | The tool used to run tests scenari against a **Mithril Devnet**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/blob/main/mithril-explorer) | - | -
+| **Mithril Explorer** | The explorer website that connects to a **Mithril Aggregator** and displays its **Certificate Chain**. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/blob/main/mithril-test-lab/mithril-end-to-end) | - | -
+| **Protocol Simulation** | A simple cli that helps understand how the **Mithril Protocol** works and the role of its protocol parameters. | [:arrow_upper_right:](https://github.com/input-output-hk/mithril/blob/main/demo/protocol-demo) | - | -
+
diff --git a/docs/versioned_docs/version-maintained/manual/getting-started/_category_.json b/docs/versioned_docs/version-maintained/manual/getting-started/_category_.json
new file mode 100644
index 00000000000..4d4a62b610f
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/getting-started/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Getting Started",
+ "collapsible": true,
+ "collapsed": false,
+ "position": 2,
+ "link": {
+ "type": "generated-index",
+ "title": "Getting Started Topics"
+ }
+}
\ No newline at end of file
diff --git a/docs/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md b/docs/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md
new file mode 100644
index 00000000000..f424b6114ab
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md
@@ -0,0 +1,426 @@
+---
+sidebar_position: 1
+---
+
+import NetworksMatrix from '../../networks-matrix.md';
+
+# Bootstrap a Cardano Node
+
+:::info
+
+Thanks to a **Mithril Client** connected to a **Mithril Aggregator**, you will restore a full Cardano node in less than 2 hours!
+
+:::
+
+:::note Mithril Networks
+
+
+
+:::
+
+# Video demonstration
+
+In this video you will see how fast the bootstrapping of a Cardano node with Mithril is compared to classical bootstrapping (benchmark done on mainnet with Daedalus wallet).
+
+
+
+
+## Pre-requisites
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+* Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `sudo apt install libssl-dev`
+
+* Install other requirements
+```bash
+sudo apt-get install make build-essential m4 docker jq
+```
+
+## Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+## Build Mithril Client binary
+
+Change directory
+
+```bash
+cd mithril/mithril-client
+```
+
+Run tests (Optional)
+
+```bash
+make test
+```
+
+Build executable
+
+```bash
+make build
+```
+
+## Verify build
+
+Check that the Mithril Client binary is working fine by running its help
+
+```bash
+./mithril-client help
+```
+
+You should see
+
+```bash
+mithril-client
+An implementation of a Mithril Client
+
+USAGE:
+ mithril-client [OPTIONS]
+
+OPTIONS:
+ -h, --help Print help information
+ -q, --quiet Less output per occurrence
+ -r, --run-mode Run Mode [default: dev]
+ -v, --verbose More output per occurrence
+
+SUBCOMMANDS:
+ download Download a snapshot
+ help Print this message or the help of the given subcommand(s)
+ list List available snapshots
+ restore Restore a snapshot
+ show Infos about a snapshot
+```
+
+:::tip
+
+You can use the `--json` option in order to display results in `JSON` format for the `list` and `show` commands:
+
+```bash
+./mithril-client list --json
+```
+
+:::
+
+:::tip
+
+If you want to dig deeper, you can get access to several level of logs from the Mithril Client:
+
+* Add `-v` for some logs (WARN)
+* Add `-vv` for more logs (INFO)
+* Add `-vvv` for even more logs (DEBUG)
+* Add `-vvvv` for all logs (TRACE)
+
+:::
+
+## Bootstrap a Cardano node from a testnet Mithril snapshot
+
+### Step 1: Prepare some useful variables
+
+```bash
+# Cardano network
+NETWORK=**YOUR_CARDANO_NETWORK**
+
+# Aggregator API endpoint URL
+AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
+
+# Genesis verification key
+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
+SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/snapshots | jq -r '.[0].digest')
+```
+
+### Step 2: Select A Snapshot
+
+List the available snapshots with which you can bootstrap a Cardano node
+
+```bash
+GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client list
+```
+
+You will see a list of snapshots
+
+```bash
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+| Network | Digest | Size | Locations | Created |
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+| testnet | cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068 | 5273560121 | 1 | 2022-07-10T11:19:18.042554390Z |
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+| testnet | 22267a8399cbd1731420f7241c91bec66b3126c971d53b1cdf4db0c016320df4 | 5267582819 | 1 | 2022-07-10T05:44:59.048360039Z |
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+| testnet | c14792945b3880fa9f8880348f885c707b8e4d13cdb035b9a735c15f88ea45db | 5265335799 | 1 | 2022-07-10T00:03:43.656860711Z |
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+| testnet | 0344faf7ebcd7cbf606288bfc8e7c11f992bd4f28f3ac159942b487a0217f485 | 5265577167 | 1 | 2022-07-09T18:31:16.604292173Z |
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+| testnet | fc42ef98e233717a7180502dc51aab1ca64d5bd6d6e9d72b4096ac1f7e45a129 | 5262797245 | 1 | 2022-07-09T12:45:20.306735843Z |
++---------+------------------------------------------------------------------+------------+-----------+--------------------------------+
+```
+
+### Step 3: Show Snapshot Details
+
+Get some more details from a specific snapshot (Optional)
+
+```bash
+GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client show $SNAPSHOT_DIGEST
+```
+
+You will see more information about a snapshot
+
+```bash
++------------+--------------------------------------------------------------------------------------------------------------------------------+
+| Info | Value |
++------------+--------------------------------------------------------------------------------------------------------------------------------+
+| Network | testnet |
++------------+--------------------------------------------------------------------------------------------------------------------------------+
+| Digest | cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068 |
++------------+--------------------------------------------------------------------------------------------------------------------------------+
+| Size | 5273560121 |
++------------+--------------------------------------------------------------------------------------------------------------------------------+
+| Location 1 | https://storage.googleapis.com/cardano-testnet/testnet.cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068.tar.gz |
++------------+--------------------------------------------------------------------------------------------------------------------------------+
+| Created | 2022-07-10T11:19:18.042554390Z |
+```
+
+### Step 4: Download Selected Snapshot
+
+Download the selected snapshot from the remote location to your remote location
+
+```bash
+GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client download $SNAPSHOT_DIGEST
+```
+
+You will see that the selected snapshot archive has been downloaded locally
+
+```bash
+Download success cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068 #1
+from https://storage.googleapis.com/cardano-testnet/testnet.cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068.tar.gz
+to /home/mithril/data/testnet/cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068/snapshot.archive.tar.gz
+```
+
+### Step 5: Restore Selected Snapshot
+
+Verify the Certificate of the snapshot and unpack its content in order to feed the Cardano node database
+
+```bash
+GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client restore $SNAPSHOT_DIGEST
+```
+
+You will see that the snapshot archive is unpacked and that the associated certificate is valid
+
+```bash
+Unpacking snapshot...
+Unpack success cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068
+to /home/mithril/data/testnet/cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068/db
+
+Restore a Cardano Node with:
+
+docker run -v cardano-node-ipc:/ipc -v cardano-node-data:/data --mount type=bind,source="/home/mithril/data/testnet/cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b02432d03f9b068/db",target=/data/db/ -e NETWORK=testnet inputoutput/cardano-node
+```
+
+### Step 6: Launch a Cardano Node From Restored Snapshot
+
+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_CARDANO_NETWORK** inputoutput/cardano-node
+```
+
+You will see the node start by validating the files injested from the snapshot archive
+
+```bash
+Starting: /nix/store/gps7n088g6xv3zqg281sng821471vq78-cardano-node-exe-cardano-node-1.35.1/bin/cardano-node run
+--config /nix/store/5b6pry15w93fv0r0x9rc3r1ii5871lvr-config-0-0.json
+--database-path /data/db
+--topology /nix/store/dpajyi2vaychwps1x7d20c2ddls4kf62-topology.yaml
+--host-addr 0.0.0.0
+--port 3001
+--socket-path /ipc/node.socket
+
+
+
+
+
++RTS
+-N2
+-I0
+-A16m
+-qg
+-qb
+--disable-delayed-os-memory-return
+-RTS
+..or, once again, in a single line:
+/nix/store/gps7n088g6xv3zqg281sng821471vq78-cardano-node-exe-cardano-node-1.35.1/bin/cardano-node run --config /nix/store/5b6pry15w93fv0r0x9rc3r1ii5871lvr-config-0-0.json --database-path /data/db --topology /nix/store/dpajyi2vaychwps1x7d20c2ddls4kf62-topology.yaml --host-addr 0.0.0.0 --port 3001 --socket-path /ipc/node.socket +RTS -N2 -I0 -A16m -qg -qb --disable-delayed-os-memory-return -RTS
+Node configuration: NodeConfiguration {ncSocketConfig = SocketConfig {ncNodeIPv4Addr = Last {getLast = Just 0.0.0.0}, ncNodeIPv6Addr = Last {getLast = Nothing}, ncNodePortNumber = Last {getLast = Just 3001}, ncSocketPath = Last {getLast = Just "/ipc/node.socket"}}, ncConfigFile = "/nix/store/5b6pry15w93fv0r0x9rc3r1ii5871lvr-config-0-0.json", ncTopologyFile = "/nix/store/dpajyi2vaychwps1x7d20c2ddls4kf62-topology.yaml", ncDatabaseFile = "/data/db", ncProtocolFiles = ProtocolFilepaths {byronCertFile = Nothing, byronKeyFile = Nothing, shelleyKESFile = Nothing, shelleyVRFFile = Nothing, shelleyCertFile = Nothing, shelleyBulkCredsFile = Nothing}, ncValidateDB = False, ncShutdownConfig = ShutdownConfig {scIPC = Nothing, scOnSyncLimit = Just NoShutdown}, ncProtocolConfig = NodeProtocolConfigurationCardano (NodeByronProtocolConfiguration {npcByronGenesisFile = "/nix/store/kax0css4lx3ywihvsgrqjym0jpi20f99-byron-genesis.json", npcByronGenesisFileHash = Just "96fceff972c2c06bd3bb5243c39215333be6d56aaf4823073dca31afe5038471", npcByronReqNetworkMagic = RequiresMagic, npcByronPbftSignatureThresh = Nothing, npcByronApplicationName = ApplicationName {unApplicationName = "cardano-sl"}, npcByronApplicationVersion = 0, npcByronSupportedProtocolVersionMajor = 3, npcByronSupportedProtocolVersionMinor = 0, npcByronSupportedProtocolVersionAlt = 0}) (NodeShelleyProtocolConfiguration {npcShelleyGenesisFile = "/nix/store/2xhy92909anynqsvx1b1x153cxwnfmzx-shelley-genesis.json", npcShelleyGenesisFileHash = Just "849a1764f152e1b09c89c0dfdbcbdd38d711d1fec2db5dfa0f87cf2737a0eaf4"}) (NodeAlonzoProtocolConfiguration {npcAlonzoGenesisFile = "/nix/store/8qnphq6yvcjspiy3z0aijfd6cv64l3hl-alonzo-genesis.json", npcAlonzoGenesisFileHash = Just "7e94a15f55d1e82d10f09203fa1d40f8eede58fd8066542cf6566008068ed874"}) (NodeHardForkProtocolConfiguration {npcTestEnableDevelopmentHardForkEras = False, npcTestShelleyHardForkAtEpoch = Nothing, npcTestShelleyHardForkAtVersion = Nothing, npcTestAllegraHardForkAtEpoch = Nothing, npcTestAllegraHardForkAtVersion = Nothing, npcTestMaryHardForkAtEpoch = Nothing, npcTestMaryHardForkAtVersion = Nothing, npcTestAlonzoHardForkAtEpoch = Nothing, npcTestAlonzoHardForkAtVersion = Nothing, npcTestBabbageHardForkAtEpoch = Nothing, npcTestBabbageHardForkAtVersion = Nothing}), ncDiffusionMode = InitiatorAndResponderDiffusionMode, ncSnapshotInterval = DefaultSnapshotInterval, ncTestEnableDevelopmentNetworkProtocols = False, ncMaxConcurrencyBulkSync = Nothing, ncMaxConcurrencyDeadline = Nothing, ncLoggingSwitch = True, ncLogMetrics = True, ncTraceConfig = TracingOnLegacy (TraceSelection {traceVerbosity = NormalVerbosity, traceAcceptPolicy = OnOff {isOn = True}, traceBlockFetchClient = OnOff {isOn = False}, traceBlockFetchDecisions = OnOff {isOn = False}, traceBlockFetchProtocol = OnOff {isOn = False}, traceBlockFetchProtocolSerialised = OnOff {isOn = False}, traceBlockFetchServer = OnOff {isOn = False}, traceBlockchainTime = OnOff {isOn = False}, traceChainDB = OnOff {isOn = True}, traceChainSyncBlockServer = OnOff {isOn = False}, traceChainSyncClient = OnOff {isOn = False}, traceChainSyncHeaderServer = OnOff {isOn = False}, traceChainSyncProtocol = OnOff {isOn = False}, traceConnectionManager = OnOff {isOn = True}, traceConnectionManagerCounters = OnOff {isOn = True}, traceConnectionManagerTransitions = OnOff {isOn = False}, traceDebugPeerSelectionInitiatorTracer = OnOff {isOn = False}, traceDebugPeerSelectionInitiatorResponderTracer = OnOff {isOn = False}, traceDiffusionInitialization = OnOff {isOn = True}, traceDnsResolver = OnOff {isOn = False}, traceDnsSubscription = OnOff {isOn = True}, traceErrorPolicy = OnOff {isOn = True}, traceForge = OnOff {isOn = True}, traceForgeStateInfo = OnOff {isOn = True}, traceHandshake = OnOff {isOn = False}, traceInboundGovernor = OnOff {isOn = True}, traceInboundGovernorCounters = OnOff {isOn = True}, traceInboundGovernorTransitions = OnOff {isOn = True}, traceIpSubscription = OnOff {isOn = True}, traceKeepAliveClient = OnOff {isOn = False}, traceLedgerPeers = OnOff {isOn = True}, traceLocalChainSyncProtocol = OnOff {isOn = False}, traceLocalConnectionManager = OnOff {isOn = False}, traceLocalErrorPolicy = OnOff {isOn = True}, traceLocalHandshake = OnOff {isOn = False}, traceLocalInboundGovernor = OnOff {isOn = False}, traceLocalMux = OnOff {isOn = False}, traceLocalRootPeers = OnOff {isOn = True}, traceLocalServer = OnOff {isOn = False}, traceLocalStateQueryProtocol = OnOff {isOn = False}, traceLocalTxMonitorProtocol = OnOff {isOn = False}, traceLocalTxSubmissionProtocol = OnOff {isOn = False}, traceLocalTxSubmissionServer = OnOff {isOn = False}, traceMempool = OnOff {isOn = True}, traceMux = OnOff {isOn = False}, tracePeerSelection = OnOff {isOn = True}, tracePeerSelectionCounters = OnOff {isOn = True}, tracePeerSelectionActions = OnOff {isOn = True}, tracePublicRootPeers = OnOff {isOn = True}, traceServer = OnOff {isOn = True}, traceTxInbound = OnOff {isOn = False}, traceTxOutbound = OnOff {isOn = False}, traceTxSubmissionProtocol = OnOff {isOn = False}, traceTxSubmission2Protocol = OnOff {isOn = False}}), ncTraceForwardSocket = Nothing, ncMaybeMempoolCapacityOverride = Nothing, ncProtocolIdleTimeout = 5s, ncTimeWaitTimeout = 60s, ncAcceptedConnectionsLimit = AcceptedConnectionsLimit {acceptedConnectionsHardLimit = 512, acceptedConnectionsSoftLimit = 384, acceptedConnectionsDelay = 5s}, ncTargetNumberOfRootPeers = 100, ncTargetNumberOfKnownPeers = 100, ncTargetNumberOfEstablishedPeers = 50, ncTargetNumberOfActivePeers = 20, ncEnableP2P = DisabledP2PMode}
+Listening on http://127.0.0.1:12798
+[c995d1df:cardano.node.basicInfo.protocol:Notice:5] [2022-07-10 13:48:51.68 UTC] Byron; Shelley
+[c995d1df:cardano.node.basicInfo.version:Notice:5] [2022-07-10 13:48:51.68 UTC] 1.35.1
+[c995d1df:cardano.node.basicInfo.commit:Notice:5] [2022-07-10 13:48:51.68 UTC] 0000000000000000000000000000000000000000
+[c995d1df:cardano.node.basicInfo.nodeStartTime:Notice:5] [2022-07-10 13:48:51.68 UTC] 2022-07-10 13:48:51.685957811 UTC
+[c995d1df:cardano.node.basicInfo.systemStartTime:Notice:5] [2022-07-10 13:48:51.68 UTC] 2019-07-24 20:20:16 UTC
+[c995d1df:cardano.node.basicInfo.slotLengthByron:Notice:5] [2022-07-10 13:48:51.68 UTC] 20s
+[c995d1df:cardano.node.basicInfo.epochLengthByron:Notice:5] [2022-07-10 13:48:51.68 UTC] 21600
+[c995d1df:cardano.node.basicInfo.slotLengthShelley:Notice:5] [2022-07-10 13:48:51.68 UTC] 1s
+[c995d1df:cardano.node.basicInfo.epochLengthShelley:Notice:5] [2022-07-10 13:48:51.68 UTC] 432000
+[c995d1df:cardano.node.basicInfo.slotsPerKESPeriodShelley:Notice:5] [2022-07-10 13:48:51.68 UTC] 129600
+[c995d1df:cardano.node.basicInfo.slotLengthAllegra:Notice:5] [2022-07-10 13:48:51.68 UTC] 1s
+[c995d1df:cardano.node.basicInfo.epochLengthAllegra:Notice:5] [2022-07-10 13:48:51.68 UTC] 432000
+[c995d1df:cardano.node.basicInfo.slotsPerKESPeriodAllegra:Notice:5] [2022-07-10 13:48:51.68 UTC] 129600
+[c995d1df:cardano.node.basicInfo.slotLengthMary:Notice:5] [2022-07-10 13:48:51.68 UTC] 1s
+[c995d1df:cardano.node.basicInfo.epochLengthMary:Notice:5] [2022-07-10 13:48:51.68 UTC] 432000
+[c995d1df:cardano.node.basicInfo.slotsPerKESPeriodMary:Notice:5] [2022-07-10 13:48:51.68 UTC] 129600
+[c995d1df:cardano.node.basicInfo.slotLengthAlonzo:Notice:5] [2022-07-10 13:48:51.68 UTC] 1s
+[c995d1df:cardano.node.basicInfo.epochLengthAlonzo:Notice:5] [2022-07-10 13:48:51.68 UTC] 432000
+[c995d1df:cardano.node.basicInfo.slotsPerKESPeriodAlonzo:Notice:5] [2022-07-10 13:48:51.68 UTC] 129600
+[c995d1df:cardano.node.basicInfo.slotLengthBabbage:Notice:5] [2022-07-10 13:48:51.68 UTC] 1s
+[c995d1df:cardano.node.basicInfo.epochLengthBabbage:Notice:5] [2022-07-10 13:48:51.68 UTC] 432000
+[c995d1df:cardano.node.basicInfo.slotsPerKESPeriodBabbage:Notice:5] [2022-07-10 13:48:51.68 UTC] 129600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Config path /nix/store/5b6pry15w93fv0r0x9rc3r1ii5871lvr-config-0-0.json, Network magic NetworkMagic {unNetworkMagic = 1097911063}, Protocol "Byron; Shelley", Version "1.35.1", Commit "0000000000000000000000000000000000000000", Node start time 2022-07-10 13:48:51.694962147 UTC
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Era Byron, Slot length 20s, Epoch length 21600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Era Shelley, Slot length 1s, Epoch length 432000, Slots per KESPeriod 129600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Era Allegra, Slot length 1s, Epoch length 432000, Slots per KESPeriod 129600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Era Mary, Slot length 1s, Epoch length 432000, Slots per KESPeriod 129600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Era Alonzo, Slot length 1s, Epoch length 432000, Slots per KESPeriod 129600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] Era Babbage, Slot length 1s, Epoch length 432000, Slots per KESPeriod 129600
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.69 UTC] startup time: 1657460932
+[c995d1df:cardano.node.startup:Info:5] [2022-07-10 13:48:51.70 UTC]
+node addresses: 0.0.0.0:3001
+local socket: /ipc/node.socket
+node-to-node versions:
+NodeToNodeV_7 HardForkNodeToNodeEnabled HardForkSpecificNodeToNodeVersion1 (EraNodeToNodeEnabled ByronNodeToNodeVersion2 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeDisabled :* Nil)
+NodeToNodeV_8 HardForkNodeToNodeEnabled HardForkSpecificNodeToNodeVersion1 (EraNodeToNodeEnabled ByronNodeToNodeVersion2 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeDisabled :* Nil)
+NodeToNodeV_9 HardForkNodeToNodeEnabled HardForkSpecificNodeToNodeVersion1 (EraNodeToNodeEnabled ByronNodeToNodeVersion2 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* EraNodeToNodeEnabled ShelleyNodeToNodeVersion1 :* Nil)
+node-to-client versions:
+NodeToClientV_9 HardForkNodeToClientEnabled HardForkSpecificNodeToClientVersion2 (EraNodeToClientEnabled ByronNodeToClientVersion1 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientDisabled :* Nil)
+NodeToClientV_10 HardForkNodeToClientEnabled HardForkSpecificNodeToClientVersion2 (EraNodeToClientEnabled ByronNodeToClientVersion1 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientEnabled ShelleyNodeToClientVersion4 :* EraNodeToClientDisabled :* Nil)
+NodeToClientV_11 HardForkNodeToClientEnabled HardForkSpecificNodeToClientVersion2 (EraNodeToClientEnabled ByronNodeToClientVersion1 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientDisabled :* Nil)
+NodeToClientV_12 HardForkNodeToClientEnabled HardForkSpecificNodeToClientVersion2 (EraNodeToClientEnabled ByronNodeToClientVersion1 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientDisabled :* Nil)
+NodeToClientV_13 HardForkNodeToClientEnabled HardForkSpecificNodeToClientVersion2 (EraNodeToClientEnabled ByronNodeToClientVersion1 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* EraNodeToClientEnabled ShelleyNodeToClientVersion5 :* Nil)
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:51.70 UTC] Started opening Chain DB
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:51.70 UTC] Started opening Immutable DB
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:51.79 UTC] Validating chunk no. 0 out of 2917. Progress: 0.00%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:52.16 UTC] Validated chunk no. 0 out of 2917. Progress: 0.00%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:52.16 UTC] Validating chunk no. 1 out of 2917. Progress: 0.00%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:52.56 UTC] Validated chunk no. 1 out of 2917. Progress: 0.03%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:52.56 UTC] Validating chunk no. 2 out of 2917. Progress: 0.03%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:52.96 UTC] Validated chunk no. 2 out of 2917. Progress: 0.07%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:52.96 UTC] Validating chunk no. 3 out of 2917. Progress: 0.07%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:53.35 UTC] Validated chunk no. 3 out of 2917. Progress: 0.10%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:53.35 UTC] Validating chunk no. 4 out of 2917. Progress: 0.10%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:53.75 UTC] Validated chunk no. 4 out of 2917. Progress: 0.14%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:53.75 UTC] Validating chunk no. 5 out of 2917. Progress: 0.14%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:48:54.14 UTC] Validated chunk no. 5 out of 2917.
+
+... (Cut for readability)
+
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.33 UTC] Validated chunk no. 2911 out of 2917. Progress: 99.79%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.33 UTC] Validating chunk no. 2912 out of 2917. Progress: 99.79%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.40 UTC] Validated chunk no. 2912 out of 2917. Progress: 99.83%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.40 UTC] Validating chunk no. 2913 out of 2917. Progress: 99.83%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.48 UTC] Validated chunk no. 2913 out of 2917. Progress: 99.86%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.48 UTC] Validating chunk no. 2914 out of 2917. Progress: 99.86%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.54 UTC] Validated chunk no. 2914 out of 2917. Progress: 99.90%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.54 UTC] Validating chunk no. 2915 out of 2917. Progress: 99.90%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.60 UTC] Validated chunk no. 2915 out of 2917. Progress: 99.93%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.60 UTC] Validating chunk no. 2916 out of 2917. Progress: 99.93%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.66 UTC] Validated chunk no. 2916 out of 2917. Progress: 99.97%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.66 UTC] Validating chunk no. 2917 out of 2917. Progress: 99.97%
+[c995d1df:cardano.node.ChainDB:Warning:5] [2022-07-10 13:53:08.67 UTC] Rewriting the secondary index for the chunk file with number 2917.
+[c995d1df:cardano.node.ChainDB:Warning:5] [2022-07-10 13:53:08.67 UTC] Rewriting the primary index for the chunk file with number 2917.
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.72 UTC] Found a valid last location at chunk 2917 with tip 07c1891b7394c92f50ddfabb84b9bd6be5944c5a201796190b5f69a69dcbc432@63009237.
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.72 UTC] Opened imm db with immutable tip at 07c1891b7394c92f50ddfabb84b9bd6be5944c5a201796190b5f69a69dcbc432 at slot 63009237 and chunk 2917
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:08.72 UTC] Started opening Volatile DB
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:09.28 UTC] Opened vol db
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:09.28 UTC] Started opening Ledger DB
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.19 UTC] Replaying ledger from snapshot at 16ce3e707388b8c033f87b440ac89095b2d2fc5fa2b42f768c38da286312a31a at slot 63005524
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.19 UTC] Replayed block: slot 63005533 out of 63009237. Progress: 0.24%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.20 UTC] Replayed block: slot 63007165 out of 63009237. Progress: 44.20%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.24 UTC] Opened lgr db
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.24 UTC] Started initial chain selection
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.45 UTC] Pushing ledger state for block 110b618d3359fb6d8bddf8cb1e98823dc995083a2af2607f1c179928a26d03c3 at slot 63009421. Progress: 0.00%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.82 UTC] before next, messages elided = 63009476
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.82 UTC] Pushing ledger state for block 5e59df354b64634bd27fc1b3ed08991c6de909ea085625da2ca78ec5a6a3e37c at slot 63019450. Progress: 13.85%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.82 UTC] Pushing ledger state for block e0610e4f03ef640ead31a729f6f18aa820f3906f6414b179d3c553f0011162ef at slot 63019479. Progress: 13.89%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:37.82 UTC] Pushing ledger state for block 8edc84f1f289475ca5c2afd9cae3c704ed7bcdf3e489fd1842e3904bd2d6d8c5 at slot 63019510. Progress: 13.93%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.21 UTC] before next, messages elided = 63019575
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.21 UTC] Pushing ledger state for block fc426a1c3a8c5ae61100e5ccfcaa47ccfb6cc144ed17fcd47a2b55f48890790a at slot 63029515. Progress: 27.75%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.21 UTC] Pushing ledger state for block 68059200505d3ec65d3ddce9441efb0607adab002066c00acc050f5bb0c53deb at slot 63029578. Progress: 27.84%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.21 UTC] Pushing ledger state for block 25f5cc004ad90dc554e085699f1386dc8f69cec4012a7b35735b83da6fa68a0b at slot 63029602. Progress: 27.87%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.61 UTC] before next, messages elided = 63029636
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.61 UTC] Pushing ledger state for block cfb3dd669fd1a85aaf005ddd0e4a8b90cbb7b2c66dc8ff6f41e2e7aa2a0f0c57 at slot 63039634. Progress: 41.72%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.61 UTC] Pushing ledger state for block d7f057436e749e4468cfd8b17a04d447c4ce628b8dc33ea7ebdc4d3ad4659dec at slot 63039638. Progress: 41.73%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.61 UTC] Pushing ledger state for block 73fcb92346714585e1dbb484b1678bb15dab7304a8071cd95ec85195ca7a46be at slot 63039655. Progress: 41.75%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.93 UTC] before next, messages elided = 63039729
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.93 UTC] Pushing ledger state for block a7256fa99f7bf50d0e764cb80122222b1d2b80ffef4bee30e42c0bb80c5f1168 at slot 63049716. Progress: 55.64%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.93 UTC] Pushing ledger state for block 75e2064629d6a017bfe324a3d31723ed7bfa017eceda1549bd6c9f4d63653394 at slot 63049861. Progress: 55.84%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:38.94 UTC] Pushing ledger state for block 71aeaae8f83ee6b94a7feb521c16f0d889a9b95be6da85d540ac0435b412fb2c at slot 63049904. Progress: 55.90%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.19 UTC] before next, messages elided = 63049909
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.19 UTC] Pushing ledger state for block 15ad241c6908d0748cb80d17035d4001f7f86ee22fe71197cbe9bc7489d8e71b at slot 63059862. Progress: 69.65%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.19 UTC] Pushing ledger state for block a5e38b0875d44e10a3cba9c420ad4c9708e913e3458f1003a8236a831762069a at slot 63059915. Progress: 69.73%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.19 UTC] Pushing ledger state for block ca6dc89bd705476bcd056d6ffc3dd43499e51d0e5ecfe56a439fadacac50fc1b at slot 63059939. Progress: 69.76%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.48 UTC] before next, messages elided = 63059957
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.48 UTC] Pushing ledger state for block 3c8593b6859b02abaa7f3b69d2114b1f402c65eef6904020e5ed37356aea4461 at slot 63069941. Progress: 83.57%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.48 UTC] Pushing ledger state for block 50a06570febcf89ee00c386979d3a616561996b6c5cf6cbff44c20aa8454c375 at slot 63069971. Progress: 83.61%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.48 UTC] Pushing ledger state for block 6265f3c30f149ba0a797a1d2c6998b918f089e7455ab665e3369456105901a5a at slot 63069972. Progress: 83.62%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.79 UTC] before next, messages elided = 63069985
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.79 UTC] Pushing ledger state for block 0be786a1d9272083e9e184da3bc3bfcb71b82ad10fbf52f4959dc5dc6d1b7b3c at slot 63079898. Progress: 97.32%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.79 UTC] Pushing ledger state for block 2862bd67a50bf9f6f31ab11d9153663d3e657f88c24ba8e71174f8f5216c2a99 at slot 63079992. Progress: 97.45%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.79 UTC] Pushing ledger state for block cc9036c6c4076ca28ac5d03522001c233a9202cb5b1d9484c3e406fbb3406fd5 at slot 63079994. Progress: 97.45%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.86 UTC] before next, messages elided = 63080024
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.86 UTC] Pushing ledger state for block c9bb7635b3e55175af30d1c9ca943d5df438ed838e814956d304cbb638c664aa at slot 63081837. Progress: 100.00%
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.86 UTC] Valid candidate at tip 110b618d3359fb6d8bddf8cb1e98823dc995083a2af2607f1c179928a26d03c3 at slot 63009421
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.86 UTC] Initial chain selected
+[c995d1df:cardano.node.ChainDB:Info:5] [2022-07-10 13:53:39.86 UTC] Opened db with immutable tip at 07c1891b7394c92f50ddfabb84b9bd6be5944c5a201796190b5f69a69dcbc432 at slot 63009237 and tip c9bb7635b3e55175af30d1c9ca943d5df438ed838e814956d304cbb638c664aa at slot 63081837
+[c995d1df:cardano.node.shutdown:Warning:5] [2022-07-10 13:53:39.87 UTC] Will terminate upon reaching NoShutdown
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:346] [2022-07-10 13:53:39.87 UTC] CreatingServerSocket 0.0.0.0:3001
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:346] [2022-07-10 13:53:39.87 UTC] ConfiguringServerSocket 0.0.0.0:3001
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:346] [2022-07-10 13:53:39.87 UTC] ListeningServerSocket 0.0.0.0:3001
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:346] [2022-07-10 13:53:39.87 UTC] ServerSocketUp 0.0.0.0:3001
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:346] [2022-07-10 13:53:39.87 UTC] RunServer (0.0.0.0:3001 :| [])
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:349] [2022-07-10 13:53:39.87 UTC] CreateSystemdSocketForSnocketPath (LocalAddress "/ipc/node.socket")
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:349] [2022-07-10 13:53:39.87 UTC] CreatedLocalSocket (LocalAddress "/ipc/node.socket")
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:349] [2022-07-10 13:53:39.87 UTC] ConfiguringLocalSocket (LocalAddress "/ipc/node.socket") (FileDescriptor 26)
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:349] [2022-07-10 13:53:39.87 UTC] ListeningLocalSocket (LocalAddress "/ipc/node.socket") (FileDescriptor 26)
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:349] [2022-07-10 13:53:39.87 UTC] LocalSocketUp (LocalAddress "/ipc/node.socket") (FileDescriptor 26)
+[c995d1df:cardano.node.DiffusionInitializationTracer:Info:349] [2022-07-10 13:53:39.87 UTC] RunLocalServer (LocalAddress "/ipc/node.socket")
+[c995d1df:cardano.node.DnsSubscription:Warning:345] [2022-07-10 13:53:39.91 UTC] Domain: "relays-new.cardano-testnet.iohkdev.io" Unsupported remote target address [2a05:d014:e00:a200:0:1:0:1]:3001
+[c995d1df:cardano.node.DnsSubscription:Notice:358] [2022-07-10 13:53:39.91 UTC] Domain: "relays-new.cardano-testnet.iohkdev.io" Connection Attempt Start, destination 3.131.32.242:3001
+[c995d1df:cardano.node.DnsSubscription:Warning:345] [2022-07-10 13:53:39.94 UTC] Domain: "relays-new.cardano-testnet.iohkdev.io" Unsupported remote target address [2a05:d01c:321:2101:0:1:0:2]:3001
+[c995d1df:cardano.node.DnsSubscription:Notice:359] [2022-07-10 13:53:39.94 UTC] Domain: "relays-new.cardano-testnet.iohkdev.io" Connection Attempt Start, destination 13.41.9.54:3001
+[c995d1df:cardano.node.DnsSubscription:Notice:359] [2022-07-10 13:53:39.95 UTC] Domain: "relays-new.cardano-testnet.iohkdev.io" Connection Attempt End, destination 13.41.9.54:3001 outcome: ConnectSuccessLast
+[c995d1df:cardano.node.ErrorPolicy:Notice:343] [2022-07-10 13:53:39.95 UTC] IP 3.131.32.242:3001 ErrorPolicySuspendConsumer (Just (ConnectionExceptionTrace (SubscriberError {seType = SubscriberParallelConnectionCancelled, seMessage = "Parallel connection cancelled", seStack = []}))) 1s
+```
+
+Then the Cardano node will synchronize with the other nodes of the network and start adding blockss
+
+```bash
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:53:40.06 UTC] Chain extended, new tip: 7ae33b2f4bc8b84e77dfd539f0f6e7f59b293e96f62fdcfdb17cbd7a006fe5c0 at slot 63081906
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:55:08.30 UTC] Chain extended, new tip: 6b4ccd2bec5e3862b23ea0f7c2f342a3659cecdcfdaf04551179df3839be6213 at slot 63092090
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:55:21.36 UTC] Chain extended, new tip: 6e95eb82da5a38544e6ef430a2733f6014c3c10527003b9d3bdc534f6a2ce81f at slot 63092103
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:55:39.04 UTC] Chain extended, new tip: a662672ec4b988022e135cb0b7e440f5fbffe8e205771d13a566a418f7021ba7 at slot 63092121
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:55:45.18 UTC] Chain extended, new tip: 2a0f2e6f218a08f4e0bc4668285d8e792fd7ec62f05880bd5b2d23d6bce20dfb at slot 63092127
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:56:18.05 UTC] Chain extended, new tip: ab9ef8af92ec062ec59a10da588e238ba8840705c095ebd5cd5da7ab9ea9c8e1 at slot 63092160
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:56:45.15 UTC] Chain extended, new tip: e59bcbf34172eb6a934e2580f6b20ebe1ea32fba7420feec096744fab8ffce76 at slot 63092189
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:57:59.06 UTC] Chain extended, new tip: ea0e76fe069a0bcb831cf6b342530adf2a28de4922a752cff734fe81a1842dff at slot 63092263
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:58:02.27 UTC] Chain extended, new tip: 1b68a85a10dd7bd840a69ece2807fbca61a1de07c30080bf94fbbfd1de8d1446 at slot 63092266
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:58:28.21 UTC] Chain extended, new tip: 07e1252c5614b9bb6e6cff95066c134eb251aea6bef33dc34c0dd064934f2cea at slot 63092292
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:58:33.17 UTC] Chain extended, new tip: 0d3712fd7852b0aff00d660f4e7dc609808018dc271fe460bb9ff8270dd50d8f at slot 63092297
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:58:48.53 UTC] Chain extended, new tip: c8bb96ea392e41dce6fc157e164dbe19ba894d268f69985e20a2d65daeb4488c at slot 63092312
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:58:58.08 UTC] Chain extended, new tip: 35ea30e175abaae7983db9f65e7a00ba45312ecb151e53a651b3a6058add4c4f at slot 63092322
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:59:02.13 UTC] Chain extended, new tip: 5320de43ea30e46515f48263211212833474ea87ff046f36f0d83059fad6e9ff at slot 63092326
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:59:06.29 UTC] Chain extended, new tip: 58e9cb29bd771e0625689a0d591a7a8309f9e859ce4a3b70a9ab2e28173ce78b at slot 63092330
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 13:59:36.31 UTC] Chain extended, new tip: 1af2411f492e1895231cc910bdb1a68a45596157bcbfae5bdfd5c5ed81b03054 at slot 63092360
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 14:00:04.51 UTC] Chain extended, new tip: 270d47c5a277ef7efe028b6eb4764ab328db8e509ad962370bb383b1832bb260 at slot 63092388
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 14:00:29.52 UTC] Chain extended, new tip: 6fbe009ac36363cbebc607c733964878dfce6054c8785d1294f202acb475c861 at slot 63092413
+[c995d1df:cardano.node.ChainDB:Notice:322] [2022-07-10 14:01:12.63 UTC] Chain extended, new tip: f764596ece0b75d5d0054f22f3f0a0846f1647ff980d053015065099ec279839 at slot 63092456
+```
diff --git a/docs/versioned_docs/version-maintained/manual/getting-started/images/devnet-topology.png b/docs/versioned_docs/version-maintained/manual/getting-started/images/devnet-topology.png
new file mode 100644
index 00000000000..a472b92cf58
Binary files /dev/null and b/docs/versioned_docs/version-maintained/manual/getting-started/images/devnet-topology.png differ
diff --git a/docs/versioned_docs/version-maintained/manual/getting-started/run-mithril-devnet.md b/docs/versioned_docs/version-maintained/manual/getting-started/run-mithril-devnet.md
new file mode 100644
index 00000000000..f73af917d30
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/getting-started/run-mithril-devnet.md
@@ -0,0 +1,540 @@
+---
+sidebar_position: 3
+---
+
+# Run a Private Mithril network
+
+:::info
+
+In this guide, you will learn how to run a demonstration of a **Mithril Network** working on top of a private `devnet` **Cardano Network**. This network is completely autonomous and setup to produce Mithril snapshots every 1 minute.
+
+:::
+
+The network will be launched with the following topology:
+
+* `2` **Cardano Nodes** configured as **Stake Pool Operators (SPO)** with a **Mithril Signer** on top
+* `1` **Cardano Node** configured as **BFT node** with a **Mithril Aggregator** on top
+
+
+
+:::danger
+
+This demonstration is working only on a Linux machine.
+
+:::
+
+:::tip
+
+More information about this private Cardano/Mithril `devnet` is available [here](https://github.com/input-output-hk/mithril/blob/main/mithril-test-lab/mithril-devnet/README.md).
+
+:::
+
+# Video demonstration
+
+
+
+## Pre-requisites
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+* 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`.
+
+## Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+## Change directory
+
+Go to the devnet folder
+
+```bash
+cd mithril-test-lab/mithril-devnet
+```
+
+## Run a Private Mithril/Cardano network locally (`devnet`)
+
+### Step 1: Launch the devnet
+
+Open a first terminal window.
+
+Run a devnet with 1 BTF and 2 SPO Cardano nodes.
+
+**Option 1**: Remote Docker images
+
+The network will be ready faster with remote Docker images.
+
+```bash
+MITHRIL_IMAGE_ID=latest NUM_BFT_NODES=1 NUM_POOL_NODES=2 ./devnet-run.sh
+```
+
+Or
+
+**Option 2**: Local Docker images
+
+This takes more time to build local Docker images of the Mithril nodes
+
+```bash
+NUM_BFT_NODES=1 NUM_POOL_NODES=2 ./devnet-run.sh
+```
+
+:::info
+
+You will see that the devnet is launched with the following steps:
+
+* **Bootstraping the devnet**: generates the artifacts of the devnet depending on the configuration parameters (cryptographic keys, network topology, transactions to setup pool nodes, ...)
+* **Start Cardano Network**: run the nodes of the **Cardano Network**, waits for it to be ready and activate the pool nodes
+* **Start Mithril Network**: run the nodes of the **Mithril Network** that works on top of the **Cardano Network**
+
+:::
+
+You should see the following information displayed
+
+```bash
+=====================================================================
+ Bootstrap Mithril/Cardano devnet
+=====================================================================
+
+>> Directory: artifacts
+>> Cardano BFT nodes: 1
+>> Cardano SPO nodes: 2
+>> Info: Mithril Aggregator will be attached to the first Cardano BFT node
+>> Info: Mithril Signers will be attached to each Cardano SPO node
+
+=====================================================================
+ Start Cardano nodes
+=====================================================================
+
+>> Start Cardano network
+cardano-node: no process found
+>> Starting Cardano node 'node-bft1'
+>> Starting Cardano node 'node-pool1'
+>> Starting Cardano node 'node-pool2'
+>> Wait for Cardano network to be ready
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Not ready yet
+>>>> Ready!
+>> Activate Cardano pools
+Estimated transaction fee: Lovelace 843
+Transaction successfully submitted.
+Estimated transaction fee: Lovelace 843
+Transaction successfully submitted.
+>> Wait for Cardano pools to be activated
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Not activated yet
+>>>> Activated!
+>>>> Found PoolId: pool1v55rfy864kslz86u45w4juahtuqr7cy282rffdnpc9exjlguvys
+>>>> Found PoolId: pool1c56jqj5qsala8c24829sxqp0fcrtrrtcmezgrs6w60hl2nwsvav
+
+=====================================================================
+ Start Mithril nodes
+=====================================================================
+
+>> Start Mithril network
+>> Build Mithril node Docker images
+>>>> Building Mithril Aggregator node Docker image
+>>>> Building Mithril Client node Docker image
+>>>> Building Mithril Signer node Docker image
+No stopped containers
+Creating network "artifacts_cardano_network" with driver "bridge"
+Creating network "artifacts_mithril_network" with driver "bridge"
+Creating artifacts_mithril-aggregator_1 ... done
+Creating artifacts_mithril-signer-node-pool1_1 ... done
+Creating artifacts_mithril-signer-node-pool2_1 ... done
+Creating artifacts_mithril-aggregator-genesis_run ... done
+{"msg":"Started","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.925641527Z","hostname":"e932dff845aa","pid":1,"config":"Configuration { cardano_cli_path: \"/app/bin/cardano-cli\", cardano_node_socket_path: \"/data/ipc/node.sock\", network_magic: Some(42), network: \"devnet\", protocol_parameters: ProtocolParameters { k: 5, m: 100, phi_f: 0.65 }, url_snapshot_manifest: \"\", snapshot_store_type: Local, snapshot_uploader_type: Local, server_url: \"http://0.0.0.0:8080/\", run_interval: 1000, db_directory: \"/data/db\", snapshot_directory: \"/data/mithril/aggregator\", data_stores_directory: \"/data/mithril/aggregator/stores\", genesis_verification_key: \"5b33322c3235332c3138362c3230312c3137372c31312c3131372c3133352c3138372c3136372c3138312c3138382c32322c35392c3230362c3130352c3233312c3135302c3231352c33302c37382c3231322c37362c31362c3235322c3138302c37322c3133342c3133372c3234372c3136312c36385d\" }","run_mode":"dev"}
+{"msg":"New LocalSnapshotUploader created","v":0,"name":"slog-rs","level":20Genesis bootstrap for test only
+,"time":"2022-09-06T09:24:31.925683285Z","hostname":"e932dff845aa","pid":1,"snapshot_server_url":"http://0.0.0.0:8080/"}
+{"msg":"New MultiSignerImpl created","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.925711468Z","hostname":"e932dff845aa","pid":1}
+{"msg":"New MithrilCertificateVerifier created","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.925736796Z","hostname":"e932dff845aa","pid":1}
+{"msg":"Update current_beacon to Beacon { network: \"devnet\", epoch: Epoch(10), immutable_file_number: 47 }","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.938337155Z","hostname":"e932dff845aa","pid":1}
+{"msg":"Get next signers with stake","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.938384324Z","hostname":"e932dff845aa","pid":1}
+{"msg":"Get next stake distribution","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.938422585Z","hostname":"e932dff845aa","pid":1}
+{"msg":"Get stake distribution with epoch offset","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.938459565Z","hostname":"e932dff845aa","pid":1,"epoch_offset":0}
+{"msg":"Get next protocol parameters","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.938500461Z","hostname":"e932dff845aa","pid":1}
+{"msg":"Get protocol parameters with epoch offset","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.938535367Z","hostname":"e932dff845aa","pid":1,"epoch_offset":0}
+{"msg":"Create clerk","v":0,"name":"slog-rs","level":20,"time":"2022-09-06T09:24:31.93856896Z","hostname":"e932dff845aa","pid":1}
+Verify genesis certificate #86a4c56d957636740a75c250fdd9d3b9a9f1539dc93449b1f80fcab49e279d6d @ epoch #10
+
+=====================================================================
+ Schedule Cardano Stake Delegation
+=====================================================================
+
+>> Begin scheduled delegation
+>> 11:24:32: Wait 180s until next delegation round...
+>> Run delegation round #1!
+>>>> Current Epoch: 12
+Estimated transaction fee: Lovelace 436
+Transaction successfully submitted.
+Estimated transaction fee: Lovelace 436
+Transaction successfully submitted.
+>> 11:27:32: Wait 180s until next delegation round...
+>> Run delegation round #2!
+>>>> Current Epoch: 14
+Estimated transaction fee: Lovelace 436
+Transaction successfully submitted.
+Estimated transaction fee: Lovelace 436
+Transaction successfully submitted.
+>> 11:30:32: Wait 180s until next delegation round...
+```
+
+### Step 2: Query the devnet
+
+Open a second terminal window.
+
+Watch the state queried from the devnet
+
+```bash
+watch -n 1 ./devnet-query.sh
+```
+
+The networks will be queried every `1s` and will display:
+
+* Certificate production informations gathered from the **Mithril Network**
+* Utxo, Stake Pools, Stake Distribution from the **Cardano Network**
+
+```bash
+=====================================================================
+ Query Mithril/Cardano devnet
+=====================================================================
+
+=====================================================================
+=== Mithril Network
+=====================================================================
+
+>> Query pending certificate
+{
+ "beacon": {
+ "network": "devnet",
+ "epoch": 2,
+ "immutable_file_number": 6
+ },
+ "protocol": {
+ "k": 5,
+ "m": 100,
+ "phi_f": 0.65
+ },
+ "signers": []
+}
+
+>> Query snapshots
+[
+ {
+ "digest": "224b77ad9cbe7fc81e6808940d391b299c27e77d9978641025f382e2e5ddd2ac",
+ "certificate_hash": "5b29543c4af0f369d40e1da53451ebd8a39c4263df1585eb072f54511c1e3333",
+ "size": 7986,
+ "created_at": "2022-07-05T11:26:55.855498395Z",
+ "locations": [
+ "http://0.0.0.0:8080/aggregator/snapshot/224b77ad9cbe7fc81e6808940d391b299c27e77d9978641025f382e2e5ddd2ac/download"
+ ]
+ },
+ {
+ "digest": "1a39f57c906133421ab7b5c782762b6abff4771b5e9158a977e58db1edc26bd0",
+ "certificate_hash": "be758b84a4b495e82af48747356946efb509ccbc4b44a9c985e3cb3099e35c94",
+ "size": 6743,
+ "created_at": "2022-07-05T11:26:35.658661878Z",
+ "locations": [
+ "http://0.0.0.0:8080/aggregator/snapshot/1a39f57c906133421ab7b5c782762b6abff4771b5e9158a977e58db1edc26bd0/download"
+ ]
+ },
+ {
+ "digest": "fd1a39d28998ba18c96547f62d308c57612ed348be058f615c14db5228a947c1",
+ "certificate_hash": "4254a6176afbe17967ad1671e4619e9a3f3412115a63dd0eb0f5e8b64094128a",
+ "size": 6199,
+ "created_at": "2022-07-05T11:26:20.470029035Z",
+ "locations": [
+ "http://0.0.0.0:8080/aggregator/snapshot/fd1a39d28998ba18c96547f62d308c57612ed348be058f615c14db5228a947c1/download"
+ ]
+ }
+]
+
+=====================================================================
+=== Cardano Network
+=====================================================================
+
+>> Query chain tip
+{
+ "era": "Alonzo",
+ "syncProgress": "100.00",
+ "hash": "075fc8366d353b45debedfc6faa92148c8fad584d81dbb4ea7b8b4d121489452",
+ "epoch": 2,
+ "slot": 219,
+ "block": 9
+}
+
+>> Query whole utxo
+ TxHash TxIx Amount
+--------------------------------------------------------------------------------------
+4980fb7c90bc003f6af65778008732cd1b1a8c0873b7d622bfb7442f1312c9b5 0 447999157 lovelace + TxOutDatumNone
+4980fb7c90bc003f6af65778008732cd1b1a8c0873b7d622bfb7442f1312c9b5 1 2000000 lovelace + TxOutDatumNone
+c31e535531c9eb32bdd8f05e25204186333262674d24c6a770b6b120f020d9a9 0 448999157 lovelace + TxOutDatumNone
+c31e535531c9eb32bdd8f05e25204186333262674d24c6a770b6b120f020d9a9 1 1000000 lovelace + TxOutDatumNone
+ed265b672873192ea1e9c19092e8f41947c28977438bcff580312de37cfbd46c 0 1002000000 lovelace + TxOutDatumNone
+
+>> Query stake pools
+pool1v55rfy864kslz86u45w4juahtuqr7cy282rffdnpc9exjlguvys
+pool1c56jqj5qsala8c24829sxqp0fcrtrrtcmezgrs6w60hl2nwsvav
+
+>> Query stake distribution
+ PoolId Stake frac
+------------------------------------------------------------------------------
+pool1v55rfy864kslz86u45w4juahtuqr7cy282rffdnpc9exjlguvys 1.052e-3
+pool1c56jqj5qsala8c24829sxqp0fcrtrrtcmezgrs6w60hl2nwsvav 5.258e-4
+```
+
+### Step 3: Observe the devnet
+
+Open a third terminal window.
+
+Watch the logs of each node of the devnet
+
+```bash
+watch -n 1 LINES=5 ./devnet-log.sh
+```
+
+The nodes will be queried every `1s` and will display as below
+
+```bash
+=====================================================================
+ Logs Mithril/Cardano devnet
+=====================================================================
+
+=====================================================================
+-- docker-compose logs --tail=5
+=====================================================================
+Attaching to artifacts_mithril-signer-node-pool1_1, artifacts_mithril-signer-node-pool2_1, artifacts_mithril-aggregator_1
+mithril-aggregator_1 | {"msg":"Epoch computation is not final and needs to be fixed: 4","v":0,"name":"slog-rs","level":40,"time":"2022-07-05T11:29:32.726760492Z","hostname":"ba17593540ac","pid":1}
+mithril-aggregator_1 | {"msg":"Get signer pool1c56jqj5qsala8c24829sxqp0fcrtrrtcmezgrs6w60hl2nwsvav","v":0,"name":"slog-rs","level":20,"time":"2022-07-05T11:29:32.72678048Z","hostname":"ba17593540ac","pid":1}
+mithril-aggregator_1 | {"msg":"Epoch computation is not final and needs to be fixed: 4","v":0,"name":"slog-rs","level":40,"time":"2022-07-05T11:29:32.72679661Z","hostname":"ba17593540ac","pid":1}
+mithril-aggregator_1 | {"msg":"Get signer pool1v55rfy864kslz86u45w4juahtuqr7cy282rffdnpc9exjlguvys","v":0,"name":"slog-rs","level":20,"time":"2022-07-05T11:29:32.734529107Z","hostname":"ba17593540ac","pid":1}
+mithril-aggregator_1 | {"msg":"Epoch computation is not final and needs to be fixed: 4","v":0,"name":"slog-rs","level":40,"time":"2022-07-05T11:29:32.734553714Z","hostname":"ba17593540ac","pid":1}
+mithril-signer-node-pool1_1 | {"msg":"Signing digest","v":0,"name":"slog-rs","level":30,"time":"2022-07-05T11:29:32.744124074Z","hostname":"4fc53f5ce413","pid":1,"digester_result":"DigesterResult {\n digest: \"e5ac1579a3fff12bf19ef88b0d9ec9d8a1c53e4d74c38c023b2e33638f454d67\",\n last_immutable_file_number: 17,\n}"}
+mithril-signer-node-pool1_1 | {"msg":"Register signatures","v":0,"name":"slog-rs","level":30,"time":"2022-07-05T11:29:32.744140625Z","hostname":"4fc53f5ce413","pid":1}
+mithril-signer-node-pool1_1 | {"msg":"Epoch computation is not final and needs to be fixed: 4","v":0,"name":"slog-rs","level":40,"time":"2022-07-05T11:29:32.744155293Z","hostname":"4fc53f5ce413","pid":1}
+mithril-signer-node-pool1_1 | {"msg":"SingleSignaturesComputeFailed(UnregisteredVerificationKey)","v":0,"name":"slog-rs","level":50,"time":"2022-07-05T11:29:32.744336041Z","hostname":"4fc53f5ce413","pid":1}
+mithril-signer-node-pool1_1 | {"msg":"Sleeping for 1000","v":0,"name":"slog-rs","level":30,"time":"2022-07-05T11:29:32.744352051Z","hostname":"4fc53f5ce413","pid":1}
+mithril-signer-node-pool2_1 | {"msg":"Signing digest","v":0,"name":"slog-rs","level":30,"time":"2022-07-05T11:29:32.73359119Z","hostname":"1c671096ee3f","pid":1,"digester_result":"DigesterResult {\n digest: \"e5ac1579a3fff12bf19ef88b0d9ec9d8a1c53e4d74c38c023b2e33638f454d67\",\n last_immutable_file_number: 17,\n}"}
+mithril-signer-node-pool2_1 | {"msg":"Register signatures","v":0,"name":"slog-rs","level":30,"time":"2022-07-05T11:29:32.733607821Z","hostname":"1c671096ee3f","pid":1}
+mithril-signer-node-pool2_1 | {"msg":"Epoch computation is not final and needs to be fixed: 4","v":0,"name":"slog-rs","level":40,"time":"2022-07-05T11:29:32.733623511Z","hostname":"1c671096ee3f","pid":1}
+mithril-signer-node-pool2_1 | {"msg":"SingleSignaturesComputeFailed(UnregisteredVerificationKey)","v":0,"name":"slog-rs","level":50,"time":"2022-07-05T11:29:32.733786246Z","hostname":"1c671096ee3f","pid":1}
+mithril-signer-node-pool2_1 | {"msg":"Sleeping for 1000","v":0,"name":"slog-rs","level":30,"time":"2022-07-05T11:29:32.733802416Z","hostname":"1c671096ee3f","pid":1}
+
+=====================================================================
+=====================================================================
+tail -n 22 ./node-bft1/node.log
+=====================================================================
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:28.01 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 219, dsSuffix = Nothing} at 075fc8366d353b45debedfc6faa92148c8fad584d81dbb4ea7b8b4d121489452 at slot 219
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:40.76 UTC] Chain extended, new tip: af93c6964de49d0696bf194c222f6e5a40e5123ef688a20613a33a705b6b736a at slot 253
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:40.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 228, dsSuffix = Nothing} at 720c625a259a23f21926fe7a30dad9b7a4b50958a508c8cfdc96a94625fbf00d at slot 228
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:43.75 UTC] Chain extended, new tip: 9f141fe78c0baa433c2554d3a09a9b43c47faa7b740be254893000310e5bad3b at slot 257
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:52.76 UTC] Chain extended, new tip: bfc0b2c1c4d06699efcdf6ad7b33c48cea722fb4bb5c5d6761a3768609cf77a4 at slot 269
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:52.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 253, dsSuffix = Nothing} at af93c6964de49d0696bf194c222f6e5a40e5123ef688a20613a33a705b6b736a at slot 253
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:03.26 UTC] Chain extended, new tip: c6238e98f186278eeef86d13f3482ebfb9b1d01d2a28da78282bfd241524eccd at slot 283
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:03.26 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 257, dsSuffix = Nothing} at 9f141fe78c0baa433c2554d3a09a9b43c47faa7b740be254893000310e5bad3b at slot 257
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:04.75 UTC] Chain extended, new tip: ac332aea5f043b3fd5ac68a04225932a21935ad7e5c5cfbb7e5b0b00df713bff at slot 285
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:16.00 UTC] Chain extended, new tip: e68d08e0c127a5346a74dd06713d8de0b4e37e338a0e03987da356bb70892b99 at slot 300
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:16.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 283, dsSuffix = Nothing} at c6238e98f186278eeef86d13f3482ebfb9b1d01d2a28da78282bfd241524eccd at slot 283
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:18.25 UTC] Chain extended, new tip: bc07b985d7f76bacc0a726b2dc5aa76a7254f1e4548a633cdfd62c31e022b3a5 at slot 303
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:37.00 UTC] Chain extended, new tip: 7d53c5eba9679c96ba32d79a02cfd953280b3477f1dd8eeb18447638c8a30e20 at slot 328
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:37.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 300, dsSuffix = Nothing} at e68d08e0c127a5346a74dd06713d8de0b4e37e338a0e03987da356bb70892b99 at slot 300
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:58.75 UTC] Chain extended, new tip: 3e9734018c585eea160a33accf82f758713f0e7aae1fab4dc40bccd859b8066f at slot 357
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:58.75 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 303, dsSuffix = Nothing} at bc07b985d7f76bacc0a726b2dc5aa76a7254f1e4548a633cdfd62c31e022b3a5 at slot 303
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:05.50 UTC] Chain extended, new tip: 8876850840ae52ca240d517def4b9c8a5db98e2e7db17f8abf87e4f12db13d15 at slot 366
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:05.50 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 328, dsSuffix = Nothing} at 7d53c5eba9679c96ba32d79a02cfd953280b3477f1dd8eeb18447638c8a30e20 at slot 328
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:19.75 UTC] Chain extended, new tip: 5733ec701db5c9dc253dd4b611421de0c2d223e6ee99c8d61010a9fea42d504b at slot 385
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:19.75 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 357, dsSuffix = Nothing} at 3e9734018c585eea160a33accf82f758713f0e7aae1fab4dc40bccd859b8066f at slot 357
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:31.00 UTC] Chain extended, new tip: 331c824ebee92dee7717f7bcc1457ac89b0de33d76073e6edd97a28770fa364b at slot 400
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:31.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 366, dsSuffix = Nothing} at 8876850840ae52ca240d517def4b9c8a5db98e2e7db17f8abf87e4f12db13d15 at slot 366
+=====================================================================
+
+=====================================================================
+tail -n 22 ./node-pool1/node.log
+=====================================================================
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:28.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 219, dsSuffix = Nothing} at 075fc8366d353b45debedfc6faa92148c8fad584d81dbb4ea7b8b4d121489452 at slot 219
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:40.76 UTC] Chain extended, new tip: af93c6964de49d0696bf194c222f6e5a40e5123ef688a20613a33a705b6b736a at slot 253
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:40.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 228, dsSuffix = Nothing} at 720c625a259a23f21926fe7a30dad9b7a4b50958a508c8cfdc96a94625fbf00d at slot 228
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:43.76 UTC] Chain extended, new tip: 9f141fe78c0baa433c2554d3a09a9b43c47faa7b740be254893000310e5bad3b at slot 257
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:52.75 UTC] Chain extended, new tip: bfc0b2c1c4d06699efcdf6ad7b33c48cea722fb4bb5c5d6761a3768609cf77a4 at slot 269
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:52.75 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 253, dsSuffix = Nothing} at af93c6964de49d0696bf194c222f6e5a40e5123ef688a20613a33a705b6b736a at slot 253
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:03.26 UTC] Chain extended, new tip: c6238e98f186278eeef86d13f3482ebfb9b1d01d2a28da78282bfd241524eccd at slot 283
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:03.26 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 257, dsSuffix = Nothing} at 9f141fe78c0baa433c2554d3a09a9b43c47faa7b740be254893000310e5bad3b at slot 257
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:04.75 UTC] Chain extended, new tip: ac332aea5f043b3fd5ac68a04225932a21935ad7e5c5cfbb7e5b0b00df713bff at slot 285
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:16.00 UTC] Chain extended, new tip: e68d08e0c127a5346a74dd06713d8de0b4e37e338a0e03987da356bb70892b99 at slot 300
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:16.01 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 283, dsSuffix = Nothing} at c6238e98f186278eeef86d13f3482ebfb9b1d01d2a28da78282bfd241524eccd at slot 283
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:18.25 UTC] Chain extended, new tip: bc07b985d7f76bacc0a726b2dc5aa76a7254f1e4548a633cdfd62c31e022b3a5 at slot 303
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:37.00 UTC] Chain extended, new tip: 7d53c5eba9679c96ba32d79a02cfd953280b3477f1dd8eeb18447638c8a30e20 at slot 328
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:37.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 300, dsSuffix = Nothing} at e68d08e0c127a5346a74dd06713d8de0b4e37e338a0e03987da356bb70892b99 at slot 300
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:58.76 UTC] Chain extended, new tip: 3e9734018c585eea160a33accf82f758713f0e7aae1fab4dc40bccd859b8066f at slot 357
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:58.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 303, dsSuffix = Nothing} at bc07b985d7f76bacc0a726b2dc5aa76a7254f1e4548a633cdfd62c31e022b3a5 at slot 303
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:05.50 UTC] Chain extended, new tip: 8876850840ae52ca240d517def4b9c8a5db98e2e7db17f8abf87e4f12db13d15 at slot 366
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:05.51 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 328, dsSuffix = Nothing} at 7d53c5eba9679c96ba32d79a02cfd953280b3477f1dd8eeb18447638c8a30e20 at slot 328
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:19.75 UTC] Chain extended, new tip: 5733ec701db5c9dc253dd4b611421de0c2d223e6ee99c8d61010a9fea42d504b at slot 385
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:19.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 357, dsSuffix = Nothing} at 3e9734018c585eea160a33accf82f758713f0e7aae1fab4dc40bccd859b8066f at slot 357
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:31.00 UTC] Chain extended, new tip: 331c824ebee92dee7717f7bcc1457ac89b0de33d76073e6edd97a28770fa364b at slot 400
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:31.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 366, dsSuffix = Nothing} at 8876850840ae52ca240d517def4b9c8a5db98e2e7db17f8abf87e4f12db13d15 at slot 366
+=====================================================================
+
+=====================================================================
+tail -n 22 ./node-pool2/node.log
+=====================================================================
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:28.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 219, dsSuffix = Nothing} at 075fc8366d353b45debedfc6faa92148c8fad584d81dbb4ea7b8b4d121489452 at slot 219
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:40.75 UTC] Chain extended, new tip: af93c6964de49d0696bf194c222f6e5a40e5123ef688a20613a33a705b6b736a at slot 253
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:40.75 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 228, dsSuffix = Nothing} at 720c625a259a23f21926fe7a30dad9b7a4b50958a508c8cfdc96a94625fbf00d at slot 228
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:43.76 UTC] Chain extended, new tip: 9f141fe78c0baa433c2554d3a09a9b43c47faa7b740be254893000310e5bad3b at slot 257
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:27:52.75 UTC] Chain extended, new tip: bfc0b2c1c4d06699efcdf6ad7b33c48cea722fb4bb5c5d6761a3768609cf77a4 at slot 269
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:27:52.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 253, dsSuffix = Nothing} at af93c6964de49d0696bf194c222f6e5a40e5123ef688a20613a33a705b6b736a at slot 253
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:03.25 UTC] Chain extended, new tip: c6238e98f186278eeef86d13f3482ebfb9b1d01d2a28da78282bfd241524eccd at slot 283
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:03.25 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 257, dsSuffix = Nothing} at 9f141fe78c0baa433c2554d3a09a9b43c47faa7b740be254893000310e5bad3b at slot 257
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:04.75 UTC] Chain extended, new tip: ac332aea5f043b3fd5ac68a04225932a21935ad7e5c5cfbb7e5b0b00df713bff at slot 285
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:16.00 UTC] Chain extended, new tip: e68d08e0c127a5346a74dd06713d8de0b4e37e338a0e03987da356bb70892b99 at slot 300
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:16.01 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 283, dsSuffix = Nothing} at c6238e98f186278eeef86d13f3482ebfb9b1d01d2a28da78282bfd241524eccd at slot 283
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:18.25 UTC] Chain extended, new tip: bc07b985d7f76bacc0a726b2dc5aa76a7254f1e4548a633cdfd62c31e022b3a5 at slot 303
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:37.00 UTC] Chain extended, new tip: 7d53c5eba9679c96ba32d79a02cfd953280b3477f1dd8eeb18447638c8a30e20 at slot 328
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:37.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 300, dsSuffix = Nothing} at e68d08e0c127a5346a74dd06713d8de0b4e37e338a0e03987da356bb70892b99 at slot 300
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:28:58.76 UTC] Chain extended, new tip: 3e9734018c585eea160a33accf82f758713f0e7aae1fab4dc40bccd859b8066f at slot 357
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:28:58.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 303, dsSuffix = Nothing} at bc07b985d7f76bacc0a726b2dc5aa76a7254f1e4548a633cdfd62c31e022b3a5 at slot 303
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:05.50 UTC] Chain extended, new tip: 8876850840ae52ca240d517def4b9c8a5db98e2e7db17f8abf87e4f12db13d15 at slot 366
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:05.50 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 328, dsSuffix = Nothing} at 7d53c5eba9679c96ba32d79a02cfd953280b3477f1dd8eeb18447638c8a30e20 at slot 328
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:19.75 UTC] Chain extended, new tip: 5733ec701db5c9dc253dd4b611421de0c2d223e6ee99c8d61010a9fea42d504b at slot 385
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:19.76 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 357, dsSuffix = Nothing} at 3e9734018c585eea160a33accf82f758713f0e7aae1fab4dc40bccd859b8066f at slot 357
+[jp:cardano.node.ChainDB:Notice:21] [2022-07-05 11:29:31.00 UTC] Chain extended, new tip: 331c824ebee92dee7717f7bcc1457ac89b0de33d76073e6edd97a28770fa364b at slot 400
+[jp:cardano.node.ChainDB:Info:25] [2022-07-05 11:29:31.00 UTC] Took ledger snapshot DiskSnapshot {dsNumber = 366, dsSuffix = Nothing} at 8876850840ae52ca240d517def4b9c8a5db98e2e7db17f8abf87e4f12db13d15 at slot 366
+=====================================================================
+
+```
+
+## Interact with the Mithril Aggregator by using the Mithril Client
+
+### Step 1: Prepare some useful variables
+
+```bash
+# Cardano network
+NETWORK=devnet
+
+# Aggregator API endpoint URL
+AGGREGATOR_ENDPOINT=http://localhost:8080/aggregator
+
+# 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
+SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/snapshots | jq -r '.[0].digest')
+```
+
+### Step 2: Select A Snapshot
+
+List the available snapshots with which you can bootstrap a Cardano node
+
+```bash
+NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client list
+```
+
+You will see a list of snapshots
+
+```bash
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+| Network | Digest | Size | Locations | Created |
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+| devnet | 85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917 | 11808 | 1 | 2022-07-04T16:47:00.258482685Z |
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+| devnet | 60d9c6e014d22335b34f55f83da728667f04fc1c63152ccff0bce7d217d08447 | 10793 | 1 | 2022-07-04T16:46:45.069646321Z |
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+| devnet | a3c4bb5f413f1b9648f0a086b3752d25ec62b540b8390917a5a7e78809896d92 | 7991 | 1 | 2022-07-04T16:46:09.817821220Z |
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+| devnet | b952adaa04dbb42206c69589b9951660f40c7262b088b13434b7a446ec90bc36 | 6746 | 1 | 2022-07-04T16:45:49.616260734Z |
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+| devnet | 46425fdcfe89ad5ba41a7822a4395e21b539e80c20e2b10546017b14cdcd4e4b | 6196 | 1 | 2022-07-04T16:45:29.425195132Z |
++---------+------------------------------------------------------------------+-------+-----------+--------------------------------+
+```
+
+### Step 3: Show Snapshot Details
+
+Get some more details from a specific snapshot (Optional)
+
+```bash
+NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client show $SNAPSHOT_DIGEST
+```
+
+You will see more information about a snapshot
+
+```bash
++------------+-------------------------------------------------------------------------------------------------------------------+
+| Info | Value |
++------------+-------------------------------------------------------------------------------------------------------------------+
+| Network | devnet |
++------------+-------------------------------------------------------------------------------------------------------------------+
+| Digest | 85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917 |
++------------+-------------------------------------------------------------------------------------------------------------------+
+| Size | 11808 |
++------------+-------------------------------------------------------------------------------------------------------------------+
+| Location 1 | http://0.0.0.0:8080/aggregator/snapshot/85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917/download |
++------------+-------------------------------------------------------------------------------------------------------------------+
+| Created | 2022-07-04T16:47:00.258482685Z |
++------------+-------------------------------------------------------------------------------------------------------------------+
+```
+
+### Step 4: Download Selected Snapshot
+
+Download the selected snapshot from the remote location to your remote location
+
+```bash
+NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client download $SNAPSHOT_DIGEST
+```
+
+You will see that the selected snapshot archive has been downloaded locally
+
+```bash
+Download success 85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917 #1
+from http://0.0.0.0:8080/aggregator/snapshot/85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917/download
+to /home/mithril/data/devnet /85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917/snapshot.archive.tar.gz
+```
+
+### Step 5: Restore Selected Snapshot
+
+Verify the Certificate of the snapshot and unpack its content in order to feed the Cardano node database
+
+```bash
+NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client restore $SNAPSHOT_DIGEST
+```
+
+You will see that the snapshot archive is unpacked and that the associated certificate is valid
+
+```bash
+Unpacking snapshot...
+Unpack success 85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917
+to /home/mithril/data/devnet /85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917/db
+
+Restore a Cardano Node with:
+
+docker run -v cardano-node-ipc:/ipc -v cardano-node-data:/data \
+ --mount type=bind,source="./data/devnet/85f09b39b0b5a13cec9d8fe7ffb82b5e5f236f02ae896f4e47b77e5cd1f2a917/db",target=/data/db/ \
+ -e NETWORK=devnet \
+ inputoutput/cardano-node
+```
diff --git a/docs/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md b/docs/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md
new file mode 100644
index 00000000000..422e8977ee6
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/getting-started/run-signer-node.md
@@ -0,0 +1,270 @@
+---
+sidebar_position: 2
+---
+
+import NetworksMatrix from '../../networks-matrix.md';
+
+# Run a Mithril Signer node (SPO)
+
+:::info
+
+In this guide, you will learn how to setup a **Mithril Signer** on top of a **Cardano SPO Node** for the `testnet`.
+
+:::
+
+:::note Mithril Networks
+
+
+
+:::
+
+:::danger
+
+This guide is working only on a Linux machine.
+
+:::
+
+:::tip
+
+For more information about the **Mithril Protocol**, please refer to the [About Mithril](../../mithril/intro.md) section.
+
+:::
+
+## Pre-requisites
+
+## What you'll need
+
+* Operating a **Cardano Node** as a **Stake Pool**:
+ * **Stable**:
+ * The Cardano `Operational Certificate` file of the pool
+ * The Cardano `KES Secret Key` file of the pool
+ * **Deprecated**: The Cardano `Pool Id` in a `BECH32` format such as `pool1frevxe70aqw2ce58c0muyesnahl88nfjjsp25h85jwakzgd2g2l`
+
+* Access to the file system of a `relay` **Cardano Node** running on the `testnet`:
+ * Read rights on the `Database` folder (`--database-path` setting of the **Cardano Node**)
+ * Read/Write rights on the `Inter Process Communication` file (usually `CARDANO_NODE_SOCKET_PATH` env var used to launch the **Cardano Node**)
+
+* Install a recent version of the [`cardano-cli`](https://hydra.iohk.io/job/Cardano/cardano-node/linux.native.cardano-cli) (version 1.35.4+)
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+* Install OpenSSL development libraries, for example on Ubuntu/Debian/Mint run `apt install libssl-dev`
+
+* Ensure the SQLite3 version is at lease `3.35` (released Apr. 2021)
+
+## Mithril Keys Certification
+
+:::danger
+
+The cryptographic certification of the Mithril keys is an experimental feature. We strongly recommend that you first setup a Mithril Signer node in the stable mode. Once you are able to sign in the stable mode is a good time to start experimenting with the keys certification.
+
+Your feedback is very important, so feel free to contact us on the #moria channel on the IOG [Discord server](https://discord.gg/5kaErDKDRq), or to file an issue on GitHub.
+
+:::
+
+### Stable mode: Certify your Pool Id
+
+In this mode, you declare your Cardano `Operational Certificate` file and `KES Secret Key` file which allows to:
+
+* Compute automatically the `PoolId`
+* Verify that you are the owner of the `PoolId`, and thus of the associated stakes used by Mithril protocol
+* Verify that you are the owner of the Mithril `Signer Secret Key`, and thus allowed to contribute to the multi-signatures and certificate production of the Mithril network
+
+This mode is displayed with a specific **Stable** mention in this document.
+
+### Deprecated mode: Declare your Pool Id
+
+In this mode, the Cardano `Pool Id` that you specify is not strictly verified. It is associated to Cardano stakes based on your declaration. This mode is deprecated and replaced by the certification mode above.
+
+This mode is presented in the setup of this document with a specific **Deprecated** mention.
+
+## Building your own executable
+
+### Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+### Build Mithril Signer binary
+
+Change directory
+
+```bash
+cd mithril/mithril-signer
+```
+
+Run tests (Optional)
+
+```bash
+make test
+```
+
+Build executable
+
+```bash
+make build
+```
+
+### Verify build
+
+Check that the Mithril Signer binary is working fine by running its help
+
+```bash
+./mithril-signer -h
+```
+
+You should see
+
+```bash
+mithril-signer
+An implementation of a Mithril Signer
+
+USAGE:
+ mithril-signer [OPTIONS]
+
+OPTIONS:
+ -h, --help Print help information
+ -r, --run-mode Run Mode [default: dev]
+ -v, --verbose Verbosity level
+```
+
+:::tip
+
+If you want to dig deeper, you can get access to several level of logs from the Mithril Signer:
+
+* Add `-v` for some logs (WARN)
+* Add `-vv` for more logs (INFO)
+* Add `-vvv` for even more logs (DEBUG)
+* Add `-vvvv` for all logs (TRACE)
+
+:::
+
+### Move executable
+
+Move executable to /opt/mithril
+
+```bash
+sudo mkdir -p /opt/mithril
+sudo mv mithril-signer /opt/mithril
+```
+
+### Setup the service
+
+:::caution
+
+* `User=cardano`:
+Replace this value with the correct user. We assume that the user used to run the **Cardano Node** is `cardano`. The **Mithril Signer** must imperatively run with the same user.
+
+* **Stable mode**: in the `/opt/mithril/mithril-signer/service.env` env file:
+ * `KES_SECRET_KEY_PATH=/cardano/keys/kes.skey`: replace `/cardano/keys/kes.skey` with the path to your Cardano `KES Secret Key` file
+ * `OPERATIONAL_CERTIFICATE_PATH=/cardano/cert/opcert.cert`: replace `/cardano/cert/opcert.cert` with the path to your Cardano `Operational Certificate` file
+ * `DB_DIRECTORY=/cardano/db`: replace `/cardano/db` with the path to the database folder of the **Cardano Node** (the one in `--database-path`)
+ * `CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket`: replace with the path to the IPC file (`CARDANO_NODE_SOCKET_PATH` env var)
+ * `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).
+
+* **Deprecated mode**: in the `/opt/mithril/mithril-signer/service.env` env file:
+ * `PARTY_ID=YOUR_POOL_ID_BECH32`: replace `YOUR_POOL_ID_BECH32` with your BECH32 `Pool Id`
+ * `DB_DIRECTORY=/cardano/db`: replace `/cardano/db` with the path to the database folder of the **Cardano Node** (the one in `--database-path`)
+ * `CARDANO_NODE_SOCKET_PATH=/cardano/ipc/node.socket`: replace with the path to the IPC file (`CARDANO_NODE_SOCKET_PATH` env var)
+ * `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).
+
+:::
+
+First create an env file that will be used by the service:
+
+* **Stable mode**:
+
+```bash
+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_CARDANO_NETWORK**
+AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
+RUN_INTERVAL=60000
+DB_DIRECTORY=/cardano/db
+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
+EOF'
+```
+
+* **Deprecated mode**:
+
+```bash
+sudo bash -c 'cat > /opt/mithril/mithril-signer.env << EOF
+PARTY_ID=**YOUR_POOL_ID_BECH32**
+NETWORK=**YOUR_CARDANO_NETWORK**
+AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
+RUN_INTERVAL=60000
+DB_DIRECTORY=/cardano/db
+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
+EOF'
+```
+
+Then we will create a `/etc/systemd/system/mithril-signer.service` description file for our service
+
+```bash
+sudo bash -c 'cat > /etc/systemd/system/mithril-signer.service << EOF
+[Unit]
+Description=Mithril Signer service
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+Restart=always
+RestartSec=1
+User=cardano
+EnvironmentFile=/opt/mithril/mithril-signer.env
+ExecStart=/opt/mithril/mithril-signer -vvv
+
+[Install]
+WantedBy=multi-user.target
+EOF'
+```
+
+Reload the service configuration (Optional)
+
+```bash
+sudo systemctl daemon-reload
+```
+
+Then start the service
+
+```bash
+sudo systemctl start mithril-signer
+```
+
+Then register the service to start on boot
+
+```bash
+sudo systemctl enable mithril-signer
+```
+
+Then monitor status of the service
+
+```bash
+systemctl status mithril-signer.service
+```
+
+And monitor the logs of the service
+
+```bash
+tail /var/log/syslog
+```
diff --git a/docs/versioned_docs/version-maintained/manual/welcome.md b/docs/versioned_docs/version-maintained/manual/welcome.md
new file mode 100644
index 00000000000..82fd6badda5
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/manual/welcome.md
@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+sidebar_label: Welcome
+---
+
+# User Manual
+
+Welcome to the **Mithril** user manual!
+
+Let's discover **Mithril in less than 5 minutes**.
+
+## Introduction
+
+A **Mithril Network** is composed of 3 main components:
+
+* **Mithril Aggregator**:
+
+This node is in charge of **coordinating the production of the Cardano snapshot archives** (along with the associated certificates powered by Mithril multi signatures) by interacting with Mithril Signer nodes and a Cardano node.
+
+* **Mithril Signer**:
+
+This node is in charge of **producing single signatures that are then combined into a multi signature** by the Mithril Aggregator. It works side by side with a Cardano node that has stakes in the network (Stake Pool Operator or SPO).
+
+* **Mithril Client**:
+
+This node is in charge of **verifying and restoring a snapshot** that will allow a lightning fast bootstrapping of a Cardano full node.
+
+:::tip
+
+For more information about the **Mithril Protocol**, please refer to the [About Mithril](../mithril/intro.md) section.
+
+:::
+
+## What you'll need
+
+* A Linux (preferred) or a macOS computer.
+
+* A [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+* A recent version of [Docker Engine](https://docs.docker.com/engine/install/).
+
+* A recent version of [Docker Compose](https://docs.docker.com/compose/install/).
+
+* A recent version of [`jq`](https://stedolan.github.io/jq/) (1.6+).
+
+## What you'll find in the user manual
+
+In the [**Getting Started**](/doc/category/getting-started) guide, you will find tutorials for:
+
+* :new: As someone who needs to [Bootstrap a Cardano node](./getting-started/bootstrap-cardano-node.md) on the `testnet`.
+
+* As an SPO who wants to [Run a Mithril Signer node](./getting-started/run-signer-node.md) on the `testnet`.
+
+* As someone who wants to [Run a Private Mithril network](./getting-started/run-mithril-devnet.md) on the `devnet`.
+
+In the [**Developer Docs**](/doc/category/developer-docs), you will find documentation for:
+
+* The **Mithril Network Nodes**:
+ * The [**Mithril Aggregator Node**](./developer-docs/nodes/mithril-aggregator.md) developer documentation.
+ * The [**Mithril Signer Node**](./developer-docs/nodes/mithril-signer.md) developer documentation.
+ * The [**Mithril Client Node**](./developer-docs/nodes/mithril-client.md) developer documentation.
+
+* The [API Reference](./developer-docs/references.md) guide.
+
+:::tip
+
+If you need help, feel free to reach the **Mithril** team:
+
+* [Github Discussions](https://github.com/input-output-hk/mithril/discussions)
+
+* [Stack Exchange](https://cardano.stackexchange.com/questions/tagged/mithril)
+
+:::
diff --git a/docs/versioned_docs/version-maintained/mithril/intro.md b/docs/versioned_docs/version-maintained/mithril/intro.md
new file mode 100644
index 00000000000..4d094cabd76
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/intro.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+---
+
+# About Mithril
+
+:::info New
+
+:new: Interact with the **Mithril Protocol** by experiencing with our [protocol simulation](./mithril-protocol/simulation.md). This will help you understand how the participants interact to create a multi signature and what's the impact of the protocol parameters.
+
+:::
+
+## Mithril in a nutshell
+
+**Mithril** is a research project which goal is to provide [Stake-based Threshold Multisignatures](https://iohk.io/en/research/library/papers/mithrilstake-based-threshold-multisignatures/) on top of the **Cardano Network**.
+
+In a nutshell, **Mithril** can be summarized as:
+
+> A protocol that allows **stakeholders** in a **Proof-of-Stake** blockchain network to individually **sign messages** that are aggregated into a **multi signature** which guarantees that they represent a minimum share of the total stakes.
+
+In other words, an adversarial participant with less than this share of the total stakes will not be able to produce valid multi signatures :closed_lock_with_key:.
+
+## What you'll find in this guide
+
+In this **About Mithril** guide, you will find:
+
+* Documentation on the **Mithril Protocol**:
+
+ * The [Mithril Protocol in depth](./mithril-protocol/protocol.md)
+
+ * The [Mithril Certificate Chain in depth](./mithril-protocol/certificates.md)
+
+ * :new: An interactive discovery of the protocol with the [Mithril Simulation](./mithril-protocol/simulation.md)
+
+* Documentation on the **Mithril Network**:
+
+ * The [Mithril Network architecture](./mithril-network/architecture.md)
+
+ * The [Mithril Aggregator node](./mithril-network/aggregator.md)
+
+ * The [Mithril Signer node](./mithril-network/signer.md)
+
+ * The [Mithril Client node](./mithril-network/client.md)
+
+:::tip
+
+If you need help, feel free to reach the **Mithril** team:
+
+* [Github Discussions](https://github.com/input-output-hk/mithril/discussions)
+
+* [Stack Exchange](https://cardano.stackexchange.com/questions/tagged/mithril)
+
+:::
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/_category_.json b/docs/versioned_docs/version-maintained/mithril/mithril-network/_category_.json
new file mode 100644
index 00000000000..56e9cbadb39
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-network/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Mithril Network",
+ "collapsible": true,
+ "collapsed": false,
+ "position": 2,
+ "link": {
+ "type": "generated-index",
+ "title": "Mithril Network Topics"
+ }
+}
\ No newline at end of file
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/aggregator.md b/docs/versioned_docs/version-maintained/mithril/mithril-network/aggregator.md
new file mode 100644
index 00000000000..bfcfc659583
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-network/aggregator.md
@@ -0,0 +1,111 @@
+---
+sidebar_position: 2
+sidebar_label: Mithril Aggregator
+---
+
+# Mithril Aggregator Node
+
+Welcome to the Mithril Aggregator Node guide!
+
+## Introduction
+
+:::info
+
+The **Mithril Aggregator** is a trustless node that orchestrates the work of the **Mithril Signer** nodes and that gathers their individual signatures to produce **Mithril** multi signatures and their associated certificates. It is also in charge of creating and storing the ledger state snapshot archive.
+
+:::
+
+:::tip
+
+* For more information about the **Mithril Protocol**, please refer to the [Protocol in depth](../mithril-protocol/protocol.md) page.
+
+* For more information about the **Mithril Aggregator**, please refer to the [Developer Documentation](../../manual/developer-docs/nodes/mithril-aggregator.md) page.
+
+:::
+
+## Trustless Orchestration
+
+The primary goal of the **Mithril Aggregator** is to orchestrate and synchronize the **Mithril multi signatures** production:
+
+* When a new snapshot is ready to be produced (and certified), the **Mithril Aggregator** creates and broadcasts a new **Beacon** that indicates to the **Mithril Signers** which point in time they should use to compute the message (or digest) to sign.
+
+* It is also responsible for advertising the **Verification Keys** (Mithril public keys) of all the registered **Mithril Signers**.
+
+* The **Beacon**, the current **Protocol Parameters** and the available **Verification Keys** are gathered and advertised in a **Pending Certificate**.
+
+* The **Mithril Signers** can register with it, in order to be able to later participate in the signature process.
+
+An important fact is that the **Mithril Aggregator** is trustless:
+
+* Anyone could run an aggregator on the network.
+
+* It does not broadcast any _sensitive_ information (such as the _message_ that needs to be signed). The signer nodes are responsible for computing these information directy from a **Cardano Node** on top of which they run.
+
+Also, in order to aggregate single signatures into **Mithril multi signatures**, the *_Mithril Aggregator_ does not need to represent any share of the total stakes of the **Cardano Network**.
+
+## Multi Signature and Certificate Production
+
+The **Mithril Aggregator** is in charge of producing the **Mithril multi signatures** and their associated certificates for a part and/or all of the ledger state (the snapshots):
+
+* The previously registered **Mithril Signers** are able to produce individual signatures. They send these individual signatures to the **Mithril Aggregator** that checks their validity and then store them.
+
+* Once the **quorum** of individual signatures has been reached, the **Mithril Aggregator** is able to produce a multi signature.
+
+* The **Mithril Aggregator** combines the multi signature and some metadata into a **Mithril Certificate** that will be later used by the **Mithril Client** to verify the authenticity of a snapshot.
+
+:::tip
+
+For more information about the **Mithril Certificate Chain**, please refer to the [Certificate Chain](../mithril-protocol/certificates.md) page.
+
+:::
+
+## Snapshot Artifacts Production
+
+In its first version, the **Mithril Aggregator** also takes care of producing the artifacts associated to the snapshot (e.g. the snapshot archive that will be later used by a **Mithril Client**).
+
+:::note
+
+It is worthy to mention that this role is endorsed only for convenience at the moment, and that on the long run the artifacts production will be delegated to a separate **Mithril Snapshotter** node.
+
+:::
+
+Once the snapshot artifact is created, it can be synchronized anywhere:
+
+* On the **Mithril Aggregator** itself.
+
+* On any cloud platform that provides a CDN.
+
+* On a separate peer to peer network (such as **IPFS** or **Bittorrent**).
+
+The **Mithril Certificate** is part of a chain of certificates that are involved in the snapshot authenticity verification and is stored:
+
+* On the **Mithril Aggregator** itself
+
+* Or on any accessible storage (as a cloud storage for example)
+
+## Snapshot Artifacts and Certificate Distribution
+
+In case the **Mithril Aggregator** stores the snapshot artifacts and/or the certificates, it can be used to distribute these data to remote clients. These clients can use them according to their need and verify that are genuine.
+
+## Under the hood
+
+In its first version, the **Mithril Aggregator** is composed of two main components:
+
+* A REST API, that enables the **Mithril Signers** to:
+ * Retrieve other registered signers **Verification Keys**.
+ * Register their **Verification Keys**.
+ * Register their **Individual Signatures**.
+
+:::tip
+
+The documentation of the REST API of the **Mithril Aggregator** is available [here](/aggregator-api).
+
+:::
+
+* A runtime that is powered by a state machine:
+ * The runtime is synchronous and is scheduled to execute at regular intervals.
+ * There are three possible states: **IDLE** , **READY** and **SIGNING**.
+ * The runtime handles state transitions.
+ * The runtime is summarized in the diagram below:
+
+
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/architecture.md b/docs/versioned_docs/version-maintained/mithril/mithril-network/architecture.md
new file mode 100644
index 00000000000..d7ce41c2aaa
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-network/architecture.md
@@ -0,0 +1,49 @@
+---
+sidebar_position: 1
+sidebar_label: Architecture
+---
+
+# Mithril Network Architecture
+
+Welcome to the Mithril Network Architecture guide!
+
+:::tip
+
+For more information about the **Mithril Protocol**, please refer to the [About Mithril](../mithril-protocol/protocol.md) section.
+
+:::
+
+## Introduction
+
+In its current version, the **Mithril Network** is a network of nodes responsible for creating **Snapshots** and **Certificates** that enable fast bootstrap of a **Cardano Node**. It runs on top of the **Cardano Network**.
+
+:::info
+
+The role of a Mithril Network is to enable end users to restore a full Cardano node in less than 2 hours!
+
+:::
+
+It is basically composed of three nodes:
+
+* [**Mithril Aggregator**](./aggregator.md):
+
+> The trustless node that orchestrates the work of the Mithril Signer nodes and that gathers their individual signatures to produce Mithril multi signatures and their associated certificates. It is also in charge of creating and storing the ledger state snapshot archive.
+
+* [**Mithril Signer**](./signer.md):
+
+> The node that works transparently on top of the Stake Pool Operator Cardano nodes and which individually signs the ledger state.
+
+* [**Mithril Client**](./client.md):
+
+> The node used to restore a Cardano full node by retrieving, from a Mithril Aggregator, a remote snapshot, its certificate chain and by verifying their validity thanks to the Mithril cryptographic primitives.
+
+## Architecture Overview
+
+:::info
+
+* This document is subject to change as it is a work in progress.
+* We are currenty working on **decentralizing** further the somewhat **centralized** architecture.
+
+:::
+
+[](images/architecture.jpg)
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/client.md b/docs/versioned_docs/version-maintained/mithril/mithril-network/client.md
new file mode 100644
index 00000000000..4ea614f2310
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-network/client.md
@@ -0,0 +1,68 @@
+---
+sidebar_position: 4
+sidebar_label: Mithril Client
+---
+
+# Mithril Client Node
+
+Welcome to the Mithril Client Node guide!
+
+## Introduction
+
+:::info
+
+The **Mithril Client** node is used to restore a **Cardano full node** by retrieving, from a **Mithril Aggregator**, a remote snapshot, its certificate chain and by verifying their validity thanks to the Mithril cryptographic primitives.
+
+:::
+
+:::tip
+
+* For more information about the **Mithril Protocol**, please refer to the [Protocol in depth](../mithril-protocol/protocol.md) page.
+
+* For more information about the **Mithril Client**, please refer to the [Developer Documentation](../../manual/developer-docs/nodes/mithril-client.md) page.
+
+:::
+
+## Usecases
+
+At a first glance, a **Mithril Client** can be used by any user that needs to restore and bootstrap rapidly a **Cardano full node**:
+
+* A full node wallet such as **Daedalus**
+* A node operator (SPO, Exchange, Dapp)
+
+On the long run, the **Mithril Client** is intended to be incorporated in **Light Clients** and **Wallets**.
+
+## Snapshot Artifacts Retrieval
+
+The first operation that a **Mithril Client** does is to retrieve snapshot artifacts from a remote source.
+
+The **Mithril Aggregator** is used as a provider for the **Snapshots** (at least their locations).
+
+This is done upon a manual action of a user that has previously selected the snapshot to use (if multiple are available).
+
+These artifacs are stored locally on a temporary location, are uncompressed if necessary and used to compute the message that should have been computed and signed by the **Mithril Signers**.
+
+## Snapshot Verification
+
+Along with the snapshot artifacts, the **Mithril Client** will download the associated **Certificate Chain** and for each **Mithril Certificate** verify that (in the following order):
+
+1. The certificate is not tampered (by computing its hash and verifying that is is the same as the one used for downloading it).
+2. The locally computed **message** is the same as in the certificate.
+3. The **multi signature** of the certificate is valid and computed with the certificate **message**.
+4. The stake distribution used to compute the multi signature is signed:
+ * Into a multi signature of a previous certificate of the chain (if there is one available).
+ * Or by a valid **Genesis Certificate** (in case this is the first certificate of the chain).
+
+The **Mithril Aggregator** is used as a provider for the **Certificate Chain**.
+
+:::tip
+
+For more information about the **Mithril Certificate Chain**, please refer to the [Certificate Chain](../mithril-protocol/certificates.md) page.
+
+:::
+
+## Snapshot Restoration
+
+Once the snapshot artifacts are verified, the **Mithril Client** node will move them from the temporary location to the final (user specified) location.
+
+At this point, the **Cardano Node** will take over, start using the artifacts. and hopefully start addng new blocks to the ledger!
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/images/aggregator-runtime.jpg b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/aggregator-runtime.jpg
new file mode 100644
index 00000000000..dfad78c81a5
Binary files /dev/null and b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/aggregator-runtime.jpg differ
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/images/architecture.jpg b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/architecture.jpg
new file mode 100644
index 00000000000..a61810c5eb5
Binary files /dev/null and b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/architecture.jpg differ
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/images/signer-runtime.jpg b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/signer-runtime.jpg
new file mode 100644
index 00000000000..87bb5997ce8
Binary files /dev/null and b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/signer-runtime.jpg differ
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/images/signer-workflow.png b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/signer-workflow.png
new file mode 100644
index 00000000000..092fa3fc956
Binary files /dev/null and b/docs/versioned_docs/version-maintained/mithril/mithril-network/images/signer-workflow.png differ
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-network/signer.md b/docs/versioned_docs/version-maintained/mithril/mithril-network/signer.md
new file mode 100644
index 00000000000..68eed4c0e45
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-network/signer.md
@@ -0,0 +1,68 @@
+---
+sidebar_position: 3
+sidebar_label: Mithril Signer
+---
+
+# Mithril Signer Node
+
+Welcome to the Mithril Signer Node guide!
+
+## Introduction
+
+:::info
+
+The **Mithril Signer** is a node that works transparently on top of the **Stake Pool Operator** Cardano nodes and which individually signs the ledger state.
+
+:::
+
+:::tip
+
+* For more information about the **Mithril Protocol**, please refer to the [Protocol in depth](../mithril-protocol/protocol.md) page.
+
+* For more information about the **Mithril Signer**, please refer to the [Developer Documentation](../../manual/developer-docs/nodes/mithril-signer.md) page.
+
+:::
+
+## Individual Signatures Production
+
+The **Mithril Signer** is a node that represents a share of the total stake of the **Cardano Network** which entitles it to participate in the **Mithril multi signature** creation (with respect to its share of total stakes). The rule is simple, the more stake shares, the more contribution to the production of the multi signatures.
+
+In order to produce an **Individual Signature** a **Mithril Signer** must also be aware of all the other **Mithril Signers** that may contribute.
+
+For the protocol to be secure, the **Mithril Signer** must also be in charge of computing by itself the messages (or digest) that are signed. To do so, they heavily rely on the **Consensus** mechanism of the **Cardano Network** that guarantees that all nodes of the network will store the same data locally (after a certain delay).
+
+If some nodes are not fully synchronized or if they have adversarial behavior they will simple not be able to contribute:
+
+* Either because they don't sign the same message (given they don't use the same data as those agreed by the rest of the network)
+
+* Or they are not entitled to sign (because they are not true holders of the stake share they used to sign)
+
+## Interaction with the Mithril Aggregator
+
+In its first version, the **Mithril Signer** works with other **Mithril Signers** through one **Mithril Aggregator** which acts as a facilitator and avoids direct signer to signer communications.
+
+In the long run, any signer will also have the ability to be a **Mithril Aggregator** as well in order to achieve a higher level of decentralization in the **Mithril Network**.
+
+The **Mithril Signer** connects to the **Mithril Aggregator**:
+
+* To know when to sign a new snapshot (by using the advertised **Beacon** of the **Pending Certificate**).
+* To retrieve the currently used **Protocol Parameters**.
+* To register its **Verification Keys** (public keys).
+* To receive the **Verification Keys** of all the other declared signers available for the next message to sign.
+* To send the **Single Signatures** of the locally computed messages (that will hopefuly be combined into **Multi signatures** by the aggregator).
+
+This process is summarized in the following diagram:
+
+
+
+## Under the hood
+
+In its first version, the **Mithril Signer** is composed of a main component:
+
+* A runtime that is powered by a state machine:
+ * The runtime is synchronous and is scheduled to execute at regular intervals.
+ * There are three possible states: **UNREGISTERED**, **REGISTERED** and **SIGNED**.
+ * The runtime handles state transitions.
+ * The runtime is summarized in the diagram below:
+
+
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/_category_.json b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/_category_.json
new file mode 100644
index 00000000000..c03b858b985
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Mithril Protocol",
+ "collapsible": true,
+ "collapsed": false,
+ "position": 1,
+ "link": {
+ "type": "generated-index",
+ "title": "Mithril Protocol Topics"
+ }
+}
\ No newline at end of file
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/certificates.md b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/certificates.md
new file mode 100644
index 00000000000..b80a67b232c
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/certificates.md
@@ -0,0 +1,130 @@
+---
+sidebar_position: 2
+sidebar_label: Certificate Chain in depth
+---
+
+# Mithril Certificate Chain in depth
+
+## Introduction
+
+The **Mithril Protocol** can be summarized as:
+
+> A protocol that allows stakeholders in a Proof-of-Stake blockchain network to individually sign messages that are aggregated into a multi signature which guarantees that they represent a minimum share of the total stakes.
+
+The **stake distribution** that is used to create the multi signature can't be trusted "as is" and must also be signed. Indeed, any one could relatively easily create a **Fake Stake Distribution** and use it to produce a valid multi signature that would be embedded in a perfectly **Valid but Non Genuine Certificate**. This certificate could be served by a dishonest **Mithril Aggregator** node and thus could lead to restoring a non genuine snapshot by a honest **Mithril Client**.
+
+In order to avoid this type of **eclipse attack**, the **stake distribution** used to create a multi signature must be certified beforehand. This is where the **Certificate Chain** takes place.
+
+## The Certificate Chain Design
+
+:::danger
+
+The **Stake Distribution** of an epoch is computed by the **Cardano Nodes** at the end of this epoch. It will be usable from the beginning of the following epoch.
+
+:::
+
+A way to certify the **stake distribution** used to create a multi signature is to verify that it has been previously signed in an earlier certificate. Then one can recursively verify that the earlier certificate is valid the same way. This process can be designed as a **Chain** of certificates: the **Mithril Certificate Chain**.
+
+As multiple certificates may be created during the same epoch (i.e. with the same stake distribution), it is sufficient to link to only one certificate of the previous epoch: this will allow faster verification times and it will also avoid network congestion.
+
+Also, the certificate at the beginning of the **Certificate Chain** has a special role. This is the **Genesis Certificate**. The only way to validate the stake distributon embedded in the **Genesis Certificate** is to sign it with a private key that is associated to a broadly available public key: the **Genesis Keys**. These are the keys that sign the hard forks used during the era transitions of the Cardano Blockchain.
+
+Here is a diagram illustrating the **Certificate Chain** design:
+[](images/certificate-chain.jpg)
+
+Where the following notations have been used:
+
+* `C(p,n)`: Certificate at trigger `p` and epoch `n`
+* `FC(n)`: First Certificate of epoch `n`
+* `GC`: Genesis Certificate
+* `H()`: Hash
+* `SD(n)`: Stake Distribution of epoch `n`
+* `VK(n)`: Verification Key at epoch `n`
+* `AVK(n)`: Aggregrate Verification Key at epoch `n` such as `AVK(n) = MKT_ROOT(SD(n) || VK(n))`
+* `MKT_ROOT()`: Merkle-tree root
+* `BEACON(p,n)`: Beacon at trigger `p` and epoch `n`
+* `METADATA(p,n)`: Metadata of the certificate at trigger `p` and epoch `n`
+* `MSG(p,n)`: Message of the certificate at trigger `p` and epoch `n`
+* `MULTI_SIG(p,n)`: Multi signature created to the message `H(MSG(p,n) || AVK(n-1))`
+* `GENESIS_SIG(MSG)`: Genesis Signature, i.e. signature of `MSG` with the Genesis Keys
+
+The hash of a **Certificate** `H(C(p,n))` is computed as the concatenation (`||`) of all its fields. Therefore, if one field is modified, its hash is different.
+
+The informations embedded in the `METADATA(p,n)` field are:
+
+* The version of the Mithril Protocol
+* The parameter of the Mithril Protocol (`k`, `m`, and `phi_f`)
+* The date and time at which the multi signature creation was initiated
+* The date and time at which the Certificate was sealed
+* The list of the signers that actively contributed to the multi signature
+
+The message `MSG(p,n)` is a map of multiple values associated with their respective keys and provides a way to add more informations in the certificates without breaking the chain itself. These can be any message that the signers are able to compute deterministically thanks to the Cardano consensus: an immutable files snapshot, the Utxo set, the stahe distribution, ...
+
+:::note
+
+The **trigger** represents the instant at which a certificate should be created. It is combined, with at least the associated **epoch** to create the [**Beacon**](../../glossary.md#beacon) of the certificate. In the current implementation, this trigger is a new [**Immutable File Number**](../../glossary.md#immutable-file-number). The epoch creation and the trigger creation processes may be uncorrelated.
+
+:::
+
+:::info
+
+The `AVK` or **Aggregate Verification Key** is the root of the Merkle-tree where each leaf is filled with `H(STAKE(signer) || VK(signer))`. It represents the corresponding **Stake Distribution** in a condensed way.
+:::
+
+## The Verification Algorithm
+
+The **Certificate Chain** verification can be stated as:
+
+```
+CHAIN_VERIFY[C(p,n(p))] = CERT_VERIFY[C(p,n(p)] ^ CERT_VERIFY[FC(n(p))] ^ CERT_VERIFY[FC(n(p)-1)] ^ ... ^ CERT_VERIFY[FC(1)] ^ CERT_VERIFY[GC]
+```
+
+Where the following notations have been used:
+
+* The epoch `n(p)` depends on the trigger `p`
+* `CHAIN_VERIFY[]`: Verify all the chain backward from a certificate
+* `CERT_VERIFY[]`: Verify a specific certificate
+
+A **Certificate Chain** is valid if from a **Certificate**, up to the **Genesis Certificate** of the chain there is at least one valid certificate per epoch.
+
+A non **Genesis Certificate** is valid **if and only if** the `AVK` used to verify the multi signature is also part of the signed message used to create a valid multi signature in a previously sealed Certificate.
+
+The **Genesis Certificate** is valid **if and only if** its **Genesis Signature** is verified with the advertised **Public Genesis Key**.
+
+An implementation of the algorithm would work as follows for a certificate:
+
+* **Step 1**: Use this certificate as the `current_certificate`
+* **Step 2**: Verify (or fail) that the `current_hash` of the `current_certificate` is valid (by computing it and comparing with the `hash` field of the certificate)
+* **Step 3**: Get the `previous_hash` of the `previous_certificate` by reading its value in the `current_certificate`
+* **Step 4**: Verify (or fail) that the `multi_signature` of the `current_certificate` is valid
+* **Step 5**: Retrieve the `previous_certificate` that has the hash `previous_hash`:
+ * **Step 5.1**: If it is not a `genesis_certificate`:
+ * **Step 5.1.1**: Verify (or fail) that the `previous_hash` of the `previous_certificate` is valid (by computing it and comparing with the `hash` field of the certificate)
+ * **Step 5.1.2**: Verify the `current_avk`
+ * **Step 5.1.2.1**: If the `current_certificate` is the `first_certificate` of the epoch, verify (or fail) that the `current_avk` of the `current_certificate` is part of the message signed by the multi signature of the `previous_certificate`
+ * **Step 5.1.2.2**: Else verify (or fail) that the `current_avk` of the `current_certificate` is the same as the `current_avk` of the `previous_certificate`
+ * **Step 5.1.3**: Verify (or fail) that the `multi_signature` of the `previous_certificate` is valid
+ * **Step 5.1.4**: Use the `previous_certificate` as `current_certificate` and start again at **Step 2**
+ * **Step 5.2**: If it is a `genesis_certificate`:
+ * **Step 5.2.1**: Verify (or fail) that the `previous_hash` of the `previous_certificate` is valid (by computing it and comparing with the `hash` field of the certificate)
+ * **Step 5.2.2**: Verify (or fail) that the `current_avk` of the `current_certificate` is part of the message signed by the genesis signature of the `previous_certificate`
+ * **Step 5.2.3**: The certificate is valid (Success)
+
+## The coexistence of multiple Certificate Chain
+
+What would happen if some **Mithril Aggregator** claims that not enough signatures were received? This doesn’t really matter, as there will be a different **Mithril Aggregator** that would collect sufficient signatures and aggregate them into a valid Certificate.
+
+Similarly, different **Mithril Aggregators** might have different views of the **individual signatures** submitted (one aggregator might receive 10 signatures, and a different one could receive 11), which would result in different **Certificates** signing the same message.
+
+This would result in different **Certificate Chains** that would all link back to the **Genesis Certificate**. Indeed they would be represented by a tree of certificates where each traversal path from the root to a leaf represent a valid **Certificate Chain**.
+
+## The need of backward compatibility
+
+The **Certificate Chain** is designed to last. At a certain point, we will need to handle the verification of the multi signature from legacy versions of the **Mithril** cryptographic library.
+
+In order to achieve this backward compatibility, some options are available:
+
+* Handle multi signature verification functions of legacy versions
+* Recreate Genesis Certificates from time to time
+* Create intermediate **Milestones Certificates** (with both a multi signature and a genesis signature)
+* Design a format migration algorithm
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/images/certificate-chain.jpg b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/images/certificate-chain.jpg
new file mode 100644
index 00000000000..56ada5833c0
Binary files /dev/null and b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/images/certificate-chain.jpg differ
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/protocol.md b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/protocol.md
new file mode 100644
index 00000000000..005b0b3d295
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/protocol.md
@@ -0,0 +1,137 @@
+---
+sidebar_position: 1
+sidebar_label: Protocol in depth
+---
+
+# Mithril Protocol in depth
+
+:::info
+
+The research paper `Mithril: Stake-based Threshold Multisignatures` is downloadable [here](https://iohk.io/en/research/library/papers/mithril-stake-based-threshold-multisignatures/).
+
+:::
+
+:::info New
+
+:new: Interact with the **Mithril Protocol** by experiencing with our [protocol simulation](./simulation.md). This will help you understand how the participants interact to create a multi signature and what's the impact of the protocol parameters.
+
+:::
+
+:::tip
+
+For more information about the **Mithril Network**, please refer to the [Architecture](../mithril-network/architecture.md) page.
+
+:::
+
+## Introduction
+
+The full details of the Mithril protocol are provided in the published paper. This section is high-level description of
+the protocol in layman’s terms.
+
+In a nutshell, Mithril is a signature scheme that generates a certificate that convinces
+the verifiers that a portion of the stake of a system has signed a message.
+
+However, rather than taking the whole set of
+stake holders, Mithril
+"randomly selects" a subset of them, and requires a portion of that subset to provide a signature.
+
+An analogy would be
+that Mithril signers participate in a lottery which defines if they are entitled to sign a particular message. In case
+they win this lottery, then they can go ahead and sign the message. Whenever a sufficient number of parties have won the
+lottery (and submitted their respective signatures), a certificate can be computed.
+
+## The phases of the protocol
+
+The protocol has 3 different phases:
+
+1. **Protocol Establishment phase** which determines the parameters that will be used by Mithril participants. Also,
+ during this phase, the set of "allowed signers" is defined.
+2. **Initialization phase** during which Mithril nodes generate and exchange keys,
+3. **Operations phase** during which nodes sign and aggregate signatures of messages to produce certificates.
+
+:::note Note
+
+Note that all 3 phases require the set of parties (`P` in the paper) to be fixed. During the protocol establishment phase
+three important parameters are generated:
+
+* `m`, defines the number of "lotteries" that a single user can participate in to sign a message.
+* `k`, defines the required number of single signatures to produce a valid certificate.
+* `phi_f` (as denoted in the library) which can be interpreted as the chance of a signer to win a lottery.
+
+:::
+
+Now, let's assume that we want to generate a valid signature for message `msg` using a mithril signature. Then we need `k` valid signatures from the subset of signers.
+
+To this end, each player is allowed to participate in `m` "lotteries" to see if it "wins" the right to sign the message.
+
+If none of this lotteries are won by this particular signer, then it will not be able to submit a signature.
+
+If, contrarily, the signer wins one of the lotteries (or more than one), then it
+can submit the corresponding signature (or all of the corresponding signatures respectively) to produce the valid certificate. The chance of winning the lottery is defined by a function over `phi_f`. The closer `phi_f` is to one, the higher the chances of winning a lottery are.
+
+This means that there exists the possibility that a particular message cannot be certified using Mithril under a given set of parameters. There could be a scenario where not enough signers have won the allowed lotteries to produce a valid certificate. In which case the parameters can be adapted.
+
+### 1. Protocol Establishment Phase
+
+* Select/fix a prime order group to be used as basis for multi-signature scheme
+* _When using bulletproof_: Generate a "random" string, for example by taking some unpredictable data from the net (hash
+ of latest block, stockmarket quotes) and hash it
+* When requested by a party, return the parameters and random string
+
+This setup phase must be done only once and is valid for as long as the same proof system, e.g the parameters can very well be statically baked into the various systems producing and consuming Mithril proofs.
+
+Similarly, during the protocol establishment phase, the parameters `k`, `m` and `phi_f` are defined, as well as the set of allowed signers.
+
+### 2. Initialisation Phase
+
+This phase includes both the actual initialisation phase of each party, and the registration of keys.
+
+* Party retrieves the protocol parameters
+* It uses the parameters to generate a new key pair of a verification key and a signing key, plus a Proof-of-possession
+ `κ`. The verification key and PoP are broadcast to all other parties for registration, which is expected to last for
+ some limited period of time. An important difference with the paper is that registration is not centralised in the "
+ idealised" manner described in the paper. Instead, all signers will register against all other signers. Meaning that
+ each signer will trace it's own registration procedure. Together with other participants' keys, the stake of each
+ party is stored.
+* Then an aggregate verification key (`AVK` in the paper) is created from the registration material, in the form of a
+ Merkle-tree.
+
+The key dissemination process can also happen on-chain, which makes sense as the parties need to have some guarantees about the validity of keys and stakes of each other party.
+
+This phase happens once for each _instance_ of the protocol running.
+
+### 3. Operations Phase
+
+Operations run in cycles, where each cycle is triggered by a message (eg. a snapshot of the UTxO set) to sign for which
+a quorum of `k` valid signatures must be submitted.
+
+* Each party needs to check for eligibility to sign the message. It may be eligible to sign the same message more than once. This check is performed for `m` distinct indices. For every index, the signer evaluates a function (parameterized with `phi_f`) that takes its stake as input. If the result of the function is `SUCCESS`, then the signer is eligible to sign this message for the given index.
+
+* For every valid signature, it creates a proof (`Ï€`) containing a signature of the message, verification key, stake and paths of party in the Merkle-tree.
+
+* Then, multiple signatures can be aggregated together to form a certificate (`Ï„`) by:
+ * Verifying signatures from each party:
+ * Checking the party is authorized to sign for the given index (using the same procedure as the signing)
+ * Checking the proof is valid which means:
+ * Check the evaluation threshold is correct for party’s stake given the message, index and signature
+ * Check the provided path exists in the aggregate keys' Merkle-tree
+ * Verify the signature of the message is valid w.r.t to verification key
+ * Producing an aggregation key from all verification keys
+ * Producing an aggregate signature from all signatures `μ`
+ * Producing a proof using the aggregate keys, the message and the vector of individual proofs from each party:
+ * In the concatenation proof system all these values are simply packed together to form the proof,
+ * In the case of _bulletproof_ system, a more compact proof is generated.
+
+* Each certificate `τ` can be verified to be valid for some message, using the known setup parameters to verify the certificate’s proof and then verifying the aggregate signatures and verification keys.
+
+:::note Note
+
+Note that if the individual signatures are broadcast to all parties, then each party can independently produce the certificates. In particular, the party that performs aggregation is not required to have any specific knowledge, nor it is assumed to be honest. This means that _any_ third party that has access to the individual signatures can perform the signature aggregation.
+
+:::
+
+:::tip
+
+For more information about the **Mithril Network**, please refer to the [Architecture](../mithril-network/architecture.md) page.
+
+:::
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/simulation.md b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/simulation.md
new file mode 100644
index 00000000000..819de9de974
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/simulation.md
@@ -0,0 +1,299 @@
+---
+sidebar_position: 3
+sidebar_label: Simulation
+---
+
+# Mithril Protocol Simulation
+
+:::info
+
+* Thanks to this demo you will get a better understanding of the **Mithril Protocol**. You will hopefully visualize how the participants interact to create a multi signature and what's the impact of the protocol parameters.
+
+* This simulation is ran by a CLI that you will build and run, and that will ultimately generate **real** Mithril multi signatures!
+
+* For the purpose of reproducibility of the results, the simulation uses a deterministic source of randomness.
+
+* During the simulation some artifacts will be written to an `artifacts` folder, such as `verification keys`, `individual signatures` and `multi signatures`.
+
+:::
+
+## What you'll need
+
+* A Linux (preferred) or a macOS computer.
+
+* A [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+## Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+## Build Mithril Protocol demo binary
+
+Change directory
+
+```bash
+cd mithril/demo/protocol-demo
+```
+
+Run tests (Optional)
+
+```bash
+make test
+```
+
+Build executable
+
+```bash
+make build
+```
+
+## Verify build
+
+Check that the Mithril Client binary is working fine by running its help
+
+```bash
+./mithrildemo -h
+```
+
+You should see
+
+```bash
+mithrildemo
+Simple demonstration of the Mithril protocol
+
+USAGE:
+ mithrildemo [OPTIONS]
+
+OPTIONS:
+ -h, --help Print help information
+ -k, --k Quorum parameter [default: 5]
+ -m, --m Security parameter, upper bound on indices [default: 200]
+ --nmessages Number of messages to sign [default: 1]
+ --nparties Number of parties [default: 5]
+ --phi-f f in phi(w) = 1 - (1 - f)^w, where w is the stake of a
+ participant [default: 0.2]
+```
+
+## Run the simulation
+
+:::tip
+
+A friendly reminder about the protocol parameters:
+
+* `k`: the `Quorum` parameter represents the minimum number of individual signatures (gathered from multiple participants) required to be aggregated in a multi signature.
+* `m`: the `Security` parameter represents the total number of `lotteries` in which each participant can participate in order to individually sign the message.
+* `phi-f`: the parameter on which depends the probability of a particpant to win a `lottery`. It variates between `0.0` (less chance) and `1.0` (more chance).
+
+:::
+
+:::danger
+
+The `security level` of the protocol is highly dependent on the value of the `protocol parameters`.
+
+Therefore they will be carefully selected by the Mithril cryptographers and researchers in order to guarantee that only legit stakeholders representing a sufficient threshold of the total stakes can combine their individual signatures in a valid multi signature.
+
+:::
+
+### Case 1: Produce a multi signature
+
+Run the simulation wih `5` participants
+
+```bash
+./mithrildemo -k 5 -m 50 --phi-f 0.65 --nparties 5
+```
+
+The simulation should succeed and produce (or aggregate) a multi signature!
+
+```bash
+>> Launch Mithril protocol demonstrator with configuration:
+Config {
+ m: 50,
+ k: 5,
+ phi_f: 0.65,
+ nparties: 5,
+ nmessages: 1,
+}
+
+>> Protocol establish phase
+Party #0: party created with 826 stakes
+Party #1: party created with 741 stakes
+Party #2: party created with 144 stakes
+Party #3: party created with 734 stakes
+Party #4: party created with 41 stakes
+Protocol established to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+
+>> Protocol initialize phase:
+Verifier: verifier created
+Verifier: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+Party #0: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+Party #1: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+Party #2: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+Party #3: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+Party #4: protocol params updated to StmParameters { m: 50, k: 5, phi_f: 0.65 }
+Verifier: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #0: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #1: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #2: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #3: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #4: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Artifacts written to artifacts/parties-keys.json
+
+>> Protocol issue certificates phase:
+Message #0 to sign: [119, 36, 224, 63, 184, 216, 74, 55, 106, 67, 184, 244, 21, 24, 161, 28]
+Party #0: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #0: lottery #2 won
+Party #0: lottery #3 won
+Party #0: lottery #8 won
+Party #0: lottery #13 won
+Party #0: lottery #16 won
+Party #0: lottery #17 won
+Party #0: lottery #19 won
+Party #0: lottery #23 won
+Party #0: lottery #25 won
+Party #0: lottery #28 won
+Party #0: lottery #29 won
+Party #0: lottery #31 won
+Party #0: lottery #42 won
+Party #0: lottery #43 won
+Party #0: lottery #46 won
+Party #1: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #1: lottery #2 won
+Party #1: lottery #3 won
+Party #1: lottery #8 won
+Party #1: lottery #13 won
+Party #1: lottery #16 won
+Party #1: lottery #17 won
+Party #1: lottery #19 won
+Party #1: lottery #23 won
+Party #1: lottery #25 won
+Party #1: lottery #29 won
+Party #1: lottery #31 won
+Party #1: lottery #42 won
+Party #1: lottery #43 won
+Party #1: lottery #46 won
+Party #2: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #2: lottery #19 won
+Party #2: lottery #43 won
+Party #2: lottery #46 won
+Party #3: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #3: lottery #2 won
+Party #3: lottery #3 won
+Party #3: lottery #8 won
+Party #3: lottery #13 won
+Party #3: lottery #16 won
+Party #3: lottery #17 won
+Party #3: lottery #19 won
+Party #3: lottery #23 won
+Party #3: lottery #25 won
+Party #3: lottery #29 won
+Party #3: lottery #31 won
+Party #3: lottery #42 won
+Party #3: lottery #43 won
+Party #3: lottery #46 won
+Party #4: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #4: lottery #19 won
+Party #0: aggregate signature computed
+Party #1: aggregate signature computed
+Party #2: aggregate signature computed
+Party #3: aggregate signature computed
+Party #4: aggregate signature computed
+Artifacts written to artifacts/single-signatures.json
+Artifacts written to artifacts/multi-signatures.json
+
+>> Protocol verify certificates phase:
+Message #0 to verify: 7724e03fb8d84a376a43b8f41518a11c
+Party #0: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Verifier: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Party #1: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Verifier: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Party #2: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Verifier: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Party #3: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Verifier: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Party #4: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+Verifier: aggregate signature successfully verified for 7724e03fb8d84a376a43b8f41518a11c!
+
+>> Congrats, protocol terminated with success!
+```
+
+### Case 2: Does not produce a multi signature
+
+Run the simulation wih `5` participants
+
+```bash
+./mithrildemo -k 5 -m 5 --phi-f 0.25 --nparties 5
+```
+
+The simulation should fail and not produce (or aggregate) any multi signature!
+
+```bash
+>> Launch Mithril protocol demonstrator with configuration:
+Config {
+ m: 5,
+ k: 5,
+ phi_f: 0.25,
+ nparties: 5,
+ nmessages: 1,
+}
+
+>> Protocol establish phase
+Party #0: party created with 826 stakes
+Party #1: party created with 741 stakes
+Party #2: party created with 144 stakes
+Party #3: party created with 734 stakes
+Party #4: party created with 41 stakes
+Protocol established to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+
+>> Protocol initialize phase:
+Verifier: verifier created
+Verifier: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+Party #0: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+Party #1: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+Party #2: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+Party #3: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+Party #4: protocol params updated to StmParameters { m: 5, k: 5, phi_f: 0.25 }
+Verifier: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #0: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #1: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #2: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #3: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Party #4: protocol keys registration from [("0", 826), ("1", 741), ("2", 144), ("3", 734), ("4", 41)]
+Artifacts written to artifacts/parties-keys.json
+
+>> Protocol issue certificates phase:
+Message #0 to sign: [119, 36, 224, 63, 184, 216, 74, 55, 106, 67, 184, 244, 21, 24, 161, 28]
+Party #0: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #1: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #2: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #3: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #4: sign message 7724e03fb8d84a376a43b8f41518a11c
+Party #0: not enough signatures to compute aggregate
+Party #1: not enough signatures to compute aggregate
+Party #2: not enough signatures to compute aggregate
+Party #3: not enough signatures to compute aggregate
+Party #4: not enough signatures to compute aggregate
+Artifacts written to artifacts/single-signatures.json
+Artifacts written to artifacts/multi-signatures.json
+
+>> Protocol verify certificates phase:
+Message #0 to verify: 7724e03fb8d84a376a43b8f41518a11c
+Party #0: aggregate signature not found 7724e03fb8d84a376a43b8f41518a11c
+
+>> Certificate verification failed: aggregate signature not found
+```
+
+:::tip
+
+For more information about the **Mithril Protocol**, please refer to the [About Mithril](../mithril-protocol/protocol.md) section.
+
+:::
diff --git a/docs/versioned_docs/version-maintained/networks-matrix.md b/docs/versioned_docs/version-maintained/networks-matrix.md
new file mode 100644
index 00000000000..0f6c5debb59
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/networks-matrix.md
@@ -0,0 +1,23 @@
+---
+unlisted: true
+hide_title: true
+hide_table_of_contents: true
+---
+
+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`)
\ No newline at end of file
diff --git a/docs/versioned_sidebars/version-maintained-sidebars.json b/docs/versioned_sidebars/version-maintained-sidebars.json
new file mode 100644
index 00000000000..1ce69050f38
--- /dev/null
+++ b/docs/versioned_sidebars/version-maintained-sidebars.json
@@ -0,0 +1,14 @@
+{
+ "docSideBar": [
+ {
+ "type": "autogenerated",
+ "dirName": "manual"
+ }
+ ],
+ "mithrilSideBar": [
+ {
+ "type": "autogenerated",
+ "dirName": "mithril"
+ }
+ ]
+}
diff --git a/docs/versions.json b/docs/versions.json
new file mode 100644
index 00000000000..53c8d714d7d
--- /dev/null
+++ b/docs/versions.json
@@ -0,0 +1,3 @@
+[
+ "maintained"
+]
diff --git a/mithril-aggregator/Dockerfile b/mithril-aggregator/Dockerfile
index ce223f26f73..a9ec5b93fb2 100644
--- a/mithril-aggregator/Dockerfile
+++ b/mithril-aggregator/Dockerfile
@@ -18,8 +18,8 @@ RUN adduser --no-create-home --disabled-password appuser
WORKDIR /app
# Copy local dependencies
-COPY mithril-core/ /mithril-core/
-COPY Cargo.lock /mithril-core/
+COPY mithril-stm/ /mithril-stm/
+COPY Cargo.lock /mithril-stm/
COPY mithril-common/ /mithril-common/
COPY Cargo.lock /mithril-common/
diff --git a/mithril-aggregator/src/command_args.rs b/mithril-aggregator/src/command_args.rs
index 7241e3d686b..fbfead4ded5 100644
--- a/mithril-aggregator/src/command_args.rs
+++ b/mithril-aggregator/src/command_args.rs
@@ -12,7 +12,7 @@ use tokio::time::Duration;
use mithril_common::certificate_chain::MithrilCertificateVerifier;
use mithril_common::chain_observer::{CardanoCliRunner, ChainObserver};
use mithril_common::crypto_helper::ProtocolGenesisVerifier;
-use mithril_common::database::{ApplicationNodeType, ApplicationVersionChecker};
+use mithril_common::database::{ApplicationNodeType, DatabaseVersionChecker};
use mithril_common::digesters::{CardanoImmutableDigester, ImmutableFileSystemObserver};
use mithril_common::entities::{Epoch, HexEncodedGenesisSecretKey};
use mithril_common::store::adapter::SQLiteAdapter;
@@ -37,12 +37,7 @@ fn setup_genesis_dependencies(
config: &GenesisConfiguration,
) -> Result> {
let sqlite_db_path = Some(config.get_sqlite_file());
- ApplicationVersionChecker::new(
- slog_scope::logger(),
- ApplicationNodeType::Aggregator,
- config.get_sqlite_file(),
- )
- .check(env!("CARGO_PKG_VERSION"))?;
+ check_database_migration(config.get_sqlite_file())?;
let chain_observer = Arc::new(
mithril_common::chain_observer::CardanoCliChainObserver::new(Box::new(
@@ -143,6 +138,17 @@ async fn do_first_launch_initialization_if_needed(
Ok(())
}
+/// Database version checker.
+/// This is the place where migrations are to be registered.
+fn check_database_migration(sql_file_path: PathBuf) -> Result<(), Box> {
+ DatabaseVersionChecker::new(
+ slog_scope::logger(),
+ ApplicationNodeType::Aggregator,
+ sql_file_path,
+ )
+ .apply()
+}
+
/// Mithril Aggregator Node
#[derive(Parser, Debug, Clone)]
#[command(version)]
@@ -304,12 +310,7 @@ impl ServeCommand {
.map_err(|e| format!("configuration deserialize error: {}", e))?;
debug!("SERVE command"; "config" => format!("{:?}", config));
let sqlite_db_path = Some(config.get_sqlite_file());
- ApplicationVersionChecker::new(
- slog_scope::logger(),
- ApplicationNodeType::Aggregator,
- config.get_sqlite_file(),
- )
- .check(env!("CARGO_PKG_VERSION"))?;
+ check_database_migration(config.get_sqlite_file())?;
// Init dependencies
let snapshot_store = config.build_snapshot_store()?;
diff --git a/mithril-aggregator/src/multi_signer.rs b/mithril-aggregator/src/multi_signer.rs
index e4c6182ce6d..bbff025372a 100644
--- a/mithril-aggregator/src/multi_signer.rs
+++ b/mithril-aggregator/src/multi_signer.rs
@@ -48,7 +48,7 @@ pub enum ProtocolError {
#[error("codec error: '{0}'")]
Codec(String),
- /// Mithril Core library returned an error.
+ /// Mithril STM library returned an error.
#[error("core error: '{0}'")]
Core(String),
diff --git a/mithril-client/Dockerfile b/mithril-client/Dockerfile
index d49f86f477f..d58ca255321 100644
--- a/mithril-client/Dockerfile
+++ b/mithril-client/Dockerfile
@@ -18,8 +18,8 @@ RUN adduser --no-create-home --disabled-password appuser
WORKDIR /app
# Copy local dependencies
-COPY mithril-core/ /mithril-core/
-COPY Cargo.lock /mithril-core/
+COPY mithril-stm/ /mithril-stm/
+COPY Cargo.lock /mithril-stm/
COPY mithril-common/ /mithril-common/
COPY Cargo.lock /mithril-common/
diff --git a/mithril-common/Cargo.toml b/mithril-common/Cargo.toml
index 304a2a128b4..8faf262fbd6 100644
--- a/mithril-common/Cargo.toml
+++ b/mithril-common/Cargo.toml
@@ -44,16 +44,18 @@ warp = "0.3"
[target.'cfg(not(windows))'.dependencies]
# non-windows: use default rug backend
-mithril = { path = "../mithril-core" }
+mithril-stm = { path = "../mithril-stm" }
[target.'cfg(windows)'.dependencies]
# Windows doesn't support rug backend, fallback to num-integer
-mithril = { path = "../mithril-core", default-features = false, features = ["num-integer-backend"] }
+mithril-stm = { path = "../mithril-stm", default-features = false, features = ["num-integer-backend"] }
[dev-dependencies]
slog-scope = "4.4.0"
[features]
-portable = ["mithril/portable"]
+default = ["allow_skip_signer_certification"]
+portable = ["mithril-stm/portable"]
test_only = []
allow_skip_signer_certification = []
+
diff --git a/mithril-common/src/crypto_helper/cardano/key_certification.rs b/mithril-common/src/crypto_helper/cardano/key_certification.rs
index 4a2a3f73ac0..f7aa2904221 100644
--- a/mithril-common/src/crypto_helper/cardano/key_certification.rs
+++ b/mithril-common/src/crypto_helper/cardano/key_certification.rs
@@ -1,7 +1,7 @@
//! API for mithril key certification.
//! Includes the wrappers for StmInitializer and KeyReg, and ProtocolRegistrationErrorWrapper.
-//! These wrappers allows keeping mithril-core agnostic to Cardano, while providing some
-//! guarantees that mithril-core will not be misused in the context of Cardano.
+//! These wrappers allows keeping mithril-stm agnostic to Cardano, while providing some
+//! guarantees that mithril-stm will not be misused in the context of Cardano.
use crate::crypto_helper::cardano::{OpCert, ParseError, SerDeShelleyFileFormat};
use crate::crypto_helper::types::{
@@ -9,9 +9,9 @@ use crate::crypto_helper::types::{
ProtocolStakeDistribution,
};
-use mithril::key_reg::{ClosedKeyReg, KeyReg};
-use mithril::stm::{Stake, StmInitializer, StmParameters, StmSigner, StmVerificationKeyPoP};
-use mithril::RegisterError;
+use mithril_stm::key_reg::{ClosedKeyReg, KeyReg};
+use mithril_stm::stm::{Stake, StmInitializer, StmParameters, StmSigner, StmVerificationKeyPoP};
+use mithril_stm::RegisterError;
use blake2::{
digest::{consts::U32, FixedOutput},
@@ -43,13 +43,17 @@ pub enum ProtocolRegistrationErrorWrapper {
#[error("party id does not exist in the stake distribution")]
PartyIdNonExisting,
+ /// Error raised when the operational certificate is missing
+ #[error("missing operational certificate")]
+ OpCertMissing,
+
/// Error raised when an operational certificate is invalid
#[error("invalid operational certificate")]
OpCertInvalid,
/// Error raised when a KES Signature verification fails
- #[error("KES signature verification error")]
- KesSignatureInvalid,
+ #[error("KES signature verification error: CurrentKesPeriod={0}, StartKesPeriod={1}")]
+ KesSignatureInvalid(usize, u64),
/// Error raised when a KES Signature is needed but not provided
#[error("missing KES signature")]
@@ -79,7 +83,7 @@ pub enum ProtocolInitializerErrorWrapper {
#[error("KES key cannot be updated for period {0}")]
KesUpdate(KESPeriod),
}
-/// Wrapper structure for [MithrilCore:StmInitializer](mithril::stm::StmInitializer).
+/// Wrapper structure for [MithrilStm:StmInitializer](mithril_stm::stm::StmInitializer).
/// It now obtains a KES signature over the Mithril key. This allows the signers prove
/// their correct identity with respect to a Cardano PoolID.
#[derive(Debug, Clone, Serialize, Deserialize)]
@@ -88,7 +92,7 @@ pub struct StmInitializerWrapper {
kes_signature: Option, // todo: The option is ONLY for a smooth transition. We have to remove this.
}
-/// Wrapper structure for [MithrilCore:KeyReg](mithril::key_reg::KeyReg).
+/// Wrapper structure for [MithrilStm:KeyReg](mithril_stm::key_reg::KeyReg).
/// The wrapper not only contains a map between `Mithril vkey <-> Stake`, but also
/// a map `PoolID <-> Stake`. This information is recovered from the node state, and
/// is used to verify the identity of a Mithril signer. Furthermore, the `register` function
@@ -221,18 +225,17 @@ impl KeyRegWrapper {
opcert
.validate()
.map_err(|_| ProtocolRegistrationErrorWrapper::OpCertInvalid)?;
- // TODO: List of eligible indices to be defined by CurrentKesPeriod and StartKesPeriod
let mut pool_id = None;
let sig = kes_sig.ok_or(ProtocolRegistrationErrorWrapper::KesSignatureMissing)?;
- for kes_period_try in 0..64 {
+ let kes_period =
+ kes_period.ok_or(ProtocolRegistrationErrorWrapper::KesPeriodMissing)?;
+ let kes_period_try_min = std::cmp::max(0, kes_period.saturating_sub(1));
+ let kes_period_try_max = std::cmp::min(64, kes_period.saturating_add(1));
+ for kes_period_try in kes_period_try_min..kes_period_try_max {
if sig
.verify(kes_period_try, &opcert.kes_vk, &pk.to_bytes())
.is_ok()
{
- println!(
- "WARNING: KES Signature verified for TryKesPeriod={}, CurrentKesPeriod={:?}, and StartKesPeriod={}",
- kes_period_try, kes_period, &opcert.start_kes_period
- );
pool_id = Some(
opcert
.compute_protocol_party_id()
@@ -241,9 +244,15 @@ impl KeyRegWrapper {
break;
}
}
- pool_id.ok_or(ProtocolRegistrationErrorWrapper::KesSignatureInvalid)?
+ pool_id.ok_or(ProtocolRegistrationErrorWrapper::KesSignatureInvalid(
+ kes_period,
+ opcert.start_kes_period,
+ ))?
} else {
- println!("WARNING: Signer certification is skipped! {:?}", party_id);
+ if cfg!(not(feature = "allow_skip_signer_certification")) {
+ Err(ProtocolRegistrationErrorWrapper::OpCertMissing)?
+ }
+ println!("WARNING: Uncertified signer regsitration by providing a Pool Id is deprecated and will be removed soon! (Pool Id: {:?})", party_id);
party_id.ok_or(ProtocolRegistrationErrorWrapper::PartyIdMissing)?
};
diff --git a/mithril-common/src/crypto_helper/mod.rs b/mithril-common/src/crypto_helper/mod.rs
index 7a24a7bc346..3901987632c 100644
--- a/mithril-common/src/crypto_helper/mod.rs
+++ b/mithril-common/src/crypto_helper/mod.rs
@@ -1,4 +1,4 @@
-//! Tools and types to abstract the use of the [Mithril Core library](https://mithril.network/rust-doc/mithril/index.html)
+//! Tools and types to abstract the use of the [Mithril STM library](https://mithril.network/rust-doc/mithril_stm/index.html)
mod cardano;
mod codec;
diff --git a/mithril-common/src/crypto_helper/tests_setup.rs b/mithril-common/src/crypto_helper/tests_setup.rs
index d49318a1f68..ccb3e58ffcb 100644
--- a/mithril-common/src/crypto_helper/tests_setup.rs
+++ b/mithril-common/src/crypto_helper/tests_setup.rs
@@ -1,4 +1,4 @@
-//! Test data builders for Mithril Core types, for testing purpose.
+//! Test data builders for Mithril STM types, for testing purpose.
use super::cardano::ColdKeyGenerator;
use super::{genesis::*, key_encode_hex, types::*, OpCert, SerDeShelleyFileFormat};
use crate::certificate_chain::CertificateGenesisProducer;
@@ -15,7 +15,8 @@ use std::{cmp::min, fs, sync::Arc};
use std::{collections::HashMap, path::PathBuf};
-fn setup_temp_directory_for_signer(
+/// Create or retrieve a temporary directory for storing cryptographic material for a signer, use this for tests only.
+pub fn setup_temp_directory_for_signer(
party_id: &ProtocolPartyId,
auto_create: bool,
) -> Option {
@@ -62,8 +63,11 @@ pub fn setup_signers(
let stake_distribution = (0..total)
.into_iter()
.map(|party_idx| {
- let party_id = if party_idx % 2 == 0 {
- // 50% of signers with key certification
+ let party_id = if party_idx % 2 == 0
+ || cfg!(not(feature = "allow_skip_signer_certification"))
+ {
+ // 50% of signers with key certification if allow unverified signer registration
+ // Or 100% of signers otherwise
let keypair = ColdKeyGenerator::create_deterministic_keypair([party_idx as u8; 32]);
let (kes_secret_key, kes_verification_key) = Sum6Kes::keygen(&mut kes_keys_seed);
let operational_certificate = OpCert::new(kes_verification_key, 0, 0, keypair);
@@ -77,14 +81,15 @@ pub fn setup_signers(
.to_file(temp_dir.join("kes.sk"))
.expect("KES secret key file export should not fail");
}
- if !temp_dir.join("pool.cert").exists() {
+ if !temp_dir.join("opcert.cert").exists() {
operational_certificate
- .to_file(temp_dir.join("pool.cert"))
+ .to_file(temp_dir.join("opcert.cert"))
.expect("operational certificate file export should not fail");
}
party_id
} else {
- // 50% of signers without key certification (legacy)
+ // 50% of signers without key certification (legacy) if allow unverified signer registration
+ // Or 0% of signers otherwise
// TODO: Should be removed once the signer certification is fully deployed
format!("{:<032}", party_idx)
};
@@ -132,7 +137,7 @@ pub fn setup_signers_from_stake_distribution(
.for_each(|(party_id, _stake, protocol_initializer)| {
let temp_dir = setup_temp_directory_for_signer(party_id, false);
let operational_certificate = temp_dir.as_ref().map(|dir| {
- OpCert::from_file(dir.join("pool.cert"))
+ OpCert::from_file(dir.join("opcert.cert"))
.expect("operational certificate decoding should not fail")
});
let verification_key = protocol_initializer.verification_key();
@@ -154,7 +159,7 @@ pub fn setup_signers_from_stake_distribution(
.map(|(party_id, stake, protocol_initializer)| {
let temp_dir = setup_temp_directory_for_signer(&party_id, false);
let operational_certificate: Option = temp_dir.as_ref().map(|dir| {
- OpCert::from_file(dir.join("pool.cert"))
+ OpCert::from_file(dir.join("opcert.cert"))
.expect("operational certificate decoding should not fail")
});
let kes_period = 0;
diff --git a/mithril-common/src/crypto_helper/types.rs b/mithril-common/src/crypto_helper/types.rs
index c87d6322149..251057b1048 100644
--- a/mithril-common/src/crypto_helper/types.rs
+++ b/mithril-common/src/crypto_helper/types.rs
@@ -2,14 +2,14 @@ use crate::crypto_helper::cardano::{
KeyRegWrapper, ProtocolRegistrationErrorWrapper, StmInitializerWrapper,
};
-use mithril::stm::{
+use mithril_stm::stm::{
Index, Stake, StmAggrSig, StmAggrVerificationKey, StmClerk, StmParameters, StmSig, StmSigner,
StmVerificationKeyPoP,
};
-use mithril::AggregationError;
+use mithril_stm::AggregationError;
#[cfg(any(test, feature = "allow_skip_signer_certification"))]
-use mithril::{key_reg::KeyReg, stm::StmInitializer};
+use mithril_stm::{key_reg::KeyReg, stm::StmInitializer};
use blake2::{digest::consts::U32, Blake2b};
use ed25519_dalek;
@@ -24,43 +24,43 @@ type D = Blake2b;
/// The id of a mithril party.
pub type ProtocolPartyId = String;
-/// Alias of [MithrilCore:Stake](type@mithril::stm::Stake).
+/// Alias of [MithrilStm:Stake](type@mithril_stm::stm::Stake).
pub type ProtocolStake = Stake;
/// A list of [Party Id][ProtocolPartyId] associated with its [Stake][ProtocolStake].
pub type ProtocolStakeDistribution = Vec<(ProtocolPartyId, ProtocolStake)>;
-/// Alias of [MithrilCore::StmParameters](struct@mithril::stm::StmParameters).
+/// Alias of [MithrilStm::StmParameters](struct@mithril_stm::stm::StmParameters).
pub type ProtocolParameters = StmParameters;
-/// Alias of [MithrilCore::Index](type@mithril::stm::Index).
+/// Alias of [MithrilStm::Index](type@mithril_stm::stm::Index).
pub type ProtocolLotteryIndex = Index;
-/// Alias of [MithrilCore:StmSigner](struct@mithril::stm::StmSigner).
+/// Alias of [MithrilStm:StmSigner](struct@mithril_stm::stm::StmSigner).
pub type ProtocolSigner = StmSigner;
-/// Alias of a wrapper of [MithrilCore:StmInitializer](struct@mithril::stm::StmInitializer).
+/// Alias of a wrapper of [MithrilStm:StmInitializer](struct@mithril_stm::stm::StmInitializer).
pub type ProtocolInitializer = StmInitializerWrapper;
-/// Alias of [MithrilCore:StmClerk](struct@mithril::stm::StmClerk).
+/// Alias of [MithrilStm:StmClerk](struct@mithril_stm::stm::StmClerk).
pub type ProtocolClerk = StmClerk;
-/// Alias of a wrapper of [MithrilCore:KeyReg](struct@mithril::key_reg::KeyReg).
+/// Alias of a wrapper of [MithrilStm:KeyReg](struct@mithril_stm::key_reg::KeyReg).
pub type ProtocolKeyRegistration = KeyRegWrapper;
-/// Alias of [MithrilCore:StmSig](struct@mithril::stm::StmSig).
+/// Alias of [MithrilStm:StmSig](struct@mithril_stm::stm::StmSig).
pub type ProtocolSingleSignature = StmSig;
-/// Alias of [MithrilCore:StmAggrSig](struct@mithril::stm::StmAggrSig).
+/// Alias of [MithrilStm:StmAggrSig](struct@mithril_stm::stm::StmAggrSig).
pub type ProtocolMultiSignature = StmAggrSig;
-/// Alias of [MithrilCore:StmVerificationKeyPoP](type@mithril::stm::StmVerificationKeyPoP).
+/// Alias of [MithrilStm:StmVerificationKeyPoP](type@mithril_stm::stm::StmVerificationKeyPoP).
pub type ProtocolSignerVerificationKey = StmVerificationKeyPoP;
/// Alias of [KES:Sum6KesSig](https://github.com/input-output-hk/kes/blob/master/src/kes.rs).
pub type ProtocolSignerVerificationKeySignature = Sum6KesSig;
-/// Alias of [MithrilCore:StmAggrVerificationKey](struct@mithril::stm::StmAggrVerificationKey).
+/// Alias of [MithrilStm:StmAggrVerificationKey](struct@mithril_stm::stm::StmAggrVerificationKey).
pub type ProtocolAggregateVerificationKey = StmAggrVerificationKey;
/// Alias of [Ed25519:PublicKey](https://docs.rs/ed25519-dalek/latest/ed25519_dalek/struct.PublicKey.html).
@@ -73,17 +73,17 @@ pub type ProtocolGenesisSecretKey = ed25519_dalek::SecretKey;
pub type ProtocolGenesisSignature = ed25519_dalek::Signature;
// Error alias
-/// Alias of a wrapper of [MithrilCore:RegisterError](enum@mithril::RegisterError).
+/// Alias of a wrapper of [MithrilStm:RegisterError](enum@mithril_stm::RegisterError).
pub type ProtocolRegistrationError = ProtocolRegistrationErrorWrapper;
-/// Alias of [MithrilCore:AggregationError](enum@mithril::AggregationError).
+/// Alias of [MithrilStm:AggregationError](enum@mithril_stm::AggregationError).
pub type ProtocolAggregationError = AggregationError;
// Test only
-/// (Test only) Alias of [MithrilCore:StmInitializer](struct@mithril::stm::StmInitializer).
+/// (Test only) Alias of [MithrilStm:StmInitializer](struct@mithril_stm::stm::StmInitializer).
#[cfg(any(test, feature = "allow_skip_signer_certification"))]
pub type ProtocolInitializerNotCertified = StmInitializer;
-/// (Test only) Alias of [MithrilCore:KeyReg](struct@mithril::key_reg::KeyReg). (Test only)
+/// (Test only) Alias of [MithrilStm:KeyReg](struct@mithril_stm::key_reg::KeyReg). (Test only)
#[cfg(any(test, feature = "allow_skip_signer_certification"))]
pub type ProtocolKeyRegistrationNotCertified = KeyReg;
diff --git a/mithril-common/src/database/db_version.rs b/mithril-common/src/database/db_version.rs
index 9770e2ed41f..4826b73332b 100644
--- a/mithril-common/src/database/db_version.rs
+++ b/mithril-common/src/database/db_version.rs
@@ -1,12 +1,17 @@
-use std::{cmp::Ordering, collections::HashMap, error::Error, fmt::Display, path::PathBuf};
-
-use chrono::{Local, NaiveDateTime};
-use semver::Version;
-use slog::{debug, error, warn, Logger};
+use std::{
+ cmp::Ordering,
+ collections::HashMap,
+ error::Error,
+ fmt::{Debug, Display},
+};
+
+use chrono::NaiveDateTime;
use sqlite::{Connection, Row, Value};
use crate::sqlite::{HydrationError, Projection, ProjectionField, Provider, SqLiteEntity};
+use super::DbVersion;
+
/// Application using a database
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApplicationNodeType {
@@ -37,11 +42,11 @@ impl Display for ApplicationNodeType {
}
}
-/// Entity related to the `app_version` database table.
+/// Entity related to the `db_version` database table.
#[derive(Debug, PartialEq, Eq, Clone)]
-pub struct ApplicationVersion {
- /// Semver of the database structure.
- pub semver: Version,
+pub struct DatabaseVersion {
+ /// Version of the database structure.
+ pub version: DbVersion,
/// Name of the application.
pub application_type: ApplicationNodeType,
@@ -51,11 +56,10 @@ pub struct ApplicationVersion {
pub updated_at: NaiveDateTime,
}
-impl SqLiteEntity for ApplicationVersion {
+impl SqLiteEntity for DatabaseVersion {
fn hydrate(row: Row) -> Result {
Ok(Self {
- semver: Version::parse(&row.get::(0))
- .map_err(|e| HydrationError::InvalidData(format!("{}", e)))?,
+ version: row.get::(0),
application_type: ApplicationNodeType::new(&row.get::(1))
.map_err(|e| HydrationError::InvalidData(format!("{}", e)))?,
updated_at: NaiveDateTime::parse_from_str(
@@ -67,12 +71,22 @@ impl SqLiteEntity for ApplicationVersion {
}
}
-/// Projection dedicated to [ApplicationVersion] entities.
-struct ApplicationVersionProjection {
+impl PartialOrd for DatabaseVersion {
+ fn partial_cmp(&self, other: &Self) -> Option {
+ if self.application_type != other.application_type {
+ None
+ } else {
+ self.version.partial_cmp(&other.version)
+ }
+ }
+}
+
+/// Projection dedicated to [DatabaseVersion] entities.
+struct DatabaseVersionProjection {
fields: Vec,
}
-impl Projection for ApplicationVersionProjection {
+impl Projection for DatabaseVersionProjection {
fn set_field(&mut self, field: ProjectionField) {
self.fields.push(field);
}
@@ -81,41 +95,44 @@ impl Projection for ApplicationVersionProjection {
&self.fields
}
}
-impl ApplicationVersionProjection {
+impl DatabaseVersionProjection {
pub fn new() -> Self {
let mut projection = Self { fields: Vec::new() };
- projection.add_field("semver", "{:app_version:}.semver", "text");
+ projection.add_field("version", "{:db_version:}.version", "text");
projection.add_field(
"application_type",
- "{:app_version:}.application_type",
+ "{:db_version:}.application_type",
"text",
);
- projection.add_field("updated_at", "{:app_version:}.updated_at", "timestamp");
+ projection.add_field("updated_at", "{:db_version:}.updated_at", "timestamp");
projection
}
}
-/// Provider for the [ApplicationVersion] entities using the `ApplicationVersionProjection`.
-pub struct VersionProvider<'conn> {
+/// Provider for the [DatabaseVersion] entities using the `DatabaseVersionProjection`.
+pub struct DatabaseVersionProvider<'conn> {
connection: &'conn Connection,
- projection: ApplicationVersionProjection,
+ projection: DatabaseVersionProjection,
}
-impl<'conn> VersionProvider<'conn> {
- /// [VersionProvider] constructor.
+impl<'conn> DatabaseVersionProvider<'conn> {
+ /// [DatabaseVersionProvider] constructor.
pub fn new(connection: &'conn Connection) -> Self {
Self {
connection,
- projection: ApplicationVersionProjection::new(),
+ projection: DatabaseVersionProjection::new(),
}
}
/// Method to create the table at the beginning of the migration procedure.
/// This code is temporary and should not last.
- pub fn create_table_if_not_exists(&self) -> Result<(), Box> {
+ pub fn create_table_if_not_exists(
+ &self,
+ application_type: &ApplicationNodeType,
+ ) -> Result<(), Box> {
let connection = self.get_connection();
- let sql = "select exists(select name from sqlite_master where type='table' and name='app_version') as table_exists";
+ let sql = "select exists(select name from sqlite_master where type='table' and name='db_version') as table_exists";
let table_exists = connection
.prepare(sql)?
.into_cursor()
@@ -126,9 +143,10 @@ impl<'conn> VersionProvider<'conn> {
== 1;
if !table_exists {
- let sql = r#"
-create table app_version (application_type text not null primary key, semver text not null, updated_at timestamp not null default CURRENT_TIMESTAMP)
-"#;
+ let sql = format!("
+create table db_version (application_type text not null primary key, version integer not null, updated_at timestamp not null default CURRENT_TIMESTAMP);
+insert into db_version (application_type, version) values ('{application_type}', 0);
+");
connection.execute(sql)?;
}
@@ -139,7 +157,7 @@ create table app_version (application_type text not null primary key, semver tex
pub fn get_application_version(
&self,
application_type: &ApplicationNodeType,
- ) -> Result, Box> {
+ ) -> Result, Box> {
let condition = "application_type = ?";
let params = [Value::String(format!("{}", application_type))];
let result = self.find(Some(condition), ¶ms)?.next();
@@ -148,8 +166,8 @@ create table app_version (application_type text not null primary key, semver tex
}
}
-impl<'conn> Provider<'conn> for VersionProvider<'conn> {
- type Entity = ApplicationVersion;
+impl<'conn> Provider<'conn> for DatabaseVersionProvider<'conn> {
+ type Entity = DatabaseVersion;
fn get_projection(&self) -> &dyn Projection {
&self.projection
@@ -162,40 +180,40 @@ impl<'conn> Provider<'conn> for VersionProvider<'conn> {
fn get_definition(&self, condition: Option<&str>) -> String {
let where_clause = condition.unwrap_or("true");
let mut aliases = HashMap::new();
- let _ = aliases.insert("{:app_version:}".to_string(), "app_version".to_string());
+ let _ = aliases.insert("{:db_version:}".to_string(), "db_version".to_string());
let projection = self.get_projection().expand(aliases);
format!(
r#"
select {projection}
-from app_version
+from db_version
where {where_clause}
"#
)
}
}
-/// Write [Provider] for the [ApplicationVersion] entities.
+/// Write [Provider] for the [DatabaseVersion] entities.
/// This will perform an UPSERT and return the updated entity.
-pub struct VersionUpdaterProvider<'conn> {
+pub struct DatabaseVersionUpdater<'conn> {
connection: &'conn Connection,
- projection: ApplicationVersionProjection,
+ projection: DatabaseVersionProjection,
}
-impl<'conn> VersionUpdaterProvider<'conn> {
- /// [VersionUpdaterProvider] constructor.
+impl<'conn> DatabaseVersionUpdater<'conn> {
+ /// [DatabaseVersionUpdater] constructor.
pub fn new(connection: &'conn Connection) -> Self {
Self {
connection,
- projection: ApplicationVersionProjection::new(),
+ projection: DatabaseVersionProjection::new(),
}
}
/// Persist the given entity and return the projection of the saved entity.
- pub fn save(&self, version: ApplicationVersion) -> Result> {
+ pub fn save(&self, version: DatabaseVersion) -> Result> {
let params = [
Value::String(format!("{}", version.application_type)),
- Value::String(version.semver.to_string()),
+ Value::Integer(version.version),
];
let entity = self
.find(None, ¶ms)?
@@ -206,8 +224,8 @@ impl<'conn> VersionUpdaterProvider<'conn> {
}
}
-impl<'conn> Provider<'conn> for VersionUpdaterProvider<'conn> {
- type Entity = ApplicationVersion;
+impl<'conn> Provider<'conn> for DatabaseVersionUpdater<'conn> {
+ type Entity = DatabaseVersion;
fn get_projection(&self) -> &dyn Projection {
&self.projection
@@ -220,115 +238,31 @@ impl<'conn> Provider<'conn> for VersionUpdaterProvider<'conn> {
fn get_definition(&self, condition: Option<&str>) -> String {
let _where_clause = condition.unwrap_or("true");
let mut aliases = HashMap::new();
- let _ = aliases.insert("{:app_version:}".to_string(), "app_version".to_string());
+ let _ = aliases.insert("{:db_version:}".to_string(), "db_version".to_string());
let projection = self.get_projection().expand(aliases);
format!(
r#"
-insert into app_version (application_type, semver) values (?, ?)
- on conflict (application_type) do update set semver = excluded.semver, updated_at = CURRENT_TIMESTAMP
+insert into db_version (application_type, version) values (?, ?)
+ on conflict (application_type) do update set version = excluded.version, updated_at = CURRENT_TIMESTAMP
returning {projection}
"#
)
}
}
-/// Struct to perform application version check in the database.
-#[derive(Debug)]
-pub struct ApplicationVersionChecker {
- /// Pathbuf to the SQLite3 file.
- sqlite_file_path: PathBuf,
-
- /// Application type which vesion is verified.
- application_type: ApplicationNodeType,
-
- /// logger
- logger: Logger,
-}
-
-impl ApplicationVersionChecker {
- /// constructor
- pub fn new(
- logger: Logger,
- application_type: ApplicationNodeType,
- sqlite_file_path: PathBuf,
- ) -> Self {
- Self {
- sqlite_file_path,
- application_type,
- logger,
- }
- }
-
- /// Performs an actual version check in the database. This method creates a
- /// connection to the SQLite3 file and drops it at the end.
- pub fn check(&self, current_semver: &str) -> Result<(), Box> {
- debug!(
- &self.logger,
- "check application version, database file = '{}'",
- self.sqlite_file_path.display()
- );
- let connection = Connection::open(&self.sqlite_file_path)?;
- let provider = VersionProvider::new(&connection);
- provider.create_table_if_not_exists()?;
- let updater = VersionUpdaterProvider::new(&connection);
- let maybe_option = provider.get_application_version(&self.application_type)?;
- let current_version = ApplicationVersion {
- semver: Version::parse(current_semver)?,
- application_type: self.application_type.clone(),
- updated_at: Local::now().naive_local(),
- };
-
- match maybe_option {
- None => {
- let current_version = updater.save(current_version)?;
- debug!(
- &self.logger,
- "Application version '{}' saved in database.", current_version.semver
- );
- }
- Some(version) => match current_version.semver.cmp(&version.semver) {
- Ordering::Greater => {
- warn!(
- &self.logger,
- "Application version '{}' is out of date, new version is '{}'. Upgrading database…",
- version.semver, current_version.semver
- );
- updater.save(current_version)?;
- debug!(&self.logger, "database updated");
- }
- Ordering::Less => {
- error!(
- &self.logger,
- "Software version '{}' is older than database structure version '{}'.",
- current_version.semver,
- version.semver
- );
-
- Err("This software version is older than the database structure. Aborting launch to prevent possible data corruption.")?;
- }
- Ordering::Equal => {
- debug!(&self.logger, "database up to date");
- }
- },
- };
-
- Ok(())
- }
-}
-
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_projection() {
- let projection = ApplicationVersionProjection::new();
+ let projection = DatabaseVersionProjection::new();
let mut aliases: HashMap = HashMap::new();
- let _ = aliases.insert("{:app_version:}".to_string(), "whatever".to_string());
+ let _ = aliases.insert("{:db_version:}".to_string(), "whatever".to_string());
assert_eq!(
- "whatever.semver as semver, whatever.application_type as application_type, whatever.updated_at as updated_at"
+ "whatever.version as version, whatever.application_type as application_type, whatever.updated_at as updated_at"
.to_string(),
projection.expand(aliases)
);
@@ -337,12 +271,12 @@ mod tests {
#[test]
fn test_definition() {
let connection = Connection::open(":memory:").unwrap();
- let provider = VersionProvider::new(&connection);
+ let provider = DatabaseVersionProvider::new(&connection);
assert_eq!(
r#"
-select app_version.semver as semver, app_version.application_type as application_type, app_version.updated_at as updated_at
-from app_version
+select db_version.version as version, db_version.application_type as application_type, db_version.updated_at as updated_at
+from db_version
where true
"#,
provider.get_definition(None)
@@ -352,47 +286,15 @@ where true
#[test]
fn test_updated_entity() {
let connection = Connection::open(":memory:").unwrap();
- let provider = VersionUpdaterProvider::new(&connection);
+ let provider = DatabaseVersionUpdater::new(&connection);
assert_eq!(
r#"
-insert into app_version (application_type, semver) values (?, ?)
- on conflict (application_type) do update set semver = excluded.semver, updated_at = CURRENT_TIMESTAMP
-returning app_version.semver as semver, app_version.application_type as application_type, app_version.updated_at as updated_at
+insert into db_version (application_type, version) values (?, ?)
+ on conflict (application_type) do update set version = excluded.version, updated_at = CURRENT_TIMESTAMP
+returning db_version.version as version, db_version.application_type as application_type, db_version.updated_at as updated_at
"#,
provider.get_definition(None)
)
}
-
- fn check_database_version(filepath: &PathBuf, semver: &str) {
- let connection = Connection::open(filepath).unwrap();
- let provider = VersionProvider::new(&connection);
- let version = provider
- .get_application_version(&ApplicationNodeType::Aggregator)
- .unwrap()
- .expect("there should be a version in the database");
-
- assert_eq!(semver, version.semver.to_string());
- }
-
- #[test]
- fn test_application_version_checker() {
- let filepath = std::env::temp_dir().join("test.sqlite3");
-
- if filepath.exists() {
- std::fs::remove_file(filepath.as_path()).unwrap();
- }
- let app_checker = ApplicationVersionChecker::new(
- slog_scope::logger(),
- ApplicationNodeType::Aggregator,
- filepath.clone(),
- );
- app_checker.check("1.0.0").unwrap();
- check_database_version(&filepath, "1.0.0");
- app_checker.check("1.0.0").unwrap();
- check_database_version(&filepath, "1.0.0");
- app_checker.check("1.1.0").unwrap();
- check_database_version(&filepath, "1.1.0");
- app_checker.check("1.0.1").unwrap_err();
- }
}
diff --git a/mithril-common/src/database/mod.rs b/mithril-common/src/database/mod.rs
index a8b4af11f85..4c6050b6c18 100644
--- a/mithril-common/src/database/mod.rs
+++ b/mithril-common/src/database/mod.rs
@@ -2,5 +2,10 @@
//! This module contains providers and entities shared between all application types.
mod db_version;
+mod version_checker;
+
+/// Database version.
+pub type DbVersion = i64;
pub use db_version::*;
+pub use version_checker::{DatabaseVersionChecker, SqlMigration};
diff --git a/mithril-common/src/database/version_checker.rs b/mithril-common/src/database/version_checker.rs
new file mode 100644
index 00000000000..2c51b1a26bd
--- /dev/null
+++ b/mithril-common/src/database/version_checker.rs
@@ -0,0 +1,353 @@
+use chrono::Local;
+use slog::{debug, error};
+use slog::{info, Logger};
+use sqlite::Connection;
+use std::{cmp::Ordering, collections::BTreeSet, error::Error, path::PathBuf};
+
+use super::{
+ ApplicationNodeType, DatabaseVersion, DatabaseVersionProvider, DatabaseVersionUpdater,
+ DbVersion,
+};
+
+/// Struct to perform application version check in the database.
+#[derive(Debug)]
+pub struct DatabaseVersionChecker {
+ /// Pathbuf to the SQLite3 file.
+ sqlite_file_path: PathBuf,
+
+ /// Application type which vesion is verified.
+ application_type: ApplicationNodeType,
+
+ /// logger
+ logger: Logger,
+
+ /// known migrations
+ migrations: BTreeSet,
+}
+
+impl DatabaseVersionChecker {
+ /// constructor
+ pub fn new(
+ logger: Logger,
+ application_type: ApplicationNodeType,
+ sqlite_file_path: PathBuf,
+ ) -> Self {
+ let migrations = BTreeSet::new();
+
+ Self {
+ sqlite_file_path,
+ application_type,
+ logger,
+ migrations,
+ }
+ }
+
+ /// Register a migration.
+ pub fn add_migration(&mut self, migration: SqlMigration) -> &mut Self {
+ let _ = self.migrations.insert(migration);
+
+ self
+ }
+
+ /// Performs an actual version check in the database. This method creates a
+ /// connection to the SQLite3 file and drops it at the end.
+ pub fn apply(&self) -> Result<(), Box> {
+ debug!(
+ &self.logger,
+ "check database version, database file = '{}'",
+ self.sqlite_file_path.display()
+ );
+ let connection = Connection::open(&self.sqlite_file_path)?;
+ let provider = DatabaseVersionProvider::new(&connection);
+ provider.create_table_if_not_exists(&self.application_type)?;
+ let updater = DatabaseVersionUpdater::new(&connection);
+ let db_version = provider
+ .get_application_version(&self.application_type)?
+ .unwrap(); // At least a record exists.
+
+ // if no migration registered then we are at version 0.
+ let migration_version = self.migrations.iter().map(|m| m.version).max().unwrap_or(0);
+
+ match migration_version.cmp(&db_version.version) {
+ Ordering::Greater => {
+ debug!(
+ &self.logger,
+ "Database needs upgrade from version '{}' to version '{}', applying new migrations…",
+ db_version.version, migration_version
+ );
+ self.apply_migrations(&db_version, &updater, &connection)?;
+ info!(
+ &self.logger,
+ "database upgraded to version '{}'", migration_version
+ );
+ }
+ Ordering::Less => {
+ error!(
+ &self.logger,
+ "Software version '{}' is older than database structure version '{}'.",
+ db_version.version,
+ migration_version,
+ );
+
+ Err("This software version is older than the database structure. Aborting launch to prevent possible data corruption.")?;
+ }
+ Ordering::Equal => {
+ debug!(&self.logger, "database up to date");
+ }
+ };
+
+ Ok(())
+ }
+
+ fn apply_migrations(
+ &self,
+ starting_version: &DatabaseVersion,
+ updater: &DatabaseVersionUpdater,
+ connection: &Connection,
+ ) -> Result<(), Box> {
+ for migration in &self
+ .migrations
+ .iter()
+ .filter(|&m| m.version > starting_version.version)
+ .collect::>()
+ {
+ connection.execute(&migration.alterations)?;
+ let db_version = DatabaseVersion {
+ version: migration.version,
+ application_type: self.application_type.clone(),
+ updated_at: Local::now().naive_local(),
+ };
+ let _ = updater.save(db_version)?;
+ }
+
+ Ok(())
+ }
+}
+
+/// Represent a file containing SQL structure or data alterations.
+#[derive(Debug)]
+pub struct SqlMigration {
+ /// The semver version this migration targets.
+ pub version: DbVersion,
+
+ /// SQL statements to alter the database.
+ pub alterations: String,
+}
+
+impl SqlMigration {
+ /// Create a new SQL migration instance.
+ pub fn new(version: DbVersion, alteration: &str) -> Self {
+ Self {
+ version,
+ alterations: alteration.to_string(),
+ }
+ }
+}
+
+impl PartialOrd for SqlMigration {
+ fn partial_cmp(&self, other: &Self) -> Option {
+ self.version.partial_cmp(&other.version)
+ }
+}
+
+impl Ord for SqlMigration {
+ fn cmp(&self, other: &Self) -> Ordering {
+ self.partial_cmp(other).unwrap()
+ }
+}
+
+impl PartialEq for SqlMigration {
+ fn eq(&self, other: &Self) -> bool {
+ self.version.eq(&other.version)
+ }
+}
+
+impl Eq for SqlMigration {}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn check_database_version(filepath: &PathBuf, db_version: DbVersion) {
+ let connection = Connection::open(filepath).unwrap();
+ let provider = DatabaseVersionProvider::new(&connection);
+ let version = provider
+ .get_application_version(&ApplicationNodeType::Aggregator)
+ .unwrap()
+ .unwrap();
+
+ assert_eq!(db_version, version.version);
+ }
+
+ fn create_sqlite_file(name: &str) -> PathBuf {
+ let dirpath = std::env::temp_dir().join("mithril_test_database");
+ std::fs::create_dir_all(&dirpath).unwrap();
+ let filepath = dirpath.join(name);
+
+ if filepath.exists() {
+ std::fs::remove_file(filepath.as_path()).unwrap();
+ }
+
+ filepath
+ }
+
+ fn get_table_whatever_column_count(filepath: &PathBuf) -> i64 {
+ let connection = Connection::open(filepath).unwrap();
+ let sql = "select count(*) as column_count from pragma_table_info('whatever');";
+ let column_count = connection
+ .prepare(sql)
+ .unwrap()
+ .into_cursor()
+ .bind(&[])
+ .unwrap()
+ .next()
+ .unwrap()
+ .unwrap()
+ .get::(0);
+
+ column_count
+ }
+
+ #[test]
+ fn test_upgrade_with_migration() {
+ let filepath = create_sqlite_file("test_upgrade_with_migration.sqlite3");
+ let mut db_checker = DatabaseVersionChecker::new(
+ slog_scope::logger(),
+ ApplicationNodeType::Aggregator,
+ filepath.clone(),
+ );
+
+ db_checker.apply().unwrap();
+ assert_eq!(0, get_table_whatever_column_count(&filepath));
+
+ db_checker.apply().unwrap();
+ assert_eq!(0, get_table_whatever_column_count(&filepath));
+
+ let alterations = "create table whatever (thing_id integer); insert into whatever (thing_id) values (1), (2), (3), (4);";
+ let migration = SqlMigration {
+ version: 1,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ db_checker.apply().unwrap();
+ assert_eq!(1, get_table_whatever_column_count(&filepath));
+ check_database_version(&filepath, 1);
+
+ db_checker.apply().unwrap();
+ assert_eq!(1, get_table_whatever_column_count(&filepath));
+ check_database_version(&filepath, 1);
+
+ let alterations = "alter table whatever add column thing_content text; update whatever set thing_content = 'some content'";
+ let migration = SqlMigration {
+ version: 2,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ db_checker.apply().unwrap();
+ assert_eq!(2, get_table_whatever_column_count(&filepath));
+ check_database_version(&filepath, 2);
+
+ // in the test below both migrations are declared in reversed order to
+ // ensure they are played in the right order. The last one depends on
+ // the 3rd.
+ let alterations = "alter table whatever add column one_last_thing text; update whatever set one_last_thing = more_thing";
+ let migration = SqlMigration {
+ version: 4,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ let alterations = "alter table whatever add column more_thing text; update whatever set more_thing = 'more thing'";
+ let migration = SqlMigration {
+ version: 3,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ db_checker.apply().unwrap();
+ assert_eq!(4, get_table_whatever_column_count(&filepath));
+ check_database_version(&filepath, 4);
+ }
+
+ #[test]
+ fn starting_with_migration() {
+ let filepath = create_sqlite_file("starting_with_migration.sqlite3");
+ let mut db_checker = DatabaseVersionChecker::new(
+ slog_scope::logger(),
+ ApplicationNodeType::Aggregator,
+ filepath.clone(),
+ );
+
+ let alterations = "create table whatever (thing_id integer); insert into whatever (thing_id) values (1), (2), (3), (4);";
+ let migration = SqlMigration {
+ version: 1,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ db_checker.apply().unwrap();
+ assert_eq!(1, get_table_whatever_column_count(&filepath));
+ check_database_version(&filepath, 1);
+ }
+
+ #[test]
+ /// This test case ensure that when multiple migrations are played and one fails:
+ /// * previous migrations are ok and the database version is updated
+ /// * further migrations are not played.
+ fn test_failing_migration() {
+ let filepath = create_sqlite_file("test_failing_migration.sqlite3");
+ let mut db_checker = DatabaseVersionChecker::new(
+ slog_scope::logger(),
+ ApplicationNodeType::Aggregator,
+ filepath.clone(),
+ );
+ // Table whatever does not exist, this should fail with error.
+ let alterations = "create table whatever (thing_id integer); insert into whatever (thing_id) values (1), (2), (3), (4);";
+ let migration = SqlMigration {
+ version: 1,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ let alterations = "alter table wrong add column thing_content text; update whatever set thing_content = 'some content'";
+ let migration = SqlMigration {
+ version: 2,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ let alterations = "alter table whatever add column thing_content text; update whatever set thing_content = 'some content'";
+ let migration = SqlMigration {
+ version: 3,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ db_checker.apply().unwrap_err();
+ check_database_version(&filepath, 1);
+ }
+
+ #[test]
+ fn test_fail_downgrading() {
+ let filepath = create_sqlite_file("test_fail_downgrading.sqlite3");
+ let mut db_checker = DatabaseVersionChecker::new(
+ slog_scope::logger(),
+ ApplicationNodeType::Aggregator,
+ filepath.clone(),
+ );
+ let alterations = "create table whatever (thing_id integer); insert into whatever (thing_id) values (1), (2), (3), (4);";
+ let migration = SqlMigration {
+ version: 1,
+ alterations: alterations.to_string(),
+ };
+ db_checker.add_migration(migration);
+ db_checker.apply().unwrap();
+ check_database_version(&filepath, 1);
+
+ // re instanciate a new checker with no migration registered (version 0).
+ let db_checker = DatabaseVersionChecker::new(
+ slog_scope::logger(),
+ ApplicationNodeType::Aggregator,
+ filepath.clone(),
+ );
+ assert!(
+ db_checker.apply().is_err(),
+ "using an old version with an up to date database should fail"
+ );
+ check_database_version(&filepath, 1);
+ }
+}
diff --git a/mithril-common/src/entities/single_signatures.rs b/mithril-common/src/entities/single_signatures.rs
index 8db29704c2a..570641be604 100644
--- a/mithril-common/src/entities/single_signatures.rs
+++ b/mithril-common/src/entities/single_signatures.rs
@@ -31,7 +31,7 @@ impl SingleSignatures {
}
}
- /// Convert this [SingleSignatures] to its corresponding [MithrilCore Signature][ProtocolSingleSignature].
+ /// Convert this [SingleSignatures] to its corresponding [MithrilStm Signature][ProtocolSingleSignature].
pub fn to_protocol_signature(&self) -> Result {
match key_decode_hex::(&self.signature) {
Ok(signature) => Ok(signature),
diff --git a/mithril-common/src/lib.rs b/mithril-common/src/lib.rs
index 0bb58961877..928a630e602 100644
--- a/mithril-common/src/lib.rs
+++ b/mithril-common/src/lib.rs
@@ -5,7 +5,7 @@
//! Provide:
//! - A way to store data with the [store] types
//! - [Digester][digesters] to compute mithril digest from a Cardano database
-//! - Helpers for the [Mithril Core](https://mithril.network/rust-doc/mithril/index.html)
+//! - Helpers for the [Mithril STM](https://mithril.network/rust-doc/mithril_stm/index.html)
//! lib with the [crypto_helper].
//! - A [certificate chain] used to validate the Certificate Chain created by an aggregator
//! - The [entities] used by, and exchanged between, the aggregator, signers and client.
diff --git a/mithril-core/README.md b/mithril-core/README.md
deleted file mode 100644
index 378ac8d1997..00000000000
--- a/mithril-core/README.md
+++ /dev/null
@@ -1,166 +0,0 @@
-Mithril-core  
-=======
-This crate is ongoing work, has not been audited, and it's API is by no means final. Do not use in production.
-
-### A rust implementation of Stake-based Threshold Multisignatures (STMs)
-`mithril-core` implements Stake-based Threshold Multisignatures as described in the paper
-[Mithril: Stake-based Threshold Multisignatures](https://eprint.iacr.org/2021/916.pdf), by
-Pyrros Chaidos and Aggelos Kiayias.
-
-This library uses zkcrypto's implementation of curve [BLS12-381](https://github.com/zkcrypto/bls12_381)
-by default for implementing the multisignature scheme. One can optionally choose the
-[blst](https://github.com/supranational/blst) backend (by using the feature `blast`),
-but this is not recommended due to some [flaky tests](https://github.com/input-output-hk/mithril/issues/207)
-That are still being resolved. We
-currently only support the trivial concatenation proof system (Section 4.3) and do not support
-other proof systems such as Bulletproofs or Halo2.
-
-This library provides implementations of:
-
-* Stake-based Threshold Multisignatures
-* Key registration procedure for STM signatures
-
-The user-facing documentation for the above modules can be found [here]().
-
-# Example
-```rust
-use mithril::key_reg::KeyReg;
-use mithril::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
-use rayon::prelude::*;
-
-use mithril::error::AggregationFailure;
-use rand_chacha::ChaCha20Rng;
-use rand_core::{RngCore, SeedableRng};
-
-type H = blake2::Blake2b;
-
-fn main() {
- let nparties = 32;
- let mut rng = ChaCha20Rng::from_seed([0u8; 32]);
- let mut msg = [0u8; 16];
- rng.fill_bytes(&mut msg);
-
- //////////////////////////
- // initialization phase //
- //////////////////////////
-
- let params = StmParameters {
- k: 357,
- m: 2642,
- phi_f: 0.2,
- };
-
- let parties = (0..nparties)
- .into_iter()
- .map(|_| 1 + (rng.next_u64() % 9999))
- .collect::>();
-
- let mut key_reg = KeyReg::init();
-
- let mut ps: Vec = Vec::with_capacity(nparties as usize);
- for stake in parties {
- let p = StmInitializer::setup(params, stake, &mut rng);
- key_reg.register(stake, p.verification_key()).unwrap();
- ps.push(p);
- }
-
- let closed_reg = key_reg.close();
-
- let ps = ps
- .into_par_iter()
- .map(|p| p.new_signer(closed_reg.clone()))
- .collect::>>();
-
- /////////////////////
- // operation phase //
- /////////////////////
-
- let sigs = ps
- .par_iter()
- .filter_map(|p| p.sign(&msg))
- .collect::>>();
-
- let clerk = StmClerk::from_signer(&ps[0]);
- let avk = clerk.compute_avk();
-
- // Check all parties can verify every sig
- for s in sigs.iter() {
- assert!(s.verify(¶ms, &avk, &msg).is_ok(), "Verification failed");
- }
-
- // Aggregate with random parties
- let msig = clerk.aggregate(&sigs, &msg);
-
- assert!(msig.is_ok(), "aggregation failed");
- assert!(msig.unwrap().verify(&msg, &clerk.compute_avk(), ¶ms).is_ok());
-}
-```
-
-# Test and Benchmarks
-You can run tests of the library using `cargo test` (we recommend to use the `--release` flag, otherwise
-the tests might take a while) and run benchmarks using `cargo bench`. This crate uses `criterion` to run
-benchmarks.
-
-We have run the benchmarks on an Apple M1 Pro machine with 16 GB of RAM, on macOS 12.6.
-
-Note that single signatures in batch compat version does not depend on any variable and size of an individual signature is `176` bytes.
-
-```shell
-+----------------------+
-| Size of benchmarks |
-+----------------------+
-| Results obtained by using the parameters suggested in paper.
-+----------------------+
-+----------------------+
-| Aggregate signatures |
-+----------------------+
-+----------------------+
-| Hash: Blake2b 512 |
-+----------------------+
-k = 445 | m = 2728 | nr parties = 3000; 118760 bytes (old version = 356632 bytes)
-+----------------------+
-| Hash: Blake2b 256 |
-+----------------------+
-k = 445 | m = 2728 | nr parties = 3000; 99384 bytes (old version = 222536 bytes)
-+----------------------+
-+----------------------+
-| Aggregate signatures |
-+----------------------+
-| Hash: Blake2b 512 |
-+----------------------+
-k = 554 | m = 3597 | nr parties = 3000; 133936 bytes (old version = 419808 bytes)
-+----------------------+
-| Hash: Blake2b 256 |
-+----------------------+
-k = 554 | m = 3597 | nr parties = 3000; 113728 bytes (old version = 261488 bytes)
-make build && ./mithrildemo --nparties 16 -k 5 -m 5 --phi-f 0.9
-
-```
-
-```shell
-STM/Blake2b/Key registration/k: 25, m: 150, nr_parties: 300
- time: [409.70 ms 426.81 ms 446.30 ms]
-STM/Blake2b/Play all lotteries/k: 25, m: 150, nr_parties: 300
- time: [696.58 µs 697.62 µs 698.75 µs]
-STM/Blake2b/Aggregation/k: 25, m: 150, nr_parties: 300
- time: [18.765 ms 18.775 ms 18.785 ms]
-STM/Blake2b/Verification/k: 25, m: 150, nr_parties: 300
- time: [2.1577 ms 2.1715 ms 2.1915 ms]
-
-STM/Blake2b/Key registration/k: 250, m: 1523, nr_parties: 2000
- time: [2.5807 s 2.5880 s 2.5961 s]
-STM/Blake2b/Play all lotteries/k: 250, m: 1523, nr_parties: 2000
- time: [5.9318 ms 5.9447 ms 5.9582 ms]
-STM/Blake2b/Aggregation/k: 250, m: 1523, nr_parties: 2000
- time: [190.81 ms 191.15 ms 191.54 ms]
-STM/Blake2b/Verification/k: 250, m: 1523, nr_parties: 2000
- time: [13.944 ms 14.010 ms 14.077 ms]
-
-
-```
-
-# ToDo list once we go public
-- [ ] Upload mithril-core to crates.io
-- [ ] Ensure that the badges are working
-- [ ] Update links for crates and docs
-- [ ] Error handling
diff --git a/mithril-signer/Dockerfile b/mithril-signer/Dockerfile
index 11df77dc717..029feb915be 100644
--- a/mithril-signer/Dockerfile
+++ b/mithril-signer/Dockerfile
@@ -18,8 +18,8 @@ RUN adduser --no-create-home --disabled-password appuser
WORKDIR /app
# Copy local dependencies
-COPY mithril-core/ /mithril-core/
-COPY Cargo.lock /mithril-core/
+COPY mithril-stm/ /mithril-stm/
+COPY Cargo.lock /mithril-stm/
COPY mithril-common/ /mithril-common/
COPY Cargo.lock /mithril-common/
diff --git a/mithril-signer/src/main.rs b/mithril-signer/src/main.rs
index 493ddd05d99..f5cba9b7243 100644
--- a/mithril-signer/src/main.rs
+++ b/mithril-signer/src/main.rs
@@ -5,7 +5,7 @@ use std::sync::Arc;
use std::time::Duration;
use std::{error::Error, path::PathBuf};
-use mithril_common::database::{ApplicationNodeType, ApplicationVersionChecker};
+use mithril_common::database::{ApplicationNodeType, DatabaseVersionChecker};
use mithril_signer::{
Config, ProductionServiceBuilder, ServiceBuilder, SignerRunner, SignerState, StateMachine,
};
@@ -83,12 +83,12 @@ async fn main() -> Result<(), Box> {
.try_deserialize()
.map_err(|e| format!("configuration deserialize error: {}", e))?;
let services = ProductionServiceBuilder::new(&config).build()?;
- ApplicationVersionChecker::new(
+ DatabaseVersionChecker::new(
slog_scope::logger(),
ApplicationNodeType::Signer,
config.get_sqlite_file(),
)
- .check(env!("CARGO_PKG_VERSION"))?;
+ .apply()?;
debug!("Started"; "run_mode" => &args.run_mode, "config" => format!("{:?}", config));
let mut state_machine = StateMachine::new(
diff --git a/mithril-signer/src/runtime/runner.rs b/mithril-signer/src/runtime/runner.rs
index 99e830d9f72..6c83c6153b8 100644
--- a/mithril-signer/src/runtime/runner.rs
+++ b/mithril-signer/src/runtime/runner.rs
@@ -165,12 +165,18 @@ impl Runner for SignerRunner {
) -> Result<(), Box> {
debug!("RUNNER: register_signer_to_aggregator");
+ let epoch_offset_to_recording_epoch = epoch.offset_to_recording_epoch()?;
let stake_distribution = self
.services
- .chain_observer
- .get_current_stake_distribution()
+ .stake_store
+ .get_stakes(epoch_offset_to_recording_epoch)
.await?
- .ok_or_else(|| RuntimeError::NoValueError("current_stake_distribution".to_string()))?;
+ .ok_or_else(|| {
+ RuntimeError::NoValueError(format!(
+ "stakes at epoch {}",
+ epoch_offset_to_recording_epoch
+ ))
+ })?;
let stake = stake_distribution
.get(&self.services.single_signer.get_party_id())
.ok_or(RuntimeError::NoStakeForSelf())?;
@@ -430,6 +436,7 @@ impl Runner for SignerRunner {
#[cfg(test)]
mod tests {
+ use mithril_common::chain_observer::ChainObserver;
use mockall::mock;
use std::{path::PathBuf, sync::Arc};
@@ -573,6 +580,24 @@ mod tests {
let protocol_initializer_store = services.protocol_initializer_store.clone();
let chain_observer = Arc::new(FakeObserver::default());
services.chain_observer = chain_observer.clone();
+ let epoch = services
+ .beacon_provider
+ .get_current_beacon()
+ .await
+ .unwrap()
+ .epoch
+ .offset_to_recording_epoch()
+ .unwrap();
+ let stakes = chain_observer
+ .get_current_stake_distribution()
+ .await
+ .unwrap()
+ .unwrap();
+ services
+ .stake_store
+ .save_stakes(epoch, stakes)
+ .await
+ .unwrap();
let runner = init_runner(Some(services), None);
let epoch = chain_observer
.current_beacon
diff --git a/mithril-signer/tests/state_machine.rs b/mithril-signer/tests/state_machine.rs
index 504f8aac362..b01e541e45c 100644
--- a/mithril-signer/tests/state_machine.rs
+++ b/mithril-signer/tests/state_machine.rs
@@ -1,13 +1,20 @@
mod test_extensions;
-use mithril_common::entities::Epoch;
+use mithril_common::{
+ crypto_helper::tests_setup,
+ entities::{Epoch, SignerWithStake},
+};
use test_extensions::StateMachineTester;
#[rustfmt::skip]
#[tokio::test]
async fn test_create_single_signature() {
- let mut tester = StateMachineTester::init().await;
+
+ let protocol_parameters = tests_setup::setup_protocol_parameters();
+ let signers = tests_setup::setup_signers(10, &protocol_parameters);
+ let signers_with_stake = signers.iter().map(|(signer_with_stake, _, _)| signer_with_stake.to_owned()).collect::>();
+ let mut tester = StateMachineTester::init(&signers_with_stake).await.expect("state machine tester init should not fail");
tester
.comment("state machine starts and remains in Unregistered state until a epoch settings is got")
@@ -25,7 +32,7 @@ async fn test_create_single_signature() {
.comment("getting an epoch settings changes the state → Registered")
.aggregator_send_epoch_settings().await
.cycle_registered().await.unwrap()
- .register_signers(2).await.unwrap()
+ .register_signers(&signers_with_stake[..2]).await.unwrap()
.check_protocol_initializer(Epoch(3)).await.unwrap()
.check_stake_store(Epoch(3)).await.unwrap()
diff --git a/mithril-signer/tests/test_extensions/state_machine_tester.rs b/mithril-signer/tests/test_extensions/state_machine_tester.rs
index 267812a5288..bdad0410b97 100644
--- a/mithril-signer/tests/test_extensions/state_machine_tester.rs
+++ b/mithril-signer/tests/test_extensions/state_machine_tester.rs
@@ -45,7 +45,13 @@ pub struct StateMachineTester {
}
impl StateMachineTester {
- pub async fn init() -> Self {
+ pub async fn init(signers_with_stake: &[SignerWithStake]) -> Result {
+ let selected_signer_with_stake = signers_with_stake.first().ok_or_else(|| {
+ TestError::AssertFailed("there should be at least one signer with stakes".to_string())
+ })?;
+ let selected_signer_party_id = selected_signer_with_stake.party_id.clone();
+ let selected_signer_temp_dir =
+ tests_setup::setup_temp_directory_for_signer(&selected_signer_party_id, false);
let config = Config {
aggregator_endpoint: "http://0.0.0.0:8000".to_string(),
cardano_cli_path: PathBuf::new(),
@@ -53,12 +59,16 @@ impl StateMachineTester {
db_directory: PathBuf::new(),
network: "devnet".to_string(),
network_magic: Some(42),
- party_id: Some("99999999999999999999999999999999".to_string()),
+ party_id: Some(selected_signer_party_id),
run_interval: 5000,
data_stores_directory: PathBuf::new(),
store_retention_limit: None,
- kes_secret_key_path: None,
- operational_certificate_path: None,
+ kes_secret_key_path: selected_signer_temp_dir
+ .as_ref()
+ .map(|dir| dir.join("kes.sk")),
+ operational_certificate_path: selected_signer_temp_dir
+ .as_ref()
+ .map(|dir| dir.join("opcert.cert")),
};
let decorator = slog_term::PlainDecorator::new(slog_term::TestStdoutWriter);
@@ -103,22 +113,9 @@ impl StateMachineTester {
stake_store: stake_store.clone(),
};
// set up stake distribution
- let protocol_parameters = tests_setup::setup_protocol_parameters();
- let mut signers: Vec =
- tests_setup::setup_signers(10, &protocol_parameters)
- .into_iter()
- .map(|(signer_with_stake, _, _)| signer_with_stake)
- .collect();
- signers.push(SignerWithStake {
- party_id: "99999999999999999999999999999999".to_string(),
- stake: 999,
- verification_key: "".to_string(),
- verification_key_signature: None,
- operational_certificate: None,
- kes_period: None,
- });
-
- chain_observer.set_signers(signers).await;
+ chain_observer
+ .set_signers(signers_with_stake.to_owned())
+ .await;
let runner = Box::new(SignerRunner::new(config, services));
@@ -128,7 +125,7 @@ impl StateMachineTester {
Duration::from_secs(5),
);
- StateMachineTester {
+ Ok(StateMachineTester {
state_machine,
immutable_observer,
chain_observer,
@@ -137,7 +134,7 @@ impl StateMachineTester {
stake_store,
comment_no: 0,
_logs_guard: logs_guard,
- }
+ })
}
fn assert(&mut self, condition: bool, description: String) -> Result<&mut Self> {
@@ -279,11 +276,11 @@ impl StateMachineTester {
}
/// register the signer in the certificate handler
- pub async fn register_signers(&mut self, count: u64) -> Result<&mut Self> {
- let protocol_parameters = tests_setup::setup_protocol_parameters();
- for (signer_with_stake, _signer, _protocol_initializer) in
- tests_setup::setup_signers(count, &protocol_parameters)
- {
+ pub async fn register_signers(
+ &mut self,
+ signers_with_stake: &[SignerWithStake],
+ ) -> Result<&mut Self> {
+ for signer_with_stake in signers_with_stake {
self.certificate_handler
.register_signer(&signer_with_stake.to_owned().into())
.await
diff --git a/mithril-core/.dockerignore b/mithril-stm/.dockerignore
similarity index 100%
rename from mithril-core/.dockerignore
rename to mithril-stm/.dockerignore
diff --git a/mithril-core/.gitignore b/mithril-stm/.gitignore
similarity index 100%
rename from mithril-core/.gitignore
rename to mithril-stm/.gitignore
diff --git a/mithril-core/Cargo.toml b/mithril-stm/Cargo.toml
similarity index 77%
rename from mithril-core/Cargo.toml
rename to mithril-stm/Cargo.toml
index 3db6c4016f3..9fcdf44f8a3 100644
--- a/mithril-core/Cargo.toml
+++ b/mithril-stm/Cargo.toml
@@ -1,12 +1,23 @@
[package]
-name = "mithril"
+name = "mithril-stm"
version = "0.1.0"
-edition = "2018"
+edition = { workspace = true }
authors = { workspace = true }
documentation = { workspace = true }
homepage = { workspace = true }
license = { workspace = true }
repository = { workspace = true }
+description = "A Rust implementation of Mithril Stake-based Threshold Multisignatures (STMs)."
+categories = ["cryptography"]
+include = [
+ "**/*.rs",
+ "Cargo.toml",
+ "README.md",
+ ".gitignore",
+]
+
+[lib]
+crate-type = ["lib", "cdylib", "staticlib"]
[dependencies]
blake2 = "0.10.4"
diff --git a/mithril-core/Dockerfile b/mithril-stm/Dockerfile
similarity index 100%
rename from mithril-core/Dockerfile
rename to mithril-stm/Dockerfile
diff --git a/mithril-core/Makefile b/mithril-stm/Makefile
similarity index 100%
rename from mithril-core/Makefile
rename to mithril-stm/Makefile
diff --git a/mithril-stm/README.md b/mithril-stm/README.md
new file mode 100644
index 00000000000..3f76308e746
--- /dev/null
+++ b/mithril-stm/README.md
@@ -0,0 +1,196 @@
+# Mithril-stm  
+
+
+**This is a work in progress** :hammer_and_wrench:s
+
+* `mithril-stm` is a Rust implementation of the scheme described in the paper [Mithril: Stake-based Threshold Multisignatures](https://eprint.iacr.org/2021/916.pdf) by Pyrros Chaidos and Aggelos Kiayias.
+* The BLS12-381 signature library [blst](https://github.com/supranational/blst) is used as the backend for the implementation of STM.
+* This implementation supports the _trivial concatenation proof system_ (Section 4.3). Other proof systems such as _Bulletproofs_ or _Halo2_ are not supported in this version.
+* We implemented the concatenation proof system as batch proofs:
+ * Individual signatures do not contain the Merkle path to prove membership of the avk. Instead, it is the role of the aggregator to generate such proofs. This allows for a more efficient implementation of batched membership proofs (or batched Merkle paths).
+* Protocol documentation is given in [Mithril Protocol in depth](https://mithril.network/doc/mithril/mithril-protocol/protocol/).
+
+
+* This library provides:
+ * The implementation of the Stake-based Threshold Multisignatures
+ * Key registration procedure for STM signatures
+ * The tests for the library functions and STM scheme
+ * Benchmark tests
+
+## Pre-requisites
+
+**Install Rust**
+
+* Install a [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+## Download source code
+
+```bash
+# Download sources from github
+git clone https://github.com/input-output-hk/mithril
+
+# Go to sources directory
+cd mithril-stm
+```
+
+## Compiling the library
+```shell
+cargo build --release
+```
+
+## Running the tests
+For running rust tests, simply run (to run the tests faster, the use of `--release` flag is recommended):
+```shell
+cargo test --release
+```
+
+## Running the benches
+```shell
+cargo bench
+```
+
+
+## Example
+
+The following is a simple example of the STM implementation:
+
+```rust
+use mithril_stm::key_reg::KeyReg;
+use mithril_stm::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
+use mithril_stm::AggregationError;
+
+use blake2::{digest::consts::U32, Blake2b};
+use rayon::prelude::*;
+use rand_chacha::ChaCha20Rng;
+use rand_core::{RngCore, SeedableRng};
+
+type H = Blake2b;
+
+fn main() {
+ let nparties = 32;
+ let mut rng = ChaCha20Rng::from_seed([0u8; 32]);
+ let mut msg = [0u8; 16];
+ rng.fill_bytes(&mut msg);
+
+ //////////////////////////
+ // initialization phase //
+ //////////////////////////
+
+ let params = StmParameters {
+ k: 357,
+ m: 2642,
+ phi_f: 0.2,
+ };
+
+ let parties = (0..nparties)
+ .into_iter()
+ .map(|_| 1 + (rng.next_u64() % 9999))
+ .collect::>();
+
+ let mut key_reg = KeyReg::init();
+
+ let mut ps: Vec = Vec::with_capacity(nparties as usize);
+ for stake in parties {
+ let p = StmInitializer::setup(params, stake, &mut rng);
+ key_reg.register(stake, p.verification_key()).unwrap();
+ ps.push(p);
+ }
+
+ let closed_reg = key_reg.close();
+
+ let ps = ps
+ .into_par_iter()
+ .map(|p| p.new_signer(closed_reg.clone()).unwrap())
+ .collect::>>();
+
+ /////////////////////
+ // operation phase //
+ /////////////////////
+
+ let sigs = ps
+ .par_iter()
+ .filter_map(|p| p.sign(&msg))
+ .collect::>();
+
+ let clerk = StmClerk::from_signer(&ps[0]);
+ let avk = clerk.compute_avk();
+
+ // Check all parties can verify every sig
+ for s in sigs.iter() {
+ assert!(s.verify(¶ms, &avk, &msg).is_ok(), "Verification failed");
+ }
+
+ // Aggregate with random parties
+ let msig = clerk.aggregate(&sigs, &msg);
+
+ match msig {
+ Ok(aggr) => {
+ println!("Aggregate ok");
+ assert!(aggr.verify(&msg, &clerk.compute_avk(), ¶ms).is_ok());
+ }
+ Err(AggregationError::NotEnoughSignatures(n, k)) => {
+ println!("Not enough signatures");
+ assert!(n < params.k && k == params.k)
+ }
+ Err(AggregationError::UsizeConversionInvalid) => {
+ println!("Invalid usize conversion");
+ }
+ }
+}
+```
+
+## Benchmarks
+
+Here we give the benchmark results of STM for size and time. We run the benchmarks on macOS 12.6 on an Apple M1 Pro machine with 16 GB of RAM.
+
+Note that the size of an individual signature with one valid index is **176 bytes** and increases linearly in the length of valid indices (where an index is 8 bytes).
+
+```shell
++----------------------+
+| Size of benchmarks |
++----------------------+
+| Results obtained by using the parameters suggested by the paper.
++----------------------+
++----------------------+
+| Aggregate signatures |
++----------------------+
++----------------------+
+| Hash: Blake2b 512 |
++----------------------+
+k = 445 | m = 2728 | nr parties = 3000; 118760 bytes
++----------------------+
+| Hash: Blake2b 256 |
++----------------------+
+k = 445 | m = 2728 | nr parties = 3000; 99384 bytes
++----------------------+
++----------------------+
+| Aggregate signatures |
++----------------------+
+| Hash: Blake2b 512 |
++----------------------+
+k = 554 | m = 3597 | nr parties = 3000; 133936 bytes
++----------------------+
+| Hash: Blake2b 256 |
++----------------------+
+k = 554 | m = 3597 | nr parties = 3000; 113728 bytes
+```
+
+```shell
+STM/Blake2b/Key registration/k: 25, m: 150, nr_parties: 300
+ time: [409.70 ms 426.81 ms 446.30 ms]
+STM/Blake2b/Play all lotteries/k: 25, m: 150, nr_parties: 300
+ time: [696.58 µs 697.62 µs 698.75 µs]
+STM/Blake2b/Aggregation/k: 25, m: 150, nr_parties: 300
+ time: [18.765 ms 18.775 ms 18.785 ms]
+STM/Blake2b/Verification/k: 25, m: 150, nr_parties: 300
+ time: [2.1577 ms 2.1715 ms 2.1915 ms]
+
+STM/Blake2b/Key registration/k: 250, m: 1523, nr_parties: 2000
+ time: [2.5807 s 2.5880 s 2.5961 s]
+STM/Blake2b/Play all lotteries/k: 250, m: 1523, nr_parties: 2000
+ time: [5.9318 ms 5.9447 ms 5.9582 ms]
+STM/Blake2b/Aggregation/k: 250, m: 1523, nr_parties: 2000
+ time: [190.81 ms 191.15 ms 191.54 ms]
+STM/Blake2b/Verification/k: 250, m: 1523, nr_parties: 2000
+ time: [13.944 ms 14.010 ms 14.077 ms]
+```
diff --git a/mithril-core/benches/size_benches.rs b/mithril-stm/benches/size_benches.rs
similarity index 94%
rename from mithril-core/benches/size_benches.rs
rename to mithril-stm/benches/size_benches.rs
index 7b0867ec65f..6531f0e95fb 100644
--- a/mithril-core/benches/size_benches.rs
+++ b/mithril-stm/benches/size_benches.rs
@@ -3,8 +3,8 @@ use blake2::{
digest::consts::{U32, U64},
Blake2b, Digest,
};
-use mithril::key_reg::KeyReg;
-use mithril::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
+use mithril_stm::key_reg::KeyReg;
+use mithril_stm::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
use rand_chacha::ChaCha20Rng;
use rand_core::{RngCore, SeedableRng};
use rayon::iter::ParallelIterator;
diff --git a/mithril-core/benches/stm.rs b/mithril-stm/benches/stm.rs
similarity index 96%
rename from mithril-core/benches/stm.rs
rename to mithril-stm/benches/stm.rs
index 56671e8e740..c2e5e490e78 100644
--- a/mithril-core/benches/stm.rs
+++ b/mithril-stm/benches/stm.rs
@@ -1,8 +1,8 @@
use blake2::digest::{Digest, FixedOutput};
use blake2::{digest::consts::U32, Blake2b};
use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
-use mithril::key_reg::KeyReg;
-use mithril::stm::{StmClerk, StmInitializer, StmParameters, StmSigner};
+use mithril_stm::key_reg::KeyReg;
+use mithril_stm::stm::{StmClerk, StmInitializer, StmParameters, StmSigner};
use rand_chacha::ChaCha20Rng;
use rand_core::{RngCore, SeedableRng};
use rayon::prelude::*;
diff --git a/mithril-core/examples/key_registration.rs b/mithril-stm/examples/key_registration.rs
similarity index 97%
rename from mithril-core/examples/key_registration.rs
rename to mithril-stm/examples/key_registration.rs
index d270f082356..904c0ef6d67 100644
--- a/mithril-core/examples/key_registration.rs
+++ b/mithril-stm/examples/key_registration.rs
@@ -2,8 +2,8 @@
//! but instead by all the participants in the signature process. Contrarily to the full protocol
//! run presented in `tests/integration.rs`, we explicitly treat each party individually.
use blake2::{digest::consts::U32, Blake2b};
-use mithril::key_reg::{ClosedKeyReg, KeyReg};
-use mithril::stm::{Stake, StmClerk, StmInitializer, StmParameters, StmVerificationKeyPoP};
+use mithril_stm::key_reg::{ClosedKeyReg, KeyReg};
+use mithril_stm::stm::{Stake, StmClerk, StmInitializer, StmParameters, StmVerificationKeyPoP};
use rand_chacha::ChaCha20Rng;
use rand_core::{RngCore, SeedableRng};
diff --git a/mithril-core/proptest-regressions/stm.txt b/mithril-stm/proptest-regressions/stm.txt
similarity index 100%
rename from mithril-core/proptest-regressions/stm.txt
rename to mithril-stm/proptest-regressions/stm.txt
diff --git a/mithril-core/src/dense_mapping.rs b/mithril-stm/src/dense_mapping.rs
similarity index 100%
rename from mithril-core/src/dense_mapping.rs
rename to mithril-stm/src/dense_mapping.rs
diff --git a/mithril-core/src/error.rs b/mithril-stm/src/error.rs
similarity index 100%
rename from mithril-core/src/error.rs
rename to mithril-stm/src/error.rs
diff --git a/mithril-core/src/key_reg.rs b/mithril-stm/src/key_reg.rs
similarity index 100%
rename from mithril-core/src/key_reg.rs
rename to mithril-stm/src/key_reg.rs
diff --git a/mithril-core/src/lib.rs b/mithril-stm/src/lib.rs
similarity index 85%
rename from mithril-core/src/lib.rs
rename to mithril-stm/src/lib.rs
index 4b15171e997..d7e96a42226 100644
--- a/mithril-core/src/lib.rs
+++ b/mithril-stm/src/lib.rs
@@ -1,4 +1,5 @@
#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
//! Implementation of Stake-based Threshold Multisignatures
mod dense_mapping;
diff --git a/mithril-core/src/merkle_tree.rs b/mithril-stm/src/merkle_tree.rs
similarity index 100%
rename from mithril-core/src/merkle_tree.rs
rename to mithril-stm/src/merkle_tree.rs
diff --git a/mithril-core/src/multi_sig.rs b/mithril-stm/src/multi_sig.rs
similarity index 99%
rename from mithril-core/src/multi_sig.rs
rename to mithril-stm/src/multi_sig.rs
index eb29be1e6ef..7f86fd34567 100644
--- a/mithril-core/src/multi_sig.rs
+++ b/mithril-stm/src/multi_sig.rs
@@ -1,9 +1,6 @@
//! Base multisignature scheme, used as a primitive for STM.
//! See Section 2.4 of [the paper](https://eprint.iacr.org/2021/916).
-//! This module uses the `blst` library as a backend for pairings
-//! and can be activated by using the feature `blast`. This feature
-//! is not chosen by default due to some flaky tests, as exposed in the
-//! [issue](https://github.com/input-output-hk/mithril/issues/207)
+//! This module uses the `blst` library as a backend for pairings.
use crate::error::{blst_err_to_atms, MultiSignatureError};
use crate::stm::Index;
diff --git a/mithril-core/src/stm.rs b/mithril-stm/src/stm.rs
similarity index 99%
rename from mithril-core/src/stm.rs
rename to mithril-stm/src/stm.rs
index 766248f2626..047da642553 100644
--- a/mithril-core/src/stm.rs
+++ b/mithril-stm/src/stm.rs
@@ -7,9 +7,9 @@
//! ```rust
//! # fn main() -> Result<(), Box> {
//! use blake2::{Blake2b, digest::consts::U32};
-//! use mithril::key_reg::KeyReg; // Import key registration functionality
-//! use mithril::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
-//! use mithril::AggregationError;
+//! use mithril_stm::key_reg::KeyReg; // Import key registration functionality
+//! use mithril_stm::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
+//! use mithril_stm::AggregationError;
//! use rayon::prelude::*; // We use par_iter to speed things up
//!
//! use rand_chacha::ChaCha20Rng;
diff --git a/mithril-core/tests/integration.rs b/mithril-stm/tests/integration.rs
similarity index 93%
rename from mithril-core/tests/integration.rs
rename to mithril-stm/tests/integration.rs
index fd86f1e756f..6a8758f16e5 100644
--- a/mithril-core/tests/integration.rs
+++ b/mithril-stm/tests/integration.rs
@@ -1,13 +1,11 @@
-use blake2::{digest::consts::U32, Blake2b};
-
-use mithril::key_reg::KeyReg;
-use mithril::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
-use mithril::AggregationError;
-
-use rayon::prelude::*;
+use mithril_stm::key_reg::KeyReg;
+use mithril_stm::stm::{StmClerk, StmInitializer, StmParameters, StmSig, StmSigner};
+use mithril_stm::AggregationError;
+use blake2::{digest::consts::U32, Blake2b};
use rand_chacha::ChaCha20Rng;
use rand_core::{RngCore, SeedableRng};
+use rayon::prelude::*;
type H = Blake2b;
diff --git a/mithril-test-lab/mithril-end-to-end/Cargo.toml b/mithril-test-lab/mithril-end-to-end/Cargo.toml
index eabaf6c834a..8af94578218 100644
--- a/mithril-test-lab/mithril-end-to-end/Cargo.toml
+++ b/mithril-test-lab/mithril-end-to-end/Cargo.toml
@@ -27,4 +27,6 @@ tokio = { version = "1.17.0", features = ["full"] }
tokio-util = { version = "0.7.1", features = ["codec"] }
[features]
+default = ["allow_skip_signer_certification"]
portable = ["mithril-common/portable"]
+allow_skip_signer_certification = []
diff --git a/mithril-test-lab/mithril-end-to-end/src/mithril/infrastructure.rs b/mithril-test-lab/mithril-end-to-end/src/mithril/infrastructure.rs
index 25e11c1d0ba..400102d8e06 100644
--- a/mithril-test-lab/mithril-end-to-end/src/mithril/infrastructure.rs
+++ b/mithril-test-lab/mithril-end-to-end/src/mithril/infrastructure.rs
@@ -39,9 +39,11 @@ impl MithrilInfrastructure {
let mut signers: Vec = vec![];
for (index, pool_node) in devnet_topology.pool_nodes.iter().enumerate() {
- // 50% of signers with key certification
- // TODO: Should be removed 100% once the signer certification is fully deployed
- let enable_certification = index % 2 == 0;
+ // 50% of signers with key certification if allow unverified signer registration
+ // Or 100% of signers otherwise
+ // TODO: Should be removed once the signer certification is fully deployed
+ let enable_certification =
+ index % 2 == 0 || cfg!(not(feature = "allow_skip_signer_certification"));
let mut signer = Signer::new(
aggregator.endpoint(),
pool_node,
.default})
+
+## Under the hood
+
+In its first version, the **Mithril Signer** is composed of a main component:
+
+* A runtime that is powered by a state machine:
+ * The runtime is synchronous and is scheduled to execute at regular intervals.
+ * There are three possible states: **UNREGISTERED**, **REGISTERED** and **SIGNED**.
+ * The runtime handles state transitions.
+ * The runtime is summarized in the diagram below:
+
+
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/_category_.json b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/_category_.json
new file mode 100644
index 00000000000..c03b858b985
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Mithril Protocol",
+ "collapsible": true,
+ "collapsed": false,
+ "position": 1,
+ "link": {
+ "type": "generated-index",
+ "title": "Mithril Protocol Topics"
+ }
+}
\ No newline at end of file
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/certificates.md b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/certificates.md
new file mode 100644
index 00000000000..b80a67b232c
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/certificates.md
@@ -0,0 +1,130 @@
+---
+sidebar_position: 2
+sidebar_label: Certificate Chain in depth
+---
+
+# Mithril Certificate Chain in depth
+
+## Introduction
+
+The **Mithril Protocol** can be summarized as:
+
+> A protocol that allows stakeholders in a Proof-of-Stake blockchain network to individually sign messages that are aggregated into a multi signature which guarantees that they represent a minimum share of the total stakes.
+
+The **stake distribution** that is used to create the multi signature can't be trusted "as is" and must also be signed. Indeed, any one could relatively easily create a **Fake Stake Distribution** and use it to produce a valid multi signature that would be embedded in a perfectly **Valid but Non Genuine Certificate**. This certificate could be served by a dishonest **Mithril Aggregator** node and thus could lead to restoring a non genuine snapshot by a honest **Mithril Client**.
+
+In order to avoid this type of **eclipse attack**, the **stake distribution** used to create a multi signature must be certified beforehand. This is where the **Certificate Chain** takes place.
+
+## The Certificate Chain Design
+
+:::danger
+
+The **Stake Distribution** of an epoch is computed by the **Cardano Nodes** at the end of this epoch. It will be usable from the beginning of the following epoch.
+
+:::
+
+A way to certify the **stake distribution** used to create a multi signature is to verify that it has been previously signed in an earlier certificate. Then one can recursively verify that the earlier certificate is valid the same way. This process can be designed as a **Chain** of certificates: the **Mithril Certificate Chain**.
+
+As multiple certificates may be created during the same epoch (i.e. with the same stake distribution), it is sufficient to link to only one certificate of the previous epoch: this will allow faster verification times and it will also avoid network congestion.
+
+Also, the certificate at the beginning of the **Certificate Chain** has a special role. This is the **Genesis Certificate**. The only way to validate the stake distributon embedded in the **Genesis Certificate** is to sign it with a private key that is associated to a broadly available public key: the **Genesis Keys**. These are the keys that sign the hard forks used during the era transitions of the Cardano Blockchain.
+
+Here is a diagram illustrating the **Certificate Chain** design:
+[](images/certificate-chain.jpg)
+
+Where the following notations have been used:
+
+* `C(p,n)`: Certificate at trigger `p` and epoch `n`
+* `FC(n)`: First Certificate of epoch `n`
+* `GC`: Genesis Certificate
+* `H()`: Hash
+* `SD(n)`: Stake Distribution of epoch `n`
+* `VK(n)`: Verification Key at epoch `n`
+* `AVK(n)`: Aggregrate Verification Key at epoch `n` such as `AVK(n) = MKT_ROOT(SD(n) || VK(n))`
+* `MKT_ROOT()`: Merkle-tree root
+* `BEACON(p,n)`: Beacon at trigger `p` and epoch `n`
+* `METADATA(p,n)`: Metadata of the certificate at trigger `p` and epoch `n`
+* `MSG(p,n)`: Message of the certificate at trigger `p` and epoch `n`
+* `MULTI_SIG(p,n)`: Multi signature created to the message `H(MSG(p,n) || AVK(n-1))`
+* `GENESIS_SIG(MSG)`: Genesis Signature, i.e. signature of `MSG` with the Genesis Keys
+
+The hash of a **Certificate** `H(C(p,n))` is computed as the concatenation (`||`) of all its fields. Therefore, if one field is modified, its hash is different.
+
+The informations embedded in the `METADATA(p,n)` field are:
+
+* The version of the Mithril Protocol
+* The parameter of the Mithril Protocol (`k`, `m`, and `phi_f`)
+* The date and time at which the multi signature creation was initiated
+* The date and time at which the Certificate was sealed
+* The list of the signers that actively contributed to the multi signature
+
+The message `MSG(p,n)` is a map of multiple values associated with their respective keys and provides a way to add more informations in the certificates without breaking the chain itself. These can be any message that the signers are able to compute deterministically thanks to the Cardano consensus: an immutable files snapshot, the Utxo set, the stahe distribution, ...
+
+:::note
+
+The **trigger** represents the instant at which a certificate should be created. It is combined, with at least the associated **epoch** to create the [**Beacon**](../../glossary.md#beacon) of the certificate. In the current implementation, this trigger is a new [**Immutable File Number**](../../glossary.md#immutable-file-number). The epoch creation and the trigger creation processes may be uncorrelated.
+
+:::
+
+:::info
+
+The `AVK` or **Aggregate Verification Key** is the root of the Merkle-tree where each leaf is filled with `H(STAKE(signer) || VK(signer))`. It represents the corresponding **Stake Distribution** in a condensed way.
+:::
+
+## The Verification Algorithm
+
+The **Certificate Chain** verification can be stated as:
+
+```
+CHAIN_VERIFY[C(p,n(p))] = CERT_VERIFY[C(p,n(p)] ^ CERT_VERIFY[FC(n(p))] ^ CERT_VERIFY[FC(n(p)-1)] ^ ... ^ CERT_VERIFY[FC(1)] ^ CERT_VERIFY[GC]
+```
+
+Where the following notations have been used:
+
+* The epoch `n(p)` depends on the trigger `p`
+* `CHAIN_VERIFY[]`: Verify all the chain backward from a certificate
+* `CERT_VERIFY[]`: Verify a specific certificate
+
+A **Certificate Chain** is valid if from a **Certificate**, up to the **Genesis Certificate** of the chain there is at least one valid certificate per epoch.
+
+A non **Genesis Certificate** is valid **if and only if** the `AVK` used to verify the multi signature is also part of the signed message used to create a valid multi signature in a previously sealed Certificate.
+
+The **Genesis Certificate** is valid **if and only if** its **Genesis Signature** is verified with the advertised **Public Genesis Key**.
+
+An implementation of the algorithm would work as follows for a certificate:
+
+* **Step 1**: Use this certificate as the `current_certificate`
+* **Step 2**: Verify (or fail) that the `current_hash` of the `current_certificate` is valid (by computing it and comparing with the `hash` field of the certificate)
+* **Step 3**: Get the `previous_hash` of the `previous_certificate` by reading its value in the `current_certificate`
+* **Step 4**: Verify (or fail) that the `multi_signature` of the `current_certificate` is valid
+* **Step 5**: Retrieve the `previous_certificate` that has the hash `previous_hash`:
+ * **Step 5.1**: If it is not a `genesis_certificate`:
+ * **Step 5.1.1**: Verify (or fail) that the `previous_hash` of the `previous_certificate` is valid (by computing it and comparing with the `hash` field of the certificate)
+ * **Step 5.1.2**: Verify the `current_avk`
+ * **Step 5.1.2.1**: If the `current_certificate` is the `first_certificate` of the epoch, verify (or fail) that the `current_avk` of the `current_certificate` is part of the message signed by the multi signature of the `previous_certificate`
+ * **Step 5.1.2.2**: Else verify (or fail) that the `current_avk` of the `current_certificate` is the same as the `current_avk` of the `previous_certificate`
+ * **Step 5.1.3**: Verify (or fail) that the `multi_signature` of the `previous_certificate` is valid
+ * **Step 5.1.4**: Use the `previous_certificate` as `current_certificate` and start again at **Step 2**
+ * **Step 5.2**: If it is a `genesis_certificate`:
+ * **Step 5.2.1**: Verify (or fail) that the `previous_hash` of the `previous_certificate` is valid (by computing it and comparing with the `hash` field of the certificate)
+ * **Step 5.2.2**: Verify (or fail) that the `current_avk` of the `current_certificate` is part of the message signed by the genesis signature of the `previous_certificate`
+ * **Step 5.2.3**: The certificate is valid (Success)
+
+## The coexistence of multiple Certificate Chain
+
+What would happen if some **Mithril Aggregator** claims that not enough signatures were received? This doesn’t really matter, as there will be a different **Mithril Aggregator** that would collect sufficient signatures and aggregate them into a valid Certificate.
+
+Similarly, different **Mithril Aggregators** might have different views of the **individual signatures** submitted (one aggregator might receive 10 signatures, and a different one could receive 11), which would result in different **Certificates** signing the same message.
+
+This would result in different **Certificate Chains** that would all link back to the **Genesis Certificate**. Indeed they would be represented by a tree of certificates where each traversal path from the root to a leaf represent a valid **Certificate Chain**.
+
+## The need of backward compatibility
+
+The **Certificate Chain** is designed to last. At a certain point, we will need to handle the verification of the multi signature from legacy versions of the **Mithril** cryptographic library.
+
+In order to achieve this backward compatibility, some options are available:
+
+* Handle multi signature verification functions of legacy versions
+* Recreate Genesis Certificates from time to time
+* Create intermediate **Milestones Certificates** (with both a multi signature and a genesis signature)
+* Design a format migration algorithm
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/images/certificate-chain.jpg b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/images/certificate-chain.jpg
new file mode 100644
index 00000000000..56ada5833c0
Binary files /dev/null and b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/images/certificate-chain.jpg differ
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/protocol.md b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/protocol.md
new file mode 100644
index 00000000000..005b0b3d295
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/protocol.md
@@ -0,0 +1,137 @@
+---
+sidebar_position: 1
+sidebar_label: Protocol in depth
+---
+
+# Mithril Protocol in depth
+
+:::info
+
+The research paper `Mithril: Stake-based Threshold Multisignatures` is downloadable [here](https://iohk.io/en/research/library/papers/mithril-stake-based-threshold-multisignatures/).
+
+:::
+
+:::info New
+
+:new: Interact with the **Mithril Protocol** by experiencing with our [protocol simulation](./simulation.md). This will help you understand how the participants interact to create a multi signature and what's the impact of the protocol parameters.
+
+:::
+
+:::tip
+
+For more information about the **Mithril Network**, please refer to the [Architecture](../mithril-network/architecture.md) page.
+
+:::
+
+## Introduction
+
+The full details of the Mithril protocol are provided in the published paper. This section is high-level description of
+the protocol in layman’s terms.
+
+In a nutshell, Mithril is a signature scheme that generates a certificate that convinces
+the verifiers that a portion of the stake of a system has signed a message.
+
+However, rather than taking the whole set of
+stake holders, Mithril
+"randomly selects" a subset of them, and requires a portion of that subset to provide a signature.
+
+An analogy would be
+that Mithril signers participate in a lottery which defines if they are entitled to sign a particular message. In case
+they win this lottery, then they can go ahead and sign the message. Whenever a sufficient number of parties have won the
+lottery (and submitted their respective signatures), a certificate can be computed.
+
+## The phases of the protocol
+
+The protocol has 3 different phases:
+
+1. **Protocol Establishment phase** which determines the parameters that will be used by Mithril participants. Also,
+ during this phase, the set of "allowed signers" is defined.
+2. **Initialization phase** during which Mithril nodes generate and exchange keys,
+3. **Operations phase** during which nodes sign and aggregate signatures of messages to produce certificates.
+
+:::note Note
+
+Note that all 3 phases require the set of parties (`P` in the paper) to be fixed. During the protocol establishment phase
+three important parameters are generated:
+
+* `m`, defines the number of "lotteries" that a single user can participate in to sign a message.
+* `k`, defines the required number of single signatures to produce a valid certificate.
+* `phi_f` (as denoted in the library) which can be interpreted as the chance of a signer to win a lottery.
+
+:::
+
+Now, let's assume that we want to generate a valid signature for message `msg` using a mithril signature. Then we need `k` valid signatures from the subset of signers.
+
+To this end, each player is allowed to participate in `m` "lotteries" to see if it "wins" the right to sign the message.
+
+If none of this lotteries are won by this particular signer, then it will not be able to submit a signature.
+
+If, contrarily, the signer wins one of the lotteries (or more than one), then it
+can submit the corresponding signature (or all of the corresponding signatures respectively) to produce the valid certificate. The chance of winning the lottery is defined by a function over `phi_f`. The closer `phi_f` is to one, the higher the chances of winning a lottery are.
+
+This means that there exists the possibility that a particular message cannot be certified using Mithril under a given set of parameters. There could be a scenario where not enough signers have won the allowed lotteries to produce a valid certificate. In which case the parameters can be adapted.
+
+### 1. Protocol Establishment Phase
+
+* Select/fix a prime order group to be used as basis for multi-signature scheme
+* _When using bulletproof_: Generate a "random" string, for example by taking some unpredictable data from the net (hash
+ of latest block, stockmarket quotes) and hash it
+* When requested by a party, return the parameters and random string
+
+This setup phase must be done only once and is valid for as long as the same proof system, e.g the parameters can very well be statically baked into the various systems producing and consuming Mithril proofs.
+
+Similarly, during the protocol establishment phase, the parameters `k`, `m` and `phi_f` are defined, as well as the set of allowed signers.
+
+### 2. Initialisation Phase
+
+This phase includes both the actual initialisation phase of each party, and the registration of keys.
+
+* Party retrieves the protocol parameters
+* It uses the parameters to generate a new key pair of a verification key and a signing key, plus a Proof-of-possession
+ `κ`. The verification key and PoP are broadcast to all other parties for registration, which is expected to last for
+ some limited period of time. An important difference with the paper is that registration is not centralised in the "
+ idealised" manner described in the paper. Instead, all signers will register against all other signers. Meaning that
+ each signer will trace it's own registration procedure. Together with other participants' keys, the stake of each
+ party is stored.
+* Then an aggregate verification key (`AVK` in the paper) is created from the registration material, in the form of a
+ Merkle-tree.
+
+The key dissemination process can also happen on-chain, which makes sense as the parties need to have some guarantees about the validity of keys and stakes of each other party.
+
+This phase happens once for each _instance_ of the protocol running.
+
+### 3. Operations Phase
+
+Operations run in cycles, where each cycle is triggered by a message (eg. a snapshot of the UTxO set) to sign for which
+a quorum of `k` valid signatures must be submitted.
+
+* Each party needs to check for eligibility to sign the message. It may be eligible to sign the same message more than once. This check is performed for `m` distinct indices. For every index, the signer evaluates a function (parameterized with `phi_f`) that takes its stake as input. If the result of the function is `SUCCESS`, then the signer is eligible to sign this message for the given index.
+
+* For every valid signature, it creates a proof (`Ï€`) containing a signature of the message, verification key, stake and paths of party in the Merkle-tree.
+
+* Then, multiple signatures can be aggregated together to form a certificate (`Ï„`) by:
+ * Verifying signatures from each party:
+ * Checking the party is authorized to sign for the given index (using the same procedure as the signing)
+ * Checking the proof is valid which means:
+ * Check the evaluation threshold is correct for party’s stake given the message, index and signature
+ * Check the provided path exists in the aggregate keys' Merkle-tree
+ * Verify the signature of the message is valid w.r.t to verification key
+ * Producing an aggregation key from all verification keys
+ * Producing an aggregate signature from all signatures `μ`
+ * Producing a proof using the aggregate keys, the message and the vector of individual proofs from each party:
+ * In the concatenation proof system all these values are simply packed together to form the proof,
+ * In the case of _bulletproof_ system, a more compact proof is generated.
+
+* Each certificate `τ` can be verified to be valid for some message, using the known setup parameters to verify the certificate’s proof and then verifying the aggregate signatures and verification keys.
+
+:::note Note
+
+Note that if the individual signatures are broadcast to all parties, then each party can independently produce the certificates. In particular, the party that performs aggregation is not required to have any specific knowledge, nor it is assumed to be honest. This means that _any_ third party that has access to the individual signatures can perform the signature aggregation.
+
+:::
+
+:::tip
+
+For more information about the **Mithril Network**, please refer to the [Architecture](../mithril-network/architecture.md) page.
+
+:::
diff --git a/docs/versioned_docs/version-maintained/mithril/mithril-protocol/simulation.md b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/simulation.md
new file mode 100644
index 00000000000..819de9de974
--- /dev/null
+++ b/docs/versioned_docs/version-maintained/mithril/mithril-protocol/simulation.md
@@ -0,0 +1,299 @@
+---
+sidebar_position: 3
+sidebar_label: Simulation
+---
+
+# Mithril Protocol Simulation
+
+:::info
+
+* Thanks to this demo you will get a better understanding of the **Mithril Protocol**. You will hopefully visualize how the participants interact to create a multi signature and what's the impact of the protocol parameters.
+
+* This simulation is ran by a CLI that you will build and run, and that will ultimately generate **real** Mithril multi signatures!
+
+* For the purpose of reproducibility of the results, the simulation uses a deterministic source of randomness.
+
+* During the simulation some artifacts will be written to an `artifacts` folder, such as `verification keys`, `individual signatures` and `multi signatures`.
+
+:::
+
+## What you'll need
+
+* A Linux (preferred) or a macOS computer.
+
+* A [correctly configured](https://www.rust-lang.org/learn/get-started) Rust toolchain (latest stable version).
+
+## Download source
+
+Download from Github (HTTPS)
+
+```bash
+git clone https://github.com/input-output-hk/mithril.git
+```
+
+Or (SSH)
+
+```bash
+git clone git@github.com:input-output-hk/mithril.git
+```
+
+## Build Mithril Protocol demo binary
+
+Change directory
+
+```bash
+cd mithril/demo/protocol-demo
+```
+
+Run tests (Optional)
+
+```bash
+make test
+```
+
+Build executable
+
+```bash
+make build
+```
+
+## Verify build
+
+Check that the Mithril Client binary is working fine by running its help
+
+```bash
+./mithrildemo -h
+```
+
+You should see
+
+```bash
+mithrildemo
+Simple demonstration of the Mithril protocol
+
+USAGE:
+ mithrildemo [OPTIONS]
+
+OPTIONS:
+ -h, --help Print help information
+ -k, --k