Overview

Relevant source files

• Cargo.lock
• Cargo.toml
• README.md
• SECURITY.md
• 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/close_buffer.rs
• xtask/src/create_ctoken_account.rs
• xtask/src/fetch_accounts.rs
• xtask/src/fetch_failed_txs.rs
• xtask/src/main.rs
• xtask/src/print_state_tree.rs
• xtask/src/reinit_cpi_accounts.rs

Light Protocol is a ZK Compression protocol for Solana that enables developers to create compressed accounts and tokens that are nearly rent-free. This repository contains the on-chain programs, off-chain infrastructure services, client SDKs, and cryptographic libraries that comprise the protocol.

Purpose of This Document

This overview introduces Light Protocol's architecture and codebase organization. It explains the role of each system component, how they interact, and where to find detailed documentation for each subsystem.

For deeper technical details, see:

• On-chain program internals: On-Chain Programs
• Off-chain infrastructure: Off-Chain Infrastructure
• Client SDKs: Client Libraries and SDKs
• Merkle tree implementations: Merkle Tree System
• Advanced topics: Advanced Topics

---

What is ZK Compression?

Light Protocol compresses Solana account state by storing data as leaves in on-chain Merkle trees rather than as individual accounts. Instead of paying rent for full account data, only a 32-byte Merkle root is stored on-chain. Account state is reconstructed using Merkle proofs and verified through zero-knowledge proofs.

Compression Mechanism

Traditional Solana accounts store data directly on-chain:

Account = {
  lamports: u64,
  data: Vec<u8>,      // Full data stored on-chain
  owner: Pubkey,
  executable: bool
}

Compressed accounts store only a hash in a Merkle tree:

CompressedAccount = {
  owner: Pubkey,
  lamports: u64,
  address: Option<[u8; 32]>,
  data: CompressedAccountData    // Stored off-chain
}

On-chain storage = Merkle root (32 bytes) + metadata

The compression ratio depends on account size but typically reduces storage costs by 100-1000x.

Key Properties

• Cost Reduction: Eliminates rent for account data storage
• Proof-Based Verification: State transitions validated via Groth16 ZK proofs generated by light-prover
• Composability: Standard Solana programs interact with compressed state through CPI
• Security: Circuits formally verified by Reilabs; programs audited by OtterSec, Neodyme, and Zellic

Deployed Program IDs

Program	Program ID	Crate Path
Light Registry	Lighton6oQpVkeewmo2mcPTQQp7kYHr4fWpAgJyEmDX	programs/registry
Account Compression	compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq	programs/account-compression
Light System Program	SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7	programs/system
Compressed Token	cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m	programs/compressed-token/program

Sources: README.md1-15 README.md47-63 Cargo.toml225-243

---

System Architecture

Light Protocol consists of four layers: client SDKs, off-chain infrastructure services, on-chain Solana programs, and shared cryptographic libraries. These components coordinate to provide ZK-compressed state management.

Architecture Diagram

Component Responsibilities

Layer	Component	Location	Responsibility
Client	light-sdk	sdk-libs/sdk	Compressed account instructions, Anchor integration
	light-client	sdk-libs/client	RPC client with retry logic, transaction submission
	light-token	sdk-libs/token-sdk	Token operations (mint, transfer, burn)
	stateless.js	js/stateless.js/	TypeScript SDK for compressed accounts
	compressed-token	js/compressed-token/	TypeScript token client
Infrastructure	light-prover	prover	ZK proof generation using gnark circuits
	photon	external/photon	Compressed account indexing and Merkle proof API
	forester	forester	Automated tree maintenance and epoch management
On-Chain	light-registry	programs/registry	Protocol configuration, forester registration
	account-compression	programs/account-compression	Merkle tree operations, nullifier management
	light-system-program	programs/system	Compressed account lifecycle, proof verification
	light-compressed-token	programs/compressed-token/program	Compressed SPL tokens and Token-2022
Crypto	light-hasher	program-libs/hasher	Generic hash trait with multiple implementations
	Merkle trees	program-libs/	Three tree implementations (V1 concurrent/indexed, V2 batched)
	light-verifier	program-libs/verifier	On-chain Groth16 verification

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

---

Core Concepts

Compressed Account Structure

A compressed account is represented by the CompressedAccount struct defined in program-libs/compressed-account:

