feat(persistence-ethereum): add sample setup scripts, improve documen…

…tation

- Fix ethereum connector openapi validation errors (mostly remove nullable
    from reference fields).
- Add sample setup scripts. Simple can be used to run persistence againsy
    already running ethereum ledger, complete will setup entire environment
    and run some basic operations to generate sample data.
- Improve documentation to include these new scripts and how to use them, fix
    smaller issues.

Signed-off-by: Michal Bajer <michal.bajer@fujitsu.com>

packages/cactus-plugin-ledger-connector-ethereum/src/main/go/generated/openapi/go-client/api/openapi.yaml

@@ -1003,7 +1003,6 @@ components:
       - $ref: '#/components/schemas/ContractJsonDefinition'
       - $ref: '#/components/schemas/ContractKeychainDefinition'
     InvokeContractV1Request_contract:
-      nullable: false
       oneOf:
       - $ref: '#/components/schemas/DeployedContractJsonDefinition'
       - $ref: '#/components/schemas/ContractKeychainDefinition'

packages/cactus-plugin-ledger-connector-ethereum/src/main/json/openapi.json

@@ -210,8 +210,7 @@
             "type": "string"
           },
           "gasConfig": {
-            "$ref": "#/components/schemas/GasTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/GasTransactionConfig"
           }
         }
       },
@@ -365,8 +364,7 @@
         "additionalProperties": false,
         "properties": {
           "contractJSON": {
-            "$ref": "#/components/schemas/ContractJSON",
-            "nullable": false
+            "$ref": "#/components/schemas/ContractJSON"
           }
         }
       },
