Ton Zk Contract Integration

TON ZK Contract Integration

Overview

A verifier proves one relation under one VK; the application binds it to authenticated TON context, current state, and one authorized transition.

Operating Rules

• Use $groth16-systems for general application binding; this skill adds TON execution and encodings.
• The bundled validator requires Python 3.10+; builds and tests use the target repository's pinned TON toolchain.
• Separate verifier validity, authorization, and state transition.
• Validate the example and schema. The helper separates consistency and artifact identity; it does not verify the circuit or implementation.
• Bind security values through public inputs or authenticated message/state sources; body-supplied addresses are not authentication.
• Bind runtime global_id, workchain, current address, action, circuit/VK, protocol, and version.
• Persist and atomically consume a nullifier, nonce, seqno, or one-shot marker.
• Reject wrong proof widths, trailing bits/bytes, and refs before TVM BLS operations.
• A getter is read-only; reverify and enforce policy in the state-changing transaction.
• Prefer value-carrying internal messages; never accept an external message unconditionally.

Workflow

1. Record proof fields, exact layout, public-input representation, message kind/opcode, wrapper, and value rule.
2. Add TON profiles and authenticated sources. Define nonce/seqno bits and range.
3. Bind runtime global_id, workchain, current address, opcode, and TON state.
4. Design storage for replay state, roots, VK/version authority, pending operations, and reserves.
5. For internal messages: parse, authenticate, range-check, verify, check semantics/state, then atomically consume the application nullifier and transition.
6. For signed external messages, authenticate and check envelope replay before ACCEPT; persist and COMMIT it before expensive ZK work. Consume the application nullifier only with success.
7. Define acceptance, payer/value, bounce, duplicates, callbacks, reserves, and in-flight behavior.
8. Decode golden wrapper BoCs and compare the complete graph and representation hash with the contract layout.
9. Run:

python3 <skills-root>/ton-zk-contract-integration/scripts/validate_proof_context.py \
  ./proof-context.json --project-root .

Then use $ton-zk-testing for getter, message, state, replay, acceptance, balance, and bounce assertions.

References: architecture, public inputs, executable TON encoding vectors, encoding, replay/domain, and external messages.

Quick Reference

Common Mistakes

• Checking proof validity but not application semantics.
• Relying on wrapper-only queryId for replay protection.
• Reducing an external value modulo the field before business interpretation.
• Trusting an address supplied only in the body.
• Splitting verification and execution without robust correlation state.
• Letting BLS parsing ignore a tail used elsewhere.
• Accepting an external message before cheap authentication/replay checks.
• Treating get-method output as consensus authorization.

Completion Gate

Report manifest, input map, authenticated sources, runtime domain, replay key, message layout, external acceptance/payer, getter role, atomic transition, bounce/value policy, wrapper/BoC fixture, and end-to-end tests. Every application input needs one unambiguous check.