relayer2-public

Aurora Relayer v2

Web3-compatible relayer server for Aurora, implements;

• a JSON-RPC server compatible with Ethereum's Web3 API for Aurora Engine instances deployed on the NEAR Protocol.
• an indexer which continuously reads JSON files generated by Aurora Refiner and populate local embedded storage

This document is useful for developers, contributors and those who would like to build, run and experiment Aurora Relayer v2 natively. For packaged releases please see the distribution project Standalone Aurora Relayer and Refiner which containerizes and packs Aurora Relayer v2 and Aurora Refiner for end users

Prerequisites and Dependencies

• requires Go and Make to build from source
• requires a NEAR account and signing key to start relayer, see Configuration
• requires JSON files, generated by Aurora Refiner, to index blocks
• depends on Aurora Relayer v2 Base library which provides common functionality for public and private Aurora Relayer implementations

How To Build

git clone https://github.com/aurora-is-near/relayer2-public.git
cd relayer2-public
make

build artifacts are placed in out directory

• relayer executable
• config directory
• build.info file

How To Use

Relayer requires a set of configuration files to start (see Configuration for details), and default configuration files for mainnet and testnet are provided under config directory after build process. If config file path is not specified, Relayer starts with config/testnet.yaml by default.

Configuring a signing key

To be able to call eth_sendRawTransaction, you must have a NEAR account and signing key on the network you are relaying to, and said NEAR account must have a sufficient Ⓝ balance to be able to send transactions.

For those who prefer not to use personal accounts, a new signing key can be generated.

Setting the Signer Key Location

Ensure the signer key location is defined in the configuration file: Ex. :

endpoint:
  ...
  engine:
    ...
    signerKey: config/relayer.json

Generating the Signer Key

Execute the following command to generate a new signer key:

./relayer generate-key

Note: The default configuration file used is config/testnet.yaml.

Upon successful execution, a relayer.json file will be generated. An example of its structure is as follows:

{
  "account_id": "703f78e5355ae6fedf6384257a18e4cfb55bada321f6e7a35b1e21a3803b03e0",
  "public_key": "ed25519:8ZAoFCzzj7FwADapMyRCctau295MpvKT5Y1z6cPySCko",
  "secret_key": "ed25519:3j8Rxcnx6BcVvphxJpxKMJGWDfjTrSZTvDx7EdWm7L223dwkK8ZgebXieiadAZ3v5Xfg9AKx4XYsaPPcfmncFNo1"
}

Update the configuration file's signer field with the account_id value from the generated relayer.json file:

endpoint:
  ...
  engine:
    ...
    signer: 703f78e5355ae6fedf6384257a18e4cfb55bada321f6e7a35b1e21a3803b03e0
    signerKey: config/relayer.json

Activating implicit account

In the NEAR Protocol, implicit accounts require activation. This is achieved when a contract-based account or an externally-owned account transfers funds to the implicit account. This step is crucial as the signer account balance is utilized to cover the costs for eth_sendRawTransaction. Utilize any NEAR-compatible wallet or the near send command. Below is an example that transfers 0.5 NEAR to the generated account:

near send myaccount.near 703f78e5355ae6fedf6384257a18e4cfb55bada321f6e7a35b1e21a3803b03e0 0.5

Handling Multiple Access Keys

When dispatching multiple transactions concurrently, each signed by a different EOA, you may encounter the ERR_INCORRECT_NONCE error. The solution is for the relayer to use multiple access keys, signing each transaction with a distinct key.

Generating Multiple Keys

After configuring and activating the access key, execute the following:

./relayer add-keys --config config/mainnet.yaml -n 100

This command generates 100 keys, storing them in the same directory as the config/relayer.json file. Upon restarting, the relayer will leverage these access keys for transaction signing.

Removing Keys

To delete these keys from the account, run:

./relayer delete-keys --config config/mainnet.yaml

You can also use ENV variables to configure the signing account and private key:

Mainnet

export AURORA_RELAYER_ENDPOINT_ENGINE_SIGNER=<signer> # or set in config/mainnet.yaml
export AURORA_RELAYER_ENDPOINT_ENGINE_SIGNERKEY=<path to Near Credentials file> # or set in config/mainnet.yaml
./relayer start --config config/mainnet.yaml

Testnet

export AURORA_RELAYER_ENDPOINT_ENGINE_SIGNER=<signer> # or set in config/testnet.yaml
export AURORA_RELAYER_ENDPOINT_ENGINE_SIGNERKEY=<path to Near Credentials file> # or set in config/testnet.yaml
./relayer start # default config file is config/testnet.yaml

If you're using the NEAR CLI, you will find your signing keys stored as JSON key files under your $HOME/.near-credentials/ directory.

Commands available

for detailed explanation and flags of each command see help

./relayer <command> --help

How To Configure

JSON-RPC Methods

Legend: ❌ = not supported. 🚧 = work in progress. ✅ = supported.

Versioning

• 2.0.0 is the initial version of Aurora Relayer v2
• Aurora Relayer v1 is being deprecated, and not source code compatible with this version.
• We are following Go lang's practices and applying semantic versioning vMAJOR[.MINOR[.PATCH[-PRERELEASE][+BUILD]]]
  • MAJOR indicates backward incompatibility
  • MINOR backward compatible and stable release with new features and/or bug fixes
  • PATCH backward compatible and stable release for hot-fixes published out of planned release cycle
  • PRERELEASE does not guarantees stability, mostly used for QA cycles, e.g.: alpha, beta with optional build number

Migration

from v2.0.x to v2.1.x

Relayer2-Public v2.1.0 introduces a new JSON-RPC server. Therefore, for those who already have a native Relayer2-Public with version v2.0.x should update the configuration .yaml file accordingly.

sample v2.0.x config.yaml

rpcNode:
  geth:                    # -> deprecated
    HTTPHost: localhost
    HTTPPort: 8545
    HTTPPathPrefix: ""
    HTTPCors: 
      - "*"
    HTTPVirtualHosts:      # -> deprecated
      - "*"
    HTTPModules:           # -> deprecated
      - "net"
      - "web3"
      - "eth"
      - "parity"
    WSHost: localhost
    WSPort: 8545
    WSPathPrefix: ""
    WSModules:             # -> deprecated
      - "net"
      - "web3"
      - "eth"
      - "parity"

sample v2.1. config.yaml

rpcNode:
  httpHost: localhost
  httpPort: 8545
  httpPathPrefix: "*"
  httpCors: 
    - "*"
  httpCompress: true      # -> new subfield
  httpTimeout: 300        # -> new subfield
  wsHost: localhost
  wsPort: 8545
  wsPathPrefix: "*"
  wsHandshakeTimeout: 10  # -> new subfield
  maxBatchRequests: 1000  # -> new subfield

IMPORTANT Please note that configuration update step is automatically done if you are using distribution project Standalone Aurora Relayer and Refiner.

Contributing