读取私密历史记录

使用专用的 RPC 方法从索引器读取加密交易。
只有用户或用户授权的人才能使用他们的查看密钥解密历史记录。
在钱包运行回填时使用：在钱包解锁、私密钱包打开、应用恢复、网络重新连接、流间隙或钱包恢复时。

与 getSignaturesForAddress 的比较

getSignaturesForAddress 返回公共签名。
RPC 返回公共历史。

开始使用

TypeScript 客户端
Rust 客户端

前提条件

TypeScript 示例需要 Node.js 24 或更高版本，pnpm 11.18.0，以及 Solana CLI。

pnpm add @heliuslabs/zolana@^0.3.1-alpha @solana/kit@^8.3.0

来源：sdk-libs/ts

连接到端点

Devnet
Localnet

pnpm install
cp .env.example .env

添加一个Helius API 密钥：

.env

API_KEY=YOUR_API_KEY
ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json

import { createZolanaClient } from "@heliuslabs/zolana";

const client = await createZolanaClient({
  solanaRpcUrl: "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY",
  indexerUrl: "https://d2xah7tnhdhcom.cloudfront.net",
  proverUrl: "https://d21ni15goiip6l.cloudfront.net",
});

示例默认使用 Solana CLI 钱包作为支付方。支付方必须持有 devnet SOL。请参阅如何获取 Devnet SOL。

在 localnet 上，SDK 启动本地测试验证器(:8899)、Photon 索引器(:8784)和证明器(:3001)，客户端自动连接到它们而无需配置端点。

cargo install --git https://github.com/helius-labs/zolana --tag v0.3.0-alpha zolana-cli
zolana dev start

import { createZolanaClient } from "@heliuslabs/zolana";

const client = await createZolanaClient({});

派生查看标签

import { createZolanaClient } from "@heliuslabs/zolana";

// The view tag is the sender's Solana public key in confidential rings.
// Used by the indexer to fetch the sender's UTXOs.
const senderViewTag =
  senderAddress.confidentialViewTag();

senderViewTag 是 senderAddress.confidentialViewTag()，发送者在机密环中的 Solana 公钥。索引器使用它返回匹配的加密输出。

从索引器获取交易输出

import { atSlot } from "@heliuslabs/zolana/client";

const depositResponse =
  await client.getShieldedTransactionsByTags(
    { tags: [senderViewTag] },
    atSlot(depositTx.slot),
  );

getShieldedTransactionsByTags 获取与 senderViewTag 关联的加密输出。
atSlot(depositTx.slot) 等待索引器在该槽位有存款。
索引器返回加密输出数据。它不解密私密历史。

解密为私密历史

import { Wallet } from "@heliuslabs/zolana";
import { decryptTransactions, LocalShieldedKeys } from "@heliuslabs/zolana/transaction";

const wallet = new Wallet({
  identity: senderAddress,
  registry: assets,
});
await decryptTransactions({
  wallet,
  keys: LocalShieldedKeys.fromKeypair(sender),
  transactions: depositResponse.transactions,
});
const history = wallet.privateTransactions();

LocalShieldedKeys.fromKeypair(sender) 提供发送方的密钥，用于本地解密。
decryptTransactions 解密匹配的输出，并将历史记录写入 Wallet。
wallet.privateTransactions() 读取已解密的历史记录。
decryptToBalances 仅返回余额。

示例响应：

[
  {
    id: { signature: "5x…", slot: 291044100n, index: 0n },
    kind: "deposit",
    direction: "inbound",
    status: "confirmed",
    asset: SOL_MINT,
    amount: 100_000_000n,
    counterpartyViewingPublicKey: undefined,
  },
]

查看概念以了解所有者标记和私密 Solana 代币账户的工作方式。

完整代码示例

克隆并运行示例：

git clone https://github.com/helius-labs/zolana-examples.git
cd zolana-examples/typescript-client
pnpm install
pnpm example examples/read_history.ts

这些示例使用了此处在 local/devnet 上运行的保密 Ring。

前提条件

Rust 示例需要 Rust 1.98.1 和 Solana CLI v4.0.2。请参阅 Solana 安装指南。

Cargo.toml

[dependencies]
zolana-client = { git = "https://github.com/helius-labs/zolana", tag = "v0.3.0-alpha", features = ["indexer-api", "solana-rpc"] }
zolana-interface = { git = "https://github.com/helius-labs/zolana", tag = "v0.3.0-alpha" }
zolana-program = { git = "https://github.com/helius-labs/zolana", tag = "v0.3.0-alpha" }
zolana-keypair = { git = "https://github.com/helius-labs/zolana", tag = "v0.3.0-alpha" }
zolana-transaction = { git = "https://github.com/helius-labs/zolana", tag = "v0.3.0-alpha" }
zolana-wallet = { git = "https://github.com/helius-labs/zolana", tag = "v0.3.0-alpha" }