CompressedAccount {
  owner: Pubkey,              // Program that owns this account
  lamports: u64,              // SOL balance
  address: Option<[u8; 32]>,  // Optional deterministic address
  data: CompressedAccountData // Account data (can be hash or full data)
}

On-chain storage stores only:

• Merkle tree root (32 bytes) in BatchedMerkleTreeAccount or ConcurrentMerkleTreeZeroCopy
• Nullifier queue in BatchedQueueAccount (for spent accounts)
• Tree metadata in MerkleTreeMetadata

Account data is provided by:

• Photon Indexer: Queries via photon-api crate returning GetCompressedAccountsByOwnerResponse
• Client: Cached locally or computed from transaction history
• RPC: Direct on-chain tree queries via light-client::Rpc trait

State Transition Flow

Compressed account modifications follow this sequence:

State Transition Sequence

Key Functions:

1. light-client::rpc::Rpc::get_compressed_accounts_by_owner() - Fetch state from Photon
2. light-prover-client::inclusion_proof() - Generate ZK proof
3. light-sdk::compressed_account::create_pda_instruction() - Build instruction
4. light-verifier::verify_groth16() - On-chain verification
5. account-compression::append_leaves_to_merkle_trees() - Update tree state

Sources: sdk-libs/client/Cargo.toml16-81 prover/client/Cargo.toml1-44 sdk-libs/sdk/Cargo.toml1-87

---

On-Chain Programs

Light Protocol deploys four Solana programs that coordinate compressed state management. Each program has a specific responsibility in the protocol architecture.

Program Overview

Program	ID / Crate Path	Entrypoint	Primary Instructions
Light Registry	Lighton6oQpVkeewmo2mcPTQQp7kYHr4fWpAgJyEmDX programs/registry	light_registry::entry	initialize_protocol_config, register_forester, initialize_merkle_tree
Account Compression	compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq programs/account-compression	account_compression::entry	append_leaves, nullify_leaves, update_address_merkle_tree
Light System Program	SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7 programs/system	light_system_program::entry	invoke, invoke_cpi (with ZK proof verification)
Light System (Anchor)	Same ID anchor-programs/system	anchor_lang::entry	Anchor-compatible variant for easier integration
Compressed Token	cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m programs/compressed-token/program	anchor_compressed_token::entry	create_token_pool, mint_to, transfer, burn

Cross-Program Invocation Architecture

CPI Flow Diagram

Key CPI Patterns:

• light-compressed-token invokes light-system-program::invoke_cpi() to compress/decompress token state
• light-system-program invokes account-compression::append_leaves_to_merkle_trees() to add new compressed accounts
• light-system-program invokes account-compression::nullify_leaves() to mark accounts as spent
• light-registry has exclusive authority to initialize new trees via account-compression::initialize_batched_state_merkle_tree()

Shared Program Libraries

All programs depend on cryptographic libraries in program-libs/:

Library	Crate Path	Usage
light-hasher	program-libs/hasher	Generic Hasher trait with Poseidon, Keccak256, SHA256 implementations
light-concurrent-merkle-tree	program-libs/concurrent-merkle-tree	V1 Merkle tree with concurrent updates via changelog
light-indexed-merkle-tree	program-libs/indexed-merkle-tree	V1 address tree with indexed leaf lookups
light-batched-merkle-tree	program-libs/batched-merkle-tree	V2 tree with batched operations and ZK proof requirements
light-verifier	program-libs/verifier	On-chain Groth16 proof verification
light-compressed-account	program-libs/compressed-account	CompressedAccount struct and serialization

For detailed program internals, see On-Chain Programs.

Sources: Cargo.toml225-243 README.md47-63 Cargo.toml199-223

---

Off-Chain Infrastructure

Photon Indexer

Maintained by: Helius Labs
Repository: https://github.com/helius-labs/photon
Purpose: Indexes all compressed state by parsing Solana transactions

The indexer provides:

• Fast queries for compressed accounts
• Merkle proofs for state transitions
• Historical state tracking
• RESTful API with OpenAPI specification

Client integration via photon-api crate which provides type-safe bindings.

Light Prover

Language: Go
Location: prover/ directory
Purpose: ZK proof generation as a service

The prover service:

• Implements gnark circuits for state transitions
• Provides HTTP/gRPC endpoints for proof requests
• Uses Redis for job queueing and priority handling
• Supports multiple circuit types (inclusion, non-inclusion, combined)

