bifrost-relayer.rs

What is bifrost-relayer.rs?

We recently introduced a Rust implementation of the CCCP-Relayer for the Bifrost Network. The new relayer has been reengineered to enhance overall performance and robustness across multiple blockchains. It retains the same functions as the Python version, processing cross-chain transactions and facilitating data transfers (e.g., feeding price information) from one blockchain to another.

The following section will guide you through the setup process about the Rust implementation of the Bifrost network's relayer.

Install Requirements

To initiate the bifrost-relayer, certain dependencies must be manually installed. Both the executable binary file and the configuration YAML file are essential for all environments and operators.

First, install the latest bifrost-relayer release binary. You can check the latest releases by going to our GitHub repository under the releases page.

wget "https://github.com/bifrost-platform/bifrost-relayer.rs/releases/latest/download/bifrost-relayer"

In order to execute the binary, the permission of the file has to be updated.

chmod +x bifrost-relayer

Then, install the configuration YAML file. This file serves as an example for a quick start. Given the minor differences between Testnet and Mainnet environments, it's crucial to use the appropriate file for the corresponding network.

# First create a directory to save your configuration file
mkdir configs && cd configs

# For mainnet only
wget "https://github.com/bifrost-platform/bifrost-relayer.rs/releases/latest/download/config.mainnet.yaml"

# For testnet only
wget "https://github.com/bifrost-platform/bifrost-relayer.rs/releases/latest/download/config.testnet.yaml"

Configuration Setup

Next, the configuration YAML file contains certain parameters that the operator has to set. For instance, variables such as your relayer private key and each EVM provider's RPC endpoints depends to the operator itself, thus these values should be manually set.

You should prepare RPC endpoints for the following blockchain networks. There are two options for this: 1) operating your own blockchains nodes, or 2) utilizing services that offers RPC endpoints. You can find node providers on the links below. It’s crucial that each node must be archive-mode enabled.

Configuration Templates

config.mainnet.yaml
system:
  private_key: "<YOUR_RELAYER_PRIVATE_KEY>"
  keystore_path: "<YOUR_KEYSTORE_PATH>"
  keystore_password: "<YOUR_KEYSTORE_PASSWORD>"
  debug_mode: false

btc_provider:
  id: 10000
  chain: "main"
  provider: "<YOUR_BITCOIN_RPC_ENDPOINT>"
  call_interval: 10000
  block_confirmations: 2

