feat(cbdc-bridging-app): implementation of CBDC bridging example

This application demonstrates a CBDC bridging between a Fabric and a Besu network
using the ODAP business logic plugin, a protocol under standardization for cross-chain
asset transfers in the IETF.

The goal is to demonstrate the use of npm packages of Cactus so that anyone can
build a solution on top of Cacti.

Summary:
* CBDC application backend (set up underlying ledgers and deployment of smart contracts)
* Add support for multiple organizations in some operations in the FabricTestLedger
* Add support for minting some Ether to a given address in the BesuTestLedger

Future Work:
* CBDC app UI demonstrating the use of the app is, for now, only available as docker image
* A Dockerfile for the backend will be created as soon as this package is published to npm
* More documentation will be added in the next weeks

Depends on: hyperledger#2205

Signed-off-by: André Augusto <andre.augusto@tecnico.ulisboa.pt>

.cspell.json

@@ -20,6 +20,8 @@
         "cafile",
         "caio",
         "cccs",
+        "cbdc",
+        "Cbdc",
         "ccid",
         "cids",
         "commenceack",
@@ -55,6 +57,7 @@
         "htlc",
         "Htlc",
         "HTLC",
+        "Hursley",
         "HyperLedger",
         "ipaddress",
         "ipfs",

.vscode/template.launch.json

@@ -65,6 +65,31 @@
         "${workspaceFolder}/**/*.js",
         "!**/node_modules/**"
       ]
+    },
+    {
+      "name": "Example: CBDC Bridging Fabric-EVM App",
+      "type": "node",
+      "request": "launch",
+      "protocol": "inspector",
+      "env": {
+        "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json"
+      },
+      "args": [
+        "${workspaceFolder}/examples/cactus-example-cbdc-bridging-backend/src/main/typescript/cbdc-bridging-app-cli.ts",
+        "dotenv_config_path=${workspaceFolder}/examples/cactus-example-cbdc-bridging-backend/process.env"
+      ],
+      "runtimeArgs": [
+        "-r",
+        "ts-node/register",
+        "-r",
+        "dotenv/config"
+      ],
+      "console": "integratedTerminal",
+      "sourceMaps": true,
+      "outFiles": [
+        "${workspaceFolder}/**/*.js",
+        "!**/node_modules/**"
+      ]
     }
   ]
 }

examples/cactus-example-cbdc-bridging-backend/Dockerfile

@@ -0,0 +1,69 @@
+FROM cruizba/ubuntu-dind:19.03.11
+
+USER root
+
+RUN apt-get update
+RUN apt -y upgrade
+
+# Need curl for healthchecks
+RUN apt-get -y install --no-install-recommends curl
+
+# The file binary is used to inspect exectubles when debugging container image issues
+RUN apt-get -y install --no-install-recommends file
+
+RUN apt-get -y install --no-install-recommends ca-certificates
+RUN apt-get -y install --no-install-recommends tzdata
+
+RUN apt-get -y install --no-install-recommends git
+RUN apt-get -y install --no-install-recommends apt-utils
+
+RUN apt -y install --no-install-recommends default-jdk
+
+ARG APP=/usr/src/app/cactus/
+COPY . ${APP}
+
+ENV TZ=Etc/UTC
+
+RUN mkdir -p ${APP}
+
+RUN mkdir -p "${APP}/log/"
+
+WORKDIR ${APP}
+
+SHELL ["/bin/bash", "--login", "-i", "-c"]
+# Installing Node Version Manager (nvm)
+RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
+
+RUN source ~/.bashrc && \
+    nvm install 16.8.0 && \
+    npm install -g yarn && \
+    npm run configure
+
+SHELL ["/bin/bash", "--login", "-c"]
+
+COPY ./examples/cactus-example-cbdc-bridging-backend/healthcheck.sh /
+
+ENV API_HOST=localhost
+ENV API_SERVER_1_PORT=4000
+ENV API_SERVER_2_PORT=4100
+ENV API_HOST_FRONTEND=localhost
+ENV API_PORT_FRONTEND=2000
+
+COPY examples/cactus-example-cbdc-bridging-backend/src/fabric-contracts /usr/src/app/cactus/examples/cactus-example-cbdc-bridging-backend/dist/lib/fabric-contracts
+COPY examples/cactus-example-cbdc-bridging-backend/supervisord.conf /etc/supervisord.conf
+COPY examples/cactus-example-cbdc-bridging-backend/run-cbdc-app.sh /run-cbdc-app.sh
+RUN chmod +x /run-cbdc-app.sh
+
+# supervisord web ui/dashboard
+EXPOSE 9001
+# API #1
+EXPOSE 4000
+# API #2
+EXPOSE 4100
+
+# Extend the parent image's entrypoint
+# https://superuser.com/questions/1459466/can-i-add-an-additional-docker-entrypoint-script
+ENTRYPOINT ["/usr/bin/supervisord"]
+CMD ["--configuration", "/etc/supervisord.conf", "--nodaemon"]
+HEALTHCHECK --interval=1s --timeout=5s --start-period=20s --retries=250 \
+    CMD /usr/src/app/cactus/examples/cbdc-bridge-app/healthcheck.sh

