Overview

Relevant source files

• Cargo.lock
• Cargo.toml
• README.md
• SECURITY.md
• package.json
• pnpm-lock.yaml
• prover/client/Cargo.toml
• sdk-libs/client/Cargo.toml
• sdk-libs/event/Cargo.toml
• sdk-libs/macros/Cargo.toml
• sdk-libs/photon-api/Cargo.toml
• sdk-libs/program-test/Cargo.toml
• sdk-libs/sdk-pinocchio/Cargo.toml
• sdk-libs/sdk-types/Cargo.toml
• sdk-libs/sdk/Cargo.toml
• sdk-libs/token-sdk/Cargo.toml
• sdk-libs/token-types/Cargo.toml
• xtask/Cargo.toml
• xtask/src/fetch_keypair_txs.rs
• xtask/src/main.rs

This document provides a high-level introduction to the Light Protocol repository, explaining its purpose as a ZK Compression system for Solana and presenting the major components that comprise the protocol. For detailed information about specific subsystems, refer to the respective sections of this wiki.

Purpose: Light Protocol enables developers to create rent-free tokens and Program Derived Accounts (PDAs) on Solana using zero-knowledge compression technology README.md10-13 The protocol achieves this by storing account state in Merkle trees and proving state transitions using ZK proofs, reducing on-chain storage costs while maintaining performance and composability README.md27-30

Scope: This overview covers the repository structure, core architectural components, and their interactions. For detailed implementation information, see:

• On-chain program details: On-Chain Programs
• Off-chain service architecture: Off-Chain Infrastructure
• SDK usage patterns: Client Libraries and SDKs
• Development environment setup: Development Environment

What is ZK Compression?

ZK Compression is a state compression mechanism that stores account data in on-chain Merkle trees rather than individual accounts. Account state is represented as leaves in these trees, and state transitions are validated using zero-knowledge proofs. This approach provides:

• Cost Efficiency: Accounts stored in Merkle trees require minimal rent (only for the tree structure itself).
• Performance: Batch operations allow multiple state updates in a single transaction.
• Composability: Compressed accounts can interact with regular Solana programs via Cross-Program Invocation (CPI).
• Security: Zero-knowledge proofs ensure state transitions are valid without revealing the entire state.

The protocol has been audited by OtterSec, Neodyme, and Zellic, with circuits formally verified by Reilabs README.md65-72

Sources: README.md10-72

Repository Structure

The Light Protocol repository is organized as a multi-language monorepo containing Rust and JavaScript/TypeScript components:

Directory Layout:

• programs/: On-chain Solana programs Cargo.toml22-25
• program-libs/: Shared Rust libraries used by on-chain programs Cargo.toml5-21
• sdk-libs/: Off-chain Rust SDKs for building applications Cargo.toml27-42
• program-tests/ and sdk-tests/: Comprehensive test suites Cargo.toml44-77
• forester/: Off-chain service for Merkle tree maintenance Cargo.toml79
• js/: JavaScript/TypeScript SDKs pnpm-lock.yaml178-234
• cli/: Command-line interface for development workflows pnpm-lock.yaml30-103
• xtask/: Development utilities (tree creation, benchmarking, deployment) xtask/src/main.rs1-152
• external/photon/: Git submodule for the Photon indexer Cargo.toml2

For details, see Repository Structure.

Sources: Cargo.toml1-81 pnpm-lock.yaml1-234 README.md17-24

Core System Architecture

The following diagram bridges high-level operations with specific code entities:

Key Interaction Patterns:

1. Account State Queries: Applications query the Photon indexer (via photon-api client) to retrieve compressed account data and Merkle proofs needed for state transitions sdk-libs/client/Cargo.toml58
2. Proof Generation: The Light Prover service generates zero-knowledge proofs that validate state transitions. Applications interact via light-prover-client sdk-libs/client/Cargo.toml59
3. State Updates: Transactions containing ZK proofs are submitted to Solana. The account-compression program verifies proofs and queues state updates Cargo.toml22
4. Batch Processing: The forester service monitors queues, generates batch proofs, and submits them to finalize tree updates Cargo.toml79

