Overview

Relevant source files

• .gitignore
• Cargo.lock
• Cargo.toml
• README.md
• SECURITY.md
• program-libs/token-interface/Cargo.toml
• 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

Purpose and Scope

This document provides a high-level introduction to the Light Protocol codebase, explaining its architecture, core components, and how they interact to implement zero-knowledge compression on Solana. Light Protocol enables developers to create rent-free accounts and tokens by storing account state in compressed form using Merkle trees and zero-knowledge proofs.

For detailed information about specific subsystems, see:

• On-chain program implementation: On-Chain Programs
• Foundational data structures and cryptography: Program Libraries
• Client-side integration: Client Libraries and SDKs
• Off-chain services (Photon, Prover, Forester): Off-Chain Infrastructure
• Merkle tree system details: Merkle Tree System

Sources: README.md1-15 Cargo.toml1-96

---

What is Light Protocol

Light Protocol is a ZK compression layer that reduces storage costs on Solana by up to 5,000x while maintaining security, composability, and performance. Instead of storing full account data on-chain, Light Protocol stores a commitment (hash) of the account in a Merkle tree. The actual account data lives off-chain in an indexer, and zero-knowledge proofs verify state transitions without exposing the full state.

The protocol consists of four deployed Solana programs with their program IDs:

• account-compression (compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq) - Manages Merkle trees and state commitments
• light-system-program (SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7) - Handles compressed account lifecycle
• light-compressed-token (cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m) - Implements compressed SPL tokens
• light-registry (Lighton6oQpVkeewmo2mcPTQQp7kYHr4fWpAgJyEmDX) - Manages program registration and forester coordination

Sources: README.md10-15 README.md47-63

---

Core Concepts

Compressed Accounts

A compressed account is represented by the CompressedAccount type defined in the light-compressed-account crate. Instead of storing the full account data on-chain, only its hash is inserted into a Merkle tree. The CompressedAccount contains:

• owner: The program that owns this account
• lamports: SOL balance
• address: Optional deterministic address
• data: Optional serialized account data

The compressed account's hash becomes a leaf in a state Merkle tree managed by the account-compression program.

Sources: Cargo.toml216 [program-libs/compressed-account directory]

State Trees and Address Trees

Light Protocol uses two types of Merkle trees:

• State Merkle Trees (StateMerkleTreeAccount): Store hashes of compressed accounts. Implemented using ConcurrentMerkleTree (V1) or BatchedMerkleTree (V2).
• Address Merkle Trees (AddressMerkleTreeAccount): Store indexed addresses for deterministic account derivation. Implemented using IndexedMerkleTree (V1) or batched variants (V2).

Trees are managed through accounts in the account-compression program and have associated metadata in MerkleTreeMetadata.

Sources: [program-libs/concurrent-merkle-tree directory], [program-libs/indexed-merkle-tree directory], [program-libs/batched-merkle-tree directory]

Zero-Knowledge Proofs

State transitions (creating, updating, nullifying compressed accounts) require ZK proofs to verify:

1. The old account state exists in the Merkle tree
2. The new state is correctly computed
3. Merkle tree updates are valid

Proofs are generated off-chain by the Light Prover service using Groth16 circuits implemented in gnark. The light-verifier library verifies proofs on-chain in Solana programs.

Sources: [program-libs/verifier directory], prover/client/Cargo.toml1-8

---

System Architecture

High-level architecture showing major system components and their relationships

Sources: Cargo.toml1-296 README.md1-206

---

Workspace Structure

The Light Protocol repository is organized as a Rust and JavaScript monorepo with the following top-level structure:

Rust Workspace

The workspace is defined in Cargo.toml1-296 with these member categories:

On-Chain Programs (programs/ and anchor-programs/):

• account-compression - Merkle tree management
• system - Compressed account state transitions
• compressed-token/program - Compressed token implementation
• registry - Program and forester registration

Program Libraries (program-libs/):

• compressed-account - Core CompressedAccount type
• hasher - Hasher trait and implementations (Poseidon, Keccak, SHA256)
• verifier - On-chain ZK proof verification
• concurrent-merkle-tree, indexed-merkle-tree, batched-merkle-tree - Tree implementations
• zero-copy - Zero-copy deserialization utilities
• merkle-tree-metadata - Tree configuration and lifecycle

SDK Libraries (sdk-libs/):

• client - LightClient RPC interface
• sdk - High-level SDK for building programs with light-sdk
• sdk-pinocchio - Pinocchio-compatible SDK
• token-sdk - Token operations with light-token
• program-test - LightProgramTest testing framework
• photon-api - Client for Photon indexer

Off-Chain Services:

• forester - Automated tree management service
• prover/client - light-prover-client for proof generation

Sources: Cargo.toml1-82

JavaScript Workspace

The JavaScript ecosystem lives in the js/ directory as a pnpm monorepo:

• @lightprotocol/stateless.js - Core TypeScript SDK
• @lightprotocol/compressed-token - Token SDK
• @lightprotocol/zk-compression-cli - Command-line tools

Sources: README.md195-202

---

Component Interaction: Transaction Flow

Transaction flow showing interaction between client, off-chain services, and on-chain programs

