Leer el historial privado

La lectura obtiene las transacciones cifradas del indexador mediante métodos RPC específicos.
Solo el usuario, o cualquier persona que este autorice, puede descifrar el historial con su clave de visualización.
Úsala siempre que la cartera ejecute recuperaciones de datos históricos: al desbloquear la cartera, abrir la cartera privada, reanudar la aplicación, volver a conectarse a la red, detectar una interrupción en el flujo o restaurar la cartera.

Compare to getSignaturesForAddress

getSignaturesForAddress devuelve firmas públicas.
El RPC devuelve el historial público.

Comenzar

TypeScript Client
Rust Client

Requisitos previos

The TypeScript examples require Node.js 24 or later, pnpm 11.18.0, and the Solana CLI.

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

Source: sdk-libs/ts

Connect to Endpoints

Devnet
Localnet

pnpm install
cp .env.example .env

Add a Helius API key:

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

The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See How to Get Devnet SOL.

On localnet the SDK starts the local test validator (:8899), Photon indexer (:8784), and prover (:3001), and the client connects to them automatically without needing endpoint configuration.

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

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

const client = await createZolanaClient({});

Derivar la etiqueta de visualización

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 es senderAddress.confidentialViewTag(), la clave pública de Solana del remitente en anillos confidenciales. El indexador la usa para devolver las salidas cifradas coincidentes.

Obtener las salidas de transacciones del indexador

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

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

getShieldedTransactionsByTags obtiene las salidas cifradas asociadas con senderViewTag.
atSlot(depositTx.slot) espera hasta que el indexador tenga el depósito en ese slot.
El indexador devuelve datos de salida cifrados. No descifra el historial privado.

Descifrar para obtener el historial 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) proporciona las claves del remitente para el descifrado local.
decryptTransactions descifra las salidas coincidentes y escribe el historial en Wallet.
wallet.privateTransactions() lee el historial descifrado.
decryptToBalances solo devuelve saldos.

Respuesta de ejemplo:

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

Consulta Conceptos para saber cómo funcionan el etiquetado de propietarios y las cuentas privadas de tokens de Solana.

Ejemplo de código completo

Clona y ejecuta el ejemplo:

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

Los ejemplos usan un anillo confidencial en local/devnet aquí.

Requisitos previos

The Rust examples require Rust 1.98.1 and the Solana CLI v4.0.2. See the Solana installation guide.

Cargo.toml

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

Source: sdk-libs/client

Connect to Endpoints

Devnet
Localnet

Add a Helius API key:

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

The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See How to Get Devnet SOL.

cargo install --git https://github.com/helius-labs/zolana --tag v0.1.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",
    tree,
)?;

Derivar la etiqueta de visualización

use zolana_client::Rpc;

let sender_tag = sender_shielded_address.confidential_view_tag()?;

sender_tag es sender_shielded_address.confidential_view_tag(), la clave pública de Solana del remitente en anillos confidenciales. El indexador la usa para devolver las salidas cifradas coincidentes.

Obtener las salidas de transacciones del 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 obtiene las salidas cifradas asociadas con sender_tag.
IndexerRpcConfig::at_slot(slot) espera hasta que el indexador tenga el depósito en ese slot.
El indexador devuelve datos de salida cifrados. No descifra el historial privado.

Descifrar para obtener el historial privado

use anyhow::anyhow;
use zolana_transaction::{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 proporciona la clave de visualización del remitente para el descifrado local.
Wallet::sync descifra las salidas coincidentes y escribe el historial en Wallet.
wallet.private_transactions() lee el historial descifrado.
decrypt_transactions solo devuelve saldos.

Respuesta de ejemplo:

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

Ejemplo de código completo

Clona y ejecuta el ejemplo:

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

Primeros pasos

Streaming de datos y escucha de eventos

API de datos y RPC

Trading

Envío de transacciones

Billetera como servicio

Privacidad

Recursos

Leer el historial privado

Comenzar

Requisitos previos

Derivar la etiqueta de visualización

Obtener las salidas de transacciones del indexador

Descifrar para obtener el historial privado

Ejemplo de código completo

Requisitos previos

Derivar la etiqueta de visualización

Obtener las salidas de transacciones del indexador

Descifrar para obtener el historial privado

Ejemplo de código completo

Guías relacionadas

Read a Private Balance

Deposit

Transfer

Withdraw

Didn’t find what you were looking for?

​Comenzar

​Requisitos previos

​Derivar la etiqueta de visualización

​Obtener las salidas de transacciones del indexador

​Descifrar para obtener el historial privado

​Ejemplo de código completo

​Requisitos previos

​Derivar la etiqueta de visualización

​Obtener las salidas de transacciones del indexador

​Descifrar para obtener el historial privado

​Ejemplo de código completo

​Guías relacionadas

Read a Private Balance

Deposit

Transfer

Withdraw

​Didn’t find what you were looking for?

Comenzar

Requisitos previos

Derivar la etiqueta de visualización

Obtener las salidas de transacciones del indexador

Descifrar para obtener el historial privado

Ejemplo de código completo

Requisitos previos

Derivar la etiqueta de visualización

Obtener las salidas de transacciones del indexador

Descifrar para obtener el historial privado

Ejemplo de código completo

Guías relacionadas

Didn’t find what you were looking for?