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 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.
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.
Roles in a rotation
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
- 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.
- 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.
- 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
Compromised key
- 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 describes.
- 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.
- 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 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.
- 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.
- 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.
- Create the new escrow. An escrow manager creates the escrow for the new wallet on each supply delegate link.
- 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.
- 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
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
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
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
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
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.
- Open the link a bank rail manager sent you. It opens the token's Settings tab at your step.
- 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.
- Select Revoke authority. The old wallet loses the token's supply management role, or its place as supply delegate. Confirm with your wallet.
- 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
You move tokens that sit on the old wallet or its escrow. Send the escrow forced transfer, POST /api/, 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
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
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
- 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.
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.