evm_providers:
  - name: "bifrost"
    id: 3068
    provider: "<YOUR_BIFROST_RPC_ENDPOINT>"
    call_interval: 3000
    block_confirmations: 3
    is_native: true
    is_relay_target: true
    socket_address: "0xd551F33Ca8eCb0Be83d8799D9C68a368BA36Dd52"
    authority_address: "0x0000000000000000000000000000000000000400"
    relayer_manager_address: "0x0000000000000000000000000000000000002000"
    bitcoin_socket_address: "0x73A9E443F51eE40C1469A740D9CCf0118e8FD9ca"
    socket_queue_address: "0x0000000000000000000000000000000000000101"
    registration_pool_address: "0x0000000000000000000000000000000000000100"
    relay_executive_address: "0x0000000000000000000000000000000000000803"
  - name: "ethereum"
    id: 1
    provider: "<YOUR_ETHEREUM_RPC_ENDPOINT>"
    call_interval: 12000
    block_confirmations: 1
    is_relay_target: false
    eip1559: true
    socket_address: "0x4A31FfeAc276CC5e508cAC0568d932d398C4DD84"
    authority_address: "0xAdcaa90cabDc730855064d5b0f5242c16A9B7E10"
    chainlink_usdc_usd_address: "0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6"
    chainlink_usdt_usd_address: "0x3E7d1eAB13ad0104d2750B8863b489D65364e32D"
    chainlink_dai_usd_address: "0xAed0c38402a5d19df6E4c03F4E2DceD6e29c1ee9"
    chainlink_btc_usd_address: "0xf4030086522a5beea4988f8ca5b36dbc97bee88c"
    chainlink_wbtc_usd_address: "0xfdFD9C85aD200c506Cf9e21F1FD8dd01932FBB23"
    chainlink_cbbtc_usd_address: "0x2665701293fCbEB223D11A08D826563EDcCE423A"
  - name: "bsc"
    id: 56
    provider: "<YOUR_BSC_RPC_ENDPOINT>"
    call_interval: 3000
    block_confirmations: 5
    is_relay_target: false
    eip1559: true
    socket_address: "0xb5Fa48E8B9b89760a9f9176388D1B64A8D4968dF"
    authority_address: "0xF0500d77d5446665314722b963ab1F71872063E9"
  - name: "polygon"
    id: 137
    provider: "<YOUR_POLYGON_RPC_ENDPOINT>"
    call_interval: 2000
    block_confirmations: 7
    is_relay_target: false
    eip1559: true
    min_priority_fee: 30000000000
    socket_address: "0x050606CC2Bcd9504991Be2c309D6c6c832Bb5bd0"
    authority_address: "0x7F48909fBd1E38f1e05B5E326A44175fc2462B13"
  - name: "base"
    id: 8453
    provider: "<YOUR_BASE_RPC_ENDPOINT>"
    call_interval: 2000
    block_confirmations: 7
    is_relay_target: false
    eip1559: true
    socket_address: "0xAe172D8c5E428D4b7C70f9E593b207F9daC9BF3e"
    authority_address: "0x4C7a44F3FB37A53F33D3fe3cCdE97A444F105239"
  - name: "arbitrum"
    id: 42161
    provider: "<YOUR_ARBITRUM_ONE_RPC_ENDPOINT>"
    call_interval: 2000
    block_confirmations: 5
    get_logs_batch_size: 8
    is_relay_target: false
    eip1559: true
    socket_address: "0xac1552e30857A814a225BAa81145bcB071B46DDd"
    authority_address: "0xA069a57426Cd4c53925c1847Bec01aAB832A5118"

handler_configs:
  - handler_type: Socket
    watch_list: [3068, 1, 56, 137, 8453, 42161]
  - handler_type: Roundup
    watch_list: [3068]

###  The items below are optional. ###

bootstrap_config:
  is_enabled: true
  round_offset: 3
  btc_block_offset: 3

sentry_config:
  environment: "<YOUR_SENTRY_ENVIRONMENT>"
  is_enabled: false
  dsn: "<YOUR_SENTRY_DSN>"

prometheus_config:
  is_enabled: false
  is_external: false
  port: 8000
config.testnet.yaml
system:
  private_key: "<YOUR_RELAYER_PRIVATE_KEY>"
  keystore_path: "<YOUR_KEYSTORE_PATH>"
  keystore_password: "<YOUR_KEYSTORE_PASSWORD>"
  debug_mode: false

btc_provider:
  id: 10001
  chain: "test"
  provider: "<YOUR_BITCOIN_RPC_ENDPOINT>"
  call_interval: 10000

