From 31541509cc0f129a943ce22de96a8c5630205e9f Mon Sep 17 00:00:00 2001 From: clayton neal Date: Fri, 7 Mar 2025 16:31:39 +0000 Subject: [PATCH 1/5] chore: docker ci --- .github/workflows/publish-sdk.yml | 2 +- .github/workflows/rpc-proxy-docker.yml | 9 +++++++-- .github/workflows/rpc-proxy.yml | 2 +- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/workflows/publish-sdk.yml b/.github/workflows/publish-sdk.yml index 624f3dafa..965929910 100644 --- a/.github/workflows/publish-sdk.yml +++ b/.github/workflows/publish-sdk.yml @@ -1,7 +1,7 @@ name: Publish NPM package on: - workflow_call: + workflow_dispatch: permissions: contents: read diff --git a/.github/workflows/rpc-proxy-docker.yml b/.github/workflows/rpc-proxy-docker.yml index d1b6938f9..119669890 100644 --- a/.github/workflows/rpc-proxy-docker.yml +++ b/.github/workflows/rpc-proxy-docker.yml @@ -43,8 +43,13 @@ jobs: context: . file: docker/rpc-proxy/Dockerfile load: true - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} + tags: "latest,v1.0.0" + labels: | + maintainer=vechain + description="RPC Proxy for vechain Thor" + build_timestamp=${{ github.event.after }} + source=https://github.com/vechain/vechain-sdk-js + commit_hash=${{ github.sha }} - name: Create .trivyignore file # "cross-spawn" is resolved as version 7.0.5 but Trivy keeps showing the error diff --git a/.github/workflows/rpc-proxy.yml b/.github/workflows/rpc-proxy.yml index 53860626a..f9739bf73 100644 --- a/.github/workflows/rpc-proxy.yml +++ b/.github/workflows/rpc-proxy.yml @@ -1,7 +1,7 @@ name: RPC Proxy on: - workflow_call: + workflow_dispatch: jobs: test: From 73f87a0a9bccd6ce99d9215c34c740a6260041ff Mon Sep 17 00:00:00 2001 From: clayton neal Date: Fri, 7 Mar 2025 17:42:20 +0000 Subject: [PATCH 2/5] fix: hardcode --- .github/workflows/rpc-proxy-docker.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/rpc-proxy-docker.yml b/.github/workflows/rpc-proxy-docker.yml index 119669890..4d72fd407 100644 --- a/.github/workflows/rpc-proxy-docker.yml +++ b/.github/workflows/rpc-proxy-docker.yml @@ -60,7 +60,7 @@ jobs: - name: Run Trivy Scan uses: aquasecurity/trivy-action@master with: - image-ref: ${{ fromJSON(steps.meta.outputs.json).tags[0] }} + image-ref: vechain/sdk-rpc-proxy format: 'table' ignore-unfixed: true exit-code: '1' From 3b3a57dac26271e2d80d24a7649bc8ea5dfc3cc5 Mon Sep 17 00:00:00 2001 From: clayton neal Date: Mon, 10 Mar 2025 09:37:31 +0000 Subject: [PATCH 3/5] chore: fix --- .github/workflows/rpc-proxy-docker.yml | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/.github/workflows/rpc-proxy-docker.yml b/.github/workflows/rpc-proxy-docker.yml index 4d72fd407..3fab48082 100644 --- a/.github/workflows/rpc-proxy-docker.yml +++ b/.github/workflows/rpc-proxy-docker.yml @@ -3,12 +3,18 @@ name: RPC Proxy - Docker build, scan and push on: workflow_call: +env: + DOCKERFILE_LOCATION: "docker/rpc-proxy/Dockerfile" + DOCKER_IMAGE_NAME: "vechain/sdk-rpc-proxy" + DOCKER_IMAGE_VERSION: "v1.0.0" + permissions: contents: read packages: write checks: write actions: read + jobs: docker: runs-on: ubuntu-latest @@ -31,19 +37,13 @@ jobs: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - name: Extract metadata (tags, labels) for Docker - id: meta - uses: docker/metadata-action@v5 - with: - images: vechain/sdk-rpc-proxy - - name: Build and export to Docker uses: docker/build-push-action@v6 with: context: . - file: docker/rpc-proxy/Dockerfile + file: ${{ env.DOCKERFILE_LOCATION }} load: true - tags: "latest,v1.0.0" + tags: "${{ env.DOCKER_IMAGE_NAME }}:${{env.DOCKER_IMAGE_VERSION}}" labels: | maintainer=vechain description="RPC Proxy for vechain Thor" @@ -60,7 +60,7 @@ jobs: - name: Run Trivy Scan uses: aquasecurity/trivy-action@master with: - image-ref: vechain/sdk-rpc-proxy + image-ref: ${{env.DOCKER_IMAGE_NAME}} format: 'table' ignore-unfixed: true exit-code: '1' @@ -77,8 +77,7 @@ jobs: uses: docker/build-push-action@v6 with: context: . - file: docker/rpc-proxy/Dockerfile + file: ${{env.DOCKERFILE_LOCATION}} platforms: linux/amd64,linux/arm64 push: true - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} + tags: "${{ env.DOCKER_IMAGE_NAME }}:${{env.DOCKER_IMAGE_VERSION}}" From 74a10523faafa0d02b0fc80236476171d1c7cb98 Mon Sep 17 00:00:00 2001 From: clayton neal Date: Mon, 10 Mar 2025 15:14:00 +0000 Subject: [PATCH 4/5] chore: update readme --- .github/workflows/rpc-proxy.yml | 1 - packages/rpc-proxy/README.md | 181 ++++++++++++++++++-------------- 2 files changed, 104 insertions(+), 78 deletions(-) diff --git a/.github/workflows/rpc-proxy.yml b/.github/workflows/rpc-proxy.yml index f9739bf73..c592d495f 100644 --- a/.github/workflows/rpc-proxy.yml +++ b/.github/workflows/rpc-proxy.yml @@ -5,7 +5,6 @@ on: jobs: test: - if: github.ref != 'refs/tags/*' uses: ./.github/workflows/rpc-proxy-test.yml secrets: inherit diff --git a/packages/rpc-proxy/README.md b/packages/rpc-proxy/README.md index 91fb8772f..7c9e131d4 100644 --- a/packages/rpc-proxy/README.md +++ b/packages/rpc-proxy/README.md @@ -8,108 +8,150 @@ The RPC Proxy is designed to bridge the gap between Thor's RESTful API and Ether interaction with the VeChainThor blockchain through RPC calls. It is particularly useful for integrating with tools such as the Remix IDE. -## Installation +The RPC Proxy can be optionally configured to: -To install the RPC proxy, use the following command: +* sign transactions for `eth_signTransaction` RPC method +* use a vechain account for fee delegation + +## Useage + +The RPC proxy can be used in two different ways: + +* Executing directly via node package execute (npx) +* Executing via Docker container + +Both ways of using can be configured via a configuration file or using command line options + +## Starting the Proxy + +To install the RPC proxy for NPX useage, use the following command: ``` bash yarn add @vechain/sdk-rpc-proxy ``` -## Usage - -The RPC proxy is simple to use. To start it, run: +To start the proxy, run: ``` bash npx rpc-proxy ``` -By default, the proxy is configured to be used with a solo node running on your local machine. There are two options if you want to change the default behavior, or use a custom configuration: - - Create a config.json file and pass it to the command when launching the RPC Proxy. - - Use CLI options. - -## Configuration file - -Run: +To start the proxy with Docker: ``` bash -npx rpc-proxy -c +docker run -d -p 8545:8545 -t vechain/sdk-rpc-proxy: ``` -Or: +*By default*, the proxy is configured to be used with a solo node running on your local machine. +There are two options if you want to change the default behavior, or use a custom configuration: + - Create a `config.json` file and pass it to the command when launching the RPC Proxy + - Use CLI options -``` bash -npx rpc-proxy --configurationFile -``` ## CLI Options -With rpc-proxy, you can use the following CLI options. -Cli options override the configuration file. -So you can run the rpc-proxy with: +The following CLI options exist. +CLI options override any used configuration file. -- a configuration file with the default values and override them with the cli options - - -e.g.- `npx rpc-proxy -p 8545 -v ...` +| NPX CLI Option | Description | +|-----------------------------------------|---------------------------------------------------------| +| -p (--port) | port number for the service | +| -c (--configurationFile) | path to configuration file | +| -u (--url) | url to vechain thor node | +| -v (--verbose) | to turn on verbose logging | +| -a (--accounts) | the private keys used to sign tx's | +| -m (--mnemonic) | mnemonic to derive private keys to sign tx's with | +| -mc (--mnemonicCount) | the number of accounts to derive from the mnemonic | +| -mi (--mnemonicInitialIndex) | index to start deriving accounts from the mnemonic | +| -e (--enableDelegation) | turns on fee delegation for signed tx's | +| --gasPayerPrivateKey | private key of the gas payer | +| -s (--gasPayerServiceUrl) | fee delegation service url | -- a custom configuration file and override some values with the cli options - - -e.g.- `npx rpc-proxy -c /path/of/custom-config.json -p 8545 -v ...` -### Cli options list +For docker based execution, CLI options are passed as environment variables. -#### Give the configuration file -- `-c, --configurationFile `: The path to the configuration file. - - -e.g.- `npx rpc-proxy -c /path/of/custom-config.json` OR `rpc-proxy --configurationFile custom-config.json` +| Docker ENV Variable | Description | +|-----------------------------------------|---------------------------------------------------------| +| URL | url to vechain thor node | +| PORT | internal port number for the service | +| ACCOUNTS | private keys to sign transactions | +| MNEMONIC | mnemonic to derive private keys to sign tx's with | +| MNEMONIC_COUNT | the number of accounts to derive from the mnemonic | +| MNEMONIC_INITIAL_INDEX | index to start deriving accounts from the mnemonic | +| ENABLE_DELEGATION | turns on fee delegation for signed tx's | +| GAS_PAYER_PRIVATE_KEY | private key of the gas payer | +| GAS_PAYER_SERVICE_URL | fee delegation service url | +| CONFIGURATION_FILE | path to configuration file | -- `-p, --port `: The port on which the proxy server will run. - - -e.g.- `npx rpc-proxy -p 8545` OR `rpc-proxy --port 8545` -- `-u, --url `: The URL of the VeChainThor node. - - -e.g.- `npx rpc-proxy -u http://testnet.vechain.org` OR `rpc-proxy --url http://testnet.vechain.org` +#### NPX CLI Examples: -- `-v, --verbose`: Whether to enable verbose logging. - - -e.g.- `npx rpc-proxy -v` OR `rpc-proxy --verbose` +- passing configuration file and port: + - `npx rpc-proxy -c /path/of/custom-config.json -p 8545 -v ...` -#### Give the accounts +- passing url of vechain thor node: + - `npx rpc-proxy -u http://testnet.vechain.org` OR `rpc-proxy --url http://testnet.vechain.org` -- `-a, --accounts `: The accounts (private keys) that the proxy server will use to sign transactions. It is a - space-separated list of private keys. - - -e.g.- `npx rpc-proxy -a "7f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158"` - OR `npx rpc-proxy --accounts "7f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158"` +- enabling verbose logging: + - `npx rpc-proxy -v` OR `rpc-proxy --verbose` -- `-m, --mnemonic `: The mnemonic that the proxy server will use to sign transactions. -- `-mc, --mnemonicCount `: The number of accounts to derive from the mnemonic. -- `-mi, --mnemonicInitialIndex `: The index from which to start deriving accounts from the - mnemonic. - - -e.g.- `npx rpc-proxy -m "denial kitchen pet squirrel other broom bar gas better priority spoil cross" -mc 10 -mi 1` - OR `npx rpc-proxy --mnemonic "denial kitchen pet squirrel other broom bar gas better priority spoil cross" --mnemonicCount 10 --mnemonicInitialIndex 1` - - **NOTE**: --mnemonic, --mnemonicCount, and --mnemonicInitialIndex MUST be used together. +- specificying the accounts (private keys) to sign transactions. It is a space-separated list of private keys. + - `npx rpc-proxy -a "7f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158"` + - `npx rpc-proxy --accounts "7f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158"` -#### Use delegation +- specifying the mnemonic to derive tx signing accounts from: + - `npx rpc-proxy -m "denial kitchen pet squirrel other broom bar gas better priority spoil cross" -mc 10 -mi 1` + - `npx rpc-proxy --mnemonic "denial kitchen pet squirrel other broom bar gas better priority spoil cross" --mnemonicCount 10 --mnemonicInitialIndex 1` + - **NOTE**: --mnemonic, --mnemonicCount, and --mnemonicInitialIndex MUST be used together. -- `-e, --enableDelegation`: Whether to enable delegation. -- `--gasPayerPrivateKey `: The private key of the gasPayer. -- `-s, --gasPayerServiceUrl `: The URL of the gasPayer. - - -e.g.- `npx rpc-proxy -e --gasPayerPrivateKey 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158` - OR `npx rpc-proxy --enableDelegation --gasPayerPrivateKey 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158` - - -e.g.- `npx rpc-proxy -e -s https://sponsor-testnet.vechain.energy/by/...` - OR `npx rpc-proxy --enableDelegation --gasPayerServiceUrl https://sponsor-testnet.vechain.energy/by/...` +- enabling fee delegation: + - `npx rpc-proxy -e -gk 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158` + - `npx rpc-proxy --enableDelegation --gasPayerPrivateKey 8f9290cc44c5fd2b95fe21d6ad6fe5fa9c177e1cd6f3b4c96a97b13e09eaa158` + - `npx rpc-proxy -e -s https://sponsor-testnet.vechain.energy/by/...` + - `npx rpc-proxy --enableDelegation --gasPayerServiceUrl https://sponsor-testnet.vechain.energy/by/...` - **NOTE**: --gasPayerPrivateKey and --gasPayerServiceUrl are mutually exclusive. - - **NOTE**: if --enableDelegation is used, --gasPayerPrivateKey OR --gasPayerServiceUrl MUST be used. + - **NOTE**: if --enableDelegation is used, --gasPayerPrivateKey OR --gasPayerServiceUrl MUST be used also. + + +#### Docker Run Examples + +- default configuration pointing to testnet nodes: + - `docker run -d -p 8545:8545 -e URL=https://testnet.vechain.org -t vechain/sdk-rpc-proxy:` + +- using a configuration file: + - `docker run -d -p 8545:8545 -v ./rpc-proxy-testnet-config.json:/app/packages/rpc-proxy/config.json -e CONFIGURATION_FILE=/app/packages/rpc-proxy/config.json -t vechain/sdk-rpc-proxy:` +` -## Configuration file + +## Configuration File The `config.json` file is used to configure the proxy server. It contains the following fields: - `url`: The URL of the VeChainThor node. - `port`: The port of the proxy server. -- `accounts`: The accounts that the proxy server will use to sign transactions (can be a mnemonic or an array of private - keys). +- `accounts`: The accounts that the proxy server will use to sign transactions (can be a mnemonic or an array of private keys). - `verbose`: Wheter to enable verbose logging. - `debug`: Whether to enable debug mode. - `enableDelegation`: Whether to enable delegation. +- `gasPayer`: Specifies gasPayer private key or fee delegation service url + +### Using Configuration file + +For NPX useage the configuration file is passed via the `-c` or `--configurationFile` command line parameter: + +``` bash +npx rpc-proxy -c +npx rpc-proxy --configurationFile +``` + +For Docker useage the configuration file is mounted as a volume, and the env variable CONFIGURATION_FILE is set to its location: -### Example Configurations +``` bash +docker run -d -p 8545:8545 -v ./rpc-proxy-testnet-config.json:/app/packages/rpc-proxy/config.json -e CONFIGURATION_FILE=/app/packages/rpc-proxy/config.json -t vechain/sdk-rpc-proxy: +``` + +### Example Configuration Files Simple thor solo configuration with mnemonic: @@ -177,22 +219,7 @@ Simple testnet configuration with a gasPayer private url: } ``` -# Run as Docker Container - -To run the RPC proxy as a Docker container, follow these steps: - -``` bash -cd ../.. -docker build -f docker/rpc-proxy/Dockerfile . -t vechain/sdk-rpc-proxy -# To replace the default config file, update the config.json file and start a terminal from the folder in which the file is located. -# DISCLAIMER: Make sure you replace the default config file before using it for production software. By default, the docker will point to testnet and use a known mnemonic. -docker run -d -p 8545:8545 -v ./config.json:/app/packages/rpc-proxy/config.json -t vechain/sdk-rpc-proxy -``` - -If you do not pass a config.json file, the default solo network standard configuration will be used. Make sure to -provide your desired configuration file. - -## JSON RPC Methods Support Status +## Appendix - JSON RPC Methods Support Status Below is the support status for JSON RPC methods in VeChain via `sdk-rpc-proxy`. @@ -262,7 +289,7 @@ Below is the support status for JSON RPC methods in VeChain via `sdk-rpc-proxy`. - **Partially Supported**: The method is implemented but may have limitations or deviations from the Ethereum standard. - **Not Supported**: The method is not implemented or cannot be supported due to protocol constraints. -## RPC to VeChain Mappings +### RPC to VeChain Mappings The following mappings are performed by the RPC proxy @@ -283,7 +310,7 @@ The method `eth_chainId` returns: * for solo or other custom networks it returns the _chainTag_ (the last byte of the genesis block id) -## Transaction Coversions +### Transaction Coversions The method `eth_sendTransaction` requires the input to be a VeChain transaction object, not a Ethereum transaction object This method signs the transaction using the configured PK, before passing it on to VeChain Thor From a2b97b3dc406cc1770ac3ade7202aa58f0f36959 Mon Sep 17 00:00:00 2001 From: clayton neal Date: Mon, 10 Mar 2025 15:58:01 +0000 Subject: [PATCH 5/5] chore: typo --- packages/rpc-proxy/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rpc-proxy/README.md b/packages/rpc-proxy/README.md index 7c9e131d4..c94d85e50 100644 --- a/packages/rpc-proxy/README.md +++ b/packages/rpc-proxy/README.md @@ -310,7 +310,7 @@ The method `eth_chainId` returns: * for solo or other custom networks it returns the _chainTag_ (the last byte of the genesis block id) -### Transaction Coversions +### Transaction Conversions The method `eth_sendTransaction` requires the input to be a VeChain transaction object, not a Ethereum transaction object This method signs the transaction using the configured PK, before passing it on to VeChain Thor