merge 'main'

Author: falcucci

.github/workflows/test-client.yml

@@ -31,6 +31,10 @@ on:
         required: false
         type: string
         default: https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey
+      transactions_hashes_to_certify:
+        description: Comma separated list of transactions hashes to test certification on.
+        required: false
+        type: string
       enable_debug:
         description: Enable debug output ("-vvv") for the mithril-client calls
         required: true
@@ -193,6 +197,7 @@ jobs:
         run: |
           echo "AGGREGATOR_ENDPOINT=${{ inputs.aggregator_endpoint }}" > ./www-test/.env
           echo "GENESIS_VERIFICATION_KEY=$(curl -s ${{ inputs.genesis_verification_key }})" >> ./www-test/.env
+          echo "TRANSACTIONS_HASHES_TO_CERTIFY=${{ inputs.transactions_hashes_to_certify }}" >> ./www-test/.env
 
       - name: Start the server
         working-directory: mithril-client-wasm

Cargo.lock

@@ -4,13 +4,17 @@ resolver = "2"
 
 members = [
   "demo/protocol-demo",
+  "examples/client-cardano-transaction",
   "examples/client-mithril-stake-distribution",
   "examples/client-snapshot",
   "mithril-aggregator",
+  "mithril-build-script",
   "mithril-client",
   "mithril-client-cli",
   "mithril-client-wasm",
   "mithril-common",
+  "mithril-doc",
+  "mithril-doc-derive",
   "mithril-persistence",
   "mithril-relay",
   "mithril-signer",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithrildemo"
-version = "0.1.29"
+version = "0.1.30"
 authors = { workspace = true }
 edition = { workspace = true }
 documentation = { workspace = true }
@@ -15,6 +15,7 @@ clap = { version = "4.4.18", features = ["derive"] }
 hex = "0.4.3"
 log = "0.4.20"
 mithril-common = { path = "../../mithril-common", features = ["fs"] }
+mithril-doc = { path = "../../mithril-doc" }
 rand_chacha = "0.3.1"
 rand_core = "0.6.4"
 serde = { version = "1.0.196", features = ["derive"] }

demo/protocol-demo/Cargo.toml

@@ -316,7 +316,7 @@ impl Demonstrator {
             })
             .collect::<Vec<Vec<u8>>>();
         Self {
-            config: *config,
+            config: config.clone(),
             parties,
             verifier: None,
             messages,
@@ -495,6 +495,7 @@ mod tests {
     fn default_config() -> crate::Config {
         let protocol_parameters = setup_protocol_parameters();
         crate::Config {
+            command: None,
             m: protocol_parameters.m,
             k: protocol_parameters.k,
             phi_f: protocol_parameters.phi_f,

demo/protocol-demo/src/demonstrator.rs

@@ -2,13 +2,18 @@ mod demonstrator;
 mod types;
 
 use crate::demonstrator::{Demonstrator, ProtocolDemonstrator};
-use clap::Parser;
+use clap::{CommandFactory, Parser, Subcommand};
+use mithril_doc::GenerateDocCommands;
 use rand_chacha::ChaCha20Rng;
 use rand_core::SeedableRng;
 
 /// Simple demonstration of the Mithril protocol
-#[derive(Parser, Debug, PartialEq, Clone, Copy)]
+#[derive(Parser, Debug, PartialEq)]
 pub struct Config {
+    /// Available commands
+    #[command(subcommand)]
+    command: Option<DemoCommands>,
+
     /// Security parameter, upper bound on indices
     #[clap(short, long, default_value_t = 200)]
     m: u64,
@@ -30,9 +35,29 @@ pub struct Config {
     nmessages: usize,
 }
 
+impl Clone for Config {
+    fn clone(&self) -> Self {
+        Config {
+            command: None,
+            ..*self
+        }
+    }
+}
+
+#[derive(Subcommand, Debug, PartialEq)]
+enum DemoCommands {
+    #[clap(alias("doc"), hide(true))]
+    GenerateDoc(GenerateDocCommands),
+}
+
 fn main() {
     let config = Config::parse();
 
+    if let Some(DemoCommands::GenerateDoc(cmd)) = &config.command {
+        cmd.execute(&mut Config::command()).unwrap();
+        return;
+    }
+
     println!(">> Launch Mithril protocol demonstrator with configuration: \n{config:#?}");
 
     //////////////////////

demo/protocol-demo/src/main.rs

@@ -24,6 +24,12 @@ A Cardano node is a node that runs in a [Cardano network](#cardano-network). The
 
 A Cardano key pair is an asymmetric key pair used to identify a [stake pool operator](#stake-pool-operator-spo) on the [Cardano network](#cardano-network).
 
+## Cardano transaction
+
+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).
+
 ## Certificate
 
 The Mithril aggregator combines the produced [multi-signature](#multi-signature) and some metadata into a Mithril certificate that will be later used by the [Mithril client](#mithril-client) to verify the authenticity of a [snapshot](#snapshot). The certificates are chained so that the [stake distribution](#stake-distribution) used to create the signatures is verifiably genuine.

docs/website/root/glossary.md

@@ -14,6 +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
 - [**Certificate**](../../../glossary.md#certificate): list, get, and chain validation.
 
 :::
@@ -113,6 +114,36 @@ let valid_stake_distribution_message = await client.verify_message_match_certifi
 console.log("valid_stake_distribution_message:", valid_stake_distribution_message);
 ```
 
+If the aggregator signs **CardanoTransactions**, you can add the code below to the previous example:
+
+:::tip
+
+You can verify that the aggregator signs **CardanoTransactions** by running the command below:
+
+```bash
+wget -q -O - YOUR_AGGREGATOR_ENDPOINT | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])'
+```
+
+For example with the aggregator on `testing-sanchonet` Mithril network:
+
+```bash
+wget -q -O - https://aggregator.testing-sanchonet.api.mithril.network/aggregator | jq '.capabilities.signed_entity_types | contains(["CardanoTransactions"])'
+```
+
+:::
+
+```js
+const proof = await client.unstable.get_cardano_transaction_proofs(["CARDANO_TRANSACTION_HASH_1", "CARDANO_TRANSACTION_HASH_2"]);
+console.log("Proof tx hash", proof.transactions_hashes);
+console.log("Proof certificate hash", proof.certificate_hash);
+
+let proof_certificate = await client.verify_certificate_chain(proof.certificate_hash);
+console.log("verify_certificate_chain OK, last_certificate_from_chain:", proof_certificate);
+
+let valid_cardano_transaction_proof = await client.unstable.verify_cardano_transaction_proof_then_compute_message(proof, proof_certificate);
+console.log("valid_cardano_transaction_proof:", valid_cardano_transaction_proof);
+```
+
 :::tip
 
 You can read the complete [Rust developer documentation](https://mithril.network/rust-doc/mithril_client_wasm/index.html).