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.

Mithril networks

Here is an updated list of all Mithril networks, including their configurations and current statuses:

Last update: 07/21/2023

release-mainnet​

Information-
Mithril networkrelease-mainnet
Cardano networkmainnet
Cardano magic Id-
SupportedYes ✔️
StatusBeta 🟢
Aggregator endpointhttps://aggregator.release-mainnet.api.mithril.network/aggregator ↗️
Genesis verification keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/genesis.vkey ↗️
Era reader adapter typecardano-chain
Era reader addresshttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/era.addr ↗️
Era reader verification keyhttps://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-mainnet/era.vkey ↗️
Build fromLatest release ↗️
caution

In this documentation, we use the following generic identifiers:

  • YOUR_CARDANO_NETWORK You need to replace this with the name of the network that runs on your Cardano node (eg, preprod)
  • YOUR_AGGREGATOR_ENDPOINT You need to replace this with the endpoint of an aggregator that runs on the Cardano network you are targeting (eg, https://aggregator.release-preprod.api.mithril.network/aggregator)
  • YOUR_GENESIS_VERIFICATION_KEY You need to replace this with the genesis verification key URL that runs on the Cardano network you are targeting (eg, https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey)
  • YOUR_ERA_READER_ADAPTER_TYPE You need to replace this with the era reader adapter type used by the Mithril network you are targeting (eg, cardano-chain)
  • YOUR_ERA_READER_ADDRESS You need to replace this with the era reader address URL used by the Mithril network you are targeting (eg, https://raw.githubusercontent.com/input-output-hk/mithril/main/address.addr)
  • YOUR_ERA_READER_VERIFICATION_KEY You need to replace this with the era reader verification key URL used by the Mithril network you are targeting (eg, https://raw.githubusercontent.com/input-output-hk/mithril/main/TEST_ONLY_era.vkey)

Resources​

NodeSource repositoryRust documentationDocker packagesREST API
Mithril aggregator↗️↗️↗️↗️

Pre-requisites​

  • Install the latest stable version of the correctly configured Rust toolchain.

  • 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 **Build from** column of the **Mithril networks** table above
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 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 capable of producing 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​

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

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.

¹ 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)
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-bucket✔️
snapshot_use_cdn_domain--SNAPSHOT_USE_CDN_DOMAINUse CDN domain for constructing snapshot urlfalse--
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 }-

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

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.