Security Model Overview
All core contracts extend OpenZeppelin’s audited upgradeable libraries (AccessControl2StepUpgradeable, ERC20Upgradeable, ERC20PermitUpgradeable, Initializable). Stablecoin OFT contracts are independently audited.
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 |
DEFAULT_ADMIN_ROLE without requiring contract upgrades.
Fund Recovery for Regulatory Actions
The recoverFunds() function enables compliance-mandated seizures:
function recoverFunds(address _from, address _to, uint256 _amount) external;
// Requires: DEFAULT_ADMIN_ROLE
// Constraint: _from must NOT be allowlisted
DEFAULT_ADMIN_ROLE).
Workflow:
- Compliance team blacklists the target address via
BLACKLISTER_ROLE
- Default admin calls
recoverFunds() to move tokens to a designated custody address
The constraint that _from must not be allowlisted ensures recovery cannot be used against compliant users. The function reverts with CannotRecoverFromAllowlisted if attempted.
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 |
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
