# 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: ```sh ./bifrost-relayer --version ``` Example Output: ```sh 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. ```sh rm ``` **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)* ```sh 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```sh # 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** ```sh 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: ```json { "jsonrpc": "2.0", "result": "0x0000000000000000000000000000000000000000000000000000000000000002", "id": 0 } # -----> ✅ The latest round is 2 ``` **Testnet** ```sh 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: ```json { "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. ```sh # Add sudo at the beginning if it doesn't work (i.e. Permission Denied) ./bifrost-relayer migrate-keystore \ --chain "" \ --round \ --new-password "" \ --version 1 ``` If the command successfully worked, replace `keystore_config.password` with your newly set password in the config.yaml file. ```sh 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. ```sh # 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. ```sh # Add sudo at the beginning if it doesn't work (i.e. Permission Denied) ./bifrost-relayer migrate-keystore \ --chain "" \ --round \ --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. ```yaml 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. ```sh # 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. ```sh rm ``` **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)* ```sh 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: ```sh # 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** ```sh 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: ```json { "jsonrpc": "2.0", "result": "0x0000000000000000000000000000000000000000000000000000000000000002", "id": 0 } # -----> ✅ The latest round is 2 ``` **Testnet** ```sh 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: ```json { "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. ```sh # Add sudo at the beginning if it doesn't work (i.e. Permission Denied) ./bifrost-relayer migrate-keystore \ --chain "" \ --round \ --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. ```yaml 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. ```sh # 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. ```sh # Add sudo at the beginning if it doesn't work (i.e. Permission Denied) ./bifrost-relayer migrate-keystore \ --chain "" \ --round \ --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. ```yaml 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. ```sh # Add sudo at the beginning if it doesn't work (i.e. Permission Denied) systemctl restart bifrost-relayer.service ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bifrostnetwork.com/bifrost-network/running-a-node/relayer-management/relay-executives-keystore-migration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.