DMQ testing program with SPOs​

We are excited to announce the launch of a testing program for the Decentralized Message Queue (DMQ) feature with a group of stake pool operators (SPOs). This program will take place on the pre-release-preview network and aims to gather feedback, identify potential issues, and ensure the robustness of the DMQ implementation before its wider release.

What is DMQ?​

The DMQ protocol, specified in CIP-0137, is a major step forward for the Mithril network. It enables multiple aggregators to operate simultaneously on the same Mithril network, significantly improving decentralization and resilience. This enhancement reduces single points of failure and strengthens the overall robustness of the certificate production process.

Call for SPO participation​

We invite interested SPOs to join the testing program! The only requirement is to run a Mithril signer on the pre-release-preview network. If you want to participate, please reach out to us on the Mithril Discord channel.

Important note on adoption​

For the DMQ protocol to operate effectively, a minimum adoption of 60% of stake among SPOs is required. During the ramp-up phase, the legacy signature registration mechanism will remain active to ensure continuity and avoid any disruption. Once the vast majority of SPOs have adopted DMQ, the legacy mechanism will be deactivated.

Rollout plan​

The rollout plan of the DMQ network is the following:

• Distribution +1: unstable on the pre-release-preview network
  • DMQ activation on the pre-release-preview network
  • Release of a guide for setting up a DMQ node in the SPO infrastructure
  • 4-6 weeks testing program with selected SPOs
• Distribution +2: stable on the release-preprod and release-mainnet networks with fallback
  • DMQ activation on the release-preprod and release-mainnet networks
  • Activation of the fallback to the legacy signature registration mechanism for all SPOs
  • Release of an updated guide for setting up a DMQ node in the SPO infrastructure
  • Monitoring and support for SPOs running DMQ nodes
• Distribution +3: stable on the release-preprod and release-mainnet networks
  • Deactivation of the fallback to the legacy signature registration mechanism for all SPOs
  • Monitoring and support for SPOs running DMQ nodes.

For any inquiries or assistance, contact the team on the Discord channel.

Multiple aggregators testing program​

The Mithril team is launching a testing program for running multiple aggregators on the pre-release-preview network: running multiple aggregators will help increase decentralization and resilience of the Mithril network. This initiative will help collect valuable feedback, identify potential issues, and validate Mithril architecture before broader deployment.

Leader/follower architecture​

We have introduced a leader/follower architecture for aggregators. In this initial phase, only the signature diffusion is decentralized thanks to the DMQ protocol (CIP-0137). IOG will continue operating the leader aggregator, while anyone will be able to run a follower aggregator.

The leader aggregator serves as the seed for the certificate chain and the signer registration. When a follower aggregator joins the Mithril network, it fetches the existing certificate chain from the leader to bootstrap its operations and also relies on the leader aggregator to broadcast the signer registrations.

Public and private aggregators​

Aggregators can be either public or private:

• Public aggregators are accessible to anyone and contribute to the overall resilience of the network
• Private aggregators can be operated for internal use cases or specific communities.

A discovery mechanism is also being tested to allow new public aggregators to be easily found and accessible by clients across the network.

Call for participation​

We invite SPOs and everyone in the Cardano ecosystem to join this testing program! Whether you want to run a public aggregator to strengthen the network or a private one for your own needs, your participation will help validate and improve the follower aggregator.

If you want to participate, please reach out to the team on the Mithril Discord channel.

Important requirement​

A healthy DMQ network operated by at least 60% of the stake is mandatory for this feature to work. The DMQ protocol enables the decentralized diffusion of signatures, which must occur before any follower aggregator can proceed with the aggregation phase. During the ramp-up phase for the DMQ network, follower aggregators may not be able to produce valid certificates if the DMQ adoption is insufficient.

Rollout plan​

The rollout plan of the DMQ network is the following:

• Distribution +1: unstable on the pre-release-preview network
  • Activation of the feature on the pre-release-preview network
  • Release of a guide for setting up a follower aggregator
  • 4-6 weeks testing program with selected participants
• Distribution +2: stable on the release-preprod and release-mainnet networks
  • Activation of the feature on the release-preprod and release-mainnet networks
  • Release of an updated guide for setting up a follower aggregator
  • Monitoring and support for operators running follower aggregators.

For any inquiries or assistance, contact the team on the Discord channel.

Distribution 2543 is now available​

The 2543.1-hotfix distribution has been released, introducing the following changes:

• Added support for default incremental backend (v2) for Cardano database restoration in the client library, CLI and WASM
• Added support for enhanced verification of a Cardano database which provides a list of tampered and missing files in case of failure in the client library and CLI
• Added support for artifacts retrieval by epoch for the Cardano database and Cardano stake distribution in the client library, CLI and WASM
• Deprecated the with_aggregator_client and new functions in the ClientBuilder struct of the client library
• General bug fixes and performance improvements.

