Version: Current

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 page.
For more information about the Mithril Aggregator, please refer to the Aggregator Node page.

Mithril Networks

Here is an up to date list of all the Mithril Networks, their configurations and their status:

Last update: 02/28/2023

Preview
Preprod
Mainnet

`pre-release-preview`

Information	-
Mithril Network	`pre-release-preview` 🔎
Cardano Network	`preview`
Cardano Magic Id	`2`
Supported	Yes ✔️
Status	Pre-Release 🟠
Aggregator Endpoint	`https://aggregator.pre-release-preview.api.mithril.network/aggregator` ↗️
Genesis Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey` ↗️
Era Reader Adapter Type	`cardano-chain`
Era Reader Address	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/era.addr` ↗️
Era Reader Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/era.vkey` ↗️
Build From	Latest Pre-Release ↗️

`testing-preview`

⚠️ For devs only

Information	-
Mithril Network	`testing-preview` 🔎
Cardano Network	`preview`
Cardano Magic Id	`2`
Supported	Yes ✔️
Status	Unstable 🔴
Aggregator Endpoint	`https://aggregator.testing-preview.api.mithril.network/aggregator` ↗️
Genesis Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/genesis.vkey` ↗️
Era Reader Adapter Type	`cardano-chain`
Era Reader Address	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/era.addr` ↗️
Era Reader Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/testing-preview/era.vkey` ↗️
Build From	Main Branch ↗️

`release-preprod`

Information	-
Mithril Network	`release-preprod` 🔎
Cardano Network	`preprod`
Cardano Magic Id	`1`
Supported	Yes ✔️
Status	Release 🟢
Aggregator Endpoint	`https://aggregator.release-preprod.api.mithril.network/aggregator` ↗️
Genesis Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey` ↗️
Era Reader Adapter Type	`cardano-chain`
Era Reader Address	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/era.addr` ↗️
Era Reader Verification Key	`https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/era.vkey` ↗️
Build From	Latest Release ↗️

`release-mainnet`

Information	-
Mithril Network	`release-mainnet`
Cardano Network	`mainnet`
Cardano Magic Id	`-`
Supported	No ❌
Status	-
Aggregator Endpoint	-
Genesis Verification Key	-
Era Reader Adapter Type	-
Era Reader Address	-
Era Reader Verification Key	-
Build From	-

caution

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/mithril-infra/configuration/release-preprod/genesis.vkey)
**YOUR_ERA_READER_ADAPTER_TYPE** identifier, but you need to replace it with the era reader adapter type used by the Mithril network you target (e.g. cardano-chain)
**YOUR_ERA_READER_ADDRESS** identifier, but you need to replace it with the era reader address url used by the Mithril network you target (e.g. https://raw.githubusercontent.com/input-output-hk/mithril/main/address.addr)
**YOUR_ERA_READER_VERIFICATION_KEY** identifier, but you need to replace it with the era reader verification key url used by the Mithril network you target (e.g. https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_era.vkey)

Resources

Node	Source Repository	Rust Documentation	Docker Packages
Mithril Aggregator	↗️	↗️	↗️

Pre-requisites

Install a correctly configured 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.40. Run sqlite3 --version to check your version.

Download source

Download from GitHub (HTTPS)

git clone https://github.com/input-output-hk/mithril.git

Or (SSH)

git clone git@github.com:input-output-hk/mithril.git

Switch to build branch / tag

# **YOUR_BUILD_BRANCH_OR_TAG** depends on the Mithril network you target, 
# please refer to the **Build From** column of the above **Mithril Networks** table
git switch **YOUR_BUILD_BRANCH_OR_TAG**

Change directory

cd mithril/mithril-aggregator

Development test and build

Run tests

make test

Create the help menu

make help

Generate the Rust documentation

make doc

Run in debug mode with default configuration

make debug

Release build and run binary 'serve' command

Build and run in release with default configuration

make run

Or, build only in release

make build

Display the help menu

./mithril-aggregator --help

You should see

Mithril Aggregator Node

Usage: mithril-aggregator [OPTIONS] <COMMAND>

Commands:
  genesis  Genesis tools
  era      Era tools
  serve    Server runtime mode
  help     Print this message or the help of the given subcommand(s)

Options:
  -r, --run-mode <RUN_MODE>
          Run Mode [default: dev]
  -v, --verbose...
          Verbosity level
      --db-directory <DB_DIRECTORY>
          Directory of the Cardano node files
      --config-directory <CONFIG_DIRECTORY>
          Directory where configuration file is located [default: ./config]
  -h, --help
          Print help
  -V, --version
          Print version

Run 'serve' command in release with default configuration

./mithril-aggregator serve

Run 'serve' command in release with a specific mode

./mithril-aggregator -r preview serve

Run 'serve' command in release with a custom configuration via env vars

GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) RUN_INTERVAL=60000 NETWORK=**YOUR_CARDANO_NETWORK** ./mithril-aggregator serve

