Invariants
Ten invariants govern the protocol, numbered INV-1 through INV-10
below. The numbers are stable and append-only: once assigned, a number is
not reused, because a later reference elsewhere in this repository — a
contract comment, a concept page, another requirement — may already cite
it. Eight are enforced in-circuit today — they are not style preferences,
and each has a specific attack behind it. Two are not, in different ways,
and each says so in its own entry rather than in a caveat a reader could
skim past. INV-3 names a bound the code could check and does not: a
constant exists for a circuit that is not yet built. INV-10 is not
something a circuit can assert about a version that does not exist yet —
it is a discipline about how predicates are added over time, held by the
maintainers rather than by anything on-chain. See
Conformance for what "not enforced" means for a page
like this one, for how MUST and MUST NOT are to be read, and for the
current status of both.
- INV-1 Acyclicity. The composition graph MUST be acyclic. If A
composes into B and B into A, each inflates
the other's attested income without bound and every downstream credit
decision is poisoned. Enforced by
depth(source) < depth(principal)— a cycle would need an account deeper than itself. - INV-2 Bounded depth. Composition depth MUST NOT exceed
MAX_DEPTH, fixed at compile time at 4. Enforced by asserting depth stays within it wherever an account's depth may increase, increateComposition. - INV-3 Bounded fan-in — not enforced. Fan-in into a principal MUST be
bounded.
MAX_FANIN = 16is measured, not chosen: the proving key for a batched fold circuit stops growing between fan-in 8 and 16, because PLONK pads to a power-of-two domain. But that batched circuit is not built. TodayfoldAggregatefolds one source per call with no count of calls per principal, so fan-in into a principal is unbounded in-circuit — only depth (INV-2) limits the graph. See Conformance for the standing gap and Composition for what is and isn't checked today. - INV-4 Conservation. Entitlement weights leaving a source MUST NOT
exceed 100%. A source cannot promise away more than it earns. Enforced in
createCompositionby asserting that a source's total outgoing entitlement never exceeds 10000 basis points. - INV-5 No double-counting per edge — not fully enforced. A source's income MUST NOT be counted into a principal's aggregate more than once. A nullifier over the (source, principal, period) triple makes a fold under a given period one-shot. But the period is supplied by the caller and checked against nothing, so the same edge folded under two different period labels yields two distinct nullifiers and counts the source twice — see Conformance. Separately, and even where the period is honest, this does not deduplicate a source that reaches a principal along more than one path; see Composition.
- INV-6 Attribution is not entitlement. The two MUST be carried as
distinct weights on an edge. Attribution is what counts toward the
principal; entitlement is what may be claimed. Only entitlement is
conserved — by
INV-4. A parent may see all of a subsidiary's revenue while owning 60% of it. - INV-7 Tier monotonicity. A folded aggregate's tier MUST be the
numerically highest — that is, weakest — tier among its
contributors. An aggregate is only as trustworthy as its weakest input. One tier-3 event in a set of tier-1 events yields a
tier-3 aggregate. Enforced by construction: every fold recomputes the
aggregate's tier through
weakerTierrather than carrying a prior tier forward untouched. - INV-8 Derived identity only. Authorization MUST NOT be gated on
ownPublicKey()— it is prover-claimed and unbound to the signer, so any caller can supply whatever the check expects. Identity MUST be a domain-separated hash of a witness-held secret.ownPublicKey()appears in this codebase exactly once, as a delivery destination. - INV-9 No disclosure without consent. A disclosure MUST NOT be constructible without an active grant covering its exact arguments. Being able to construct a proof is not permission to disclose one. A grant names one verifier and one exact set of predicate arguments, and its id is derived from everything it authorizes, so it cannot be widened after issue. No party other than the holder can issue one covering that holder.
- INV-10 Predicates are append-only — not enforced on-chain. A
registered predicate MUST NOT be redefined. Each is its own circuit with
its own verifier key. New market needs add predicates, because a verifier that
pinned one must keep working forever. There is no runtime verifier-key
registry to check a change against — see Conformance
for this gap alongside
INV-3's. It holds because the maintainers hold it, stated in CONTRIBUTING.md as a promise to verifiers rather than a coding standard.
INV-1 through INV-3 govern Composition;
INV-4 and INV-6 govern how entitlement and attribution differ on a
composition edge; INV-5 and INV-7 govern how a
committed aggregate accumulates; INV-8
governs identity everywhere accounts appear, described in
Accounts; INV-9 and INV-10 govern
disclosure and consent and the
predicate registry.
Changes to any invariant touch the consensus surface. They are one of the six things CONTRIBUTING.md asks for an issue about before any code is written, not something to send as a pull request and discuss afterward.