Overview & Program Template

Compressed PDAs provide full composability and functionality of accounts at PDAs, without rent-exemption cost per account. Suited for accounts where each user or entity gets their own PDA and state is infrequently accessed.

Creation Cost	Regular PDA	Compressed PDA
100-byte account	~0.0016 SOL	0.000015 SOL

Compressed PDAs are derived using a specific program address and seed, like regular PDAs. Custom programs invoke the Light System program to create and update compressed accounts, instead of the System program. Compressed PDAs are compressed accounts with an address.

Compressed PDAs are suited for:

• Per-user state (profiles, preferences, credentials)
• DePIN node accounts and stake accounts
• Nullifiers to prevent an on-chain instruction from being executed twice (little implementation overhead and useful e.g. for payments or ZK programs)
• App state that is written to and read from infrequently

For DeFi pools, vaults, shared state, pool accounts, or config accounts, use Light-PDA with minimal code changes.

Create

Update

Close

Reinitialize

Burn

Start Building with the Program Template

1. Prerequisites

   Required versions:

   • Rust: 1.90.0 or later
   • Solana CLI: 2.3.11 or later
   • Anchor CLI: 0.31.1
   • Zk compression CLI: 0.27.0 or later
   • Node.js: 22 or later

   Install Solana CLI:

   sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
   

   Install Anchor CLI:

   cargo install --git https://github.com/coral-xyz/anchor avm --force
   avm install latest
   avm use latest
   

   Install the Light CLI:

   npm

   npm install -g @lightprotocol/zk-compression-cli
   

   yarn

   yarn global add @lightprotocol/zk-compression-cli
   

   pnpm

   pnpm add -g @lightprotocol/zk-compression-cli
   

   Verify installation:

   light --version
   
2. Initialize your Program

   Instantiate a template Solana program with compressed accounts with all required dependencies.

   light init testprogram
   

   The light init command creates only Anchor-based projects . For Pinocchio programs, manually configure dependencies using light-sdk-pinocchio.

   Dependencies

   Rust Crates

   • light-sdk - Core SDK for compressed accounts in native and anchor programs
   • light-sdk-pinocchio Core SDK for compressed accounts in pinocchio programs
   • light-client - RPC client and indexer for interacting with compressed accounts
   • light-program-test - Testing utilities for compressed programs.

   TypeScript/JavaScript Packages

   • @lightprotocol/stateless.js - Client library for interacting with compressed accounts
   • @lightprotocol/zk-compression-cli - Command-line tools for ZK compression development
3. Build and Test

   Now cd testprogram and run:

   anchor build
   # Success: Finished `release` profile [optimized] target(s), after compiling.
   # Note: Stack offset warnings are expected and don't prevent compilation
   

   cargo test-sbf
   
   # Success: test result: ok. 1 passed; 0 failed; 0 ignored
   

Common Errors

assert.h file not found - during compilation.

Fix:
In your terminal, run:
1. export CC=$(xcrun -find clang)
2. export SDKROOT=$(xcrun --show-sdk-path)
3. cargo clean
4. anchor build


Example log:
The following warnings were emitted during compilation:

warning: blake3@1.5.1: In file included from c/blake3_neon.c:1:
warning: blake3@1.5.1: c/blake3_impl.h:4:10: fatal error: 'assert.h' file not found
warning: blake3@1.5.1:     4 | #include <assert.h>
warning: blake3@1.5.1:       |          ^~~~~~~~~~
warning: blake3@1.5.1: 1 error generated.

error: failed to run custom build command for `blake3 v1.5.1`

