Test Validator

The light test-validator command starts a complete local development environment for ZK Compression, including:

Solana test validator with Light Protocol programs
Photon indexer for querying compressed accounts
Light prover server for generating zero-knowledge proofs
Forester service (optional) for automatic tree management

Basic Usage

light test-validator

This starts all services with default configuration and a clean ledger.

Core Flags

Skip Services

Run the validator without specific components:

--skip-indexer

boolean

default:"false"

Skip starting the Photon indexer. Use when you have an external indexer or don’t need compressed account queries.

--skip-prover

boolean

default:"false"

Skip starting the prover service. Use when you have an external prover or want to test without proof generation.

--skip-system-accounts

boolean

default:"false"

Skip initializing Light system accounts. Advanced usage only.

Example

light test-validator --skip-indexer --skip-prover

Forester Service

--forester

boolean

default:"false"

Start the forester service for automatic compression of compressible accounts.

--forester-port

integer

default:"8080"

Port for the forester API server.

--light-pda-program

string

Light PDA programs to track. Format: program_id:discriminator_base58. Can be specified multiple times for tracking multiple programs.

Example

light test-validator --forester --forester-port 9090 \
  --light-pda-program "ProgramId1:Discriminator1" \
  --light-pda-program "ProgramId2:Discriminator2"

Network Configuration

Port Configuration

--rpc-port

integer

default:"8899"

JSON RPC port. The RPC websocket will use the next port (default: 8900).

--indexer-port

integer

default:"8784"

Photon indexer port. Cannot be used with --skip-indexer.

--prover-port

integer

default:"3001"

Light prover server port. Cannot be used with --skip-prover.

--gossip-host

string

default:"127.0.0.1"

Gossip DNS name or IP address for the validator to advertise.

Example

light test-validator \
  --rpc-port 9000 \
  --indexer-port 9784 \
  --prover-port 4001

Validator Configuration

--limit-ledger-size

integer

default:"10000"

Maximum number of shreds to keep in root slots. Higher values use more disk space.

--geyser-config

string

Path to Geyser plugin configuration file. Cannot be used with --validator-args.

--validator-args

string

Additional arguments to pass directly to solana-test-validator. For advanced users only. Cannot be used with --geyser-config.

Example

light test-validator --limit-ledger-size 50000000

Geyser Plugin

light test-validator --geyser-config ./config.json

Direct Validator Args

light test-validator --validator-args "--limit-ledger-size 50000000"

Program Management

Loading Custom Programs

--sbf-program

string

Add a SBF program to genesis with upgrades disabled. Takes two arguments: <address> <path/program.so>. Can be specified multiple times.If the ledger exists, this parameter is silently ignored.

--upgradeable-program

string

Add an upgradeable SBF program to genesis. Required for programs needing compressible config initialization. Takes three arguments: <address> <path/program.so> <upgrade_authority>. Can be specified multiple times.If the ledger exists, this parameter is silently ignored.

SBF Program

light test-validator \
  --sbf-program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA token.so

Upgradeable Program

light test-validator \
  --upgradeable-program MyProgram111111111111111111111111111 \
    ./target/deploy/my_program.so \
    UpgradeAuth11111111111111111111111111111

Custom programs cannot use addresses or filenames that collide with Light Protocol system programs:

noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV (spl_noop.so)
SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7 (light_system_program.so)
cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m (light_compressed_token.so)
compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq (account_compression.so)
Lighton6oQpVkeewmo2mcPTQQp7kYHr4fWpAgJyEmDX (light_registry.so)

Loading Accounts

--account-dir

string

Additional directory containing account JSON files to preload. Can be specified multiple times for multiple directories.

Example

light test-validator \
  --account-dir ./accounts/mainnet \
  --account-dir ./accounts/custom

Network Cloning

--devnet

boolean

default:"false"

Clone Light Protocol programs and accounts from Devnet instead of loading local binaries. Cannot be used with --mainnet.

--mainnet

boolean

default:"false"

Clone Light Protocol programs and accounts from Mainnet instead of loading local binaries. Cannot be used with --devnet.

Devnet Clone

light test-validator --devnet

Mainnet Clone

light test-validator --mainnet

Indexer Configuration

--indexer-db-url

string

