design-doc: compliance module (Chainalysis-backed ICompliance)

[tynes]

Summary

• Adds protocol/compliance-module.md: an optional, opt-in compliance screening layer for OptimismPortal2 (deposits) and L2ToL1MessagePasser (withdrawals). The bridges call a single ICompliance.check(from, to) hook; one concrete implementation, ChainalysisCompliance, wraps the on-chain Chainalysis Sanctions Oracle.
• Adds security/fma-compliance.md: the failure mode and recovery analysis for the module.
• ETH msg.value on screened-out transactions (sanctioned addresses or oracle outages) is permanently locked in the compliance contract — the contract has no admin role and no ETH-egress function. Two alternative dispositions (auto-bounce-to-sender, burn-to-address(0)) are documented in the Alternatives section.

Design highlights

• Single minimal interface. ICompliance.check(address,address) returns (bool) is the only function the bridges depend on. The 4-byte selector is preserved indefinitely; richer signatures will be added as overloads in future iterations rather than by replacing this one.
• No state machine, no plugins, no admin. Earlier drafts proposed an abstract Compliance + L1Compliance + L2Compliance split, an IRule plugin set, a four-state status enum with bit-packed owner-override, and a settle / approved callback flow. All of that is gone. The deployed ChainalysisCompliance has no Ownable, no recover, no settle, no transferOwnership.
• Hot-path behavior. Compliant: oracle says clean → donateETH back to bridge → bridge proceeds. Sanctioned or oracle-failure: ETH retained, distinct event emitted (Sanctioned / OracleUnavailable), check returns false, bridge returns successfully without emitting a TransactionDeposited / MessagePassed.
• Opt-in. compliance == address(0) disables the module. L1 sets the address via initialize (governance-gated proxy upgrade to change). L2 has setCompliance(address(0)) gated to the L2ProxyAdmin owner.
• L2 predeploy at 0x420000000000000000000000000000000000002D.

Trade-off discussion

The no-recovery design is the central trade-off. It eliminates an admin-key-compromise vector and dramatically shrinks the contract, but it makes oracle false positives and oracle outages translate directly into permanent user loss. The FMA's FM2 and FM4 are scoped around this. The Alternatives section documents auto-bounce-to-sender and burn-to-zero as drop-in alternative dispositions if reviewers prefer one of those.

Test plan

This is a documentation change. Reviewers should:

• Read protocol/compliance-module.md end-to-end and confirm the design is internally consistent (interface, contract, bridge changes, predeploy, alternatives, risks).
• Read security/fma-compliance.md and confirm FM coverage matches the design (six FMs: bridge-blocking bugs, locked compliant ETH, access control, Chainalysis dependency, dispute-game interaction, generic SC).
• Confirm both Mermaid diagrams render and reflect the compliant / sanctioned / oracle-unavailable branches.
• Sanction-check the no-recovery decision against operator UX requirements; if a refund path is required, point reviewers at the auto-bounce / burn alternatives in the Alternatives section.

🤖 Generated with Claude Code