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
OpTxOutputSpkpushes it: version, then script) and amount; the same for the change output when--change-address/--change-amountare 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(theHKZ1layout: 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
OpZkPrecompilemust 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-scriptsand compared byte for byte (redeemScriptCanonical). Only an identical output-bound lock getsconsensusEnforced: trueand theenforces*/bound*fields (boundPayoutSpk,boundChangeSpk,boundMaxInputSompi, …). Anything else isZK_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 areZK_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
proofSha256records 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_MISMATCHotherwise): a receipt made for another verifier never unlocks the lock.