Draft standard: on-chain risk verdicts

This is a working draft, written to be discussed in the open before anything is proposed formally. It describes a schema for publishing a token risk verdict as an attestation, the semantics a consumer can rely on, and the contract interface a protocol would call. Interfaces here are specifications. No implementation is given.

Schema VMT-RiskVerdict-v1

One attestation is one verdict about one token, taken at one block.

• checkBitmap — nine bits, one per published check, set when the check reached an answer and found the condition present.
• notCompletedBitmap — nine bits, one per published check, set when the check did not reach an answer at all. A check that did not run is not a check that passed, and the two bitmaps together say which is which.
• clusterId — the cluster identifier the deploying wallet belongs to, or zero.
• evidenceCID — a content address for the evidence bundle the verdict was computed from.
• scannerVersion — the version of the rules that produced the verdict.
• historicalTs — the second at which the observation was made, which is not the second the attestation was written.

The verdict itself is an enumeration, and the enumeration is closed: Clear, Caution, Adverse, Withheld. Withheld is the honest fourth value — it says a verdict was attempted and is not being published, which a consumer must treat as the absence of a clearance rather than as a clearance.

Attester registry

An attestation means nothing without a named attester. The registry maps an attester address to the schema it is permitted to write under and the block range over which its attestations are recognised. Removing an attester does not retract what it wrote: history stays readable, and a consumer decides for itself whether to keep honouring it.

Freshness

A verdict is a statement about a block, so it ages. A consumer states the age it will accept and the guard answers against that age; an attestation older than the stated window is treated as the absence of a clearance. No verdict is ever treated as valid for an unbounded time.

Daily root and per-verdict proofs

Writing every verdict on chain costs more than it is worth. Instead, the day's verdict leaves are reduced to a single Merkle root and only that root is attested. A consumer that holds one verdict presents the leaf and its proof, and the guard checks the proof against the attested root for that day.

A leaf is a SHA-256 over the verdict identifier and its fields in a fixed, published order — the order is given on the identifier specification page. An unpaired node is carried unchanged rather than duplicated: duplicating the last node admits two different leaf sets that produce one root, and a root that two different histories can produce proves nothing.

Guard interface

Two entry points, because there are two situations. The first is a token that has its own attestation. The second is a token covered only by the day's root, which is the common case.

• verdictOf(token) — the verdict from a direct attestation on that token, where one exists.
• isClearedWithProof(token, leaf, proof) — whether the supplied leaf is in the attested daily root and carries a clearing verdict inside the freshness window.
• attester() — the attester whose root this guard honours.
• schemaUID() — the schema those attestations are written under.

A guard that cannot answer returns the absence of a clearance. It never returns a clearance by default, and a caller that treats a failure as a pass has misread this document.

Solana

The same content, expressed as a program-derived account per daily root rather than an attestation. The account holds the root, the schema version, the attester and the day; a verdict is checked by presenting the leaf and proof to a read-only instruction. Enumerations, bitmaps, freshness and the carried-node rule are identical, so a verdict means the same thing on either chain.

Conformance tests

A conformance suite accompanies this draft in a later release. It covers: the two bitmaps disagreeing about the same check; a proof against the wrong day's root; an attestation from an attester removed from the registry after it was written; a verdict past its freshness window; an unpaired leaf at the end of a day; and an empty day. Every case asserts that the guard withholds a clearance rather than granting one.

Reference implementation

The reference implementation is the live VetMyToken endpoint documented at the API reference.