Skip to main content

ZK L1 Proof Verification & Toccata Script Building

HardKAS provides experimental, local-only CLI and SDK tooling for Zero-Knowledge proofs that target Kaspa Layer 1 (OpZkPrecompile, 0xa6). Nothing here signs or broadcasts a transaction, and nothing here is an on-chain claim: a local result never predicts what a node will accept. On-chain acceptance is shown only by the simnet suites against a real rusty-kaspad v2.1.0.

HardKAS keeps three things apart: fixture coherence (self-attested digests), the Groth16 pairing check (snarkjs over BN254, trusted only for an anchored key), and Toccata script construction (kaspa-wasm ZkScriptBuilder).


1. Groth16 Pairing Check (verify-math)​

The path is a fixture directory with manifest.json, proof.json, public-inputs.json and verification-key.json (see fixtures/toccata-v2/zk/groth16-multiplier):

hardkas zk proof verify-math fixtures/toccata-v2/zk/groth16-multiplier --json

That fixture is a toy with a known trapdoor: by default it is refused (ZK_GROTH16_MATH_REJECTED, ZK_VERIFICATION_KEY_WEAK_TRAPDOOR). --allow-weak-vk runs the pairing anyway, for testing the verifier only; a proof against such a key proves nothing.

Anchor the verification key​

