Skip to content

Commit

Permalink
feat(persistence-ethereum): add sample setup scripts, improve documen…
Browse files Browse the repository at this point in the history
…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 <[email protected]>
  • Loading branch information
outSH committed Aug 14, 2024
1 parent 9fef336 commit ed915cf
Show file tree
Hide file tree
Showing 11 changed files with 497 additions and 89 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,7 @@
"type": "string"
},
"gasConfig": {
"$ref": "#/components/schemas/GasTransactionConfig",
"nullable": false
"$ref": "#/components/schemas/GasTransactionConfig"
}
}
},
Expand Down Expand Up @@ -365,8 +364,7 @@
"additionalProperties": false,
"properties": {
"contractJSON": {
"$ref": "#/components/schemas/ContractJSON",
"nullable": false
"$ref": "#/components/schemas/ContractJSON"
}
}
},
Expand All @@ -376,8 +374,7 @@
"additionalProperties": false,
"properties": {
"contractJSON": {
"$ref": "#/components/schemas/ContractJSON",
"nullable": false
"$ref": "#/components/schemas/ContractJSON"
},
"contractAddress": {
"type": "string",
Expand Down Expand Up @@ -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",
Expand All @@ -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
Expand All @@ -466,8 +458,7 @@
"items": {}
},
"gasConfig": {
"$ref": "#/components/schemas/GasTransactionConfig",
"nullable": false
"$ref": "#/components/schemas/GasTransactionConfig"
},
"value": {
"type": "string",
Expand All @@ -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.",
Expand All @@ -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"
Expand Down Expand Up @@ -599,7 +583,6 @@
"type": "string"
},
"invocationType": {
"description": "Contract invocation method to be performed (send, call, etc...)",
"$ref": "#/components/schemas/EthContractInvocationWeb3Method"
},
"invocationParams": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,7 @@
"type": "string"
},
"gasConfig": {
"$ref": "#/components/schemas/GasTransactionConfig",
"nullable": false
"$ref": "#/components/schemas/GasTransactionConfig"
}
}
},
Expand Down Expand Up @@ -365,8 +364,7 @@
"additionalProperties": false,
"properties": {
"contractJSON": {
"$ref": "#/components/schemas/ContractJSON",
"nullable": false
"$ref": "#/components/schemas/ContractJSON"
}
}
},
Expand All @@ -376,8 +374,7 @@
"additionalProperties": false,
"properties": {
"contractJSON": {
"$ref": "#/components/schemas/ContractJSON",
"nullable": false
"$ref": "#/components/schemas/ContractJSON"
},
"contractAddress": {
"type": "string",
Expand Down Expand Up @@ -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",
Expand All @@ -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
Expand All @@ -466,8 +458,7 @@
"items": {}
},
"gasConfig": {
"$ref": "#/components/schemas/GasTransactionConfig",
"nullable": false
"$ref": "#/components/schemas/GasTransactionConfig"
},
"value": {
"type": "string",
Expand All @@ -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.",
Expand All @@ -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"
Expand Down Expand Up @@ -599,7 +583,6 @@
"type": "string"
},
"invocationType": {
"description": "Contract invocation method to be performed (send, call, etc...)",
"$ref": "#/components/schemas/EthContractInvocationWeb3Method"
},
"invocationParams": {
Expand Down
73 changes: 51 additions & 22 deletions packages/cactus-plugin-persistence-ethereum/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,44 +26,73 @@ 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 EthereumApiClient(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:[email protected]: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:[email protected]: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 EthereumApiClient(apiConfigOptions),
logLevel: "info",
Expand Down
5 changes: 4 additions & 1 deletion packages/cactus-plugin-persistence-ethereum/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down
Loading

0 comments on commit ed915cf

Please sign in to comment.