refactor: reorganize wasm example & ci test

- Move nodejs & web browser examples to the `/examples` directory
  - Standardize them: add a README and a MAKEFILE when missing
- Rename `mithril-client-wasm/www-test` to `ci-test`
- adapt ci
- adapt upgrade repository dependencies devbook

Co-authored-by: Damien Lachaume <[email protected]>

Author: Alenar

.github/workflows/test-client.yml

@@ -300,19 +300,19 @@ jobs:
 
       - name: Install dependencies
         working-directory: mithril-client-wasm
-        run: make www-test-install
+        run: make ci-test-install
 
       - name: Create .env file
         working-directory: mithril-client-wasm
         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
+          echo "AGGREGATOR_ENDPOINT=${{ inputs.aggregator_endpoint }}" > ./ci-test/.env
+          echo "GENESIS_VERIFICATION_KEY=$(curl -s ${{ inputs.genesis_verification_key }})" >> ./ci-test/.env
+          echo "TRANSACTIONS_HASHES_TO_CERTIFY=${{ inputs.transactions_hashes_to_certify }}" >> ./ci-test/.env
 
       - name: Start the server
         working-directory: mithril-client-wasm
         shell: bash
-        run: make www-test-serve &
+        run: make ci-test-serve &
 
       - name: Wait for the server to be ready
         shell: bash

docs/devbook/upgrade-repository-dependencies/README.md

@@ -84,32 +84,61 @@ chore: upgrade doc dependencies
 By running 'make upgrade' command.
 ```
 
-### Upgrade `www/` and `www-test/` dependencies
+### Upgrade client wasm `ci-test/` dependencies
 
 From the root of the repository, run:
 
-[!IMPORTANT]: This command must be run before upgrading `mithril-explorer`.
+Upgrade the `ci-test` dependencies by running:
 
 ```bash
-cd mithril-client-wasm
-make upgrade-www-deps
+make -C mithril-client-wasm upgrade-ci-test-deps
+```
+
+Create a dedicated commit, e.g.:
+
+```bash
+chore: upgrade mithril client wasm 'ci-test' dependencies
+
+By running 'make upgrade-ci-test-deps' command.
+```
+
+### Upgrade client wasm examples dependencies
+
+From the root of the repository, run:
+
+[!IMPORTANT]: This command must be run before upgrading client wasm examples.
+
+```bash
+make -C mithril-client-wasm build
+```
+
+Upgrade the examples dependencies by running:
+
+```bash
+make -C examples/client-wasm-nodejs upgrade
+make -C examples/client-wasm-web upgrade
 ```
 
 Create a dedicated commit, e.g.:
 
 ```bash
-chore: upgrade mithril client wasm 'www' and 'www-test' dependencies
+chore: upgrade mithril client wasm examples dependencies
 
-By running 'make upgrade-www-deps' command.
+By running 'make upgrade' command in 'examples/client-wasm-nodejs' and 'examples/client-wasm-web'.
 ```
 
 ### Upgrade the explorer dependencies
 
+[!IMPORTANT]: This command must be run before upgrading `mithril-explorer`.
+
+```bash
+make -C mithril-client-wasm build
+```
+
 From the root of the repository, run:
 
 ```bash
