Operations
Everything in Nokto is an application of five operations. This page states what each one requires of a caller, what it checks, and what it changes. Requirement keywords follow Conformance; the entities these operations act on are defined in The object model, and this page does not redefine them.
| Operation | What happens |
|---|---|
| Receive | A registered issuer signs an income claim. Value enters the vault; a commitment is appended to the account's income log at the issuer's assurance tier. |
| Compose | A source account attributes its income to a principal, with an attribution weight and an entitlement weight. Cycles are rejected. |
| Claim | A principal exercises its entitlement. Value moves within the vault and reaches the holder on withdrawal. |
| Grant | A holder permits one verifier one predicate answer, time-bounded and revocable. Nothing else in the protocol creates this permission. |
| Disclose | A verifier receives a ZK proof that a predicate holds — and learns nothing else. |
An agent earning for its owner is one composition. A company's agents composing into the company, and the company into its partners by equity, is the same edge applied twice. Corporate capital structure is not a subsystem here; it is a weight on an edge — see Composition.
Where each operation lives in the contract
The account contract is these operations composed into circuits, included from separate part files and deployed as one contract:
| Operation | Circuit(s) |
|---|---|
| Receive | recordIncome |
| Compose | createComposition (create the edge), foldAggregate (fold a source's committed aggregate into a principal's) |
| Claim | depositShielded, withdrawShielded |
| Grant | grantDisclosure, revokeGrant |
| Disclose | discloseIncomeAtLeast — see Predicates |
Receive
recordIncome is invoked by the account named as recipient in the claim,
identified the way every account is — a derived identity, never a raw key
(MODEL-1, MODEL-2). The recipient must already carry a usable subject
binding; an unbound or retired subject accrues nothing. What actually lets
value in is a signature: a registered issuer attests the claim, and the
circuit checks that attestation before recording anything.
- OP-1 Receive MUST verify the issuer's signature over the signed message before any value accrues.
- OP-2 Receive MUST assert that the tier in the signed message equals the issuer's registered tier. An issuer MUST NOT be able to promote its own claims by signing a stronger tier than it is registered for.
- OP-3 Receive MUST reject a claim whose claim nonce has already been used.
- OP-4 Receive MUST reject a claim signed by a revoked issuer.
A satisfied claim appends a commitment to the account's income log
(MODEL-9, MODEL-10) and accrues the amount into the account's committed
aggregate (MODEL-11), recomputing the aggregate's tier rather than
carrying a prior one forward — the same rule that governs a fold,
INV-7. A revoked issuer's past claims are not unwound: the registry keeps
a revoked record precisely so that income already recorded stays
auditable, and OP-4 only stops claims signed after revocation from
entering.
Compose
createComposition is invoked by the source account, and only the source:
the principal cannot create the edge, because it is the source's income
being attributed away, and consent has to come from the party giving
something up. See Composition for why
aggregation is hierarchical rather than a walk of the graph.
- OP-5 Compose MUST assert
depth(source) < depth(principal). - OP-6 Compose MUST assert that the total entitlement weight leaving a source does not exceed 100%.
- OP-7 Compose MUST be invocable only by the source account, whose identity is derived rather than asserted.
OP-5 is what keeps the composition graph acyclic without ever walking
it — INV-1, INV-2. OP-6 is conservation, INV-4: a source cannot
promise away more entitlement than it earns. OP-7 is the same derived-identity
discipline as everywhere else an account acts for itself, INV-8. A
satisfied call records the edge, its weights, and — where the principal's
depth has nothing yet depending on it — raises the principal's depth to
satisfy OP-5.
Folding is a separate circuit, foldAggregate, invoked by the principal
against a source it already has an edge from. Each call folds one source's
committed aggregate into the principal's, weighted by the edge's
attribution — not its entitlement, which is what may be claimed rather
than what counts toward the total (MODEL-14, INV-6).
- OP-8 Folding a source's aggregate into a principal's MUST reject a replay of the same
(source, principal, period). - OP-9 The tier of a folded aggregate MUST be the numerically highest — that is, weakest — tier among its contributors.
OP-8 is enforced by a nullifier over the triple, INV-5; it stops the
same edge from being folded twice in one period, but does not deduplicate
a source that reaches a principal along more than one path. OP-9 is
INV-7 applied at fold time rather than at accrual: the principal's tier
after the fold is never stronger than the weaker of what it already held
and what the source contributed.
Claim
Value reaches a vault by depositShielded and leaves it by
withdrawShielded. Both credit or debit the caller's own position only —
depositShielded credits whoever calls it, for the same reason
withdrawal pays only the caller: crediting a third party would need that
party to learn a position nonce out of band, which this protocol does not
provide a channel for.
- OP-10 Value MUST remain under the protocol's control for as long as entitlement rules apply to it. Once value reaches a holder's wallet it is spent with the holder's own key, and no rule reaches it.
- OP-11 Withdrawal MUST deliver only to the transaction caller.
sendShieldedemits no coin ciphertext, so a non-caller would have to learn the coin's nonce out of band, which a protocol cannot depend on.
OP-10 is the requirement: a vault position is a claim on value the
contract still custodies, and every rule this specification states about
entitlement — conservation, tier, replay — presumes the value it governs
has not yet left. OP-11 is not a second, independent rule; it is what
OP-10 collapses into given what Midnight actually offers a contract for
delivering shielded value. A contract can direct sendShielded at any
key, but the primitive creates no coin ciphertext for that key to
discover the coin by — only the caller who submitted the transaction is in
a position to learn the resulting coin's nonce. Any delivery target other
than the caller would be entitlement enforced up to the door and then
handed to a mechanism that cannot address anyone else. Pull-only
withdrawal is therefore not a design preference sitting beside OP-10; it
is the one delivery shape OP-10 admits under this constraint.
withdrawShielded further requires:
- OP-12 A vault position MUST be spendable at most once.
OP-12 is enforced by a nullifier over the spent position's commitment,
the same construction OP-8 uses for a fold — one-shot by nullifier
wherever a commitment could otherwise be replayed. A withdrawal that does
not exhaust a position reinserts the remainder as a fresh commitment
(MODEL-12, MODEL-13) rather than mutating the old one; nothing in this
protocol edits a commitment in place.
Grant
grantDisclosure and revokeGrant are invoked by the holder over their
own account: the principal a grant covers is always the caller's derived
identity, never a parameter another party could supply. See
Disclosure and consent for the
consent model Grant and Disclose together implement.
- OP-13 A grant MUST be issuable only by the holder, over the holder's own derived identity. No partner, platform, or administrator can issue a grant covering another holder.
- OP-14 A grant's id MUST be derived from everything it authorises, so that a grant cannot be widened after issue.
- OP-15 A grant's expiry MUST be evaluated against block time. It MUST NOT accept a time supplied by the prover.
- OP-16 Revocation MUST be final for the exact scope revoked. A holder who changes their mind issues a new grant rather than reinstating a withdrawn one.
OP-13 and OP-14 together are INV-9: no one else can mint a grant
covering a holder, and the grant that is minted cannot later be stretched
to cover more than it named at issue — a different threshold, verifier, or
predicate argument hashes to a different id, which is a grant that does
not exist until issued. OP-15 is checked where a grant is consumed
rather than where it is issued — issuing a grant only records an expiry
value, and it is the check every Disclose call makes first (OP-17) that
evaluates that value against the chain's own clock rather than a
prover-supplied one, so a lapsed grant cannot be revived by asserting it
is still earlier than it is. OP-16 is enforced by keeping revoked
grant ids in their own set, permanently: re-issuing the same id is
rejected, so a revoked scope stays revoked and a holder who wants to
permit it again does so under a new set of arguments — a visibly
different grant.
Disclose
discloseIncomeAtLeast is the only registered predicate today (see
Predicates); everything this section states about
Disclose describes the check every predicate circuit performs, in the
order it performs it.
- OP-17 Disclose MUST verify an active grant covering the exact arguments before performing any other check.
- OP-18 Disclose MUST bind a verifier-supplied challenge into the proof, separately from the grant.
- OP-19 Disclose MUST NOT write to public state.
- OP-20 Disclose MUST NOT reveal the aggregate total, the number of contributors, their identities, or any individual amount.
OP-17 is INV-9 at the point of use: being able to construct a proof
over a principal's aggregate is not permission to disclose it, so the
active-grant check runs before the aggregate is even read. OP-18 is
independent of that grant: a grant authorises the question, not any
particular answer session, so freshness against replay has to come from
somewhere else — a challenge the verifier chooses and the circuit binds
into the proof, checked separately from consent rather than folded into
it. OP-19 and OP-20 together are what makes a disclosure a proof and
not a record: nothing is written, and the only fact that leaves the
circuit is whether the predicate holds, at the tier and over the period
the verifier asked about — not the total that cleared the threshold, how
many accounts folded into it, which accounts they were, or what any of
them individually contributed.