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

Los ejemplos de TypeScript requieren Node.js 24 o una versión posterior, pnpm 11.18.0 y la CLI de Solana.

pnpm add @heliuslabs/spr@^0.9.0-alpha @solana/kit@^8.3.0

Connect to Endpoints

Devnet
Localnet

pnpm install
cp .env.example .env

Agrega una clave de API de Helius:

.env

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

import { createSprClient } from "@heliuslabs/spr";

const client = await createSprClient({
  solanaRpcUrl: "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY",
});

Los ejemplos usan de forma predeterminada la billetera de la CLI de Solana como pagador. El pagador debe tener SOL de devnet. Consulta Cómo obtener SOL de devnet.

En localnet, el SDK inicia el validador de pruebas local (:8899), el indexador Photon (:8784) y el demostrador (:3001), y el cliente se conecta a ellos automáticamente sin necesidad de configurar puntos de conexión.

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

import { createSprClient } from "@heliuslabs/spr";

const client = await createSprClient({});

Derivar la etiqueta de visualización

import { createSprClient } from "@heliuslabs/spr";

// 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/spr/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/spr";
import { decryptTransactions, LocalShieldedKeys } from "@heliuslabs/spr/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 Estado privado y UTXO para saber cómo funcionan el etiquetado de propietarios y las cuentas de tokens privadas 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 Ring confidencial en local/devnet aquí.

Requisitos previos

Los ejemplos de Rust requieren Rust 1.98.1 y la CLI de Solana v4.0.2. Consulta la guía de instalación de Solana.

Cargo.toml

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

Connect to Endpoints

Devnet
Localnet

Agrega una clave de API de Helius:

.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 url = "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY";
let client = ZolanaClient::from_urls(SolanaRpc::new(url), url, url)?;

Los ejemplos usan la billetera de Solana CLI como pagador de forma predeterminada. El pagador debe tener SOL de devnet. Consulta Cómo obtener SOL de devnet.

cargo install --git https://github.com/helius-labs/zolana --tag v0.5.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 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_test_utils::wallet::{sync_wallet_with_config, SyncWalletConfig, Wallet};

let mut wallet = Wallet::new(sender.shielded_address()?, assets)
    .map_err(|e| anyhow!("create wallet: {e:?}"))?;
let report = sync_wallet_with_config(
    &mut wallet,
    &sender,
    &client,
    SyncWalletConfig {
        page_limit: 50,
        ..SyncWalletConfig::default()
    },
)?;
anyhow::ensure!(
    report.unknown_asset_ids.is_empty() && report.unknown_mints.is_empty(),
    "could not resolve SPL asset registrations"
);
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_spendable devuelve saldos verificados y UTXO con datos, no el historial de transacciones.

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

Transmisión 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

¿No encontraste lo que buscabas?

​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

​¿No encontraste lo que buscabas?

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

¿No encontraste lo que buscabas?