ZK_GROTH16_MATH_VERIFIED is returned only when the key is anchored: pinned by you with --expect-vk-hash (the key's summary.verificationKeyFingerprint, or its legacy digest, obtained from a source you trust) or pinned in code (PINNED_GROTH16_VERIFICATION_KEYS). A passing pairing against any other key is ZK_GROTH16_MATH_VALID_UNANCHORED_VK with ok: false and exit 1: the proof is consistent with that key, whose maker may know its trapdoor.

hardkas zk proof verify-math ./my-fixture --expect-vk-hash <64-hex fingerprint> --timeout 10000 --json

Non-canonical encodings, off-curve points and G2 points outside the subgroup are rejected before snarkjs. The weak-key check recognises an uncontributed setup (and keys pinned as toys); it detects accidents and is not a security boundary. The fixture-coherence binding is self-attested (FIXTURE_COHERENCE_SELF_ATTESTED); --math-only skips it and labels the result MATH_ONLY.

Using the TypeScript SDK (@hardkas/sdk)​

import { verifyZkProofMath, inspectZkProof } from '@hardkas/sdk';

// 1. Inspect proof metadata and canonical digests
const inspection = await inspectZkProof('./fixtures/toccata-v2/zk/groth16-multiplier', process.cwd());

// 2. Pairing check, bound to the fixture's (self-attested) content hashes, against an anchored key
const verification = await verifyZkProofMath('./my-fixture', process.cwd(), {
timeoutMs: 10_000,
expectedVerificationKeyHash: '<64-hex fingerprint from a trusted source>',
mathOnly: false,
allowWeakVerificationKey: false,
});

if (verification.status !== 'ZK_GROTH16_MATH_VERIFIED') {
throw new Error(`ZK verification failed: ${verification.status} ${JSON.stringify(verification.issues)}`);
}

2. Verifying a RISC Zero Groth16 Receipt (verify-receipt)​

hardkas zk toccata verify-receipt \
--image-id 75641a540ee2ad9ee5902bcdcdb8b55c0bef4a28287309b858f97b1356c6c2e0 \
--journal-hash 5df6e0e2761359d30a8275058e299fcc0381534545f55cf43e41983f5d4c9456 \
--receipt fixtures/toccata-v2/zk/r0-groth16-official/receipt.hex \
--json

The receipt is checked with snarkjs against the pinned official RISC Zero verifying key, control root and BN254 control id, for the claim of (imageId, journalHash). SDK: verifyR0Groth16ReceiptLocal({ imageId, journalHash, receiptHex, timeoutMs }) returns status: "ZK_R0_GROTH16_RECEIPT_VERIFIED" on success. Only that result sets a ZK fact's verifiedOffChain. The vector above is the public one from kaspa-python-sdk: anyone can spend a lock built for it, so HardKAS returns only its simnet address.


3. Inspecting the Toccata OpZkPrecompile Rules​

hardkas zk toccata rules --json

Or programmatically:

import { getToccataPrecompileRules } from '@hardkas/sdk';

const rules = getToccataPrecompileRules();
console.log(rules.opcode); // "0xa6" (OpZkPrecompile)
console.log(rules.tag); // "0x20" (Groth16)
console.log(rules.groth16PrecompileCostGrams); // 140000 (= 14,000,000 script units)
console.log(rules.groth16VkElementCostScriptUnits); // 250000 per verifying-key element
console.log(rules.minimumR0Groth16ComputeBudget); // 1550 (RISC Zero wrapper, 6 key elements)
console.log(rules.recommendedComputeBudget); // 1600
console.log(rules.authorizationModel); // "IMAGE_ID_ONLY" (the default lock)

A compute budget below the minimum makes the node reject the spend; one whose compute mass exceeds the 500,000 block limit is refused by HardKAS.


4. Building Toccata L1 ZK Scripts (build-scripts)​

build-scripts calls kaspa-wasm's ZkScriptBuilder and returns the P2SH redeem script, the signature script and the simnet address. The receipt's claim is cross-checked against (imageId, journalHash) (receiptClaimCrossCheck: "MATCH"); a mismatch is refused. Choose the lock's authorization model with --mode.

proof-only (default): IMAGE_ID_ONLY​

hardkas zk toccata build-scripts \
--image-id 75641a540ee2ad9ee5902bcdcdb8b55c0bef4a28287309b858f97b1356c6c2e0 \
--journal-hash 5df6e0e2761359d30a8275058e299fcc0381534545f55cf43e41983f5d4c9456 \
--receipt fixtures/toccata-v2/zk/r0-groth16-official/receipt.hex \
--json

The lock binds the image id only: anyone holding a valid receipt of that program spends every UTXO at the address, to outputs of their choosing, on any network; a spend seen in the mempool can be replayed or front-run. Every result carries the warning ZK_LOCK_BINDS_IMAGE_ID_ONLY. A testnet-10 address needs --address-network testnet-10 plus --ack-image-id-only-lock, and is never returned for a program whose receipts are published (PUBLIC_R0_TEST_VECTORS: the official vector and HardKAS's own fixture receipt, matched on the image id): such a lock would be anyone-can-spend (ZK_PUBLIC_VECTOR_PUBLIC_NETWORK_REFUSED). A proof-and-output-bound lock of such a program is built, with the warning ZK_PUBLIC_PROGRAM_PAYOUT_TRIGGERABLE: its funds can only reach the bound outputs, but anyone can trigger that payout. Mainnet, in any spelling (or a bound payout or change address of mainnet), is refused while mainnet is locked down: MAINNET_SIGNING_DISABLED, with no address and no signature script, because the signature script is the authorization of the spend.

proof-and-output-bound: IMAGE_ID_AND_OUTPUTS​

hardkas zk toccata build-scripts \
--image-id <64-hex image id> --journal-hash <64-hex journal hash> --receipt ./receipt.hex \
--mode proof-and-output-bound \
--payout-address <kaspasim:...> --payout-amount 100000000 \
--max-fee 50000000 \
--json

After the Groth16 verifier, the redeem script checks by output introspection:

  • the output count, and the payout's script public key (as OpTxOutputSpk pushes it: version, then script) and amount; the same for the change output when --change-address/--change-amount are given;
  • exactly one input (OpTxInputCount), so several UTXOs of the lock cannot be merged into one spend and burnt as fee;
  • an input of at most the bound outputs plus maxFeeSompi (OpTxInputAmount); a larger deposit stays locked.

Anyone with a valid receipt can trigger the spend, but only to those outputs; whatever the UTXO holds beyond them is the fee. Fund the lock with the returned requiredFundingSompi (bound outputs plus the recommended fee); maxInputSompi is the largest UTXO the script accepts. Results carry ZK_LOCK_BINDS_IMAGE_ID_AND_OUTPUTS and consensusEnforced: true (only for a successful bound build).

What neither mode binds:

  • The spent outpoint. A redeem script cannot name it: the funding transaction's id commits to its outputs, this P2SH among them. HardKAS refuses such a binding (ZK_UTXO_BINDING_UNSATISFIABLE).
  • The journal. The unlocking script supplies the journal hash and nothing checks it on-chain. createZkOutputBindingJournal (the HKZ1 layout: script public key digest, amount, outpoint digest, nonce) is an off-chain convention; its fields mean something only if the guest program enforces them.

Programmatic Script Construction in TypeScript​

import { buildR0Groth16Scripts } from '@hardkas/sdk';

const scripts = buildR0Groth16Scripts({
imageId: '<64-hex image id>',
journalHash: '<64-hex journal hash>',
receiptHex: '<r0-groth16-receipt-hex>',
bindingPolicy: {
mode: 'proof-and-output-bound',
payout: { address: '<kaspasim:...>', amountSompi: 100_000_000n },
maxFeeSompi: 50_000_000n,
},
});

if (scripts.ok) {
console.log('Authorization:', scripts.authorizationModel); // "IMAGE_ID_AND_OUTPUTS"
console.log('Redeem script:', scripts.redeemScript);
console.log('P2SH script public key:', scripts.p2shScriptPublicKey.script);
console.log('Signature script:', scripts.sigScript);
console.log('P2SH address (simnet):', scripts.p2shAddresses.simnet);
console.log('Fund with (sompi):', scripts.requiredFundingSompi);
} else {
console.error(scripts.issues);
}

buildR0Groth16Transaction({ scripts, utxo, destinationAddress, networkId }) builds the version-1 spend (compute budget 1600 by default, fee capped by feeOptions.maxFeeSompi). A ZK spend needs no signature: the signature script is its authorization, so the built transaction is complete. For that reason buildR0Groth16Transaction and buildR0Groth16Plan refuse mainnet (any spelling) with MAINNET_SIGNING_DISABLED, before anything is read (MAINNET TOTAL LOCKDOWN).

Checking a lock before funding it (verify-scripts)​

hardkas zk toccata verify-scripts --redeem-script <hex> --sig-script <hex> \
--image-id <64-hex image id> --expected-mode proof-and-output-bound \
--expected-payout-address <kaspasim:...> --expected-payout-amount 100000000 \
--expected-change-address <kaspasim:...> --expected-change-amount 15000000 \
--json

verify-scripts does not trust what the script appears to contain:

  • Pinned verifier. The verifying key handed to OpZkPrecompile must be the pinned RISC Zero key (verifyingKeyPinned), and the script must push the pinned control root and BN254 control id (controlRootPinned, controlIdPinned). A lock over another key is refused (ZK_VERIFYING_KEY_NOT_PINNED) even when it pushes the right image id: whoever knows that key's trapdoor forges receipts.
  • Byte-exact reconstruction. The image id, and in output-bound mode the payout, the change and the input limit, are read back from the script, which is then rebuilt with the same builders as build-scripts and compared byte for byte (redeemScriptCanonical). Only an identical output-bound lock gets consensusEnforced: true and the enforces* / bound* fields (boundPayoutSpk, boundChangeSpk, boundMaxInputSompi, …). Anything else is ZK_REDEEM_SCRIPT_NOT_CANONICAL, and nothing is inferred from the presence of introspection opcodes.
  • Expected outputs are compared with what the lock binds (ZK_BOUND_PAYOUT_*, ZK_BOUND_CHANGE_*); asked of a lock that binds none, they are ZK_EXPECTED_BINDING_NOT_ENFORCED.

5. Verifying a Complete ZK Corpus in CI​

To check every positive and adversarial ZK fixture of a corpus:

hardkas zk corpus verify fixtures/toccata-v2/zk --json

6. What a node has decided about these locks​

HardKAS builds locks and spends, and hardkas zk toccata spend sends a spend through HardKAS's own send (recorded, one submission per txId); the verdict is always the node's. Two receipts are in the repository: the public kaspa-python-sdk vector (fixtures/toccata-v2/zk/r0-groth16-official) and one HardKAS made itself (fixtures/toccata-v2/zk/r0-groth16-hardkas, another program and journal).

  • Local node (rusty-kaspad v2.1.0 in Docker, the repository's node suites, also run in CI on Linux): valid spends accepted, proof-only and proof-and-output-bound, for both receipts; rejected: an altered proof or journal, a truncated proof, a v0 transaction, a compute budget or a fee too low, a wrong payout script or amount, two inputs, an input above the bound.
  • Testnet-10 (2026-11-13, test funds, that day's release candidate): two proof-and-output-bound locks over HardKAS's own receipt, funded and spent to their bound payout; the node rejected the payout one sompi short, another payee, a flipped proof byte, a valid proof of another program and the proof with another journal hash.

Two properties to keep in mind:

  • Groth16 is malleable. (A, B, C) → (r⁻¹·A, r·B, C) is another valid proof of the same statement, so a ZK fact's proofSha256 records the bytes it was built from and never identifies a proof or a spend. Identify a spend by its txid and outpoint; note that a Kaspa txid does not cover the signature script, so every spend of one outpoint to the same outputs has the same txid whatever proof it carries.
  • The verifier is pinned end to end. Besides the key, control root and control id, a receipt's verifier parameters must be the pinned RISC Zero verifier's (ZK_RECEIPT_VERIFIER_PARAMETERS_MISMATCH otherwise): a receipt made for another verifier never unlocks the lock.