build(connector-stellar): add skeleton for future Stellar connector

1. The diff is already quite large so I've decided to start with a smaller pull request that is easier to review. Basic functionality is missing from the connector because of the latter. 2. The build is confirmed to be working, so is code generation and tests. 3. We don't yet have a `StellarTestLedger` class in the test-utils package and so we can't yet implement end to end testing but once that gets added we'll be ready to go. 4. For now the public-api.ts and the index.ts and index.web.ts files are not exporting anything so that we adhere to semantic versioning principles in that we won't be doing any breaking changes with the sub-sequent pull requests since there was nothing exported and nothing is unbreakable. 5. For now the package is set to private: true and the "access" within `publishConfig` is set to restricted. Signed-off-by: Peter Somogyvari <[email protected]>
hyperledger-cacti · May 2, 2024 · 86fcc7c · 86fcc7c
1 parent 6be6447
commit 86fcc7c
Show file tree

Hide file tree

Showing 31 changed files with 1,787 additions and 0 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -44,6 +44,7 @@
         "couchdb",
         "COUCHDBADDRESS",
         "COUCHDBCONFIG",
+        "cplcs",
         "Creds",
         "Crpc",
         "data",

diff --git a/packages/cacti-plugin-ledger-connector-stellar/Dockerfile b/packages/cacti-plugin-ledger-connector-stellar/Dockerfile
@@ -0,0 +1,5 @@
+FROM ghcr.io/hyperledger/cactus-cmd-api-server:2024-03-18-8ddc02d
+
+ARG NPM_PKG_VERSION=latest
+
+RUN npm i @hyperledger/cacti-plugin-ledger-connector-stellar@${NPM_PKG_VERSION} --production
diff --git a/packages/cacti-plugin-ledger-connector-stellar/README.md b/packages/cacti-plugin-ledger-connector-stellar/README.md
@@ -0,0 +1,168 @@
+# `@hyperledger/cacti-plugin-ledger-connector-stellar`
+
+
+## 🚧 **Package Under Construction** 🚧
+
+This package is a skeleton for now with no exported modules at all.
+Stay tuned for later improvements.
+
+## 🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧
+
+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
+
+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 enable-corepack
+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
+
+### Usage
+
+TODO
+
+### Building/running the container image locally
+
+In the Cacti project root say:
+
+```sh
+DOCKER_BUILDKIT=1 docker build -f ./packages/cacti-plugin-ledger-connector-stellar/Dockerfile . --tag cplcs --tag cacti-plugin-ledger-connector-stellar
+```
+
+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 \
+  --publish 3000:3000 \
+  --publish 4000:4000 \
+  --env PLUGINS='[{"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"}}]' \
+  cplcs
+```
+
+Launch container with plugin configuration as a **CLI argument**:
+```sh
+docker run \
+  --rm \
+  --publish 3000:3000 \
+   --publish 4000:4000 \
+  cplcs \
+    ./node_modules/.bin/cactusapi \
+    --plugins='[{"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"}}]'
+```
+
+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
+
+docker run \
+  --rm \
+  --publish 3000:3000 \
+  --publish 4000:4000 \
+  --mount type=bind,source="$(pwd)"/cactus.json,target=/cactus.json \
+  cplcs \
+    ./node_modules/.bin/cactusapi \
+    --config-file=/cactus.json
+```
+
+#### Testing API calls with the container
+
+Don't have a Stellar network on hand to test with? Test or develop against our Stellar All-In-One container!
+
+TODO
+
+
+## Prometheus Exporter
+
+This class creates a prometheus exporter, which scrapes the transactions (total transaction count) for the use cases incorporating the use of Stellar connector plugin.
+
+### Prometheus Exporter Usage
+
+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.
+
+### Prometheus Integration
+
+To use Prometheus with this exporter make sure to install [Prometheus main component](https://prometheus.io/download/).
+Once Prometheus is setup, the corresponding scrape_config needs to be added to the prometheus.yml
+
+```(yaml)
+- job_name: 'stellar_ledger_connector_exporter'
+  metrics_path: api/v1/plugins/@hyperledger/cacti-plugin-ledger-connector-stellar/get-prometheus-exporter-metrics
+  scrape_interval: 5s
+  static_configs:
+    - targets: ['{host}:{port}']
+```
+
+Here the `host:port` is where the prometheus exporter metrics are exposed. The test cases (For example, `packages/cacti-plugin-ledger-connector-stellar/src/test/typescript/unit/get-open-api-spec-v1-connector-stellar.test.ts`) exposes it over `0.0.0.0` and a random port(). The random port can be found in the running logs of the test case and looks like (42379 in the below mentioned URL)
+`Metrics URL: http://0.0.0.0:42379/api/v1/plugins/@hyperledger/cacti-plugin-ledger-connector-stellar/get-prometheus-exporter-metrics`
+
+Once edited, you can start the prometheus service by referencing the above edited prometheus.yml file.
+On the prometheus graphical interface (defaulted to http://localhost:9090), choose **Graph** from the menu bar, then select the **Console** tab. From the **Insert metric at cursor** drop down, select **cacti_stellar_total_tx_count** and click **execute**
+
+### 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
+
+## 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 
diff --git a/packages/cacti-plugin-ledger-connector-stellar/openapitools.json b/packages/cacti-plugin-ledger-connector-stellar/openapitools.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "6.6.0"
+  }
+}
diff --git a/packages/cacti-plugin-ledger-connector-stellar/package.json b/packages/cacti-plugin-ledger-connector-stellar/package.json
@@ -0,0 +1,100 @@
+{
+  "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",
+    "Cacti",
+    "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": "Peter Somogyvari",
+      "email": "[email protected]",
+      "url": "https://accenture.com"
+    }
+  ],
+  "main": "dist/lib/main/typescript/index.js",
+  "module": "dist/lib/main/typescript/index.js",
+  "browser": "dist/cacti-plugin-ledger-connector-stellar.web.umd.js",
+  "types": "dist/lib/main/typescript/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "codegen": "yarn run --top-level run-s '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 --ignore-file-override ../../openapi-generator-ignore",
+    "watch": "npm-watch",
+    "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.6.0",
+    "express": "4.19.2",
+    "http-errors-enhanced-cjs": "2.0.1",
+    "joi": "17.9.1",
+    "openapi-types": "12.1.3",
+    "prom-client": "13.2.0",
+    "run-time-error-cjs": "1.4.0",
+    "rxjs": "7.8.1",
+    "socket.io-client-fixed-types": "4.5.4",
+    "typescript-optional": "2.0.1"
+  },
+  "devDependencies": {
+    "@hyperledger/cactus-plugin-keychain-memory": "2.0.0-alpha.2",
+    "@hyperledger/cactus-test-tooling": "2.0.0-alpha.2",
+    "@types/body-parser": "1.19.4",
+    "@types/express": "4.17.19",
+    "@types/http-errors": "2.0.4",
+    "@types/uuid": "9.0.8",
+    "body-parser": "1.20.2",
+    "npm-run-all2": "6.1.2",
+    "socket.io": "4.5.4",
+    "uuid": "9.0.1"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=8"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "browserMinified": "dist/cacti-plugin-ledger-connector-stellar.web.umd.min.js",
+  "mainMinified": "dist/cacti-plugin-ledger-connector-stellar.node.umd.min.js",
+  "watch": {
+    "codegen:openapi": {
+      "patterns": [
+        "./src/main/json/openapi.json"
+      ]
+    }
+  }
+}