examples/cactus-example-cbdc-bridging-backend/README.md

@@ -0,0 +1,38 @@
+# Hyperledger Cactus Example - CBDC Bridging between Fabric and Besu Backend
+
+## Running the Test Suites
+
+> Make sure you have all the dependencies set up as explained in `BUILD.md`
+
+On the terminal, issue the following commands in the project root:
+
+1. `npm run configure`
+2. `npm run start:example-cbdc-bridging-app`
+
+Wait for the output to show the message `CbdcBridgingApp running...`
+
+In a second terminal run the following commands from the project root:
+3. `cd examples/cactus-example-cbdc-bridging-backend`
+4. `npm run test`
+
+## Running the Example Application Locally
+
+> Make sure you have all the dependencies set up as explained in `BUILD.md`
+
+On the terminal, issue the following commands:
+
+1. `npm run configure`
+2. `npm run start:example-cbdc-bridging-app`
+
+Wait for the output to show the message `CbdcBridgingApp running...`
+
+## Debugging the Example Application Locally
+
+On the terminal, issue the following commands (steps 1 to 6) and then perform the rest of the steps manually.
+
+1. `npm run configure`
+2. Locate the `.vscode/template.launch.json` file
+3. Within that file locate the entry named `"Example: CBDC Bridging Fabric-EVM App"`
+4. Copy the VSCode debug definition object from 2) to your `.vscode/launch.json` file
+5. At this point the VSCode `Run and Debug` panel on the left should have an option also titled `"Example: CBDC Bridging Fabric-EVM App"` which starts the application
+6. Wait for the output to show the message `CbdcBridgingApp running...`

examples/cactus-example-cbdc-bridging-backend/healthcheck.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+curl -v -i -X OPTIONS http://127.0.0.1:${API_SERVER_1_PORT}