@@ -376,8 +374,7 @@
         "additionalProperties": false,
         "properties": {
           "contractJSON": {
-            "$ref": "#/components/schemas/ContractJSON",
-            "nullable": false
+            "$ref": "#/components/schemas/ContractJSON"
           },
           "contractAddress": {
             "type": "string",
@@ -412,12 +409,10 @@
         "additionalProperties": false,
         "properties": {
           "web3SigningCredential": {
-            "$ref": "#/components/schemas/Web3SigningCredential",
-            "nullable": false
+            "$ref": "#/components/schemas/Web3SigningCredential"
           },
           "transactionConfig": {
-            "$ref": "#/components/schemas/EthereumTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/EthereumTransactionConfig"
           },
           "timeoutMs": {
             "type": "number",
@@ -443,18 +438,15 @@
         "additionalProperties": false,
         "properties": {
           "web3SigningCredential": {
-            "$ref": "#/components/schemas/Web3SigningCredential",
-            "nullable": false
+            "$ref": "#/components/schemas/Web3SigningCredential"
           },
           "contract": {
             "oneOf": [
               {
-                "$ref": "#/components/schemas/ContractJsonDefinition",
-                "description": "Send contract ABI directly in the request."
+                "$ref": "#/components/schemas/ContractJsonDefinition"
               },
               {
-                "$ref": "#/components/schemas/ContractKeychainDefinition",
-                "description": "Read contract definition from the keychain plugin."
+                "$ref": "#/components/schemas/ContractKeychainDefinition"
               }
             ],
             "nullable": false
@@ -466,8 +458,7 @@
             "items": {}
           },
           "gasConfig": {
-            "$ref": "#/components/schemas/GasTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/GasTransactionConfig"
           },
           "value": {
             "type": "string",
@@ -484,15 +475,12 @@
           "contract": {
             "oneOf": [
               {
-                "$ref": "#/components/schemas/DeployedContractJsonDefinition",
-                "description": "Send contract ABI and address directly in the request."
+                "$ref": "#/components/schemas/DeployedContractJsonDefinition"
               },
               {
-                "$ref": "#/components/schemas/ContractKeychainDefinition",
-                "description": "Read contract definition from the keychain plugin."
+                "$ref": "#/components/schemas/ContractKeychainDefinition"
               }
-            ],
-            "nullable": false
+            ]
           },
           "methodName": {
             "description": "The name of the contract method to invoke.",
@@ -508,17 +496,13 @@
             "items": {}
           },
           "invocationType": {
-            "$ref": "#/components/schemas/EthContractInvocationType",
-            "nullable": false,
-            "description": "Indicates wether it is a CALL or a SEND type of  invocation where only SEND ends up creating an actual transaction on the ledger."
+            "$ref": "#/components/schemas/EthContractInvocationType"
           },
           "web3SigningCredential": {
-            "$ref": "#/components/schemas/Web3SigningCredential",
-            "nullable": false
+            "$ref": "#/components/schemas/Web3SigningCredential"
           },
           "gasConfig": {
-            "$ref": "#/components/schemas/GasTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/GasTransactionConfig"
           },
           "value": {
             "type": "string"
@@ -599,7 +583,6 @@
             "type": "string"
           },
           "invocationType": {
-            "description": "Contract invocation method to be performed (send, call, etc...)",
             "$ref": "#/components/schemas/EthContractInvocationWeb3Method"
           },
           "invocationParams": {

packages/cactus-plugin-ledger-connector-ethereum/src/main/json/openapi.tpl.json

@@ -210,8 +210,7 @@
             "type": "string"
           },
           "gasConfig": {
-            "$ref": "#/components/schemas/GasTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/GasTransactionConfig"
           }
         }
       },
@@ -365,8 +364,7 @@
         "additionalProperties": false,
         "properties": {
           "contractJSON": {
-            "$ref": "#/components/schemas/ContractJSON",
-            "nullable": false
+            "$ref": "#/components/schemas/ContractJSON"
           }
         }
       },
@@ -376,8 +374,7 @@
         "additionalProperties": false,
         "properties": {
           "contractJSON": {
-            "$ref": "#/components/schemas/ContractJSON",
-            "nullable": false
+            "$ref": "#/components/schemas/ContractJSON"
           },
           "contractAddress": {
             "type": "string",
@@ -412,12 +409,10 @@
         "additionalProperties": false,
         "properties": {
           "web3SigningCredential": {
-            "$ref": "#/components/schemas/Web3SigningCredential",
-            "nullable": false
+            "$ref": "#/components/schemas/Web3SigningCredential"
           },
           "transactionConfig": {
-            "$ref": "#/components/schemas/EthereumTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/EthereumTransactionConfig"
           },
           "timeoutMs": {
             "type": "number",
@@ -443,18 +438,15 @@
         "additionalProperties": false,
         "properties": {
           "web3SigningCredential": {
-            "$ref": "#/components/schemas/Web3SigningCredential",
-            "nullable": false
+            "$ref": "#/components/schemas/Web3SigningCredential"
           },
           "contract": {
             "oneOf": [
               {
-                "$ref": "#/components/schemas/ContractJsonDefinition",
-                "description": "Send contract ABI directly in the request."
+                "$ref": "#/components/schemas/ContractJsonDefinition"
               },
               {
-                "$ref": "#/components/schemas/ContractKeychainDefinition",
-                "description": "Read contract definition from the keychain plugin."
+                "$ref": "#/components/schemas/ContractKeychainDefinition"
               }
             ],
             "nullable": false
@@ -466,8 +458,7 @@
             "items": {}
           },
           "gasConfig": {
-            "$ref": "#/components/schemas/GasTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/GasTransactionConfig"
           },
           "value": {
             "type": "string",
@@ -484,15 +475,12 @@
           "contract": {
             "oneOf": [
               {
-                "$ref": "#/components/schemas/DeployedContractJsonDefinition",
-                "description": "Send contract ABI and address directly in the request."
+                "$ref": "#/components/schemas/DeployedContractJsonDefinition"
               },
               {
-                "$ref": "#/components/schemas/ContractKeychainDefinition",
-                "description": "Read contract definition from the keychain plugin."
+                "$ref": "#/components/schemas/ContractKeychainDefinition"
               }
-            ],
-            "nullable": false
+            ]
           },
           "methodName": {
             "description": "The name of the contract method to invoke.",
@@ -508,17 +496,13 @@
             "items": {}
           },
           "invocationType": {
-            "$ref": "#/components/schemas/EthContractInvocationType",
-            "nullable": false,
-            "description": "Indicates wether it is a CALL or a SEND type of  invocation where only SEND ends up creating an actual transaction on the ledger."
+            "$ref": "#/components/schemas/EthContractInvocationType"
           },
           "web3SigningCredential": {
-            "$ref": "#/components/schemas/Web3SigningCredential",
-            "nullable": false
+            "$ref": "#/components/schemas/Web3SigningCredential"
           },
           "gasConfig": {
-            "$ref": "#/components/schemas/GasTransactionConfig",
-            "nullable": false
+            "$ref": "#/components/schemas/GasTransactionConfig"
           },
           "value": {
             "type": "string"
@@ -599,7 +583,6 @@
             "type": "string"
           },
           "invocationType": {
-            "description": "Contract invocation method to be performed (send, call, etc...)",
             "$ref": "#/components/schemas/EthContractInvocationWeb3Method"
           },
           "invocationParams": {

packages/cactus-plugin-persistence-ethereum/README.md

@@ -26,46 +26,75 @@ Clone the git repository on your local machine. Follow these instructions that w
 
 ### Prerequisites
 
+#### Build
+
 In the root of the project, execute the command to install and build the dependencies. It will also build this persistence plugin:
 
 ```sh
 yarn run configure
 ```
 
-### Usage
+#### Ethereum Ledger and Connector
 
-Instantiate a new `PluginPersistenceEthereum` instance:
+This plugin requires a running Ethereum ledger that you want to persist to a database. For testing purposes, you can use our [test geth-all-in-one Docker image](../../tools/docker/geth-all-in-one/README.md). Make sure you have the JSON-RPC WS address ready.
 
-```typescript
-import { PluginPersistenceEthereum } from "@hyperledger/cactus-plugin-persistence-ethereum";
-import { v4 as uuidv4 } from "uuid";
+Once you have an Ethereum ledger ready, you need to start the [Ethereum Cacti Connector](../cactus-plugin-ledger-connector-ethereum/README.md). We recommend running the connector on the same ApiServer instance as the persistence plugin for better performance and reduced network overhead. See the connector package README for more instructions, or check out the [setup sample scripts](./src/test/typescript/manual).
 
-const persistencePlugin = new PluginPersistenceEthereum({
-  instanceId: uuidv4(),
-  apiClient: new SocketIOApiClient(apiConfigOptions),
-  logLevel: "info",
-  connectionString:
-    "postgresql://postgres:your-super-secret-and-long-postgres-password@localhost:5432/postgres",
-});
+#### Supabase Instance
 
-// Initialize the connection to the DB
-await persistencePlugin.onPluginInit();
+You need a running Supabase instance to serve as a database backend for this plugin.
+
+### Setup Tutorials
+
+We've created some sample scripts to help you get started quickly. All the steps have detailed comments on it so you can quickly understand the code.
+
+#### Sample Setup
+
+Location: [./src/test/typescript/manual/sample-setup.ts](./src/test/typescript/manual/sample-setup.ts)
+
+This sample script can be used to set up `ApiServer` with the Ethereum connector and persistence plugins to monitor and store ledger data in a database. You need to have a ledger running before executing this script. You can add custom code (e.g., to specify tokens to be monitored) after the comment `CUSTOM CODE GOES HERE !!!!` in the script file.
+
+By default, the script will try to use a localhost Ethereum ledger (`ws://127.0.0.1:8546`) and our `supabase-all-in-one` instance running on localhost.
+
+```shell
+npm run sample-setup
+```
+
+Custom ledger and supabase can be set with environment variables `ETHEREUM_RPC_WS_HOST` and `SUPABASE_CONNECTION_STRING`:
+
+```shell
+ETHEREUM_RPC_WS_HOST=ws://127.0.0.1:8546 SUPABASE_CONNECTION_STRING=postgresql://postgres:your-super-secret-and-long-postgres-password@127.0.0.1:5432/postgres npm run sample-setup
+```
+
+#### Complete Sample Scenario
+
+Location: [./src/test/typescript/manual/common-setup-methods](./src/test/typescript/manual/common-setup-methods)
+
+This script starts the test Ethereum ledger for you, deploys a sample ERC721 contract, and mints some tokens. Then it synchronizes everything to a database and monitors for all new blocks. This script can also be used for manual, end-to-end tests of a plugin.
+
+By default, the script will try to use our `supabase-all-in-one` instance running on localhost.
+
+```shell
+npm run complete-sample-scenario
 ```
 
-Alternatively, import `PluginFactoryLedgerPersistence` from the plugin package and use it to create a plugin.
+Custom supabase can be set with environment variable `SUPABASE_CONNECTION_STRING`:
+
+```shell
+SUPABASE_CONNECTION_STRING=postgresql://postgres:your-super-secret-and-long-postgres-password@127.0.0.1:5432/postgres npm run complete-sample-scenario
+```
+
+### Usage
+
+Instantiate a new `PluginPersistenceEthereum` instance:
 
 ```typescript
-import { PluginFactoryLedgerPersistence } from "@hyperledger/cactus-plugin-persistence-ethereum";
-import { PluginImportType } from "@hyperledger/cactus-core-api";
+import { PluginPersistenceEthereum } from "@hyperledger/cactus-plugin-persistence-ethereum";
 import { v4 as uuidv4 } from "uuid";
 
-const factory = new PluginFactoryLedgerPersistence({
-  pluginImportType: PluginImportType.Local,
-});
-
-const persistencePlugin = await factory.create({
+const persistencePlugin = new PluginPersistenceEthereum({
   instanceId: uuidv4(),
-  apiClient: new SocketIOApiClient(apiConfigOptions),
+  apiClient: new EthereumApiClient(apiConfigOptions),
   logLevel: "info",
   connectionString:
     "postgresql://postgres:your-super-secret-and-long-postgres-password@localhost:5432/postgres",

packages/cactus-plugin-persistence-ethereum/package.json

@@ -56,7 +56,9 @@
     "copy-yarn-lock": "mkdir -p ./dist/lib/ && cp -rfp ../../yarn.lock ./dist/yarn.lock",
     "generate-sdk": "run-p 'generate-sdk:*'",
     "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",
-    "generate-sdk:go": "openapi-generator-cli generate -i ./src/main/json/openapi.json -g go -o ./src/main/go/generated/openapi/go-client/ --git-user-id hyperledger --git-repo-id $(echo $npm_package_name | replace @hyperledger/ \"\" -z)/src/main/go/generated/openapi/go-client --package-name $(echo $npm_package_name | replace @hyperledger/ \"\" -z)  --reserved-words-mappings protected=protected --ignore-file-override ../../openapi-generator-ignore"
+    "generate-sdk:go": "openapi-generator-cli generate -i ./src/main/json/openapi.json -g go -o ./src/main/go/generated/openapi/go-client/ --git-user-id hyperledger --git-repo-id $(echo $npm_package_name | replace @hyperledger/ \"\" -z)/src/main/go/generated/openapi/go-client --package-name $(echo $npm_package_name | replace @hyperledger/ \"\" -z)  --reserved-words-mappings protected=protected --ignore-file-override ../../openapi-generator-ignore",
+    "complete-sample-scenario": "npm run build && node ./dist/lib/test/typescript/manual/complete-sample-scenario.js",
+    "sample-setup": "npm run build && node ./dist/lib/test/typescript/manual/sample-setup.js"
   },
   "dependencies": {
     "@ethersproject/abi": "5.7.0",
@@ -73,6 +75,7 @@
     "web3-validator": "2.0.2"
   },
   "devDependencies": {
+    "@hyperledger/cactus-cmd-api-server": "2.0.0-rc.3",
     "@hyperledger/cactus-plugin-keychain-memory": "2.0.0-rc.3",
     "@hyperledger/cactus-test-geth-ledger": "2.0.0-rc.3",
     "@hyperledger/cactus-test-tooling": "2.0.0-rc.3",