Predicates
A predicate is a statement a Disclose proof can assert. income_at_least
is the only one that exists, and it is also the only evidence a new
implementer has for what a second predicate is required to look like —
the rules below are what today is only implied by that single entry, made
explicit so a first outside contributor does not have to reverse-engineer
them from one example.
Rules a new predicate must satisfy
- PRED-1 Each predicate MUST be its own proof statement with its own verifier key.
- PRED-2 Every predicate argument that changes the meaning of the answer MUST be bound into the grant, so that permission to prove one threshold cannot silently cover another.
- PRED-3 A predicate MUST NOT write to public state. An earlier design recorded a hash of the disclosed arguments on-chain; because thresholds are low-entropy and a verifier already knows which principals it deals with, that hash was itself a linkable public trail.
- PRED-4 A registered predicate MUST NOT be redefined. New market needs add predicates.
- PRED-5 A predicate MUST be registered with an id and a version.
- PRED-6 The verifier's challenge MUST NOT form part of the grant, so that freshness does not require a new grant per request.
PRED-4 is this registry's expression of INV-10, which states the
append-only discipline; see Conformance's annex for
whether anything enforces it.
PRED-5's "id and a version" is not a field this codebase adds to a
predicate's arguments — it is the registry table below: the Id and
Version columns are what "registered" means here, kept alongside the
circuit name rather than inside it.
PRED-6 is easy to misread as an omission rather than a boundary. A grant
authorizes a question — this verifier, this predicate, these arguments —
and nothing about who asks it or when. Folding the challenge into the
grant would make the grant answer both "may this be asked" and "is this
instance of asking fresh", and a holder would have to re-grant on every
request just to keep the second property true. Keeping the challenge out
lets OP-17 and OP-18 run as two independent checks: the grant is
verified first, over arguments that do not change per request, and the
challenge is bound after, fresh on every one, without the holder in the
loop for either.
PRED-3 restates the same rule as OP-19 from the other direction — not
"this circuit happens not to write anything" but "no predicate may", which
is why the reason travels with the rule rather than living only in one
circuit's comments: a design that re-adds a write for the next predicate,
for what looks like an unrelated reason, would reopen exactly this trail.
The registry currently holds one entry:
| Predicate | Id | Version | Circuit |
|---|---|---|---|
income_at_least | 1 | 1 | discloseIncomeAtLeast |
discloseIncomeAtLeast
Proves that a principal's composed income over a period is at least a threshold, at an assurance tier no weaker than a stated minimum — and nothing more. Not the total, not how many accounts contributed, not who they are, not any individual amount.
Its arguments are:
principalId— the account whose aggregate is being proven over.verifierId— who the proof is addressed to.threshold— the minimum total being proven.minTier— the weakest assurance tier the proof will accept; lower is stronger, sominTier: 1accepts only aggregates built entirely from issuer-attested income.periodStart,periodEnd— the window the aggregate must sit inside.challenge— chosen by the verifier and bound into the proof, so it cannot be replayed against a later request or redirected to a different verifier.
threshold, minTier, periodStart, and periodEnd — not just the
predicate's name — are hashed together into incomeAtLeastParams, and that
hash, together with principalId, verifierId, and the predicate itself,
is what the active grant the
circuit checks must cover. That is what stops permission to prove "income
over 1,000" from silently covering "income over 1,000,000": a different
threshold produces a different params hash, which is a different grant.
challenge is not part of the grant at all — it is checked separately, for
freshness, so it can be fresh on every request without needing a new grant
each time.
The circuit checks, in order: an active grant covering these exact
arguments; that the disclosed aggregate matches its on-chain commitment
(so a prover cannot simply assert a total that clears the threshold); that
the aggregate's period sits inside the requested window; that the
aggregate's tier is no weaker than minTier; that the total meets
threshold; and finally binds the challenge into the proof. Only the
result of that chain — not the aggregate itself — leaves the circuit.
This circuit writes nothing to the ledger. An earlier design recorded a hash of the disclosed arguments on-chain as an audit trail; that turned out to be a linkable public record on its own, since thresholds are low-entropy and a verifier already knows which principals it deals with. See Disclosure and consent for why that matters and where freshness comes from instead.
See Verifying a disclosure for what a verifier checks against this proof's public claim, and Write a verifier for building one.