Release build and run binary 'genesis' command

Build in release with default configuration

make build

Display the help menu

./mithril-aggregator genesis --help

You should see

mithril-aggregator-genesis 
Aggregator runs in Genesis tools mode
USAGE:
    mithril-aggregator genesis <SUBCOMMAND>
OPTIONS:
    -h, --help    Print help information
SUBCOMMANDS:
    bootstrap    Bootstrap a genesis certificate Test only usage
    export       Export payload to sign with genesis secret key
    help         Print this message or the help of the given subcommand(s)
    import       Import payload signed with genesis secret key and create & import a genesis certificate

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.

./mithril-aggregator genesis bootstrap

Or with a specific Genesis Secret Key, only in test mode.

./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.

./mithril-aggregator genesis export

Or with a custom export path (to override the default value ./mithril-genesis-payload.txt)

./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.

./mithril-aggregator genesis import

Or with a custom export path (to override the default value ./mithril-genesis-signed-payload.txt)

./mithril-aggregator genesis import --signed-payload-path **YOUR_SIGNED_PAYLOAD_PATH**

Run 'genesis import' command in release with a custom configuration via env vars

GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) RUN_INTERVAL=60000 NETWORK=**YOUR_CARDANO_NETWORK** ./mithril-aggregator genesis import

Release build and run binary 'era' command

Build in release with default configuration

make build

Display the help menu

./mithril-aggregator era --help

You should see

Era tools

Usage: mithril-aggregator era <COMMAND>

Commands:
  list               Era list command
  generate-tx-datum  Era tx datum generate command
  help               Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Run 'era list' to list the supported eras embedded in the binary

./mithril-aggregator era list

You should see something like

Supported Eras:
[
    Thales,
]

tip

You can use the --json option in order to display results in JSON format for the list command:

./mithril-aggregator era list --json

You should see something like

["thales"]

Run 'era generate-tx-datum' to generate the transaction datum file to be stored on the Cardano chain that will provide era markers to the 'cardano-chain' era reader adapter

Case 1: There is only one supported era in the code, create the datum file with

./mithril-aggregator era generate-tx-datum --current-era-epoch **EPOCH_AT_WHICH_CURRENT_ERA_STARTS** --era-markers-secret-key **YOUR_ERA_ACTIVATION_SECRET_KEY**

You should see something like

{"constructor":0,"fields":[{"bytes":"5b7b226e223a227468616c6573222c2265223a317d5d"},{"bytes":"a58fe8e336f465ded3bba7c5a7afe5b5a26f2fb65b7c4e6e742e680645f13df28bf2b63a61cc72d9c826be490e2c1f1098d955df503580a4e899b5173884e30e"}]}

Case 2: There are two supported era in the code, in order to announce the upcoming era (i.e. the activation epoch of this era is not known yet), run the command

./mithril-aggregator era generate-tx-datum --current-era-epoch **EPOCH_AT_WHICH_CURRENT_ERA_STARTS** --era-markers-secret-key **YOUR_ERA_ACTIVATION_SECRET_KEY**

Case 3: There are two supported era in the code, in order to activate the era switch at a following epoch (i.e. the activation epoch of this era known), run the command

./mithril-aggregator era generate-tx-datum --current-era-epoch **EPOCH_AT_WHICH_CURRENT_ERA_STARTS** --next-era-epoch **EPOCH_AT_WHICH_NEXT_ERA_STARTS** --era-markers-secret-key **YOUR_ERA_ACTIVATION_SECRET_KEY**

tip

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)

Download compiled binary

Each Release / Pre-Release distribution comes with pre compiled binaries ready to use or wrapped in a debian package.

You can download them from the Release / Pre-Release distribution page that depends on the Mithril Network you are targeting.

These links are available in the Build From column of the above Mithril Networks table.

Build and run Docker container

Build a local Docker image

