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 +1:

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

• Distribution +2:

  • The v2 backend will become the default
  • The v1 backend will be deprecated.

• Distribution +3:

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

• Distribution +4:

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

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 --unstable tools utxo-hd snapshot-converter --db-directory $DB_DIRECTORY --cardano-node-version 10.1.4 --utxo-hd-flavor $UTXO_HD_FLAVOR --cardano-network $CARDANO_NETWORK

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)
• --cardano-network: Cardano network (preview, preprod or mainnet).

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.

Distribution 2517 is now available​

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

• ⚠️ Breaking changes in Mithril client CLI and library:
  • To fast bootstrap a Cardano node, the new --include-ancillary option has been added to the Cardano node database command in the Mithril client CLI.
  • Without this option, only final immutable files are downloaded, and the ledger state must be computed from the genesis block when the Cardano node starts.
  • The --include-ancillary option requires the usage of an ancillary verification key (--ancillary-verification-key or ANCILLARY_VERIFICATION_KEY) which is specified in the Networks configuration page.
  • Clients from distribution [2513] and earlier are not compatible with this change and must be updated.
• Support for Cardano node 10.3.1 in the signer and the aggregator
• Support for origin tags in Mithril client library, CLI and WASM to record the origin of client requests.
• Bug fixes and performance improvements.

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

If you are running a Mithril signer:

• pre-release-preview network: no action is required at this time
• release-preprod network: upgrade your signer node binary to version 0.2.243 – no configuration updates are required
• release-mainnet network: upgrade your signer node binary to version 0.2.243– no configuration updates are 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 2517.1 -p $(pwd)

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

Certification of Cardano node database v2​

With the release of the new distribution 2513, we have started to roll out the certification of the Cardano node database v2 in the Mithril networks.

Initially, Mithril certified entire database snapshots, requiring clients to download and verify the full database to bootstrap a Cardano node. The Mithril network now provides incremental certification of the Cardano node database, allowing clients to download only the specific range of immutable files needed, accelerating the process of bootstrapping a Cardano node. The key features include:

• Certification of the Cardano node database v2 every time a new immutable file is produced
• New HTTP routes in the aggregator REST API to access this certified data
• Updates to the Mithril client library and CLI for retrieving and verifying Cardano node database v2 (will be made stable one distribution after the activation in release-mainet)
• Mithril Explorer now displays certified Cardano node database v2.

The roll-out plan of the feature is the following:

• Distribution 2513:
  • Activation of the certification of Cardano node database v2 in the pre-release-preview network
  • Activation of the certification of Cardano node database v2 in the release-preprod network
• Distribution 2517:
  • Activation of the certification of Cardano node database v2 in the release-mainnet network.

For any inquiries or assistance, don't hesitate to contact the team on the Discord channel.

Distribution 2513 is now available​

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

• ⚠️ Breaking changes in Mithril nodes:
  • The minimum required glibc version for pre-built Linux binaries has been upgraded from 2.31 to 2.35
  • Mithril signers running versions <=0.2.200 must be updated due to the removal of Thales era legacy code
  • The with_snapshot_uploader function in the Mithril client library has been renamed to with_file_uploader
• Added support for Cardano node 10.2.1 in the signer and aggregator
• Ended support for macOS x64 pre-built binaries for the client CLI
• Bug fixes and performance improvements.

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

If you are running a Mithril signer:

• pre-release-preview network: no action is required at this time
• release-preprod network: upgrade your signer node binary to version 0.2.237 – no configuration updates are required
• release-mainnet network: upgrade your signer node binary to version 0.2.237– no configuration updates are 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 2513.0 -p $(pwd)

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

Ending support for macOS x64 pre-built binaries​

Since 2020, macOS has transitioned from Intel (x64 architecture) to Apple Silicon (arm64 architecture) processors.

Additionally, Cardano node version 10+ now supports only Apple Silicon on macOSX.

As a result, the Mithril team will end support for macOS x64 pre-built binaries for the client CLI starting March 2025.

From this date, CI will no longer build these binaries for GitHub releases. If you are still using macOS x64, you will need to build the binaries from source.

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

Announcing the decommissioning of the testing‑sanchonet network​

The testing-sanchonet Mithril network was introduced a year ago to allow the community to test experimental features and provide feedback to the Mithril team. In particular, it has been a valuable tool for testing the transition to the Conway era.

The Mithril team sincerely appreciates the Mithril pioneer stake pool operators for participating in testing and providing valuable feedback!

The Cardano SanchoNet network is now being sunset, having served its purpose of introducing governance features from CIP-1694 in a controlled testnet environment.

In this context, the Mithril team has decided to decommission the testing-sanchonet network:

• the aggregator will be terminated by February 21, 2025
• the network will be removed from the Mithril explorer
• the repository code will be cleaned up.

If you are running a Mithril signer on this network, you can safely terminate your node and remove the testing-sanchonet configuration from your setup.

Available Mithril networks are listed on the Network configurations page of the documentation website.

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