-
Notifications
You must be signed in to change notification settings - Fork 269
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
refactor(cc-tx-visualization): capture transactional data with RxJS
The plugin now utilizes RxJS instead of RabbitMQ in transaction monitoring. ReplaySubjects store and emit observed transactional data to subscribers. fix(cc-tx-visualization): rebase latest version Signed-off-by: Rafael Belchior <rafael.belchior@tecnico.ulisboa.pt> squash! - migrate a test case to Fabric v2.5.6 LTS AIO This is just a snippet of a change from the pair programming call with Bruno, it can be safely squashed, no worries. Signed-off-by: Peter Somogyvari <peter.somogyvari@accenture.com> Signed-off-by: Bruno Mateus <brumat315@gmail.com>
- Loading branch information
1 parent
079e787
commit 4bd50b7
Showing
50 changed files
with
3,461 additions
and
2,064 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| cactus-openapi-spec-plugin-consortium-manual.json | ||
| src/main/typescript/generated/openapi/typescript-axios/.npmignore | ||
| src/test/csv | ||
| src/test/json | ||
| src/test/test-results/*.out |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,118 @@ | ||
| # `@hyperledger/cactus-plugin-cctxviz` | ||
| # `@hyperledger/cactus-plugin-cc-tx-visualization` | ||
|
|
||
| The proposed plugin allows generating process models from arbitrary cross-chain use cases. Currently supports Fabric and Besu. More documentation to come soon. | ||
| The package provides `Hyperledger Cacti` a way to generate process models from arbitrary cross-chain use cases. The implementation follows the paper [Hephaestus](https://www.techrxiv.org/doi/full/10.36227/techrxiv.20718058.v3). | ||
|
|
||
| With this plugin it will be possible to generate cross-chain models from local transactions in different ledgers (currently supports Fabric and Besu), realizing arbitrary cross-chain use cases and allowing operators to monitor their applications. | ||
| Through monitoring, errors like outliers and malicious behavior can be identified, which can enable programmatically stopping attacks (circuit breaker), including bridge hacks. | ||
|
|
||
| ## Summary | ||
|
|
||
| - [`@hyperledger/cactus-plugin-cc-tx-visualization`](#hyperledgercactus-plugin-cc-tx-visualization) | ||
| - [Summary](#summary) | ||
| - [Getting Started](#getting-started) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Architecture](#architecture) | ||
| - [RxJS Transaction Monitoring](#rxjs-transaction-monitoring) | ||
| - [Cross-Chain Model Pipeline](#cross-chain-model-pipeline) | ||
| - [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 | ||
|
|
||
| ### RxJS Transaction Monitoring | ||
|
|
||
| This plugin utilizes RxJS (Reactive Extensions for JavaScript) to monitor transactions issued in Hyperledger Besu and Hyperledger Fabric connectors. | ||
|
|
||
| RxJS provides a powerful framework for asynchronous or callback-based code, each connector maintains an RxJS `ReplaySubject`, named `txSubject`, which acts as a message bus for emitting transaction data. | ||
|
|
||
| - When a transaction is issued in a connector, the `ReplaySubject` stores the value it observes in an internal buffer. This observation is achieved by passing the value to its `next` method. | ||
| - When a new subscriber subscribes to the `txSubject`, it synchronously emits all values in its buffer in a First-In-First-Out (FIFO) manner. This ensures that subscribers receive the most recent transactional data, regardless of when they subscribe. | ||
| - The transactional data emitted includes essential information such as the transaction ID, timestamp, and other parameters, which are necessary for creating transaction receipts within the plugin. | ||
|
|
||
| ### Cross-Chain Model Pipeline | ||
|
|
||
| The plugin employs a structured pipeline to create a cross-chain model from monitored connector transactions: | ||
|
|
||
| 1. **Transaction Emission**: Connectors issue local transactions against their respective target blockchains. Each transaction's data is emitted by the `txSubject` to the subscribers within our plugin. | ||
|
|
||
| 2. **Receipt Polling**: Upon receiving of transactional data, the plugin processes it into transaction receipts. This step involves precessing transactional information received such as transaction IDs, timestamps, and other parameters. | ||
|
|
||
| 3. **Cross-Chain Event Logging**: The processed transaction receipts can then be used to create cross-chain events, forming a cross-chain event log. | ||
|
|
||
| 4. **Cross-Chain Model Updating**: The plugin parses the cross chain event log and updates the cross chain model with the new information received from the connectors. | ||
|
|
||
| ## Running the tests | ||
| - **api-surface.test.ts**: Verifies the successful loading of the library. | ||
| - **cctxviz-basic-test.test.ts**: Conducts the simulation of a transaction without instantiating the connectors, and tests that the plugin monitors, captures, and processes the transactional data and creates a cross-chain event. | ||
| - **cctxviz-persist-cross-chain-log.test.ts**: Tests the plugin's ability to export transactional data, in both CSV and JSON formats, as cross-chain event logs. | ||
| - **cctxviz-generate-use-case-dummy-baseline-events.test.ts**: Conducts a simulation of a series of transactions, exporting the cross-chain event log in CSV and JSON formats, and tests if the cross-chain model is correctly saved. | ||
| - **cctxviz-generate-use-case-dummy-invalid.test.ts**: Tests a simulation of a series of transactions across multiple cases. | ||
| - **initialize-cctxviz-usecase-fabric-besu-6-events.test.ts**: Tests the plugin's ability to effectively monitor, capture, and process transactional data emitted from the RxJS ReplaySubjects in the Fabric and Besu connectors. | ||
|
|
||
| ## Usage | ||
| Let us consider two conectors: one connected to Hyperledger Besu and one connected to Hyperledger Fabric. To monitor cross-chain transactions and create a cross-chain model we should follow the next steps. | ||
|
|
||
| After instantiating the connectors, we instantiate the plugin as follows: | ||
| ```typescript | ||
| let cctxvizOptions: IPluginCcTxVisualizationOptions; | ||
| cctxvizOptions = { | ||
| instanceId: randomUUID(), | ||
| logLevel: logLevel, | ||
| besuTxObservable: besuConnector.getTxSubjectObservable(), | ||
| fabricTxObservable: fabricConnector.getTxSubjectObservable(), | ||
| }; | ||
| cctxViz = new CcTxVisualization(cctxvizOptions); | ||
| ``` | ||
|
|
||
| We set the desired caseID and start monitoring and processing the transactions into transaction receipts: | ||
|
|
||
| ```typescript | ||
| cctxViz.setCaseId("Desired_CaseID"); | ||
| cctxViz.monitorTransactions(); | ||
| ``` | ||
|
|
||
| We can create cross-chain events from processed transaction receipts and add them to the cross-chain event log: | ||
|
|
||
| ```typescript | ||
| await cctxViz.txReceiptToCrossChainEventLogEntry(); | ||
| ``` | ||
|
|
||
| We can export the cross-chain event log to CSV and JSON files: | ||
|
|
||
| ```typescript | ||
| await cctxViz.persistCrossChainLogCsv("output-file-CSV"); | ||
| await cctxViz.persistCrossChainLogJson("output-file-JSON"); | ||
| ``` | ||
|
|
||
| And we can update the cross-chain model with the events created from the transactional data captured: | ||
| ```typescript | ||
| await cctxViz.aggregateCcTx(); | ||
| ``` | ||
|
|
||
| ## 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
packages/cactus-plugin-cc-tx-visualization/src/main/typescript/models/cross-chain-event.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.