zk coprocessor docs update#360
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughThe documentation for the Valence ZK system has been extensively restructured and expanded. Several new files were introduced, providing in-depth overviews, developer guides, architectural explanations, and technical references for the ZK Coprocessor, state encoding, sparse Merkle trees, guest execution environments, and on-chain integration. Outdated overview and sparse Merkle tree documents were removed, and the documentation summary and related component references were updated to reflect the new organization. Changes
Sequence Diagram(s)sequenceDiagram
participant Developer
participant Coprocessor
participant GuestProgram
participant ZK Circuit
participant AuthorizationContract
participant VerificationGateway
participant ProcessorContract
Developer->>Coprocessor: Deploy Guest Program (Controller + Circuit)
Coprocessor->>AuthorizationContract: Register Verification Key
Developer->>Coprocessor: Request Proof (with Inputs)
Coprocessor->>GuestProgram: Run Controller (Process Inputs)
GuestProgram->>ZK Circuit: Generate Witness & Proof
ZK Circuit-->>GuestProgram: Output Proof & Public Inputs
GuestProgram-->>Coprocessor: Store Proof, Outputs
Developer->>Coprocessor: Retrieve Proof & Public Inputs
Developer->>AuthorizationContract: Submit Proof & ZKMessage
AuthorizationContract->>VerificationGateway: Verify Proof
VerificationGateway-->>AuthorizationContract: Verification Result
AuthorizationContract->>ProcessorContract: Dispatch Verified Message
ProcessorContract-->>Blockchain: Execute State Change
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (6)
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (14)
docs/src/zk/00_introduction.md (2)
3-3: Remove erroneous article before "Zero-Knowledge proofs"
Line 3 reads "provides a Zero-Knowledge proofs…", which mixes the singular article with a plural noun. Remove the leading "a":- Valence Protocol provides a Zero-Knowledge proofs and a dedicated ZK Coprocessor system… + Valence Protocol provides Zero-Knowledge proofs and a dedicated ZK Coprocessor system…
14-14: Fix typo in encoder naming
The term "Merklelized Encoder" has an extra 'l'. Correct it to "Merkleized Encoder" for accurate terminology.- while the Merklelized Encoder manages cross-chain state dependencies. + while the Merkleized Encoder manages cross-chain state dependencies.docs/src/zk/03_onchain_integration.md (3)
22-22: Use correct verb form "look up"
Change the noun "lookup" to the verb phrase "look up":- …to lookup the correct Verification Key (VK)… + …to look up the correct Verification Key (VK)…🧰 Tools
🪛 LanguageTool
[grammar] ~22-~22: The word “lookup” is a noun. The verb is spelled with a white space.
Context: ...gram. Used by Authorization contract to lookup the correct Verification Key (VK) from ...(NOUN_VERB_CONFUSION)
23-23: Add missing comma for clarity
Insert a comma before "or" to separate the independent clauses:- Ensures proofs aren't submitted multiple times or after they're no longer relevant. + Ensures proofs aren't submitted multiple times, or after they're no longer relevant.🧰 Tools
🪛 LanguageTool
[uncategorized] ~23-~23: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...s proofs aren't submitted multiple times or after they're no longer relevant. | | `...(COMMA_COMPOUND_SENTENCE)
35-35: Replace wordy phrase "with respect to"
Consider a more concise alternative, e.g.:- If the proof is valid with respect to the VK and the public inputs… + If the proof is valid against the VK and public inputs…🧰 Tools
🪛 LanguageTool
[style] ~35-~35: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...hic verification. If the proof is valid with respect to the VK and the public inputs, the gatew...(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/src/zk/05_sparse_merkle_trees.md (2)
9-9: Correct spelling of "authenticated"
Line 9 reads "authenticaed". Fix the spelling:- A Merkle tree is an authenticaed data structure… + A Merkle tree is an authenticated data structure…
92-92: Standardize hyphenation: "precomputed"
Use the single-word "precomputed" instead of "pre-computed" for consistency:- includes a pre-computed set of empty subtrees… + includes a precomputed set of empty subtrees…🧰 Tools
🪛 LanguageTool
[uncategorized] ~92-~92: Do not mix variants of the same word (‘pre-compute’ and ‘precompute’) within a single text.
Context: ...e Valence SMT implementation includes a pre-computed set of empty subtrees based on the sele...(EN_WORD_COHERENCY)
docs/src/zk/02_developing_coprocessor_apps.md (1)
21-21: Use consistent term "coprocessor"
Replace "local Valence co-processor instance" with "local Valence coprocessor instance" to maintain consistent spelling:- …or optionally run a [local Valence co-processor instance]… + …or optionally run a [local Valence coprocessor instance]…🧰 Tools
🪛 LanguageTool
[misspelling] ~21-~21: This word is normally spelled as one.
Context: ...281` or optionally run a [local Valence co-processor instance](https://github.com/timewave-c...(EN_COMPOUNDS_CO_PROCESSOR)
docs/src/zk/01_system_overview.md (1)
25-25: Prefer 'before' over 'prior to' for conciseness
The phrase "initializing the application prior to execution" is verbose. Consider replacing "prior to" with "before" for improved readability.🧰 Tools
🪛 LanguageTool
[style] ~25-~25: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...lications, initializing the application prior to execution. They build guest program com...(EN_WORDINESS_PREMIUM_PRIOR_TO)
docs/src/zk/07_state_encoding_and_encoders.md (2)
117-117: Review term "Merklelized" for correctness
The heading "Merklelized Encoder" may contain a typo. Consider renaming to "Merkleized Encoder" (or "Merkelized Encoder") to align with established terminology.
130-137: Add language specifier and closing fence to ASCII diagram
The ASCII Merkle tree diagram is in a code block without a language identifier and the closing fence is missing. To ensure proper rendering, specify a language (e.g.,text) and add the closing ``` fence after the diagram.- ``` + ```text (ASCII Merkle tree diagram lines) + ```🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
130-130: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
docs/src/zk/04_coprocessor_internals.md (3)
7-7: Correct heading level to maintain hierarchy
The heading "Service Architecture" should be level 2 (##) rather than level 3 (###) since it directly follows the level 1 title.- ### Service Architecture + ## Service Architecture🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
7-7: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3(MD001, heading-increment)
5-5: Fix verb agreement
In the sentence "registers and execute Zero-Knowledge (ZK) guest applications," change "execute" to "executes" to match the singular subject.- service that registers and execute Zero-Knowledge (ZK) guest applications. + service that registers and executes Zero-Knowledge (ZK) guest applications.
3-3: Strengthen adjective for clearer emphasis
Instead of "provides a deeper look," consider "provides a comprehensive look" or a similar term to better convey the thoroughness of this internal overview.🧰 Tools
🪛 LanguageTool
[style] ~3-~3: Consider a different adjective to strengthen your wording.
Context: ...sor Internals This document provides a deeper look into the internal architecture and...(DEEP_PROFOUND)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
docs/src/zk-coprocessor/_overview.md(0 hunks)docs/src/zk-coprocessor/sparse-merkle-trees.md(0 hunks)docs/src/zk/00_introduction.md(1 hunks)docs/src/zk/01_system_overview.md(1 hunks)docs/src/zk/02_developing_coprocessor_apps.md(1 hunks)docs/src/zk/03_onchain_integration.md(1 hunks)docs/src/zk/04_coprocessor_internals.md(1 hunks)docs/src/zk/05_sparse_merkle_trees.md(1 hunks)docs/src/zk/06_guest_environment.md(1 hunks)docs/src/zk/07_state_encoding_and_encoders.md(1 hunks)
💤 Files with no reviewable changes (2)
- docs/src/zk-coprocessor/sparse-merkle-trees.md
- docs/src/zk-coprocessor/_overview.md
🧰 Additional context used
🪛 LanguageTool
docs/src/zk/05_sparse_merkle_trees.md
[uncategorized] ~92-~92: Do not mix variants of the same word (‘pre-compute’ and ‘precompute’) within a single text.
Context: ...e Valence SMT implementation includes a pre-computed set of empty subtrees based on the sele...
(EN_WORD_COHERENCY)
docs/src/zk/01_system_overview.md
[style] ~25-~25: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...lications, initializing the application prior to execution. They build guest program com...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
docs/src/zk/03_onchain_integration.md
[grammar] ~22-~22: The word “lookup” is a noun. The verb is spelled with a white space.
Context: ...gram. Used by Authorization contract to lookup the correct Verification Key (VK) from ...
(NOUN_VERB_CONFUSION)
[uncategorized] ~23-~23: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...s proofs aren't submitted multiple times or after they're no longer relevant. | | `...
(COMMA_COMPOUND_SENTENCE)
[style] ~35-~35: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...hic verification. If the proof is valid with respect to the VK and the public inputs, the gatew...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/src/zk/04_coprocessor_internals.md
[style] ~3-~3: Consider a different adjective to strengthen your wording.
Context: ...sor Internals This document provides a deeper look into the internal architecture and...
(DEEP_PROFOUND)
docs/src/zk/02_developing_coprocessor_apps.md
[misspelling] ~21-~21: This word is normally spelled as one.
Context: ...281` or optionally run a [local Valence co-processor instance](https://github.com/timewave-c...
(EN_COMPOUNDS_CO_PROCESSOR)
🪛 markdownlint-cli2 (0.17.2)
docs/src/zk/04_coprocessor_internals.md
7-7: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
docs/src/zk/07_state_encoding_and_encoders.md
130-130: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build-and-deploy
- GitHub Check: setup-local-ic
- GitHub Check: solidity contracts
🔇 Additional comments (5)
docs/src/zk/00_introduction.md (1)
1-19: Overall: Introduction is clear and well-structured
This document effectively sets the stage for the Valence ZK documentation series, defining core concepts and terminology.docs/src/zk/06_guest_environment.md (1)
1-41: Overall: Guest environment overview is comprehensive
The file clearly describes the sandbox, virtual filesystem constraints, interaction protocols, and resource limits for controller logic. It’s informative and well-organized.docs/src/zk/03_onchain_integration.md (1)
1-41: Overall: On-chain integration docs are detailed and accurate
The workflow, data structures, and verification sequence are clearly explained.🧰 Tools
🪛 LanguageTool
[grammar] ~22-~22: The word “lookup” is a noun. The verb is spelled with a white space.
Context: ...gram. Used by Authorization contract to lookup the correct Verification Key (VK) from ...(NOUN_VERB_CONFUSION)
[uncategorized] ~23-~23: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...s proofs aren't submitted multiple times or after they're no longer relevant. | | `...(COMMA_COMPOUND_SENTENCE)
[style] ~35-~35: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...hic verification. If the proof is valid with respect to the VK and the public inputs, the gatew...(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/src/zk/05_sparse_merkle_trees.md (1)
1-134: Overall: Sparse Merkle Trees documentation is thorough
This file provides clear definitions, diagrams, and implementation insights for SMTs.🧰 Tools
🪛 LanguageTool
[uncategorized] ~92-~92: Do not mix variants of the same word (‘pre-compute’ and ‘precompute’) within a single text.
Context: ...e Valence SMT implementation includes a pre-computed set of empty subtrees based on the sele...(EN_WORD_COHERENCY)
docs/src/zk/02_developing_coprocessor_apps.md (1)
1-33: Overall: Development guide is well-structured
The step-by-step workflow, crate responsibilities, and CLI examples are clear and actionable.🧰 Tools
🪛 LanguageTool
[misspelling] ~21-~21: This word is normally spelled as one.
Context: ...281` or optionally run a [local Valence co-processor instance](https://github.com/timewave-c...(EN_COMPOUNDS_CO_PROCESSOR)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
docs/src/zk/_overview.md (1)
3-3: Fix article usage in introductory sentence.The phrase “Valence Protocol provides a Zero-Knowledge proofs…” uses an incorrect article before the plural noun. Consider removing the “a”:
- Valence Protocol provides a Zero-Knowledge proofs and a dedicated ZK Coprocessor system… + Valence Protocol provides Zero-Knowledge proofs and a dedicated ZK Coprocessor system…docs/src/zk/02_developing_coprocessor_apps.md (1)
21-23: Inconsistent hyphenation and missing comma.
- Change “co-processor” to “Coprocessor” for consistency:
- run a [local Valence co-processor instance] + run a [local Valence Coprocessor instance]- Add a comma after “importance” for readability:
- The public output of your ZK circuit (a `Vec<u8>`) is of particular importance as this is... + The public output of your ZK circuit (a `Vec<u8>`) is of particular importance, as this is...🧰 Tools
🪛 LanguageTool
[misspelling] ~21-~21: This word is normally spelled as one.
Context: ...281` or optionally run a [local Valence co-processor instance](https://github.com/timewave-c...(EN_COMPOUNDS_CO_PROCESSOR)
[uncategorized] ~23-~23: Possible missing comma found.
Context: ... circuit (aVec<u8>) is of particular importance as this is the data that will ultimatel...(AI_HYDRA_LEO_MISSING_COMMA)
docs/src/zk/01_system_overview.md (2)
5-5: Capitalize “Service” for consistency.You write “off-chain ZK Coprocessor service” here, but later use “ZK Coprocessor Service” in title case. Align to title case:
- integrates an off-chain ZK Coprocessor service with on-chain smart contracts + integrates an off-chain ZK Coprocessor Service with on-chain smart contracts
25-25: Replace “prior to” with “before” for clarity.The phrase “initializing the application prior to execution” is wordy. Consider simplifying:
- Developers prepare and register their ZK applications, initializing the application prior to execution. + Developers prepare and register their ZK applications, initializing the application before execution.🧰 Tools
🪛 LanguageTool
[style] ~25-~25: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...lications, initializing the application prior to execution. They build guest program com...(EN_WORDINESS_PREMIUM_PRIOR_TO)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/src/SUMMARY.md(2 hunks)docs/src/components/_overview.md(1 hunks)docs/src/zk/01_system_overview.md(1 hunks)docs/src/zk/02_developing_coprocessor_apps.md(1 hunks)docs/src/zk/_overview.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/src/components/_overview.md
🧰 Additional context used
🧠 Learnings (1)
docs/src/zk/01_system_overview.md (1)
Learnt from: keyleu
PR: timewave-computer/valence-protocol#346
File: contracts/authorization/src/contract.rs:357-452
Timestamp: 2025-05-14T08:59:53.676Z
Learning: ZK authorizations in the Valence protocol don't require the same validation mechanism as standard authorizations. They have a different validation approach with inline checks in the `create_zk_authorizations` function and core validation occurring at execution time through proof verification.
🪛 LanguageTool
docs/src/SUMMARY.md
[duplication] ~13-~13: Possible typo: you repeated a word.
Context: ...components/middleware.md) - Valence ZK System - System Overview ...
(ENGLISH_WORD_REPEAT_RULE)
docs/src/zk/01_system_overview.md
[style] ~25-~25: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ...lications, initializing the application prior to execution. They build guest program com...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
docs/src/zk/02_developing_coprocessor_apps.md
[misspelling] ~21-~21: This word is normally spelled as one.
Context: ...281` or optionally run a [local Valence co-processor instance](https://github.com/timewave-c...
(EN_COMPOUNDS_CO_PROCESSOR)
[uncategorized] ~23-~23: Possible missing comma found.
Context: ... circuit (a Vec<u8>) is of particular importance as this is the data that will ultimatel...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/src/zk/_overview.md
[uncategorized] ~2-~2: You might be missing the article “the” here.
Context: # Introduction to Valence ZK Valence Protocol provides a Zero-Knowledge proo...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: build
- GitHub Check: build-and-deploy
🔇 Additional comments (1)
docs/src/SUMMARY.md (1)
13-20: Looks good: ZK System section added correctly.The new “Valence ZK System” section with its subsections integrates well into the SUMMARY, reflects the updated documentation structure, and follows existing indentation conventions.
🧰 Tools
🪛 LanguageTool
[duplication] ~13-~13: Possible typo: you repeated a word.
Context: ...components/middleware.md) - Valence ZK System - System Overview ...(ENGLISH_WORD_REPEAT_RULE)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
docs/src/zk/_overview.md (3)
1-4: Add missing article and improve clarity in introduction.
The opening sentence reads more naturally as “The Valence Protocol provides…”. Adding “The” enhances readability.- # Introduction to Valence ZK - Valence Protocol provides Zero-Knowledge proofs and a dedicated ZK Coprocessor system to enhance its capabilities, particularly in areas requiring complex computation, privacy, and verifiable off-chain operations. + # Introduction to Valence ZK + The Valence Protocol provides Zero-Knowledge proofs and a dedicated ZK Coprocessor system to enhance its capabilities, particularly in areas requiring complex computation, privacy, and verifiable off-chain operations.🧰 Tools
🪛 LanguageTool
[uncategorized] ~2-~2: You might be missing the article “the” here.
Context: # Introduction to Valence ZK Valence Protocol provides Zero-Knowledge proofs...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
11-17: Enhance readability of key terms list.
Consider adding links to deeper sections (e.g.,06_guest_environment.md) and breaking long definitions into smaller sentences or bullet subpoints for consistency.- **Guest Program:** Software designed for off-chain execution on the ZK Coprocessor. It has two parts: 1. **ZK Circuit:** Defines core ZK-provable computations. 2. **Controller:** Wasm-compiled logic for preparing inputs, handling outputs, and interacting with the Coprocessor.
19-19: Add link to documentation summary.
At the end of this overview, add a link to the main SUMMARY.md entry for the Valence ZK section to help readers navigate the full docs.For detailed information on how blockchain state is encoded for ZK proofs and cross-chain coordination, see [State Encoding and Encoders](./07_state_encoding_and_encoders.md). See the full Valence ZK docs in the [SUMMARY](../SUMMARY.md#valence-zk) section.docs/src/zk/03_onchain_integration.md (2)
20-26: Fix “lookup” verb usage and add missing comma.
Change “lookup” (noun) to “look up” (verb), insert “the” before “Authorization contract,” and add a comma before “or” to improve grammar.- | `registry` | uint64 | Unique identifier for the deployed ZK guest program. Used by Authorization contract to lookup the correct Verification Key (VK) from VerificationGateway. | + | `registry` | uint64 | Unique identifier for the deployed ZK guest program. Used by the Authorization contract to look up the correct Verification Key (VK) from VerificationGateway. | - | `blockNumber` | uint64 | Current or recent block number for replay protection. Ensures proofs aren't submitted multiple times or after they're no longer relevant. | + | `blockNumber` | uint64 | Current or recent block number for replay protection. Ensures proofs aren't submitted multiple times, or after they're no longer relevant. |🧰 Tools
🪛 LanguageTool
[grammar] ~22-~22: The word “lookup” is a noun. The verb is spelled with a white space.
Context: ...gram. Used by Authorization contract to lookup the correct Verification Key (VK) from ...(NOUN_VERB_CONFUSION)
[uncategorized] ~23-~23: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...s proofs aren't submitted multiple times or after they're no longer relevant. | | `...(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~24-~24: You might be missing the article “the” here.
Context: ...contract. Acts as a safeguard to ensure message is processed by the correct instance. |...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
34-36: Streamline wording for style.
Replace “with respect to” to reduce verbosity.- If the proof is valid with respect to the VK and the public inputs, the gateway returns a success status... + If the proof is valid for the VK and public inputs, the gateway returns a success status...🧰 Tools
🪛 LanguageTool
[style] ~35-~35: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...hic verification. If the proof is valid with respect to the VK and the public inputs, the gatew...(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/src/zk/04_coprocessor_internals.md (2)
3-3: Consider stronger descriptor.
“Provides a deeper look” could be more impactful as “Offers a comprehensive overview” or “Provides an in-depth look.”🧰 Tools
🪛 LanguageTool
[style] ~3-~3: Consider a different adjective to strengthen your wording.
Context: ...sor Internals This document provides a deeper look into the internal architecture and...(DEEP_PROFOUND)
5-6: Correct verb agreement.
Change “registers and execute” to “registers and executes” to maintain subject-verb agreement.- The Valence ZK Coprocessor is designed as a persistent off-chain service that registers and execute Zero-Knowledge (ZK) guest applications. + The Valence ZK Coprocessor is designed as a persistent off-chain service that registers and executes Zero-Knowledge (ZK) guest applications.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/src/zk/01_system_overview.md(1 hunks)docs/src/zk/02_developing_coprocessor_apps.md(1 hunks)docs/src/zk/03_onchain_integration.md(1 hunks)docs/src/zk/04_coprocessor_internals.md(1 hunks)docs/src/zk/_overview.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/src/zk/01_system_overview.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/src/zk/02_developing_coprocessor_apps.md
🧰 Additional context used
🪛 LanguageTool
docs/src/zk/_overview.md
[uncategorized] ~2-~2: You might be missing the article “the” here.
Context: # Introduction to Valence ZK Valence Protocol provides Zero-Knowledge proofs...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
docs/src/zk/03_onchain_integration.md
[grammar] ~22-~22: The word “lookup” is a noun. The verb is spelled with a white space.
Context: ...gram. Used by Authorization contract to lookup the correct Verification Key (VK) from ...
(NOUN_VERB_CONFUSION)
[uncategorized] ~23-~23: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...s proofs aren't submitted multiple times or after they're no longer relevant. | | `...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~24-~24: You might be missing the article “the” here.
Context: ...contract. Acts as a safeguard to ensure message is processed by the correct instance. |...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[style] ~35-~35: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...hic verification. If the proof is valid with respect to the VK and the public inputs, the gatew...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/src/zk/04_coprocessor_internals.md
[style] ~3-~3: Consider a different adjective to strengthen your wording.
Context: ...sor Internals This document provides a deeper look into the internal architecture and...
(DEEP_PROFOUND)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: solidity contracts
- GitHub Check: setup-local-ic
- GitHub Check: build-and-deploy
keyleu
left a comment
keyleu
left a comment
There was a problem hiding this comment.
makes sense to me, left 1 suggestion
|
|
||
| **Proof Submission and Verification** | ||
|
|
||
| Following proof generation, the off-chain entity retrieves the ZK proof and circuit's public output from the Coprocessor. It constructs a `ZKMessage`, which includes the circuit's public output (forming the `processorMessage`), the `registry` ID, a `blockNumber` for replay protection, and the target `authorizationContract` address. This `ZKMessage` and ZK proof are submitted to the `executeZKMessage` function of the `Authorization` contract. |
There was a problem hiding this comment.
just to clarify authorizationContract is optional here, if not used it's not validated.
|
|
||
| **On-Chain Processing** | ||
|
|
||
| This triggers on-chain processing. The `Authorization` contract performs initial checks, verifying sender authorization for the `registry` ID and ensuring replay protection using the `blockNumber`. If checks pass, it calls the `verify` function on the `VerificationGateway`, passing the ZK proof and relevant public inputs from the `ZKMessage`. The `VerificationGateway` uses the `registry` ID to fetch the correct VK and verify the proof. The first 32 bytes of public inputs are a "Coprocessor Root" hash, with application-specific circuit output following. |
There was a problem hiding this comment.
| This triggers on-chain processing. The `Authorization` contract performs initial checks, verifying sender authorization for the `registry` ID and ensuring replay protection using the `blockNumber`. If checks pass, it calls the `verify` function on the `VerificationGateway`, passing the ZK proof and relevant public inputs from the `ZKMessage`. The `VerificationGateway` uses the `registry` ID to fetch the correct VK and verify the proof. The first 32 bytes of public inputs are a "Coprocessor Root" hash, with application-specific circuit output following. | |
| This triggers on-chain processing. The `Authorization` contract performs initial checks, verifying sender authorization for the `registry` ID and ensuring replay protection using the `blockNumber`. If checks pass, it calls the `verify` function on the `VerificationGateway`, passing the ZK proof and public inputs. The `VerificationGateway` uses the `registry` ID to fetch the correct VK and verify the proof. The first 32 bytes of public inputs are a "Coprocessor Root" hash, with application-specific circuit output following. |
There was a problem hiding this comment.
the ZkMessage is part of the public inputs, public inputs are not from ZKMessage but is given returned by the circuit when computing the proof
vlopes11
left a comment
vlopes11
left a comment
There was a problem hiding this comment.
Looks very good, thanks for that! Only a couple of questions & suggestions
| @@ -0,0 +1,97 @@ | |||
| # Valence ZK System Overview | |||
|
|
|||
| The Valence Zero-Knowledge (ZK) system facilitates the execution of complex or private computations off-chain, with their correctness verified on-chain through cryptographic proofs. This overview describes the primary components and the general flow of information and operations within this system. The foundational concepts of ZK proofs in Valence are introduced in [Introduction to Valence ZK](./_overview.md). | |||
There was a problem hiding this comment.
Should we mention here we always check on-chain with Groth16 proofs that are agnostic to the prover backend?
|
|
||
| The Valence ZK system comprises several key components, each with distinct responsibilities. | ||
|
|
||
| The **ZK Coprocessor Service**, operating off-chain, is a persistent service that manages ZK "guest programs." It deploys new guest programs, executes them with specific inputs, manages proving using an underlying zkVM (like SP1), and makes generated proofs available. Developers interact with this service to deploy ZK applications and initiate proof generation. |
There was a problem hiding this comment.
We should probably mention that we call the guest programs "circuit"
|
|
||
| The **ZK Coprocessor Service**, operating off-chain, is a persistent service that manages ZK "guest programs." It deploys new guest programs, executes them with specific inputs, manages proving using an underlying zkVM (like SP1), and makes generated proofs available. Developers interact with this service to deploy ZK applications and initiate proof generation. | ||
|
|
||
| A **Guest Program** is application-specific code developed by users. It consists of two parts: the **Controller** (Wasm-compiled Rust code running in the Coprocessor's sandbox) takes input data, processes it to generate a "witness" for the ZK circuit, and coordinates proof generation. The **ZK Circuit** (e.g., SP1 circuit) performs the core computation and assertions, taking the witness and producing a proof and public output (`Vec<u8>`) that forms the primary data for on-chain contracts. |
There was a problem hiding this comment.
The controller is not necessarily WASM. It happens to be right now, but that might change. Maybe call it a sandboxed user runtime?
| graph TD | ||
| Strategist[Strategist<br/>- Requests proof generation<br/>- Retrieves proof<br/>- Submits ZKMessage] -- Requests proof generation --> Coproc[ZK Coprocessor Service] | ||
| Coproc -- Executes Guest Program --> Proof[ZK Proof + Public Output] | ||
| Strategist -- Retrieves proof --> Coproc |
There was a problem hiding this comment.
Should we mention here this is called by the custom entrypoint of the controller that allows for it to, for example, post an HTTP request somewhere as callback?
|
|
||
| A Valence Coprocessor App (a Guest Program), when based on the template, is primarily structured around two main Rust crates, which compile into the two logical parts of the Guest Program: the Controller and the ZK Circuit. | ||
|
|
||
| 1. **The `controller` Crate (compiles to the Controller):** This component contains off-chain logic executed as Wasm within the Valence ZK Coprocessor's sandboxed environment. This **Controller** acts as an intermediary between user inputs and the ZK circuit. Key responsibilities include receiving input arguments (often JSON) for proof requests, processing inputs to generate a "witness" (private and public data the ZK circuit needs), and interacting with the Coprocessor service to initiate proof generation. The Controller handles proof computation results; it has an entrypoint function the Coprocessor calls upon successful proof generation, allowing the Controller to store the proof or log information. The Controller can utilize a virtual filesystem provided by the Coprocessor, which is FAT-16 based (implying constraints like 3-character file extensions and case-insensitive paths), for persistent data storage. |
There was a problem hiding this comment.
Note: whenever I have some free time, I plan to upgrade from FAT-16 to EXT-4
|
|
||
| 1. **The `controller` Crate (compiles to the Controller):** This component contains off-chain logic executed as Wasm within the Valence ZK Coprocessor's sandboxed environment. This **Controller** acts as an intermediary between user inputs and the ZK circuit. Key responsibilities include receiving input arguments (often JSON) for proof requests, processing inputs to generate a "witness" (private and public data the ZK circuit needs), and interacting with the Coprocessor service to initiate proof generation. The Controller handles proof computation results; it has an entrypoint function the Coprocessor calls upon successful proof generation, allowing the Controller to store the proof or log information. The Controller can utilize a virtual filesystem provided by the Coprocessor, which is FAT-16 based (implying constraints like 3-character file extensions and case-insensitive paths), for persistent data storage. | ||
|
|
||
| 2. **The `circuit` Crate (defines the ZK Circuit):** This crate defines the **ZK Circuit** itself. The ZK Circuit is the heart of the ZK application, containing the actual computations and assertions whose correctness will be proven. It's typically written using a specialized language or Domain-Specific Language (DSL) that compiles down to a ZK proving system supported by the Coprocessor (for example, SP1). The ZK Circuit receives the witness data prepared by the Controller. It then performs its defined computations and assertions. If all these pass, it produces a public output (as a `Vec<u8>`), which represents the public statement that will be cryptographically verified on-chain. This output forms a crucial part of the "public inputs" of the ZK proof. |
There was a problem hiding this comment.
We don't use a DSL here since we are using native Rust. Your mean DSL as the Rust frontend to RiscV? I think we should rephrase this part to make it clear that the devs touch Rust only (for now)
|
|
||
| 3. **Controller Development (`./crates/controller`):** Concurrently, you'll develop the Controller logic within the `controller` crate. This includes implementing the logic to parse incoming JSON arguments that are provided when a proof is requested for your application. You will also need to write the code that transforms these user-provided arguments into the precise witness format required by your ZK circuit. A key part of the Controller is its entrypoint function; this function is called by the Coprocessor service when a proof for your program has been successfully generated and is ready. This entrypoint typically receives the proof itself, the initial arguments that triggered the request, and any logs generated during the process. You must also implement how your Controller should handle this generated proof – a common pattern is to store it to a specific path (e.g., `/var/share/proof.bin`) within its virtual filesystem using a `store` command payload directed to the Coprocessor. | ||
|
|
||
| 4. **Application Build and Deployment:** Once the ZK Circuit (from `circuit` crate) and Controller (from `controller` crate) are developed, you build and deploy your Guest Program to the Coprocessor using the `cargo-valence` CLI tool. This is typically done by running the command `cargo-valence --socket prover.timewave.computer:37281 deploy circuit --controller ./crates/controller --circuit <circuit-name>` from your app template directory. If you're using a local coprocessor instance, you can omit the `--socket` parameter. This command compiles both crates (Controller to Wasm) and packages them into a single application bundle, which is then submitted to the Coprocessor service. Upon successful deployment, the Coprocessor service will return a unique Controller ID (e.g., `8965493acca61dfc26193978c4b9a785d24192a0a314143f1c497402859df783`). This Controller ID is crucial as it's used to reference your deployed ZK application in subsequent interactions. |
There was a problem hiding this comment.
We could put circuit-crate-project-name to disambiguate
|
|
||
| ### Incorporating Verifiable External State | ||
|
|
||
| Guest programs on the Valence Coprocessor can be designed to utilize verifiable state from external blockchains, like Ethereum. This allows ZK applications to react to or incorporate off-chain data in a trust-minimized way. Services such as the state proof service facilitate this by generating state proofs (e.g., Merkle proofs for account balances or storage slots on Ethereum at specific block heights). |
There was a problem hiding this comment.
We could mention this is done via the ABI HTTP call (we can release future stuff such as websockets, or whatever the user needs)
|
|
||
| 2. **Delegation to `VerificationGateway.sol`:** If the initial checks pass, `Authorization.sol` delegates the task of cryptographic proof verification to the `VerificationGateway.sol` contract whose address it has been configured with. It calls a `verify` function on the gateway, passing along the ZK proof, the `registry` ID (so the gateway can find the correct VK), and a hash derived from the `ZKMessage` contents (crucially including the `processorMessage` which represents your circuit's output). | ||
|
|
||
| 3. **Proof Verification by `VerificationGateway.sol`:** The `VerificationGateway` retrieves the pre-registered Verification Key (VK) associated with the `registry` ID. It then uses this VK, the submitted ZK proof, and the public inputs (which include the Coprocessor Root hash and your circuit's output embedded within the hashed `ZKMessage`) to perform the cryptographic verification. If the proof is valid with respect to the VK and the public inputs, the gateway returns a success status to the `Authorization.sol` contract. |
There was a problem hiding this comment.
It's important to mention that the co-processor root contains all the embedded state proofs of the domain of that proof via its SMT. Every new appended block is included in the SMT with a ZK domain proof, and all the verifications of these inclusions are embedded into this root.
|
|
||
| ### Service Architecture | ||
|
|
||
| The Coprocessor service consists of several coordinated components that work together to provide a complete ZK execution environment: |
There was a problem hiding this comment.
It's nice to mention that we split the prover from the coprocessor. We have a dedicated prover instance running on prover.timewave.computer:37282 for holders of VALENCE_PROVER_SECRET to connect their coprocessor instances to, and we have the possibility to run the coprocessor isolated from the proof, on localhost, with mocked ZK proofs - for debugging purposes.
|
pushed an update which should address everything above |
3 participants
this reformulates the intro + SMT docs that were on the docs site, and then adds a few more documents that fill in details about some important components:
this will definitely need to be adjusted as the architecture continues to solidity, but it's a much better starting point than what's on the site right now
Summary by CodeRabbit