Skip to content
nokto/docsGitHub (opens in a new tab)

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, in createComposition.
  • INV-3 Bounded fan-in — not enforced. Fan-in into a principal MUST be bounded. MAX_FANIN = 16 is 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. Today foldAggregate folds 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 createComposition by 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 weakerTier rather 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.