Forester Service

Language: Rust
Location: forester/ directory
Purpose: Automated tree maintenance and rollover

The forester:

• Processes queued operations in batches
• Handles tree rollover when trees reach capacity
• Operates on an epoch-based registration model
• Monitors tree health and reports metrics

For detailed service architecture, see Off-Chain Infrastructure.

Sources: README.md17 prover/client/Cargo.toml1-44 Cargo.toml78-79

---

Client Libraries and SDKs

Light Protocol provides SDKs in two languages:

Rust SDK

Primary Crates:

• light-client: RPC client with retry logic and connection pooling
• light-sdk: High-level API for compressed accounts and transactions
• light-token: Token-specific operations
• light-program-test: Fast local testing using litesvm

Usage Pattern (Anchor programs):

TypeScript SDK

Primary Packages:

• @lightprotocol/stateless.js: Core compression functionality
• @lightprotocol/compressed-token: Token operations client
• @lightprotocol/zk-compression-cli: Development CLI

Installation:

Both SDKs handle:

• Proof fetching from Light Prover
• State queries from Photon
• Transaction construction and submission
• Account serialization/deserialization

For detailed SDK usage, see Client Libraries and SDKs.

Sources: sdk-libs/client/Cargo.toml1-81 sdk-libs/sdk/Cargo.toml1-87 pnpm-lock.yaml1-50

---

Development Workflow

Local Development Setup

Light Protocol provides a self-contained development environment via shell scripts:

Installation and Setup

The scripts/devenv.sh script configures:

• PATH for .local/bin (Solana CLI, Anchor, Node.js)
• CARGO_FEATURES=v2_ix for V2 instruction support
• Rust toolchains (stable 1.75.0, nightly)
• Node.js 20.9.0 LTS and pnpm 9.x
• Gnark proving keys in .local/proving-keys/

Alternative Setup: Development Containers via .devcontainer/devcontainer.json provide a pre-configured Docker environment with all dependencies installed.

Prerequisites (for manual setup):

• Ubuntu: sudo apt-get install lld clang build-essential
• macOS: brew install llvm

Test Infrastructure

Light Protocol uses multiple testing layers for different purposes:

Testing Architecture

Key Testing Components:

Framework	Crate/Path	Purpose
LightProgramTest	sdk-libs/program-test/Cargo.toml1-72	Fast in-memory testing using litesvm
TestIndexer	sdk-libs/program-test	In-memory state indexer for tests
E2ETestEnv	program-tests/e2e-test	Multi-round randomized testing
TestRpc	js/stateless.js/src/rpc/test-rpc.ts	Mock RPC for TypeScript unit tests

Running Tests:

For detailed testing information, see Testing Framework.

Sources: README.md76-206 sdk-libs/program-test/Cargo.toml1-72 README.md183-205

---

Repository Organization

The repository is organized as a Cargo monorepo with 81 workspace members and a pnpm workspace for TypeScript packages.

Directory Structure

Core Directory Layout

Workspace Configuration

The root Cargo.toml1-296 defines workspace structure:

Key Workspace Dependencies (defined in [workspace.dependencies]):

Dependency	Version	Usage
solana-sdk	2.3	Solana runtime types and syscalls
anchor-lang	0.31.1	Anchor framework for Anchor programs
light-hasher	5.0.0	Pluggable hash implementations
light-client	0.23.0	RPC client with retry logic
light-compressed-token	2.0.0	Compressed token program (CPI)
photon-api	0.56.0	Type-safe Photon API client
light-prover-client	8.0.0	ZK proof generation client

TypeScript Packages

The pnpm-workspace.yaml organizes JavaScript/TypeScript code:

js/
  stateless.js/          # Core compression SDK
    src/rpc/
      rpc.ts             # Rpc class
      test-rpc.ts        # TestRpc for unit tests
  compressed-token/      # Token SDK
    src/actions/
      mint.ts
      transfer.ts
cli/                     # CLI tool
  @lightprotocol/zk-compression-cli
sdk-tests/               # TypeScript integration tests

Development Tools

The xtask/ directory (xtask/src/main.rs1-142) provides administrative commands:

