Merge pull request #1542 from input-output-hk/ensemble/1535/stabilize…

…-namings-cardano-transactions

Stabilize namings cardano transactions:
- "cardano transactions commitment" are now "cardano transactions snapshot"
- In client CLI `snapshot` subcommand is superseeded by a `cardano-db` subcommand (the old command is still available for backward compatibility but a warning is print to stderr).

.github/workflows/test-client.yml

@@ -87,7 +87,7 @@ jobs:
           aria2c -o aggregator_capabilities.json $AGGREGATOR_ENDPOINT
           CTX_CAPABILITY=$(jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])' aggregator_capabilities.json)
           echo "ctx_enabled=$CTX_CAPABILITY" >> $GITHUB_OUTPUT
-          
+
       - name: Checkout binary
         uses: dawidd6/action-download-artifact@v3
         with:
@@ -108,17 +108,25 @@ jobs:
         working-directory: ./bin
         run: ./mithril-client ${{ steps.prepare.outputs.debug_level }} --version
 
-      - name: Snapshot / list and get last digest
+      - name: Cardano-db / list and get last digest
         shell: bash
         working-directory: ./bin
         run: |
-          ./mithril-client ${{ steps.prepare.outputs.debug_level }} snapshot list
-          echo "SNAPSHOT_DIGEST=$(./mithril-client snapshot list --json | jq -r '.[0].digest')" >> $GITHUB_ENV
+          ./mithril-client ${{ steps.prepare.outputs.debug_level }} cardano-db snapshot list
+          echo "CDB_SNAPSHOT_DIGEST=$(./mithril-client cardano-db snapshot list --json | jq -r '.[0].digest')" >> $GITHUB_ENV
+
+      - name: Cardano-db / download & restore latest
+        shell: bash
+        working-directory: ./bin
+        run: ./mithril-client ${{ steps.prepare.outputs.debug_level }} cardano-db download $CDB_SNAPSHOT_DIGEST
 
-      - name: Snapshot / download & restore latest
+      - name: Cardano-db / check old 'snapshot' commands availability
         shell: bash
         working-directory: ./bin
-        run: ./mithril-client ${{ steps.prepare.outputs.debug_level }} snapshot download $SNAPSHOT_DIGEST
+        run: |
+          ./mithril-client ${{ steps.prepare.outputs.debug_level }} snapshot list --help
+          ./mithril-client ${{ steps.prepare.outputs.debug_level }} snapshot show --help
+          ./mithril-client ${{ steps.prepare.outputs.debug_level }} snapshot download --help
 
       - name: Mithril Stake Distribution / list and get last hash
         shell: bash
@@ -132,19 +140,19 @@ jobs:
         working-directory: ./bin
         run: ./mithril-client ${{ steps.prepare.outputs.debug_level }} mithril-stake-distribution download $MITHRIL_STAKE_DISTRIBUTION_HASH
 
-      - name: Cardano transaction / list and get last commitment
+      - name: Cardano transaction / list and get last snapshot
         if: steps.aggregator_capability_unix.outputs.ctx_enabled == 'true' || steps.aggregator_capability_windows.outputs.ctx_enabled == 'true'
         shell: bash
         working-directory: ./bin
         run: |
-          ./mithril-client ${{ steps.prepare.outputs.debug_level }} --unstable cardano-transaction commitment list
-          echo "CTX_COMMITMENT_HASH=$(./mithril-client --unstable cardano-transaction commitment list --json | jq -r '.[0].hash')" >> $GITHUB_ENV
+          ./mithril-client ${{ steps.prepare.outputs.debug_level }} --unstable cardano-transaction snapshot list
+          echo "CTX_SNAPSHOT_HASH=$(./mithril-client --unstable cardano-transaction snapshot list --json | jq -r '.[0].hash')" >> $GITHUB_ENV
 
-      - name: Cardano transaction / show commitment
+      - name: Cardano transaction / show snapshot
         if: steps.aggregator_capability_unix.outputs.ctx_enabled == 'true' || steps.aggregator_capability_windows.outputs.ctx_enabled == 'true'
         shell: bash
         working-directory: ./bin
