The object model
This page defines the entities the protocol operates on and the requirements that hold of each one, so that a second implementer has something to build against instead of reconstructing the model from prose spread across the concept pages. It defines what a thing is. Operations defines what happens when a circuit is invoked, and does not repeat here. Where a rule is already stated as an invariant in Invariants, this page cites it rather than restating it, so the two pages cannot drift apart by one of them being edited and not the other.
Requirement keywords follow Conformance.
Account
An account is a receiving account: a person's own payout account, a platform's payout record, a marketplace seller account, or an agent earning on someone's behalf. It carries a holder type, a subject binding, a vault position, an income log, and a committed aggregate — each defined below.
- MODEL-1 An account MUST be identified by a derived identity: a domain-separated hash of a secret held privately by the holder.
Holder
The holder is whoever controls the account's secret — the value hashed to produce the account's derived identity. A holder is a person, a company, or an agent acting on someone's behalf, and the protocol treats the three identically: nothing about how an account composes, accrues income, or discloses depends on which kind of holder it has.
- MODEL-3 An account MUST carry a holder type of
person,company, oragent. - MODEL-4 A protocol rule MUST NOT branch on holder type. An agent account composes exactly as a person's does.
Derived identity
An account's identity is never a raw public key. ownPublicKey() is a
value the prover asserts about themselves, with no binding to whoever
actually signed the transaction — a check against it can be satisfied by
any caller willing to supply the value the check expects. A derived
identity closes that gap: it is the hash of a secret the holder proves
they hold, produced by a fixed, domain-separated function, so a claim
about an account can only be made by whoever holds that account's secret.
- MODEL-2 An implementation MUST NOT gate authorisation on a
prover-asserted value. See
INV-8.
Subject binding
A subject binding is the record that connects an account's derived identity to a claim about who holds it. It names the binding scheme that produced it and the holder type asserted under that scheme. Today the only scheme that exists proves control of a key and nothing more — it does not establish that the holder is the person, company, or agent operator it claims to be. A stronger scheme is reserved, not implemented.
A subject binding is metadata about an account's identity; it is never the source of that identity. The subject id an account is known by comes from the holder's own secret, not from whatever bound it — which is what lets a holder move to a stronger binding scheme later without disturbing the income log, compositions, or grants already recorded against that id.
- MODEL-5 An account MUST carry a subject binding recording the binding scheme used and the holder type asserted under it.
- MODEL-6 A subject id MUST be derived from the holder's own secret and MUST NOT be issued by the binding scheme, so that a later re-binding does not disturb anything referencing the account.
- MODEL-7 Binding schemes MUST be ordered with a higher number being stronger. Scheme 1 is self-asserted. Scheme 2 is reserved.
- MODEL-8 An implementation MUST NOT mint a binding at a scheme it cannot establish.
Binding-scheme strength runs in the opposite direction from assurance-tier strength, where the lower number is stronger — see Assurance tiers. The two orderings were defined at different times for different reasons, and getting one backwards for the other is the easiest mistake to make in this specification.
Issuer
An issuer is a registered party whose signature can carry income into an account's log. An issuer record holds a verifying key, an assurance tier, and a revocation state — the tier a claim enters at is governed by this record, not by whatever tier the issuer's own signature asserts, so an issuer cannot promote its own claims by signing a stronger number than it is registered for.
- MODEL-15 An issuer MUST be recorded with a key, an assurance tier, and a revocation state.
Income event
An income event is one payment, claimed by an issuer on behalf of an account. It is the unit the income log accumulates and the committed aggregate summarises.
- MODEL-9 An income event MUST carry an amount, a currency, an occurrence time, an assurance tier, an issuer key id, and a claim nonce.
- MODEL-10 An income event MUST be recorded as a commitment in an append-only log. Its amount MUST NOT appear in public state.
Committed aggregate
A committed aggregate is an account's running summary of the income
events recorded against it, or folded into it from composed sources: a
total, the period the total spans, and the weakest assurance tier among
its contributors — never the strongest, and never an average, because a
total is not more trustworthy than its least-trustworthy component. How
that tier is computed on each accrual and each fold is INV-7; this
entity only states what the aggregate holds.
- MODEL-11 A committed aggregate MUST carry a total, period bounds, and the weakest assurance tier among its contributors, and MUST be committed rather than held in public state.
Vault position
A vault position is a holder's claim on the value a vault custodies on their behalf. A position is not a balance sitting in the clear against an account; it is a commitment binding the account identity, the balance, and a nonce, so that the set of all positions reveals nothing about what any one of them holds.
- MODEL-12 A vault position MUST be a commitment binding the account identity, the balance, and a nonce. A position MUST NOT be recorded as a public balance, which would publish exactly what shielding protects.
- MODEL-13 A position's nonce MUST be unpredictable to anyone but the holder. Without it, two holders with equal balances produce identical commitments, so the set of positions would leak which accounts hold the same amount and a balance could be confirmed by guessing it.
Composition edge
A composition edge attributes a source account's income to a principal
account. Every edge carries two distinct weights: how much of the
source's income counts toward the principal's aggregate, and how much of
that counted income the principal may actually claim. The graph these
edges form is acyclic and depth-bounded (INV-1, INV-2), an
outgoing account's entitlement never exceeds what it earns (INV-4),
attribution is not conserved the way entitlement is (INV-6), and a
given edge cannot be folded into its principal's aggregate twice in the
same period (INV-5) — this entity states only what an edge carries, not
how those rules are enforced.
- MODEL-14 A composition edge MUST carry a source, a principal, an attribution weight, and an entitlement weight.
Grant
A grant is the permission a holder issues for one verifier to receive one
predicate answer. Being able to construct a proof is not the same as
having permitted one; a grant is what turns the former into the latter.
Its id is derived from everything it authorises, so widening what a grant
covers is impossible after the fact — only issuing a new grant can
authorise more. INV-9 governs who may issue a grant and what a
disclosure circuit must check before acting on one; this entity states
only what a grant carries.
- MODEL-16 A grant MUST bind the principal, the verifier, the predicate, every predicate argument that changes the meaning of the answer, and an expiry.
Disclosure
A disclosure is a proof that a predicate holds over a principal's
composed income, produced under an active grant and addressed to the
verifier the grant names. It is not a stored entity: producing one writes
nothing to the ledger, and a verifier learns only the predicate's
answer — not the aggregate, not any contributing income event, and not
which accounts contributed. See Predicates for the
registry of predicates a disclosure can prove, and INV-9 for the
consent a disclosure circuit must check before it runs.