light-protocol

Light Protocol 开发指南

借助 Light Protocol 在 Solana 上构建可扩展且经济高效的应用。Light Protocol 是一款基础设施平台，可实现免租代币和账户，同时具备 L1 级性能与安全性。

概览

Light Protocol 提供两项互补技术：

• ZK Compression：使用零知识证明创建免租的压缩代币和 PDA。利用 Merkle 树和有效性证明高效存储状态。
• Light Token Program：一种高性能代币标准，与 SPL 代币相比，可将铸币和代币账户的成本降低 200 倍。

主要优势

优势	说明
成本降低 200 倍	压缩代币账户的成本约为 5,000 lamports，而 SPL 代币约为 2,000,000 lamports
账户免租	代币或 PDA 无需预先支付免租押金
L1 安全性	所有执行和状态均保留在 Solana 主网上
完全可组合	可与现有 Solana 程序和钱包（Phantom、Backpack）配合使用

程序 ID

程序	地址	说明
Light System Program	SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7	核心系统程序
Light Token Program	cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m	压缩代币操作
Account Compression	compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq	账户压缩程序

快速入门

安装

# Install TypeScript SDKs
npm install @lightprotocol/stateless.js @lightprotocol/compressed-token

# Install CLI for local development
npm install -g @lightprotocol/zk-compression-cli

RPC 设置

Light Protocol 需要启用了 ZK Compression 的 RPC。请使用 Helius：

import { Rpc, createRpc } from "@lightprotocol/stateless.js";

// Mainnet
const rpc = createRpc(
  "https://mainnet.helius-rpc.com?api-key=<YOUR_API_KEY>",
  "https://mainnet.helius-rpc.com?api-key=<YOUR_API_KEY>"
);

// Devnet
const devnetRpc = createRpc(
  "https://devnet.helius-rpc.com?api-key=<YOUR_API_KEY>",
  "https://devnet.helius-rpc.com?api-key=<YOUR_API_KEY>"
);

基本设置

import { Rpc, createRpc } from "@lightprotocol/stateless.js";
import {
  createMint,
  mintTo,
  transfer,
} from "@lightprotocol/compressed-token";
import { Keypair, PublicKey } from "@solana/web3.js";

// Initialize RPC connection
const rpc = createRpc(process.env.RPC_ENDPOINT!, process.env.RPC_ENDPOINT!);

// Load wallet
const payer = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(process.env.PRIVATE_KEY!))
);

console.log("Connected to Light Protocol");
console.log("Wallet:", payer.publicKey.toBase58());

---

ZK Compression

ZK Compression 使用零知识证明实现免租的压缩代币。压缩账户存储在 Merkle 树中，并通过有效性证明进行验证。

创建压缩代币铸币账户

import { createMint } from "@lightprotocol/compressed-token";
import { Keypair } from "@solana/web3.js";

const payer = Keypair.generate();
const mintAuthority = payer;

// Create mint with token pool for compression
const { mint, transactionSignature } = await createMint(
  rpc,
  payer,           // Fee payer
  mintAuthority.publicKey,  // Mint authority
  9,               // Decimals
);

console.log("Mint created:", mint.toBase58());
console.log("Transaction:", transactionSignature);

铸造压缩代币

import { mintTo } from "@lightprotocol/compressed-token";

const recipient = new PublicKey("...");
const amount = 1_000_000_000; // 1 token with 9 decimals

const transactionSignature = await mintTo(
  rpc,
  payer,           // Fee payer
  mint,            // Mint with token pool
  recipient,       // Recipient address
  mintAuthority,   // Mint authority (signer)
  amount,          // Amount to mint
);

console.log("Minted:", transactionSignature);

向多个接收方铸造

const recipients = [
  new PublicKey("recipient1..."),
  new PublicKey("recipient2..."),
  new PublicKey("recipient3..."),
];

const amounts = [
  1_000_000_000,
  2_000_000_000,
  3_000_000_000,
];

const transactionSignature = await mintTo(
  rpc,
  payer,
  mint,
  recipients,      // Array of recipients
  mintAuthority,
  amounts,         // Array of amounts (must match recipients length)
);

转移压缩代币

import { transfer } from "@lightprotocol/compressed-token";

const recipient = new PublicKey("...");
const amount = 500_000_000; // 0.5 tokens

