lightprotocol/compressed-pda

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 (100 bytes) | ~1,600,000 lamports | ~15,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

How it works

A program derives a compressed PDA like a regular PDA, then invokes the Light System Program (not the System Program) via CPI to create and update it. Creating an account requires a validity proof that the derived address does not yet exist; updates, closes, and burns require a proof that the account exists. Clients fetch proofs with getValidityProof from an RPC provider that supports ZK compression. The program loads accounts with LightAccount::new_init() (create) or LightAccount::new_mut() (update) and builds the CPI manually.

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 |

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.