> 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/security-and-trust-model/emergency-behavior.md). # Emergency behavior Things go wrong: a key is compromised, a satellite stalls, a module misbehaves, a message arrives that should not exist. This page describes what the protocol does on its own in such situations, which levers exist, who holds them, and how normal operation resumes. Two principles shape the design. * **Fail closed.** When the protocol cannot be sure, it stops. A chain that was not opened carries nothing. A message that cannot be attributed is refused. A settlement that cannot be accounted for halts the token. * **Use the narrowest lever.** Each lever has a scope: one address, one validation, one satellite, one asset, every asset. An incident is contained with the smallest scope that covers it. ## What the protocol does on its own | Situation | Automatic response | Resumed by | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------- | | A settlement arrives for a validation that was never issued, or for one already applied or resolved | Nothing is applied. The token pauses itself. | `AGENT_PAUSER`, after investigation | | A settlement arrives after its validation was discarded, and the executed amount breaches a rule | The settlement is applied and flagged. Issuance of validations for that chain is paused. | `COMPLIANCE_MANAGER` | | A transfer between two satellites is resolved with only its mint reported | Issuance for the sending chain, whose report is missing, is paused. | `COMPLIANCE_MANAGER` | | The network removes a gateway from the trusted registry | Every route through it stops, for every asset, at the next message. | The Issuer sets another route | | A settlement is delivered while the token is paused | The delivery is refused and remains deliverable. | Delivered again after the pause is lifted | | A message comes from a contract that is not the asset's peer, or twice | Refused. | Not applicable | ## The levers From the narrowest scope to the widest. | Scope | Lever | Function | Held by | | --------------------------------------- | -------------------------------------- | ----------------------------------------------------- | ----------------------------------- | | One address | Freeze the address, or an amount on it | `setAddressFrozen`, `freezePartialTokens` | Freezer agents | | One wallet | Revoke the wallet from its identity | `IdentityFactory.revokeAccount` | The Identity Owner | | One position | Move it, or restore it to its owner | `forcedTransfer`, `recoveryAddress` | Forced-transfer and recovery agents | | One claim | Revoke it | `revokeClaimByDigest` | The Claim Issuer | | One signing key of a Claim Issuer | Withdraw it | `removeKey` | The Claim Issuer | | One Claim Issuer, for one asset | Stop trusting it | `removeTrustedIssuer` | `OWNER` of the registry | | One Claim Issuer, for the network | Lower its reputation | `setReputation` | `REPUTATION_MANAGER` | | One rule | Remove the module | `removeModule`, `forceRemoveModule` | `OWNER` of the compliance | | One validation | Discard it, or resolve a stuck one | `discardExpiredValidations`, `resolveStuckValidation` | `VALIDATION_KEEPER` | | One satellite, for one asset | Stop authorizing transfers there | `setIssuancePaused` | `COMPLIANCE_MANAGER` | | One satellite, for one asset | Close the chain | `setRoute` with a zero gateway | `IDENTITY_MANAGER` | | One asset | Halt it | `pause` | `AGENT_PAUSER` | | One messaging provider, for every asset | Stop trusting its gateway | `setTrustedGateway(gateway, false)` | `INTEROP_MANAGER` | | Every shared suite | Replace faulty code | `publishAndUpgrade` | `VERSION_MANAGER` | ## Incidents and responses This section gives the levers that fit each incident. The order of actions and the escalation are each Issuer's own runbook. ### A holder's wallet is compromised 1. **The owner revokes the wallet.** It can no longer receive the asset. Its holdings stay attributed to the owner. 2. **The owner moves the tokens out**, through its identity, with `identityTransfer`, to an address it controls. 3. **If the owner cannot act, or if part of the balance is frozen**, an agent restores the position with `recoveryAddress`, after freezing the address if needed. An address freeze follows the position to the new wallet, where the agent lifts it. A recovery moves the whole balance and keeps frozen tokens frozen. A transfer through the identity moves free tokens only. The identity, its claims and its other wallets are unaffected. See [Wallet linking and the global identity registry](/identity-onchainid/wallet-linking-and-the-global-identity-registry.md). ### The keys of an identity are compromised or lost | Case | Response | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | One key is compromised, a `MANAGEMENT` key remains safe | The owner removes the compromised key. | | Every `MANAGEMENT` key is lost | The guardians recover the identity, if a recovery module is installed. See [Account abstraction and recovery](/identity-onchainid/account-abstraction-and-recovery.md). | | An attacker holds a `MANAGEMENT` key | The asset's agents freeze the addresses of the identity while the owner or its guardians regain control. | Compromising an identity does not give access to the assets of any other holder. ### A Claim Issuer is compromised A compromised signing key can attest falsely. The response has three levels, and they are independent. | Who | Action | Effect | | --------------------------- | ----------------------------------- | ------------------------------------------------------------------------ | | The Claim Issuer | Withdraws the signing key | Every claim signed with that key stops being valid, everywhere, at once. | | Each Issuer that trusted it | Removes it from its trusted issuers | Its claims stop counting for that asset. | | Network governance | Sets its reputation to zero | It can no longer write claims onto identities without a grant. | Investors who relied only on that issuer become ineligible to receive until they hold a claim from another trusted issuer. Their positions are untouched. ### A compliance module misbehaves | Symptom | Response | | ------------------------------------------------------------ | ---------------------------------------------------- | | A rule refuses movements it should allow | `OWNER` reconfigures the module or removes it. | | A tracker module reverts and blocks movements | `OWNER` removes it. | | The module reverts when it is removed | `forceRemoveModule`, which does not call the module. | | A position is misattributed after a registration was changed | `OWNER` repairs it with `fixPosition`. | A faulty module cannot block an asset beyond the time it takes its `OWNER` to remove it. ### A satellite or its messaging stalls | Symptom | Response | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Settlements are slow, within the reconciliation window | None needed. | | Settlements are slower than the window | The keeper may discard expired validations. A settlement that still arrives is applied late and flagged. | | A satellite repeatedly settles late | `COMPLIANCE_MANAGER` raises the reconciliation window for that chain, or pauses issuance for it. | | The provider is down | The Issuer routes the chain through another vetted gateway. Validations already sent settle through the gateway that carried them. | | The satellite itself is compromised | See "A satellite is compromised" below. | Positions on the reference chain are unaffected by any failure of a satellite or of a provider. ### A satellite is compromised A satellite that can no longer be relied on, because the chain itself is compromised or lost, is cut off from the asset. 1. **The Issuer pauses issuance for the chain and closes its route.** No new transfer is authorized there, and nothing more is sent to it. 2. **The satellite is marked as compromised.** From then on, any transaction from or to that chain is treated as invalid. `[[TBC: the function that marks a satellite as compromised]]` 3. **Every position bridged there is recalled.** Each one returns to the reference chain as a free balance of the identity its satellite wallet is linked to. The register already knows whose each position is, so the recall does not depend on the satellite. No holder loses a position because a satellite failed. The register never stopped recording who owns what there. ### A gateway is compromised The `INTEROP_MANAGER` removes it from the trusted registry. Every asset stops sending to it and accepting from it at the next message, with no action on any token. Each Issuer then routes its satellites through another vetted gateway. A gateway is as reliable as the interoperability solution behind it. While that solution works as designed, this incident does not occur. If a forged message got through before the removal, the matching checks limit what it could do, and a message that matches nothing halts the token. See [Messaging providers](/cross-chain-the-distributed-register/messaging-providers.md). ### A faulty version is activated Versions only move forward. The response to a faulty version of a shared suite is a new version, decided by Network governance and activated by the `VERSION_MANAGER`. Until then, each Issuer can pause its asset. An Issuer with an isolated suite was not affected, and decides for itself when to upgrade. ## The pause, precisely | While the token is paused | | | --------------------------------------------------- | ------------------------------------------------------------------------ | | Transfers by holders, by spenders and by identities | Blocked | | Forced transfers and recoveries | Blocked | | Settlements from satellites | Refused, and delivered again later | | Mints and burns | Allowed | | Freezing and unfreezing | Allowed | | Configuration: rules, eligibility, roles, routes | Allowed | | Issuance of new validations | Allowed. The executions they authorize settle after the pause is lifted. | The pause stops every change of ownership between holders, including those ordered by agents. An incident under investigation settles nothing. To also stop new transfers from being authorized on satellites, pause issuance for those chains. ## Who restarts what | What stopped | Who restarts it | How | | -------------------------- | -------------------- | ------------------------------------------------------------------------------ | | The token | `AGENT_PAUSER` | `unpause` | | Issuance for a satellite | `COMPLIANCE_MANAGER` | `setIssuancePaused(chainKey, false)` | | A closed chain | `IDENTITY_MANAGER` | `setRoute` with a trusted gateway | | A frozen address or amount | Freezer agents | `setAddressFrozen(address, false)`, `unfreezePartialTokens` | | A removed gateway | `INTEROP_MANAGER` | `setTrustedGateway(gateway, true)`, after which Issuers route through it again | Two things cannot be restarted, by design: a revoked wallet stays revoked, and a discarded validation stays discarded. The holder links another wallet, or requests a new validation. ## Keys that must not be lost An access manager has a root role, `ADMIN_ROLE`. Its holder grants every other role and maps every function. Every lever on this page can be handed out again by it. The root itself has no fallback on-chain. An Issuer holds it in an arrangement that survives the loss of one key: a multisig, or its governance process. --- # 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/security-and-trust-model/emergency-behavior.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.