const transactionSignature = await transfer(
  rpc,
  payer,           // Fee payer
  mint,            // Mint with token pool
  amount,          // Amount to transfer
  sender,          // Token owner (signer)
  recipient,       // Destination address
);

console.log("Transferred:", transactionSignature);

注意：压缩代币转移采用消耗并创建的模式。输入账户会被消耗，并创建余额已更新的新输出账户。

压缩 SPL 代币

将现有 SPL 代币转换为压缩格式：

import { compress, compressSplTokenAccount } from "@lightprotocol/compressed-token";

// Compress specific amount to a recipient
const transactionSignature = await compress(
  rpc,
  payer,
  mint,
  amount,
  owner,           // SPL token owner
  recipient,       // Compressed token recipient
  tokenAccount,    // Source SPL token account
);

// Compress entire SPL token account (reclaim rent)
const tx = await compressSplTokenAccount(
  rpc,
  payer,
  mint,
  owner,
  tokenAccount,
  // Optional: amount to keep in SPL format
);

解压缩为 SPL 代币

将压缩代币转换回 SPL 格式：

import { decompress } from "@lightprotocol/compressed-token";

const transactionSignature = await decompress(
  rpc,
  payer,
  mint,
  amount,
  owner,           // Compressed token owner (signer)
  recipient,       // SPL token recipient
);

查询压缩账户

// Get all compressed token accounts for an owner
const tokenAccounts = await rpc.getCompressedTokenAccountsByOwner(
  owner.publicKey,
  { mint }
);

console.log("Token accounts:", tokenAccounts.items.length);

// Calculate total balance
const totalBalance = tokenAccounts.items.reduce(
  (sum, account) => sum + BigInt(account.parsed.amount),
  BigInt(0)
);
console.log("Total balance:", totalBalance.toString());

// Get compressed account balance
const balance = await rpc.getCompressedTokenAccountBalance(accountHash);

// Get validity proof for transaction
const proof = await rpc.getValidityProof(compressedAccountHashes);

为现有铸币账户创建代币池

为现有 SPL 铸币账户添加压缩支持：

import { createTokenPool } from "@lightprotocol/compressed-token";

// Add token pool to existing SPL mint
// Note: Does NOT require mint authority
const transactionSignature = await createTokenPool(
  rpc,
  payer,           // Fee payer
  existingMint,    // Existing SPL mint
);

---

Light Token Program

Light Token Program 是一种独立的高性能代币标准，无需 ZK 证明即可降低成本。它针对高频操作路径进行了优化，并支持与 SPL 代币互操作的包装和解包。

与 ZK Compression 的主要区别

特性	ZK Compression	Light Token Program
技术	零知识证明	优化的代币标准
用例	压缩代币/PDA	高性能代币
计算单元	较高（证明验证）	较低（优化的高频操作路径）
互操作性	压缩/解压缩 SPL	包装/解包 SPL 和 Token-2022

创建 Light Token 铸币账户

import { createLightMint } from "@lightprotocol/light-token";

const { mint, transactionSignature } = await createLightMint(
  rpc,
  payer,
  mintAuthority.publicKey,
  9,  // decimals
);

console.log("Light mint created:", mint.toBase58());

铸造到 Light-ATA

import { mintToLightAta } from "@lightprotocol/light-token";

const transactionSignature = await mintToLightAta(
  rpc,
  payer,
  mint,
  recipient,
  mintAuthority,
  amount,
);

将 SPL 包装为 Light Token

import { wrapSpl } from "@lightprotocol/light-token";

// Wrap SPL tokens to Light tokens
const transactionSignature = await wrapSpl(
  rpc,
  payer,
  mint,
  amount,
  owner,
  splTokenAccount,
);

将 Light Token 解包为 SPL

import { unwrapToSpl } from "@lightprotocol/light-token";

// Unwrap Light tokens back to SPL
const transactionSignature = await unwrapToSpl(
  rpc,
  payer,
  mint,
  amount,
  owner,
  recipient,  // SPL token account
);

---

JSON RPC 方法

Light Protocol 为压缩账户提供了 21 种专用 RPC 方法。主要方法：

