16. Pause and unpause a token

The pause halts every movement of an asset between holders. An agent uses it during an incident, and lifts it when the incident is resolved. The same call, unpause, opens a new asset: a token is deployed paused, and nothing moves between holders until the Issuer decides the asset is ready. The token can also pause itself, when the cross-chain layer delivers a settlement the register cannot account for.

At a glance

Triggered by	Token Agent
Actors	Issuer, Token Agent, Platform
Contracts	Token
Preconditions	The caller holds AGENT_PAUSER in the asset's domain (see 25); to pause, the token is not paused; to unpause, the token is paused and the Issuer has decided that the asset can move
Result	Movements between holders are halted, or resumed

Actors and roles

Actor	Role in this flow	What they hold
Issuer	Decides to halt the asset and to resume it. Does not transact in this flow.	The roles it delegated to its agents
Token Agent	Submits the pause or lifts it.	AGENT_PAUSER on the Token
Platform	Reads the state, submits with the Token Agent's key and informs the holders.	The Token Agent's signing key, or a key authorized for it

Sequence

Step by step

Step 1. Read the state and decide

Who: Issuer and Platform

Call: Off-chain, using read calls

Before the call: For a pause: an incident, or a decision of the Issuer, calls for a halt. For an unpause: the asset is ready to open, or the incident is resolved.

What happens: The Platform reads Token.paused(). Before opening a new asset, it confirms that the suite is commissioned, that the required claim topics and the trusted Claim Issuers are set, and that the rules are bound. Before lifting a pause the token set on itself, it confirms that the cause was investigated: see 36.

What changes: Nothing on-chain.

Step 2. Pause

Who: Token Agent (AGENT_PAUSER)

Call: Token.pause()

Before the call: The token is not paused.

What the contract checks:

1. The caller holds AGENT_PAUSER in the asset's domain. Otherwise the call reverts with AccessManagedUnauthorized.

2. The token is not already paused. Otherwise EnforcedPause.

What changes: The token records the pause and emits Paused(agent). From now on, the operations below are blocked or allowed as shown.

While paused
transfer, transferFrom, identityTransfer, batchTransfer	Blocked, with EnforcedPause
forcedTransfer, recoveryAddress	Blocked, with EnforcedPause
Settlement of a transfer executed on a satellite	Blocked. The delivery reverts and the settlement stays deliverable
Returning an amount held in transit, when resolving a stuck validation	Blocked
mint, burn	Allowed
Freezing and unfreezing	Allowed
Registrations, claim topics, trusted Claim Issuers, compliance rules	Allowed
Requesting and discarding cross-chain validations	Allowed
approve, permit	Allowed. They move nothing

Step 3. Unpause

Who: Token Agent (AGENT_PAUSER)

Call: Token.unpause()

Before the call: Step 1 concluded that the asset can move.

What the contract checks:

1. The caller holds AGENT_PAUSER in the asset's domain. Otherwise AccessManagedUnauthorized.

2. The token is paused. Otherwise ExpectedPause.

What changes: The token records that it is not paused and emits Unpaused(agent). Transfers execute again. Settlements that were refused during the pause are applied when they are delivered again.

State after the flow

• Token.paused() is true after a pause and false after an unpause.

• No balance, no position, no freeze and no registration has changed.

• After a pause, validations already issued keep running: their expiry and their release time do not stop.

• An indexer has seen Paused or Unpaused, with the account that acted.

Failure modes

Symptom	Cause	Fix
Reverts with AccessManagedUnauthorized	The caller does not hold AGENT_PAUSER in the asset's domain (check 1 of steps 2 and 3)	Grant the role: 25
pause reverts with EnforcedPause	The token is already paused (step 2, check 2)	Nothing to do. Read paused()
unpause reverts with ExpectedPause	The token is not paused (step 3, check 2)	Nothing to do
A new asset is deployed and no holder can transfer	A token is deployed paused	Open it with unpause when it is ready
The token is paused and no agent paused it	The token paused itself on a replayed or unknown settlement. The Paused event names the gateway that delivered it, and the compliance emitted ReplayedSettlement	Investigate before lifting the pause: 36
The token is paused and tokens were still created or destroyed	Mints and burns are allowed during a pause	Intended. Issuance and redemption are often part of the response
The token is paused and an agent cannot force a transfer or run a recovery	The pause stops the privileged movements too	Lift the pause, act, and pause again if needed
After a long pause, validations were discarded and their settlements arrive late	The windows of a validation keep running during a pause	Keep pauses short when transfers are in flight on satellites, and hold the keeper back: 35
Only one satellite has to stop	The pause is for the whole asset	Pause the issuance of validations for that chain instead: 36

Common misunderstandings

Wrong: "A pause freezes everything."

Right: It stops movements between holders, including forced transfers, recoveries and the settlement of transfers executed on satellites. Mints, burns, freezes and all configuration stay available.

Wrong: "A paused token is a broken token."

Right: Paused is the state a token is deployed in. The initial setup and the first mints happen during it, and the Issuer opens the asset with unpause.

Wrong: "Pausing the token stops the satellites."

Right: The pause is on the reference chain. T-REX Lite keeps executing the validations it already holds until they expire. What the pause stops is the recording of those transfers on the register: their settlements wait and are applied when the pause is lifted. To stop new transfers on a satellite, pause the issuance of validations for that chain.

Wrong: "Only an agent can pause the token."

Right: The token pauses itself when a trusted gateway delivers a settlement for a validation that was never issued, or one that was already applied. Lifting that pause is an agent's decision, after investigation.

Integration notes

• Read paused() before submitting a transfer and tell the holder when the asset is halted. Every blocked operation reverts with EnforcedPause.

• Index Paused(account) and Unpaused(account). An account that is a gateway and not an agent means the token paused itself.

• Alert on Paused together with ReplayedSettlement from the compliance. Together they mean the interop layer delivered something the register refused.

• Plan the opening of an asset: commission, configure, mint the initial positions, then unpause.

• Keep AGENT_PAUSER with an operator that can act at any hour. It is the one role whose value depends on speed.

• A pause does not stop time. Claims expire, and validations reach their expiry and their release time during a pause.

Related flows

• 36 Handle a late reconciliation or a halt : when the token paused itself

• 13 Freeze and unfreeze an address or a partial balance : halting one address, not the asset

• 14 Execute a forced transfer : blocked while the token is paused

• 15 Recover a position from a lost wallet : blocked while the token is paused

• 08 Mint a position to an investor : allowed while the token is paused

• 01 Deploy a token suite : a token is deployed paused