Skip to main content

​
Prerequisites

Before installing Light Protocol, ensure you have the following:
Required for JavaScript/TypeScript development.Recommended: Node.js 20.9.0 LTS or higher
# Check your version
node --version
npm --version
Download from nodejs.org
Required for building Solana programs with Light Protocol.Required: Rust stable and nightly toolchains
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install nightly toolchain
rustup toolchain install nightly

# Check versions
rustc --version
cargo --version
Required for deploying and testing programs.Recommended: Solana CLI 1.18+ (compatible with SDK 2.3)
# Install Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# Check version
solana --version

# Generate keypair
solana-keygen new -o ~/.config/solana/id.json
Platform-specific build dependencies.Linux (Ubuntu/Debian):
sudo apt-get install lld clang build-essential autoconf automake libtool zlib1g-dev pkg-config libssl-dev
Linux (Fedora):
sudo dnf install clang lld
Linux (Arch):
sudo pacman -S lld clang
macOS:
brew install llvm

​
CLI Installation

The Light Protocol CLI provides tools for local development and testing. 
npm install -g @lightprotocol/zk-compression-cli
Verify installation: 
light --version
The CLI includes the light test-validator command which runs a local Solana validator pre-configured with all Light Protocol programs.

​
JavaScript SDK

Install the Light Protocol JavaScript libraries for building client applications.

​
Core SDK (@lightprotocol/stateless.js)

For working with compressed accounts and general ZK Compression features: 
npm install @lightprotocol/stateless.js @solana/web3.js

​
Compressed Token SDK (@lightprotocol/compressed-token)

For working with compressed tokens: 
npm install @lightprotocol/compressed-token @lightprotocol/stateless.js @solana/web3.js @solana/spl-token
The @lightprotocol/compressed-token package depends on @lightprotocol/stateless.js, so both need to be installed.

​
Quick Test

Verify the installation: 
import { Rpc } from '@lightprotocol/stateless.js';
import { Connection } from '@solana/web3.js';

// Create RPC connection
const connection = new Connection('http://127.0.0.1:8899');
const rpc = await Rpc.createRpc(connection);

console.log('Light Protocol SDK installed successfully!');

​
Rust SDK

Add Light Protocol to your Solana program’s Cargo.toml.

​
For Anchor Programs

[Cargo.toml]
[dependencies]
anchor-lang = "0.31.1"
light-sdk = "0.23.0"
light-compressed-token = { version = "2.0.0", features = ["cpi"] }
light-system-program = { version = "2.0.0", features = ["cpi"] }
account-compression = { version = "2.0.0", features = ["cpi"] }

​
For Native Programs

[Cargo.toml]
[dependencies]
solana-program = "2.3"
light-sdk = "0.23.0"
light-compressed-account = "0.11.0"
light-hasher = "5.0.0"

​
Client Libraries

For building Rust clients or test utilities:
[Cargo.toml]
[dependencies]
light-client = "0.23.0"
light-token-client = "0.23.0"
light-program-test = "0.23.0"  # For testing
Make sure to use compatible versions. Light Protocol v0.23.0 works with Solana SDK 2.3 and Anchor 0.31.1.

​
Building from Source

For advanced users who want to build Light Protocol from source.

​
Clone Repository

git clone https://github.com/Lightprotocol/light-protocol.git
cd light-protocol

​
Install Dependencies

./scripts/install.sh
This installs:
  • Solana CLI tools
  • Anchor framework
  • Node.js dependencies
  • Gnark proving keys (subset for testing)
If you need the complete set of production proving keys:
./scripts/install.sh --full-keys
Full keys are large (~10GB+). Only needed for production deployments.

​
Activate Development Environment

./scripts/devenv.sh
This sets up a shell with all dependencies in your PATH.

​
Build the Project

./scripts/build.sh
This builds:
  • All Rust programs and libraries
  • TypeScript packages
  • CLI tools

​
Run Tests

./scripts/test.sh
For specific test suites, see the Testing Guide.

​
Development Containers

Light Protocol supports Development Containers for consistent environments.

​
VS Code

  1. Install the Dev Containers extension
  2. Open the repository in VS Code
  3. Click “Reopen in Container” when prompted

​
Other IDEs

The container includes all dependencies pre-configured.

​
Network Endpoints

Configure your application to connect to different networks.

​
Localnet

const connection = new Connection('http://127.0.0.1:8899');
const rpc = await Rpc.createRpc(connection, {
  proverUrl: 'http://127.0.0.1:3001',
  indexerUrl: 'http://127.0.0.1:8784',
});

​
Devnet

const connection = new Connection('https://api.devnet.solana.com');
const rpc = await Rpc.createRpc(connection, {
  proverUrl: 'https://prover.devnet.lightprotocol.com',
  indexerUrl: 'https://devnet.helius-rpc.com',
});

​
Mainnet Beta

const connection = new Connection('https://api.mainnet-beta.solana.com');
const rpc = await Rpc.createRpc(connection, {
  proverUrl: 'https://prover.mainnet.lightprotocol.com',
  indexerUrl: 'https://mainnet.helius-rpc.com',
});
Helius provides the official Photon indexer for devnet and mainnet. Visit helius.dev to get an API key.

​
Verify Installation

Test your complete setup:
1

Start Test Validator

light test-validator
Keep this running in a separate terminal.
2

Run Example

Create a test file test.ts:
import { Rpc, compress } from '@lightprotocol/stateless.js';
import { Keypair, Connection } from '@solana/web3.js';

const payer = Keypair.generate();
const connection = new Connection('http://127.0.0.1:8899');
const rpc = await Rpc.createRpc(connection);

// Airdrop SOL
const airdrop = await connection.requestAirdrop(
  payer.publicKey,
  1e9
);
await connection.confirmTransaction(airdrop);

console.log('✓ Installation verified!');
Run it:
npx tsx test.ts

​
Troubleshooting

The CLI wasn’t added to PATH. Try:
# Check where npm installs global packages
npm config get prefix

# Add to PATH (in ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"
Ensure no other Solana validator is running:
# Kill existing validators
killall solana-test-validator

# Clear ledger data
rm -rf test-ledger/

# Restart
light test-validator
Install missing system dependencies:Ubuntu/Debian:
sudo apt install build-essential autoconf automake libtool zlib1g-dev pkg-config libssl-dev
macOS:
xcode-select --install
Ensure all packages use compatible versions:
  • Light Protocol SDK: v0.23.0
  • Solana SDK: v2.3.x
  • Anchor: v0.31.1
Clear cache and reinstall:
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Quickstart

Build your first compressed token application

CLI Reference

Explore all CLI commands

JavaScript SDK

Learn the TypeScript SDK

Rust SDK

Integrate into Solana programs

Build docs developers (and LLMs) love

Get started for freeTalk to us