> For the complete documentation index, see [llms.txt](https://docs.t-rex.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.t-rex.network/guides/agents/16.-pause-and-unpause-a-token.md). # 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](/guides/issuer/25.-commission-a-suite-and-grant-roles.md)); 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 ```mermaid sequenceDiagram participant Platform participant Agent as Token Agent participant Token Platform->>Token: paused() (read) Platform->>Agent: decision recorded, submit alt halt the asset Agent->>Token: pause() Token->>Token: caller holds AGENT_PAUSER, token not paused Token-->>Platform: Paused(agent) else open or resume the asset Agent->>Token: unpause() Token->>Token: caller holds AGENT_PAUSER, token paused Token-->>Platform: Unpaused(agent) end ``` ## 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](/guides/cross-chain/36.-handle-a-late-reconciliation-or-a-halt.md). **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](/guides/issuer/25.-commission-a-suite-and-grant-roles.md) | | `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](/guides/cross-chain/36.-handle-a-late-reconciliation-or-a-halt.md) | | 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](/guides/cross-chain/35.-discard-or-resolve-a-validation.md) | | Only one satellite has to stop | The pause is for the whole asset | Pause the issuance of validations for that chain instead: [36](/guides/cross-chain/36.-handle-a-late-reconciliation-or-a-halt.md) | ## 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](/guides/cross-chain/36.-handle-a-late-reconciliation-or-a-halt.md) : when the token paused itself * [13 Freeze and unfreeze an address or a partial balance](/guides/agents/13.-freeze-and-unfreeze-an-address-or-a-partial-balance.md) : halting one address, not the asset * [14 Execute a forced transfer](/guides/agents/14.-execute-a-forced-transfer.md) : blocked while the token is paused * [15 Recover a position from a lost wallet](/guides/agents/15.-recover-a-position-from-a-lost-wallet.md) : blocked while the token is paused * [08 Mint a position to an investor](/guides/positions/08.-mint-a-position-to-an-investor.md) : allowed while the token is paused * [01 Deploy a token suite](/guides/issuer/01.-deploy-a-token-suite.md) : a token is deployed paused --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.t-rex.network/guides/agents/16.-pause-and-unpause-a-token.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.