feat(bungee-hermes): new plugin bungee-hermes

* refactored plugin bungee, using strategy design pattern * current version has strategy both for fabric and besu networks * includes a few tests to demonstrate basic functionality * added README with package documentation * added bungee tests to Cactus CI Co-authored-by: eduv09 <[email protected]> Co-authored-by: André Augusto <[email protected]> Co-authored-by: Rafael Belchior <[email protected]> Signed-off-by: eduv09 <[email protected]>
hyperledger-cacti · Apr 5, 2024 · ecf52ec · ecf52ec
1 parent e8d56e0
commit ecf52ec
Show file tree

Hide file tree

Showing 85 changed files with 10,960 additions and 12 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -1730,6 +1730,31 @@ jobs:
   #         restore-keys: |
   #           ${{ runner.os }}-yarn-
   #     - run: ./tools/ci.sh
+  cactus-plugin-bungee-hermes:
+    continue-on-error: false
+    env:
+      FULL_BUILD_DISABLED: true
+      JEST_TEST_RUNNER_DISABLED: false
+      JEST_TEST_PATTERN: packages/cactus-plugin-bungee-hermes/src/test/typescript/(unit|integration|benchmark)/.*/*.test.ts
+      TAPE_TEST_RUNNER_DISABLED: true
+    needs: build-dev
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Use Node.js ${{ env.NODEJS_VERSION }}
+        uses: actions/[email protected]
+        with:
+          node-version: ${{ env.NODEJS_VERSION }}
+      - uses: actions/[email protected]
+
+      - id: yarn-cache
+        name: Restore Yarn Cache
+        uses: actions/[email protected]
+        with:
+          key: ${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
+          path: ./.yarn/
+          restore-keys: |
+            ${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
+      - run: ./tools/ci.sh
   cactus-test-api-client:
     continue-on-error: false
     env:

diff --git a/CODEOWNERS b/CODEOWNERS
@@ -1,6 +1,7 @@
 * @petermetz @takeutak @izuru0 @jagpreetsinghsasan @vramakrishna @sandeepnRES @outSH
 
 packages/cactus-plugin-satp-hermes @RafaelAPB
+packages/cactus-plugin-bungee-hermes @RafaelAPB
 examples/cactus-example-cbdc-bridging @RafaelAPB
 examples/cactus-example-cbdc-bridging-backend @RafaelAPB
 examples/cactus-example-cbdc-bridging-frontend @RafaelAPB
diff --git a/packages/cactus-plugin-bungee-hermes/CHANGELOG.md b/packages/cactus-plugin-bungee-hermes/CHANGELOG.md
diff --git a/packages/cactus-plugin-bungee-hermes/README.md b/packages/cactus-plugin-bungee-hermes/README.md
@@ -0,0 +1,159 @@
+# `@hyperledger/cactus-plugin-bungee-hermes`
+
+The package provides `Hyperledger Cacti` a way to create blockchain snapshots and views for different distributed ledgers currently supported by Cacti. The implementation follows the paper [BUNGEE](https://dl.acm.org/doi/pdf/10.1145/3643689) (Blockchain UNifier view GEnErator).
+
+The plugin will allow, as suggested in the paper, "new applications built on top
+of dependable blockchain interoperability, such as stakeholder-centric snapshots for audits, cross-chain analysis, blockchain
+migration, and combined on-chain-off-chain analytics".
+
+## Summary
+
+- [`@hyperledger/cactus-plugin-bungee-hermes`](#hyperledgercactus-plugin-bungee-hermes)
+  - [Summary](#summary)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+  - [Architecture](#architecture)
+    - [BUNGEE - Hermes API](#bungee---hermes-api)
+  - [Running the tests](#running-the-tests)
+  - [Usage](#usage)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+
+## Getting Started
+
+Clone the git repository on your local machine. Follow these instructions that will get you a copy of the project up and running on
+your local machine for development and testing purposes.
+
+### Prerequisites
+
+In the root of the project to install the dependencies execute the command:
+```sh
+npm run configure
+```
+
+Know how to use the following plugins of the project:
+
+  - [cactus-plugin-ledger-connector-fabric](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-ledger-connector-fabric)
+  - [cactus-plugin-ledger-connector-besu](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-ledger-connector-besu)
+
+
+## Architecture
+
+The plugin interacts with a cactus ledger connector, using strategies with custom logic for each different network.
+
+Note that, so far, only strategies for Fabric and Besu networks were implemented. Smart-contracts in Fabric and Besu must implement the interface provided in the files ITraceableContract.ts and ITraceableContract.sol, in the test directory 
+
+The plugin stands _behind_ a cacti-ledger-connector, which is used to fetch information from the ledger to create the snapshot.
+```typescript
+.......................................
+.            Cacti Node               .
+.                                     .
+.                                     .
+. ..........            ............. .          .........
+. .        .            .   Cacti   . .          .       .
+. . BUNGEE . ---------- . Connector . -----------. _DLT  . 
+. .        .            ............. .          .       .
+. ..........                          .          .........  
+.                                     .
+.                                     .
+.                                     .
+.......................................
+```
+The plugin can then serve multiple purposes, and thus serve also other plugins or apps in more complex deployment architectures (where we link bungee to other components).
+
+### BUNGEE - Hermes API
+
+This plugin uses OpenAPI to generate the API paths.
+Endpoints exposed:
+
+  - CreateViewV1
+  - GetPublicKey
+  - GetAvailableStrategies
+
+
+## Running the tests
+  - **besu-test-basic.test.ts**: A test using strategy-besu and a besu connector, testing creating views for different timeframes and states.
+  - **fabric-test-basic.test.ts**: A test using strategy-fabric and a fabric connector, testing creating views for different timeframes and states.
+  - **besu-test-pruning.test.ts**: A test using strategy-besu and a besu connector, testing creating views for specific timeframes.
+  - **fabric-test-pruning.test.ts**: A test using strategy-fabric and a fabric connector, testing creating views for specific timeframes.
+  - **bungee-api-test.test.ts**: A more complex test, using both besu and fabric strategies, fabric and besu connectors, and calls to bungee-hermes API. Tests bungee's API and functionality with multiple strategies. 
+
+Tests developed using JEST testing framework.
+
+## Usage
+Lets imagine we want bungee-hermes to create views for a besu ledger.
+Let us consider a besu ledger connector, exposing its API on URL: http://localhost:4000
+
+
+Then we instantiate the plugin as follows:
+```typescript
+const pluginBungeeHermesOptions = {
+    keyPair: Secp256k1Keys.generateKeyPairsBuffer(),
+    instanceId: uuidv4(),
+    logLevel,
+};
+const bungee = new PluginBungeeHermes(pluginBungeeHermesOptions);
+```
+
+We add the desired strategies:
+
+```typescript
+bungee.addStrategy('BESU_STRATEGY', new StrategyBesu("INFO"));
+```
+
+Save network details for our target ledger:
+
+```typescript
+const besuNetworkDetails: BesuNetworkDetails = {
+    signingCredential: besuSigningCredential,
+    contractName: besuContractName,
+    connectorApiPath: 'http://localhost:4000',
+    keychainId: besuKeychainPlugin.getKeychainId(),
+    contractAddress: besuContractAddress,
+    participant: accountAddress,
+  };
+```
+
+And we can request views, after exposing the api:
+```typescript
+const expressApp = express();
+  expressApp.use(bodyParser.json({ limit: "250mb" }));
+  bungeeServer = http.createServer(expressApp);
+  const listenOptions: IListenOptions = {
+    hostname: "127.0.0.1",
+    port: 3000,
+    server: bungeeServer,
+  };
+const addressInfo = (await Servers.listen(listenOptions)) as AddressInfo;
+const { address, port } = addressInfo;
+
+await bungee.getOrCreateWebServices();
+await bungee.registerWebServices(expressApp);
+const bungeePath = `http://${address}:${port}`;
+
+const config = new Configuration({ basePath: bungeePath });
+const bungeeApi = new BungeeApi(config);
+
+const viewBesu = await bungeeApi.createViewV1({
+    strategyId: 'BESU_STRATEGY',
+    networkDetails: besuNetworkDetails,
+    tI: undefined,          //default to 0 (UNIX timestamp seconds)
+    tF: undefined,          //default to Number.MAX_SAFE_INTEGER.toString() (UNIX timestamp seconds)
+    stateIds: undefined,    //default to capture all assets
+    viewID: undefined,      //plugin generates the id, if not given
+  } as CreateViewRequest);
+```
+
+Note that each strategy can be used to query different ledgers (ledgers of the same type, but on different locations), and BUNGEE also supports adding multiple strategies to each bungee-hermes-plugin instance.
+Each strategy implements the logic to query information from each different ledger (i.e. capture set of asset states), while bungee-hermes plugin handles the snapshot and view creation.
+
+
+
+## Contributing
+We welcome contributions to Hyperledger Cactus in many forms, and there’s always plenty to do!
+
+Please review [CONTIRBUTING.md](https://github.com/hyperledger/cactus/blob/main/CONTRIBUTING.md "CONTIRBUTING.md") to get started.
+
+## License
+This distribution is published under the Apache License Version 2.0 found in the [LICENSE ](https://github.com/hyperledger/cactus/blob/main/LICENSE "LICENSE ")file.
diff --git a/packages/cactus-plugin-bungee-hermes/openapitools.json b/packages/cactus-plugin-bungee-hermes/openapitools.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "6.6.0"
+  }
+}
diff --git a/packages/cactus-plugin-bungee-hermes/package.json b/packages/cactus-plugin-bungee-hermes/package.json
@@ -0,0 +1,111 @@
+{
+  "name": "@hyperledger/cactus-plugin-bungee-hermes",
+  "version": "2.0.0-alpha.2",
+  "description": "Allows Cactus nodes to create DLT views using Cactus connectors",
+  "keywords": [
+    "Hyperledger",
+    "Cactus",
+    "Integration",
+    "Blockchain",
+    "Distributed Ledger Technology",
+    "View"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperledger/cacti.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Hyperledger Cactus Contributors",
+    "email": "[email protected]",
+    "url": "https://www.hyperledger.org/use/cacti"
+  },
+  "contributors": [
+    {
+      "name": "Eduardo Vasques",
+      "email": "[email protected]",
+      "url": "https://github.com/eduv09"
+    },
+    {
+      "name": "Rafael Belchior",
+      "email": "[email protected]",
+      "url": "https://rafaelapb.github.io/"
+    },
+    {
+      "name": "André Augusto",
+      "email": "[email protected]",
+      "url": "https://github.com/AndreAugusto11"
+    }
+  ],
+  "main": "dist/lib/main/typescript/index.js",
+  "module": "dist/lib/main/typescript/index.js",
+  "types": "dist/lib/main/typescript/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "codegen": "run-p 'codegen:*'",
+    "codegen:openapi": "npm run generate-sdk",
+    "generate-sdk": "run-p 'generate-sdk:*'",
+    "generate-sdk:kotlin": "openapi-generator-cli generate -i ./src/main/json/openapi.json -g kotlin -o ./src/main/kotlin/generated/openapi/kotlin-client/ --reserved-words-mappings protected=protected --ignore-file-override ../../openapi-generator-ignore",
+    "generate-sdk:typescript-axios": "openapi-generator-cli generate -i ./src/main/json/openapi.json -g typescript-axios -o ./src/main/typescript/generated/openapi/typescript-axios/ --reserved-words-mappings protected=protected --ignore-file-override ../../openapi-generator-ignore",
+    "pretsc": "npm run generate-sdk",
+    "tsc": "tsc --project ./tsconfig.json",
+    "watch": "npm-watch"
+  },
+  "dependencies": {
+    "@hyperledger/cactus-cmd-api-server": "2.0.0-alpha.2",
+    "@hyperledger/cactus-common": "2.0.0-alpha.2",
+    "@hyperledger/cactus-core": "2.0.0-alpha.2",
+    "@hyperledger/cactus-core-api": "2.0.0-alpha.2",
+    "@hyperledger/cactus-plugin-keychain-memory": "2.0.0-alpha.2",
+    "@hyperledger/cactus-plugin-ledger-connector-besu": "2.0.0-alpha.2",
+    "@hyperledger/cactus-plugin-ledger-connector-fabric": "2.0.0-alpha.2",
+    "@hyperledger/cactus-plugin-object-store-ipfs": "2.0.0-alpha.2",
+    "@hyperledger/cactus-test-tooling": "2.0.0-alpha.2",
+    "axios": "1.6.0",
+    "body-parser": "1.20.2",
+    "fs-extra": "10.1.0",
+    "key-encoder": "2.0.3",
+    "typescript-optional": "2.0.1",
+    "uuid": "9.0.1",
+    "web3": "1.6.1",
+    "web3-core": "1.6.1"
+  },
+  "devDependencies": {
+    "@types/body-parser": "1.19.4",
+    "@types/crypto-js": "4.0.1",
+    "@types/express": "4.17.19",
+    "@types/fs-extra": "11.0.3",
+    "@types/tape": "4.13.4",
+    "@types/uuid": "9.0.6",
+    "express": "4.18.2",
+    "fabric-network": "2.2.20",
+    "socket.io": "4.5.4"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "watch": {
+    "tsc": {
+      "patterns": [
+        "src/",
+        "src/*/json/**/openapi*"
+      ],
+      "ignore": [
+        "src/**/generated/*"
+      ],
+      "extensions": [
+        "ts",
+        "json"
+      ],
+      "quiet": true,
+      "verbose": false,
+      "runOnChangeOnly": true
+    }
+  }
+}