evm_providers:
  - name: "bifrost-testnet"
    id: 49088
    provider: "<YOUR_BIFROST_TESTNET_RPC_ENDPOINT>"
    call_interval: 3000
    block_confirmations: 3
    is_native: true
    is_relay_target: true
    socket_address: "0x0218371b18340aBD460961bdF3Bd5F01858dAB53"
    authority_address: "0x0000000000000000000000000000000000000400"
    relayer_manager_address: "0x0000000000000000000000000000000000002000"
    bitcoin_socket_address: "0xc292D9d5c31D5246cfAC67ba91202bbCF0AA8108"
    socket_queue_address: "0x0000000000000000000000000000000000000101"
    registration_pool_address: "0x0000000000000000000000000000000000000100"
    relay_executive_address: "0x0000000000000000000000000000000000000803"
  - name: "sepolia"
    id: 11155111
    provider: "<YOUR_SEPOLIA_RPC_ENDPOINT>"
    call_interval: 12000
    block_confirmations: 1
    is_relay_target: false
    eip1559: true
    socket_address: "0xdAcc4aeea580F782bB991eA862e1a57827Ea9D68"
    authority_address: "0xff95B9861eE5d44eC0b489B0DCB73932c7C7074B"
  - name: "bsc-testnet"
    id: 97
    provider: "<YOUR_BSC_TESTNET_RPC_ENDPOINT>"
    call_interval: 3000
    block_confirmations: 5
    is_relay_target: false
    eip1559: true
    socket_address: "0x8039c3AD8ED55509fD3f6Daa78867923fDe6E61c"
    authority_address: "0xCf9f6428A309b6652a1dfaA4d8aB8B61C9c7E8CF"
    chainlink_usdc_usd_address: "0x90c069C4538adAc136E051052E14c1cD799C41B7"
    chainlink_usdt_usd_address: "0xEca2605f0BCF2BA5966372C99837b1F182d3D620"
    chainlink_dai_usd_address: "0xE4eE17114774713d2De0eC0f035d4F7665fc025D"
    chainlink_btc_usd_address: "0x5741306c21795FdCBb9b265Ea0255F499DFe515C"
    chainlink_wbtc_usd_address: "0x5741306c21795FdCBb9b265Ea0255F499DFe515C"
  - name: "base-sepolia"
    id: 84532
    provider: "<YOUR_BASE_SEPOLIA_RPC_ENDPOINT>"
    call_interval: 2000
    block_confirmations: 7
    is_relay_target: false
    eip1559: true
    socket_address: "0xdAcc4aeea580F782bB991eA862e1a57827Ea9D68"
    authority_address: "0x15EDC0c65004548fa787Bc01e533366674946C5F"
  - name: "arbitrum-sepolia"
    id: 421614
    provider: "<YOUR_ARBITRUM_SEPOLIA_RPC_ENDPOINT>"
    call_interval: 2000
    block_confirmations: 5
    get_logs_batch_size: 8
    is_relay_target: false
    eip1559: true
    socket_address: "0xd1E060FD930B75DA9A709c91E6Ad03B330Fb2950"
    authority_address: "0x4dA97eCD85d4EE00E26C5f3aF21e6Da7bc3F71e2"

handler_configs:
  - handler_type: Socket
    watch_list: [49088, 11155111, 97, 84532, 421614]
  - handler_type: Roundup
    watch_list: [49088]

###  The items below are optional. ###

bootstrap_config:
  is_enabled: true
  round_offset: 3
  btc_block_offset: 3

sentry_config:
  environment: "<YOUR_SENTRY_ENVIRONMENT>"
  is_enabled: false
  dsn: "<YOUR_SENTRY_DSN>"

prometheus_config:
  is_enabled: false
  is_external: false
  port: 8000

Configuration Parameters

The following table presents customizable parameters for the relayer. You can change each parameter according to your environment. However, we highly recommend to use the default values specified in the template except for fields that are not checked in the "Template Provided" column. Furthermore, "Template Provided" merely serves as an example, thus you must change the correct values for certain parameters (e.g., your private key).

Generally, for safety and to prevent unexpected system malfunctions, you should refrain from altering parameters that are included in the YAML file but not explicitly specified. If the network's self-monitoring mechanism detects a malfunction stemming from altered parameters, the offending relayer may be subject to slashing.

Using Systemd

For operators who prefer on using Systemd, you should make a configuration file for the Systemd execution environment. First, create a configuration file in the following directory.

sudo vi /etc/systemd/system/bifrost-relayer.service

An example of the configuration is provided below. The following parameters should be set regarding to your setup environment.

  • <DIRECTORY_WHERE_BIFROST_RELAYER_LOCATES> : The absolute path to the directory where the installed bifrost-relayer binary file locates.

  • <PATH_TO_BIFROST_RELAYER> : The absolute path to the installed bifrost-relayer binary file.

  • <PATH_TO_CONFIG_FILE> : The absolute path to the installed config.testnet.yaml or config.mainnet.yaml. This parameter will be the the value for the CLI option, --chain.

[Unit]
Description=Bifrost Relayer Daemon
After=network.target
StartLimitIntervalSec=5

[Service]
Type=simple
Restart=always
RestartSec=30
SyslogIdentifier=bifrost-relayer
SyslogFacility=local7
WorkingDirectory=<DIRECTORY_WHERE_BIFROST_RELAYER_LOCATES>
ExecStart=<PATH_TO_BIFROST_RELAYER> --chain <mainnet|testnet|<PATH_TO_CONFIG_FILE>>
KillSignal=SIGHUP

