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.

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.
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.

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.