Command	Module	Purpose
create-state-tree	xtask/src/create_state_tree.rs	Initialize new Merkle trees
fetch-accounts	xtask/src/fetch_accounts.rs1-264	Download account data from RPC
fetch-failed-txs	xtask/src/fetch_failed_txs.rs1-262	Query failed Registry transactions
create-ctoken-account	xtask/src/create_ctoken_account.rs1-114	Create compressible token accounts
reinit-cpi-accounts	xtask/src/reinit_cpi_accounts.rs1-159	Migrate legacy CPI context accounts
print-state-tree	xtask/src/print_state_tree.rs1-279	Display tree metadata
close-buffer	xtask/src/close_buffer.rs1-51	Close BPF loader buffers via multisig

Usage example:

For detailed workspace structure, see Repository Structure.

Sources: Cargo.toml1-296 xtask/Cargo.toml1-43 xtask/src/main.rs1-142

---

Build System and CI/CD

Cargo Workspace Configuration

The repository uses Cargo workspace resolver v2 (Cargo.toml83) with centralized dependency management.

Workspace Structure:

Key Shared Dependencies (defined in [workspace.dependencies]):

Dependency	Version	Purpose
solana-sdk	2.3	Solana runtime and syscalls
solana-program	2.3	BPF program entrypoint
anchor-lang	0.31.1	Anchor framework
borsh	0.10.4	Serialization (Anchor-compatible)
litesvm	0.7	Fast in-process validator for tests
ark-bn254	0.5	BN254 curve for ZK proofs

Build Profiles:

• dev: Fast compilation with opt-level = 0
• release: Overflow checks enabled for safety in production

Custom Patches (Cargo.toml289-296):

Patches add profiling syscalls for CU and heap memory tracking.

CI/CD Workflows

The repository has multiple GitHub Actions workflows for automated testing:

Workflow	Trigger	Purpose
rust.yml	Push/PR	Rust program compilation and tests
js-tests-v1.yml	Push/PR	V1 protocol TypeScript tests
js-tests-v2.yml	Push/PR	V2 protocol TypeScript tests
light-system-programs-tests.yml	Push/PR	System program integration tests
forester-e2e-test.yml	Push/PR	Forester service end-to-end tests
prover-test.yml	Push/PR	Prover service unit tests
verifiable-build.yml	Tag	Reproducible program builds

Verifiable Builds

Light Protocol uses deterministic builds for on-chain programs:

The build-verifiable.sh script uses Docker with solana-verify to ensure reproducible builds matching deployed bytecode.

For detailed CI/CD information, see Build System and CI/CD.

Sources: Cargo.toml83-296 README.md32-63

---

Security and Audits

Light Protocol core programs have undergone extensive security review and formal verification:

Audit Reports

Auditor	Scope	Date	Report
OtterSec	Programs audit #1	2024	audits/ottersec_v1_audit.pdf
Neodyme	Programs audit #2	2024	audits/neodyme_v1_audit.pdf
Zellic	Programs audit #3	2024	audits/zellic_v1_audit.pdf
Reilabs	ZK circuits formal verification	2024	audits/reilabs_circuits_formal_verification_report.pdf

Audited Components:

• account-compression program (programs/account-compression)
• light-system-program (programs/system)
• light-compressed-token (programs/compressed-token/program)
• light-registry (programs/registry)
• ZK circuits in light-prover (prover)

Unaudited Components (in active development):

• SDK libraries: light-sdk, light-client, light-token
• SDK macros: light-sdk-macros
• Development tools: light-program-test, xtask
• Forester service implementation

Bug Bounty Program

Active vulnerability disclosure program on Immunefi: https://immunefi.com/bug-bounty/light-protocol/information/

Reporting Channels:

• Smart contract vulnerabilities: Immunefi program
• Infrastructure vulnerabilities: [email protected]
• GitHub Security Advisories: Private disclosure via GitHub

For detailed security information, see Access Control and Security.

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

---

Next Steps

For developers getting started with Light Protocol:

1. Quick Start: Set up the development environment (Development Environment)
2. Understanding Programs: Learn about the four core programs (On-Chain Programs)
3. SDK Integration: Integrate Light Protocol into your application (Client Libraries and SDKs)
4. Testing: Write tests for your compressed accounts (Testing Framework)
5. Advanced Topics: Dive into ZK proofs, Merkle trees, and performance optimization (Advanced Topics)

For questions and support:

• Documentation: https://www.zkcompression.com
• Discord: https://discord.gg/x4nyjT8fK5
• GitHub Issues: https://github.com/Lightprotocol/light-protocol/issues

Sources: README.md15-206