docs: improve zk-merkle-proof and zk-nullifier READMEs

tilo-14 · tilo-14 · commit 8352b983a5ae · 2026-01-12T22:24:51.000Z
diff --git a/zk/zk-merkle-proof/README.md b/zk/zk-merkle-proof/README.md
@@ -21,21 +21,57 @@ Verifies a Groth16 proof that the account exists in the state tree. Does not mod
 - The account address stays private
 - Only the data hash, discriminator, and Merkle root are public
 
-## Circuit
+## Requirements
 
-5 public inputs:
+### System dependencies
 
-- `owner_hashed` - program ID
-- `merkle_tree_hashed` - state tree pubkey
-- `discriminator` - account type
-- `data_hash` - account data
-- `expectedRoot` - current Merkle root
+- **Rust** (1.90.0 or later)
+- **Node.js** (v22 or later) and npm
+- **Solana CLI** (2.3.11 or later)
+- **Light CLI**: Install with `npm install -g @lightprotocol/zk-compression-cli`
 
-Account hash:
+### ZK circuit tools
 
+- **Circom** (v2.2.2): Zero-knowledge circuit compiler
+- **SnarkJS**: JavaScript library for generating and verifying ZK proofs
+
+To install circom and snarkjs:
+
+```bash
+# Install circom (Linux/macOS)
+wget https://github.com/iden3/circom/releases/download/v2.2.2/circom-linux-amd64
+chmod +x circom-linux-amd64
+sudo mv circom-linux-amd64 /usr/local/bin/circom
+
+# For macOS, replace with circom-macos-amd64
+
+# Install snarkjs globally
+npm install -g snarkjs
 ```
-Poseidon(owner_hashed, leaf_index, merkle_tree_hashed, address, discriminator + DOMAIN, data_hash)
-```
+
+## Circuit
+
+### Public inputs
+
+- `owner_hashed` - Hash of the program ID owning the account
+- `merkle_tree_hashed` - Hash of the state tree pubkey
+- `discriminator` - Account type discriminator
+- `data_hash` - Hash of account data
+- `expectedRoot` - Current Merkle root
+
+### Private inputs
+
+- `leaf_index` - Position of the account in the Merkle tree
+- `account_leaf_index` - Leaf index field inside compressed account hash
+- `address` - Compressed account address
+- `pathElements[26]` - Merkle proof siblings
+
+### Constraint
+
+The circuit:
+
+1. Computes the account hash: `Poseidon(owner_hashed, leaf_index, merkle_tree_hashed, address, discriminator + DOMAIN, data_hash)`
+2. Verifies the Merkle proof against `expectedRoot`
 
 ## Setup
 
@@ -45,11 +81,13 @@ Poseidon(owner_hashed, leaf_index, merkle_tree_hashed, address, discriminator +
 
 This script will:
 
-1. Install npm dependencies
-2. Download the Powers of Tau ceremony file
-3. Compile the circom circuit
-4. Generate the proving key (zkey)
-5. Export the verification key
+1. Check dependencies (Node.js, circom)
+2. Install npm dependencies
+3. Create build directories
+4. Download the Powers of Tau ceremony file (16 powers)
+5. Compile the circuit
+6. Generate the proving key (zkey) with contribution
+7. Export the verification key
 
 ## Build and Test
 
@@ -80,3 +118,11 @@ zk-merkle-proof/
 └── scripts/
     └── setup.sh                     # Circuit compilation and setup
 ```
+
+## Cleaning build artifacts
+
+To clean generated circuit files:
+
+```bash
+./scripts/clean.sh
+```
diff --git a/zk/zk-nullifier/README.md b/zk/zk-nullifier/README.md
@@ -2,9 +2,9 @@
 
 Example to create one or four nullifiers. Uses Groth16 proofs and compressed accounts.
 
-The required property for nullifiers is that they can not be created twice. 
+The required property for nullifiers is that they can not be created twice.
 Light uses rent-free PDAs to track nullifiers in an address Merkle tree.
-The address tree is the nullifier set and indexed by Helius. 
+The address tree is the nullifier set and indexed by Helius.
 You don't need to index your own Merkle tree.
 
 On Solana, you typically would create a PDA account.
@@ -15,21 +15,64 @@ Nullifier accounts must remain active, hence lock ~0.001 SOL in rent per nullifi
 | PDA | ~0.001 SOL |
 | Compressed PDA | ~0.000005 SOL |
 