-cd mithril-explorer
-make upgrade
+make -C mithril-explorer upgrade
 ```
 
 Create a dedicated commit, e.g.:

docs/devbook/upgrade-repository-dependencies/upgrade_dependencies.sh

@@ -23,26 +23,26 @@ cargo set-version --bump patch
 git commit -am "chore: bump crates versions"
 
 # Build mithril-client wasm (to have latest version used in the explorer)
-pushd mithril-client-wasm || exit
-make build
-popd || exit
+make -C mithril-client-wasm build
 
 # Upgrade the documentation website dependencies
-pushd docs/website || exit
-make upgrade
-popd || exit
+make -C docs/website upgrade
 git commit -am "chore: upgrade doc dependencies
 
 By running 'make upgrade' command."
 
-# Upgrade www/ and www-test/ dependencies
-pushd mithril-client-wasm || exit
-make upgrade-www-deps
-popd || exit
+# Upgrade ci-test/ dependencies
+make -C mithril-client-wasm upgrade-ci-test-deps
+git commit -am "chore: upgrade mithril client wasm 'ci-test' dependencies
+
+By running 'make upgrade-ci-test-deps' command."
 
-git commit -am "chore: upgrade mithril client wasm 'www' and 'www-test' dependencies
+# Upgrade client wasm examples dependencies
+make -C examples/client-wasm-nodejs upgrade
+make -C examples/client-wasm-web upgrade
+git commit -am "chore: upgrade mithril client wasm examples dependencies
 
-By running 'make upgrade-www-deps' command."
+By running 'make upgrade' command in 'examples/client-wasm-nodejs' and 'examples/client-wasm-web'."
 
 # Upgrade the explorer dependencies
 pushd mithril-explorer || exit
@@ -55,25 +55,19 @@ By running 'make upgrade' command."
 # Bump Javascript packages versions
 
 # Search all package.json files and bump the version
-# and exclude `package.json` in `node_modules` folder
-for package_json_file in $(find . -name package.json | grep -v "/node_modules/" | grep -v "/pkg/"); do
+# and exclude `package.json` in auto-generated folders
+for package_json_file in $(find . -name package.json | grep -v "/node_modules/" | grep -v "/pkg/" | grep -v "/dist/"); do
     folder="$(dirname $package_json_file)"
     pushd "$folder" || exit
     npm version patch
     popd || exit
 done
 
-pushd mithril-client-wasm || exit
-make www-install www-test-install
-popd || exit
-
-pushd mithril-explorer || exit
-make install
-popd || exit
-
-pushd docs/website || exit
-make install
-popd || exit
+make -C mithril-client-wasm ci-test-install
+make -C examples/client-wasm-nodejs ci-test-install
+make -C examples/client-wasm-web ci-test-install
+make -C mithril-explorer install
+make -C docs/website install
 
 git commit -am "chore: bump javascript packages versions
 

mithril-client-wasm/node-test/.gitignore renamed to examples/client-wasm-nodejs/.gitignore

@@ -0,0 +1,21 @@
+.PHONY: clean install upgrade
+
+package-lock.json:
+	npm install
+
+install: package-lock.json
+
+clean:
+	rm -rf build
+	rm package-lock.json || true
+
+upgrade: clean install
+	npm install \
+		prettier@latest \
+
+
+lint:
+	npm run pretty:check
+
+format:
+	npm run pretty:write

examples/client-wasm-nodejs/Makefile

@@ -0,0 +1,39 @@
+# Mithril client wasm library example: Node.js
+
+## Description
+
+This example shows how to implement a Mithril client and use its features in a Node.js environment.
+
+In this example, the client interacts by default with a real aggregator on the network `testing-sanchonet` to:
+
+- Mithril Stake Distribution:
+  - list the available Mithril Stake Distributions
+  - verify the latest Mithril Stake Distribution
+  - verify a certificate chain
+  - compute a message
+  - verify that the certificate signs the computed message
+- Cardano transactions
+  - get proof of inclusion for a known set of Cardano transactions
+  - verify a certificate chain
+  - compute a message for
+  - verify that the certificate signs the computed message
+
+## Build and run the example
+
+First you need to compile the Mithril client Wasm library:
+
+```bash
+make -C ../../mithril-client-wasm build
+```
+
+Then you can run the example:
+
+```bash
+npm install
+npm run start
+```
+
+## Links
+
+- **Developer documentation**: https://mithril.network/doc/manual/develop/nodes/mithril-client-library-wasm
+- **NPM**: https://www.npmjs.com/package/@mithril-dev/mithril-client-wasm

examples/client-wasm-nodejs/README.md

@@ -10,16 +10,16 @@ broadcast_channel.onmessage = (e) => {
   let event = e.data;
   if (event.type === "CertificateChainValidationStarted") {
     console.log(
-      `The certificate chain validation has started, event_id: ${event.payload.certificate_chain_validation_id}`
+      `The certificate chain validation has started, event_id: ${event.payload.certificate_chain_validation_id}`,
     );
   } else if (event.type === "CertificateValidated") {
     console.log(
-      `A certificate has been validated, certificate_hash: ${event.payload.certificate_hash}, event_id: ${event.payload.certificate_chain_validation_id}`
+      `A certificate has been validated, certificate_hash: ${event.payload.certificate_hash}, event_id: ${event.payload.certificate_chain_validation_id}`,
     );
   } else if (event.type === "CertificateChainValidated") {
     certificate_chain_validated_occurs = true;
     console.log(
-      `The certificate chain is valid, event_id: ${event.payload.certificate_chain_validation_id}`
+      `The certificate chain is valid, event_id: ${event.payload.certificate_chain_validation_id}`,
     );
   } else {
     console.log(event);
@@ -40,62 +40,69 @@ async function main() {
     http_headers: new Map([["Content-Type", "application/json"]]),
     // The following option activates the unstable features of the client.
     // Unstable features will trigger an error if this option is not set.
-    unstable: true
+    unstable: true,
   });
 
   console.log(1, "Getting stake distributions list...");
   let mithril_stake_distributions_list = await client.list_mithril_stake_distributions();
   console.log(
     "Result",
-    "got " + mithril_stake_distributions_list.length + " stake distributions ✔️"
+    "got " + mithril_stake_distributions_list.length + " stake distributions ✔️",
   );
   console.log("stake distributions:", mithril_stake_distributions_list);
   let last_mithril_stake_distribution = mithril_stake_distributions_list[0];
 
   console.log(
     2,
-    "Getting last stake distribution with hash: " + last_mithril_stake_distribution.hash + "..."
+    "Getting last stake distribution with hash: " + last_mithril_stake_distribution.hash + "...",
   );
   let last_stake_distribution = await client.get_mithril_stake_distribution(
-    last_mithril_stake_distribution.hash
+    last_mithril_stake_distribution.hash,
   );
   console.log("Result", "got last stake distribution ✔️");
   console.log("last_stake_distribution:", {
     epoch: last_stake_distribution.epoch,
-    signers: last_stake_distribution.signers.map((s) => `${s.party_id} - ${s.stake} lovelace`)
+    signers: last_stake_distribution.signers.map((s) => `${s.party_id} - ${s.stake} lovelace`),
   });
 
   console.log(
     3,
     "Getting Mithril certificate from certificate hash: " +
-    last_stake_distribution.certificate_hash +
-    "..."
+      last_stake_distribution.certificate_hash +
+      "...",
   );
   let certificate = await client.get_mithril_certificate(last_stake_distribution.certificate_hash);
   console.log("Result", "got Mithril certificate ✔️");
-  console.log("certificate:", certificate.hash, "epoch:", certificate.epoch, "signed_entity:", certificate.signed_entity_type);
+  console.log(
+    "certificate:",
+    certificate.hash,
+    "epoch:",
+    certificate.epoch,
+    "signed_entity:",
+    certificate.signed_entity_type,
+  );
 
   console.log(4, "Verifying certificate chain...");
   let last_certificate_from_chain = await client.verify_certificate_chain(certificate.hash);
   await waitUntilCertificateChainValidatedOccursOrTimeout();
   console.log("Result", "certificate chain verified ✔️");
   console.log(
     "verify_certificate_chain OK, last_certificate_from_chain:",
-    last_certificate_from_chain.hash
+    last_certificate_from_chain.hash,
   );
 
   console.log(5, "Computing the Mithril stake distribution message...");
   let mithril_stake_distributions_message = await client.compute_mithril_stake_distribution_message(
     last_stake_distribution,
-    last_certificate_from_chain
+    last_certificate_from_chain,
   );
   console.log("Result", "Mithril stake distribution message computed ✔️");
   console.log("mithril_stake_distributions_message:", mithril_stake_distributions_message);
 
   console.log(6, "Validating Mithril stake distribution message...");
   let valid_stake_distribution_message = await client.verify_message_match_certificate(
     mithril_stake_distributions_message,
-    last_certificate_from_chain
+    last_certificate_from_chain,
   );
   console.log("Result", "Mithril stake distribution message validated ✔️");
   console.log("valid_stake_distribution_message:", valid_stake_distribution_message);
@@ -104,17 +111,11 @@ async function main() {
   const proof = await client.get_cardano_transaction_proofs([
     "eac09f970f47ef3ab378db9232914e146773853397e79b904f1a45123a23c21f",
     "81fe7a5dab42867ef309b6d7210158bf99331884ac3c3b6c7188a8c9c18d5974",
-    "320c13f4a3e51f6f4f66fcd9007e02bf658aa4ee9a88a509028d867d3b8a8e9a"
+    "320c13f4a3e51f6f4f66fcd9007e02bf658aa4ee9a88a509028d867d3b8a8e9a",
   ]);
   console.log("Certificate hash of the returned proof", proof.certificate_hash);
-  console.log(
-    "Transactions hashes included in the proof:",
-    proof.transactions_hashes
-  );
-  console.log(
-    "Transactions hashes not included in the proof:",
-    proof.non_certified_transactions
-  );
+  console.log("Transactions hashes included in the proof:", proof.transactions_hashes);
+  console.log("Transactions hashes not included in the proof:", proof.non_certified_transactions);
 
   console.log(9, "Verifying certificate chain...");
   let proof_certificate = await client.verify_certificate_chain(proof.certificate_hash);
@@ -125,19 +126,18 @@ async function main() {
   console.log(10, "Validating Cardano transaction proof message...");
   let protocol_message = await client.verify_cardano_transaction_proof_then_compute_message(
     proof,
-    proof_certificate
+    proof_certificate,
   );
   console.log("Ensure that the proof is indeed signed in the associated certificate");
-  if ((await client.verify_message_match_certificate(protocol_message, proof_certificate)) === true) {
+  if (
+    (await client.verify_message_match_certificate(protocol_message, proof_certificate)) === true
+  ) {
     console.log("Result", "The proof is signed in the associated certificate ✔️");
   } else {
     console.log("Result", "Proof and certificate don't match ❌");
   }
   console.log("Transactions hashes certified", proof.transactions_hashes);
-  console.log(
-    "Transactions hashes not certified",
-    proof.non_certified_transactions
-  );
+  console.log("Transactions hashes not certified", proof.non_certified_transactions);
 
   process.exit(0);
 }