Skip to content

Commit

Permalink
feat(cactus-plugin-ledger-connector-sawtooth): add new connector plugin
Browse files Browse the repository at this point in the history
- Add new plugin for connecting with sawtooth ledgers.
- New connector is based on already existing sawtooth-socketio connector.
- Currently it supports only watchBlock and connector status endpoints.
- Add new connector to cactus-verifier-client
- Add integration tests in `cactus-test-plugin-ledger-connector-sawtooth`.

Signed-off-by: Michal Bajer <[email protected]>
  • Loading branch information
outSH authored and petermetz committed Nov 2, 2023
1 parent 5185968 commit 65e4715
Show file tree
Hide file tree
Showing 48 changed files with 6,359 additions and 1 deletion.
1 change: 1 addition & 0 deletions .cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
"caio",
"cbdc",
"Cbdc",
"cbor",
"cccg",
"cccs",
"ccep",
Expand Down
24 changes: 24 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -1335,6 +1335,30 @@ jobs:
node-version: v16.14.2
- uses: actions/[email protected]

- id: yarn-cache
name: Restore Yarn Cache
uses: actions/[email protected]
with:
key: ${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
path: ./.yarn/
restore-keys: |
${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
- run: ./tools/ci.sh
cactus-plugin-ledger-connector-sawtooth:
continue-on-error: false
env:
FULL_BUILD_DISABLED: true
JEST_TEST_PATTERN: packages/cactus-plugin-ledger-connector-sawtooth/src/test/typescript/(unit|integration|benchmark)/.*/*.test.ts
JEST_TEST_RUNNER_DISABLED: false
TAPE_TEST_RUNNER_DISABLED: true
needs: build-dev
runs-on: ubuntu-20.04
steps:
- name: Use Node.js v16.14.2
uses: actions/[email protected]
with:
node-version: v16.14.2
- uses: actions/[email protected]
- id: yarn-cache
name: Restore Yarn Cache
uses: actions/[email protected]
Expand Down
5 changes: 5 additions & 0 deletions packages/cactus-plugin-ledger-connector-sawtooth/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
FROM ghcr.io/hyperledger/cactus-cmd-api-server:v1.0.0

ARG NPM_PKG_VERSION=latest

RUN npm i @hyperledger/cactus-plugin-ledger-connector-sawtooth@${NPM_PKG_VERSION} --production
147 changes: 147 additions & 0 deletions packages/cactus-plugin-ledger-connector-sawtooth/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
# `@hyperledger/cactus-plugin-ledger-connector-sawtooth`

This plugin provides `Cacti` a way to interact with Sawtooth networks. Using this we can perform:

- Check plugin and sawtooth node status.
- Monitor new blocks and transactions on the ledger.

## Summary

- [Getting Started](#getting-started)
- [Usage](#usage)
- [SawtoothApiClient](#sawtoothapiclient)
- [Runing the tests](#running-the-tests)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## 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
```

## Usage

Before running the connector please ensure that Sawtooth node is running and that connector will have direct access to it. Access through a proxy is not supported yet (see https://sawtooth.hyperledger.org/docs/1.2/sysadmin_guide/rest_auth_proxy.html).
To use this import public-api and create new **PluginLedgerConnectorSawtooth**.

```typescript
const connector = new PluginLedgerConnectorSawtooth({
instanceId: uuidV4(),
logLevel: testLogLevel,
sawtoothRestApiEndpoint: ledgerRestApi,
watchBlocksPollTime,
});
```

You can make calls through the connector to the plugin API:

```typescript
async getStatus(): Promise<StatusResponseV1>
```

Please note that `deployContract()` and `transact()`, although available to call, **are not implemented and will throw error on runtime!**

## SawtoothApiClient

All connector API endpoints are defined in [open-api specification](./src/main/json/openapi.json). You can use [SawtoothApiClient](./src/main/typescript/api-client) to call remote sawtooth connector functions. It also contain additional utility functions to ease integration.

### REST Functions

See [DefaultApi](./src/main/typescript/generated/openapi/typescript-axios/api.ts) for up-to-date listing of supported endpoints.

- getStatusV1

### Asynchronous Functions (socket.io)

- watchBlocksV1

## Running the tests

To check that all has been installed correctly and that the plugin has no errors run jest test suites.

- Run this command at the project's root:

```sh
npx jest cactus-plugin-ledger-connector-sawtooth
```

### Building/running the container image locally

In the Cactus project root say:

```sh
DOCKER_BUILDKIT=1 docker build -f ./packages/cactus-plugin-ledger-connector-sawtooth/Dockerfile . -t cplcb
```

Build with a specific version of the npm package:

```sh
DOCKER_BUILDKIT=1 docker build --build-arg NPM_PKG_VERSION=0.4.1 -f ./packages/cactus-plugin-ledger-connector-sawtooth/Dockerfile . -t cplcb
```

#### Running the container

Launch container with plugin configuration as an **environment variable**:

```sh
docker run \
--rm \
--publish 3000:3000 \
--publish 4000:4000 \
--env AUTHORIZATION_PROTOCOL='NONE' \
--env AUTHORIZATION_CONFIG_JSON='{}' \
--env PLUGINS='[{"packageName": "@hyperledger/cactus-plugin-ledger-connector-sawtooth", "type": "org.hyperledger.cactus.plugin_import_type.LOCAL", "action": "org.hyperledger.cactus.plugin_import_action.INSTALL", "options": {"rpcApiHttpHost": "http://localhost:8545", "instanceId": "some-unique-sawtooth-connector-instance-id"}}]' \
cplcb
```

Launch container with plugin configuration as a **CLI argument**:

```sh
docker run \
--rm \
--publish 3000:3000 \
--publish 4000:4000 \
cplcb \
./node_modules/@hyperledger/cactus-cmd-api-server/dist/lib/main/typescript/cmd/cactus-api.js \
--authorization-protocol='NONE' \
--authorization-config-json='{}' \
--plugins='[{"packageName": "@hyperledger/cactus-plugin-ledger-connector-sawtooth", "type": "org.hyperledger.cactus.plugin_import_type.LOCAL", "action": "org.hyperledger.cactus.plugin_import_action.INSTALL", "options": {"rpcApiHttpHost": "http://localhost:8545", "instanceId": "some-unique-sawtooth-connector-instance-id"}}]'
```

Launch container with **configuration file** mounted from host machine:

```sh

echo '{"authorizationProtocol":"NONE","authorizationConfigJson":{},"plugins":[{"packageName":"@hyperledger/cactus-plugin-ledger-connector-sawtooth","type":"org.hyperledger.cactus.plugin_import_type.LOCAL","action":"org.hyperledger.cactus.plugin_import_action.INSTALL","options":{"rpcApiHttpHost":"http://localhost:8545","instanceId":"some-unique-sawtooth-connector-instance-id"}}]}' > cactus.json

docker run \
--rm \
--publish 3000:3000 \
--publish 4000:4000 \
--mount type=bind,source="$(pwd)"/cactus.json,target=/cactus.json \
cplcb \
./node_modules/@hyperledger/cactus-cmd-api-server/dist/lib/main/typescript/cmd/cactus-api.js \
--config-file=/cactus.json
```

## Contributing

We welcome contributions to Hyperledger Cactus in many forms, and there’s always plenty to do!

Please review [CONTIRBUTING.md](../../CONTRIBUTING.md) to get started.

## License

This distribution is published under the Apache License Version 2.0 found in the [LICENSE](../../LICENSE) file.

## Acknowledgments
- This plugin uses Sawtooth REST API OpenAPI specification from https://sawtooth.hyperledger.org/docs/1.2/rest_api/openapi/. We did some changes to the original spec in order to simplify request handling (e.g. change type, mark fields as requried, etc...)
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "6.3.0"
}
}
91 changes: 91 additions & 0 deletions packages/cactus-plugin-ledger-connector-sawtooth/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
{
"name": "@hyperledger/cactus-plugin-ledger-connector-sawtooth",
"version": "2.0.0-alpha.2",
"description": "Allows Cactus nodes to connect to a Sawtooth ledger.",
"keywords": [
"Hyperledger",
"Cacti",
"Cactus",
"Integration",
"Blockchain",
"Distributed Ledger Technology"
],
"homepage": "https://github.com/hyperledger/cacti#readme",
"bugs": {
"url": "https://github.com/hyperledger/cacti/issues"
},
"repository": {
"type": "git",
"url": "git+https://github.com/hyperledger/cacti.git"
},
"license": "Apache-2.0",
"author": {
"name": "Hyperledger Cacti Contributors",
"email": "[email protected]",
"url": "https://www.hyperledger.org/use/cacti"
},
"contributors": [
{
"name": "Please add yourself to the list of contributors",
"email": "[email protected]",
"url": "https://example.com"
},
{
"name": "Michal Bajer",
"email": "[email protected]",
"url": "https://www.fujitsu.com/global/"
}
],
"main": "dist/lib/main/typescript/index.js",
"module": "dist/lib/main/typescript/index.js",
"browser": "dist/cactus-plugin-ledger-connector-sawtooth.web.umd.js",
"types": "dist/lib/main/typescript/index.d.ts",
"files": [
"dist/*"
],
"scripts": {
"codegen": "run-p 'codegen:*'",
"codegen:openapi": "npm run generate-sdk",
"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",
"generate-sdk:sawtooth-axios": "openapi-generator-cli generate -i ./src/main/json/sawtooth-openapi.json -g typescript-axios -o ./src/main/typescript/sawtooth-api/ --reserved-words-mappings protected=protected",
"webpack": "npm-run-all webpack:dev",
"webpack:dev": "npm-run-all webpack:dev:node webpack:dev:web",
"webpack:dev:node": "webpack --env=dev --target=node --config ../../webpack.config.js",
"webpack:dev:web": "webpack --env=dev --target=web --config ../../webpack.config.js"
},
"dependencies": {
"@hyperledger/cactus-common": "2.0.0-alpha.2",
"@hyperledger/cactus-core": "2.0.0-alpha.2",
"@hyperledger/cactus-core-api": "2.0.0-alpha.2",
"axios": "1.5.1",
"cbor": "9.0.1",
"rxjs": "7.8.1",
"socket.io-client": "4.5.4"
},
"devDependencies": {
"@hyperledger/cactus-test-tooling": "2.0.0-alpha.2",
"@types/express": "4.17.20",
"@types/uuid": "9.0.6",
"body-parser": "1.20.2",
"express": "4.18.2",
"socket.io": "4.5.4",
"uuid": "9.0.1"
},
"engines": {
"node": ">=16",
"npm": ">=8"
},
"publishConfig": {
"access": "public"
},
"browserMinified": "dist/cactus-plugin-ledger-connector-sawtooth.web.umd.min.js",
"mainMinified": "dist/cactus-plugin-ledger-connector-sawtooth.node.umd.min.js",
"watch": {
"codegen:openapi": {
"patterns": [
"./src/main/json/openapi.json"
]
}
}
}
Loading

0 comments on commit 65e4715

Please sign in to comment.