-        run: ./mithril-client --unstable cardano-transaction commitment show $CTX_COMMITMENT_HASH
+        run: ./mithril-client --unstable cardano-transaction snapshot show $CTX_SNAPSHOT_HASH
 
       - name: Cardano transaction certify
         if: steps.aggregator_capability_unix.outputs.ctx_enabled == 'true' || steps.aggregator_capability_windows.outputs.ctx_enabled == 'true'
@@ -190,15 +198,22 @@ jobs:
         shell: bash
         run: ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} --version
 
-      - name: Snapshot / list and get last digest
+      - name: Cardano-db / list and get last digest
         shell: bash
         run: |
-          ${{ steps.command.outputs.mithril_client }} snapshot list
-          echo "SNAPSHOT_DIGEST=$(${{ steps.command.outputs.mithril_client }} snapshot list --json | jq -r '.[0].digest')" >> $GITHUB_ENV
+          ${{ steps.command.outputs.mithril_client }} cardano-db snapshot list
+          echo "CDB_SNAPSHOT_DIGEST=$(${{ steps.command.outputs.mithril_client }} cardano-db snapshot list --json | jq -r '.[0].digest')" >> $GITHUB_ENV
 
-      - name: Snapshot / download & restore latest
+      - name: Cardano-db / download & restore latest
         shell: bash
-        run: ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} snapshot download $SNAPSHOT_DIGEST --download-dir /app
+        run: ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} cardano-db download $CDB_SNAPSHOT_DIGEST --download-dir /app
+
+      - name: Cardano-db / check old 'snapshot' commands availability
+        shell: bash
+        run: |
+          ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} snapshot list --help
+          ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} snapshot show --help
+          ${{ steps.command.outputs.mithril_client }} ${{ steps.prepare.outputs.debug_level }} snapshot download --help
 
       - name: Mithril Stake Distribution / list and get last hash
         shell: bash
@@ -210,18 +225,18 @@ jobs:
         shell: bash
         run: ${{ steps.command.outputs.mithril_client }}  ${{ steps.prepare.outputs.debug_level }} mithril-stake-distribution download $MITHRIL_STAKE_DISTRIBUTION_HASH --download-dir /app
 
-      - name: Cardano transaction / list and get last commitment
+      - name: Cardano transaction / list and get last snapshot
         if: steps.aggregator_capability.outputs.ctx_enabled == 'true'
         shell: bash
         run: |
-          ${{ steps.command.outputs.mithril_client }} --unstable cardano-transaction commitment list
-          echo "CTX_COMMITMENT_HASH=$(${{ steps.command.outputs.mithril_client }} --unstable cardano-transaction commitment list --json | jq -r '.[0].hash')" >> $GITHUB_ENV
+          ${{ steps.command.outputs.mithril_client }} --unstable cardano-transaction snapshot list
+          echo "CTX_SNAPSHOT_HASH=$(${{ steps.command.outputs.mithril_client }} --unstable cardano-transaction snapshot list --json | jq -r '.[0].hash')" >> $GITHUB_ENV
 
-      - name: Cardano transaction / show commitment
+      - name: Cardano transaction / show snapshot
         if: steps.aggregator_capability.outputs.ctx_enabled == 'true'
         shell: bash
-        run: ${{ steps.command.outputs.mithril_client }} --unstable cardano-transaction commitment show $CTX_COMMITMENT_HASH
-    
+        run: ${{ steps.command.outputs.mithril_client }} --unstable cardano-transaction snapshot show $CTX_SNAPSHOT_HASH
+
       - name: Cardano transaction certify
         if: steps.aggregator_capability.outputs.ctx_enabled == 'true'
         shell: bash

docs/website/root/glossary.md

