[Open Question] Machine-readable compliance reason-code taxonomy

[oa-sarvesh]

Context

The compliance layer (Whitepaper §6.3) proposes standardizing the signaling interface, not the rule engine: canTransfer(from, to, amount, context) -> {allow | deny + reason-code} with standard machine-readable reason codes (e.g., INELIGIBLE_RECEIVER, JURISDICTION_BLOCKED, HOLDER_CAP_EXCEEDED, LOCKUP_ACTIVE, SANCTIONS_HIT, TRAVEL_RULE_PENDING).

The question

Can the community agree on a stable, machine-readable compliance reason-code set that maps cleanly onto FATF / MiCA / BSA-AML obligations?

How to contribute

• Propose a v0.1 reason-code enumeration with definitions and the regulatory obligation each maps to.
• Identify codes that are jurisdiction-specific and should live in an extension namespace.
• Comment on granularity trade-offs: detailed codes aid remediation but may leak information about parties or rules.

Reference: Whitepaper §6.3, §5.2 (event schema).

[msantore]

NIST OSCAL doesn’t define AML/CFT reason codes, that remains an OTAS question.

Its Assessment Results model may nevertheless be useful at the evidence seam: it can represent evidence from OTAS’s proposed canTransfer(...) interface alongside structured control findings and risks.

If the community defines a stable reason-code taxonomy, OSCAL’s namespaced props offer a clean extension point while keeping the OTAS transfer interface independent of any specific GRC or security-control framework.

Happy to loop in the OSCAL community if helpful.

[MukulKolpe]

Thanks @msantore, much appreciated.

The independence constraint you raise is the one that matters most here. I think OTAS should own the canonical code list, with OSCAL referencing it rather than the other way round, since a deny code has to be readable by settlement systems that will not process an OSCAL document. That's what makes the props route work; it adds without creating a dependency.

Two things your framing usefully surfaces for the enum work itself.

If a code is returned by canTransfer(...) at transfer time and later carried in an assessment record, it should probably be the same token; otherwise reconciling what the ledger enforced against what the evidence reports gets painful.
If assessment records carry these codes, they outlive the moment they're emitted, since evidence gets read long after the transfer. That's an argument for versioning the enum explicitly and keeping the core set small and additive, rather than re-cutting it later.

On the granularity question raised above, the evidence seam you've described actually helps, because the two audiences want opposite things. A counterparty at transfer time should arguably learn as little as possible, since detailed codes leak rule structure and in sanctions cases disclosure may itself be a problem, while an assessor after the fact wants specificity. Separating them would mean a coarse enum in the return value, with the detail living in the evidence path to authorized parties.

Thanks again for the thoughtful input, and for the offer to bring in the OSCAL community. Would be great to pick this up on the next community call if you're able to join; the evidence seam feels like a good topic for a live discussion as well.

[SergeevDmitry]

A practical data point from running a permissioned EVM token in production, and one concern on granularity.

Granularity leaks on public chains. On EVM, revert data and events are public. A SANCTIONS_HIT returned on-chain effectively publishes "this wallet is sanctioned" to anyone watching, and JURISDICTION_BLOCKED reveals where the holder lives. I'd suggest two tiers:

• Public, on-chain codes: coarse and non-revealing. They answer which side and what kind of remedy, not why.
• Detailed codes: returned off-chain to authorized parties (the holder, their institution, the transfer agent) through the identity/compliance interface, not emitted on the ledger.

A minimal public tier that already works. ERC-7943 (Final) defines side-specific errors: ERC7943CannotSend(account), ERC7943CannotReceive(account), ERC7943CannotTransfer(from, to, amount), ERC7943InsufficientUnfrozenBalance(...). They map cleanly to coarse OTAS codes:

ERC-7943 / native	OTAS public code
CannotSend	INELIGIBLE_SENDER
CannotReceive	INELIGIBLE_RECEIVER
CannotTransfer (offering-level rule)	TRANSFER_RULE_BLOCKED (detail off-chain: cap, lockup, jurisdiction)
InsufficientUnfrozenBalance	BALANCE_FROZEN
token paused	TOKEN_PAUSED

Proposed addition: ELIGIBILITY_EXPIRED, distinct from INELIGIBLE_*. KYC and accreditation are time-bound. Our registry keeps status ∈ {Unknown, Allowed, Blocked} plus an optional validUntil, which gives three operationally different states without revealing any reason:

• NOT_ONBOARDED (Unknown): onboard first
• ELIGIBILITY_EXPIRED (Allowed, past validUntil): renew the credential; nothing adverse happened
• INELIGIBLE (Blocked): adverse; detail only off-chain

Separating "expired" from "blocked" matters for remediation and for not stigmatizing a holder whose KYC simply lapsed.

Reference implementation: https://github.com/devlab-group/rwa-platform-evm (IComplianceRegistry, IERC7943). Related: ERC-7943 survey addition in #44.