Sources: [sdk-libs/client directory], [programs/system directory], [programs/account-compression directory]

---

Key Code Entities and Their Roles

On-Chain Program Instructions

The account-compression program defines instructions in programs/account-compression/src/lib.rs:

• initialize_address_merkle_tree - Creates a new address tree
• initialize_state_merkle_tree - Creates a new state tree
• append_leaves - Adds leaves to a state tree
• nullify_leaves - Marks leaves as spent
• update_address_merkle_tree - Updates address tree with new addresses

The light-system-program (Anchor) defines instructions in anchor-programs/system/src/lib.rs:

• invoke - Processes compressed account state transitions with ZK proofs
• invoke_cpi - Handles cross-program invocations with compressed accounts

Sources: [programs/account-compression directory], [anchor-programs/system directory]

Core Data Types

CompressedAccount ([program-libs/compressed-account directory]):

InstructionDataInvoke ([sdk-libs/sdk-types directory]): Contains the data passed to light-system-program::invoke:

• proof: Compressed ZK proof
• input_compressed_accounts_with_merkle_context: Accounts being read/nullified
• output_compressed_accounts: New accounts being created
• relay_fee: Optional fee for transaction relaying

MerkleTreeMetadata ([program-libs/merkle-tree-metadata directory]): Tracks tree configuration and rollover state:

• next_merkle_tree: Pubkey of next tree in rollover chain
• rollover_metadata: Configuration for automatic rollover

Sources: [program-libs/compressed-account directory], [sdk-libs/sdk-types directory], [program-libs/merkle-tree-metadata directory]

Client Library Entry Points

LightClient (sdk-libs/client/src/rpc/rpc_connection.rs):

• new() - Creates client with RPC and indexer endpoints
• create_and_send_transaction() - Builds and sends compressed account transactions
• get_compressed_accounts_by_owner() - Queries accounts via indexer

LightProgramTest (sdk-libs/program-test/src/lib.rs):

• new() - Starts local test validator with mock indexer
• process_transaction() - Processes test transactions
• get_compressed_accounts() - Queries mock indexer state

Sources: sdk-libs/client/Cargo.toml1-81 sdk-libs/program-test/Cargo.toml1-72

---

Development and Testing

Local Testing Environment

The light-program-test crate provides LightProgramTest for local development:

Local testing infrastructure components

The test framework:

1. Spins up litesvm as an in-memory Solana validator
2. Starts TestRpc as a mock Photon indexer
3. Configures light-prover-client to generate proofs locally
4. Deploys all Light Protocol programs

Sources: [sdk-libs/program-test directory], README.md176-191

Build and Test Commands

The repository provides shell scripts for development:

• ./scripts/install.sh - Installs dependencies to .local/ directory
• ./scripts/devenv.sh - Activates development environment
• ./scripts/build.sh - Builds all Rust and JavaScript code
• ./scripts/test.sh - Runs full test suite

Program tests use cargo test-sbf:

Sources: README.md95-191

---

Off-Chain Infrastructure

Photon Indexer

The Photon indexer (maintained by Helius) tracks compressed account state by:

1. Subscribing to Solana account updates via Geyser plugin
2. Decoding events from account-compression and light-system-program
3. Storing compressed account data in a queryable database
4. Providing RPC endpoints for account queries

Client code interacts with Photon through the photon-api crate, which provides a generated client from the OpenAPI spec.

Sources: sdk-libs/photon-api/Cargo.toml1-35 README.md17

Light Prover Service

The Light Prover generates zero-knowledge proofs using gnark circuits. The light-prover-client crate provides:

• prove_inclusion() - Generates inclusion proofs for compressed accounts
• prove_batch() - Generates batch proofs for multiple operations
• Circuit endpoints for different tree configurations

Proofs use the Groth16 proving system with BN254 curve.

Sources: prover/client/Cargo.toml1-45

Forester Service

The Forester automates V2 batched tree operations:

1. Registers for epochs via light-registry
2. Monitors QueueAccount for pending operations
3. Batches operations and generates proofs
4. Submits batched transactions during active epochs
5. Reports work completed for reward claims

Sources: [forester directory], Cargo.toml78-79

---

Security and Audits

Light Protocol has undergone multiple security audits:

• OtterSec (Programs audit #1)
• Neodyme (Programs audit #2)
• Zellic (Programs audit #3)
• Reilabs (Circuits formal verification)

Audit reports are available in the audits/ directory. Programs are deployed with verifiable builds that can be checked using solana-verify.

Sources: README.md65-74 SECURITY.md1-13

---

Version and Feature Flags

The codebase supports multiple feature configurations:

V1 vs V2 Trees:

• V1: ConcurrentMerkleTree and IndexedMerkleTree for individual operations
• V2: BatchedMerkleTree for batched operations (default with v2 feature)

Hash Functions:

• poseidon - Poseidon hash (default, ZK-friendly)
• keccak - Keccak256
• sha256 - SHA256

Framework Support:

• anchor - Anchor framework compatibility
• idl-build - IDL generation for client tooling

Most crates default to v2 and poseidon features for production use.

Sources: sdk-libs/sdk/Cargo.toml13-40 sdk-libs/client/Cargo.toml9-14