examples/cactus-example-cbdc-bridging-backend/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "@hyperledger/cactus-example-cbdc-bridging-backend",
+  "version": "1.1.3",
+  "description": "An example application showing how to use Cactus when implementing a CBDC bridging application between Hyperledger Fabric and Hyperledger Besu.",
+  "keywords": [
+    "Hyperledger",
+    "Cactus",
+    "ODAP",
+    "Fabric",
+    "Besu",
+    "Blockchain",
+    "CBDC"
+  ],
+  "homepage": "https://github.com/hyperledger/cactus#readme",
+  "bugs": {
+    "url": "https://github.com/hyperledger/cactus/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperledger/cactus.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Hyperledger Cactus Contributors",
+    "email": "cactus@lists.hyperledger.org",
+    "url": "https://www.hyperledger.org/use/cactus"
+  },
+  "contributors": [
+    {
+      "name": "Please add yourself to the list of contributors",
+      "email": "your.name@example.com",
+      "url": "https://example.com"
+    },
+    {
+      "name": "André Augusto",
+      "email": "andre.augusto@tecnico.ulisboa.pt"
+    }
+  ],
+  "main": "dist/lib/main/typescript/index.js",
+  "module": "dist/lib/main/typescript/index.js",
+  "browser": "dist/cactus-example-cbdc-bridging-backend.web.umd.js",
+  "types": "dist/lib/main/typescript/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "solidity": "hardhat compile",
+    "start": "CONFIG_FILE=./example-config.json node dist/lib/main/typescript/cbdc-bridging-app-cli.js",
+    "watch": "npm-watch",
+    "test": "nyc cucumber-js ./src/test/typescript/cucumber/features/*.feature --require-module ts-node/register --require './src/test/typescript/cucumber/*/*.ts'",
+    "webpack": "npm-run-all webpack:dev",
+    "webpack:dev": "npm-run-all webpack:dev:node webpack:dev:web",
+    "webpack:dev:node": "webpack --env=dev --target=node --config ../../webpack.config.js",
+    "webpack:dev:web": "webpack --env=dev --target=web --config ../../webpack.config.js",
+    "build:dev:backend:postbuild": "mkdir ./dist/lib/fabric-contracts && cp -r ./src/fabric-contracts/* ./dist/lib/fabric-contracts/"
+  },
+  "dependencies": {
+    "@hyperledger/cactus-api-client": "1.1.3",
+    "@hyperledger/cactus-cmd-api-server": "1.1.3",
+    "@hyperledger/cactus-common": "1.1.3",
+    "@hyperledger/cactus-core": "1.1.3",
+    "@hyperledger/cactus-core-api": "1.1.3",
+    "@hyperledger/cactus-plugin-keychain-memory": "1.1.3",
+    "@hyperledger/cactus-plugin-ledger-connector-fabric": "1.1.3",
+    "@hyperledger/cactus-plugin-ledger-connector-xdai": "1.1.3",
+    "@hyperledger/cactus-plugin-odap-hermes": "1.1.3",
+    "@hyperledger/cactus-test-tooling": "1.1.3",
+    "@openzeppelin/contracts": "4.4.2",
+    "@openzeppelin/contracts-upgradeable": "4.4.2",
+    "async-exit-hook": "2.0.1",
+    "axios": "^0.27.2",
+    "dotenv": "^16.0.1",
+    "fabric-network": "2.2.10",
+    "fs-extra": "10.0.0",
+    "nyc": "^13.1.0",
+    "openapi-types": "9.1.0",
+    "sqlite3": "^5.0.8",
+    "typescript-optional": "2.0.1",
+    "uuid": "8.3.2",
+    "web3-core": "1.5.2",
+    "web3-utils": "1.5.2"
+  },
+  "devDependencies": {
+    "@types/chai": "^4.3.1",
+    "@types/cucumber": "^4.0.4",
+    "@types/express": "4.17.13",
+    "@types/express-jwt": "6.0.2",
+    "@types/fs-extra": "9.0.12",
+    "@types/node": "^10.7.1",
+    "@types/uuid": "8.3.1",
+    "chai": "^4.1.2",
+    "cucumber": "^5.0.3",
+    "hardhat": "2.6.0",
+    "http-status-codes": "2.1.4",
+    "jose": "4.1.0",
+    "remix-tests": "^0.1.34",
+    "ts-node": "^7.0.1"
+  },
+  "engines": {
+    "node": ">=10",
+    "npm": ">=6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "browserMinified": "dist/cactus-example-cbdc-bridging-backend.web.umd.min.js",
+  "mainMinified": "dist/cactus-example-cbdc-bridging-backend.node.umd.min.js",
+  "watch": {
+    "solidity": {
+      "patterns": [
+        "./src/main/solidity/"
+      ],
+      "extensions": "sol"
+    }
+  }
+}

