Migrating from the Chainalysis sanctions oracle

What does not change

• The interface. Clearlist’s contract exposes isSanctioned(address) returns (bool) with the same selector, 0xdf592f7d. Code that compiled against the Chainalysis interface compiles against ours.
• Reads are free and need no account, on chain and off.
• A listed address returns true; anything else false. No scores, no revert on unknown input.

What changes

• The address constant: one per chain, published on the oracle page and at GET /api/v1/oracle.
• Coverage: OFAC SDN and Consolidated crypto addresses, synced daily by a keeper after the list refresh, with listVersion(), lastUpdated() and sourceListBatch() so a contract or a monitor can tell when it was last updated and from which list batch.
• Verifiability: the exact set the oracle mirrors is published as a snapshot with a Merkle root, and a proof endpoint lets anyone check one address against it without trusting us.
• Operational transparency: the status page shows list freshness, batch checksums and the daily crosscheck of our OFAC address parse against an independent extract.

Switch 1: on-chain, change one constant

// Before: the Chainalysis oracle (deprecated 18 March 2026; no longer updated)
interface SanctionsList {
    function isSanctioned(address addr) external view returns (bool);
}
SanctionsList constant ORACLE = SanctionsList(0x40C57923924B5c5c5455c48D93317139ADDaC8fb);

require(!ORACLE.isSanctioned(msg.sender), "sanctioned");

// After: the Clearlist oracle. Same selector (0xdf592f7d), same return type. Change one constant.
interface SanctionsList {
    function isSanctioned(address addr) external view returns (bool);
}
SanctionsList constant ORACLE = SanctionsList(0x0000000000000000000000000000000000000000); // the address for your chain, from /docs/oracle

require(!ORACLE.isSanctioned(msg.sender), "sanctioned");

// Optional: prove the oracle is current before trusting it
// listVersion() increments on every change; sourceListBatch() is keccak256 of the OFAC batch id it mirrors
// GET https://clearlist.xyz/api/v1/oracle/snapshot returns the full set with a Merkle root; /proof/{address} returns a proof

If your contract holds the oracle address in storage with a setter, the migration is a transaction, not a redeploy. If it is a constant, it is a redeploy; the SanctionsGuard modifier takes the oracle address in the constructor for next time.

Switch 2: off-chain, call the API

Front ends and servers that called the Chainalysis public API get a decision with reasons and the list versions used, and the record is kept so you can show it later.

# Off-chain callers (web and mobile UIs that polled the Chainalysis API):
curl -s -X POST https://clearlist.xyz/api/v1/screen \
  -H "authorization: Bearer cl_live_…" -H "content-type: application/json" \
  -d '{"type":"address","address":"0x098B716B8Aaf21512996dC57EB0615e2383E2f96"}'
# → { "outcome": "block", "reasons": [ { "code": "address.sanctioned", "summary": "…", "evidence": { "list": "OFAC_SDN", … } } ], "lists": { … } }
# Direct address checks are unlimited on every plan, including Free. No card.

Deployments

The contract is built, tested and the keeper runs end to end; addresses appear here the day each network goes live, and the same list is at GET /api/v1/oracle.

Need a chain that is not listed, or want to be told the moment yours is live? Email support@clearlist.xyz with the chain and the contract that reads the oracle.