Skip to main content
Version: Current

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​

NodeSource repositoryRust documentationDocker packagesREST APINetwork 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:

SubcommandPerformed action
serveThe aggregator runs its HTTP server in nominal mode and orchestrates multi-signature production
helpPrints this message or the help of the given subcommand(s)
genesis exportExports genesis payload to sign with genesis secret key
genesis signSigns the genesis payload with the genesis secret key
genesis importImports the genesis signature (the payload signed with the genesis secret key) and creates and imports a genesis certificate in the store
genesis bootstrapBootstraps a genesis certificate (test only usage)
genesis generate-keypairGenerates a genesis keypair
era listLists the supported eras
era generate-tx-datumGenerates the era markers transaction datum to be stored on-chain
tools recompute-certificates-hashLoads 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:

  1. In a configuration file, depending on the --run-mode parameter. If the runtime mode is testnet, the file is located in ./conf/testnet.json.

  2. The value can be overridden by an environment variable with the parameter name in uppercase.

Here is a list of the available parameters:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
cardano_cli_path--CARDANO_CLI_PATHCardano CLI tool path-cardano-cliβœ”οΈ
cardano_node_socket_path--CARDANO_NODE_SOCKET_PATHPath 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_directoryDirectory to store aggregator data (certificates, snapshots, protocol parameters, ...)-./mithril-aggregator/storesβœ”οΈ
db_directory--db-directory-DB_DIRECTORYDirectory of the Cardano node stores/db-βœ”οΈ
genesis_verification_key--GENESIS_VERIFICATION_KEYGenesis verification key--βœ”οΈ
network--NETWORKCardano network-testnet or mainnet or devnetβœ”οΈ
network_magic--NETWORK_MAGICCardano network magic number (for testnet and devnet)-1097911063 or 42-
protocol_parameters--PROTOCOL_PARAMETERS__K, PROTOCOL_PARAMETERS__M, and PROTOCOL_PARAMETERS__PHI_FMithril protocol parameters-{ k: 5, m: 100, phi_f: 0.65 }βœ”οΈ
run_mode--run-mode-rRUN_MODERuntime modedev-βœ”οΈ
store_retention_limit--STORE_RETENTION_LIMITMaximum number of records in stores. If not set, no limit is set.---
verbose--verbose-vVERBOSEVerbosity level-Parsed from the number of occurrences: -v for Warning, -vv for Info, -vvv for Debug and -vvvv for Traceβœ”οΈ

serve command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
server_ip--server-ip-SERVER_IPListening server IP0.0.0.0-βœ”οΈ
server_port--server-port-SERVER_PORTListening server port8080-βœ”οΈ
snapshot_directory--snapshot-directory-SNAPSHOT_DIRECTORYDirectory to store local snapshots of the Cardano node.-βœ”οΈ
snapshot_store_type--SNAPSHOT_STORE_TYPEType of snapshot store to use-gcp or localβœ”οΈ
snapshot_uploader_type--SNAPSHOT_UPLOADER_TYPEType of snapshot uploader to use-gcp or localβœ”οΈ
snapshot_bucket_name--SNAPSHOT_BUCKET_NAMEName of the bucket where the snapshots are stored-snapshot-bucketRequired if snapshot_uploader_type is gcp
snapshot_use_cdn_domain--SNAPSHOT_USE_CDN_DOMAINUse CDN domain for constructing snapshot urlfalse-To be used if snapshot_uploader_type is gcp
run_interval--RUN_INTERVALInterval between two runtime cycles in ms-60000βœ”οΈ
chain_observer_type--chain-observer-type-CHAIN_OBSERVER_TYPEChain observer type that can be cardano-cli, pallas or fake.pallas--
era_reader_adapter_type--era-reader-adapter-type-ERA_READER_ADAPTER_TYPEEra reader adapter type that can be cardano-chain, file or bootstrap.bootstrap--
era_reader_adapter_params--era-reader-adapter-params-ERA_READER_ADAPTER_PARAMSEra 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_TYPESSigned entity types parameters (discriminants names in an ordered comma separated list)-MithrilStakeDistribution,CardanoImmutableFilesFull,CardanoStakeDistribution-
snapshot_compression_algorithm--snapshot-compression-algorithm-SNAPSHOT_COMPRESSION_ALGORITHMCompression algorithm of the snapshot archivezstandardgzip or zstandard-
zstandard_parameters--ZSTANDARD_PARAMETERS__LEVEL and ZSTANDARD_PARAMETERS__NUMBER_OF_WORKERSZstandard specific parameters-{ level: 9, number_of_workers: 4 }-
allow_unparsable_block--allow-unparsable-block-ALLOW_UNPARSABLE_BLOCKIf 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__STEPCardano 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_SIZECardano transactions prover cache pool size1010-
cardano_transactions_database_connection_pool_size--cardano-transactions-database-connection-pool-size-CARDANO_TRANSACTIONS_DATABASE_CONNECTION_POOL_SIZECardano transactions database connection pool size1010-
cardano_transactions_prover_max_hashes_allowed_by_request--cardano-transactions-prover-max-hashes-allowed-by-request-CARDANO_TRANSACTIONS_PROVER_MAX_HASHES_ALLOWED_BY_REQUESTMaximum number of transactions hashes allowed by request to the prover of the Cardano transactions100100-
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_POLLMaximum number of roll forwards during a poll of the block streamer when importing transactions10001000-
cardano_transactions_signing_config--cardano-transactions-signing-config-CARDANO_TRANSACTIONS_SIGNING_CONFIGCardano transactions signing configuration{ "security_parameter": 3000, "step": 120 }{ "security_parameter": 3000, "step": 120 }-
enable_metrics_server--enable-metrics-server-ENABLE_METRICS_SERVEREnable metrics HTTP server (Prometheus endpoint on /metrics)false--
metrics_server_ip--metrics-server-ip-METRICS_SERVER_IPMetrics HTTP server IP0.0.0.0--
metrics_server_port--metrics-server-port-METRICS_SERVER_PORTMetrics HTTP server listening port9090--
persist_usage_report_interval_in_seconds-PERSIST_USAGE_REPORT_INTERVAL_IN_SECONDSDuration in seconds between two recording of usage metrics105-

genesis bootstrap command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
genesis_secret_key--GENESIS_SECRET_KEYGenesis secret key, ⚠️ for test only---

genesis export command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
target_path--target-path--Path of the file to export the payload to.---

genesis import command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
signed_payload_path--signed-payload-path--Path of the payload to import.---

genesis sign command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
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:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
target_path--target-path--Target path for the generated keypair--βœ”οΈ

era list command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
json--json--Export the supported era list to JSON format.---

era generate-tx-datum command:

ParameterCommand line (long)Command line (short)Environment variableDescriptionDefault valueExampleMandatory
current_era_epoch--current-era-epoch-CURRENT_ERA_EPOCHEpoch at which current era starts.--βœ”οΈ
next_era_epoch--next-era-epoch-NEXT_ERA_EPOCHEpoch 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_KEYEra 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.