# Rail wallet compromised or lost

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident
Replace the bank rail wallet when its key is compromised or lost: who you need, the order of the steps, and what happens to money in flight.

When the rail wallet's key is compromised, so someone else may hold it, or lost, so nobody can sign with it, contain the wallet first from "Bank rail", the token, **Settings**, then replace it with a rotation. The rail wallet is the key the bank rail signs mints, burns and escrow moves with. It holds supply authority on every linked token, which means it can create and destroy that token's supply. A rotation replaces the key with a new generation. It needs several people, because the people who manage a token are often not the bank rail managers. The [bank rail Console guide](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail#rotate-the-rail-wallet) describes the token's "Settings" tab and the other screens used below.

Containing the wallet only stops DALP from signing. Whoever holds a compromised key keeps its on-chain power until people revoke it on each token, and keeps full control of the old escrow until its tokens are moved out, so the revokes come first on a compromised key.

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

[Screenshot] The "Settings" tab of the Demo bank euro token lists Token, Network, Supply mode, Link state, Rail wallet, Rail wallet identity and Checker threshold.

The "Escrow" card below the fields shows the "Controller wallet" with the **Rail wallet** badge. A bank rail manager reads the rail wallet here before containing it.

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

- Name at least two people for each role on each linked token, so one absence is less likely to stop a rotation. Write the names down where the bank rail managers can find them.
- Turn on the **Bank rail** approval row, because with it off one manager completes or abandons a rotation alone.
- Rehearse one full rotation on a test network before you need it, so each person has used their own screen once.
- A token with Booked movements needs a token admin. A token linked as Supply delegate needs a token governor. On the token's "Settings" tab, **Supply mode** reads "Booked movements" or "Supply delegate".

## Roles in a rotation [#roles-in-a-rotation]

| Role | What they do in a rotation | Where |
| --- | --- | --- |
| Bank rail manager | Contains the wallet and requests completion. | **Bank rail**, the token, **Settings** |
| Second bank rail manager | Approves or rejects completion while the **Bank rail** approval row is on. Cannot be the manager who requested it. | **Bank rail**, the token, **Settings** |
| Token admin or governor, per token | Revokes the old wallet's supply authority and grants it to the new wallet. | The checklist step, or the token's own permissions |
| Token custodian, per token | Empties the old escrow, moves the suspense, and freezes the old address. | The token's forced transfer sheet, and the Platform API for the escrow forced transfer |
| Identity manager | Registers the new wallet's on-chain identity. | **Identities** |
| Escrow manager | Creates the new escrow for each supply delegate link. | **Bank rail**, the token, **Settings**, **Create escrow** in the **Escrow** block |

## Symptoms [#symptoms]

- A mint, burn or escrow move came from the rail wallet that nobody asked for.
- The rail wallet's private key was exposed, or a person with access to it left under suspicion.
- Credits park with the reason "The rail wallet lost its supply authority", or "Reconciliation" shows a **Break** because another account holds a token's supply authority.
- Custody can no longer sign with the rail wallet, so no request from it leaves.

## Checks [#checks]

1. Open "Asset lifecycle", then "Bank rail", select the token, open "Settings" and read the **Rail wallet** card. A "Contained" state means someone already started a rotation, and the checklist shows where it stands.
2. Decide whether the key is compromised or lost. If anyone else may hold it, treat it as compromised. A compromised rotation cannot be abandoned, and a lost one can be reported as compromised later, so choose **Compromised** when in doubt.
3. On "Reconciliation", read **Rail wallets** and each token's supply line to see the balance the rail wallet holds and what is parked as suspense.

While the rail wallet is contained, the recall sheet on **Payments** refuses a request to execute a recall with the message that a bank rail manager contained the rail wallet and that the link moves to the new rail wallet when the rotation completes. Request the recall again after the rotation completes.

## Actions [#actions]

### Compromised key [#compromised-key]

1. Contain the wallet. A bank rail manager selects **Contain rail wallet**, chooses "Compromised", and confirms. Every token link is suspended and the rail prepares the new wallet. A compromised rotation cannot be abandoned, and containing releases every cash-out the bank has not been instructed to pay, as [Money in flight](#money-in-flight) describes.
2. Revoke the old wallet on every link. Each token admin or governor opens their checklist step, "Authority revoked on" the token, and selects **Revoke authority**. It does not need the new wallet, so it can start straight after containment. Until it is mined on every link, the card says the old key still holds supply authority.
3. Protect the old escrow. On each supply delegate link, a token custodian moves every holder's tokens out of the old escrow, the contract that locks a client's tokens while a cash-out is paid, back to its owner with the escrow forced transfer through the Platform API, as [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows#move-units-out-with-the-forced-transfer-api) describes. Freezing the old address does not satisfy this step: the rail refuses completion until the old escrow is empty. The step reads **Old escrow protected on** the token.
4. Register the new identity. An identity manager registers the on-chain identity of the new wallet. Fund the new wallet with gas, the network's fee currency, at the address the step shows.
5. Grant the new wallet. Each token admin or governor selects **Grant authority**. The rail refuses a grant on a compromised rotation until every link is revoked and the old escrow is empty, and while any other account holds supply authority on the token.
6. Create the new escrow. An escrow manager creates the escrow for the new wallet on each supply delegate link.
7. Move the suspense. Suspense is the tokens the rail holds for credits it could not pass on, plus the coins of credits still on their way to the client's custody gateway. A token custodian moves the amount shown at **Suspense moved on** the token from the old wallet to the new one with a forced transfer, and freezes the old address if it still holds tokens.
8. Request completion. A bank rail manager selects "Request completion". While the "Bank rail" approval row is on, a second bank rail manager checks the old and new addresses, selects "Approve", then **Approve and complete**. With the row off, the request is approved at once.

### Lost key [#lost-key]

The checklist keeps its normal order: the new identity is registered first, then each token's revoke, escrow, grant and suspense steps. Nothing is at risk while you work, because nobody can sign with a lost key. Step 3 stays mandatory: the rail refuses completion while the old escrow holds tokens. On a lost rotation the Platform API refuses a custodian's forced transfer of a lock that backs an unpaid cash-out, with the reason `not-compromised`, so those units leave only when each holder reclaims the lock after its date and withdraws. If no holder can reach the old escrow to empty it, abandon the rotation instead of completing it. A bank rail manager can select **Request abandon**, but only before anyone submits the first revoke or grant of the hand-over. While the "Bank rail" approval row is on, a second manager approves it. With the row off, it takes effect at once and the old wallet signs again. After that, the rotation can only complete. If the investigation later finds the key was compromised after all, a manager selects "Report compromised": the rotation becomes a compromised one at once and any abandon request is dropped.

### What blocks completion [#what-blocks-completion]

**Request completion** stays disabled with a reason until every earlier step is done. The rail also refuses completion while the old wallet has queued writes, which containment does not cancel, while the old escrow still holds tokens, while the old wallet holds tokens and is not frozen on the token, while the new wallet holds less than the credits parked in suspense and in transit, and while a credit is mid-send from the old wallet. The blocker names each credit in transit, and a mid-send credit clears when it lands or fails.

The rail also protects the old wallet from a grant that was already on its way when you contained it. Activating a token link, or changing the mint cap of a supply delegate link, queues a grant of supply authority to the rail wallet, and that grant can wait up to 24 hours for an approval, a custody signature or gas. Containment cannot cancel it. The rail therefore refuses completion, for a lost and for a compromised rotation, while:

- A grant to the old wallet is still queued, submitted or waiting for approval on a token linked to it. This includes the re-delegation of a mint cap that has not settled. The blocker names the token and the request. When the grant lands, the next blocker below applies. When it fails, the blocker clears.
- The old wallet holds supply authority on any token linked to it, including a link that still waits for activation. On a suspended link the checklist offers **Revoke authority**. A link that waits for activation is not in the checklist, so a token admin or governor revokes the old wallet's authority from the token's own permissions. The rail also refuses to remove a link that waits for activation while the wallet is contained, because the removal would hide a queued grant from these checks.

- The indexer is behind the chain, so the rail cannot tell whether a grant landed. Request completion again after a moment.

While a grant is in flight, the rail raises one security case in operations for the rotation. It names each token and request, and it resolves when the rotation completes or is abandoned.

## Role steps [#role-steps]

### Bank rail manager [#bank-rail-manager]

Contain first, then follow the checklist. Each step shows the role it needs and a **Copy link** button: send that link to the person, so they land on the exact screen. Request completion once every earlier step reads "Done". Before you sign, check the reason you chose, because a compromised rotation cannot be abandoned.

### Second bank rail manager [#second-bank-rail-manager]

Open the token's "Settings" tab and select **Approve** or "Reject" on the request. The dialog shows the "Old wallet" and "New wallet" addresses and how many token links move. Before you sign, check the new address against the one the identity manager and the token admins confirmed, and that the checklist shows every step "Done". Reject with a reason when anything differs.

### Token admin or governor [#token-admin-or-governor]

You need only the role on the token: token admin for a token with Booked movements, token governor for a token linked as Supply delegate.

1. Open the link a bank rail manager sent you. It opens the token's Settings tab at your step.
2. Find the step **Authority revoked on** your token. The status reads "Yours to do" when your account holds the role, or "Waiting on" another role when it does not.
3. Select **Revoke authority**. The old wallet loses the token's supply management role, or its place as supply delegate. Confirm with your wallet.
4. Later, when the step "Authority granted on" your token reads "Yours to do", select **Grant authority** and confirm with your wallet. The new wallet receives the role or becomes the supply delegate.

Before you sign, check the address in the dialog against the "Old wallet" and "New wallet" addresses on the card, and that your token is the one in the step name. Select **Open the token's holders** to see its current holders.

### Token custodian [#token-custodian]

You move tokens that sit on the old wallet or its escrow. Send the escrow forced transfer, `POST /api/v2/addons/escrows/{escrowAddress}/forced-transfers`, through the Platform API to return each holder's free and locked tokens to its owner, which also ends the cash-outs that were using them. At **Suspense moved on** your token, use the token's forced transfer sheet to move the shown amount from the old wallet to the new one. Freeze the old address afterwards if it still holds tokens. Before you sign, check that the destination is the new wallet for suspense and the lock's owner for an escrow, and the token and amount match the step.

### Identity manager [#identity-manager]

Register the on-chain identity of the new wallet address shown in the step. Before you sign, check that the address matches the **New wallet** on the card, not the old one.

### Escrow manager [#escrow-manager]

Create the new escrow for each supply delegate link, controlled by the new wallet. Before you sign, check that the controller is the new wallet and the link is the token the step names.

## Money in flight [#money-in-flight]

- Credits that arrive while the wallet is contained are held. The rail does not mint them, and each parks with "The rail wallet lost its supply authority". After completion they mint from the new wallet without a manual retry.
- Credits already parked move with the suspense. The new wallet must hold at least their total before completion.
- Credits whose coins are minted and wait for delivery to the client's custody gateway, or whose delivery failed or came back, move to the new wallet at completion, so their delivery sends from it. The new wallet must hold their coins too. A credit mid-send from the old wallet blocks completion until it lands or fails.
- Cash-outs that were not instructed to the bank are released, and holders withdraw their tokens. New cash-outs wait with the link inactive until completion. A cash-out already instructed but not paid expires at its deadline, and the holder reclaims the tokens.
- A paid cash-out whose tokens were not burnt shows "Unbooked". A token custodian forces the locked tokens from the old escrow to the rail wallet, then a bank rail manager selects **Recover** on the cash-out row, and the rail burns the tokens and shows "Paid".
- A frozen retired wallet's balance is a case to work, not a **Break**. Tokens sent to the old wallet after completion stay there until a custodian moves them.

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

- On the token's **Settings** tab, every checklist step reads "Done" and the token links read "Active".
- On **Reconciliation**, "Rail wallets" lists the new wallet as "Current rail wallet" and the old one as "Previous rail wallet", and the status reads "Clear".

## Frequently asked questions [#frequently-asked-questions]

### Can I undo containment?

Only for a lost key. A lost rotation can be abandoned until the first revoke or grant of the hand-over is submitted, and abandoning it makes the old wallet active again. A compromised rotation cannot, because the key may be in other hands.

### Why does the checklist ask for the revoke before the new identity?

A compromised key can mint and burn on every linked token until someone revokes it: without limit on a Booked movements link, and up to the link's mint cap on a supply delegate link, or without limit when that link has none. The revoke does not need the new wallet, so it goes first.

### Can the same person do every step?

Only the roles they hold. While the **Bank rail** approval row is on, completion needs two different bank rail managers. With the row off, one manager completes it. The checklist shows who each step waits on.