Solana 隐私环 API 参考

Solana 隐私环 API 用于查询隐私索引器。它返回加密状态和公开交易元数据。你的钱包会解密有效载荷，以读取私有余额和历史记录。有关相关概念，请参阅隐私概述；有关存款、转账和提款流程，请参阅 SDK。

公开余额和私有余额

私有余额存储在 UTXO（未花费交易输出）中。UTXO 不是 Solana 账户。

	公开余额	私有余额
余额	Solana 账户中的 Lamport，或 SPL 代币账户中的 `amount`	一种资产的所有未花费 UTXO 之和
可见性	链上公开	链上加密
发现代币账户或输出	`getTokenAccountsByOwner` 返回某个地址拥有的 SPL 代币账户	`getEncryptedUtxosByTags` 返回与查看标签或环匹配的加密输出
读取余额	对于 SOL，使用 `getBalance`；对于 SPL 代币账户，使用 `getTokenAccountBalance`	你的钱包会解密输出，检查哪些输出尚未花费，并计算每种资产的金额总和

有关私有余额的存储和花费方式，请参阅私有状态和 UTXO。

端点和身份验证

使用你的 Helius API 密钥，向该方法的路径发送 JSON-RPC 2.0 请求：

curl --request POST \
  --url "https://devnet.helius-rpc.com/v1/spr/getUserRecords?api-key=YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getUserRecords",
    "params": {
      "owners": ["11111111111111111111111111111111"]
    }
  }'

method 必须与 URL 的最后一个路径段匹配。方法路径接受单个请求；批量请求、重复的 method 字段以及路径与请求正文不匹配，都会在执行前返回 HTTP 400。进行本地开发时，请先启动本地堆栈，然后使用 http://127.0.0.1:8784/{method}。

方法

getEncryptedUtxosByTags

按查看标签或环发现加密输出。

getShieldedTransactionsByTags

按查看标签或环查询屏蔽交易历史记录。

getShieldedTransactionsBySignature

检索一笔 Solana 交易的屏蔽事件。

getShieldedTransactionsByNullifiers

查找花费了所提供无效标识符的交易。

getMerkleProofs

获取状态树承诺的包含证明。

getNonInclusionProofs

获取无效标识符值的非包含证明。

getNullifierQueueElements

按序列顺序读取队列中的无效标识符。

getUserRecords

查询公开的屏蔽地址注册记录。

分页

getEncryptedUtxosByTags、getShieldedTransactionsByTags 和 getShieldedTransactionsByNullifiers 在 result 中返回一页结果：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "context": { "slot": 4242, "blockTime": 1730000000 },
    "data": [],
    "paginationToken": null
  }
}

data 按 Solana 交易对结果进行分组，并按槽位和签名升序排列。加密 UTXO 方法在每个组中使用 outputs 数组；交易历史记录方法使用 events 数组。
limit 以 Solana 交易为计数单位，取值范围为 1 到 1,000，默认为 1,000。一笔交易中匹配的输出或事件会保留在同一页中。
将非空的 paginationToken 原样传回，并使用相同的标签或无效标识符、环和槽位筛选条件。持续请求，直到响应令牌为 null。
filters.slot 接受 gt、gte、lt 和 lte 边界。所提供的边界以 AND 方式组合。无上限读取到达空令牌后，保存该页的 context.slot，稍后将 filters.slot.gt 设置为该值以继续读取。受 lt 或 lte 限制的读取仅涵盖不超过该上限的槽位；应从该上限继续读取，而不是从 context.slot 继续。
设置 minContextSlot，以要求索引器至少已持久化到指定槽位。索引器还要求达到 paginationToken 的槽位，以及任何 gt 或 gte 筛选条件指定的槽位。如果索引器落后于其中任何一个槽位，它将返回错误 -32016 和 error.data.contextSlot；请等待索引器追上后重试。

历史记录响应还可以包含 outputTreeId，即最新的未暂停状态树 ID。如果不可用，则省略该字段。每个输出通过 outputContext.treeId 标识其所属的树。 getNullifierQueueElements 使用基于序列的分页；请参阅其方法页面。

数据编码

值	编码
公钥、哈希、承诺、查看标签、无效标识符	表示 32 字节的 Base58 字符串
Solana 交易签名	表示 64 字节的 Base58 字符串
密文有效载荷、`txViewingPk`、`salt`、注册表 `viewingPubkey`	Base64 字符串
`context.slot`	索引器已持久化的最高 Solana 槽位
`context.blockTime`	以秒为单位的 Unix 时间戳表示的区块时间

错误

读取 result 前，请检查 JSON-RPC 的 error 字段，即使 HTTP 状态码为 200 也应如此。

代码	含义
`-32600`	请求验证失败、未找到记录、已编入索引的证明根已过期，或请求的历史记录起点早于已编入索引的历史记录。无法读取的请求正文也会返回 `-32600` 和 HTTP 400。请读取 `message` 以了解原因。
`-32601`	方法未知，或方法路径在执行前拒绝了请求。路径拒绝使用 HTTP 400。
`-32602`	无法解析参数，例如密钥编码无效或限制值超出范围。
`-32603`	内部服务器错误。
`-32016`	索引器尚未达到 `minContextSlot`、分页令牌的槽位，或 `gt`/`gte` 槽位筛选条件指定的槽位。

HTTP 429 表示请求受到速率限制；请参阅速率限制。有关 API 密钥设置，请参阅身份验证。

开始使用

交易操作

发送交易

账户管理

Solana 隐私环 API

公开余额和私有余额

端点和身份验证

方法

getEncryptedUtxosByTags

getShieldedTransactionsByTags

getShieldedTransactionsBySignature

getShieldedTransactionsByNullifiers

getMerkleProofs

getNonInclusionProofs

getNullifierQueueElements

getUserRecords

分页

数据编码

错误

​公开余额和私有余额

​端点和身份验证

​方法

getEncryptedUtxosByTags

getShieldedTransactionsByTags

getShieldedTransactionsBySignature

getShieldedTransactionsByNullifiers

getMerkleProofs

getNonInclusionProofs

getNullifierQueueElements

getUserRecords

​分页

​数据编码

​错误

公开余额和私有余额

端点和身份验证

方法

分页

数据编码

错误