Bifrost Relayer Release Report v2.1.1

BIFROST-Team · June 12, 2025, 6:02am

This report outlines a set of notable changes that significantly impact the Bifrost Network. To improve readability, these updates are categorized into High Impact, Medium Impact, and Low Impact based on their level of significance.

For detailed instructions on setting up your Relayer, please refer to our official documentation.

1. Summary

This report summarizes the latest updates to the Bifrost Network’s CCCP Relayer. The key enhancement is the integration of AWS KMS for transaction signing and keystore encryption, significantly improving security and reliability.

The Rust library ethers-rs, previously used for interacting with Ethereum and other EVM-based chains, has been fully replaced with alloy, leading to better performance and code maintainability.

This release also includes minor features and bug fixes to enhance overall stability and functionality.

Client Upgrade

V2.0.0 → V2.1.1

Important Notice: If you are operating a Relayer on Bifrost Mainnet or Testnet, it is strongly recommended to upgrade your client and configurations to ensure compatibility and optimal performance. Details regarding the necessary configuration updates can be found in the “Configuration Update” section below.

2. Key Takeaways

2.1. High Impact

2.1.1. Support for AWS KMS Signer

Ref: CCCP-475 integrate aws-kms by alstjd0921 · Pull Request #170 · bifrost-platform/bifrost-relayer.rs

Previously, configuring a Bifrost relayer required specifying an account’s private key in the config.yaml file to sign CCCP-related relay transactions. While this approach simplified relayer setup by avoiding external dependencies, it posed a significant security risk by exposing the private key in plaintext, making the account vulnerable to unauthorized access.

To address this, transaction signing can now be delegated to AWS KMS, eliminating the need for local key storage. When enabled, the private key is no longer required in config.yaml, greatly reducing the risk of exposure. For simplicity and broader use cases, local signing remains available as an alternative.

Important Notice

To enable this feature requires an external dependency: an asymmetric sign and verification AWS KMS key.
There are critical changes to the config.yaml file in this update. Please refer to the “Configuration Update” section below for detailed information on the required modifications.

2.1.2. Support for AWS KMS Keystore Encryption

Ref: CCCP-488, support kms integrated keystore by dnjscksdn98 · Pull Request #171 · bifrost-platform/bifrost-relayer.rs

Relay executives, also known as Bitcoin relayers, carry additional responsibilities within the Bitcoin Relay Protocol (BRP). They are authorized to manage a local key-value database—referred to as the keystore—which stores keypairs for multi-signature vault accounts.

Previously, the keystore supported optional encryption using a password. However, this password had to be specified in the config.yaml file, introducing a significant security risk due to plaintext storage.

To improve security, the system now supports delegating keystore encryption and decryption to AWS KMS, removing the need for local password storage. When this feature is enabled, the password is no longer required in config.yaml.

For added flexibility, local encryption and decryption options are still available to support alternative use cases.

Important Notice

To enable this feature requires an external dependency: a symmetric encryption and decryption AWS KMS key.
There are critical changes to the config.yaml file in this update. Please refer to the “Configuration Update” section below for detailed information on the required modifications.

2.1.3. Migrate `ethers-rs` to `alloy`

Ref: [CCCP-295] Migrate to alloy by alstjd0921 · Pull Request #168 · bifrost-platform/bifrost-relayer.rs

Previously, the Rust library ethers-rs, which enabled interactions with Ethereum and other EVM-based chains for the Bifrost relayer, was deprecated and is no longer maintained. It has now been replaced with Alloy, a modern, modular library that offers essential interfaces and improved performance.

This migration not only increases execution efficiency but also promotes long-term maintainability by adopting an actively maintained framework. Alloy’s optimized architecture reduces unnecessary dependencies and enhances compatibility with evolving EVM standards. Its well-structured design also streamlines future upgrades and maintenance, resulting in a more robust and future-proof codebase for the Bifrost relayer.

2.2. Medium Impact

2.2.1. Newly Supported Chains and Asset

Ref:

As part of this update, CCCP has expanded its interoperability by adding support for additional blockchain networks and asset. These new integrations enhance cross-chain functionality, improve transaction efficiency, and strengthen the overall ecosystem.

The newly supported chains and asset are:

Chain Name Native Coin Symbol References
CORE Mainnet CORE * https://coredao.org/
Oasys Mainnet OAS * Oasys The Blockchain for Asia and Beyond

Asset Symbol	Available Networks	References
`cbBTC`	Bifrost ↔︎ Base	* Coinbase cbBTC

2.3. Low Impact

2.3.1. Bump Dependencies and Migrate Rust to Edition 2024

