build(connector-stellar): add a deploy contract endpoint

- 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 <[email protected]>
hyperledger-cacti · Jun 3, 2024 · d29f769 · d29f769
1 parent 81da333
commit d29f769
Show file tree

Hide file tree

Showing 21 changed files with 1,246 additions and 265 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -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 }}
@@ -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/**'
@@ -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/[email protected]
+        with:
+          node-version: ${{ env.NODEJS_VERSION }}
+      - 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
+
 
   plc-fabric-0:
     needs:

diff --git a/packages/cacti-plugin-ledger-connector-stellar/README.md b/packages/cacti-plugin-ledger-connector-stellar/README.md
@@ -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
 
@@ -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
@@ -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
 
@@ -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 \
@@ -78,6 +139,7 @@ docker run \
 ```
 
 Launch container with plugin configuration as a **CLI argument**:
+
 ```sh
 docker run \
   --rm \
@@ -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
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
diff --git a/packages/cacti-plugin-ledger-connector-stellar/package.json b/packages/cacti-plugin-ledger-connector-stellar/package.json
@@ -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",
@@ -34,6 +33,11 @@
       "name": "Peter Somogyvari",
       "email": "[email protected]",
       "url": "https://accenture.com"
+    },
+    {
+      "name": "Fabricius Zatti",
+      "email": "[email protected]",
+      "url": "https://oififo.com"
     }
   ],
   "main": "dist/lib/main/typescript/index.js",
@@ -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": {
@@ -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",