Skip to content

Commit

Permalink
build(connector-stellar): add a deploy contract endpoint
Browse files Browse the repository at this point in the history 
- Add a Stellar Connector plugin following the same pattern as the **Besu Connector plugin**.
- Add a deploy contract endpoint to the Stellar Connector plugin.

**Initialization remarks:**
Supports a network configuration object to define all integration services that seamlessly
integrate with the Stellar test ledger within the Cacti test tooling.

**Deploy remarks:**
The deploy process supports both the compiled smart contract WASM as well as the on-chain WASM
hash as inputs. This follows the smart contract deployment design on Soroban
(Stellar's smart contract platform). Refer to the Stellar documentation at:
https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/contracts
for further detail on this process.

More details can be found in the `README.md` file under the connector root directory.

Signed-off-by: Fabricius Zatti <fazzatti@gmail.com>
  • Loading branch information
@fazzatti @petermetz
fazzatti authored and petermetz committed Jun 3, 2024
1 parent 81da333 commit e1d86c3
Show file tree
Hide file tree
Showing 21 changed files with 1,246 additions and 265 deletions.
40 changes: 40 additions & 0 deletions .github/workflows/ci.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ jobs:
plugin-ledger-connector-ethereum-changed: ${{ steps.changes.outputs.plugin-ledger-connector-ethereum-changed }}
plugin-ledger-connector-iroha2-changed: ${{ steps.changes.outputs.plugin-ledger-connector-iroha2-changed }}
plugin-ledger-connector-quorum-changed: ${{ steps.changes.outputs.plugin-ledger-connector-quorum-changed }}
plugin-ledger-connector-stellar-changed: ${{ steps.changes.outputs.plugin-ledger-connector-stellar-changed }}
plugin-htlc-coordinator-besu-changed: ${{ steps.changes.outputs.plugin-htlc-coordinator-besu-changed }}
test-tooling-changed: ${{ steps.changes.outputs.test-tooling-changed }}
ghcr-corda-all-in-one-obligation-changed: ${{ steps.changes.outputs.ghcr-corda-all-in-one-obligation-changed }}
Expand Down Expand Up @@ -134,6 +135,15 @@ jobs:
- './packages/cactus-plugin-keychain-memory/**'
# - './.github/workflows/ci.yaml'
plugin-ledger-connector-stellar-changed:
- './packages/cacti-plugin-ledger-connector-stellar/**'
- './packages/cactus-common/**'
- './packages/cactus-core/**'
- './packages/cactus-core-api/**'
- './packages/cactus-test-tooling/**'
- './packages/cactus-plugin-keychain-memory/**'
# - './.github/workflows/ci.yaml'
test-tooling-changed:
- './packages/cactus-test-tooling/**'
- './packages/cactus-common/**'
Expand Down Expand Up @@ -1105,6 +1115,36 @@ jobs:
restore-keys: |
${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
- run: ./tools/ci.sh

cpl-connector-stellar:
continue-on-error: false
needs:
- build-dev
- compute_changed_packages
if: needs.compute_changed_packages.outputs.plugin-ledger-connector-stellar-changed == 'true'
env:
FULL_BUILD_DISABLED: true
JEST_TEST_PATTERN: packages/cacti-plugin-ledger-connector-stellar/src/test/typescript/(unit|integration|benchmark)/.*/*.test.ts
JEST_TEST_RUNNER_DISABLED: false
TAPE_TEST_RUNNER_DISABLED: true
runs-on: ubuntu-22.04
steps:
- name: Use Node.js ${{ env.NODEJS_VERSION }}
uses: actions/setup-node@v4.0.2
with:
node-version: ${{ env.NODEJS_VERSION }}
- uses: actions/checkout@v4.1.1

- id: yarn-cache
name: Restore Yarn Cache
uses: actions/cache@v4.0.1
with:
key: ${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
path: ./.yarn/
restore-keys: |
${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
- run: ./tools/ci.sh


plc-fabric-0:
needs:
Expand Down
128 changes: 101 additions & 27 deletions packages/cacti-plugin-ledger-connector-stellar/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,22 @@
# `@hyperledger/cacti-plugin-ledger-connector-stellar`

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

## 🚧 **Package Under Construction** 🚧

This package is a skeleton for now with no exported modules at all.
Stay tuned for later improvements.

## 🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧
- Deploy Smart-contracts over the network.
- Build and sign transactions. (WIP)
- Invoke smart-contract functions that we have deployed on the network. (WIP)

This plugin provides `Cacti` a way to interact with Stellar networks. Using this we can perform:
* Deploy Smart-contracts over the network.
* Build and sign transactions using different keystores.
* Invoke smart-contract functions that we have deployed on the network.
## Summary

- [Getting Started](#getting-started)
- [Architecture](#architecture)
- [Usage](#usage)
- [Prometheus Exporter](#prometheus-exporter)
- [Runing the tests](#running-the-tests)
- [Built With](#built-with)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [Getting Started](#getting-started)
- [Architecture](#architecture)
- [Usage](#usage)
- [Prometheus Exporter](#prometheus-exporter)
- [Runing the tests](#running-the-tests)
- [Built With](#built-with)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## Getting Started

Expand All @@ -31,7 +25,8 @@ your local machine for development and testing purposes.

### Prerequisites

In the root of the project to install the dependencies execute the command:
In the root of the Cacti project to install the dependencies execute the command:

```sh
npm run enable-corepack
yarn configure
Expand All @@ -40,17 +35,81 @@ yarn configure
### Compiling

In the project root folder, run this command to compile the plugin and create the dist directory:

```sh
yarn tsc
```

### Architecture

TODO
The Stellar Ledger Connector offers a variaty of endpoints to handle specific actions for a given Stellar network.

#### `deploy-contract` endpoint

This endpoint is responsible for deploying smart contracts to Soroban (Stellar's smart contract platform).

**Core Aspects**:

- **Input**: Accepts either a compiled WASM buffer or a WASM hash.
- **WASM Buffer**: Uploads compiled code to Stellar, generates a on-chain WASM hash, then deploys the contract. Refer to the [Stellar documentation](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/contracts) for further detail on this process.
- **WASM Hash**: Directly deploys the contract using the existing WASM hash.
- **Output**: An object containing the on-chain WASM hash and a unique contract ID of the newly deployed instance.

- **Transaction Invocation**: Provides data for assembling and executing the transactions.

### Usage

TODO
#### Initialization

To use this import public-api and create new **PluginFactoryLedgerConnector**. Then use it to create a connector.

```typescript
const factory = new PluginFactoryLedgerConnector({
pluginImportType: PluginImportType.LOCAL,
});
const connector: PluginLedgerConnectorStellar = await factory.create({
networkConfig,
pluginRegistry: new PluginRegistry({}),
instanceId: uuidV4(),
});
```

A key element of the connector intialization is the provided `networkConfig` object. It follows the standard format defined in the open source library [Stellar Plus](https://github.com/CheesecakeLabs/stellar-plus) and can be assembled by the `CustomNet()` function provided by it as well as the most common network environments for Stellar such as the `TestNet()` for Stellar testnet or `FutureNet()` for early features and protocol changes validation.

When using the _Stellar Test Ledger_ provided under the Cacti Test tooling, the network can be assembled using the `CustomNet()` function combined with the test ledger `getNetworkConfiguration()` method. Once the test ledger has been fully started, it exposes the configuration parameters for all its services. See the following example:

```typescript
const stellarTestLedger = new StellarTestLedger({ logLevel });

await stellarTestLedger.start();
const networkConfig = CustomNet(
await stellarTestLedger.getNetworkConfiguration(),
);
```

#### Making Calls

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

```typescript
async deployContract(req: DeployContractV1Request):Promise<DeployContractV1Response>;
```

Call example to deploy a contract:

```typescript
const deployOut = await connector.deployContract({
wasmBuffer: wasmBuffer.toString("base64"),
transactionInvocation: {
header: {
source: deployerAccount.getPublicKey(),
fee: 100,
timeout: 30,
},
signers: [deployerAccount.getSecretKey()],
},
});
```

### Building/running the container image locally

Expand All @@ -61,13 +120,15 @@ DOCKER_BUILDKIT=1 docker build -f ./packages/cacti-plugin-ledger-connector-stell
```

Build with a specific version of the npm package:

```sh
DOCKER_BUILDKIT=1 docker build --build-arg NPM_PKG_VERSION=2.0.0-alpha.2 -f ./packages/cacti-plugin-ledger-connector-stellar/Dockerfile . --tag cplcs --tag cacti-plugin-ledger-connector-stellar
```

#### Running the container

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

```sh
docker run \
--rm \
Expand All @@ -78,6 +139,7 @@ docker run \
```

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

```sh
docker run \
--rm \
Expand All @@ -89,6 +151,7 @@ docker run \
```

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

```sh

echo '[{"packageName": "@hyperledger/cacti-plugin-ledger-connector-stellar", "type": "org.hyperledger.cactus.plugin_import_type.LOCAL", "action": "org.hyperledger.cactus.plugin_import_action.INSTALL", "options": { "instanceId": "some-unique-stellar-connector-instance-id"}}]' > cactus.json
Expand All @@ -107,8 +170,7 @@ docker run \

Don't have a Stellar network on hand to test with? Test or develop against our Stellar All-In-One container!

TODO

TODO (WIP)

## Prometheus Exporter

Expand All @@ -119,7 +181,10 @@ This class creates a prometheus exporter, which scrapes the transactions (total
The prometheus exporter object is initialized in the `PluginLedgerConnectorStellar` class constructor itself, so instantiating the object of the `PluginLedgerConnectorStellar` class, gives access to the exporter object.
You can also initialize the prometheus exporter object seperately and then pass it to the `IPluginLedgerConnectorStellarOptions` interface for `PluginLedgerConnectorStellar` constructor.

`getPrometheusMetricsV1` function returns the prometheus exporter metrics, currently displaying the total transaction count, which currently increments everytime the `transact()` method of the `PluginLedgerConnectorStellar` class is called.
`getPrometheusMetricsV1` function returns the prometheus exporter metrics, currently displaying the total transaction count, which currently increments everytime a Stellar transaction is executed through the connector internal methods. This includes the methods

- `deployContract`
- `runSorobanTransaction()` (_Soon_)

### Prometheus Integration

Expand All @@ -143,17 +208,26 @@ On the prometheus graphical interface (defaulted to http://localhost:9090), choo
### Helper code

###### response.type.ts

This file contains the various responses of the metrics.

###### data-fetcher.ts

This file contains functions encasing the logic to process the data points

###### metrics.ts

This file lists all the prometheus metrics and what they are used for.

## Running the tests

TODO
To check that all has been installed correctly and that the pugin has no errors run the tests:

- Run this command at the project's root:

```sh
yarn jest packages/cacti-plugin-ledger-connector-stellar/
```

## Contributing

Expand All @@ -165,4 +239,4 @@ Please review [CONTIRBUTING.md](../../CONTRIBUTING.md) to get started.

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

## Acknowledgments
## Acknowledgments
9 changes: 7 additions & 2 deletions packages/cacti-plugin-ledger-connector-stellar/package.json
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
{
"name": "@hyperledger/cacti-plugin-ledger-connector-stellar",
"version": "2.0.0-alpha.2",
"private": true,
"description": "Allows Cacti nodes to connect to a Stellar ledger.",
"keywords": [
"Hyperledger",
Expand Down Expand Up @@ -34,6 +33,11 @@
"name": "Peter Somogyvari",
"email": "peter.somogyvari@accenture.com",
"url": "https://accenture.com"
},
{
"name": "Fabricius Zatti",
"email": "fazzatti@gmail.com",
"url": "https://oififo.com"
}
],
"main": "dist/lib/main/typescript/index.js",
Expand Down Expand Up @@ -67,6 +71,7 @@
"run-time-error-cjs": "1.4.0",
"rxjs": "7.8.1",
"socket.io-client-fixed-types": "4.5.4",
"stellar-plus": "0.8.4",
"typescript-optional": "2.0.1"
},
"devDependencies": {
Expand All @@ -86,7 +91,7 @@
"npm": ">=8"
},
"publishConfig": {
"access": "restricted"
"access": "public"
},
"browserMinified": "dist/cacti-plugin-ledger-connector-stellar.web.umd.min.js",
"mainMinified": "dist/cacti-plugin-ledger-connector-stellar.node.umd.min.js",
Expand Down
Loading

0 comments on commit e1d86c3

Please sign in to comment.