This new distribution has been deployed to the Mithril aggregator on the release-mainnet and release-preprod networks.

For those running a Mithril signer:

• pre-release-preview network: no action is required at this time
• release-preprod network: upgrade the signer node binary to version 0.2.276 – no configuration changes are required
• release-mainnet network: upgrade the signer node binary to version 0.2.276 – no configuration changes are required.

You can update the Mithril signer using the one-line command below. By default, it downloads to the current directory, but you can specify a custom folder with the -p option:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh | sh -s -- -c mithril-signer -d 2543.1-hotfix -p $(pwd)

For any inquiries or assistance, contact the team on the Discord channel.

Distribution 2537 is now available​

The 2537.0 distribution has been released, introducing the following changes:

• Added support for Cardano node v.10.5.1 in the signer and aggregator
• Added support for the stable cardano_database_v2 backend in the mithril-client library
• Added support for the stable v2 backend of the cardano-db command, with the decommissioning of the cardano-db-v2 command in the client CLI
• Added support for the stable verify command to validate an existing Cardano database in the client CLI
• Added support for the stable UTXO-HD snapshot converter via the tools utxo-hd snapshot-converter command in the client CLI
• Provided pre-built Linux ARM binaries for the signer, client CLI, and aggregator
• Migrated to the Rust 2024 edition (from the 2021 edition)
• General bug fixes and performance improvements.

This new distribution has been deployed to the Mithril aggregator on the release-mainnet and release-preprod networks.

For those running a Mithril signer:

• pre-release-preview network: no action is required at this time
• release-preprod network: upgrade the signer node binary to version 0.2.268 – no configuration changes are required
• release-mainnet network: upgrade the signer node binary to version 0.2.268– no configuration changes are required.

You can update the Mithril signer using the one-line command below. By default, it downloads to the current directory, but you can specify a custom folder with the -p option:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh | sh -s -- -c mithril-signer -d 2537.0 -p $(pwd)

For any inquiries or assistance, contact the team on the Discord channel.

Pre-built Linux ARM binaries are now available​

With the release of the 2537.0 distribution, pre-built Linux ARM binaries are now available for Mithril nodes:

• Download the binaries directly (files attached to the GitHub release with the suffix -linux-arm64.tar.gz)
• Download the Debian package (files attached to the GitHub release with the suffix -arm64.deb)
• Use the one-liner installer to install them.

To provide a clear overview of supported platforms, the team has added a new 'Platform support' section in the release notes, reproduced below for convenience (note that it may change in the future).

⁽*⁾⚠️ Linux arm64 builds are provided on a best-effort basis and are not officially supported.

For any inquiries or assistance, contact the team on the Discord channel.

Switching to Cardano database incremental certification​

A new incremental certification process has been introduced for the Cardano node internal database. This enhancement is part of ongoing efforts to improve the Mithril protocol and optimize Cardano node bootstrapping.

More information about the Cardano database certification is available at:

• Cardano node database
• Cardano node database v2.

The Cardano node database v2 certification offers incremental verification and greater efficiency compared to the original method. It will progressively replace the current certification process for the Cardano node internal database.

To facilitate this transition, updates have been made to both the Mithril client CLI and the Mithril client library. These changes are designed to support the new incremental certification process and ensure a smooth user experience.

In particular, the cardano-db command in the Mithril client CLI has been updated to support the new incremental certification process and eventually a seamless switch to the new backend. A new --backend option has been added to the command, allowing users to specify the certification version:

• --backend v1 uses the original Cardano node database certification (this remains the default)
• --backend v2 enables the new incremental Cardano node database certification.

To support this transition, both certification versions will remain available during the migration period, allowing users to adapt at their own pace.

• Distribution 2524:

  • Introduced the --backend parameter in the cardano-db command
  • The default backend is v1; the v2 backend is still considered unstable
  • No breaking changes in the client CLI
  • The v2 backend is accessible via the cardano_database_v2 function in the client library.

• Distribution 2537:

  • The v2 backend is promoted to stable status but will remain optional
  • The v1 backend is still the default.

• Distribution 2543:

  • The v2 backend is the default

• Distribution +3:

  • The v1 backend will be deprecated.

• Distribution +4:

  • The v1 backend will be decommissioned and removed from the client CLI and library.

• Distribution +5:

  • The v1 backend will be fully removed from the signer and aggregator.

If you have any questions or need assistance, contact the team on the Discord channel.

Update 2025/09/17: The command has been promoted to stable and is now available without the --unstable flag.

Introducing the UTXO-HD ledger state snapshot converter command in the Mithril client CLI​

With the release of the new 2524 distribution, the tools command has been added to the Mithril client CLI.

Since the release of Cardano node v.10.4.1, the Mithril aggregator node has been producing snapshots of the Cardano database using the InMemory UTXO-HD flavor.

