Layer Relayer

Relayers for Tellor Layer that synchronize validator sets, relay oracle data to EVM chains, and relay token-bridge withdrawals. Includes a threshold relayer driven by heartbeat and external price-change thresholds, and a shared HTTP price-service supporting batched provider queries.

Setup

We assume you have python installed. Note, if you are running on ubuntu, see the additional requirements below.

1. Clone the repo:

git clone https://github.com/tellor-io/py-relayer.git

2. Navigate to the repository directory:

cd py-relayer

3. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

4. Install the dependencies:

pip install -r requirements.txt

5. Copy the .env.example file to .env and set the appropriate environment variables:

cp .env.example .env

All .env variables can alternatively be set through the CLI. We recommend setting your ethereum private key in the .env file for security reasons. For convenience, you should set any parameters which tend to remain constant across runs in the .env file. CLI arguments will override .env variables.

Additional Requirements for Ubuntu

If you are running the relayer on ubuntu, you may need to install additional tools:

sudo apt update
sudo apt install build-essential python3-dev

After installing these dependencies, proceed with the setup instructions above.

Usage

The CLI provides the following commands:

Simple Oracle Relayer (interval-based)

relayer relay --query-string "SpotPrice(eth,usd)" \
  --data-bridge-address <DATA_BRIDGE> \
  --layer-user-address <USER_CONTRACT> \
  --web3-provider <RPC> --layer-swagger <LAYER_API> --layer-rpc <LAYER_RPC> \
  --sleep-time 900 --fixed-interval

Token Bridge Withdraw Relayer

relayer relay-bridge --data-bridge-address 0xa73Efa04476B45E5bBAa68A59f7Ee2A21e14FDD4 --token-bridge-address 0x6ac02F3887B358591b8B2D22CfB1F36Fa5843867 --withdraw-id 8

Initialize Data Bridge

This calls the data bridge init function to set the initial validator set. The init function can only be called by the contract deployer, and only once.

relayer init

Reset Data Bridge

This allows the bridge guardian to reset the validator set, if and only if the validator set is stale (21 days old).

relayer reset

Threshold Relayer (Primary)

Heartbeat + price-threshold driven relayer to TellorDataBank. Uses external price(s) from the price-service (if configured), else falls back to a single PRICE_API_URL, else Layer aggregate.

relayer relay-threshold --query-string "SpotPrice(eth,usd)" --price-threshold 0.01 \
  --data-bridge-address <DATA_BRIDGE> --layer-user-address <DATABANK> \
  --web3-provider <RPC> --layer-swagger <LAYER_API> --layer-rpc <LAYER_RPC> \
  --layer-tx-creator-address <LAYER_ADDR>

Threshold Relayer (Backup)

Conservative gates and higher thresholds/heartbeat.

relayer relay-threshold --backup --query-string "SpotPrice(eth,usd)" --price-threshold 0.015 \
  --data-bridge-address <DATA_BRIDGE> --layer-user-address <DATABANK> \
  --web3-provider <RPC> --layer-swagger <LAYER_API> --layer-rpc <LAYER_RPC> \
  --layer-tx-creator-address <LAYER_ADDR>

Validator Set Relayer

Sync the EVM bridge validator set to Layer periodically (no oracle relay):

relayer relay-valset --data-bridge-address <DATA_BRIDGE> \
  --web3-provider <RPC> --layer-swagger <LAYER_API> --layer-rpc <LAYER_RPC> \
  --sleep-time 900 --fixed-interval

Price Service

Run a shared HTTP price-service that batches/caches external provider calls (CoinGecko, CoinMarketCap, CoinPaprika, Coinbase, Curve price API):

# defaults to configs/price-service.toml
relayer price-service

# or explicit
PRICE_SERVICE_CONFIG=configs/price-service.toml ./venv/bin/python -m src.cli price-service --host 0.0.0.0 --port 8787

Endpoints:

• GET /price?feed=eth-usd[&agg=median&required=1]
• GET /batch?feeds=eth-usd,btc-usd[&agg=trimmed_mean:0.1]

Config System (TOML)

Configs live under configs/, support inheritance via extends, and provide both environment variables ([env]) and per-command defaults ([commands.<name>]). Example:

extends = ["saga-shared"]

[env]
FEED_NAME = "eth-usd"
PRICE_SERVICE_URL = "http://127.0.0.1:8787"

[commands.relay-threshold]
query_string = "SpotPrice(eth,usd)"
price_threshold = 0.01

Per-network shared configs: saga-shared.toml, sepolia-shared.toml. Feed configs: configs/<network>/<feed>.toml (templates included for ETH/BTC/USDC/USDT/TBTC/wstETH/rETH/stATOM).

When using configs:

relayer --config saga/eth-usd relay-threshold --eth-private-key 0x...

Help

relayer --help
relayer relay --help
relayer relay-threshold --help
relayer relay-bridge --help
relayer relay-valset --help