@kadena/relay-app v1.0.4
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.comPACT_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 iskovan
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
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=
Run tests
a. via npm
``` npm run app-test ```
b. via docker
```bash docker compose -f app-test/docker-compose.yaml --env-file=./app-test/.env up --build ```