> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerzero.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and Compliance

> Security model, compliance features, threat mitigations, and operational security recommendations.

## Security Model Overview

All core contracts extend OpenZeppelin's audited upgradeable libraries (AccessControl2StepUpgradeable, ERC20Upgradeable, ERC20PermitUpgradeable, Initializable). Stablecoin OFT contracts are [independently audited](/v2/resources/audits).

10 distinct roles enforce separation of duties. Critical pairs are split by design (pauser vs unpauser, minter vs burner, fee admin vs token mint authority).

EIP-7201 namespaced storage eliminates storage collision risks during upgrades. Proxy contracts must be deployed and initialized atomically to prevent front-running.

Multiple independent enforcement layers (pause, rate limit, allowlist, fee) operate simultaneously. Compromise of one layer does not disable the others.

## Compliance Features

### KYC/AML Enforcement via Allowlist

The three-mode allowlist system directly supports compliance workflows:

| Compliance Requirement      | Implementation                                                                            |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| **KYC-only transfers**      | Whitelist mode: only verified addresses can send/receive                                  |
| **Sanctions screening**     | Blacklist mode: block sanctioned addresses while allowing everyone else                   |
| **Unrestricted operations** | Open mode: no address restrictions                                                        |
| **Gradual rollout**         | Start in Whitelist mode for controlled launch, switch to Blacklist after onboarding phase |

Mode transitions can be performed instantly by `DEFAULT_ADMIN_ROLE` without requiring contract upgrades.

### Fund Recovery for Regulatory Actions

The `recoverFunds()` function enables compliance-mandated seizures:

```solidity theme={null}
function recoverFunds(address _from, address _to, uint256 _amount) external;
// Requires: DEFAULT_ADMIN_ROLE
// Constraint: _from must NOT be allowlisted
```

**Prerequisite:** Blacklist mode must be active (set by `DEFAULT_ADMIN_ROLE`).

Workflow:

1. Compliance team blacklists the target address via `BLACKLISTER_ROLE`
2. Default admin calls `recoverFunds()` to move tokens to a designated custody address

<Warning>
  The constraint that `_from` must not be allowlisted ensures recovery cannot be used against compliant users. The function reverts with `CannotRecoverFromAllowlisted` if attempted.
</Warning>

### Per-Destination Controls

Per-destination pause (`PauseByID`) enables targeted responses when a specific chain requires isolation — whether for regulatory reasons, security incidents, or maintenance:

* Pause transfers to/from a specific destination chain
* Maintain normal operations on all other chains
* No contract upgrade required

### Audit Trail via Events

Every state-changing operation emits an indexed event:

| Category           | Events                                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transfers**      | `Transfer`, `OFTSent`, `OFTReceived`                                                                                                              |
| **Allowlist**      | `AllowlistModeUpdated`, `BlacklistUpdated`, `WhitelistUpdated`                                                                                    |
| **Pause**          | `PauseSet`, `DefaultPauseSet`                                                                                                                     |
| **Fees**           | `DefaultFeeBpsSet`, `FeeBpsSet` (fee proceeds also appear as standard ERC20 `Transfer` or native transfers to the configured fee deposit address) |
| **Rate Limits**    | `RateLimitConfigUpdated`, `RateLimitStateUpdated`, `RateLimitAddressExemptionUpdated`                                                             |
| **Access Control** | `RoleGranted`, `RoleRevoked`                                                                                                                      |

All events are indexed where applicable, for off-chain monitoring and reporting.

## Threat Model