+## Requirements
+
+### System dependencies
+
+- **Rust** (1.90.0 or later)
+- **Node.js** (v22 or later) and npm
+- **Solana CLI** (2.3.11 or later)
+- **Light CLI**: Install with `npm install -g @lightprotocol/zk-compression-cli`
+
+### ZK circuit tools
+
+- **Circom** (v2.2.2): Zero-knowledge circuit compiler
+- **SnarkJS**: JavaScript library for generating and verifying ZK proofs
+
+To install circom and snarkjs:
+
+```bash
+# Install circom (Linux/macOS)
+wget https://github.com/iden3/circom/releases/download/v2.2.2/circom-linux-amd64
+chmod +x circom-linux-amd64
+sudo mv circom-linux-amd64 /usr/local/bin/circom
+
+# For macOS, replace with circom-macos-amd64
+
+# Install snarkjs globally
+npm install -g snarkjs
+```
+
 ## Flow
 
 1. Client computes nullifiers from secrets
 2. Client generates Groth16 proof
 3. On-chain: verify proof, derive addresses, create accounts
 4. If any address exists, tx fails
 
-## Instructions
+## Program instructions
+
+### 1. `create_nullifier`
+
+Creates a single nullifier account using a ZK proof. The nullifier is derived from `Poseidon(verification_id, secret)` where only the prover knows the secret.
+
+**Properties:**
+
+- The secret stays private
+- The nullifier is deterministic from the secret and verification_id
+- If the nullifier address already exists, the transaction fails
+
+### 2. `create_batch_nullifier`
+
+Creates four nullifier accounts with a single ZK proof. Each nullifier is derived from the same `verification_id` but different secrets.
 
-| Instruction | Nullifiers | Description |
-|-------------|-----------|-------------|
-| `create_nullifier` | 1 | Single nullifier with ZK proof |
-| `create_batch_nullifier` | 4 | Batch of 4 with single proof |
+**Properties:**
 
-## Compute Units
+- All four secrets stay private
+- Single proof verification is ~2.7x more efficient per nullifier than four separate proofs
+- If any nullifier address already exists, the entire transaction fails
+
+## Compute units
 
 | Method | Nullifiers | CU | CU per nullifier |
 |--------|-----------|-------------|------------------|
@@ -38,39 +81,82 @@ Nullifier accounts must remain active, hence lock ~0.001 SOL in rent per nullifi
 
 *Estimated. Batch is ~2.7x more efficient per nullifier.
 
-## Setup
+## Circuits
 
-```bash
-./scripts/setup.sh     
-cargo build-sbf        
-```
+### Single nullifier (`nullifier.circom`)
 
-## Testing
+**Public inputs:**
 
-**Rust tests**:
-```bash
-cargo test-sbf
-```
+- `verification_id` - Context identifier (vote ID, airdrop ID, etc.)
+- `nullifier` - The nullifier hash
 
-**TypeScript tests**
-```bash
-npm install
-npm test
-```
+**Private inputs:**
 
-## Circuits
+- `secret` - Only the owner knows this value
+
+**Constraint:**
 
-**Single** (`nullifier.circom`):
 ```circom
 nullifier === Poseidon(verification_id, secret)
 ```
 
-**Batch** (`batch_nullifier.circom`):
+### Batch nullifier (`batchnullifier.circom`)
+
+**Public inputs:**
+
+- `verification_id` - Shared context for all nullifiers
+- `nullifier[4]` - Array of 4 nullifier hashes
+
+**Private inputs:**
+
+- `secret[4]` - Array of 4 secrets
+
+**Constraint:**
+
 ```circom
 for i in 0..4:
     nullifier[i] === Poseidon(verification_id, secret[i])
 ```
 
+## Setup
+
+```bash
+./scripts/setup.sh
+```
+
+This script will:
+
+1. Check dependencies (Node.js, circom)
+2. Install npm dependencies
+3. Create build directories
+4. Download the Powers of Tau ceremony file (14 powers)
+5. Compile single nullifier circuit
+6. Generate single nullifier proving key
+7. Compile batch nullifier circuit
+8. Generate batch nullifier proving key
+9. Clean intermediate files
+
+## Build and test
+
+**Build:**
+
+```bash
+cargo build-sbf
+```
+
+**Rust tests:**
+
+```bash
+cargo test-sbf
+```
+
+**TypeScript tests:**
+
+```bash
+npm install
+npm test
+```
+
 ## Structure
 
 ```
@@ -84,3 +170,11 @@ zk-nullifier/
 │   └── zk-nullifier.ts         # TypeScript tests
 └── scripts/setup.sh
 ```
+
+## Cleaning build artifacts
+
+To clean generated circuit files:
+
+```bash
+./scripts/clean.sh
+```
