solana-compression

Compressed PDA Programs

Build Solana programs with compressed accounts via CPI to the Light System Program. No rent-exemption required.

Creation cost	Solana account	Compressed account
PDA (128 bytes)	~1,100,000 lamports	~5,000 lamports

When to use compressed PDAs

• Per-user state (profiles, game state, credentials)
• DePIN device registrations
• Nullifier-based double-spend prevention
• Infrequently accessed accounts

Choosing approach

Criteria	Light-PDA (easy)	Compressed PDA (advanced)
When	Rent-free version of existing Anchor accounts	Custom compressed state with ZK proofs
Skill	light-sdk (Anchor macro pattern)	This skill (solana-compression)
Macro	#[light_account(init)]	LightAccount::new_init() manual CPI
Dependencies	light-sdk, light-compressible	light-sdk, light-sdk-types

If you just want rent-free Anchor accounts, use the light-sdk skill instead. This skill is for programs that require manual CPI to the Light System Program (custom compressed state, ZK proofs, address derivation).

Client-program interaction flow

 ├─ Client
 │  ├─ Get ValidityProof from RPC.
 │  ├─ pack accounts with PackedAccounts into PackedAddressTreeInfo and PackedStateTreeInfo.
 │  ├─ pack CompressedAccountMeta.
 │  ├─ Build Instruction from PackedAccounts and CompressedAccountMetas.
 │  └─ Send transaction.
 │
 └─ Custom Program
    ├─ CpiAccounts parse accounts consistent with PackedAccounts.
    ├─ LightAccount instantiates from CompressedAccountMeta.
    │
    └─ Light System Program CPI
       ├─ Verify ValidityProof.
       ├─ Update State Merkle tree.
       ├─ Update Address Merkle tree.
       └─ Complete atomic state transition.

Domain references

Topic	Reference
Program operations (create, update, close, burn, reinit)	references/compressed-pdas.md
Client SDK (TypeScript + Rust)	references/client.md
Nullifier PDAs (double-spend prevention)	references/nullifier-pdas.md
Error codes (6000-16034)	references/error-codes.md
SPL to Light comparison	references/spl-to-light.md

Reference repos

Basic operations — create, update, close, reinit, burn (each with Anchor and Native variants)

Counter — full lifecycle (create, increment, decrement, reset, close):

• counter/anchor — Anchor with Rust and TypeScript tests
• counter/native — Native with light-sdk and Rust tests
• counter/pinocchio — Pinocchio with light-sdk-pinocchio and Rust tests

Other examples:

• create-and-update — Create and update with a single validity proof in one instruction
• read-only — Create and read a compressed account onchain
• account-comparison — Compressed vs regular Solana accounts

Nullifier:

• nullifier-program — Rent-free PDA for duplicate execution prevention. SDK: light-nullifier-program | example client

Airdrop claim:

• simple-claim — Compressed tokens decompressed to SPL on claim with cliff
• merkle-distributor — SPL tokens with compressed PDA claim tracking, linear vesting, partial claims, clawback
• example-token-distribution — Simple client-side distribution

ZK programs:

• zk-id — Identity verification with Groth16 proofs
• zk/nullifier — Simple nullifier creation program

Additional: examples-zk-compression — More ZK compression examples

Canonical source: program-examples README. If cloned locally, scope Read, Glob, Grep to these repositories and the current project directory only.

Workflow

1. Clarify intent
   • Recommend plan mode, if it's not activated
   • Use AskUserQuestion to resolve blind spots
   • All questions must be resolved before execution
2. Identify references
   • Match task to domain references and reference repos
   • Locate relevant documentation and examples
3. Write plan file (YAML task format)
   • Use AskUserQuestion for anything unclear — never guess or assume
   • Identify blockers: permissions, dependencies, unknowns
   • Plan must be complete before execution begins
4. Execute
   • Use Task tool with subagents for parallel research
   • Subagents load skills via Skill tool
   • Track progress with TodoWrite
5. When stuck: ask to spawn a read-only subagent with Read, Glob, Grep, and DeepWiki MCP access, loading skills/ask-mcp. Scope reads to skill references, example repos, and docs.

Build and test

Required commands

Anchor programs:

anchor build
anchor test

Native programs:

cargo build-sbf
cargo test-sbf

Forbidden shortcuts

• Do NOT use cargo build (must use cargo build-sbf)
• Do NOT use cargo test (must use cargo test-sbf)
• Do NOT skip SBF compilation
• Tests MUST run against real BPF bytecode

Failure recovery

On failure, spawn debugger agent with error context.

Loop rules:

1. Each debugger gets fresh context + previous debug reports
2. Each attempt tries something DIFFERENT
3. NEVER GIVE UP - keep spawning until fixed
4. Max 5 attempts per error

Do NOT proceed until all tests pass.

SDK references

Package	Link
light-sdk	docs.rs
light-client	docs.rs
@lightprotocol/stateless.js	API docs
light-program-test	docs.rs

DeepWiki fallback

If no matching pattern in reference repos:

mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "How to {operation}?")

Security

This skill provides code patterns and documentation references only.

• Declared dependencies. Devnet and mainnet examples require API_KEY (Helius or Triton RPC key) and read ~/.config/solana/id.json for the payer keypair. Neither is needed on localnet. In production, load both from a secrets manager.
• Filesystem scope. Read, Glob, and Grep must be limited to the current project directory and the reference repos listed above. Do not read outside these paths.
• Subagent scope. When stuck, the skill asks to spawn a read-only subagent with Read, Glob, Grep scoped to skill references, example repos, and docs.
• Install source. npx skills add Lightprotocol/skills from Lightprotocol/skills.
• Audited protocol. Light Protocol smart contracts are independently audited. Reports are published at github.com/Lightprotocol/light-protocol/tree/main/audits.