# Rail wallet rotation

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-rotation
Contain the rail wallet, work the rotation checklist, request and decide completion, and recover an unbooked delegate cash-out.

Rotate the bank rail wallet from **Settings** on a [Bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) token page whenever the signing key is compromised or lost. See the [rail wallet incident runbook](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident) for full incident coordination across roles.

![Settings tab of a bank rail token with Token, Network, Supply mode, Link state, Rail wallet, Rail wallet identity and Redemption approval threshold, and the Mint limits fields below](https://docs.settlemint.com/docs/screenshots/console-bank-rail-settings.light.en.webp)

[Screenshot] The "Settings" tab of a bank rail token lists "Token", "Network", "Supply mode", "Link state", "Rail wallet", "Rail wallet identity" and "Redemption approval threshold", with "Mint limits" below.

## Before you start [#before-you-start]

- **Bank rail manager role.** Required to contain the wallet, request completion or abandon a lost-key rotation (a second manager approves when **Bank rail** approval is on).
- **Token and system role holders ready.** Rotation requires token admins or governors (revoke and grant supply authority), token custodians (empty old escrow and move suspense), an **Identity manager** and an **Escrow manager** (for **Supply delegate** links).

## Rotate the rail wallet [#rotate-the-rail-wallet]

Open **Asset lifecycle** → **Bank rail**, select the token and open **Settings**. The **Rail wallet** card displays **Generation**, **State** ("Active", "Staged", "Contained" or "Retired") and **Address**. In **Supply delegate** mode, the **Escrow** card below shows **Controller wallet** with the "Rail wallet" badge.

### Contain the wallet [#contain-the-wallet]

1. Select **Contain rail wallet**.
2. Choose **Compromised** or **Lost**, add an optional note, review **What happens** and select **Contain rail wallet**.

Containment stops DALP from signing with the old key, suspends every linked token and stages a replacement wallet. Because a compromised key still retains on-chain authority until revoked, revoke supply authority and empty the old escrow first. On a "Lost" rotation, **Report compromised** escalates immediately and irreversibly to compromised. See [Money in flight](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident#money-in-flight) for how pending credits and cash-outs behave.

### Work the checklist [#work-the-checklist]

The **Rotation checklist** orders every step and marks each "Done", "Yours to do", "Waiting on", "Blocked by", "Not applicable" or "Failed", highlighting **Next** on the active blocker.

- Use **Copy link** on a step to send the exact screen URL to the responsible role holder.
- Use each step's deep link (**Open the token's permissions**, **Open the token's holders**, **Go to the escrow** or **Register rail wallet identity** for dual **Identity manager** + **Bank rail manager** accounts).
- If you hold the token role yourself, run **Revoke authority** or **Grant authority** directly from the checklist and confirm with your PIN.

See [Actions](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident#actions) and [Role steps](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident#role-steps) for exact order and pre-sign checks.

### Request and decide completion [#request-and-decide-completion]

1. Wait until every prerequisite step shows "Done" and no blocker appears under **Request completion** (see [What blocks completion](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident#what-blocks-completion)).
2. Select **Request completion**.
3. When **Bank rail** approval is on, a second **Bank rail manager** reviews **Old wallet**, **New wallet** and affected links and selects **Approve** (or **Reject** with a reason so the requester can select **Request again**). With the row off, approval applies immediately.

Completion transfers all token links, open credits and signing to the new wallet atomically. Credits parked during containment mint automatically from the new wallet, while open allocate/return or mint-approval requests reset and must be requested again.

For a **Lost** key, a manager can select **Request abandon** only while no revoke or grant has been submitted and all tokens remain with the old wallet (see [Lost key](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident#lost-key)). Compromised rotations cannot be abandoned.

### Read both wallets on the reconciliation page [#read-both-wallets-on-the-reconciliation-page]

During rotation, **Rail wallets** on **Reconciliation** lists each wallet's role ("Current rail wallet", "Next rail wallet", "Contained rail wallet" or "Previous rail wallet"), supply authority and balance. After completion, the retired wallet stays in history, and any residual balance on a frozen retired wallet opens an operations case rather than a "Break".

### Recover an unbooked delegate cash-out [#recover-an-unbooked-delegate-cash-out]

If a compromised escrow leaves a **Supply delegate** cash-out "Unbooked" (bank paid, tokens unburnt):

1. Have a token custodian forced-transfer the locked tokens from the old escrow to the rail wallet.
2. On **Cash-outs**, select **Recover** on the "Unbooked" row to record the transfer and burn the units ("The rail wallet is burning the recovered units.").
3. Once the burn confirms, status moves to "Paid". If only a partial amount was recovered, **Recover** reappears after that burn for the next forced transfer.

## You should see [#you-should-see]

- Every step on **Rotation checklist** reads "Done" and all token links return to "Active".
- **Reconciliation** → **Rail wallets** shows the replacement as "Current rail wallet" and the old wallet as "Previous rail wallet", with status "Clear".