来源：sdk-libs/client

连接到端点

Devnet
Localnet

添加一个Helius API 密钥:

.env

API_KEY=YOUR_API_KEY
ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json

use zolana_client::{SolanaRpc, ZolanaClient};
use zolana_interface::pda;

let tree = pda::tree(0);
let client = ZolanaClient::from_urls(
    SolanaRpc::new("https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY"),
    "https://d2xah7tnhdhcom.cloudfront.net",
    "https://d21ni15goiip6l.cloudfront.net",
)?;

这些示例默认使用 Solana CLI 钱包作为付款人。付款人必须持有 devnet SOL。请参阅如何获取 Devnet SOL。

cargo install --git https://github.com/helius-labs/zolana --tag v0.3.0-alpha zolana-cli
zolana dev start

use zolana_client::{SolanaRpc, ZolanaClient};
use zolana_interface::pda;

let tree = pda::tree(0);
let client = ZolanaClient::from_urls(
    SolanaRpc::new("http://127.0.0.1:8899"),
    "http://127.0.0.1:8784",
    "http://127.0.0.1:3001",
)?;

派生查看标签

use zolana_client::Rpc;

let sender_tag = sender_shielded_address.confidential_view_tag()?;

sender_tag 是 sender_shielded_address.confidential_view_tag()，发送者在机密环中的 Solana 公钥。索引器使用它返回匹配的加密输出。

从索引器获取交易输出

use zolana_client::{IndexerRpcConfig, Rpc};

let response = client.get_shielded_transactions_by_tags(
    vec![sender_tag],
    None,
    Some(50),
    Some(IndexerRpcConfig::at_slot(slot)),
)?;

get_shielded_transactions_by_tags 获取与 sender_tag 关联的加密输出。
IndexerRpcConfig::at_slot(slot) 等待索引器在该槽位有存款。
索引器返回加密输出数据。它不解密私密历史。

解密为私密历史

use anyhow::anyhow;
use zolana_wallet::{Wallet, DEFAULT_TAG_WINDOW};

let mut wallet = Wallet::new(sender.shielded_address()?, assets.clone())
    .map_err(|e| anyhow!("create wallet: {e:?}"))?;
wallet
    .sync(&sender, &response.transactions, 0, DEFAULT_TAG_WINDOW)
    .map_err(|e| anyhow!("decrypt sender transactions: {e:?}"))?;
let history = wallet.private_transactions();

sender 提供发送方的查看密钥，用于本地解密。
Wallet::sync 解密匹配的输出，并将历史记录写入 Wallet。
wallet.private_transactions() 读取已解密的历史记录。
decrypt_spendable 返回经过验证的余额和包含数据的 UTXO，而非交易历史记录。

示例响应：

[
    PrivateTransaction {
        id: PrivateTransactionId {
            signature: "5x…".into(),
            slot: 291044100,
            index: 0,
        },
        kind: PrivateTransactionKind::Deposit,
        direction: PrivateTransactionDirection::Inbound,
        status: PrivateTransactionStatus::Confirmed,
        asset: SOL_MINT,
        amount: 100_000_000,
        counterparty_viewing_pubkey: None,
    },
]

完整代码示例

克隆并运行示例：

git clone https://github.com/helius-labs/zolana-examples.git
cd zolana-examples/rust-client
cargo run -p rust-client-example --example read_history

开始使用

数据流与事件监听

数据 API 与 RPC

交易服务

发送交易

钱包即服务

隐私

资源

读取私密历史记录

开始使用

前提条件

派生查看标签

从索引器获取交易输出

解密为私密历史

完整代码示例

前提条件

派生查看标签

从索引器获取交易输出

解密为私密历史

完整代码示例

相关指南

读取私密余额

存款

转账

取款

没找到您要找的？

​开始使用

​前提条件

​派生查看标签

​从索引器获取交易输出

​解密为私密历史

​完整代码示例

​前提条件

​派生查看标签

​从索引器获取交易输出

​解密为私密历史

​完整代码示例

​相关指南

读取私密余额

存款

转账

取款

​没找到您要找的？

开始使用

前提条件

派生查看标签

从索引器获取交易输出

解密为私密历史

完整代码示例

前提条件

派生查看标签

从索引器获取交易输出

解密为私密历史

完整代码示例

相关指南

没找到您要找的？