Add ZK documentation

.gitignore

@@ -6,3 +6,5 @@ mintlify-docs/
 
 # Dependencies
 node_modules/
+
+stash

cspell.json

@@ -175,7 +175,16 @@
     "stablecoins",
     "fintechs",
     "micropayments",
-    "clawback"
+    "clawback",
+    "hackathon",
+    "altbn",
+    "circom",
+    "snarkjs",
+    "Zcash",
+    "zcash",
+    "circomlibjs",
+    "Jotaro",
+    "Yano"
   ],
   "ignorePaths": [
     "node_modules",

docs.json

@@ -99,6 +99,33 @@
               "quickstart"
             ]
           },
+          {
+            "group": "ZK",
+            "pages": [
+              "zk/overview",
+              "zk/examples"
+            ]
+          },
+          {
+            "group": "Compressed PDAs",
+            "pages": [
+              "compressed-pdas/overview",
+              {
+                "group": "Program Guides",
+                "pages": [
+                  "compressed-pdas/guides",
+                  "compressed-pdas/guides/how-to-create-compressed-accounts",
+                  "compressed-pdas/guides/how-to-update-compressed-accounts",
+                  "compressed-pdas/guides/how-to-close-compressed-accounts",
+                  "compressed-pdas/guides/how-to-reinitialize-compressed-accounts",
+                  "compressed-pdas/guides/how-to-burn-compressed-accounts"
+                ]
+              },
+              "compressed-pdas/program-examples",
+              "client-library/client-guide",
+              "compressed-pdas/solana-attestation-service"
+            ]
+          },
           {
             "group": "Compressed Tokens",
             "pages": [
@@ -144,26 +171,6 @@
               }
             ]
           },
-          {
-            "group": "Compressed PDAs",
-            "pages": [
-              "compressed-pdas/create-a-program-with-compressed-pdas",
-              {
-                "group": "Program Guides",
-                "pages": [
-                  "compressed-pdas/guides",
-                  "compressed-pdas/guides/how-to-create-compressed-accounts",
-                  "compressed-pdas/guides/how-to-update-compressed-accounts",
-                  "compressed-pdas/guides/how-to-close-compressed-accounts",
-                  "compressed-pdas/guides/how-to-reinitialize-compressed-accounts",
-                  "compressed-pdas/guides/how-to-burn-compressed-accounts"
-                ]
-              },
-              "compressed-pdas/program-examples",
-              "client-library/client-guide",
-              "compressed-pdas/solana-attestation-service"
-            ]
-          },
           {
             "group": "JSON RPC Methods",
             "pages": [

home.mdx

@@ -189,7 +189,7 @@ import WelcomePageInstall from "/snippets/setup/welcome-page-install.mdx";
   <Card
     title="Compressed PDAs"
     icon="users"
-    href="/compressed-pdas/create-a-program-with-compressed-pdas"
+    href="/compressed-pdas/overview"
   >
     Program and client guides for rent-free PDA accounts.
   </Card>

learn/core-concepts/considerations.mdx

@@ -81,7 +81,7 @@ You're ready to take the next step and start building!
   title="Compressed PDAs"
   icon="chevron-right"
   color="#0066ff"
-  href="/compressed-pdas/create-a-program-with-compressed-pdas"
+  href="/compressed-pdas/overview"
   horizontal
 />
 </CardGroup>

package.json

@@ -12,11 +12,10 @@
     "ci": "npm run format:check && npm run lint && npm run spellcheck"
   },
   "devDependencies": {
-    "cspell": "^8.6.0",
+    "cspell": "^8.19.4",
     "eslint": "^8.57.0",
     "eslint-plugin-react": "^7.34.1",
     "eslint-plugin-react-hooks": "^4.6.2",
     "prettier": "^3.2.5"
   }
 }
-

references/migration-v1-to-v2.mdx

@@ -4,15 +4,16 @@ description: V2 reduces CU consumption by up to 70%. V1 remains supported for ex
 sidebarTitle: V2 Migration Guide
 ---
 
