feat(bungee): implementation of bungee plugin

* plugin follows strategy design pattern defined in folder strategy/ * current version has strategy for fabric and besu networks * includes a few tests to demonstrate basic functionality * added README with package description Signed-off-by: eduv09 <eduardovasques10@tecnico.ulisboa.pt>
RafaelAPB · Mar 19, 2024 · 469a1a5 · 469a1a5
1 parent fb12f2c
commit 469a1a5
Show file tree

Hide file tree

Showing 27 changed files with 7,152 additions and 834 deletions.
diff --git a/packages/cactus-plugin-bungee/README.md b/packages/cactus-plugin-bungee/README.md
@@ -0,0 +1,159 @@
+# `@hyperledger/cactus-plugin-bungee`
+
+ 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)
+
+## Summary
+
+- [`@hyperledger/cactus-plugin-bungee`](#hyperledgercactus-plugin-bungee)
+  - [Summary](#summary)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+  - [Architecture](#architecture)
+    - [BUNGEE API](#bungee-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)
+
+Note that at the moment, only logic for Fabric and Besu networks
+
+## Architecture
+
+BUNGEE is a blockchain view generator, serving multiple purposes such as stakeholder-centric snapshots for audits, cross-chain analysis, blockchain migration, and combined on-chain-off-chain analytics.
+
+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.
+
+The plugin stands _behind_ a cacti-ledger-connector, which is used to fetch information from the ledger to create the snapshot.
+
+.......................................
+.            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 API
+
+This plugin uses OpenAPI to generate the API paths.
+Endpoints exposed:
+
+  - CreateViewV1
+
+
+## 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 API. Tests bungee's API and functionality with multiple strategies. 
+
+
+## Usage
+Lets imagine we want bungee 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 pluginBungeeOptions = {
+    keyPair: Secp256k1Keys.generateKeyPairsBuffer(),
+    instanceId: uuidv4(),
+    logLevel,
+};
+const bungee = new PluginBUNGEE(pluginBungeeOptions);
+```
+
+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
+    tF: undefined,          //default to 9999999999999
+    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-plugin instance.
+Each strategy implements the logic to query information from each different ledger (i.e. capture set of asset states), while bungee plugin handles the snapshot and view creation.
+
+For now, strategy-besu requires that solidity smart contracts in besu have a 'getAllAssetsIDs' function and that each function that changed an asset state, emits an event indexing the asset ID (we will introduce an interface soon). Lastly, strategy-fabric also requires that the fabric chaincode includes "GetAllAssetsKey" and "GetAllTxByKey" functions.
+
+Future versions of bungee may include smart contract interfaces for different ledgers.
+
+
+
+## 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/package.json b/packages/cactus-plugin-bungee/package.json
@@ -64,8 +64,13 @@
     "@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"
+    "uuid": "9.0.1",
+    "web3": "1.6.1",
+    "web3-core": "1.6.1"
   },
   "devDependencies": {
     "@types/body-parser": "1.19.4",
@@ -75,7 +80,8 @@
     "@types/tape": "4.13.4",
     "@types/uuid": "9.0.6",
     "express": "4.18.2",
-    "fabric-network": "2.2.20"
+    "fabric-network": "2.2.20",
+    "socket.io": "4.5.4"
   },
   "engines": {
     "node": ">=18",

diff --git a/packages/cactus-plugin-bungee/src/main/typescript/generated/openapi/typescript-axios/api.ts b/packages/cactus-plugin-bungee/src/main/typescript/generated/openapi/typescript-axios/api.ts
@@ -22,6 +22,7 @@ import { DUMMY_BASE_URL, assertParamExists, setApiKeyToObject, setBasicAuthToObj
 import type { RequestArgs } from './base';
 // @ts-ignore
 import { BASE_PATH, COLLECTION_FORMATS, BaseAPI, RequiredError } from './base';
+import { NetworkDetails } from '../../../strategy/obtain-ledger-strategy';
 
 /**
  * 
@@ -34,7 +35,12 @@ export interface CreateViewRequest {
      * @type {string}
      * @memberof CreateViewRequest
      */
-    'x'?: string;
+    'stateIds'?: string[];
+    'tI'?: string;
+    'tF'?: string;
+    'viewID'?: string;
+    'strategyId': string;
+    'networkDetails': NetworkDetails;
 }
 /**
  * 
@@ -47,7 +53,7 @@ export interface CreateViewResponse {
      * @type {string}
      * @memberof CreateViewResponse
      */
-    'y'?: string;
+    'view'?: string;
 }
 
 /**