Skip to content

Commit 705e8ff

Browse files
ananas-blockananas-block
committed
docs: add comprehensive CLAUDE.md AI assistant reference guide
- Repository overview with core technologies and architecture - Complete directory structure with component purposes - Component relationship diagram and data flow - Development workflow with build, test, and code generation commands - AI assistant guidelines with code patterns and navigation - Key files for understanding subsystems and debugging - Quick reference for frequently modified files and configuration - Links to detailed component documentation Provides AI assistants with essential context about Light Protocol codebase structure, enabling efficient navigation and development assistance across the ZK compression protocol implementation.
1 parent b3f0947 commit 705e8ff

File tree

1 file changed

+162
-0
lines changed

1 file changed

+162
-0
lines changed

‎CLAUDE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Light Protocol - AI Assistant Reference Guide
2+
3+
## Repository Overview
4+
5+
Light Protocol is the ZK Compression Protocol for Solana, enabling developers to create rent-free tokens and PDAs without sacrificing performance, security, or composability. The protocol uses zero-knowledge proofs to compress account state into Merkle trees, reducing storage costs while maintaining full Solana compatibility.
6+
7+
**Core Technologies:** Rust, Solana, ZK circuits (Gnark), Poseidon hashing, batched Merkle trees
8+
**Architecture:** On-chain programs + off-chain ZK provers + client SDKs + forester service
9+
10+
## Directory Structure
11+
12+
```
13+
light-protocol/
14+
├── program-libs/ # Core Rust libraries (shared business logic)
15+
│ ├── batched-merkle-tree/ # Batched Merkle tree implementation with ZKP verification
16+
│ ├── account-checks/ # Unified account validation (solana-program + pinocchio)
17+
│ ├── compressed-account/ # Compressed account types and utilities
18+
│ ├── compressible/ # Configuration for compressible token accounts
19+
│ ├── hasher/ # Poseidon hash implementation
20+
│ ├── verifier/ # ZKP verification logic
21+
│ ├── zero-copy/ # Zero-copy serialization for efficient account access
22+
│ ├── bloom-filter/ # Bloom filters for non-inclusion proofs
23+
│ ├── concurrent-merkle-tree/ # Concurrent Merkle tree operations
24+
│ ├── indexed-merkle-tree/ # Indexed Merkle tree with address management
25+
│ └── [other utility libs]/ # Additional supporting libraries
26+
├── programs/ # Solana on-chain programs
27+
│ ├── account-compression/ # Core compression program (Merkle tree management)
28+
│ ├── system/ # Light system program (compressed account operations)
29+
│ ├── compressed-token/ # Compressed SPL token implementation
30+
│ └── registry/ # Protocol configuration and forester registration
31+
├── sdk-libs/ # Client-side libraries
32+
│ ├── client/ # RPC client for querying compressed accounts
33+
│ ├── sdk/ # Core SDK for Rust/Anchor programs
34+
│ ├── sdk-pinocchio/ # Pinocchio-specific SDK implementation
35+
│ ├── compressed-token-sdk/ # Compressed token client utilities
36+
│ └── program-test/ # Fast local test environment (LiteSVM)
37+
├── prover/ # ZK proof generation
38+
│ ├── server/ # Go-based prover server (Gnark circuits)
39+
│ └── client/ # Rust client for requesting proofs
40+
├── forester/ # Off-chain service for tree maintenance
41+
├── cli/ # Light CLI tool (@lightprotocol/zk-compression-cli)
42+
├── js/ # JavaScript/TypeScript libraries
43+
├── program-tests/ # Integration tests and test programs
44+
├── sdk-tests/ # SDK integration tests
45+
└── scripts/ # Build, test, and deployment scripts
46+
```
47+
48+
## Component Relationships
49+
50+
```
51+
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
52+
│ Client Apps │───▶│ SDK Libraries │───▶│ On-chain Progs │
53+
└─────────────────┘ └──────────────────┘ └─────────────────┘
54+
│ │
55+
▼ ▼
56+
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
57+
│ Light CLI Tool │ │ Program Libs │ │ Forester │
58+
└─────────────────┘ └──────────────────┘ └─────────────────┘
59+
│ │
60+
▼ ▼
61+
┌──────────────────┐ ┌─────────────────┐
62+
│ ZK Prover │ │ Merkle Trees │
63+
└──────────────────┘ └─────────────────┘
64+
```
65+
66+
**Data Flow:**
67+
1. **Client** creates compressed accounts via SDK
68+
2. **SDK** builds instructions using program-libs
69+
3. **On-chain programs** validate and queue operations
70+
4. **Forester** triggers batch updates with ZK proofs
71+
5. **Prover** generates proofs for Merkle tree operations
72+
6. **Trees** store compressed state as hashes
73+
74+
## Development Workflow
75+
76+
### Build Commands
77+
```bash
78+
# Install all dependencies and tools
79+
./scripts/install.sh
80+
81+
# Build entire monorepo (uses Nx)
82+
./scripts/build.sh
83+
# OR: npx nx run-many --target=build --all
84+
85+
# Build specific components
86+
npx nx build @lightprotocol/programs # Solana programs
87+
npx nx build @lightprotocol/zk-compression-cli # CLI tool
88+
cargo build # Rust workspace
89+
```
90+
91+
### Testing Patterns
92+
```bash
93+
# Run all tests
94+
./scripts/test.sh
95+
# OR: npx nx run-many --target=test --all
96+
97+
# Unit tests (Rust)
98+
cargo test -p light-batched-merkle-tree
99+
cargo test -p light-account-checks
100+
101+
# Integration tests
102+
cargo test -p program-tests
103+
cargo test -p sdk-tests
104+
105+
# Local test validator
106+
light test-validator # Start Light test validator
107+
```
108+
109+
## AI Assistant Guidelines
110+
111+
### Code Patterns & Conventions
112+
- **Error Handling:** Use `thiserror` for custom errors, map to `ProgramError` for Solana
113+
- **Serialization:** Prefer `light-zero-copy` for account data, `borsh` for instruction data
114+
- **Account Validation:** Use `light-account-checks` for unified validation across SDKs
115+
- **Naming:** `BatchedMerkleTreeAccount`, `CompressedAccount`, `ValidityProof` patterns
116+
- **Features:** Use feature flags (`anchor`, `pinocchio`, `test-only`) for conditional compilation
117+
118+
### Navigation Patterns
119+
- **Program → Lib:** `programs/account-compression/src/` → `program-libs/batched-merkle-tree/src/`
120+
- **SDK → Program:** `sdk-libs/sdk/src/` → `programs/system/src/`
121+
- **Client → RPC:** `sdk-libs/client/src/` → Photon indexer API
122+
- **Test → Implementation:** `program-tests/` → corresponding `programs/` or `program-libs/`
123+
124+
### Key Files for Understanding Subsystems
125+
- **Compressed Accounts:** `program-libs/compressed-account/src/compressed_account.rs`
126+
- **Merkle Trees:** `program-libs/batched-merkle-tree/src/merkle_tree.rs`
127+
- **ZK Verification:** `program-libs/verifier/src/lib.rs`
128+
- **System Program:** `programs/system/src/lib.rs`
129+
- **SDK Core:** `sdk-libs/sdk/src/lib.rs`
130+
- **Client RPC:** `sdk-libs/client/src/rpc/mod.rs`
131+
132+
### Common Debugging Entry Points
133+
- **Errors:** `programs/*/src/errors.rs` and `program-libs/*/src/errors.rs`
134+
- **ZK Proof Failures:** `prover/server/` logs and `light-verifier` errors
135+
- **RPC Issues:** `sdk-libs/client/src/indexer/` and Photon indexer logs
136+
137+
### Important Constants & Configuration
138+
- **Program IDs:** Defined in each program's `lib.rs`
139+
- **Tree Configuration:** `program-libs/batched-merkle-tree/src/constants.rs`
140+
- **Error Codes:** Each crate defines ranges (e.g., 14301-14312 for batched-merkle-tree)
141+
- **Default Configs:** `program-libs/*/src/constants.rs` files
142+
143+
## Quick Reference
144+
145+
### Most Frequently Modified Files
146+
- `programs/system/src/invoke/` - Core compressed account operations
147+
- `program-libs/batched-merkle-tree/src/merkle_tree.rs` - Tree update logic
148+
- `sdk-libs/sdk/src/instruction/` - Instruction builders
149+
- `programs/account-compression/src/processor/` - Batch processing logic
150+
151+
### Key Configuration Files
152+
- `Cargo.toml` - Workspace dependencies and versions
153+
- `nx.json` - Build system configuration (Nx monorepo)
154+
- `rust-toolchain.toml` - Rust version specification
155+
156+
### Testing & Documentation
157+
- **Unit Tests:** `cargo test -p <crate-name>`
158+
- **Integration:** `program-tests/` and `sdk-tests/` directories
159+
- **Local Validator:** `light test-validator` (CLI provides all programs)
160+
- **Fast Testing:** `light-program-test` uses LiteSVM
161+
162+
**Detailed docs:** See `CLAUDE.md` files in `program-libs/*/docs/` and `programs/*/`

0 commit comments

Comments
 (0)