solana-compression

压缩 PDA 程序

通过 CPI 调用 Light System Program，构建使用压缩账户的 Solana 程序。无需满足租金豁免要求。

创建成本	Solana 账户	压缩账户
PDA（128 字节）	~1,100,000 lamports	~5,000 lamports

何时使用压缩 PDA

• 每用户状态（个人资料、游戏状态、凭证）
• DePIN 设备注册
• 基于 Nullifier 的双花防护
• 不常访问的账户

选择方案

标准	Light-PDA（简单）	压缩 PDA（高级）
适用场景	现有 Anchor 账户的免租金版本	使用 ZK 证明的自定义压缩状态
技能	light-sdk（Anchor 宏模式）	本技能（solana-compression）
宏	#[light_account(init)]	LightAccount::new_init() 手动 CPI
依赖项	light-sdk、light-compressible	light-sdk、light-sdk-types

如果你只需要免租金的 Anchor 账户，请改用 light-sdk 技能。本技能适用于需要手动 CPI 调用 Light System Program 的程序（自定义压缩状态、ZK 证明、地址派生）。

客户端与程序交互流程

 ├─ 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.

领域参考

主题	参考资料
程序操作（创建、更新、关闭、销毁、重新初始化）	references/compressed-pdas.md
客户端 SDK（TypeScript + Rust）	references/client.md
Nullifier PDA（双花防护）	references/nullifier-pdas.md
错误代码（6000-16034）	references/error-codes.md
SPL 与 Light 对比	references/spl-to-light.md

参考仓库

基本操作 — 创建、更新、关闭、重新初始化、销毁（每种操作都提供 Anchor 和 Native 变体）

计数器 — 完整生命周期（创建、递增、递减、重置、关闭）：

• counter/anchor — 使用 Rust 和 TypeScript 测试的 Anchor
• counter/native — 使用 light-sdk 和 Rust 测试的 Native
• counter/pinocchio — 使用 light-sdk-pinocchio 和 Rust 测试的 Pinocchio

其他示例：

• create-and-update — 在一条指令中使用单个有效性证明创建并更新
• read-only — 在链上创建并读取压缩账户
• account-comparison — 压缩与常规 Solana 账户

Nullifier：

• nullifier-program — 用于防止重复执行的免租金 PDA。SDK：light-nullifier-program | 示例客户端

空投领取：

• simple-claim — 领取时将压缩代币解压为 SPL 代币，并设有锁定期
• merkle-distributor — SPL 代币，使用压缩 PDA 跟踪领取情况，支持线性归属、部分领取和追回
• example-token-distribution — 简单的客户端分发

ZK 程序：

• zk-id — 使用 Groth16 证明进行身份验证
• zk/nullifier — 简单的 nullifier 创建程序

更多示例： examples-zk-compression — 更多 ZK 压缩示例

权威来源：program-examples README。如果已在本地克隆，请仅将 Read、Glob、Grep 的范围限定为这些仓库和当前项目目录。

工作流

1. 明确意图
   • 如果尚未启用，建议使用计划模式
   • 使用 AskUserQuestion 消除盲点
   • 执行前必须解决所有问题
2. 确定参考资料
   • 将任务与领域参考资料和参考仓库匹配
   • 查找相关文档和示例
3. 编写计划文件（YAML 任务格式）
   • 对于任何不明确之处，使用 AskUserQuestion 提问——切勿猜测或臆断
   • 识别阻碍因素：权限、依赖项、未知事项
   • 开始执行前必须完成计划
4. 执行
   • 使用 Task 工具和子 Agent 并行调研
   • 子 Agent 通过 Skill 工具加载技能
   • 使用 TodoWrite 跟踪进度
5. 遇到困难时：请求启动只读子 Agent，使用 Read、Glob、Grep 和 DeepWiki MCP 访问权限，并加载 skills/ask-mcp。读取范围限定为技能参考资料、示例仓库和文档。

构建和测试

必需命令

Anchor 程序：

anchor build
anchor test

Native 程序：

cargo build-sbf
cargo test-sbf

禁止使用的捷径

• 切勿使用 cargo build（必须使用 cargo build-sbf）
• 切勿使用 cargo test（必须使用 cargo test-sbf）
• 不得跳过 SBF 编译
• 测试必须针对真实的 BPF 字节码运行

失败恢复

发生故障时，使用错误上下文启动调试器 Agent。

循环规则：

1. 每个调试器都使用全新的上下文和之前的调试报告
2. 每次尝试都要采用不同的方法
3. 绝不放弃——持续启动调试器，直到修复问题
4. 每个错误最多尝试 5 次

所有测试通过后才能继续。

SDK 参考

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

DeepWiki 备用方案

如果参考仓库中没有匹配的模式：

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

安全

此技能仅提供代码模式和文档参考。

• 声明的依赖项。 Devnet 和 mainnet 示例需要 API_KEY（Helius 或 Triton RPC 密钥），并会读取 ~/.config/solana/id.json 中的付款方密钥对。Localnet 无需这两项。在生产环境中，请从密钥管理器加载这两项。
• 文件系统范围。 Read、Glob 和 Grep 必须仅限于当前项目目录和上方列出的参考仓库。不得读取这些路径之外的内容。
• 子 Agent 范围。 陷入困境时，此技能会要求启动一个只读子 Agent，并将其 Read、Glob、Grep 的范围限定为技能参考资料、示例仓库和文档。
• 安装来源。 从 Lightprotocol/skills 运行 npx skills add Lightprotocol/skills。
• 经过审计的协议。 Light Protocol 智能合约已经过独立审计。审计报告发布于 github.com/Lightprotocol/light-protocol/tree/main/audits。