Skip to main content
KeyStone enforces compliance at settlement time. Compliance is the only step that requires KeyStone’s off-chain involvement - everything after compliance is handled autonomously by the contracts.

​
Three-layer architecture

​
1. Off-chain screening

KeyStone’s compliance oracle screens parties via external APIs: LSEG World-Check - Entity-level screening against 100M+ records across 240+ countries:
  • Sanctions lists (OFAC, EU, UN, HMT)
  • Politically Exposed Persons (PEPs)
  • Adverse media
  • Enforcement actions
CipherOwl - Wallet-level risk scoring across 50+ blockchains:
  • Sanctions exposure
  • Mixer/tumbler interaction
  • Fraud and scam associations
  • Protocol risk attribution

​
2. On-chain attestation

After screening, the Pass result is attested to the ComplianceRegistry smart contract via an M-of-N bundle of independent EIP-712 attester signatures:
The contract recovers each signer and requires a threshold of distinct attesters before recording the attestation - the submitter is not trusted, the signatures authorize. No personal data is stored on-chain: only the hashed party identifier, the status, and a hashed reference.

​
3. Contract-enforced gate

The KeystoneSettlement contract checks areAllPartiesCleared(settlementId, partyHashes) on the ComplianceRegistry before executing - every party hash bound at registration must be attested Pass. No one can skip compliance: the contract enforces it at the moment funds move.

​
How it works in a settlement

​
The gate fails closed

Only a full set of PASS verdicts covering every party clears the compliance gate. Everything else stops the settlement:
  • Any FAIL ends the settlement in REJECTED.
  • Any FLAGGED parks it in COMPLIANCE_CHECKING for a manual decision.
  • A verdict outside the PASS/FLAGGED/FAIL vocabulary parks it too: a value KeyStone cannot interpret neither clears the gate nor terminally rejects.
  • Screening that leaves any party without a verdict parks it as well - a party nothing screened is not a party that passed. Wallet providers apply only to wallet-bearing parties, so entity providers are what cover every party.
  • A provider error or open circuit breaker parks it with the screening outcome unknown.
The template that would make screening vacuous is not creatable: a compliance_check action with "resolution": "immediate" must name at least one entity or wallet provider, and template create and update requests that violate this are refused with 422. The same binding with a manual, webhook, or poll resolution is valid without providers - it configures a pure human-decision gate that only the compliance-decision endpoints resolve.

​
Manual compliance decisions

When a party is flagged, a compliance officer reviews the screening details in the KeyStone Dashboard and submits a decision. Decisions can also be submitted via the API:
Decisions are:
  • approve - Override the flag, allow the settlement to proceed. Approve is refused with 409 unless a recorded screening outcome covers every party the template requires screening for - including a party none of the configured providers is able to screen, which can only be rejected
  • reject - End the settlement: it transitions to REJECTED (nothing was deposited yet). Reject never requires evidence
Both decisions are recorded in the settlement’s event history with full audit context. The compliance-decision endpoint is the only way to resolve a settlement parked on a compliance check. Provider callbacks (POST /v1/callbacks/{provider}) are rejected with 409 whenever the transition would exit or enter a state the settlement’s pinned template binds a compliance_check action to - a callback carries no screening evidence and cannot substitute for screening or for a compliance officer’s decision.

​
Compliance data on the API

Each party’s compliance check is exposed on the settlement resource with:
  • status - PASS, FLAGGED, or FAIL per screening
  • chain_attested_at - when the on-chain M-of-N attestation landed in the ComplianceRegistry (null until it does). Use this to distinguish “screened off-chain” from “attested on-chain and able to execute”.
Admin views additionally expose principal_id, linking the check to the screened principal’s full audit trail.

​
Open attestation interface

KeyStone operates the default compliance oracle, but the attestation interface is open:
  • M-of-N attesters: A Pass is recorded only when a threshold of distinct attester keys each sign the same attestation. The contract recovers every signature and counts distinct recognized signers, so no single key can forge a Pass on-chain. The attester set and threshold are fixed at the registry’s deployment and cannot be changed afterwards. On the current testnet deployments every key in the set is held by a single KeyStone process, which signs the whole threshold bundle itself. The independence the threshold is designed for is therefore a property of the contract and not of the deployment today. Independent attester operators are the design goal. See ComplianceRegistry.
  • Platform-operated oracles: Platforms can run their own compliance screening; on-chain enforcement is the standardized threshold gate
  • Verifiable: All attestations are permanent on-chain records - a false attestation is provable liability
This design separates screening (off-chain, provider-specific) from enforcement (on-chain, standardized gate check).

​
What KeyStone stores

KeyStone never stores raw KYC/AML data. We store only compliance status (pass/fail/flagged) and a reference ID pointing to the compliance provider’s record.
The compliance provider (LSEG, CipherOwl) remains the source of truth for the actual screening data. KeyStone only records the outcome.

​
Screening performance

See ComplianceRegistry for full contract documentation.