examples/cactus-example-cbdc-bridging-backend/process.env

@@ -0,0 +1,5 @@
+API_HOST=localhost
+API_SERVER_1_PORT=4000
+API_SERVER_2_PORT=4100
+API_HOST_FRONTEND=localhost
+API_PORT_FRONTEND=2000

examples/cactus-example-cbdc-bridging-backend/run-cbdc-app.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+function main()
+{
+  echo "Sleeping to let dockerd spin up"
+  sleep 10
+
+  docker pull ghcr.io/hyperledger/cactus-besu-all-in-one:2021-01-08-7a055c3
+  docker pull ghcr.io/hyperledger/cactus-fabric-all-in-one:v1.0.0-rc.2
+  docker pull ipfs/go-ipfs:v0.8.0
+
+  /root/.nvm/versions/node/v16.8.0/bin/node -r ts-node/register /usr/src/app/cactus/examples/cactus-example-cbdc-bridging-backend/dist/lib/main/typescript/cbdc-bridging-app-cli.js
+}
+
+main

examples/cactus-example-cbdc-bridging-backend/src/crypto-material/crypto-material.json

@@ -0,0 +1,40 @@
+{
+  "info": {
+    "description": "this file contains data to be used for testing purposes only. It should not be changed. It should remain consistent with the crypto material in the fabric chaincode"
+  },
+  "accounts": {
+    "userA": {
+      "ethAddress": "0x1A86D6f4b5D30A07D1a94bb232eF916AFe5DbDbc",
+      "privateKey": "0xb47c3ba5a816dbbb2271db721e76e6c80e58fe54972d26a42f00bc97a92a2535",
+      "fabricID": "x509::/OU=client/OU=org1/OU=department1/CN=userA::/C=US/ST=North Carolina/L=Durham/O=org1.example.com/CN=ca.org1.example.com"
+    },
+    "bridge": {
+      "ethAddress": "0xf28d5769171bfbD2B3628d722e58129a6aE15022",
+      "privateKey": "0x2917bd3b0dced512d3555f171a0979fedd37bb0593883089396d9b893aa0505d",
+      "fabricID": "x509::/OU=client/OU=org2/OU=department1/CN=bridge::/C=UK/ST=Hampshire/L=Hursley/O=org2.example.com/CN=ca.org2.example.com"
+    },
+    "userB": {
+      "ethAddress": "0xB264c626D7D09789AbfD2a431A28a054366e7b63",
+      "privateKey": "0xfe95d40663e60e9a8a2e1f4153c9e207ac26d928e8a5631647735d91e93be402",
+      "fabricID": "x509::/OU=client/OU=org1/OU=department1/CN=userB::/C=US/ST=North Carolina/L=Durham/O=org1.example.com/CN=ca.org1.example.com"
+    }
+  },
+  "gateways": {
+    "gateway1": {
+      "publicKey": "02e2beaa887c53d0ddb8383e2c49553545f50ae19074b4c7f79238dcb59f4b5fcb",
+      "privateKey": "206021a8ffaba949d21e32c02d76d2dc13da25e8197532ab300bb49d91397e52"
+    },
+    "gateway2": {
+      "publicKey": "02309ff54e58748616aa81245c1a4457f11fab47dcdb45b107dbcde24ee772b609",
+      "privateKey": "6bb4c730739969ff3429be71dd62d05459e61bc3f2956326449ae2ca7de50fb6"
+    }
+  },
+  "keychains": {
+    "keychain1": {
+      "id": "df05d3c2-ddd5-4074-aae3-526564217459"
+    },
+    "keychain2": {
+      "id": "d741fb4a-c95c-4205-8afa-758a9423234f"
+    }
+  }
+}

examples/cactus-example-cbdc-bridging-backend/src/fabric-contracts/asset-reference/typescript/.gitignore

@@ -0,0 +1,16 @@
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Dependency directories
+node_modules/
+jspm_packages/
+package-lock.json
+
+# Compiled TypeScript files
+dist
+