[Install]
WantedBy=multi-user.target
Example
[Unit]
Description=Bifrost Relayer Daemon
After=network.target
StartLimitIntervalSec=5

[Service]
Type=simple
Restart=always
RestartSec=30
SyslogIdentifier=bifrost-relayer
SyslogFacility=local7
WorkingDirectory=/home/ubuntu/example
ExecStart=/home/ubuntu/example/bifrost-relayer --chain /home/ubuntu/example/config.yaml
KillSignal=SIGHUP

[Install]
WantedBy=multi-user.target

Run the Relayer Service

Now, the service can be started by executing the following commands. First, enable the service that will let it start automatically at every next system restart.

sudo systemctl enable bifrost-relayer

Then, start the Systemd service, executing instructions in the service’s configuration file, use the start command as mentioned below.

sudo systemctl start bifrost-relayer

And lastly, verify the service has successfully executed.

systemctl status bifrost-relayer

Check Logs

To check your running bifrost-relayer service logs, execute the command below.

journalctl -f -u bifrost-relayer

Once the service has successfully started, the initial logs will show up similar as below.

2023-08-04T14:41:38 INFO  sc_sysinfo     ]💻 Operating system: macos
2023-08-04T14:41:38 INFO  sc_sysinfo     ]💻 CPU architecture: aarch64
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] Bifrost Relayer
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] ✌️  version 1.0.2-1053ac84663
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] ❤️  by bifrost-platform, 2023-2023
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] ⛓  Chain specification: testnet
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] 👤 Relayer: 0xf708d58820fa20405993e186a8b38fb777f3143a
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] 🔨 Relay Targets (Legacy): bifrost, bsc
2023-08-04T14:41:38 INFO  bifrost-relayer]-[main               ] 🔨 Relay Targets (EIP1559): ethereum, polygon
2023-08-04T14:41:38 INFO  bifrost        ]-[block-manager      ] 💤 Idle, best: #8495214
2023-08-04T14:41:38 INFO  ethereum       ]-[block-manager      ] 💤 Idle, best: #9459619
2023-08-04T14:41:38 INFO  polygon        ]-[block-manager      ] 💤 Idle, best: #38621155
2023-08-04T14:41:38 INFO  bsc            ]-[block-manager      ] 💤 Idle, best: #32143709

If the bootstrap configuration is enabled, it will then start to bootstrap historical events as below.

2023-07-14T16:00:35 INFO  bifrost        ]-[roundup-handler    ] ⚙️  [Bootstrap mode] Bootstrapping RoundUp events.
2023-07-14T16:00:35 INFO  bsc            ]-[bridge-handler     ] ⚙️  [Bootstrap mode] Bootstrapping Socket events.
2023-07-14T16:00:35 INFO  bifrost        ]-[bridge-handler     ] ⚙️  [Bootstrap mode] Bootstrapping Socket events.
2023-07-14T16:00:35 INFO  mumbai         ]-[bridge-handler     ] ⚙️  [Bootstrap mode] Bootstrapping Socket events.
2023-07-14T16:00:35 INFO  goerli         ]-[bridge-handler     ] ⚙️  [Bootstrap mode] Bootstrapping Socket events.
2023-07-14T16:00:37 INFO  bifrost        ]-[bridge-handler     ] ⚙️  [Bootstrap mode] Bootstrapping Socket events.
2023-07-14T16:00:37 INFO  bifrost-relayer]-[bridge-handler     ] ⚙️  [Bootstrap mode] Bootstrap process successfully ended.

After the initial launch and the bootstrap process ends, the system will wait until each chain has reached the block confirmations specified in your configuration YAML file. It will then import every new block on every interval as below.

