Version: Next 🚧

Mithril aggregator node

info

Mithril aggregator is responsible for collecting individual signatures from the Mithril signers and aggregating them into a multi-signature. With this capability, the Mithril aggregator can provide certified snapshots of the Cardano blockchain.

tip

For more information about the Mithril network, please see the architecture overview
For more information about the Mithril aggregator, please see the aggregator node overview.

info

The Mithril network configurations are available in the Network configurations section of the user manual.

Resources

Node	Source repository	Rust documentation	Docker packages	REST API	Network configurations
Mithril aggregator	↗️	↗️	↗️	↗️	↗️

Prerequisites

Install the latest stable version of the correctly configured Rust toolchain
Install build tools build-essential and m4; for example, on Ubuntu/Debian/Mint, run sudo apt install build-essential m4
Install OpenSSL development libraries; for example, on Ubuntu/Debian/Mint, run apt install libssl-dev.

Download the source file

Download the source file 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 the desired branch/tag:

# Replace **YOUR_BUILD_BRANCH_OR_TAG** with the appropriate branch or tag name
# Please refer to the [**Network configurations**](http://mithril.network/manual/getting-started/network-configurations) section of the user manual
git checkout **YOUR_BUILD_BRANCH_OR_TAG**

Change the directory:

cd mithril/mithril-aggregator

Development testing and building

Run tests:

make test

Create the help menu:

make help

Generate the Rust documentation:

make doc

To run in debug mode with the default configuration, use the following command:

make debug

Release the build and run the binary 'serve' command

To build and run in release mode with the default configuration:

make run

Or, build only in release mode:

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
  tools    List of tools to upkeep the aggregator
  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 the configuration file is located [default: ./config]
  -h, --help
          Print help
  -V, --version
          Print version

Run the 'serve' command in release mode with the default configuration:

./mithril-aggregator serve

Run the 'serve' command in release with a specific mode:

./mithril-aggregator -r preview serve

Run the 'serve' command in release mode with a custom configuration using environment variables:

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

Release the build and run the binary 'genesis' command

Build in release mode with the default configuration:

make build

Display the help menu:

./mithril-aggregator genesis --help

You should see:

mithril-aggregator-genesis
The 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

Bootstrap sub-command (test-only)

You can run the 'genesis bootstrap' command in release mode with the default configuration, but only in test mode. This will enable the Mithril aggregator node to bootstrap a genesis certificate. After completing this operation, the Mithril aggregator will be able to produce new snapshots and certificates.

./mithril-aggregator genesis bootstrap

You can use a specific genesis secret key (only in test mode):

./mithril-aggregator genesis bootstrap --genesis-secret-key **YOUR_SECRET_KEY*

Export sub-command

You can run the 'genesis export' command in release mode. This allows the Mithril aggregator node to export the genesis payload that needs to be signed (and later reimported) for the genesis certificate. The signature of the genesis payload must be done manually by the owner of the genesis secret key.

./mithril-aggregator genesis export --target-path **YOUR_TARGET_PATH**

Sign sub-command

You can run the 'genesis sign' command in release mode. This allows the Mithril aggregator node to sign the genesis payload that needs to be reimported. The signature of the genesis payload must be done manually by the owner of the genesis secret key.

./mithril-aggregator genesis sign --to-sign-payload-path **TO_SIGN_PAYLOAD_PATH** --target-signed-payload-path **TARGET_SIGNED_PAYLOAD_PATH** --genesis-secret-key-path **GENESIS_SECRET_KEY_PATH**

Import sub-command

Run the 'genesis import' command in release mode. This allows the aggregator node to import the signed payload of the genesis certificate and store it. After this operation, the aggregator will be able to produce new snapshots and certificates.

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

Run the 'genesis import' command in release mode with a custom configuration using environment variables:

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

Release the build and run the binary 'era' command

Build in release mode using the 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 the 'era list' command to list the supported eras embedded in the binary:

./mithril-aggregator era list

You should see something like:

Supported Eras:
[
    Thales,
]

tip

To display results in JSON format for the list command, simply use the --json option:

./mithril-aggregator era list --json

You should see something like:

["thales"]

You can run 'era generate-tx-datum' to create the transaction datum file that will be stored on the Cardano chain, providing era markers to the 'cardano-chain' era reader adapter.

Case 1: If there is only one supported era in the code, create the datum file:

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

You should see something like:

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

