Relayer Account Update

This guide will walk you through the process of updating your relayer account to a new one, derived from either:

  • a plaintext private key, or

  • an AWS KMS key.

Note that migration steps may vary depending on your current relayer client version. To check your client version, run the following command:

./bifrost-relayer --version

Example Output:

bifrost-relayer 2.1.1-1b4f8ca012b

1. For Relayer Client versions below v2.1.1

1.1. Binary Update

To update your relayer account, follow the steps below to update your relayer client to the latest version:

Step 1.

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

rm <PATH_TO_BIFROST_RELAYER_BINARY>

Step 2.

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

1.2. Configuration Update

Before proceeding with the update, you have to first stop the running relayer. To do so, run the following command:

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
systemctl stop bifrost-relayer.service

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

  • ⚠️ Important: At this step, you must enter your previously used private key to proceed update.

Below is the updated configuration format:

system:
  # -----> ❌ Private key removed from here

signer_config:
  - private_key: "0xxxx...xxx"
  # -----> ⚠️ Important: Enter your previously used private key

Now you have two options to update your relayer account:

  • A new account derived by a plaintext private key

    • Whenever the relayer needs to sign a message or transaction, it will use this key for signing.

  • A new account derived by an AWS KMS key

    • Whenever the relayer needs to sign a message or transaction, it will delegate the signing request to the configured AWS KMS, ensuring secure and hardware-backed key management.

    • 🚨 We highly recommend using a AWS KMS for better security.

Choose the option that best fits your security requirements and follow the corresponding steps.

1.2.1. Option 1: Private Key Derivation

To update your relayer account to a new account derived from a private key, simply add the new key to the signer_config section in your config.yaml file.

  • ⚠️ Important: At this step, you must retain your previously used private key to proceed update.

signer_config:
  - private_key: "0xxxx...xxx"  # -----> Retain your current private key
  - private_key: "0xxxx...xxx"  # -----> Enter your new private key

Now it’s fully set to go. You can now restart your relayer.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
systemctl restart bifrost-relayer.service

Once it successfully restarts, follow section #3 to request an account update.

1.2.2. Option 1: AWS KMS Key Derivation

To update your relayer account to a new account derived from an AWS KMS key, simply add the new key ID to the signer_config section in your config.yaml file.

  • ⚠️ Important: At this step, you must retain your previously used private key to proceed update.

signer_config:
  - private_key: "0xxxx...xxx"  # -----> Retain your current private key
  - kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # -----> Enter your new AWS KMS key ID

Now it’s fully set to go. You can now restart your relayer.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
systemctl restart bifrost-relayer.service

Once it successfully restarts, follow section #3 to request an account update.

2. For Relayer Client versions higher than or equal to v2.1.1

2.1. Binary Update

To update your relayer account, follow the steps below to update your relayer client to the latest version:

Step 1.

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

rm <PATH_TO_BIFROST_RELAYER_BINARY>

Step 2.

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

2.2. Configuration Update

Now you have two options to update your relayer account:

  • A new account derived by a plaintext private key

    • Whenever the relayer needs to sign a message or transaction, it will use this key for signing.

  • A new account derived by an AWS KMS key

    • Whenever the relayer needs to sign a message or transaction, it will delegate the signing request to the configured AWS KMS, ensuring secure and hardware-backed key management.

    • 🚨 We highly recommend using a AWS KMS for better security.

Choose the option that best fits your security requirements and follow the corresponding steps.

2.2.1. Option 1: Private Key Derivation

To update your relayer account to a new account derived from a private key, simply add the new key to the signer_config section in your config.yaml file.

  • ⚠️ Important: At this step, you must retain your previously used private key or AWS KMS key ID to proceed update.

signer_config:
  - private_key: "0xxxx...xxx"  # -----> Retain your current private key or AWS KMS key ID
  - private_key: "0xxxx...xxx"  # -----> Enter your new private key

Now it’s fully set to go. You can now restart your relayer.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
systemctl restart bifrost-relayer.service

Once it successfully restarts, follow section #3 to request an account update.

2.2.2. Option 1: AWS KMS Key Derivation

To update your relayer account to a new account derived from an AWS KMS key, simply add the new key ID to the signer_config section in your config.yaml file.

  • ⚠️ Important: At this step, you must retain your previously used private key or AWS KMS key ID to proceed update.

signer_config:
  - private_key: "0xxxx...xxx"  # -----> Retain your current private key
  - kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # -----> Enter your new AWS KMS key ID

Now it’s fully set to go. You can now restart your relayer.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
systemctl restart bifrost-relayer.service

Once it successfully restarts, follow section #3 to request an account update.

3. Request Account Update

3.1. Prerequisites

Now you have to request an account update to the Bifrost network. To do so, you can simply send an extrinsic through the polkadot.js app page.

Mainnet

Testnet

link.

link.

When you enter the page, you have to first register your validator’s Controller account to the page. Please follow this guide to setup your Controller account.

Before proceeding, make sure your new relayer account is properly set up and has sufficient funds to perform cross-chain actions.

⚠️ Note: You do not need to transfer the entire balance from your current account, as it still requires funds for ongoing operations.

3.2. Send Extrinsic: setRelayer()

Now to send a request to update your relayer account, proceed with the following steps in order.

  1. First, access the polkadot.js web page and move on to the extrinsics tab. In prior, your controller account must be registered to polkadot.js

  2. Select your own controller account.

  3. Select the relayManager pallet.

  4. Select the setRelayer() extrinsic.

  5. Set the new parameter to your new account.

  6. Click on the "Submit Transaction" button and send the transaction by entering your password and signing.

Once the extrinsic has been successfully executed and included in a block, the account replacement will take effect in the next staking round. You can simply check the remaining staking round time in our explorer page.

3.3. After Staking Round Update

Once the current staking round ends, your relayer account will be successfully replaced.

To confirm that the update was successful:

  1. Go to our explorer page.

  2. Check if your new account is actively sending transactions.

When the update is confirmed, you can remove your previous private key or AWS KMS key ID from your config.yaml file. This ensures that only the new relayer account is used for signing transactions.

⚠️ Note: You can now transfer the entire balance from your previous account to your new account, as it will no longer perform any operations.

PreviousRelay Executives: Keystore MigrationNextGuide for Operators

Last updated