Chainweb Relay App

What is it?

This is a small server application to power Kadena bridges. The first iteration supports bridging transactions from Ethereum.

The application can:

• Listen to Ethereum token contracts for transfers into a designated "locker" address.
• For selected transfers, retreive header information from Ethereum in order to "propose" it to the relay smart contract on Kadena
• Respond to proposals to validate headers by quering Ethereum and asserting they match.

Who needs it?

Bonders in the Kadena Chain Relay need to endorse enough headers in their bond lockup period in order to

• earn a per-endorsement fee
• qualify for risk fees in the form of APY

Thus bonders either need to operate the software themselves, or have a service provider like Flux operate the software on their behalf.

Prerequisites for running the software

A given instance of the software runs for a single bond, and must be configured with the private key that governs the bond.

Rotating the bond key

Bonders who have purchased bonds on relay.chainweb.com using their KDA public key should NOT expose their public key to this software. Instead, bonders should rotate their bond to a dedicated keypair just for bond administration as this will protect their KDA account.

Rotating can be achieved by

1. Generating a keypair
2. Using the "rotate bond" button on relay.chainweb.com for the appropriate bond.

Quick Start

npm install --global @kadena/relay-app
INFURA_API_TOKEN=... BOND_NAME=... PACT_PRIVATE_KEY=... relay-app

Run with Docker:

docker run -e INFURA_API_TOKEN=... -e BOND_NAME=... -e PACT_PRIVATE_KEY=... kadena/relay-app

Usage

Configuration

Configuration is done either

• by setting respective environment variables, or
• by creating an .env file,
• by using docker and providing the settings as environment variables to the container.

Default environment:

• DEFAULT_ENV (production|ropsten|kovan, default: kovan)

Required settings for relay-app:

• INFURA_API_TOKEN: api token for connecting to Infura servers - the project ID of infura projects.
• BOND_NAME: the bond name as seen in relay.chainweb.com
• PACT_PRIVATE_KEY: the private key for administering the bond, as described above in "Rotating the bond key" section.

Usually set via default environment:

• ETH_NETWORK_ID: network identifier for mainnet or various testnets. Default is kovan
• ETH_CONTRACT_ADDR: Contract address for observing transfers.
• ETH_LOCKUP_PUBLIC_KEY: Lockup address for observing transfers.
• ETH_CONFIRMATION_DEPTH (default for mainnet is 20)
• PACT_CONFIRMATION_DEPTH (default for mainnet is 10)

By default infura.io and api.chainweb.com are used as API servers for Ethereum and Kadena, respectively. Other API providers can be configured through setting ETH_URL and PACT_SERVER environment variables.

All other settings are mainly for debugging and testing purposes. For details have a look at Config.mjs.

Template for .env file:

DEFAULT_ENV=kovan
INFURA_API_TOKEN=

# Relay-app settings (always required)
BOND_NAME=
PACT_PRIVATE_KEY=

# Only for testing with lockup transfers
ETH_TEST_PRIVATE_KEY=

# For testing with docker compose: second bonder
BOND_NAME_2=
PACT_PRIVATE_KEY_2=

Running From Source

npm install
INFURA_API_TOKEN=... BOND_NAME=... PACT_PRIVATE_KEY=... npm start

Docker

docker build -t relay-app
docker run -e INFURA_API_TOKEN=... -e BOND_NAME=... -e PACT_PRIVATE_KEY=... relay-app

or provide the settings via an local .env file:

docker run -v "$PWD/.env:/app/.env:ro" relay-app

Testing and Development

Unit Tests

npm test

Generating Test Lockup Transfers

Required settings for testing with lockup transfers for Test Standard Token (TST)

• INFURA_API_TOKEN
• ETH_TEST_PRIVATE_KEY

npm install --global @kadena/relay-app
INFURA_API_TOKEN=... ETH_TEST_PRIVATE_KEY=... lockup-transfers

or via docker as

docker build -t lockup-transfers -f app-test/RunLockups.Dockerfile .
docker run -e INFURA_API_TOKEN=... -e ETH_TEST_PRIVATE_KEY=... lockup-transfers

Testing With Docker Compose

1. Create app-test/.env and fill out the respective settings:

   INFURA_API_TOKEN=
   ETH_TEST_PRIVATE_KEY=
   
   # First bonder
   BOND_NAME=
   PACT_PRIVATE_KEY=
   
   # Second bonder
   BOND_NAME_2=
   PACT_PRIVATE_KEY_2=

2. Run tests

   a. via npm

   ```
   npm run app-test
   ```

   b. via docker

   ```sh
   docker compose -f app-test/docker-compose.yaml --env-file=./app-test/.env up --build
   ```