For details, see System Architecture.

Sources: sdk-libs/client/Cargo.toml1-81 Cargo.toml1-81 README.md17-18

On-Chain Programs

Light Protocol consists of four core Solana programs:

Program	Crate Name	Purpose
account-compression	account-compression	Merkle tree operations, batch processing, ZKP verification Cargo.toml22
light-registry	light-registry	Forester coordination, epoch management, protocol config Cargo.toml25
light-system-program	light-system-program	ZK compression core, CPI framework Cargo.toml23
light-compressed-token	light-compressed-token	Compressed SPL token operations Cargo.toml24

Program Locations:

• Account Compression: programs/account-compression/
• Light Registry: programs/registry/
• Light System Program: programs/system/
• Compressed Token: programs/compressed-token/program/

Deployment Verification: The programs use verifiable builds README.md32-43 See README.md45-63 for verification instructions using solana-verify.

Sources: Cargo.toml22-25 README.md32-63

SDK and Client Libraries

Light Protocol provides SDKs for building compressed account applications:

Rust SDKs:

• light-client (sdk-libs/client/): High-level client for interacting with compressed accounts and building transactions sdk-libs/client/Cargo.toml2-7
• light-sdk (sdk-libs/sdk/): Core SDK for programs using compressed state sdk-libs/sdk/Cargo.toml2-4
• light-token-sdk (sdk-libs/token-sdk/): SDK for compressed token operations Cargo.toml28
• light-program-test (sdk-libs/program-test/): Fast local testing environment using litesvm sdk-libs/program-test/Cargo.toml2-34

JavaScript/TypeScript SDKs:

• @lightprotocol/stateless.js: Core RPC interface for compressed accounts pnpm-lock.yaml41-43
• @lightprotocol/compressed-token: Token-specific operations pnpm-lock.yaml35-37
• cli: Command-line interface for development workflows pnpm-lock.yaml30-31

Sources: sdk-libs/client/Cargo.toml1-81 sdk-libs/sdk/Cargo.toml1-87 sdk-libs/program-test/Cargo.toml1-72 pnpm-lock.yaml30-185

Merkle Tree System

The protocol supports multiple Merkle tree implementations optimized for different use cases:

Implementations:

• V1 Concurrent: program-libs/concurrent-merkle-tree/ Cargo.toml17
• V1 Indexed: program-libs/indexed-merkle-tree/ Cargo.toml19
• V2 Batched: program-libs/batched-merkle-tree/ Cargo.toml9
• Sparse: sparse-merkle-tree/ Cargo.toml80

Sources: Cargo.toml5-21 Cargo.toml80

Development Workflow

Environment Setup:

1. Run scripts/install.sh to install dependencies and gnark keys README.md104-113
2. Activate environment with scripts/devenv.sh README.md118-119
3. Generate keypair: solana-keygen new -o ~/.config/solana/id.json README.md171

The xtask Utility: The xtask crate provides critical development commands xtask/src/main.rs41-105:

• GenerateVkeyRs: Generates verification keys from gnark keys xtask/src/main.rs49-50
• CreateStateTree: Initializes on-chain state trees xtask/src/main.rs57-60
• CreateCtokenAccount: Creates compressed token accounts xtask/src/main.rs97-100
• Bench: Generates compute unit and heap usage reports xtask/src/main.rs51-52

Sources: README.md76-180 xtask/src/main.rs1-152

Next Steps

For deeper understanding of specific subsystems:

• System Architecture: See System Architecture for component interaction details.
• Repository Structure: See Repository Structure for workspace organization.
• On-Chain Programs: See On-Chain Programs for program logic.
• Off-Chain Services: See Off-Chain Infrastructure for indexer and prover details.

Sources: Wiki table of contents structure