feat(contract-dev): edit zero knowledge proof guide to fit style guide#2128
Draft
feat(contract-dev): edit zero knowledge proof guide to fit style guide#2128
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 26 minutes and 57 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Collaborator
Author
|
/review |
This comment has been minimized.
This comment has been minimized.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Collaborator
Author
|
/review |
Collaborator
Author
|
/review |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (3)
contract-dev/techniques/zero-knowledge.mdx (3)
243-247:⚠️ Potential issue | 🟡 MinorUnresolved self-reference: "This tutorial follows the path".
Line 243 still uses "This tutorial follows the path…", which is the reader/document-referential phrasing flagged previously. Line 245's "The idea is always the same: generate
proof.jsonandverification_key.jsonin the snarkjs format…" also partially restates the preceding sentence, which the style guide discourages.Proposed rewrite
-This tutorial follows the path: Circom → snarkjs → export-ton-verifier → TON. - -The same workflow applies to other stacks, the key requirement is to obtain a proof and a verification key in the snarkjs format. The idea is always the same: generate `proof.json` and `verification_key.json` in the snarkjs format, then perform the verification in TON with the export-ton-verifier. - -[The zk-ton-examples repository](https://github.com/zk-examples/zk-ton-examples/) contains templates for Noname, gnark, and Arkworks. It is possible to generate proofs in any of these stacks, then convert them to the snarkjs format and verify them both locally and on-chain. +The workflow above uses the path `Circom` → `snarkjs` → `export-ton-verifier` → TON. Any stack that can emit a `snarkjs`-format `proof.json` and `verification_key.json` plugs into the same TON-side verification step. + +The [zk-ton-examples repository](https://github.com/zk-examples/zk-ton-examples/) provides templates for `Noname`, `gnark`, and `Arkworks`, each converting its native output into the `snarkjs` format before on-chain verification.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@contract-dev/techniques/zero-knowledge.mdx` around lines 243 - 247, Replace the self-referential sentence "This tutorial follows the path: Circom → snarkjs → export-ton-verifier → TON." with a declarative, reader-focused phrase (e.g., "The workflow is: Circom → snarkjs → export-ton-verifier → TON.") and remove the redundant clause that restates the same idea in "The idea is always the same: generate `proof.json` and `verification_key.json` in the snarkjs format…" by merging the two into a single concise sentence that explains the required outputs (`proof.json` and `verification_key.json` in snarkjs format) and their role in verifying proofs on TON; ensure the phrases "This tutorial follows the path" and "generate `proof.json` and `verification_key.json`" are updated accordingly to eliminate self-reference and repetition.
369-378:⚠️ Potential issue | 🟡 MinorUnresolved:
## Useful Linksheading casing and non-descriptive link labels.Two issues here:
## Useful Linksis title-case ("Links" capitalized), which violates the sentence-case heading rule enforced elsewhere in this diff (e.g., "Initialize a project", "Export the verifier contract", "Test and verify the proof").- Link labels remain structural/generic ("The snarkjs repository", "The Arkworks homepage", "The gnark repository", etc.) — flagged previously. Scanability improves when link text describes the resource's content, not the page type.
Proposed fix
-## Useful Links +## Useful links -- [The zk-ton-examples repository](https://github.com/zk-examples/zk-ton-examples/) contains additional examples of zk-SNARK circuits and their integration with TON. -- [The export-ton-verifier repository](https://github.com/mysteryon88/export-ton-verifier) is a library that generates TON-compatible verifier contracts from snarkjs verification keys. -- [The snarkjs repository](https://github.com/iden3/snarkjs) is a JavaScript library for generating and verifying zk-SNARK proofs, as well as performing trusted setup ceremonies. -- [The ark-snarkjs repository](https://github.com/mysteryon88/ark-snarkjs) is a utility that converts Arkworks proofs and verification keys into a format compatible with snarkjs. -- [The gnark-to-snarkjs repository](https://github.com/mysteryon88/gnark-to-snarkjs) is a utility that converts gnark proofs and verification keys into a format compatible with snarkjs. -- [The Noname repository](https://github.com/zksecurity/noname) is a high-level language for writing zk-SNARK circuits, which can be compiled to a format compatible with snarkjs. -- [The gnark repository](https://github.com/Consensys/gnark) is a Go library for writing zk-SNARK circuits and generating proofs. -- [The Arkworks homepage](https://arkworks.rs/) is a Rust ecosystem for zk-SNARKs, providing libraries for writing circuits, generating proofs, and performing trusted setup ceremonies. +- [`zk-ton-examples`](https://github.com/zk-examples/zk-ton-examples/) — sample zk-SNARK circuits and TON integrations. +- [`export-ton-verifier`](https://github.com/mysteryon88/export-ton-verifier) — generates TON verifier contracts from `snarkjs` verification keys. +- [`snarkjs`](https://github.com/iden3/snarkjs) — JavaScript library for generating, verifying, and running trusted setup for zk-SNARKs. +- [`ark-snarkjs`](https://github.com/mysteryon88/ark-snarkjs) — converts `Arkworks` proofs and verification keys to the `snarkjs` format. +- [`gnark-to-snarkjs`](https://github.com/mysteryon88/gnark-to-snarkjs) — converts `gnark` proofs and verification keys to the `snarkjs` format. +- [`Noname`](https://github.com/zksecurity/noname) — high-level language for zk-SNARK circuits, compiles to a `snarkjs`-compatible format. +- [`gnark`](https://github.com/Consensys/gnark) — Go library for zk-SNARK circuit authoring and proof generation. +- [Arkworks](https://arkworks.rs/) — Rust ecosystem for zk-SNARK circuits, proofs, and trusted setup.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@contract-dev/techniques/zero-knowledge.mdx` around lines 369 - 378, Change the heading "## Useful Links" to sentence case ("## Useful links") and replace generic link labels like "The snarkjs repository", "The Arkworks homepage", "The gnark repository" etc. with descriptive, content-focused text that describes what each resource provides (e.g., "snarkjs: JS zk‑SNARK tooling and trusted setup", "Arkworks: Rust libraries for zk‑SNARK circuits", "gnark: Go library for zk‑SNARK circuit development"), keeping the original URLs and list order unchanged; update the MDX list items that match the pattern "- [The ... repository/homepage]" accordingly so link text improves scanability.
8-14:⚠️ Potential issue | 🟡 MinorUnresolved: self-referential opener and missing code font on tool/library names.
Lines 8 and 10–13 still contain:
- The self-referential phrase "This guide is also applicable…" flagged previously.
- Tool/library identifiers (
Circom,snarkjs,Noname,export-ton-verifier,zk-SNARK,Groth16) rendered as plain prose rather than code font, which the style guide requires for code identifiers and tool names.Additionally, line 8 chains three bracketed links in a row ("Circom", "ZK-proof", "zk-SNARK", "Groth16") which crowds the opening sentence and obscures the actual task.
Proposed rewrite
-Create, compile, and test a simple [Circom](https://docs.circom.io/) scheme and verify a [ZK-proof](https://en.wikipedia.org/wiki/Zero-knowledge_proof) using the [zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof) [Groth16](https://eprint.iacr.org/2016/260.pdf) protocol. +Create, compile, and test a simple [`Circom`](https://docs.circom.io/) circuit and verify a [zero-knowledge proof](https://en.wikipedia.org/wiki/Zero-knowledge_proof) using the [`Groth16`](https://eprint.iacr.org/2016/260.pdf) [zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof) protocol. <Aside type="tip"> - This guide is also applicable to circuits written in the [Noname](https://github.com/zksecurity/noname) language, since the [export-ton-verifier](https://github.com/mysteryon88/export-ton-verifier) library integrates with snarkjs, which in turn integrates with the Noname language. + The same workflow applies to circuits written in [`Noname`](https://github.com/zksecurity/noname), because [`export-ton-verifier`](https://github.com/mysteryon88/export-ton-verifier) integrates with `snarkjs`, which in turn supports `Noname`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@contract-dev/techniques/zero-knowledge.mdx` around lines 8 - 14, Rewrite the opening sentence to focus on the task by simplifying the bracketed links (e.g., "Create, compile, and test a simple Circom circuit and verify a ZK-proof using the Groth16 zk-SNARK protocol.") remove the self-referential phrase "This guide is also applicable…" from the Aside, and ensure all tool/library identifiers (Circom, snarkjs, Noname, export-ton-verifier, zk-SNARK, Groth16) are rendered in code font per style guide; keep the explanatory note about Noname/export-ton-verifier/snarkjs in the Aside but rephrase it as a short supporting sentence and move any extra links there to avoid crowding the opener.
🧹 Nitpick comments (1)
contract-dev/techniques/zero-knowledge.mdx (1)
299-299: Redundanttitle="Rust"/title="Go"on language-tagged fences.Lines 299 and 346 use
```rust title="Rust"and```go title="Go". Since the language already identifies the fence, atitleequal to the language name just repeats the label on the rendered tab. Either drop thetitleor use it to indicate the file path (e.g.,title="src/main.rs",title="main.go") the way earlier bash/ts blocks do (e.g.,title="./tests/ZkSimple.spec.ts").Proposed fix
- ```rust title="Rust" + ```rust title="src/main.rs" ... - ```go title="Go" + ```go title="main.go"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@contract-dev/techniques/zero-knowledge.mdx` at line 299, Remove the redundant title attribute that duplicates the language on the code fences (e.g., replace ```rust title="Rust" and ```go title="Go") or replace the title with a meaningful file path instead (e.g., use title="src/main.rs" for the Rust block and title="main.go" for the Go block); update the fenced code blocks referenced in the diff (the Rust and Go triple-backtick blocks) accordingly so the rendered tab shows either just the language or a useful file path rather than a duplicate label.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@contract-dev/techniques/zero-knowledge.mdx`:
- Around line 326-333: The Step component titled "Create a new project" has
content that only links to external repos and lacks the Go project scaffolding
commands; update the Step (title "Create a new project") so its Go subsection
includes the actual scaffolding commands (e.g., initialize module with go mod
init and any required directory/file creation) to match the Rust (`cargo init`)
and TS examples, or if you prefer keeping only template links, rename the Step
title to something like "Use example repositories" to accurately reflect the
contents; modify the Step block accordingly so readers see either the concrete
go mod init instructions or a retitled header that matches the current content.
- Around line 86-89: Remove the redundant directive "Run inside the
`circuits/Multiplier` directory." that appears immediately before the circom
command block (the sentence referencing the `circuits/Multiplier` directory)
because Step 1 already instructs `cd circuits/Multiplier`; keep the circom
command block (`circom Multiplier.circom --r1cs --wasm --sym --prime bls12381`)
as-is and ensure surrounding context still makes clear the command should be
executed from that directory by relying on the earlier Step 1 instruction.
- Around line 289-292: Split the combined step title "Compile, generate proof,
perform trusted setup" into separate, single-action step headings (e.g.,
"Compile", "Generate proof", "Perform trusted setup") by updating the Step/title
value(s), and update the body links so each step points to the correct anchor:
keep the compile/generate proof link targeting `#create-the-circom-circuit` and
add or change the trusted-setup link to point to `#initialize-trusted-setup`
(ensure the Step component or heading that contained the original title is
replaced with three distinct Step entries or headings and that their link
targets are corrected).
---
Duplicate comments:
In `@contract-dev/techniques/zero-knowledge.mdx`:
- Around line 243-247: Replace the self-referential sentence "This tutorial
follows the path: Circom → snarkjs → export-ton-verifier → TON." with a
declarative, reader-focused phrase (e.g., "The workflow is: Circom → snarkjs →
export-ton-verifier → TON.") and remove the redundant clause that restates the
same idea in "The idea is always the same: generate `proof.json` and
`verification_key.json` in the snarkjs format…" by merging the two into a single
concise sentence that explains the required outputs (`proof.json` and
`verification_key.json` in snarkjs format) and their role in verifying proofs on
TON; ensure the phrases "This tutorial follows the path" and "generate
`proof.json` and `verification_key.json`" are updated accordingly to eliminate
self-reference and repetition.
- Around line 369-378: Change the heading "## Useful Links" to sentence case
("## Useful links") and replace generic link labels like "The snarkjs
repository", "The Arkworks homepage", "The gnark repository" etc. with
descriptive, content-focused text that describes what each resource provides
(e.g., "snarkjs: JS zk‑SNARK tooling and trusted setup", "Arkworks: Rust
libraries for zk‑SNARK circuits", "gnark: Go library for zk‑SNARK circuit
development"), keeping the original URLs and list order unchanged; update the
MDX list items that match the pattern "- [The ... repository/homepage]"
accordingly so link text improves scanability.
- Around line 8-14: Rewrite the opening sentence to focus on the task by
simplifying the bracketed links (e.g., "Create, compile, and test a simple
Circom circuit and verify a ZK-proof using the Groth16 zk-SNARK protocol.")
remove the self-referential phrase "This guide is also applicable…" from the
Aside, and ensure all tool/library identifiers (Circom, snarkjs, Noname,
export-ton-verifier, zk-SNARK, Groth16) are rendered in code font per style
guide; keep the explanatory note about Noname/export-ton-verifier/snarkjs in the
Aside but rephrase it as a short supporting sentence and move any extra links
there to avoid crowding the opener.
---
Nitpick comments:
In `@contract-dev/techniques/zero-knowledge.mdx`:
- Line 299: Remove the redundant title attribute that duplicates the language on
the code fences (e.g., replace ```rust title="Rust" and ```go title="Go") or
replace the title with a meaningful file path instead (e.g., use
title="src/main.rs" for the Rust block and title="main.go" for the Go block);
update the fenced code blocks referenced in the diff (the Rust and Go
triple-backtick blocks) accordingly so the rendered tab shows either just the
language or a useful file path rather than a duplicate label.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c4949722-c9bd-48ad-9020-6f80659a2be5
📒 Files selected for processing (2)
contract-dev/techniques/zero-knowledge.mdxresources/dictionaries/custom.txt
There was a problem hiding this comment.
Pull request overview
Updates the contract-dev zero-knowledge proofs guide to conform to the docs style guide (notably using structured <Steps>/<Step> blocks and standardized <Aside> callouts), improving readability and navigation for contract developers.
Changes:
- Restructured the Circom → snarkjs → export-ton-verifier workflow into step-based sections.
- Refined trusted setup, verifier export, and testing guidance with updated snippets and callouts.
- Extended the custom dictionary to include common ZK-related terms (e.g., snarkjs, gnark).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| resources/dictionaries/custom.txt | Adds ZK ecosystem terms to avoid spellcheck false positives. |
| contract-dev/techniques/zero-knowledge.mdx | Rewrites the ZK proof guide to match the style guide using Steps/Asides and refreshed examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This comment has been minimized.
This comment has been minimized.
Collaborator
Author
|
@aigerimu I couldn't get the spell checker working with "zk". Any idea how to solve this? |
Collaborator
@kay-is let's remove |
novusnota
reviewed
Apr 24, 2026
| <Step | ||
| title="Create a new project" | ||
| > | ||
| ´´´bash |
Collaborator
There was a problem hiding this comment.
There should be triple backticks ```, not forward ticks ´. Plus, the end of this code block should also have backticks, and the 4-backtick wrapping lower must be removed (before and after Aside). Afterwards, run the formatting command again: npm run fmt:some -- contract-dev/techniques/zero-knowledge.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2119.
Summary by CodeRabbit