Skip to content

Commit ed915cf

Browse files
outSHoutSH
committed
feat(persistence-ethereum): add sample setup scripts, improve documentation
- 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 <[email protected]>
1 parent 9fef336 commit ed915cf

File tree

11 files changed

+497
-89
lines changed

11 files changed

+497
-89
lines changed

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

-1
Original file line numberDiff line numberDiff line change
@@ -1003,7 +1003,6 @@ components:
10031003
- $ref: '#/components/schemas/ContractJsonDefinition'
10041004
- $ref: '#/components/schemas/ContractKeychainDefinition'
10051005
InvokeContractV1Request_contract:
1006-
nullable: false
10071006
oneOf:
10081007
- $ref: '#/components/schemas/DeployedContractJsonDefinition'
10091008
- $ref: '#/components/schemas/ContractKeychainDefinition'

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

+15-32
Original file line numberDiff line numberDiff line change
@@ -210,8 +210,7 @@
210210
"type": "string"
211211
},
212212
"gasConfig": {
213-
"$ref": "#/components/schemas/GasTransactionConfig",
214-
"nullable": false
213+
"$ref": "#/components/schemas/GasTransactionConfig"
215214
}
216215
}
217216
},
@@ -365,8 +364,7 @@
365364
"additionalProperties": false,
366365
"properties": {
367366
"contractJSON": {
368-
"$ref": "#/components/schemas/ContractJSON",
369-
"nullable": false
367+
"$ref": "#/components/schemas/ContractJSON"
370368
}
371369
}
372370
},
@@ -376,8 +374,7 @@
376374
"additionalProperties": false,
377375
"properties": {
378376
"contractJSON": {
379-
"$ref": "#/components/schemas/ContractJSON",
380-
"nullable": false
377+
"$ref": "#/components/schemas/ContractJSON"
381378
},
382379
"contractAddress": {
383380
"type": "string",
@@ -412,12 +409,10 @@
412409
"additionalProperties": false,
413410
"properties": {
414411
"web3SigningCredential": {
415-
"$ref": "#/components/schemas/Web3SigningCredential",
416-
"nullable": false
412+
"$ref": "#/components/schemas/Web3SigningCredential"
417413
},
418414
"transactionConfig": {
419-
"$ref": "#/components/schemas/EthereumTransactionConfig",
420-
"nullable": false
415+
"$ref": "#/components/schemas/EthereumTransactionConfig"
421416
},
422417
"timeoutMs": {
423418
"type": "number",
@@ -443,18 +438,15 @@
443438
"additionalProperties": false,
444439
"properties": {
445440
"web3SigningCredential": {
446-
"$ref": "#/components/schemas/Web3SigningCredential",
447-
"nullable": false
441+
"$ref": "#/components/schemas/Web3SigningCredential"
448442
},
449443
"contract": {
450444
"oneOf": [
451445
{
452-
"$ref": "#/components/schemas/ContractJsonDefinition",
453-
"description": "Send contract ABI directly in the request."
446+
"$ref": "#/components/schemas/ContractJsonDefinition"
454447
},
455448
{
456-
"$ref": "#/components/schemas/ContractKeychainDefinition",
457-
"description": "Read contract definition from the keychain plugin."
449+
"$ref": "#/components/schemas/ContractKeychainDefinition"
458450
}
459451
],
460452
"nullable": false
@@ -466,8 +458,7 @@
466458
"items": {}
467459
},
468460
"gasConfig": {
469-
"$ref": "#/components/schemas/GasTransactionConfig",
470-
"nullable": false
461+
"$ref": "#/components/schemas/GasTransactionConfig"
471462
},
472463
"value": {
473464
"type": "string",
@@ -484,15 +475,12 @@
484475
"contract": {
485476
"oneOf": [
486477
{
487-
"$ref": "#/components/schemas/DeployedContractJsonDefinition",
488-
"description": "Send contract ABI and address directly in the request."
478+
"$ref": "#/components/schemas/DeployedContractJsonDefinition"
489479
},
490480
{
491-
"$ref": "#/components/schemas/ContractKeychainDefinition",
492-
"description": "Read contract definition from the keychain plugin."
481+
"$ref": "#/components/schemas/ContractKeychainDefinition"
493482
}
494-
],
495-
"nullable": false
483+
]
496484
},
497485
"methodName": {
498486
"description": "The name of the contract method to invoke.",
@@ -508,17 +496,13 @@
508496
"items": {}
509497
},
510498
"invocationType": {
511-
"$ref": "#/components/schemas/EthContractInvocationType",
512-
"nullable": false,
513-
"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."
499+
"$ref": "#/components/schemas/EthContractInvocationType"
514500
},
515501
"web3SigningCredential": {
516-
"$ref": "#/components/schemas/Web3SigningCredential",
517-
"nullable": false
502+
"$ref": "#/components/schemas/Web3SigningCredential"
518503
},
519504
"gasConfig": {
520-
"$ref": "#/components/schemas/GasTransactionConfig",
521-
"nullable": false
505+
"$ref": "#/components/schemas/GasTransactionConfig"
522506
},
523507
"value": {
524508
"type": "string"
@@ -599,7 +583,6 @@
599583
"type": "string"
600584
},
601585
"invocationType": {
602-
"description": "Contract invocation method to be performed (send, call, etc...)",
603586
"$ref": "#/components/schemas/EthContractInvocationWeb3Method"
604587
},
605588
"invocationParams": {

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

+15-32
Original file line numberDiff line numberDiff line change
@@ -210,8 +210,7 @@
210210
"type": "string"
211211
},
212212
"gasConfig": {
213-
"$ref": "#/components/schemas/GasTransactionConfig",
214-
"nullable": false
213+
"$ref": "#/components/schemas/GasTransactionConfig"
215214
}
216215
}
217216
},
@@ -365,8 +364,7 @@
365364
"additionalProperties": false,
366365
"properties": {
367366
"contractJSON": {
368-
"$ref": "#/components/schemas/ContractJSON",
369-
"nullable": false
367+
"$ref": "#/components/schemas/ContractJSON"
370368
}
371369
}
372370
},
@@ -376,8 +374,7 @@
376374
"additionalProperties": false,
377375
"properties": {
378376
"contractJSON": {
379-
"$ref": "#/components/schemas/ContractJSON",
380-
"nullable": false
377+
"$ref": "#/components/schemas/ContractJSON"
381378
},
382379
"contractAddress": {
383380
"type": "string",
@@ -412,12 +409,10 @@
412409
"additionalProperties": false,
413410
"properties": {
414411
"web3SigningCredential": {
415-
"$ref": "#/components/schemas/Web3SigningCredential",
416-
"nullable": false
412+
"$ref": "#/components/schemas/Web3SigningCredential"
417413
},
418414
"transactionConfig": {
419-
"$ref": "#/components/schemas/EthereumTransactionConfig",
420-
"nullable": false
415+
"$ref": "#/components/schemas/EthereumTransactionConfig"
421416
},
422417
"timeoutMs": {
423418
"type": "number",
@@ -443,18 +438,15 @@
443438
"additionalProperties": false,
444439
"properties": {
445440
"web3SigningCredential": {
446-
"$ref": "#/components/schemas/Web3SigningCredential",
447-
"nullable": false
441+
"$ref": "#/components/schemas/Web3SigningCredential"
448442
},
449443
"contract": {
450444
"oneOf": [
451445
{
452-
"$ref": "#/components/schemas/ContractJsonDefinition",
453-
"description": "Send contract ABI directly in the request."
446+
"$ref": "#/components/schemas/ContractJsonDefinition"
454447
},
455448
{
456-
"$ref": "#/components/schemas/ContractKeychainDefinition",
457-
"description": "Read contract definition from the keychain plugin."
449+
"$ref": "#/components/schemas/ContractKeychainDefinition"
458450
}
459451
],
460452
"nullable": false
@@ -466,8 +458,7 @@
466458
"items": {}
467459
},
468460
"gasConfig": {
469-
"$ref": "#/components/schemas/GasTransactionConfig",
470-
"nullable": false
461+
"$ref": "#/components/schemas/GasTransactionConfig"
471462
},
472463
"value": {
473464
"type": "string",
@@ -484,15 +475,12 @@
484475
"contract": {
485476
"oneOf": [
486477
{
487-
"$ref": "#/components/schemas/DeployedContractJsonDefinition",
488-
"description": "Send contract ABI and address directly in the request."
478+
"$ref": "#/components/schemas/DeployedContractJsonDefinition"
489479
},
490480
{
491-
"$ref": "#/components/schemas/ContractKeychainDefinition",
492-
"description": "Read contract definition from the keychain plugin."
481+
"$ref": "#/components/schemas/ContractKeychainDefinition"
493482
}
494-
],
495-
"nullable": false
483+
]
496484
},
497485
"methodName": {
498486
"description": "The name of the contract method to invoke.",
@@ -508,17 +496,13 @@
508496
"items": {}
509497
},
510498
"invocationType": {
511-
"$ref": "#/components/schemas/EthContractInvocationType",
512-
"nullable": false,
513-
"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."
499+
"$ref": "#/components/schemas/EthContractInvocationType"
514500
},
515501
"web3SigningCredential": {
516-
"$ref": "#/components/schemas/Web3SigningCredential",
517-
"nullable": false
502+
"$ref": "#/components/schemas/Web3SigningCredential"
518503
},
519504
"gasConfig": {
520-
"$ref": "#/components/schemas/GasTransactionConfig",
521-
"nullable": false
505+
"$ref": "#/components/schemas/GasTransactionConfig"
522506
},
523507
"value": {
524508
"type": "string"
@@ -599,7 +583,6 @@
599583
"type": "string"
600584
},
601585
"invocationType": {
602-
"description": "Contract invocation method to be performed (send, call, etc...)",
603586
"$ref": "#/components/schemas/EthContractInvocationWeb3Method"
604587
},
605588
"invocationParams": {

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

+51-22
Original file line numberDiff line numberDiff line change
@@ -26,44 +26,73 @@ Clone the git repository on your local machine. Follow these instructions that w
2626

2727
### Prerequisites
2828

29+
#### Build
30+
2931
In the root of the project, execute the command to install and build the dependencies. It will also build this persistence plugin:
3032

3133
```sh
3234
yarn run configure
3335
```
3436

35-
### Usage
37+
#### Ethereum Ledger and Connector
3638

37-
Instantiate a new `PluginPersistenceEthereum` instance:
39+
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.
3840

39-
```typescript
40-
import { PluginPersistenceEthereum } from "@hyperledger/cactus-plugin-persistence-ethereum";
41-
import { v4 as uuidv4 } from "uuid";
41+
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).
4242

43-
const persistencePlugin = new PluginPersistenceEthereum({
44-
instanceId: uuidv4(),
45-
apiClient: new EthereumApiClient(apiConfigOptions),
46-
logLevel: "info",
47-
connectionString:
48-
"postgresql://postgres:your-super-secret-and-long-postgres-password@localhost:5432/postgres",
49-
});
43+
#### Supabase Instance
5044

51-
// Initialize the connection to the DB
52-
await persistencePlugin.onPluginInit();
45+
You need a running Supabase instance to serve as a database backend for this plugin.
46+
47+
### Setup Tutorials
48+
49+
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.
50+
51+
#### Sample Setup
52+
53+
Location: [./src/test/typescript/manual/sample-setup.ts](./src/test/typescript/manual/sample-setup.ts)
54+
55+
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.
56+
57+
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.
58+
59+
```shell
60+
npm run sample-setup
61+
```
62+
63+
Custom ledger and supabase can be set with environment variables `ETHEREUM_RPC_WS_HOST` and `SUPABASE_CONNECTION_STRING`:
64+
65+
```shell
66+
ETHEREUM_RPC_WS_HOST=ws://127.0.0.1:8546 SUPABASE_CONNECTION_STRING=postgresql://postgres:[email protected]:5432/postgres npm run sample-setup
67+
```
68+
69+
#### Complete Sample Scenario
70+
71+
Location: [./src/test/typescript/manual/common-setup-methods](./src/test/typescript/manual/common-setup-methods)
72+
73+
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.
74+
75+
By default, the script will try to use our `supabase-all-in-one` instance running on localhost.
76+
77+
```shell
78+
npm run complete-sample-scenario
5379
```
5480

55-
Alternatively, import `PluginFactoryLedgerPersistence` from the plugin package and use it to create a plugin.
81+
Custom supabase can be set with environment variable `SUPABASE_CONNECTION_STRING`:
82+
83+
```shell
84+
SUPABASE_CONNECTION_STRING=postgresql://postgres:[email protected]:5432/postgres npm run complete-sample-scenario
85+
```
86+
87+
### Usage
88+
89+
Instantiate a new `PluginPersistenceEthereum` instance:
5690

5791
```typescript
58-
import { PluginFactoryLedgerPersistence } from "@hyperledger/cactus-plugin-persistence-ethereum";
59-
import { PluginImportType } from "@hyperledger/cactus-core-api";
92+
import { PluginPersistenceEthereum } from "@hyperledger/cactus-plugin-persistence-ethereum";
6093
import { v4 as uuidv4 } from "uuid";
6194

62-
const factory = new PluginFactoryLedgerPersistence({
63-
pluginImportType: PluginImportType.Local,
64-
});
65-
66-
const persistencePlugin = await factory.create({
95+
const persistencePlugin = new PluginPersistenceEthereum({
6796
instanceId: uuidv4(),
6897
apiClient: new EthereumApiClient(apiConfigOptions),
6998
logLevel: "info",

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

+4-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,9 @@
5656
"copy-yarn-lock": "mkdir -p ./dist/lib/ && cp -rfp ../../yarn.lock ./dist/yarn.lock",
5757
"generate-sdk": "run-p 'generate-sdk:*'",
5858
"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",
59-
"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"
59+
"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",
60+
"complete-sample-scenario": "npm run build && node ./dist/lib/test/typescript/manual/complete-sample-scenario.js",
61+
"sample-setup": "npm run build && node ./dist/lib/test/typescript/manual/sample-setup.js"
6062
},
6163
"dependencies": {
6264
"@ethersproject/abi": "5.7.0",
@@ -73,6 +75,7 @@
7375
"web3-validator": "2.0.2"
7476
},
7577
"devDependencies": {
78+
"@hyperledger/cactus-cmd-api-server": "2.0.0-rc.3",
7679
"@hyperledger/cactus-plugin-keychain-memory": "2.0.0-rc.3",
7780
"@hyperledger/cactus-test-geth-ledger": "2.0.0-rc.3",
7881
"@hyperledger/cactus-test-tooling": "2.0.0-rc.3",

0 commit comments

Comments
 (0)