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

v0.1.0

The first record. What follows was true of the protocol at this version, against the toolchain named below, and was established by compiling and executing code rather than by reading documentation.

Status and scope

Phase 1a is built and tested at the simulator level. 141 contract tests run through @midnight-ntwrk/compact-runtime directly and do not involve the client stack at all; 229 tests pass across the contracts and the protocol packages, the other 88 being pure-TypeScript unit tests over @nokto-protocol/schema, sdk, and plugin-kit. A full --zk build of account.compact produces prover and verifier keys for all thirteen circuits in 1m54s.

Not demonstrated at this version: PLONK proof generation through the proof server, and transaction submission carrying a contract call. The devnet level is blocked upstream — see Known blockers. Any result reported from this version should say which level it came from.

The @nokto-protocol/* packages are not published to any registry and each carries "private": true. Nothing here is audited.

Verified against

ComponentVersion
compact CLI0.5.2
Compact compiler0.34.0
Compact language version0.26.0
@midnight-ntwrk/compact-js2.5.1
@midnight-ntwrk/compact-runtime0.19.0
@midnight-ntwrk/ledger-v88.1.1
@midnight-ntwrk/midnight-js-contracts4.1.1
@midnight-ntwrk/midnight-js-http-client-proof-provider4.1.1
@midnight-ntwrk/midnight-js-indexer-public-data-provider4.1.1
@midnight-ntwrk/midnight-js-level-private-state-provider4.1.1
@midnight-ntwrk/midnight-js-network-id4.1.1
@midnight-ntwrk/midnight-js-node-zk-config-provider4.1.1
@midnight-ntwrk/wallet-sdk-abstractions2.1.0
@midnight-ntwrk/wallet-sdk-address-format3.1.2
@midnight-ntwrk/wallet-sdk-dust-wallet4.1.0
@midnight-ntwrk/wallet-sdk-facade4.0.1
@midnight-ntwrk/wallet-sdk-hd3.0.2
@midnight-ntwrk/wallet-sdk-shielded3.0.1
@midnight-ntwrk/wallet-sdk-unshielded-wallet3.1.0
pnpm11.3.0
Node>=22

These are pinned in toolchain.json and checked against the workspace on every site build. The versions below were observed during verification but are not pinned by this repository — they are transitive, and a lockfile refresh may move them without changing anything stated here.

ObservedVersion
Node interpreter used25.9.0
@midnight-ntwrk/ledger4.0.0
@midnight-ntwrk/zswap4.0.0
@midnight-ntwrk/onchain-runtime0.3.0

Assumptions of record

Five assumptions carry the design at this version. All five were confirmed by contracts that compile and run. Nothing was refuted; two were sharpened, and the sharpening changed the design.

1 — Custody and conditional release. Confirmed. A contract can hold shielded value and release it only to a caller who proves knowledge of a secret, with authorization never resting on ownPublicKey(). Identity is derived as a persistentHash over a witness-supplied secret and stored in a sealed ledger at construction. Executed: a deposit is custodied; the owner withdraws in full; a caller presenting a different secret is rejected, the funds stay put, and the rightful owner can still withdraw afterwards. Derived identity was checked against an independently computed persistentHash and differs for a different secret.

2 — The delivery constraint. Confirmed, and sharpened. sendShielded creates no coin ciphertext. The constraint this imposes is not that a contract cannot reach a non-caller, but that it cannot inform one: value can be sent, and the recipient has no way to learn of it. The practical consequence is the same and the pull model survives — income lands in the vault and holders withdraw it themselves, in a transaction they sign — but the reason is different from the one the design was written against.

3 — Bounded aggregation. Confirmed, with a language constraint the design had missed. Aggregation over a fixed fan-in is expressible in one circuit, and MAX_FANIN was chosen from measurement. See Constraints below for both the measurement and the constraint.

4 — In-circuit signature verification. Confirmed, better than assumed. jubjubSchnorrVerify is in the standard library; the planned polyfill is unnecessary. The signature is

jubjubSchnorrVerify<size>(
  message: Vector<size, Field>,
  signature: JubjubSchnorrSignature,   // { announcement: JubjubPoint, response: Field }
  verifyingKey: JubjubPoint
): Boolean

jubjubSchnorrVerifyingKey is not in scope in-circuit — it is an unbound identifier there. Key derivation is off-chain only, so an issuer's verifying key is derived off-chain and registered on-chain as a JubjubPoint. Argument order differs between the two sides: in-circuit jubjubSchnorrVerify<n>(msg, sig, vk), in TypeScript jubjubSchnorrVerify(rtType, msg, verifyingKey, sig). Executed: a signature produced off-chain verifies inside the circuit; a tampered message is rejected; a signature under a different key is rejected.

5 — HistoricMerkleTree at depth 20. Confirmed. A membership path built against an earlier root still verifies as the tree grows. A path snapshotted at 50 leaves verified after 30 further insertions, while the same stale path against a plain MerkleTree<20> was rejected — both types run side by side in one contract, so this is a controlled comparison. 1,000 leaves were inserted at depth 20; firstFree() reported 1000, isFull() false, and membership of the last leaf still verified. A path for a leaf never inserted returns undefined.

Constraints this version depends on

These are properties of Compact and Midnight, not of Nokto. A later version must re-check every one of them.

Compact has no mutable locals. const is the only binding form and reassignment is rejected; only ledger ADT fields can be assigned. An accumulating fold therefore cannot be written as a loop over an accumulator — it is an unrolled chain of const bindings, one per contributor. The consequence is real: MAX_FANIN is baked into contract source rather than read from @nokto-protocol/schema, so changing it means regenerating and redeploying the contract, not editing a constant. The schema constant documents what the deployed contract was generated with, and a test asserts the two agree.

fold is a reserved keyword. export circuit fold() is a parse error. The circuit is named foldChildren.

MAX_FANIN = 16, chosen from measurement. Each measured fold_N verifies N child aggregates committed in a HistoricMerkleTree<16>, checks each path against its commitment, sums the amounts, takes the weakest (numerically highest) tier, and re-commits.

NInstructionsPer childProver keyVerifier key
237318610.0 MB2,119 B
466816719.5 MB2,119 B
81,26015838.6 MB2,119 B
162,44115338.9 MB2,119 B
32————

Two things fall out, and they point the same way. The prover key stops growing between 8 and 16: instructions nearly double (×1.94) while the proving key moves ×1.01, from 38.6 MB to 38.9 MB. That is PLONK padding — 8 and 16 land in the same power-of-two domain, so a fan-in of 8 pays for 16 and uses half of it. And 32 is out of reach: the --skip-zk compile, seconds at every smaller N, was still running at 13m42s with 15.9 GB resident against 31 GB of RAM, and was aborted before it could exhaust the machine. Proving-key generation was never reached, so there is no measurement to report. The verifier key is 2,119 bytes at every N: on-chain verification cost does not depend on fan-in at all, only proving does.

The fold was executed, not merely compiled. Two children (300 at tier 1, 700 at tier 3) fold to 1000 at tier 3 — the aggregate inherits the weakest contributor's tier, and reversing the order does not let a stronger later contributor upgrade it. A folded aggregate can itself be a child one level up. A child whose commitment is not in the tree is rejected, so a prover cannot invent contributors. Sixteen children fold in one bounded step.

Re-measuring this table: generate fold_N.compact for N in 2, 4, 8, 16 as described above, compile each with and without --skip-zk, and compare the zkir and keys directory sizes. The probes that produced these numbers were removed along with the verification spike; recover them with git log --diff-filter=D --format=%H -1 -- spikes/ and check out that commit's parent.

degradeToTransient is banned from any signed or committed value. degradeToTransient(b: Bytes<32>): Field silently discards the entire least-significant byte. Varying each of the 32 byte positions in turn, 31 change the output and byte 31 does not; 256 inputs differing only in their low byte collapse to one field value. Had a signed message packed a recipient identity this way, an attacker could grind an account id matching a victim's first 31 bytes in 256 tries and replay an issuer's signature into their own account — with every signature still verifying. It is a transient helper, and the name is the only warning the toolchain gives.

The canonical signed message is Vector<n, Field>, not bytes. Fixed-width big-endian byte packing does not survive contact with jubjubSchnorrVerify. Every Bytes<32> field occupies two message slots, carried as two 128-bit field elements built by unrolled Horner evaluation — each half comfortably under the 255-bit field modulus, so neither is reduced.

insert and insertHash are not interchangeable, and mismatching them fails silently. checkRoot returns false rather than raising.

InsertCircuit-side root helperTypeScript lookup
insert(leaf)merkleTreePathRoot<20, Bytes<32>>(path)findPathForLeaf(rawLeaf)
insertHash(hash)merkleTreePathRootNoLeafHash<20>(path)pathForLeaf(index, hash)

Crossing them produces a contract that compiles, runs, and rejects every valid proof. Every circuit that touches a Merkle tree must state which pair it uses.

Leaf lookup must not scan. findPathForLeaf measured 0.55 ms against pathForLeaf at 0.14 ms over 1,000 leaves — 4.1× slower. The O(n) warning is real but immaterial at this size, and will not be at 10⁶. An SDK must track leaf indices and use pathForLeaf.

Known blockers

The devnet level cannot be reached with any released client stack. This is an upstream version split, not a defect in this repository, and nothing here can code around it.

Compiling and deploying pull in two different compact-runtime versions, and both cannot be satisfied:

PathCompilerEmitsHas jubjubSchnorrVerify
Current toolchain0.34.0 (language 0.26.0)0.19.0yes
Older toolchain0.31.1 (language 0.23.0)0.16.0no
Client stackWants runtimeLedger
midnight-js 4.1.1 (latest release)0.16.0v8
midnight-js 5.0.0-beta.70.19.0-rc.0v9

Deploying with the latest release requires compiling with a compiler that has no in-circuit Schnorr — and in-circuit issuer signature verification is the trust anchor of the whole design. JubjubSchnorrSignature is an unbound identifier at language 0.23. Compiling with the current toolchain leaves only the 5.0.0 beta line as a client.

The devnet itself is not the problem. midnight-node 0.22.5, indexer-standalone 4.2.1, and proof-server 8.1.0 all run healthy; a wallet derives, receives NIGHT from the dev-preset genesis wallet, registers UTXOs for DUST generation, and observes DUST accrue. Two real transactions were submitted and confirmed. The network, the wallet SDK, fee handling, and submission all work. What fails is deploying the contract.

The beta line was tried and produced four sequential breaks: a changed httpClientProofProvider shape requiring a zkConfigProvider rather than a bare URL; a ledger split, where a v8 LedgerParameters passed into a v9 function fails outright; wallet-sdk-facade@5.0.0-beta.2 importing Clock from a package it does not declare as a dependency; and a changed createKeystore signature. Each is individually surmountable. Together they mean a green devnet result would attest to an undocumented, in-flight beta rather than to anything this protocol would ship on. The end-to-end package stays pinned to the stable line, where the wallet path demonstrably works.

What changed

First record.

What invalidates this record

  1. Any pin in the matrix above moves. This half is enforced: toolchain.json is checked against the workspace, and the current release page is checked against toolchain.json. A bump fails the build until the record is redone.

  2. A midnight-js 5.0.0 stable release, or a compact-js release pinning compact-runtime 0.19.0 final rather than an rc. The cheap check is one command:

    npm view @midnight-ntwrk/compact-js dependencies.@midnight-ntwrk/compact-runtime
    

    If that prints 0.19.0, re-run the end-to-end package and the blocker above is obsolete.

  3. A wallet-sdk-facade release on ledger-v9 that declares its Clock dependency.

  4. MAX_FANIN is revisited, or a new circuit touches a Merkle tree. The fan-in table and the insert/lookup pairing are the two places where a change elsewhere silently invalidates something stated here.