如何使用 getProgramAccounts

​

常见用例

• 查找铸币的所有代币账户： 发现特定 SPL 代币的所有持有者。
• 检索用户特定数据： 获取程序为特定用户创建的所有账户（例如，用户在 DeFi 协议中的头寸，或他们在游戏中的状态）。
• 列出自定义账户类型的所有实例： 如果您的程序定义了特定账户结构，getProgramAccounts 可以找到该结构的所有实例。
• 监控程序状态： 观察与程序相关的所有账户，以跟踪其整体状态或活动。
• 构建探查器和分析工具： 聚合有关程序及其关联账户的数据。

​

请求参数

1. programId (string, 必需):
   • 您要获取其账户的程序的 base-58 编码公钥。
   • 示例："TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"（用于 SPL 代币程序）。
2. options (object, 可选项): 包含以下字段的配置对象：
   • commitment (string): 指定承诺级别（例如，"finalized", "confirmed"）。
   • encoding (string): 每个返回账户中data字段的编码。默认为"base64"。
     • "base58": 较慢的二进制数据替代方案。
     • "base64": 标准的base64编码用于二进制数据。
     • "base64+zstd": base64编码的zstd压缩二进制数据。
     • "jsonParsed": 如果RPC节点有程序账户类型的解析器（例如，SPL Token，Stake），则data字段将是一个结构化的JSON对象。这对于可读性和易用性非常推荐。
   • filters (array): 要应用于账户的过滤器对象数组。这对于性能和相关性至关重要。你最多可以使用4个过滤器。常见的过滤器包括:
     • dataSize (object):
       • dataSize (u64): 按字节过滤账户的数据长度。示例: { "dataSize": 165 } (用于SPL Token账户)。
     • memcmp (object): 内存比较。将账户数据的切片与提供的字节进行比较。
       • offset (usize): 开始比较的账户数据的字节偏移量。
       • bytes (string): 要匹配的字节的base-58编码字符串。字节字符串必须小于129字节。
       • 示例: 要查找特定铸币的代币账户，可以使用memcmp与offset: 0 (其中铸币地址存储在代币账户中) 和 bytes设置为铸币的公钥。
   • dataSlice (object): 仅返回每个账户数据的特定切片。当您只需要部分数据时，这对大账户非常有用。
     • offset (usize): 开始切片的字节偏移量。
     • length (usize): 要返回的字节数。
     • 注意: dataSlice主要用于二进制编码，而非jsonParsed。
   • withContext (boolean): 如果true, 则响应将是一个RpcResponse对象，包含一个context (带有slot) 和 value (账户数组)。如果false或省略，通常只返回账户数组。行为可能因RPC提供商而略有不同。
   • minContextSlot (u64): 可以评估请求的最小槽位。

​

响应结构

• pubkey (string): 账户的 base-58 编码公钥。
• account (object):
  • lamports (u64): 账户以 lamports 为单位的余额。
  • owner (string): 拥有此账户的程序的 base-58 编码公钥（这将是您查询的 programId）。
  • data (string, array, 或 object): 根据 encoding 参数格式化的账户数据。
    • 对于 jsonParsed: 表示反序列化账户状态的 JSON 对象。
    • 对于 base64: 一个数组 ["encoded_string", "base64"]。
  • executable (boolean): 账户是否可执行（即自身为程序）。
  • rentEpoch (u64): 此账户下次欠租的纪元。
  • space (u64, 可选): 账户数据的字节长度。如果数据是缓冲区，或作为解析结构的一部分，有时称为 data.length。

​

示例

​

1. 查找特定铸币（USDC）的所有代币账户

# Replace <api-key> with your Helius API key
# USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Token Program ID: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "encoding": "jsonParsed",
        "filters": [
          { "dataSize": 165 },
          {
            "memcmp": {
              "offset": 0, 
              "bytes": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          }
        ]
      }
    ]
  }'

​

2. 查找由特定钱包拥有的所有代币账户

# Replace <api-key> with your Helius API key
# Example Wallet Address: Helioo21241PANoNdeG55722hgUnp2VawDgsz2g
# Token Program ID: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "encoding": "jsonParsed",
        "filters": [
          { "dataSize": 165 },
          {
            "memcmp": {
              "offset": 32, 
              "bytes": "Helioo21241PANoNdeG55722hgUnp2VawDgsz2g"
            }
          }
        ]
      }
    ]
  }'

​

高级过滤

// Example filtering by memcmp (memory comparison)
const response = await fetch(
  "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "getProgramAccounts",
      params: [
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Solana Token Program
        {
          encoding: "jsonParsed",
          filters: [
            {
              dataSize: 165, // Size of token account data
            },
            {
              memcmp: {
                offset: 32, // Location of owner address in the token account
                bytes: "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
              },
            },
          ],
        },
      ],
    }),
  }
);
const data = await response.json();
console.log("Filtered program accounts data:", data);

​

过滤器类型

• memcmp: 过滤在特定偏移处匹配特定模式的账户
• dataSize: 按账户的精确数据大小进行过滤
• 多重过滤器：所有条件必须满足（逻辑与）

​

开发者提示

• 性能： getProgramAccounts 在没有过滤器或程序拥有许多账户时，可能对RPC节点资源消耗较大。务必使用过滤器（dataSize, memcmp）和 dataSlice 来减少查询范围和响应大小。
• 大结果集： 对于返回许多结果的查询，响应可能会被截断或超时。使用过滤减少范围，或考虑使用getProgramAccountsV2 进行分页支持。
• 速率限制： 注意RPC提供商的速率限制，因为频繁或大量的 getProgramAccounts 调用可能会达到这些限制。
• 数据布局知识： 有效使用 memcmp 需要了解您正在查询的账户数据的字节布局。
• jsonParsed 可用性： jsonParsed 编码依赖于RPC节点是否有特定程序账户类型的解析器。对于常见程序，如SPL Token，广泛支持。

​

大数据集的分页

• 基于游标的分页: 设置 limit（1-10,000）并使用 paginationKey 导航结果
• 增量更新: 使用 changedSinceSlot 仅获取自特定槽以来修改的账户
• 更好的性能: 防止超时和减少内存使用
• 分页行为: 只有在不返回账户时才表示分页结束。由于过滤，返回的账户可能少于限制 - 继续分页直到 paginationKey 为null

// Example: Paginated query for all token accounts
const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "getProgramAccountsV2",
    params: [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        encoding: "base64",
        filters: [{ dataSize: 165 }],
        limit: 5000
      }
    ]
  })
});

const data = await response.json();
console.log(`Found ${data.result.accounts.length} accounts`);
if (data.result.paginationKey) {
  console.log("More results available, use paginationKey for next page");
  // Continue pagination even if fewer than limit accounts were returned
} else {
  console.log("End of pagination - no more accounts available");
}

​

相关方法