TON ZK Verifier Generation
Overview
Turn a locally verified artifact into reproducible TON contract output. Diagnosis precedes rendering: format, protocol, BLS12-381 curve, public-input count, target template, and TVM limits must be known.
Operating Rules
- Inspect the installed package and lockfile; do not silently change generator versions.
- Use the locally installed or explicitly approved
export-ton-verifier and its supported Node.js LTS; inspect project engines and installed help.
- Run
export-ton-verifier doctor for the exact artifact and language.
- Fail closed on unsupported curve, format, protocol, template, point/subgroup validation, or limits.
- Prefer Tolk; use
--func or --tact only for an explicitly supported target.
- Treat the generated verifier and wrapper as reproducible output. Preserve SPDX/license headers; see licensing.md.
- Command snippets assume a repository-pinned local package; do not let
npx fetch or replace export-ton-verifier without explicit approval.
Workflow
- Identify
.zkey, snarkjs VK JSON, native Gnark JSON/binary, or Arkworks bundle/VK JSON.
- Record local CLI version/help and run
doctor.
- Confirm protocol, BLS12-381, source format, public-input count, template, and all checks.
- Render to an intentional path with a stable contract name.
- Generate/copy the matching TypeScript wrapper.
- Use library helpers or
proof-to-message for a fixture; do not invent parallel serialization.
- Compile immediately and test valid, malformed/tampered, one-byte-short, valid-prefix-plus-tail, and extra-ref cases at the integration parser boundary.
- Record input/output hashes, command, generator version, target, and VK fingerprint.
Read CLI, formats, language targets, and experimental PLONK.
Quick Reference
npm ls export-ton-verifier --depth=0
npx --no-install export-ton-verifier --help
npx --no-install export-ton-verifier doctor ./circuits/verification_key.json --tolk
npx --no-install export-ton-verifier ./circuits/verification_key.json ./contracts/verifier.tolk --contract-name ApplicationVerifier
npx --no-install export-ton-verifier import-wrapper ./wrappers/Verifier_tolk.ts --groth16 --force
npx --no-install export-ton-verifier proof-to-message ./circuits/proof.json ./circuits/public.json --groth16 --tolk
| Target |
Policy |
| Tolk Groth16 |
Preferred |
| FunC Groth16 |
Supported for existing/compatibility projects |
| Tact Groth16 |
Use only when installed template supports it |
| Tolk/FunC PLONK |
Experimental |
| Tact PLONK |
Block without current upstream proof of support |
Common Mistakes
- Rendering before
doctor or feeding BN254/bn128 to BLS12-381 templates.
- Mixing wrapper, protocol, language, VK, or circuit versions.
- Hand-editing pairing, transcript, scalar, point, or VK code.
- Assuming a named Tolk contract keeps an old getter name.
- Treating
proof-to-message as authorization or replay protection.
- Assuming the generated BLS opcode rejects oversized slices instead of enforcing exact 48/96-byte component lengths in the receiver.
Completion Gate
Provide diagnosis, generator version, input format/hash, protocol, BLS12-381 evidence, public-input count, target, commands, output hashes, license status, build result, and valid/invalid plus exact-length parser results. A generated verifier is incomplete until reproducible and tested.
1---2name: ton-zk-verifier-generation3description: Use when inspecting a .zkey, verification_key.json, Gnark JSON/binary, or Arkworks bundle and generating TON Groth16 or experimental PLONK verifiers and TypeScript wrappers with export-ton-verifier for Tolk, FunC, or Tact.4license: Apache-2.05---67# TON ZK Verifier Generation89## Overview1011Turn a locally verified artifact into reproducible TON contract output. Diagnosis precedes rendering: format, protocol, BLS12-381 curve, public-input count, target template, and TVM limits must be known.1213## Operating Rules1415- Inspect the installed package and lockfile; do not silently change generator versions.16- Use the locally installed or explicitly approved `export-ton-verifier` and its supported Node.js LTS; inspect project engines and installed help.17- Run `export-ton-verifier doctor` for the exact artifact and language.18- Fail closed on unsupported curve, format, protocol, template, point/subgroup validation, or limits.19- Prefer Tolk; use `--func` or `--tact` only for an explicitly supported target.20- Treat the generated verifier and wrapper as reproducible output. Preserve SPDX/license headers; see [licensing.md](references/licensing.md).21- Command snippets assume a repository-pinned local package; do not let `npx` fetch or replace `export-ton-verifier` without explicit approval.2223## Workflow24251. Identify `.zkey`, snarkjs VK JSON, native Gnark JSON/binary, or Arkworks bundle/VK JSON.262. Record local CLI version/help and run `doctor`.273. Confirm protocol, BLS12-381, source format, public-input count, template, and all checks.284. Render to an intentional path with a stable contract name.295. Generate/copy the matching TypeScript wrapper.306. Use library helpers or `proof-to-message` for a fixture; do not invent parallel serialization.317. Compile immediately and test valid, malformed/tampered, one-byte-short, valid-prefix-plus-tail, and extra-ref cases at the integration parser boundary.328. Record input/output hashes, command, generator version, target, and VK fingerprint.3334Read [CLI](references/cli.md), [formats](references/formats.md), [language targets](references/language-targets.md), and [experimental PLONK](references/plonk.md).3536## Quick Reference3738```bash39npm ls export-ton-verifier --depth=040npx --no-install export-ton-verifier --help41npx --no-install export-ton-verifier doctor ./circuits/verification_key.json --tolk42npx --no-install export-ton-verifier ./circuits/verification_key.json ./contracts/verifier.tolk --contract-name ApplicationVerifier43npx --no-install export-ton-verifier import-wrapper ./wrappers/Verifier_tolk.ts --groth16 --force44npx --no-install export-ton-verifier proof-to-message ./circuits/proof.json ./circuits/public.json --groth16 --tolk45```4647| Target | Policy |48|---|---|49| Tolk Groth16 | Preferred |50| FunC Groth16 | Supported for existing/compatibility projects |51| Tact Groth16 | Use only when installed template supports it |52| Tolk/FunC PLONK | Experimental |53| Tact PLONK | Block without current upstream proof of support |5455## Common Mistakes5657- Rendering before `doctor` or feeding BN254/bn128 to BLS12-381 templates.58- Mixing wrapper, protocol, language, VK, or circuit versions.59- Hand-editing pairing, transcript, scalar, point, or VK code.60- Assuming a named Tolk contract keeps an old getter name.61- Treating `proof-to-message` as authorization or replay protection.62- Assuming the generated BLS opcode rejects oversized slices instead of enforcing exact 48/96-byte component lengths in the receiver.6364## Completion Gate6566Provide diagnosis, generator version, input format/hash, protocol, BLS12-381 evidence, public-input count, target, commands, output hashes, license status, build result, and valid/invalid plus exact-length parser results. A generated verifier is incomplete until reproducible and tested.
mysteryon88