# Restricted wallet on chain

Source: https://docs.settlemint.com/docs/console/participants/restricted-wallet-on-chain
How the wallet restriction module stops a restricted wallet on every token of the system, what each module state means, and how recovery is handled.

On systems with the wallet restriction module, a [wallet restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) is enforced directly on chain across every token of the system in addition to per-token freezes. This reference covers on-chain enforcement, module states, wallet recovery carry-over, and out-of-sync operations cases.

## On-chain enforcement [#on-chain-enforcement]

The wallet restriction module is a system compliance rule shown as "Wallet restriction" on [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls#the-wallet-restriction-rule). New systems on supporting networks receive it at creation, and [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates#the-wallet-restriction-row) installs it on existing systems and backfills active restrictions.

Once a wallet is recorded in the module:

- **Outgoing sends blocked everywhere:** The wallet cannot send any token of the system (including unlisted or newly received tokens), reverting with `COMPLIANCE_CHECK_REASON_WALLET_RESTRICTED`. Single-token unfreezes sent outside DALP cannot bypass it.
- **Applies across all active restrictions:** Any valid API restriction created by a Custodian on one token blocks outgoing transfers across the whole system.
- **Incoming transfers stay open to the module:** Mints and incoming transfers pass the module unless the wallet is also frozen on that specific token.
- **Forced operations and legacy burns:** Custodian forced transfers and forced corporate-action burns skip all compliance modules ([Burns and corporate actions](https://docs.settlemint.com/docs/console/participants/restricted-wallet-burns#burns-and-corporate-actions)). Ordinary burns are checked by the module only on DALP 3.2 token contracts, not legacy contracts.
- **Wallet recovery:** Recovery skips transfer checks, and unless the module rule is switched off, the module automatically adds the replacement wallet when moving balances out of a restricted lost wallet.
- **Governance overrides:** A token's Governance role can point a token at a different compliance contract directly on chain, detaching it from the module.

Only a Compliance manager can restrict or lift wallets directly on the module (and the signer running **System updates** needs Compliance manager to backfill). A System manager can replace the module contract, and a Compliance manager can pause or remove the rule in **Global controls** or directly on chain (which skips approvals and the audit trail and marks the row "Not fully enforced" on **System updates**).

## The wallet restriction module [#the-wallet-restriction-module]

Each restriction reports module status in **Wallet restriction module** on **Restriction result** (API field `chain.state`, accompanied by `action`, `transactionHash`, `failure`, and `updatedAt`):

| Console label | `chain.state` | Meaning | Next action |
| --- | --- | --- | --- |
| "Not installed" | `no-module` | System has no wallet restriction module. Enforcement relies on per-token freezes and DALP holds only. | None. |
| "Restriction pending" | `pending` | `action` is `restrict`. DALP retries automatically using the original signer. Stops with `DALP-17461` if that signer loses Compliance manager. | Wait while retrying (row shows "Pending on chain"). After `DALP-17461`, have a Compliance manager select **Apply again**. |
| "Lift pending" | `pending` | `action` is `lift`. Awaiting module lift confirmation or remaining token unfreezes. Restriction remains active. | Wait for the restriction to close automatically. |
| "Confirmed" | `confirmed` | On-chain module matches the restriction (after a failed lift, `failure` explains why the lift did not land). | None (or fix `failure` and lift again after a failed lift). |
| "Out of sync" | `out-of-sync` | Module was modified outside DALP or switched off on the compliance engine. | Resolve the generated operations case below. |

## When a restricted wallet is recovered [#when-a-restricted-wallet-is-recovered]

When a restricted wallet is recovered to a replacement wallet (through DALP, forced recovery, or directly on the identity registry), DALP automatically opens a linked restriction on the replacement wallet (`carriedFrom` pointing to the original, displaying "This restriction was carried over from a lost wallet that was recovered to this wallet.") with the original reason and scope, and ensures the replacement wallet is restricted in the module.

Because recovery does not transfer per-token freezes, the carried restriction's tokens start as pending. Select **Apply again** on the replacement wallet to freeze them (if the original restriction had no signer on record, a Compliance manager runs **Apply again** to sign the module call too).

## Cases from the wallet restriction module [#cases-from-the-wallet-restriction-module]

While the module is bound to the compliance engine, DALP watches on-chain changes from first observation and opens operations cases on [Cases](https://docs.settlemint.com/docs/console/organisation-settings/custody-books#work-an-operations-case) for two events (DALP's own restricts, lifts, and recovery carry-overs never open cases):

| Case title | Severity | Trigger |
| --- | --- | --- |
| "Wallet restriction out of sync with the chain" | Critical or Warning | Critical if a wallet was lifted, cleared, or the module switched off outside DALP. Warning if an untracked wallet was restricted directly on chain. Names wallet, sender, and transaction. |
| "Credit to a restricted wallet" | Warning | Fired whenever a transfer, mint, forced transfer, or recovery credits a restricted wallet, reporting token, base-unit amount, sender, and timestamp. |

Neither case auto-resolves: acknowledge and resolve with a note, or allow it to expire after 30 days.