Custom indexer database URL for storing indexing data. By default, an in-memory SQLite database is used. Cannot be used with --skip-indexer.

--relax-indexer-version-constraint

boolean

default:"false"

Disable indexer version check. Use only if you know what you’re doing. Cannot be used with --skip-indexer.

Custom Database

light test-validator --indexer-db-url "postgresql://user:pass@localhost/photon"

Validator Management

Validator Runtime

--use-surfpool

boolean

default:"true"

Use Surfpool instead of solana-test-validator. Pass --no-use-surfpool to use the standard Solana test validator.

--skip-reset

boolean

default:"false"

Skip resetting the ledger. Continues from previous state.

Use Standard Validator

light test-validator --no-use-surfpool

Continue Previous Session

light test-validator --skip-reset

Stopping the Validator

--stop

boolean

default:"false"

Stop the test validator and dependent processes. Combine with --skip-indexer or --skip-prover to keep specific services running.

Stop All

light test-validator --stop

Stop Validator, Keep Prover

light test-validator --stop --skip-prover

Logging

--verbose

boolean

default:"false"

Enable verbose logging for debugging.

light test-validator -v

Common Workflows

Standard Development Setup

# Full environment with clean state
light test-validator

Testing Without Indexer

# When you don't need compressed account queries
light test-validator --skip-indexer

Custom Ports for Multiple Instances

# Run multiple validators simultaneously
light test-validator \
  --rpc-port 9899 \
  --indexer-port 9784 \
  --prover-port 4001

Production-Like Setup

# Clone mainnet state with forester
light test-validator --mainnet --forester

Testing Custom Programs

# Load your program with Light Protocol
light test-validator \
  --upgradeable-program MyProg111111111111111111111111111111 \
    ./target/deploy/my_program.so \
    $(solana address)

Troubleshooting

Port already in use

If you see port conflicts, either:

Stop existing services with light test-validator --stop
Use custom ports with --rpc-port, --indexer-port, --prover-port

Validator won't start

Try these steps:

Stop all processes: light test-validator --stop
Check for zombie processes: ps aux | grep solana
Start with verbose logging: light test-validator -v
Reset the ledger: Start normally (resets by default)

Indexer version mismatch

If you need to bypass version checks temporarily:

light test-validator --relax-indexer-version-constraint

Note: This is not recommended for production use.

Custom program not loading

Ensure:

Program file exists at the specified path
Address doesn’t conflict with system programs
Filename doesn’t match system program names
You’re using the correct flag (—sbf-program vs —upgradeable-program)

Examples

# Just validator and prover
light test-validator --skip-indexer

CLI

Test Validator

Test Validator

Basic Usage

Core Flags

Skip Services

Forester Service

Network Configuration

Port Configuration

Validator Configuration

Program Management

Loading Custom Programs

Loading Accounts

Network Cloning

Indexer Configuration

Validator Management

Validator Runtime

Stopping the Validator

Logging

Common Workflows

Standard Development Setup

Testing Without Indexer

Custom Ports for Multiple Instances

Production-Like Setup

Testing Custom Programs

Troubleshooting

Examples

Next Steps

All Commands

Compressed Tokens

Build docs developers (and LLMs) love

CLI

​Test Validator

​Basic Usage

​Core Flags

​Skip Services

​Forester Service

​Network Configuration

​Port Configuration

​Validator Configuration

​Program Management

​Loading Custom Programs

​Loading Accounts

​Network Cloning

​Indexer Configuration

​Validator Management

​Validator Runtime

​Stopping the Validator

​Logging

​Common Workflows

​Standard Development Setup

​Testing Without Indexer

​Custom Ports for Multiple Instances

​Production-Like Setup

​Testing Custom Programs

​Troubleshooting

​Examples

​Next Steps

All Commands

Compressed Tokens

Build docs developers (and LLMs) love

Test Validator

Basic Usage

Core Flags

Skip Services

Forester Service

Network Configuration

Port Configuration

Validator Configuration

Program Management

Loading Custom Programs

Loading Accounts

Network Cloning

Indexer Configuration

Validator Management

Validator Runtime

Stopping the Validator

Logging

Common Workflows

Standard Development Setup

Testing Without Indexer

Custom Ports for Multiple Instances

Production-Like Setup

Testing Custom Programs

Troubleshooting

Examples

Next Steps