-## V2 Improvements
+import V1ToV2MigrationPrompt from "/snippets/ai-prompts/v1-to-v2-migration.mdx";
 
-|                     | v1                                                                                                        | v2                                                                                                      |
-|---------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
-| Merkle tree type    | Concurrent                                                                                               | Batched                                                                                                |
-| State tree depth    | 26 (~67M leaves)                                                                                        | 32 (~4B leaves)                                                                                      |
-| Address tree depth  | 26                                                                                                       | 40                                                                                                     |
-| Address tree accounts| Separate tree + queue                                                                                    | Single batch tree                                                                                     |
+## V2 Improvements
 
+|                       | v1                    | v2                 |
+|-----------------------|-----------------------|--------------------|
+| Merkle tree type      | Concurrent            | Batched            |
+| State tree depth      | 26 (~67M leaves)      | 32 (~4B leaves)    |
+| Address tree depth    | 26                    | 40                 |
+| Address tree accounts | Separate tree + queue | Single batch tree  |
 
 <Tabs>
 <Tab title="TypeScript">
@@ -250,6 +251,11 @@ let new_address_params = instruction_data
     .into_new_address_params_assigned_packed(address_seed, Some(0));
 ```
 
+</Tab>
+<Tab title="AI Prompt">
+
+<V1ToV2MigrationPrompt />
+
 </Tab>
 </Tabs>
 

resources/addresses-and-urls.mdx

@@ -87,7 +87,6 @@ Find all JSON RPC Methods for ZK Compression [here](/api-reference/json-rpc-meth
 
 </Tab>
 
-
 </Tabs>
 
 ## Address Trees & Queues

resources/cli-installation.mdx

@@ -253,7 +253,7 @@ FLAGS
   title="Build with compressed PDAs"
   icon="chevron-right"
   color="#0066ff"
-  href="/compressed-pdas/create-a-program-with-compressed-pdas"
+  href="/compressed-pdas/overview"
   horizontal
 />
 </CardGroup>

snippets/ai-prompts/v1-to-v2-migration.mdx

@@ -0,0 +1,105 @@
+---
+argument-hint: <path_to_program>
+description: Migrate Light Protocol program from v1 to v2 Merkle trees
+allowed-tools: [Bash, Read, Glob, Grep, Task, WebFetch]
+---
+
+Migrate this Light Protocol program from v1 to v2 Merkle trees.
+
+## Goal
+
+Produce a **fully working migration** that builds and tests pass.
+
+## Available commands
+
+Via Bash tool:
+- `cargo build-sbf`, `cargo test-sbf`, `cargo fmt`, `cargo clippy`
+- `anchor build`, `anchor test`
+- `grep`, `sed`
+
+## Documentation
+
+- Migration Guide: https://zkcompression.com/references/migration-v1-to-v2
+- Reference PR: https://github.com/Lightprotocol/program-examples/commit/54f0e7f15c2972a078f776cfb40b238d83c7e486
+
+## Reference repos
+
+program-examples/counter/anchor/
+├── programs/counter/src/lib.rs    # v2 patterns: derive_address, CpiAccounts
+├── Cargo.toml                      # v2 feature flags
+└── tests/counter.ts                # v2 client patterns
+
+## Workflow
+
+### Phase 1: Index program
+
+Find all v1 patterns:
+
+    grep -r "::v1::" src/ tests/
+    grep -r "ADDRESS_TREE_V1" src/
+    grep -r "into_new_address_params_packed" src/
+    grep -r "get_address_tree_v1" tests/
+
+### Phase 2: Update dependencies
+
+Add v2 feature to Cargo.toml:
+
+    [dependencies]
+    light-sdk = { version = "0.17", features = ["anchor", "v2"] }
+    light-sdk-types = { version = "0.17", features = ["v2"] }
+
+    [dev-dependencies]
+    light-program-test = { version = "0.17", features = ["v2"] }
+    light-client = { version = "0.17", features = ["v2"] }
+
+### Phase 3: Rust SDK replacements
+
+| v1 Pattern | v2 Replacement |
+|------------|----------------|
+| address::v1::derive_address | address::v2::derive_address |
+| cpi::v1::CpiAccounts | cpi::v2::CpiAccounts |
+| cpi::v1::LightSystemProgramCpi | cpi::v2::LightSystemProgramCpi |
+| constants::ADDRESS_TREE_V1 | light_sdk_types::ADDRESS_TREE_V2 |
+| .into_new_address_params_packed(seed) | .into_new_address_params_assigned_packed(seed, Some(0)) |
+| .add_system_accounts(config) | .add_system_accounts_v2(config) |
+
+### Phase 4: TypeScript SDK replacements
+
+| v1 Pattern | v2 Replacement |
+|------------|----------------|
+| deriveAddress( | deriveAddressV2( |
+| deriveAddressSeed( | deriveAddressSeedV2( |
+| defaultTestStateTreeAccounts().addressTree | batchAddressTree |
+| .newWithSystemAccounts( | .newWithSystemAccountsV2( |
+| get_address_tree_v1() | get_address_tree_v2() |
+| get_random_state_tree_info_v1() | get_random_state_tree_info() |
+
+### Phase 5: Build and test loop
+
+**Required commands (no shortcuts):**
+
+For Anchor programs: `anchor build && anchor test`
+
+For Native programs: `cargo build-sbf && cargo test-sbf`
+
+**NO shortcuts allowed:**
+
+- Do NOT use `cargo build` (must use `cargo build-sbf`)
+- Do NOT use `cargo test` (must use `cargo test-sbf`)
+- Tests MUST run against real BPF bytecode
+
+**On failure:** Spawn debugger agent with error context.
+
+**Loop rules:**
+
+1. Each debugger gets fresh context + previous debug reports
+2. Each attempt tries something DIFFERENT
+3. **NEVER GIVE UP** - keep spawning until fixed
+
+Do NOT proceed until all tests pass.
+
+## DeepWiki fallback
+
+If no matching pattern in reference repos:
+
+    mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "How to migrate {pattern} from v1 to v2?")

snippets/mermaid/nullifier-flow.mdx

@@ -0,0 +1,18 @@
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Client
+    participant P as Program
+    participant L as Light Protocol
+
+    U->>C: secret + verification_id
+    C->>C: nullifier = Poseidon(vid, secret)
+    C->>C: proof = Groth16.prove(...)
+    C->>P: create_nullifier(proof, vid, nullifier)
+    P->>P: Groth16.verify(proof)
+    P->>L: derive_address(nullifier, vid)
+    L-->>P: address
+    P->>L: create_account(address)
+    L-->>P: success/fail
+    P-->>U: tx result
+```

snippets/overview-tables/zk-examples-table.mdx

@@ -0,0 +1,4 @@
+|  | Description |
+|:--------|:------------|
+| [ZK-ID](https://github.com/Lightprotocol/program-examples/tree/main/zk/zk-id) | Identity verification using Groth16 proofs. Issuers create credentials; users prove ownership without revealing the credential. |
+| [Nullifier](https://github.com/Lightprotocol/program-examples/tree/main/zk/zk-nullifier) | Simple Program to Create Nullifiers. |

welcome.mdx

@@ -24,7 +24,7 @@ import WelcomePageInstall from "/snippets/setup/welcome-page-install.mdx";
 
   <Card
     title="Compressed PDAs"
-    href="/compressed-pdas/create-a-program-with-compressed-pdas"
+    href="/compressed-pdas/overview"
     icon="user"
   >
     For App State.

zk/examples.mdx

@@ -0,0 +1,10 @@
+---
+title: Examples
+description: Example projects for building privacy applications on Solana.
+keywords: ["privacy examples solana", "zk examples solana", "private payments examples", "zk identity solana"]
+---
+
+import ZkExamplesTable from "/snippets/overview-tables/zk-examples-table.mdx";
+
+<ZkExamplesTable />
+