Ler Histórico Privado

A leitura busca transações criptografadas do indexador com métodos RPC dedicados.
Apenas o usuário, ou qualquer pessoa que ele autorize, pode descriptografar o histórico com sua chave de visualização.
Use em qualquer lugar onde a carteira executa preenchimentos: ao desbloquear a carteira, abrir carteira privada, retomar aplicativo, reconectar rede, intervalo de streaming ou restaurar carteira.

Comparar com getSignaturesForAddress

getSignaturesForAddress retorna assinaturas públicas.
O RPC retorna o histórico público.

Introdução

Cliente TypeScript
Cliente Rust

Pré-requisitos

Os exemplos em TypeScript exigem Node.js 24 ou superior, pnpm 11.18.0 e o Solana CLI.

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

Fonte: sdk-libs/ts

Conectar aos Endpoints

Devnet
Localnet

pnpm install
cp .env.example .env

Adicione uma chave de API Helius:

.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",
});

Os exemplos usam a carteira Solana CLI como pagador por padrão. O pagador deve possuir SOL na devnet. Veja Como Obter SOL na Devnet.

No localnet, o SDK inicia o validador de teste local (:8899), o indexador Photon (:8784) e o provedor (:3001), e o cliente se conecta a eles automaticamente, sem a necessidade de configuração de endpoint.

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({});

Derivar a Tag de Visualização

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(), a chave pública Solana do remetente em anéis confidenciais. O indexador a utiliza para retornar saídas criptografadas correspondentes.

Buscar Saídas de Transação do Indexador

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

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

getShieldedTransactionsByTags busca as saídas criptografadas associadas com senderViewTag.
atSlot(depositTx.slot) espera até que o indexador tenha o depósito naquele slot.
O indexador retorna dados de saída criptografados. Ele não descriptografa o histórico privado.

Descriptografar para Histórico Privado

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) fornece as chaves do remetente para descriptografia local.
decryptTransactions descriptografa as saídas correspondentes e grava o histórico em Wallet.
wallet.privateTransactions() lê o histórico descriptografado.
decryptToBalances retorna apenas os saldos.

Resposta de Exemplo:

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

Veja Concepts para entender como funciona a marcação de proprietário e Contas de Token Privadas na Solana.

Exemplo de Código Completo

Clone e execute o exemplo:

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

Os exemplos usam um Ring confidencial em local/devnet aqui.

Pré-requisitos

Os exemplos em Rust exigem o Rust 1.98.1 e a CLI da Solana v4.0.2. Consulte o guia de instalação da 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" }

Fonte: sdk-libs/client

Conectar aos Endpoints

Devnet
Localnet

Adicione uma chave da 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",
)?;

Os exemplos usam a carteira Solana CLI como a pagadora por padrão. A pagadora deve possuir SOL de devnet. Veja Como Obter SOL de Devnet.

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",
)?;

Derivar a Tag de Visualização

use zolana_client::Rpc;

let sender_tag = sender_shielded_address.confidential_view_tag()?;

sender_tag é sender_shielded_address.confidential_view_tag(), a chave pública Solana do remetente em anéis confidenciais. O indexador a utiliza para retornar saídas criptografadas correspondentes.

Buscar Saídas de Transação do Indexador

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 busca as saídas criptografadas associadas com sender_tag.
IndexerRpcConfig::at_slot(slot) espera até que o indexador tenha o depósito naquele slot.
O indexador retorna dados de saída criptografados. Ele não descriptografa o histórico privado.

Descriptografar para Histórico Privado

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 fornece a chave de visualização do remetente para descriptografia local.
Wallet::sync descriptografa as saídas correspondentes e grava o histórico em Wallet.
wallet.private_transactions() lê o histórico descriptografado.
decrypt_spendable retorna saldos verificados e UTXOs com dados, mas não o histórico de transações.

Resposta de Exemplo:

[
    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,
    },
]

Exemplo Completo de Código

Clone e execute o exemplo:

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

Primeiros passos

Streaming de dados e escuta de eventos

APIs de dados e RPCs

Negociação

Envio de transações

Carteira como serviço

Privacidade

Recursos

Ler Histórico Privado

Introdução

Pré-requisitos

Derivar a Tag de Visualização

Buscar Saídas de Transação do Indexador

Descriptografar para Histórico Privado

Exemplo de Código Completo

Pré-requisitos

Derivar a Tag de Visualização

Buscar Saídas de Transação do Indexador

Descriptografar para Histórico Privado

Exemplo Completo de Código

Guias Relacionados

Ler um Saldo Privado

Depositar

Transferir

Retirar

Não encontrou o que estava procurando?

​Introdução

​Pré-requisitos

​Derivar a Tag de Visualização

​Buscar Saídas de Transação do Indexador

​Descriptografar para Histórico Privado

​Exemplo de Código Completo

​Pré-requisitos

​Derivar a Tag de Visualização

​Buscar Saídas de Transação do Indexador

​Descriptografar para Histórico Privado

​Exemplo Completo de Código

​Guias Relacionados

Ler um Saldo Privado

Depositar

Transferir

Retirar

​Não encontrou o que estava procurando?

Introdução

Pré-requisitos

Derivar a Tag de Visualização

Buscar Saídas de Transação do Indexador

Descriptografar para Histórico Privado

Exemplo de Código Completo

Pré-requisitos

Derivar a Tag de Visualização

Buscar Saídas de Transação do Indexador

Descriptografar para Histórico Privado

Exemplo Completo de Código

Guias Relacionados

Não encontrou o que estava procurando?