Compliance Architecture#

All participant verification is enforced on-chain via the ComplianceRegistry contract. Non-compliant addresses are rejected at the contract boundary - open(), fill(), and claim() all revert.

ComplianceRegistry - a UUPS-upgradeable per-chain contract that stores KYC attestations. Every settlement interaction checks compliance at the contract level - non-compliant addresses are rejected before any funds move.

Attestation Model#

Each participant needs a valid on-chain attestation:

Solidity

1struct Attestation {
2    bytes2 jurisdiction;  // ISO 3166-1 (e.g., "US", "CH")
3    uint8 tier;           // 0=NONE, 1=RETAIL, 2=PROFESSIONAL, 3=INSTITUTIONAL
4    uint48 expiresAt;     // Attestation expiry timestamp
5    bytes32 vendorHash;   // KYC vendor (e.g., keccak256("chainalysis"))
6}

6 linessolidity

isCompliant(address) checks: attestation exists → not expired → jurisdiction not blocked. Cost: < 0 gas.

Attestation Lifecycle

initial

normal

success

error

Hover a state to explore

Settlement Path Routing#

	Escrow	ResourceLock (Compact)
Compliant (no API key)	`ComplianceSettlerEscrow`	`ComplianceAllocator` via Compact
Direct (API key present)	`InputSettlerEscrow`	Integrator's allocator via Compact

API key present → Direct path (integrator handles KYC externally). No API key → Compliant path (on-chain enforcement, 403 COMPLIANCE_FAILED for non-compliant signers).

Pre-Trade Compliance Gate#

Every order passes 0 checks before reaching settlement contracts:

Risk labels - wallet risk scoring via vendor adapter
Originator sanctions - OFAC/EU/UN screening
Beneficiary sanctions - same screening on recipient
Jurisdiction corridor - origin→destination corridor permitted
Corridor volume - per-corridor caps not exceeded
Travel Rule data - FATF fields present above threshold
Unhosted wallet EDD - enhanced due diligence for non-custodial wallets

Compliance Check Sequence

0 / 6

request

response

event

onchain

KYC / KYB Onboarding#

Onboarding Flow#

User initiates KYC/KYB - frontend calls POST /api/v1/kyc/initiate, which creates a Sumsub applicant and returns a verification URL / SDK token
Vendor verification - Sumsub collects identity documents, runs liveness checks, verifies beneficial ownership (KYB). Result arrives via webhook (POST /api/v1/kyc/webhook)
Off-chain registration - backend stores the verified counterparty with jurisdiction, tier (1/2/3), and vendor evidence hash. The ComplianceService DashMap is updated for O(1) pre-trade lookups
On-chain attestation - backend calls ComplianceRegistry.setAttestation() on each chain where the counterparty needs to transact (per-chain replication, no cross-chain messaging)
Counterparty can transact - isCompliant(wallet) returns true on both off-chain (DashMap) and on-chain (ComplianceRegistry) layers

Counterparty Types#

KYC Individual users on the Compliant settlement path.

Complete KYC via Sumsub WebSDK (identity verification, liveness)
Pre-trade gate checks KYC status, sanctions, and jurisdiction on every order
Attestation expires - renewal required before expiry

Entity Type	Requirements
Individual (KYC)	Identity, address, wallet, sanctions, PEP screening
Company (KYB)	Entity verification, UBO, director KYC, sanctions
Broker	Company KYB + regulatory license + compliance program + insurance
LP	Company KYB + liquidity proof + settlement infrastructure + SLA docs

Attestations expire. Alerts fire at 90 days (info), 30 days (warning), and on expiry (critical - trading blocked).

Travel Rule (IVMS101)#

FATF Recommendation 16 compliance via IVMS101 data format. Originator and beneficiary identity data transmitted between VASPs via Notabene for transfers above jurisdiction-specific thresholds.

WORM Evidence Ledger#

Every compliance decision and trade generates an immutable audit record:

WORM Properties

Hash-chained: Each entry's SHA-256 hash includes the previous entry's hash - tampering breaks the chain
Append-only: Written by the EvidenceSubscriber on the EventBus, cannot be modified or deleted
Retention: Hot (in-memory DashMap) → Cold (PostgreSQL, append-only evidence_entries table)

Per-Chain Replication Architecture#

Compliance Pipeline

Actor

Engine

Contract

Network

The ComplianceRegistry is deployed independently on each chain - there is no cross-chain messaging for compliance state. This is a deliberate architectural choice.

Why per-chain, not cross-chain? Cross-chain compliance would create an oracle dependency for KYC state - if the oracle relay is down, no one could trade. Per-chain replication avoids this: each chain has a self-contained registry that the backend keeps in sync.

How replication works:

Backend KYC service verifies a participant via vendor adapter (Chainalysis, Elliptic)
Backend calls setAttestation() on each chain's ComplianceRegistry contract
Each chain now has an independent, locally-verifiable attestation
isCompliant() checks are pure on-chain reads - no external calls, no oracle dependency

Registry contracts are deployed via CREATE2 for deterministic addresses across chains. The address is the same on every chain, simplifying integrator configuration.

Circuit Breaker for Vendor Adapters#

Circuit Breaker States