11 posts tagged with "mithril client"

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.

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.

Mithril certificate chain could be manipulated by an adversarial signer (security advisory)​

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

• Identifier: GHSA-724h-fpm5-4qvr
• Title: Mithril certificate chain could be manipulated by an adversarial signer
• Location: GHSA-724h-fpm5-4qvr
• Severity: High (5.3/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 2506.0 -p $(pwd)

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

Breaking change introduced in the unstable features of the Mithril client WASM​

With the release of distribution 2437, we introduced a breaking change to the Mithril client WASM version 0.4.1. Unstable features are now activated using a configuration option instead of the .unstable property.

This change ensures a seamless transition when new unstable features become stable, eliminating breaking changes in developer code and enhancing the developer experience.

To activate unstable features, use the following code:

let client = new MithrilClient(aggregator_endpoint, genesis_verification_key, {
  // The following option activates the unstable features of the client.
  // Unstable features will trigger an error if this option is not set.
  unstable: true,
});

The previous client.unstable implementation is not supported anymore and must be replaced with client:

// Before
let mithril_stake_distributions_message =
  await client.unstable.compute_mithril_stake_distribution_message(
    last_stake_distribution,
  );

// After
let mithril_stake_distributions_message =
  await client.compute_mithril_stake_distribution_message(
    last_stake_distribution,
  );

The Mithril client WASM documentation is available here.

For questions or assistance, contact the team on the Discord channel.

The 'snapshot' command of the client CLI is removed​

With the release of the new distribution 2423, we have removed the snapshot command of the client CLI.

The snapshot command has been superseded by the cardano-db snapshot command.

The snapshot command has been deprecated with the release 2412, and this has been announced in this post.

In order to proceed to the upgrade, install the latest stable client CLI, and replace the removed command with the new command, e.g.:

mithril-client -vvv snapshot download latest --json

Should be replaced with

mithril-client -vvv cardano-db snapshot download latest --json

The documentation of the client CLI has been updated accordingly and can be found here.

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

The 'snapshot' command of the client CLI is deprecated​

With the release of the new distribution 2412, we have deprecated the snapshot command of the client CLI.

The snapshot command has been superseded by the cardano-db snapshot command. In order to give time to our users to use the new command, the now legacy snapshot command is still available, but it will be removed in a near future.

In order to proceed to the upgrade, install the latest stable client CLI, and replace the legacy command with the new command, e.g.:

mithril-client -vvv snapshot download latest --json

Should be replaced with

mithril-client -vvv cardano-db snapshot download latest --json

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

Breaking change introduced in the output of Mithril client CLI​

With the release of the new distribution 2408, we have introduced a breaking change to the Mithril client CLI version 0.7.0: all logs are now written to stderr instead of stdout. This allows for cleaner command results that you can directly pipe into tools like jq.

Below, the stdout output of mithril-client -vvv snapshot download latest --json command before the update:

{"timestamp": "2024-02-27T10:41:55.576645+00:00", "step_num": 1, "total_steps": 5, "message": "Checking local disk info…"}
{"timestamp": "2024-02-27T10:41:55.576932+00:00", "step_num": 2, "total_steps": 5, "message": "Fetching the certificate and verifying the certificate chain…"}
{"timestamp": "2024-02-27T10:41:55.847199+00:00", "step_num": 3, "total_steps": 5, "message": "Downloading and unpacking the snapshot…"}
{"timestamp": "2024-02-27T10:41:56.023585+00:00", "bytes_downloaded": 390, "bytes_total": 345223208, "seconds_left": 75797.765, "seconds_elapsed": 0.085}
{"timestamp": "2024-02-27T10:41:56.356820+00:00", "bytes_downloaded": 9487846, "bytes_total": 345223208, "seconds_left": 32.674, "seconds_elapsed": 0.418}
{"timestamp": "2024-02-27T10:41:56.690001+00:00", "bytes_downloaded": 21682030, "bytes_total": 345223208, "seconds_left": 18.209, "seconds_elapsed": 0.752}
{"timestamp": "2024-02-27T10:41:57.023923+00:00", "bytes_downloaded": 33795639, "bytes_total": 345223208, "seconds_left": 14.218, "seconds_elapsed": 1.085}
{"timestamp": "2024-02-27T10:41:57.356999+00:00", "bytes_downloaded": 45934938, "bytes_total": 345223208, "seconds_left": 12.204, "seconds_elapsed": 1.419}
{"timestamp": "2024-02-27T10:41:57.690031+00:00", "bytes_downloaded": 58130472, "bytes_total": 345223208, "seconds_left": 10.894, "seconds_elapsed": 1.752}
{"timestamp": "2024-02-27T10:41:58.023964+00:00", "bytes_downloaded": 70235494, "bytes_total": 345223208, "seconds_left": 9.922, "seconds_elapsed": 2.086}
{"timestamp": "2024-02-27T10:41:58.357817+00:00", "bytes_downloaded": 82456663, "bytes_total": 345223208, "seconds_left": 9.134, "seconds_elapsed": 2.419}
{"timestamp": "2024-02-27T10:41:58.690945+00:00", "bytes_downloaded": 94618128, "bytes_total": 345223208, "seconds_left": 8.463, "seconds_elapsed": 2.753}
{"timestamp": "2024-02-27T10:41:59.024599+00:00", "bytes_downloaded": 106765259, "bytes_total": 345223208, "seconds_left": 7.868, "seconds_elapsed": 3.086}
{"timestamp": "2024-02-27T10:41:59.358139+00:00", "bytes_downloaded": 118941687, "bytes_total": 345223208, "seconds_left": 7.325, "seconds_elapsed": 3.420}
{"timestamp": "2024-02-27T10:41:59.691176+00:00", "bytes_downloaded": 131052374, "bytes_total": 345223208, "seconds_left": 6.824, "seconds_elapsed": 3.753}
{"timestamp": "2024-02-27T10:42:00.025189+00:00", "bytes_downloaded": 143190076, "bytes_total": 345223208, "seconds_left": 6.351, "seconds_elapsed": 4.087}
{"timestamp": "2024-02-27T10:42:00.358735+00:00", "bytes_downloaded": 155448192, "bytes_total": 345223208, "seconds_left": 5.896, "seconds_elapsed": 4.420}
{"timestamp": "2024-02-27T10:42:00.693529+00:00", "bytes_downloaded": 167494850, "bytes_total": 345223208, "seconds_left": 5.466, "seconds_elapsed": 4.755}
{"timestamp": "2024-02-27T10:42:01.026885+00:00", "bytes_downloaded": 179789000, "bytes_total": 345223208, "seconds_left": 5.043, "seconds_elapsed": 5.088}
{"timestamp": "2024-02-27T10:42:01.360483+00:00", "bytes_downloaded": 187536751, "bytes_total": 345223208, "seconds_left": 4.778, "seconds_elapsed": 5.422}
{"timestamp": "2024-02-27T10:42:01.693978+00:00", "bytes_downloaded": 199737576, "bytes_total": 345223208, "seconds_left": 4.389, "seconds_elapsed": 5.756}
{"timestamp": "2024-02-27T10:42:02.027113+00:00", "bytes_downloaded": 211879712, "bytes_total": 345223208, "seconds_left": 4.006, "seconds_elapsed": 6.089}
{"timestamp": "2024-02-27T10:42:02.360139+00:00", "bytes_downloaded": 224033698, "bytes_total": 345223208, "seconds_left": 3.626, "seconds_elapsed": 6.422}
{"timestamp": "2024-02-27T10:42:02.694407+00:00", "bytes_downloaded": 236212871, "bytes_total": 345223208, "seconds_left": 3.249, "seconds_elapsed": 6.756}
{"timestamp": "2024-02-27T10:42:03.027431+00:00", "bytes_downloaded": 248301091, "bytes_total": 345223208, "seconds_left": 2.878, "seconds_elapsed": 7.089}
{"timestamp": "2024-02-27T10:42:03.361001+00:00", "bytes_downloaded": 260428703, "bytes_total": 345223208, "seconds_left": 2.509, "seconds_elapsed": 7.423}
{"timestamp": "2024-02-27T10:42:03.694430+00:00", "bytes_downloaded": 272673595, "bytes_total": 345223208, "seconds_left": 2.139, "seconds_elapsed": 7.756}
{"timestamp": "2024-02-27T10:42:04.028557+00:00", "bytes_downloaded": 284878102, "bytes_total": 345223208, "seconds_left": 1.774, "seconds_elapsed": 8.090}
{"timestamp": "2024-02-27T10:42:04.361686+00:00", "bytes_downloaded": 296835374, "bytes_total": 345223208, "seconds_left": 1.418, "seconds_elapsed": 8.423}
{"timestamp": "2024-02-27T10:42:04.695532+00:00", "bytes_downloaded": 309005759, "bytes_total": 345223208, "seconds_left": 1.058, "seconds_elapsed": 8.757}
{"timestamp": "2024-02-27T10:42:05.028705+00:00", "bytes_downloaded": 321118015, "bytes_total": 345223208, "seconds_left": 0.702, "seconds_elapsed": 9.090}
{"timestamp": "2024-02-27T10:42:05.361956+00:00", "bytes_downloaded": 333264477, "bytes_total": 345223208, "seconds_left": 0.347, "seconds_elapsed": 9.424}
{"timestamp": "2024-02-27T10:42:05.711065+00:00", "step_num": 4, "total_steps": 5, "message": "Computing the snapshot message"}
{"timestamp": "2024-02-27T10:42:12.540752+00:00", "step_num": 5, "total_steps": 5, "message": "Verifying the snapshot signature…"}
{"timestamp": "2024-02-27T10:42:12.540913+00:00", "db_directory": "/mithril-client-0.5.17/db"}

Now the stdout output with Mithril client CLI version 0.7.0:

{"timestamp": "2024-02-27T10:43:06.357962+00:00", "db_directory": "/mithril-client-0.7.0/db"}

In addition, the --log-format-json option that enable JSON output is now written to stderr as well.

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

Mithril client npm is open to developers on npmjs.com​

The Mithril team has published the first release (v0.1.7) of its mithril-client-wasm npm package on npmjs.com.

The Mithril client npm package allows developers to use all the tooling necessary to manipulate Mithril certified types from a Mithril Aggregator directly in their (web) applications and to develop their own Mithril clients in any supported browser!

Here are some useful documentation that can be used by developers:

• Example of implementations: https://mithril.network/doc/manual/developer-docs/nodes/mithril-client-library-wasm
• Mithril client npm package repository: https://github.com/input-output-hk/mithril/tree/main/mithril-client-wasm
• npm: https://www.npmjs.com/package/@mithril-dev/mithril-client-wasm

Feel free to reach out to us on the Discord channel for questions and/or help.