| Threat                                   | Impact                                                                     | Mitigation                                                                                                                                                                                                                                                                        |
| ---------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin key compromise**                 | Attacker grants themselves all roles, drains funds                         | Use governance multisig for `DEFAULT_ADMIN_ROLE`. Monitor `RoleGranted` events. Consider renouncing admin after initial setup.                                                                                                                                                    |
| **Pauser key compromise**                | Attacker pauses all operations (DoS)                                       | Separate `PAUSER_ROLE` and `UNPAUSER_ROLE`. Assign unpauser to a different multisig. Pausing is disruptive but not catastrophic — funds remain safe.                                                                                                                              |
| **Unpauser key compromise**              | Attacker reverses a legitimate security pause                              | Assign `UNPAUSER_ROLE` to a governance multisig, separate from the pauser key. Monitor `PauseSet` / `DefaultPauseSet` events for unexpected unpauses.                                                                                                                             |
| **Fee admin compromise**                 | Attacker sets fees to 100%                                                 | Fees are pushed to the fee deposit address during `_debit`; the fee admin cannot redirect proceeds. Ensure integrations use `minAmountLD` to reject unexpectedly small received amounts. Monitor `DefaultFeeBpsSet` / `FeeBpsSet`. High fees are visible on-chain and reversible. |
| **Minter key compromise**                | Attacker mints unlimited tokens, inflating supply                          | Only grant `MINTER_ROLE` to the OFT contract, never to EOAs. The OFT can only mint via `_credit()` after receiving a verified LayerZero message. Outbound rate limits cap the contagion risk to other chains.                                                                     |
| **Sanctioned address transfer**          | Compliance violation                                                       | Enable Blacklist mode. Monitor OFAC/sanctions lists. Automate blacklist updates via `BLACKLISTER_ROLE`.                                                                                                                                                                           |
| **Chain compromise**                     | Malicious messages from a compromised chain                                | Per-destination pause to isolate the chain. Inbound rate limits cap damage. DVN verification provides message integrity.                                                                                                                                                          |
| **Proxy storage collision**              | Upgrade corrupts storage                                                   | EIP-7201 namespaced storage with deterministic slots. Each module has an isolated storage location.                                                                                                                                                                               |
| **Non-atomic proxy deployment**          | Attacker front-runs `initialize()` between proxy deploy and initialization | Deploy proxy and call `initialize()` atomically in the same transaction (e.g., via a deployer contract or `TransparentUpgradeableProxy` constructor data).                                                                                                                        |
| **Dust exploitation**                    | Attacker sends dust amounts to avoid fees                                  | Fee calculation uses `(_amount * bps) / BPS_DENOMINATOR`. Amounts where `amount * bps < BPS_DENOMINATOR` produce zero fee. This is by design — dust amounts are meant to be economically insignificant.                                                                           |
| **Rate limit bypass via many small txs** | Attacker splits large transfer into many small ones                        | Each transaction updates the bucket. Aggregate usage is tracked regardless of individual transaction size. With net accounting enabled, rounding can slightly favour the user, but the amounts are insignificant relative to the cost of running each `send()` transaction.       |

## Monitoring

Deploy off-chain monitoring for:

| Event                                              | Source           | Indicates                                      |
| -------------------------------------------------- | ---------------- | ---------------------------------------------- |
| `RoleGranted` / `RoleRevoked`                      | OFT, `ERC20Plus` | Permission changes                             |
| `DefaultAdminTransferScheduled`                    | OFT, `ERC20Plus` | Admin transfer initiated                       |
| `PauseSet` / `DefaultPauseSet`                     | OFT              | Pause state changes                            |
| `DefaultFeeBpsSet` / `FeeBpsSet`                   | OFT              | Fee rate changes                               |
| `RateLimitConfigUpdated` / `RateLimitStateUpdated` | OFT              | Rate limit config changes                      |
| `RateLimitAddressExemptionUpdated`                 | OFT              | Rate limit exemption changes                   |
| `AllowlistModeUpdated`                             | `ERC20Plus`      | Allowlist mode transitions                     |
| `BlacklistUpdated` / `WhitelistUpdated`            | `ERC20Plus`      | Address list changes                           |
| `OFTSent` / `OFTReceived`                          | OFT              | Cross-chain transfers (alert on large amounts) |
| `Transfer` (to fee deposit)                        | `ERC20Plus`      | Fee deposit inflows                            |

## Next Steps

* [RBAC Reference](/v2/developers/evm/stablecoin-oft/rbac-reference) for the complete role-to-function matrix
* [Architecture](/v2/developers/evm/stablecoin-oft/architecture) for the system design overview