diff --git a/packages/cactus-plugin-ledger-connector-besu/README.md b/packages/cactus-plugin-ledger-connector-besu/README.md index c0eb4e6ea8..18e78071dc 100644 --- a/packages/cactus-plugin-ledger-connector-besu/README.md +++ b/packages/cactus-plugin-ledger-connector-besu/README.md @@ -7,6 +7,7 @@ This plugin provides `Cactus` a way to interact with Besu networks. Using this w ## Summary - [Getting Started](#getting-started) + - [Architecture](#architecture) - [Usage](#usage) - [Prometheus Exporter](#prometheus-exporter) - [Runing the tests](#running-the-tests) @@ -34,6 +35,25 @@ In the project root folder, run this command to compile the plugin and create th npm run tsc ``` +### Architecture +The sequence diagrams for various endpoints are mentioned below + +#### run-transaction-endpoint +![run-transaction-endpoint sequence diagram](docs/architecture/images/run-transaction-endpoint.png) +The above diagram shows the sequence diagram of run-transaction-endpoint. User A (One of the many Users) interacts with the API Client which in turn, calls the API server. API server then executes transact() method which is explained in detailed in the subsequent diagrams. +![run-transaction-endpoint transact() method](docs/architecture/images/run-transaction-endpoint-transact.png) +The above diagram shows the sequence diagraom of transact() method of the PluginLedgerConnectorBesu class. The caller to this function, which in reference to the above sequence diagram is API server, sends RunTransactionRequest object as an argument to the transact() method. Based on the type of Web3SigningCredentialType, corresponsing responses are sent back to the caller. +![run-transaction-endpoint transactCactusKeychainRef() method](docs/architecture/images/run-transaction-endpoint-transact-cactuskeychainref.png) +The above diagram shows transactCactusKeychainReference() method being called by the transact() method of the PluginLedgerConnector class when the Web3SigningCredentialType is CACTUSKEYCHAINREF. This method inturn calls transactPrivateKey() which calls the signTransaction() method of web3 library. +![runtransaction-endpoint transactPrivateKey() method](docs/architecture/images/run-transaction-endpoint-transact-privatekey.png) +The above diagram shows transactPrivateKey() method being called by the transact() method of the PluginLedgerConnector class when the Web3SigningCredentialType is PRIVATEKEYHEX. This method then calls the signTransaction() method of the web3 library. +![run-transaction-endpoint transactSigned() method](docs/architecture/images/run-transaction-endpoint-transact-signed.png) +The above diagram shows transactSigned() method being called by the transact() method of the PluginLedgerConnector class when the Web3SigningCredentialType is NONE. This method calls the sendSignedTransaction() of the web3 library and then calls pollForTxReceipt() method. +![run-transaction-endpoint pollForTxReceipt() method](docs/architecture/images/run-transaction-endpoint-transact-pollfortxreceipt.png) +The above diagram shows pollForTxReceipt() method which is called by the transactSigned() method as described in the previous sequence diagram. This method waits for the block confirmation in a loop and then sends the corresponding response back to the caller. + +### Usage + To use this import public-api and create new **PluginFactoryLedgerConnector**. Then use it to create a connector. ```typescript const factory = new PluginFactoryLedgerConnector({ @@ -83,7 +103,7 @@ enum Web3SigningCredentialType { This class creates a prometheus exporter, which scrapes the transactions (total transaction count) for the use cases incorporating the use of Besu connector plugin. -### Usage +### Prometheus Exporter Usage The prometheus exporter object is initialized in the `PluginLedgerConnectorBesu` class constructor itself, so instantiating the object of the `PluginLedgerConnectorBesu` class, gives access to the exporter object. You can also initialize the prometheus exporter object seperately and then pass it to the `IPluginLedgerConnectorBesuOptions` interface for `PluginLedgerConnectoBesu` constructor. diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-cactuskeychainref.png b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-cactuskeychainref.png new file mode 100644 index 0000000000..20647e8258 Binary files /dev/null and b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-cactuskeychainref.png differ diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-pollfortxreceipt.png b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-pollfortxreceipt.png new file mode 100644 index 0000000000..c7d4296abe Binary files /dev/null and b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-pollfortxreceipt.png differ diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-privatekey.png b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-privatekey.png new file mode 100644 index 0000000000..1ff8188248 Binary files /dev/null and b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-privatekey.png differ diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-signed.png b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-signed.png new file mode 100644 index 0000000000..967eb22b71 Binary files /dev/null and b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact-signed.png differ diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact.png b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact.png new file mode 100644 index 0000000000..dc51fe46fd Binary files /dev/null and b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint-transact.png differ diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint.png b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint.png new file mode 100644 index 0000000000..4ad53b872d Binary files /dev/null and b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/images/run-transaction-endpoint.png differ diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-cactuskeychainref.puml b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-cactuskeychainref.puml new file mode 100644 index 0000000000..a9ddd1622f --- /dev/null +++ b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-cactuskeychainref.puml @@ -0,0 +1,33 @@ +@startuml +title Hyperledger Cactus\nSequence Diagram\nRun Transaction Endpoint\ntransactCactusKeychainReference() method + +skinparam sequenceArrowThickness 2 +skinparam roundcorner 20 +skinparam maxmessagesize 120 +skinparam sequenceParticipant underline + +actor "Caller" as caller +participant "transactCactusKeychainReference()" as tckr +participant "transactPrivateKey()" as tpk +participant "web3.eth.accounts.signTransaction()" as weas + +caller-> tckr: req +activate caller +group #LightBlue if web3SigningCredential == CACTUSKEYCHAINREF + activate tckr + tckr -> tpk: [transactionConfig, web3SigningCredential] + activate tpk + tpk -> weas: [transactionConfig, secret] + activate weas + weas --> tpk: return [signedTx] + deactivate weas + group #LightGray if defined: signedTx.rawTransaction + tpk --> tckr: return [req with rawTransaction] + tckr --> caller : return {transactionConfig, web3SigningCredential, consistencyStrategy} as resBody + deactivate tckr + else #LightCoral + tpk --> tckr: throw Error: Failed to sign eth transaction. signedTransaction.rawTransaction is blank after .signTransaction() + end + deactivate tpk +end +@enduml \ No newline at end of file diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-pollfortxreceipt.puml b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-pollfortxreceipt.puml new file mode 100644 index 0000000000..85c4727fd6 --- /dev/null +++ b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-pollfortxreceipt.puml @@ -0,0 +1,35 @@ +@startuml Sequence Diagram - transact method + +title Hyperledger Cactus\nSequence Diagram\nRun Transaction Endpoint\npollForTxReceipt() method + +skinparam sequenceArrowThickness 2 +skinparam roundcorner 20 +skinparam maxmessagesize 100 +skinparam sequenceParticipant underline + +actor "Caller" as caller +participant "pollForTxReceipt()" as pftr +participant "web3.eth.getTransactionReceipt" as wegt + +caller -> pftr: txHash, consistencyStrategy +activate caller +group #Orange + activate pftr + pftr -> wegt: + activate wegt + loop #LightGreen until confirmationCount >= \n consistencyStrategy.blockConfirmations + wegt --> pftr: txReceipt + deactivate wegt + end loop + + group #LightGreen if defined: txReceipt + pftr --> caller: txReceipt + else #LightCoral + pftr --> caller: Timed out + deactivate pftr + end +end +deactivate caller + + +@enduml \ No newline at end of file diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-privatekey.puml b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-privatekey.puml new file mode 100644 index 0000000000..8b2ddbd128 --- /dev/null +++ b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-privatekey.puml @@ -0,0 +1,30 @@ +@startuml Sequence Diagram - transact method + +title Hyperledger Cactus\nSequence Diagram\nRun Transaction Endpoint\ntransactPrivateKey() method + +skinparam sequenceArrowThickness 2 +skinparam roundcorner 20 +skinparam maxmessagesize 120 +skinparam sequenceParticipant underline + +actor "Caller" as caller +participant "transactPrivateKey()" as tpk +participant "web3.eth.accounts.signTransaction()" as weas + +caller -> tpk: req +activate caller +alt #LightGreen web3SigningCredential == PRIVATEKEYHEX + group #LightGray if defined: signedTx.rawTransaction + activate tpk + tpk -> weas: [transactionConfig, secret] + activate weas + weas --> tpk: return [signedTx] + deactivate weas + tpk --> caller: return [req with rawTransaction] as resBody + else #LightCoral + tpk --> caller: throw Error: Failed to sign eth transaction. signedTransaction.rawTransaction is blank after .signTransaction() + deactivate tpk + end +end + +@enduml diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-signed.puml b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-signed.puml new file mode 100644 index 0000000000..7c40ebcc00 --- /dev/null +++ b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact-signed.puml @@ -0,0 +1,35 @@ +@startuml Sequence Diagram - transact method + +title Hyperledger Cactus\nSequence Diagram\nRun Transaction Endpoint\ntransactSigned() method + +skinparam sequenceArrowThickness 2 +skinparam roundcorner 20 +skinparam maxmessagesize 120 +skinparam sequenceParticipant underline + +actor "Caller" as caller +participant "transactSigned()" as ts +participant "web3.eth.sendSignedTransaction()" as wesst + +caller -> ts: req +activate caller +group #e6e632 if web3SigningCredential == NONE + activate ts + ts -> wesst: rawTransaction + activate wesst + wesst --> ts: txPoolReceipt + deactivate wesst + group #ecec66 if ReceiptType == NODETXPOOLACK + ts --> caller: returns [txPoolReceipt] as resBody + else #f2f299 ReceiptType == LEDGERBLOCKACK + ts -> ts: pollForTxReceipt(txHash, consistencyStrategy) + ts --> caller: return [ledgerReceipt as transactionReceipt] as resBody + else #LightCoral + ts --> caller: throw Error: Unrecognized ReceiptType + deactivate ts + end +end +deactivate caller + + +@enduml diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact.puml b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact.puml new file mode 100644 index 0000000000..c8efaf061a --- /dev/null +++ b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint-transact.puml @@ -0,0 +1,40 @@ +@startuml +title Hyperledger Cactus\nSequence Diagram\nRun Transaction Endpoint\ntransact() method + +skinparam sequenceArrowThickness 2 +skinparam roundcorner 20 +skinparam maxmessagesize 120 +skinparam sequenceParticipant underline + +actor "Caller" as caller +participant "PluginLedgerConnectorBesu" as t << (C,#ADD1B2) class >> + +autoactivate on + +activate caller +caller -> t: transact(RunTransactionRequest) + +alt #LightBlue web3SigningCredential == CACTUSKEYCHAINREF + t -> t: transactCactusKeychainRef(RunTransactionRequest) + return RunTransactionResponse + t --> caller: return RunTransactionResponse +else #LightGreen web3SigningCredential == PRIVATEKEYHEX + group #LightGray if defined: signedTx.rawTransaction + t -> t: transactPrivateKey(RunTransactionRequest) + return RunTransactionResponse + t --> caller: return RunTransactionResponse + else #LightCoral + t --> caller: throw Error: Failed to sign eth transaction. signedTransaction.rawTransaction is blank after .signTransaction() + end +else #e6e632 web3SigningCredential == NONE + group #LightGray if defined: req.transactionConfig.rawTransaction + t -> t: transactSigned(RunTransactionRequest) + return RunTransactionResponse + t --> caller: return RunTransactionResponse + else #LightCoral + t --> caller: throw Error: Expected pre-signed raw transaction + end +else #LightCoral default + t --> caller: throw Error: Unrecognized Web3SigningCredentialType +end +@enduml \ No newline at end of file diff --git a/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint.puml b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint.puml new file mode 100644 index 0000000000..42b3b0ba6b --- /dev/null +++ b/packages/cactus-plugin-ledger-connector-besu/docs/architecture/run-transaction-endpoint.puml @@ -0,0 +1,29 @@ +@startuml Sequence Diagram - Transaction + +title Hyperledger Cactus\nSequence Diagram\nRun Transaction Endpoint + +skinparam sequenceArrowThickness 2 +skinparam roundcorner 20 +skinparam maxmessagesize 120 +skinparam sequenceParticipant underline + +box "Users" #LightBlue +actor "User A" as a +end box + +box "Hyperledger Cactus" #LightGray +entity "API Client" as apic +entity "API Server" as apis +end box + +box "Ledger Connector" #LightGreen +database "Besu" as besucon +end box + +a --> apic : Tx Besu Ledger +apic --> apis: Request +apis --> besucon: transact() +besucon --> apis: Response +apis --> apic: Formatted Response + +@enduml