System Architecture

​

Architecture Overview

​

Core Components

​

On-Chain Programs

​

Account Compression Program

• Maintain state and address Merkle trees
• Verify zero-knowledge proofs
• Update tree roots after batch insertions
• Manage nullifier and output queues
• Handle rollover to new trees when capacity is reached

​

Light System Program

• Validate compressed account structure
• Perform ownership checks (only owner can modify data)
• Verify ZK proofs for state transitions
• Insert nullifiers for spent accounts
• Append new account hashes to output queues
• Enforce account layout similar to Solana’s regular accounts

pub struct CompressedAccount {
    pub owner: Pubkey,              // Only owner can modify
    pub lamports: u64,               // Account balance
    pub address: Option<[u8; 32]>,  // Optional unique identifier
    pub data: Option<CompressedAccountData>,
}

​

Compressed Token Program

• SPL Token-compatible interface
• Mint, transfer, burn compressed tokens
• Compress/decompress between SPL and compressed tokens
• Token-2022 extension support (partial)

​

Registry Program

• Register and manage foresters
• Set network fees and parameters
• Control protocol upgrades

​

Off-Chain Infrastructure

​

Photon Indexer

• Listens to Solana blocks for Light Protocol events
• Indexes compressed account data from transaction calldata
• Provides RPC API for querying compressed accounts
• Maintains database of current and historical state
• Generates Merkle proofs for inclusion verification

• Compressed account hashes and data
• Merkle tree roots and metadata
• Nullifier queue contents
• Transaction history

// Get compressed account
getCompressedAccount(hash: string)

// Get compressed accounts by owner
getCompressedAccountsByOwner(owner: PublicKey)

// Get multiple compressed accounts
getMultipleCompressedAccounts(hashes: string[])

// Get proof for compressed account
getCompressedAccountProof(hash: string)

// Get validity proof
getValidityProof(hashes: string[])

​

ZK Prover Service

• Written in Go using Gnark library
• Implements Groth16 SNARK proving system
• Generates circuit-specific proofs

• Batch Append: Insert multiple new leaves into state tree
• Batch Update: Nullify multiple existing leaves (update in place)
• Address Append: Insert addresses into address tree with non-inclusion proof

• Uses Poseidon hash function (ZK-friendly)
• Supports variable batch sizes (100-1000 typical)
• ~1-10 seconds proving time depending on batch size

​

Forester Service

1. Monitor nullifier and output queues for full batches
2. Request ZK proof from prover service
3. Submit batch update transaction to update tree roots
4. Zero out bloom filters when safe
5. Roll over to new trees when capacity reached

• Queues have limited capacity
• Full queues prevent new transactions
• Must consistently empty queues to maintain protocol availability
• Permissionless - anyone can run a forester

​

Transaction Flow

​

Creating a Compressed Account

​

Updating a Compressed Account

​

State Storage Design

​

Two-Queue System

​

Input Queue (Nullifier Queue)

• Two alternating batches (double-buffering)
• Bloom filters for fast non-inclusion checks
• Hash chains for batch proof generation
• Batch size: typically 500-10,000 nullifiers

• Prevent double-spending
• Enable proof-by-index before tree update
• Batch nullifications for efficiency

​

Output Queue

• Two alternating batches
• Value arrays store full hashes
• Hash chains for batch proof generation
• Batch size: typically 10,000-50,000 hashes

• Buffer new accounts before tree insertion
• Enable immediate reading of newly created accounts
• Batch insertions for efficiency

​

Batch Processing

1. Fill Phase: Accept new insertions into current batch
2. Full Phase: Batch is full, switch to alternate batch, ready for tree insertion
3. Inserted Phase: ZK proof submitted, tree updated, batch can be cleared
4. Clear Phase: Bloom filters zeroed (for nullifier queue), batch ready to fill again

pub enum BatchState {
    Fill,      // Accepting new insertions
    Full,      // Full, ready for tree update
    Inserted,  // Tree updated, ready to clear
}

​

Parallelism and Scaling

​

Tree Parallelism

• Each tree has its own write lock
• Trees can be updated simultaneously
• Applications can use dedicated trees for better throughput
• Custom programs can derive and own their own trees

​

Account Separation

• Nullifying from tree A doesn’t lock tree B
• Inserting into tree A doesn’t lock nullifier queue B
• Enables higher transaction throughput

​

Rollover Mechanism

1. New tree account is created automatically
2. Linked to previous tree via metadata
3. New accounts directed to new tree
4. Old tree remains readable forever
5. Rollover fees amortized across all transactions

// For a tree with depth 26 (67M capacity)
let tree_rent = 0.5 SOL;  // One-time cost
let capacity = 2^26;       // 67 million accounts
let fee_per_account = tree_rent / capacity;
// = ~0.0000000075 SOL per account

​

Data Availability

​

Solana Ledger Storage

• All compressed account data is emitted as calldata in transactions
• Stored in Solana’s ledger space (not account space)
• Significantly cheaper than account rent
• Available to all validators

​

Indexer Redundancy

• Multiple independent indexers can exist
• Open source - anyone can run an indexer
• Syncs from genesis by processing all transactions
• No dependency on specific infrastructure provider

​

Cryptographic Guarantees

• On-chain Merkle roots prove state integrity
• Cannot use data not previously emitted through protocol
• ZK proofs verify correct state transitions
• Invalid data is rejected on-chain

​

Security Model

​

Trust Assumptions

• On-chain programs (Solana security)
• Merkle root integrity (cryptographic)
• ZK proof verification (mathematical)

• Indexer for data retrieval (but can verify against roots)
• Prover service (but proofs are verified on-chain)
• Forester liveness (but cannot compromise security)

​

Attack Vectors and Mitigations

​

Program Libraries

​

Core Libraries

• light-sdk: High-level SDK for compressed account operations
• light-compressed-account: Account types and hashing
• light-batched-merkle-tree: Tree data structures
• light-hasher: Poseidon hash implementation
• light-verifier: ZK proof verification

​

Integration Patterns

use light_sdk::compressed_account::CompressedAccount;
use light_sdk::merkle_context::MerkleContext;

#[derive(Accounts)]
pub struct CreateCompressed<'info> {
    #[account(mut)]
    pub signer: Signer<'info>,
    
    /// State merkle tree
    pub merkle_tree: AccountLoader<'info, MerkleTree>,
    
    /// Output queue for new accounts
    pub output_queue: AccountLoader<'info, Queue>,
}

​

Next Steps