2023-08-04T14:41:54 INFO  polygon        ]-[block-manager      ] ✨ Imported #38621155
2023-08-04T14:41:56 INFO  bifrost        ]-[block-manager      ] ✨ Imported #8495214
2023-08-04T14:41:56 INFO  polygon        ]-[block-manager      ] ✨ Imported #38621156
2023-08-04T14:41:57 INFO  bsc            ]-[block-manager      ] ✨ Imported #32143709
2023-08-04T14:41:58 INFO  polygon        ]-[block-manager      ] ✨ Imported #38621157
2023-08-04T14:41:59 INFO  bifrost        ]-[block-manager      ] ✨ Imported #8495215
2023-08-04T14:42:00 INFO  bsc            ]-[block-manager      ] ✨ Imported #32143710
2023-08-04T14:42:00 INFO  polygon        ]-[block-manager      ] ✨ Imported #38621158
2023-08-04T14:42:02 INFO  ethereum       ]-[block-manager      ] ✨ Imported #9459619
2023-08-04T14:42:02 INFO  bifrost        ]-[block-manager      ] ✨ Imported #8495216
2023-08-04T14:42:02 INFO  polygon        ]-[block-manager      ] ✨ Imported #38621159
2023-08-04T14:42:03 INFO  bsc            ]-[block-manager      ] ✨ Imported #32143711

If your relayer has met every system logs mentioned above, this means that it has successfully been launched and has started to operate in a healthy state.

Upgrade Service

As the bifrost-relayer is under continuous development, there will be instances when it becomes necessary to upgrade your relayer service. When such upgrades become available, relayer operators will be notified either through our community channels or via direct communication. Please note that some upgrades may be optional rather than mandatory.

First, remove or backup the previous bifrost-relayer binary file.

rm <PATH_TO_BIFROST_RELAYER_BINARY>

Then, install the latest version of bifrost-relayer into the same directory and update permissions. (In case of directory changes, the Systemd configuration file should be modified as well)

chmod +x bifrost-relayer

At last, restart the Systemd service.

sudo systemctl restart bifrost-relayer

Using Docker

For operators who prefer on using Docker, it must be pre-installed in your operating system. Once installed, you can proceed to the following steps.

To run the relayer as a Docker container, use the command as mentioned below.

  • <DIRECTORY_WHERE_CONFIG_FILE_LOCATES> : The absolute path of the directory where the installed config.testnet.yaml or config.mainnet.yaml locates.

  • <YOUR_CONFIG_FILE_NAME> : The file name of the installed configuration YAML file.

  • <YOUR_CONTAINER_NAME> : Please set an explicit name for your relayer container.

docker run -d \
  --restart always \
  --network host \
  --mount type=bind,source=<DIRECTORY_WHERE_CONFIG_FILE_LOCATES>,target=/relayer/configs \
  --name <YOUR_CONTAINER_NAME> \
  thebifrost/bifrost-relayer.rs:latest --chain /relayer/configs/<YOUR_CONFIG_FILE_NAME>
Example
docker run -d \
  --restart always \
  --network host \
  --mount type=bind,source=/home/ubuntu/example,target=/relayer/configs \
  --name bifrost-relayer \
  thebifrost/bifrost-relayer.rs:latest --chain /relayer/configs/config.mainnet.yaml

Check Logs

To check your running bifrost-relayer container logs, execute the command below.

docker logs -f <YOUR_CONTAINER_NAME>

Upgrade Docker Image

As the bifrost-relayer is under continuous development, there will be instances when it becomes necessary to upgrade your relayer service. When such upgrades become available, relayer operators will be notified either through our community channels or via direct communication. Please note that some upgrades may be optional rather than mandatory.

First stop and remove your running relayer container.

docker stop "YOUR_CONTAINER_NAME"
docker rm "YOUR_CONTAINER_NAME"

Then, pull the latest bifrost-relayer Docker image.

docker pull thebifrost/bifrost-relayer.rs:latest

At last execute the following command below to start a new container.

docker run -d \
  --restart always \
  --network host \
  --mount type=bind,source=<DIRECTORY_WHERE_CONFIG_FILE_LOCATES>,target=/relayer/configs \
  --name <YOUR_CONTAINER_NAME> \
  thebifrost/bifrost-relayer.rs:latest --chain /relayer/configs/<YOUR_CONFIG_FILE_NAME>

Parameter Descriptions

Name
Description
Example / Available Values
Required
Template Provided
Default

system

System related parameters of the relayer.

-

-

system.private_key

The private key of the relayer.

"0x5fb92d6e98884f76de468fa3f6278f8807c48bebc13595d45af5bdc4da702133"

-

system.debug_mode

