/neutron-query-relayer

Relays interchain queries inside Cosmos interchain

Primary LanguageGoApache License 2.0Apache-2.0

Interchain query relayer implementation for Neutron.

More on relayer in neutron-docs

Running in development

Natively

  • export environment you need (e.g. export $(grep -v '^#' .env.example | xargs) note: change rpc addresses to actual)
  • make dev

For more configuration parameters see Environment section.

In Docker

  1. Build docker image make build-docker
  2. Run docker run --env-file .env.example -v $PWD/../neutron/data:/data -p 9999:9999 neutron-org/neutron-query-relayer
    • note: this command uses relative path to mount keys, run this from root path of neutron-query-relayer
    • note: with local chains use host.docker.internal in RELAYER_NEUTRON_CHAIN_RPC_ADDR and RELAYER_TARGET_CHAIN_RPC_ADDR instead of localhost/127.0.0.1
    • note: on Linux machines it is necessary to pass --add-host=host.docker.internal:host-gateway to Docker in order to make container able to access host network

Testing

Run unit tests

$ make test

Testing with 2 neutron-chains (easier for development) via cli

prerequisites

Clone the following repositories to the same folder where the neutron-query-relayer folder is located:

  1. git clone git@github.com:neutron-org/neutron.git
  2. git clone git@github.com:neutron-org/neutron-dev-contracts.git
  3. git clone git@github.com:neutron-org/neutron-integration-tests.git for testing using docker

terminal 1

  1. cd neutron
  2. make build && make init && make start-rly

terminal 2

  1. cd neutron-dev-contracts
  2. run test_*.sh files from the root of the neutron-dev-contracts project (e.g. ./test_tx_query_result.sh).

terminal 3

  1. cp .env.example.dev .env, edit .env if desired
  2. export $(grep -v '^#' .env | xargs) && make dev

Testing via docker

  1. cd neutron-integration-tests
  2. read and run preparation steps described in the README.md file
  3. run tests as described in the README.md file

In case of unexpected behaviour (e.g. tests failure) you can inspect neutron and relayer logs by doing the following:

Neutron:

  1. docker ps
  2. find the neutron container id
  3. docker exec -it neutron_id bash
  4. cd /opt/neutron/data
  5. observe neutron logs in file test-1.log

Relayer:

  1. docker ps
  2. find the relayer container id
  3. docker logs -f relayer_id

Configuration

Environment

Key type description optional
RELAYER_NEUTRON_CHAIN_RPC_ADDR string rpc address of neutron chain required
RELAYER_NEUTRON_CHAIN_REST_ADDR string rest address of neutron chain required
RELAYER_NEUTRON_CHAIN_HOME_DIR string path to keys directory required
RELAYER_NEUTRON_CHAIN_SIGN_KEY_NAME string key name required
RELAYER_NEUTRON_CHAIN_TIMEOUT time timeout of neutron chain provider optional
RELAYER_NEUTRON_CHAIN_GAS_PRICES string specifies how much the user is willing to pay per unit of gas, which can be one or multiple denominations of token required
RELAYER_NEUTRON_CHAIN_GAS_LIMIT string the maximum price a relayer user is willing to pay for relayer's paid blockchain actions required
RELAYER_NEUTRON_CHAIN_GAS_ADJUSTMENT float used to scale gas up in order to avoid underestimating. For example, users can specify their gas adjustment as 1.5 to use 1.5 times the estimated gas required
RELAYER_NEUTRON_CHAIN_CONNECTION_ID string neutron chain connection ID required
RELAYER_NEUTRON_CHAIN_DEBUG bool flag to run neutron chain provider in debug mode optional
RELAYER_NEUTRON_CHAIN_KEYRING_BACKEND string see required
RELAYER_NEUTRON_CHAIN_OUTPUT_FORMAT json OR yaml neutron chain provider output format required
RELAYER_NEUTRON_CHAIN_SIGN_MODE_STR string see also consider use short variation, e.g. direct optional
RELAYER_TARGET_CHAIN_RPC_ADDR string rpc address of target chain required
RELAYER_TARGET_CHAIN_TIMEOUT time timeout of target chain provider optional
RELAYER_TARGET_CHAIN_DEBUG bool flag to run target chain provider in debug mode optional
RELAYER_TARGET_CHAIN_OUTPUT_FORMAT json or yaml target chain provider output format optional
RELAYER_REGISTRY_ADDRESSES string a list of comma-separated smart-contract addresses for which the relayer processes interchain queries required
RELAYER_REGISTRY_QUERY_IDS string a list of comma-separated query IDs which complements to RELAYER_REGISTRY_ADDRESSES to further filter out interchain queries being processed optional
RELAYER_ALLOW_TX_QUERIES bool if true relayer will process tx queries (if false, relayer will drop them) required
RELAYER_ALLOW_KV_CALLBACKS bool if true, will pass proofs as sudo callbacks to contracts required
RELAYER_MIN_KV_UPDATE_PERIOD uint minimal period of queries execution and submission (not less than n blocks) optional
RELAYER_STORAGE_PATH string path to leveldb storage, will be created on given path if doesn't exists
(required if RELAYER_ALLOW_TX_QUERIES is true)		 optional
RELAYER_CHECK_SUBMITTED_TX_STATUS_DELAY uint delay in seconds to wait before transaction is checked for commit status optional
RELAYER_QUERIES_TASK_QUEUE_CAPACITY int capacity of the channel that is used to send messages from subscriber to relayer (better set to a higher value to avoid problems with Tendermint websocket subscriptions). optional
RELAYER_INITIAL_TX_SEARCH_OFFSET uint if set to non zero and no prior search height exists, it will initially set to (last_height - X). Set this if you have lots of old tx's on first start you don't need. optional
RELAYER_LISTEN_ADDR string listener address for webserver json api you can query and prometheus metrics optional

Logging

We are using a little modified zap.Logger, the modification can be seen at the neutron-logger repository. The default version of the logger used in the application is a little bit modified zap.NewProduction. The logger level can be set via the LOGGER_LEVEL env variable. If there is a need for a more significant customisation of the logger behaviour, see the neutron-logger repository readme.

Generate Openapi

The relayer uses a generated swagger client to retrieve queries information from Neutron. You can re-generate the Go client from ./internal/subscriber/querier/openapi.yml by running:

make generate-openapi

The swagger specs can be taken from the Neutron repo (you need to remove most of the generated specification).

Querying api server

You can query any running relayer as an api webserver.

Print available queries:

go run ./cmd/neutron_query_relayer query