方法	描述
getCompressedAccount	按地址或哈希获取压缩账户
getCompressedAccountsByOwner	获取某个所有者的全部压缩账户
getCompressedTokenAccountsByOwner	获取某个所有者的全部压缩代币账户
getCompressedTokenAccountBalance	获取代币账户的余额
getCompressedTokenBalancesByOwner	获取某个所有者的全部代币余额
getCompressedMintTokenHolders	获取某个压缩 Mint 的全部持有者
getValidityProof	获取压缩账户的 ZK 证明
getMultipleCompressedAccounts	批量获取压缩账户
getTransactionWithCompressionInfo	获取包含已解析压缩数据的交易
getIndexerHealth	检查索引器状态

完整文档请参阅 resources/json-rpc-methods.md。

---

最佳实践

交易限制

• 每笔交易最多包含 4 个压缩账户：将大型操作拆分为多笔交易
• 计算单元预算：为证明验证增加额外的计算单元

import { ComputeBudgetProgram } from "@solana/web3.js";

// Add compute budget for complex transactions
const modifyComputeUnits = ComputeBudgetProgram.setComputeUnitLimit({
  units: 300_000,
});

批量操作

// Process multiple recipients in batches
async function batchMint(
  recipients: PublicKey[],
  amounts: number[],
  batchSize = 4
) {
  const results = [];

  for (let i = 0; i < recipients.length; i += batchSize) {
    const batchRecipients = recipients.slice(i, i + batchSize);
    const batchAmounts = amounts.slice(i, i + batchSize);

    const sig = await mintTo(
      rpc,
      payer,
      mint,
      batchRecipients,
      mintAuthority,
      batchAmounts,
    );

    results.push(sig);
  }

  return results;
}

错误处理

try {
  const signature = await transfer(rpc, payer, mint, amount, sender, recipient);
  console.log("Success:", signature);
} catch (error) {
  if (error.message.includes("TokenPool not found")) {
    // Create token pool first
    await createTokenPool(rpc, payer, mint);
  } else if (error.message.includes("Insufficient balance")) {
    // Check balance before transfer
    const accounts = await rpc.getCompressedTokenAccountsByOwner(sender.publicKey, { mint });
    console.log("Available balance:", accounts.items);
  } else {
    throw error;
  }
}

委托

import { approve, transferDelegated } from "@lightprotocol/compressed-token";

// Approve delegate
const approveSig = await approve(
  rpc,
  payer,
  mint,
  amount,
  owner,           // Token owner
  delegate,        // Delegate public key
);

// Transfer as delegate
const transferSig = await transferDelegated(
  rpc,
  payer,
  mint,
  amount,
  delegate,        // Delegate (signer)
  recipient,
);

---

资源

官方文档

• ZK Compression 文档
• Light Protocol 白皮书

GitHub 仓库

• Light Protocol - 主仓库
• Node.js 客户端示例
• Web 客户端示例

社区

• Discord - Light Protocol Discord
• Helius Discord - RPC 提供商支持

钱包支持

• Phantom - 原生支持压缩代币
• Backpack - 原生支持压缩代币

---

技能结构

light-protocol/
├── SKILL.md                    # This file
├── resources/
│   ├── program-addresses.md    # Program IDs, state trees, RPC endpoints
│   ├── json-rpc-methods.md     # All 21 RPC methods documented
│   ├── sdk-reference.md        # TypeScript SDK reference
│   └── github-repos.md         # Official repositories
├── examples/
│   ├── setup/
│   │   └── example.ts          # Basic setup
│   ├── zk-compression/
│   │   ├── create-mint.ts      # Create compressed mint
│   │   ├── mint-tokens.ts      # Mint compressed tokens
│   │   ├── transfer-tokens.ts  # Transfer compressed tokens
│   │   ├── compress-spl.ts     # Compress SPL tokens
│   │   └── decompress.ts       # Decompress to SPL
│   ├── light-token-program/
│   │   ├── create-light-mint.ts
│   │   ├── mint-light-tokens.ts
│   │   └── wrap-unwrap.ts
│   ├── querying/
│   │   └── fetch-accounts.ts   # Query compressed accounts
│   └── advanced/
│       ├── batch-operations.ts # Multi-recipient operations
│       └── delegation.ts       # Approve and delegate transfers
├── templates/
│   └── setup.ts                # Complete starter template
└── docs/
    └── troubleshooting.md      # Common issues and solutions