Ref: CCCP-488, support kms integrated keystore by dnjscksdn98 · Pull Request #171 · bifrost-platform/bifrost-relayer.rs

In this release, we have performed a comprehensive dependency bump and migrated the codebase to Rust Edition 2024 to ensure improved performance, security, and long-term maintainability. Upgrading dependencies to their latest stable versions helps reduce technical debt, leverage optimizations, and incorporate important bug fixes from upstream libraries. Additionally, migrating to Rust 2024 brings enhanced language features, improved async support, and stricter compiler diagnostics, leading to more efficient and maintainable code. This transition future-proofs the project, ensuring compatibility with the latest Rust ecosystem advancements while maintaining stability and performance.

3. Process to update relayer client

3.1. Binary Update

Please follow the steps below to update your relayer client.

Step 1.

Update your config.yaml file according to the instructions in the “Configuration Update” section below.

Step 2.

Remove or create a backup of the previous bifrost-relayer binary file before proceeding.

rm <PATH_TO_BIFROST_RELAYER_BINARY>

Step 3.

Install the latest version of bifrost-relayer in the same directory and update the necessary permissions. (Note: If the directory has changed, be sure to update the Systemd configuration file accordingly)

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

Step 4.

At last, restart the Systemd service to apply the changes.

sudo systemctl restart bifrost-relayer

3.2. Configuration Update

config.mainnet.yaml: link.

config.testnet.yaml: link.

3.2.1. Provider Configurations

3.2.1.1. Removed Options

Previously, for customized transaction building and sending, we provided several options that could be added to each provider item in the evm_providers section. These options were designed to prevent transactions from getting stuck in the mempool and to maximize the likelihood of inclusion in a block.

From now on, the relayer will handle pending transactions internally. As a result, the following options have been removed:

min_gas_price
min_priority_fee
escalate_percentage
is_initially_escalated
duplicate_confirm_delay

If any of your provider items contain the mentioned options, please remove them to ensure compatibility with the latest update.

3.2.1.2. Newly Supported Chains

If you are currently running on the Bifrost Testnet, you can skip this section. This section is only for the Bifrost Mainnet.

CORE and Oasys Mainnet have been added to CCCP to expand its interoperability. To integrate these chains, follow these steps:

Add them as provider items in your evm_providers section. Furthermore, RPC nodes are required for each chain and each node must be archive-mode enabled. Check out the listed third-party RPC providers:
CORE
Oasys
Include each chain ID in the handler_configs.watch_list array as shown below:

evm_providers:
  # -----> ✅ Add CORE and Oasys here.
  - name: "core"
    id: 1116
    provider: "<YOUR_CORE_RPC_ENDPOINT>"
    call_interval: 3000
    block_confirmations: 3
    is_relay_target: false
    eip1559: false
    socket_address: "0x4C7a44F3FB37A53F33D3fe3cCdE97A444F105239"
    authority_address: "0xA069a57426Cd4c53925c1847Bec01aAB832A5118"
  - name: "oasys"
    id: 248
    provider: "<YOUR_OASYS_RPC_ENDPOINT>"
    call_interval: 6000
    block_confirmations: 3
    is_relay_target: false
    eip1559: true
    socket_address: "0x4C7a44F3FB37A53F33D3fe3cCdE97A444F105239"
    authority_address: "0x48820089C1d4f5d768f6800CF647b4f5b8675CFA"
handler_configs:
  - handler_type: Socket
    # -----> ✅ Add 1116 and 248 here.
    watch_list: [3068, 1, 56, 137, 8453, 42161, 1116, 248]
  - handler_type: Roundup
    watch_list: [3068]

This ensures proper monitoring and transaction handling for the newly supported chains.

3.2.2. Signer Configurations

The method for specifying and configuring the signer has changed. Previously, it was configured as follows:

system:
  private_key: "0xxxx...xxx"

However, the configuration has now changed. The private key from the system section has been removed. Instead, you must explicitly specify a signer_config, which can contain either:

A plaintext private key
An AWS KMS key

Below is the updated configuration format:

system:
  # -----> ❌ Private key removed from here
# Option 1. When using AWS KMS signer
signer_config:
  - kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# Option 2. When using local signer with plaintext private key
signer_config:
  - private_key: "0xxxx...xxx"

3.2.3. Keystore Configurations

If you currently don’t have a keystore configured, you can skip this section.

The method for specifying and configuring the keystore has changed. Previously, it was configured as follows:

system:
  keystore_path: "./example"
  keystore_password: "password"

However, the configuration has now changed. The path and password from the system section have been removed. Instead, you must explicitly specify a keystore_config, which includes:

The keystore path
Either a plaintext password or an AWS KMS key