The flag that represents if the debug mode is enabled. If enabled, debug-level logs and sentry alerts will be enabled.

true / false

false

btc_provider

The parameters related to the Bitcoin chain provider.

-

-

btc_provider.id

The unique ID of the Bitcoin chain.

  • 10000 (For Mainnet)

  • 10001 (For Testnet)

-

btc_provider.chain

The name of the Bitcoin chain.

  • "main" (For Mainnet)

  • "test" (For Testnet)

-

btc_provider.provider

The RPC endpoint of the Bitcoin chain.

-

-

btc_provider.call_interval

The block synchronization interval in milliseconds. At every new interval, the system will synchronize every new block mined on the target chain.

10000

-

btc_provider.block_confirmations

The number of block confirmations required to synchronize a new block.

3

3

evm_providers

The parameters related to EVM chain providers.

-

-

evm_providers.id

The unique ID of the chain.

3068

-

evm_providers.name

The name of the chain.

"bifrost"

-

evm_providers.provider

The RPC endpoint of the node. If the node is running, or is expected to be operated on the same server with the relayer, then set this value to the provided example.

"http://127.0.0.1:9933"

-

evm_providers.call_interval

The block synchronization interval in milliseconds. At every new interval, the system will synchronize every new block mined on the target chain.

1500

-

evm_providers.block_confirmations

The number of block confirmations required to synchronize a new block.

5

-

evm_providers.is_relay_target

The flag which represents whether the system will participate in external-chain CCCP actions. If this value is set to true, the system will try to execute transactions on the target chain, so sufficient balances are required. This value must be set to true if it is the Bifrost Network.

true / false

-

evm_providers.eip1559

The flag which represents whether the system will execute EIP-1559 transactions. If set to false, transactions will be executed by legacy types.

true / false

false

evm_providers.min_gas_price

The minimum gas price (in WEI) that the system will setup when executing legacy transactions. If the value is null, it will be dynamically set. This field only has effect when the eip1559 parameter is disabled.

30000000000

0

evm_providers.min_priority_fee

The minimum priority fee (in WEI) that the system will setup when executing EIP-1559 transactions. If the value is null, it will be dynamically set. This field only has effect when the eip1559 parameter is enabled.

30000000000

0

evm_providers.escalate_percentage

The percentage that will be used on gas price escalation to replace a transaction that is stuck in the mempool. This option will only have effect for legacy transactions.

15.0

15.0

evm_providers.is_initially_escalated

The flag whether if the gas price will be initially escalated. The escalate_percentage will be used on escalation. This option will only have effect for legacy transactions.

true / false

false

evm_providers.get_logs_batch_size

The batch size (=block range) used when requesting eth_getLogs(). If increased the RPC request ration will be reduced, however event processing will be delayed regarded to the configured value. Default size is set to 1, which means it will be requested on every new block.

5

1

sentry_config

Sentry related parameters. If this section does not exist in your configuration file, Sentry will be disabled.

-

None

sentry_config.is_enabled

The flag which represents whether Sentry is enabled.

-

-

sentry_config.environment

The identifier for the Sentry client. This value will be used to distinguish triggered alarms.

"mainnet"

""

sentry_config.dsn

The Sentry DSN. If the value has been set, error and warning alerts will be notified. If the value is empty, Sentry will be disabled.

-

-

prometheus_config

Prometheus related parameters. It this section does not exist in your configuration file, Prometheus will be disabled.

-

None

prometheus_config.is_enabled

The flag which represents whether Prometheus metric collection is enabled.

true / false

-

prometheus_config.is_external

The flag which represents whether the Prometheus server is exposed on all interfaces.

true / false

false

prometheus_config.port

The Prometheus exporter TCP port.

8000

8000

bootstrap_config

Bootstrap related parameters. Bootstrap is a process that will be executed whenever the relayer (re-)starts. It will collect historical CCCP events and let the relayer re-handle the event to prevent missed actions.

-

None

bootstrap_config.is_enabled

The flag which represents whether bootstrap is enabled

true / false

-

bootstrap_config.round_offset

The amount of rounds to search for missed events.

3

3

PreviousSetting up a RelayerNextbifrost-relayer.py (Legacy)

Last updated