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

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.

OperationWhat happens
ReceiveA 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.
ComposeA source account attributes its income to a principal, with an attribution weight and an entitlement weight. Cycles are rejected.
ClaimA principal exercises its entitlement. Value moves within the vault and reaches the holder on withdrawal.
GrantA holder permits one verifier one predicate answer, time-bounded and revocable. Nothing else in the protocol creates this permission.
DiscloseA 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:

OperationCircuit(s)
ReceiverecordIncome
ComposecreateComposition (create the edge), foldAggregate (fold a source's committed aggregate into a principal's)
ClaimdepositShielded, withdrawShielded
GrantgrantDisclosure, revokeGrant
DisclosediscloseIncomeAtLeast — 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. sendShielded emits 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.