Relay Executives: Keystore Migration

This guide outlines the steps to migrate your local keystore to the new encryption and decryption mechanism.

🔹 If you do not have a keystore configured, you can skip this section.

Due to differences between relayer client versions, the migration steps may vary depending on your current 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 migrate your keystore, 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

1.2.1. 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"

1.2.2. Keystore Configurations

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

  • ⚠️ Important: At this step, you must enter your previously used password to proceed with the migration.

Below is the updated configuration format:

system:
  # -----> ❌ path and password removed from here

keystore_config:
  path: "./example"
  password: "password"  # -----> ⚠️ Important: Enter your previously used password

1.3. Run the Migration CLI Command: migrate-keystore

Before proceeding with the migration, 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

1.3.1. Fetch the latest BRP Round

And then, you need to fetch the latest BRP (Bitcoin Relay Protocol) round. To do so, run the following command:

Mainnet

curl --location 'https://public-01.mainnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":0,"method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000100","data":"0x319c068c"}]}'

Example Output:

{
    "jsonrpc": "2.0",
    "result": "0x0000000000000000000000000000000000000000000000000000000000000002",
    "id": 0
} # -----> ✅ The latest round is 2

Testnet

curl --location 'https://public-01.testnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":0,"method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000100","data":"0x319c068c"}]}'

Example Output:

{
    "jsonrpc": "2.0",
    "result": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "id": 0
} # -----> ✅ The latest round is 1

Now you have two options for migrating your keystore encryption:

1. Keystore encrypted by a plaintext password

2. Keystore encrypted by AWS KMS

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

1.3.2. Option 1: Password Encrypted Keystore

To migrate your keystore, run the following command with the necessary options:

• chain: Specify the path to your config.yaml file.

• round: Enter the round index you fetched in the previous step.

• new-password: Set a new plaintext password for encrypting and decrypting keystore keys.

  • 🚨 We highly recommend using a new password for better security.

• version: This option must be set to 1 at this step.

⚠️ Important: Before running the command, your previously used password must be specified in the config.yaml file for the migration to succeed.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
./bifrost-relayer migrate-keystore \
    --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
    --round <THE_POOL_ROUND_TO_MIGRATE> \
    --new-password "<YOUR_NEW_PASSWORD>" \
    --version 1

If the command successfully worked, replace keystore_config.password with your newly set password in the config.yaml file.

keystore_config:
  path: "./example"
  password: "new-password"  # -----> Replace this to your new password

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

1.3.3. Option 2: AWS KMS Encrypted Keystore

To migrate your keystore, run the following command with the necessary options:

• chain: Specify the path to your config.yaml file.

• round: Enter the round index you fetched in the previous step.

• new-kms-key-id: Set a new AWS KMS key ID for encrypting and decrypting keystore keys.

• version: This option must be set to 1 at this step.

⚠️ Important: Before running the command, your previously used password must be specified in the config.yaml file for the migration to succeed.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
./bifrost-relayer migrate-keystore \
    --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
    --round <THE_POOL_ROUND_TO_MIGRATE> \
    --new-kms-key-id "<YOUR_NEW_KMS_KEY_ID>" \
    --version 1

If the command successfully worked, remove keystore_config.password and add keystore_config.kms_key_id, then set it to your new AWS KMS key ID in the config.yaml file.

keystore_config:
  path: "./example"
  kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  # -----> Remove password and add 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

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

2.1. Binary Update

To migrate your keystore, 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. Run the Migration CLI Command: migrate-keystore

Before proceeding with the migration, 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

2.2.1. Fetch the latest BRP Round

And then, you need to fetch the latest BRP (Bitcoin Relay Protocol) round. To do so, run the following command:

Mainnet

curl --location 'https://public-01.mainnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":0,"method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000100","data":"0x319c068c"}]}'

Example Output:

{
    "jsonrpc": "2.0",
    "result": "0x0000000000000000000000000000000000000000000000000000000000000002",
    "id": 0
} # -----> ✅ The latest round is 2

Testnet

curl --location 'https://public-01.testnet.bifrostnetwork.com/rpc' --header 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":0,"method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000100","data":"0x319c068c"}]}'

Example Output:

{
    "jsonrpc": "2.0",
    "result": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "id": 0
} # -----> ✅ The latest round is 1

Now you have two options for migrating your keystore encryption:

1. Keystore encrypted by a plaintext password

2. Keystore encrypted by AWS KMS

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

2.2.2. Option 1: Password Encrypted Keystore

To migrate your keystore, run the following command with the necessary options:

• chain: Specify the path to your config.yaml file.

• round: Enter the round index you fetched in the previous step.

• new-password: Set a new plaintext password for encrypting and decrypting keystore keys.

  • 🚨 We highly recommend using a new password for better security.

⚠️ Important: Before running the command, your previously used password or AWS-KMS key ID must be specified in the config.yaml file for the migration to succeed.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
./bifrost-relayer migrate-keystore \
    --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
    --round <THE_POOL_ROUND_TO_MIGRATE> \
    --new-password "<YOUR_NEW_PASSWORD>"

If the command successfully worked, update your config.yaml file as follows:

• If you previously had keystore_config.password, replace it with your newly set password.

• If you previously had keystore_config.kms_key_id, remove it and add keystore_config.password, then set it to your new password.

keystore_config:
  path: "./example"
  password: "new-password"  # -----> Add or replace this to your new password

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

2.2.3. Option 2: AWS KMS Encrypted Keystore

To migrate your keystore, run the following command with the necessary options:

• chain: Specify the path to your config.yaml file.

• round: Enter the round index you fetched in the previous step.

• new-kms-key-id: Set a new AWS KMS key ID for encrypting and decrypting keystore keys.

⚠️ Important: Before running the command, your previously used password or AWS-KMS key ID must be specified in the config.yaml file for the migration to succeed.

# Add sudo at the beginning if it doesn't work (i.e. Permission Denied)
./bifrost-relayer migrate-keystore \
    --chain "<YOUR_CONFIG_YAML_FILE_PATH>" \
    --round <THE_POOL_ROUND_TO_MIGRATE> \
    --new-kms-key-id "<YOUR_NEW_KMS_KEY_ID>"

If the command successfully worked, update your config.yaml file as follows:

• If you previously had keystore_config.kms_key_id, replace it with your newly set key ID.

• If you previously had keystore_config.password, remove it and add keystore_config.kms_key_id, then set it to your new key ID.

keystore_config:
  path: "./example"
  kms_key_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  # -----> Add or replace this to your new 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