Case 2: If there are two supported eras in the code and the activation epoch of the upcoming era is not yet known, 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** --target-path **TARGET_PATH**

Case 3: If there are two supported eras in the code and the activation epoch of the era switch is known to be at the following epoch, 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** --target-path **TARGET_PATH**

Release the build and run the binary 'tools' command

Build in release mode using the default configuration:

make build

Display the help menu:

./mithril-aggregator tools --help

You should see:

List of tools to upkeep the aggregator

Usage: mithril-aggregator tools <COMMAND>

Commands:
  recompute-certificates-hash  Load all certificates in the database to recompute their hash and update all related entities
  help                         Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Run the 'tools recompute-certificates-hash' command in release mode with the default configuration. This allows the Mithril aggregator node to recompute all of its certificate hashes, which is useful to avoid a chain re-genesis after an update that changes the structure of the certificates.

./mithril-aggregator tools recompute-certificates-hash

tip

If you wish to delve deeper and access several levels of logs from the Mithril aggregator, use the following:

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 the pre-built binary

You can install a the latest released binary of the mithril-aggregator by running this one line command (replace YOUR_PATH with your installation path):

curl --proto '=https' --tlsv1.2 -sSf
https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh
| sh -s -- -c mithril-aggregator -d latest -p YOUR_PATH

tip

You can also install the mithril-aggregator binary for other distributions:

use -d unstable for the unstable version
use -d **DISTRIBUTION_VERSION** for a specific distribution (e.g. -d 2445.0)

info

The Linux binaries target glibc, and have a minimum requirement of glibc 2.31 (compatible with Ubuntu 20.04 or Debian Bullseye).

Build and run the Docker container

Build a local Docker image:

make docker-build

Run a local Docker container:

make docker-run

Subcommands

Here are the available subcommands:

Subcommand	Performed action
serve	The aggregator runs its HTTP server in nominal mode and orchestrates multi-signature production
help	Prints this message or the help of the given subcommand(s)
genesis export	Exports genesis payload to sign with genesis secret key
genesis sign	Signs the genesis payload with the genesis secret key
genesis import	Imports the genesis signature (the payload signed with the genesis secret key) and creates and imports a genesis certificate in the store
genesis bootstrap	Bootstraps a genesis certificate (test only usage)
genesis generate-keypair	Generates a genesis keypair
era list	Lists the supported eras
era generate-tx-datum	Generates the era markers transaction datum to be stored on-chain
tools recompute-certificates-hash	Loads all certificates in the database, recomputing their hash, and updating all related entities

Configuration parameters

The configuration parameters can be set in either of the following ways:

In a configuration file, depending on the --run-mode parameter. If the runtime mode is testnet, the file is located in ./conf/testnet.json.
The value can be overridden by an environment variable with the parameter name in uppercase.

