> For the complete documentation index, see [llms.txt](https://docs.bifrostnetwork.com/bifrost-network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bifrostnetwork.com/bifrost-network/running-a-node/relayer-management/relay-executives-keystore-migration.md).

# 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 <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)*

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

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

```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 <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)*

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

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

```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
```