> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana 隐私环 API

> 查询 Solana 隐私环的加密 UTXO、屏蔽交易历史记录、Merkle 证明和公开用户注册记录。

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

## 公开余额和私有余额

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

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

有关私有余额的存储和花费方式，请参阅[私有状态和 UTXO](https://www.helius.dev/docs/zh/privacy/concepts/utxo.md)。

## 端点和身份验证

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

```bash theme={"system"}
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。

进行本地开发时，请先启动[本地堆栈](https://www.helius.dev/docs/zh/privacy/endpoints.md)，然后使用 `http://127.0.0.1:8784/{method}`。

## 方法

> [card] [getEncryptedUtxosByTags](https://www.helius.dev/docs/zh/api-reference/privacy/getencryptedutxosbytags.md)
>
> 按查看标签或环发现加密输出。

> [card] [getShieldedTransactionsByTags](https://www.helius.dev/docs/zh/api-reference/privacy/getshieldedtransactionsbytags.md)
>
> 按查看标签或环查询屏蔽交易历史记录。

> [card] [getShieldedTransactionsBySignature](https://www.helius.dev/docs/zh/api-reference/privacy/getshieldedtransactionsbysignature.md)
>
> 检索一笔 Solana 交易的屏蔽事件。

> [card] [getShieldedTransactionsByNullifiers](https://www.helius.dev/docs/zh/api-reference/privacy/getshieldedtransactionsbynullifiers.md)
>
> 查找花费了所提供无效标识符的交易。

> [card] [getMerkleProofs](https://www.helius.dev/docs/zh/api-reference/privacy/getmerkleproofs.md)
>
> 获取状态树承诺的包含证明。

> [card] [getNonInclusionProofs](https://www.helius.dev/docs/zh/api-reference/privacy/getnoninclusionproofs.md)
>
> 获取无效标识符值的非包含证明。

> [card] [getNullifierQueueElements](https://www.helius.dev/docs/zh/api-reference/privacy/getnullifierqueueelements.md)
>
> 按序列顺序读取队列中的无效标识符。

> [card] [getUserRecords](https://www.helius.dev/docs/zh/api-reference/privacy/getuserrecords.md)
>
> 查询公开的屏蔽地址注册记录。

## 分页

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

```json theme={"system"}
{
  "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` 使用基于序列的分页；请参阅其[方法页面](https://www.helius.dev/docs/zh/api-reference/privacy/getnullifierqueueelements.md)。

## 数据编码

| 值 | 编码 |
| - | - |
| 公钥、哈希、承诺、查看标签、无效标识符 | 表示 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 表示请求受到速率限制；请参阅[速率限制](https://www.helius.dev/docs/zh/billing/rate-limits.md)。有关 API 密钥设置，请参阅[身份验证](https://www.helius.dev/docs/zh/api-reference/authentication.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.