Here is a list of the available 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 the 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`	Required if `snapshot_uploader_type` is `gcp`
`snapshot_use_cdn_domain`	-	-	`SNAPSHOT_USE_CDN_DOMAIN`	Use CDN domain for constructing snapshot url	`false`	-	To be used if `snapshot_uploader_type` is `gcp`
`run_interval`	-	-	`RUN_INTERVAL`	Interval between two runtime cycles in ms	-	`60000`	✔️
`chain_observer_type`	`--chain-observer-type`	-	`CHAIN_OBSERVER_TYPE`	Chain observer type that can be `cardano-cli`, `pallas` or `fake`.	`pallas`	-	-
`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	-	-	-
`signed_entity_types`	`--signed-entity-types`	-	`SIGNED_ENTITY_TYPES`	Signed entity types parameters (discriminants names in an ordered comma separated list)	-	`MithrilStakeDistribution,CardanoImmutableFilesFull,CardanoStakeDistribution`	-
`snapshot_compression_algorithm`	`--snapshot-compression-algorithm`	-	`SNAPSHOT_COMPRESSION_ALGORITHM`	Compression algorithm of the snapshot archive	`zstandard`	`gzip` or `zstandard`	-
`zstandard_parameters`	-	-	`ZSTANDARD_PARAMETERS__LEVEL` and `ZSTANDARD_PARAMETERS__NUMBER_OF_WORKERS`	Zstandard specific parameters	-	`{ level: 9, number_of_workers: 4 }`	-
`allow_unparsable_block`	`--allow-unparsable-block`	-	`ALLOW_UNPARSABLE_BLOCK`	If set no error is returned in case of unparsable block and an error log is written instead. Will be ignored on (pre)production networks.	`false`	-	-
`cardano_transactions_signing_config`	-	-	`CARDANO_TRANSACTIONS_SIGNING_CONFIG__SECURITY_PARAMETER` and `CARDANO_TRANSACTIONS_SIGNING_CONFIG__STEP`	Cardano transactions signing configuration	-	`{ security_parameter: 3000, step: 120 }`	-
`cardano_transactions_prover_cache_pool_size`	`--cardano-transactions-prover-cache-pool-size`	-	`CARDANO_TRANSACTIONS_PROVER_CACHE_POOL_SIZE`	Cardano transactions prover cache pool size	`10`	`10`	-
`cardano_transactions_database_connection_pool_size`	`--cardano-transactions-database-connection-pool-size`	-	`CARDANO_TRANSACTIONS_DATABASE_CONNECTION_POOL_SIZE`	Cardano transactions database connection pool size	`10`	`10`	-
`cardano_transactions_prover_max_hashes_allowed_by_request`	`--cardano-transactions-prover-max-hashes-allowed-by-request`	-	`CARDANO_TRANSACTIONS_PROVER_MAX_HASHES_ALLOWED_BY_REQUEST`	Maximum number of transactions hashes allowed by request to the prover of the Cardano transactions	`100`	`100`	-
`cardano_transactions_block_streamer_max_roll_forwards_per_poll`	`--cardano-transactions-block-streamer-max-roll-forwards-per-poll`	-	`CARDANO_TRANSACTIONS_BLOCK_STREAMER_MAX_ROLL_FORWARDS_PER_POLL`	Maximum number of roll forwards during a poll of the block streamer when importing transactions	`1000`	`1000`	-
`cardano_transactions_signing_config`	`--cardano-transactions-signing-config`	-	`CARDANO_TRANSACTIONS_SIGNING_CONFIG`	Cardano transactions signing configuration	`{ "security_parameter": 3000, "step": 120 }`	`{ "security_parameter": 3000, "step": 120 }`	-
`enable_metrics_server`	`--enable-metrics-server`	-	`ENABLE_METRICS_SERVER`	Enable metrics HTTP server (Prometheus endpoint on /metrics)	`false`	-	-
`metrics_server_ip`	`--metrics-server-ip`	-	`METRICS_SERVER_IP`	Metrics HTTP server IP	`0.0.0.0`	-	-
`metrics_server_port`	`--metrics-server-port`	-	`METRICS_SERVER_PORT`	Metrics HTTP server listening port	`9090`	-	-
`persist_usage_report_interval_in_seconds`		-	`PERSIST_USAGE_REPORT_INTERVAL_IN_SECONDS`	Duration in seconds between two recording of usage metrics	`10`	`5`	-

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

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 sign command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`to_sign_payload_path`	`--to-sign-payload-path`	-	-	Path of the payload to sign.	-	-	-
`target_signed_payload_path`	`--target-signed-payload-path`	-	-	Path of the signed payload to export.	-	-	-
`genesis_secret_key_path`	`--genesis-secret-key-path`	-	-	Path of the genesis secret key.	-	-	-

genesis generate-keypair command:

Parameter	Command line (long)	Command line (short)	Environment variable	Description	Default value	Example	Mandatory
`target_path`	`--target-path`	-	-	Target path for the generated keypair	-	-	✔️

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 the chain.	-	-	✔️
`target_path`	`--target-path`	-	-	Path of the file to export the payload to.	-	-	-

The tools recompute-certificates-hash command has no dedicated parameters.

Resources​

Prerequisites​

Download the source file​

Development testing and building​

Release the build and run the binary 'serve' command​

Release the build and run the binary 'genesis' command​

Bootstrap sub-command (test-only)​

Export sub-command​

Sign sub-command​

Import sub-command​

Release the build and run the binary 'era' command​

Release the build and run the binary 'tools' command​

Download the pre-built binary​

Build and run the Docker container​

Subcommands​

Configuration parameters​

Resources

Prerequisites

Download the source file

Development testing and building

Release the build and run the binary 'serve' command

Release the build and run the binary 'genesis' command

Bootstrap sub-command (test-only)

Export sub-command

Sign sub-command

Import sub-command

Release the build and run the binary 'era' command

Release the build and run the binary 'tools' command

Download the pre-built binary

Build and run the Docker container

Subcommands

Configuration parameters