@@ -28,7 +28,7 @@ A Cardano key pair is an asymmetric key pair used to identify a [stake pool oper
 
 A Cardano transaction proof is a cryptographic proof that a sub-set of Cardano transactions is included in the Cardano transactions set. It is generated upon request from a [Mithril client](#mithril-client) and is signed by a [certificate](#certificate).
 
-A Cardano transactions set commitment represents, in a succinct way, the Cardano transactions set that was signed by Mithril at a given [Beacon](#beacon).
+A Cardano transactions set snapshot represents, in a succinct way, the Cardano transactions set that was signed by Mithril at a given [Beacon](#beacon).
 
 ## Certificate
 

docs/website/root/manual/developer-docs/nodes/mithril-client-library-wasm.md

@@ -14,7 +14,7 @@ Mithril client library WASM can be used by Javascript developers to use the Mith
 It is responsible for handling the different types of data certified by Mithril, and available through a Mithril aggregator:
 - [**Snapshot**](../../../glossary.md#snapshot): list and get.
 - [**Mithril stake distribution**](../../../glossary.md#stake-distribution): list and get.
-- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get commitments, get proofs
+- [**Cardano transaction**](../../../glossary.md#cardano-transaction): list & get snapshots, get proofs
 - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
 
 :::

docs/website/root/manual/developer-docs/nodes/mithril-client.md

@@ -126,7 +126,8 @@ This program shows, downloads and verifies certified blockchain artifacts.
 Usage: mithril-client [OPTIONS] <COMMAND>
 
 Commands:
-  snapshot                    Snapshot management
+  snapshot                    Deprecated, use `cardano-db` instead
+  cardano-db                  Cardano db management (alias: cdb)
   mithril-stake-distribution  Mithril Stake Distribution management (alias: msd)
   cardano-transaction         [unstable] Cardano transactions management (alias: ctx)
   help                        Print this message or the help of the given subcommand(s)
@@ -150,7 +151,6 @@ Options:
           Print help
   -V, --version
           Print version
-
 ```
 
 Run in release mode with the default configuration:
@@ -237,26 +237,26 @@ Now you can use the `mithril_client` functions:
 # 1- Help
 mithril_client help
 
-# 2- List snapshots
-mithril_client snapshot list
+# 2- List cardano db snapshots
+mithril_client cardano-db snapshot list
 
-# 3- Show detailed information about a snapshot
-mithril_client snapshot show $SNAPSHOT_DIGEST
+# 3- Show detailed information about a cardano db snapshot
+mithril_client cardano-db snapshot show $CARDANO_DB_DIGEST
 
-# 4- Download the given snapshot and verify the certificate
-mithril_client snapshot download $SNAPSHOT_DIGEST
+# 4- Download the given cardano db and verify the certificate
+mithril_client cardano-db download $CARDANO_DB_DIGEST
 
 # 5- List Mithril stake distributions
 mithril_client mithril-stake-distribution list
 
 # 6- Download and verify the given Mithril stake distribution
 mithril_client mithril-stake-distribution download $MITHRIL_STAKE_DISTRIBUTION_ARTIFACT_HASH
 
-# 7- List Cardano transaction commitments
-mithril_client --unstable cardano-transaction commitment list
+# 7- List Cardano transaction snapshots
+mithril_client --unstable cardano-transaction snapshot list
 
-# 8- Show detailed information about a Cardano transaction commitment
-mithril_client --unstable cardano-transaction commitment show $CARDANO_TRANSACTION_COMMITMENT_HASH
+# 8- Show detailed information about a Cardano transaction snapshot
+mithril_client --unstable cardano-transaction snapshot show $CARDANO_TRANSACTION_SNAPSHOT_HASH
 
 # 9- Certify that given list of transactions hashes are included in the Cardano transactions set
 mithril_client --unstable cardano-transaction certify $TRANSACTION_HASH_1,$TRANSACTION_HASH_2
@@ -280,14 +280,28 @@ make docker-run
 
 Here are the subcommands available:
 
+### Cardano DB (previously: Snapshot)
+
+| Subcommand | Performed action |
+|------------|------------------|
+| **download** | Downloads and restores a cardano-db snapshot|
+| **help** | Prints this message or the help for the given subcommand(s)|
+| **snapshot list** | Lists available cardano-db snapshots|
+| **snapshot show** | Shows information about a cardano-db snapshot|
+
 ### Snapshot
 
+:::warning
+The `snapshot` commands are now **deprecated** and has been superseded by the `cardano-db` commands.
+The `snapshot` commands  will be removed in the near future.
+:::
+
 | Subcommand | Performed action |
 |------------|------------------|
-| **download** | Downloads and restores a snapshot|
+| **download** | Downloads and restores a cardano-db snapshot|
 | **help** | Prints this message or the help for the given subcommand(s)|
-| **list** | Lists available snapshots|
-| **show** | Shows information about a snapshot|
+| **list** | Lists available cardano-db snapshots|
+| **show** | Shows information about a cardano-db snapshot|
 
 ### Mithril stake distribution
 
@@ -302,8 +316,8 @@ Here are the subcommands available:
 | Subcommand | Performed action |
 |------------|------------------|
 | **certify** | Certifies that given list of transactions hashes are included in the Cardano transactions set|
-| **commitment list** | Lists available Cardano transactions commitments|
-| **commitment show** | Shows information about a Cardano transactions commitment|
+| **snapshot list** | Lists available Cardano transactions snapshots|
+| **snapshot show** | Shows information about a Cardano transactions snapshot|
 | **help** | Prints this message or the help for the given subcommand(s)|
 
 ## Configuration parameters
@@ -328,25 +342,25 @@ Here is a list of the available parameters:
 | `log_format_json` | `--log-format-json` | - | - | Enable JSON output for logs | - | - | - |
 | `log_output` | `--log-output` | `-o` | - | Redirect the logs to a file | - | `./mithril-client.log` | - |
 
-`snapshot show` command:
+`cardano-db snapshot show` or `snapshot show` command:
 
 | Parameter | Command line (long) |  Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
-| `digest` | `--digest` | - | `DIGEST` | Snapshot digest or `latest` for the latest digest | - | - | :heavy_check_mark: |
+| `digest` | `--digest` | - | `DIGEST` | Cardano DB digest or `latest` for the latest digest | - | - | :heavy_check_mark: |
 | `json` | `--json` | - | - | Enable JSON output for command results | - | - | - |
 
-`snapshot list` command:
+`cardano-db snapshot list` or `snapshot list` command:
 
 | Parameter | Command line (long) |  Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
 | `json` | `--json` | - | - | Enable JSON output for command results | - | - | - |
 
-`snapshot download` command:
+`cardano-db download` or `snapshot download` command:
 
 | Parameter | Command line (long) |  Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
-| `digest` | `--digest` | - | `DIGEST` | Snapshot digest or `latest` for the latest digest | - | - | :heavy_check_mark: |
-| `download_dir` | `--download-dir` | - | - | Directory where the snapshot will be downloaded | . | - | - |
+| `digest` | `--digest` | - | `DIGEST` | Cardano DB digest or `latest` for the latest digest | - | - | :heavy_check_mark: |
+| `download_dir` | `--download-dir` | - | - | Directory where the Cardano DB will be downloaded | . | - | - |
 | `json` | `--json` | - | - | Enable JSON output for progress logs | - | - | - |
 
 `mithril-stake-distribution list` command:
@@ -362,14 +376,14 @@ Here is a list of the available parameters:
 | `artifact_hash` | `--artifact-hash` | - | - | Hash of the Mithril stake distribution artifact or `latest` for the latest artifact | - | - | :heavy_check_mark: |
 | `download_dir` | `--download-dir` | - | - | Directory where the Mithril stake distribution will be downloaded | . | - | - |
 
-`cardano-transaction commitment show` command:
+`cardano-transaction snapshot show` command:
 
 | Parameter | Command line (long) |  Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|
-| `hash` | `--hash` | - | `HASH` | Cardano transaction commitment hash or `latest` for the latest Cardano transaction commitment | - | - | :heavy_check_mark: |
+| `hash` | `--hash` | - | `HASH` | Cardano transaction snapshot hash or `latest` for the latest Cardano transaction snapshot | - | - | :heavy_check_mark: |
 | `json` | `--json` | - | - | Enable JSON output for command results | - | - | - |
 
-`cardano-transaction commitment list` command:
+`cardano-transaction snapshot list` command:
 
 | Parameter | Command line (long) |  Command line (short) | Environment variable | Description | Default value | Example | Mandatory |
 |-----------|---------------------|:---------------------:|----------------------|-------------|---------------|---------|:---------:|

internal/mithril-build-script/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-build-script"
-version = "0.1.1"
+version = "0.1.2"
 description = "A toolbox for Mithril crates build scripts"
 authors = { workspace = true }
 edition = { workspace = true }