When restoring a Cardano database snapshot, if the Cardano node is configured to use the on-disk (LMDB) or Legacy format (as in Cardano node v.10.3 and earlier), the ledger state snapshot must be converted before restarting the node.

The new utxo-hd snapshot-converter subcommand simplifies node bootstrapping by converting the restored ledger state snapshot into the required format (LMDB or Legacy).

This conversion tool is currently marked as unstable and is available on Linux, macOS, and Windows.

It operates using the snapshot-converter binary included with the Cardano node distribution.

Usage:

mithril-client tools utxo-hd snapshot-converter --db-directory $DB_DIRECTORY --cardano-node-version 10.1.4 --utxo-hd-flavor $UTXO_HD_FLAVOR

Parameters:

• --db-directory: path to the Cardano database directory
• --cardano-node-version: version used to download the snapshot-converter binary (specific version, eg, 10.1.4, latest, or prerelease)
• --utxo-hd-flavor: target UTXO-HD flavor (LMDB or Legacy)

The 'Bootstrap a Cardano node' guide now includes a new optional step that describes how to use the command.

The documentation for the client CLI has been updated accordingly and is available here.

For any inquiries or assistance, contact the team on the Discord channel.

Distribution 2524 is now available​

The 2524.0 distribution has been released, introducing the following changes:

• Support for Cardano node v.10.4.1 in the signer and aggregator
• Support for recording client origin types (library, CLI, WASM) in aggregator metrics
• Unstable support for UTXO-HD snapshot converter tools utxo-hd snapshot-converter command in the client CLI
• Unstable support for partial Cardano database restoration using the cardano-database command with the --backend v2 parameter
• Bug fixes and performance improvements.

This new distribution has been deployed to the Mithril aggregator on the release-mainnet and release-preprod networks.

If running a Mithril signer:

• pre-release-preview network: no action required at this time
• release-preprod network: upgrade the signer node binary to version 0.2.249 – no configuration changes required
• release-mainnet network: upgrade the signer node binary to version 0.2.249– no configuration changes required.

You can update the Mithril signer using the one-line command below. It downloads to the current directory by default, but you can specify a custom folder using the -p option:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh | sh -s -- -c mithril-signer -d 2524.0 -p $(pwd)

For any inquiries or assistance, contact the team on the Discord channel.

Mithril snapshots for Cardano database could be compromised by an adversary​

The Mithril team has published a security advisory for users running the Mithril client on the mainnet infrastructure:

• Identifier: GHSA-qv97-5qr8-2266
• Title: Mithril snapshots for Cardano database could be compromised by an adversary
• Location: GHSA-qv97-5qr8-2266
• Severity: Moderate (4.9/10).

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh | sh -s -- -c mithril-client -d 2517.1 -p $(pwd)

For any inquiries or assistance, contact the team on the Discord channel.

Breaking changes in client library and CLI​

The 2517 release introduces breaking changes to the Mithril client CLI and library.

Client CLI​

The command for downloading a certified Cardano database using the Mithril client CLI has been updated starting from version 0.12.1:

• The existing command remains functional but no longer downloads ancillary files (ledger state snapshot and last immutable file) by default. As a result, the fast bootstrap feature is disabled, requiring the Cardano node to compute the ledger state from the genesis block during startup:

mithril-client cardano-database download latest

• To include ancillary files and enable fast bootstrap, use the new command with the --include-ancillary option:

mithril-client cardano-database download latest --include-ancillary --ancillary-verification-key <ANCILLARY_VERIFICATION_KEY>

To update the Mithril client CLI, use the following one-line command. By default, it downloads to the current directory. To specify a custom folder, use the -p option:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh | sh -s -- -c mithril-client -d 2517.1 -p $(pwd)

For more details, refer to the Mithril client node documentation.

Client Library​

The Mithril client library has also been updated. By default, it no longer downloads ancillary files (ledger state snapshot and last immutable file), which disables the fast bootstrap feature. Consequently, the Cardano node must compute the ledger state from the genesis block during startup.

To enable fast bootstrap, use the download_unpack_full function instead of download_unpack and provide the set_ancillary_verification_key parameter:

• Set the ancillary verification key using the set_ancillary_verification_key method when building the client:

let client = ClientBuilder::aggregator(AGGREGATOR_ENDPOINT, GENESIS_VERIFICATION_KEY)
    .set_ancillary_verification_key(ANCILLARY_VERIFICATION_KEY.to_string()) // Added line
    .with_origin_tag(Some("EXAMPLE".to_string()))
    .build()?;

• Use the download_unpack_full function to download ancillary files:

client
    .cardano_database()
    .download_unpack_full(&snapshot, target_directory)
    .await?;

For more information and a complete example, refer to the Mithril client library documentation.

If you have any questions or need assistance, contact the team on the Discord channel.