Relayer
Typescript implementation of an IBC Relayer.
To get a good overview of what it can do, please
check our feature matrix
You can also read our specification page, which explains how
the relayer works, but the Quick Start probably gives a better intro.
This repo is mainly used as a node binary to perform IBC relaying. However, all logic is
available in the library, which can be run equally well in the browser or in Node.
You can see an example of embedding the relayer in a webapp below.
Requirements
Important Note
Versions until v0.1.6
support Cosmos SDK v0.41.1+
.
From v0.2.0
on we require Tendermint v0.34.9+
(which is used in SDK v0.42.4+
).
If you are connecting to a v0.41 chain, please use the v0.1.x
relayer.
With v0.2.0
we add support for relaying packets in BeginBlock and EndBlock. However, this requires
an extra rpc endpoint in Tendermint that is not available in v0.41.1
. We therefore increase the
minimum compatible version of the SDK.
Installation
NPM
Install the latest release.
npm i -g @confio/relayer
Alternatively, install from the main
branch.
npm i -g @confio/relayer@main
NOTE: We do a manual release after completing a predefined milestone or when it feels right. No release schedule is in place yet. To utilize the latest changes, use the main
tag during the installation.
Usage
After installation, ibc-setup
and ibc-relayer
executables are available.
ibc-setup
Collection of commands to quickly setup a relayer and query IBC/chain data.
ibc-relayer
Reads the configuration and starts relaying packets.
Quick start
Configure and start the relayer
-
Init the configuration
ibc-setup init --src oysternet --dest nyancat
-
creates relayer's home directory at ~/.ibc-setup
-
creates app.yaml
inside relayer's home with src
, dest
and newly generated mnemonic
-
pulls default registry.yaml
to relayer's home
-
funds addresses on oysternet
so relayer can pay the fee while relaying packets
NOTE: Both testnets are running in the public. You do not need to start any blockchain locally to complete the quick start guide.
NOTE: Run ibc-setup balances
to see the amount of tokens on each address.
-
Get testnet tokens for nyancat
- Find your relayer address on nyancat via:
ibc-setup keys list | grep nyancat
- Join IRISnet discord with this invite link
- Go to the
nyancat-faucet
channel - Request tokens at this address in the above channel:
$faucet iaa1fxmqew9dgg44jdf3l34zwa8rx7tcf42wz8ehjk
- Check you have tokens on oysternet and nyancat via
ibc-setup balances
Original Instructions from IRISnet
-
Create ics20
channel
ibc-setup ics20 -v
- creates a new connection on source and desination chains
- saves connection ids to
app.yaml
file - creates a new channel
-
Start the relayer in the verbose mode and 10s frequency polling
ibc-relayer start -v --poll 15
Send tokens between chains
-
Make sure wasmd
binary is installed on your system
-
Make sure iris
binary is installed on your system
-
Create a new account and fund it
wasmd keys add sender
JSON=$(jq -n --arg addr $(wasmd keys show -a sender) '{"denom":"usponge","address":$addr}')
curl -X POST --header "Content-Type: application/json" --data "$JSON" https://faucet.oysternet.cosmwasm.com/credit
-
Create a valid IRISnet address to send tokens to
iris keys add receiver
Get testnet tokens if you want to send tokens to oysternet
.
-
Send tokens
wasmd tx ibc-transfer transfer transfer <channel-id> $(iris keys show -a receiver) 200usponge --from $(wasmd keys show -a sender) --node http://rpc.oysternet.cosmwasm.com:80 --chain-id oysternet-1 --fees 2000usponge --packet-timeout-height 0-0
-
Observe the relayer output
Configuration overview
The relayer configuration is stored under relayer's home directory. By default, it's located at $HOME/.ibc-setup
, however, can be customized with home
option, e.g.:
ibc-setup init --home /home/user/relayer_custom_home
ibc-relayer start --home /home/user/relayer_custom_home
There are 3 files that live in the relayer's home.
-
registry.yaml (required)
Contains a list of available chains with corresponding information. The chains from the registry can be referenced by ibc-setup
binary or within the app.yaml
file. View an example of registry.yaml file.
-
app.yaml (optional)
Holds the relayer-specific options such as source or destination chains. These options can be overridden with CLI flags or environment variables.
-
last-queried-heights.json (optional)
Stores last queried heights for better performance on relayer startup. It's constantly overwritten with new heights when relayer is running. Simply delete this file to scan the events since forever.
Learn more about configuration.
Monitoring
The relayer collects various metrics that a Prometheus instance can consume.
To enable metrics collection, pass the --enable-metrics
flag when starting the relayer:
ibc-relayer start --enable-metrics
NOTE: Metrics can also be enabled via an environment variable RELAYER_ENABLE_METRICS=true
, or with an enableMetrics: true
entry in the app.yaml
file, as explained in the config specification.
The GET /metrics
endpoint will be exposed by default on port 8080
, which you can override with --metrics-port
flag, RELAYER_METRICS_PORT
env variable, or metricsPort
entry in app.yaml
.
Local setup
Prometheus
- Start the relayer with metrics enabled
- Spin up the Prometheus instance:
docker run -it -v $(pwd):/prometheus -p9090:9090 prom/prometheus --config.file=demo/prometheus.yaml
NOTE: Ensure that the --config.file=<path>
flag points at the existing configuration file. If you wish to use the example config, just run the command above in the root of this repository. Otherwise, you must adjust the volume (-v
) and config file path to your setup.
- Open the Prometheus dashboard in a browser at http://localhost:9090
Grafana
- Spin up the Grafana instance:
docker run -d --name=grafana -p 3000:3000 grafana/grafana
- Navigate to http://localhost:3000 and log in (
admin
/admin
) - Create a Prometheus data source
NOTE: Use http://host.docker.internal:9090
as the server URL and Server
as the Access method.
- Create a new graph and query data
NOTE: Useful guides:
Development
Refer to the development page.
Chain Requirements
The blockchain must be based on Cosmos SDK v0.42.4+
. In particular it must have
PR 8458 and PR 9081
merged (if you are using a fork) in order for the relayer to work properly. ibc-setup
should work on v0.40.0+
The chain must have a large value for staking.params.historical_entries
(often set in genesis).
The default is "10000" and this should work with "1000", but no relayer will work if it is set to 0.
Full Node Requirements
Ideally you are in control of the node that the relayer connects to. If not, it should be run
by a known and trusted party, whom you can check the configuration with. Note that a malicious node
could cause the relayer to send invalid packets and waste tokens on gas (but not create invalid state).
The indexer should be enabled (tx_index.indexer = "kv"
in config.toml
),
and all events should be indexed (index-events = []
in app.toml
).
The node must support historical queries. --pruning=nothing
will definitely work, but will use an
enormous amount of disk space. You can also trim it to 3 weeks of data with
--pruning=custom --pruning-keep-recent=362880 --pruning-keep-every=0 --pruning-interval=100
, which has been
tested. It is likely you could reduce pruning-keep-recent
to as low as, say, 3600, but that would need testing.
Web App
This repo can also be imported as a library and used in a web app. @clockworkgr has been so nice
to share a sample Vue.js app using the relayer.
This includes some nice code samples to
send a IbcTransfer message with CosmJS
as well as setting up
and running the relayer.
The key import is import { IbcClient, Link } from "@confio/relayer/build";