make docker-build

Run a local Docker container

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)
era list	List the supported eras
era generate-tx-datum	Generate era markers transaction datum to be stored on chain

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`	✔️
`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`	✔️
`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`	✔️
`db_directory`	`--db-directory`	-	`DB_DIRECTORY`	Directory of the Cardano Node stores	`/db`	-	✔️
`genesis_verification_key`	-	-	`GENESIS_VERIFICATION_KEY`	Genesis verification key	-	-	✔️
`network`	-	-	`NETWORK`	Cardano network	-	`testnet` or `mainnet` or `devnet`	✔️
`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 }`	✔️
`run_mode`	`--run-mode`	`-r`	`RUN_MODE`	Runtime mode	`dev`	-	✔️
`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`	✔️

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`	-	✔️
`server_port`	`--server-port`	-	`SERVER_PORT`	Listening server port	`8080`	-	✔️
`snapshot_directory`	`--snapshot-directory`	-	`SNAPSHOT_DIRECTORY`	Directory to store local snapshots of the Cardano Node	`.`	-	✔️
`snapshot_store_type`	-	-	`SNAPSHOT_STORE_TYPE`	Type of snapshot store to use	-	`gcp` or `local`	✔️
`snapshot_uploader_type`	-	-	`SNAPSHOT_UPLOADER_TYPE`	Type of snapshot uploader to use	-	`gcp` or `local`	✔️
`snapshot_bucket_name`	-	-	`SNAPSHOT_BUCKET_NAME`	Name of the bucket where the snapshots are stored	-	`snapshot-bucket`	✔️
`run_interval`	-	-	`RUN_INTERVAL`	Interval between two runtime cycles in ms	-	`60000`	✔️
`url_snapshot_manifest`	-	-	`URL_SNAPSHOT_MANIFEST`	Snapshots manifest location	-	Only if `snapshot_store_type` is `gcp`, else it should be ``	✔️
`era_reader_adapter_type`	`--era-reader-adapter-type`	-	`ERA_READER_ADAPTER_TYPE`	Era reader adapter type that can be `cardano-chain`, `file` or `bootstrap`.	`bootstrap`	-	-
`era_reader_adapter_params`	`--era-reader-adapter-params`	-	`ERA_READER_ADAPTER_PARAMS`	Era reader adapter params that is an optional JSON encoded parameters structure that is expected depending on the `era_reader_adapter_type` parameter	-	-	-

genesis bootstrap command:

Parameter	Command Line (long)	Command Line (short)	Environment Variable	Description	Default Value	Example	Mandatory
`genesis_secret_key`	-	-	`GENESIS_SECRET_KEY`	Genesis secret key, ⚠️ 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.	-	-	-

era list command:

Parameter	Command Line (long)	Command Line (short)	Environment Variable	Description	Default Value	Example	Mandatory
`json`	`--json`	-	-	Export the supported era list to JSON format.	-	-	-

era generate-tx-datum command:

Parameter	Command Line (long)	Command Line (short)	Environment Variable	Description	Default Value	Example	Mandatory
`current_era_epoch`	`--current-era-epoch`	-	`CURRENT_ERA_EPOCH`	Epoch at which current era starts.	-	-	-
`next_era_epoch`	`--next-era-epoch`	-	`NEXT_ERA_EPOCH`	Epoch at which the next era starts. If not specified and an upcoming era is available, it will announce the next era. If specified, it must be strictly greater than `current-epoch-era`	-	-	-
`era_markers_secret_key`	`--era-markers-secret-key`	-	`ERA_MARKERS_SECRET_KEY`	Era Markers Secret Key that is used to verify the authenticity of the era markers on chain.	-	-	-

Mithril Aggregator Node

pre-release-preview​

testing-preview​

release-preprod​

release-mainnet​

Resources​

Pre-requisites​

Download source​

Development test and build​

Release build and run binary 'serve' command​

Release build and run binary 'genesis' command​

Release build and run binary 'era' command​

Download compiled binary​

Build and run Docker container​

Subcommands​

Configuration parameters​

`pre-release-preview`

`testing-preview`

`release-preprod`

`release-mainnet`

Resources

Pre-requisites

Download source

Development test and build

Release build and run binary 'serve' command

Release build and run binary 'genesis' command

Release build and run binary 'era' command

Download compiled binary

Build and run Docker container

Subcommands

Configuration parameters