Caused by:
  process didn't exit successfully: `/Users/you/testprogram/target/release/build/blake3-ac41d29c2eabe052/build-script-build` (exit status: 1)
  --- stdout
  cargo:rerun-if-env-changed=CARGO_FEATURE_PURE
  cargo:rerun-if-env-changed=CARGO_FEATURE_NO_NEON
  cargo:rerun-if-env-changed=CARGO_FEATURE_NEON
  cargo:rerun-if-env-changed=CARGO_FEATURE_NEON
  cargo:rerun-if-env-changed=CARGO_FEATURE_NO_NEON
  cargo:rerun-if-env-changed=CARGO_FEATURE_PURE
  cargo:rustc-cfg=blake3_neon
  OUT_DIR = Some(/Users/you/testprogram/target/release/build/blake3-735a4c71d985df30/out)
  TARGET = Some(aarch64-apple-darwin)
  OPT_LEVEL = Some(3)
  HOST = Some(aarch64-apple-darwin)
  cargo:rerun-if-env-changed=CC_aarch64-apple-darwin
  CC_aarch64-apple-darwin = None
  cargo:rerun-if-env-changed=CC_aarch64_apple_darwin
  CC_aarch64_apple_darwin = None
  cargo:rerun-if-env-changed=HOST_CC
  HOST_CC = None
  cargo:rerun-if-env-changed=CC
  CC = Some(/Users/you/.local/share/solana/install/releases/1.18.22/solana-release/bin/sdk/sbf/dependencies/platform-tools/llvm/bin/clang)
  RUSTC_WRAPPER = None
  cargo:rerun-if-env-changed=CC_ENABLE_DEBUG_OUTPUT
  cargo:rerun-if-env-changed=CRATE_CC_NO_DEFAULTS
  CRATE_CC_NO_DEFAULTS = None
  DEBUG = Some(false)
  cargo:rerun-if-env-changed=MACOSX_DEPLOYMENT_TARGET
  MACOSX_DEPLOYMENT_TARGET = None
  cargo:rerun-if-env-changed=CFLAGS_aarch64-apple-darwin
  CFLAGS_aarch64-apple-darwin = None
  cargo:rerun-if-env-changed=CFLAGS_aarch64_apple_darwin
  CFLAGS_aarch64_apple_darwin = None
  cargo:rerun-if-env-changed=HOST_CFLAGS
  HOST_CFLAGS = None
  cargo:rerun-if-env-changed=CFLAGS
  CFLAGS = None
  cargo:warning=In file included from c/blake3_neon.c:1:
  cargo:warning=c/blake3_impl.h:4:10: fatal error: 'assert.h' file not found
  cargo:warning=    4 | #include <assert.h>
  cargo:warning=      |          ^~~~~~~~~~
  cargo:warning=1 error generated.

  --- stderr


  error occurred: Command env -u IPHONEOS_DEPLOYMENT_TARGET "/Users/you/.local/share/solana/install/releases/1.18.22/solana-release/bin/sdk/sbf/dependencies/platform-tools/llvm/bin/clang" "-O3" "-ffunction-sections" "-fdata-sections" "-fPIC" "--target=arm64-apple-darwin" "-mmacosx-version-min=14.4" "-Wall" "-Wextra" "-std=c11" "-o" "/Users/you/testprogram/target/release/build/blake3-735a4c71d985df30/out/db3b6bfb95261072-blake3_neon.o" "-c" "c/blake3_neon.c" with args clang did not execute successfully (status code exit status: 1).

Guides

Create	Initialize compressed PDAs in your program
Update	Modify state in compressed accounts
Close	Reclaim lamports from compressed accounts
Reinitialize	Reset and reuse compressed accounts
Burn	Permanently delete compressed accounts
Nullifier PDAs	Prevent replay attacks with one-time use accounts

Program Examples

Example	Description
Account Comparison	Compare compressed accounts with standard Solana accounts
basic-operations/anchor	Anchor programs to create, update, close, reinitialize and burn compressed accounts with Rust and TypeScript tests
basic-operations/native	Native Solana program implementation to create, update, close, reinitialize and burn compressed accounts with Rust tests
Counter (Anchor)	Full compressed account lifecycle (create, increment, decrement, reset, close) using Anchor framework
Counter (Native)	Native Solana program implementation with Rust tests
Counter (Pinocchio)	Pinocchio implementation using light-sdk-pinocchio with Rust tests
Create-and-Update	Create new compressed accounts and update existing ones within a single instruction and one validity proof
merkle-distributor	SPL token distribution with compressed PDAs for claim tracking, vesting, and clawback
Nullifier Program	Primitive to enforce that a given onchain instruction (such as a payment) executes only once, and to track execution by unique identifiers (e.g. a nonce, uuid, etc.)
Read-Only	Create compressed accounts and read them on-chain
simple-claim	Distributes compressed tokens that decompress to SPL on claim
ZK-ID	Zero-knowledge proofs for identity verification with compressed accounts
ZK-Nullifier	Implementation of nullifiers for zk programs on Solana to prevent double spending

SDK Reference

Client

@lightprotocol/stateless.js

TypeScript RPC client for compressed accounts, validity proofs, and address derivation.

light-client

Rust RPC client and indexer for compressed accounts.

Program

light-sdk

Core SDK for compressed accounts in Anchor programs.

light-sdk-macros

Procedural macros for LightAccount derivation.

light-program-test

Local testing framework for programs.

Next Steps

Build a client for your program.