Read fetches encrypted transactions from the indexer with dedicated RPC methods.
Only the user, or anyone the user authorizes, can decrypt history with their viewing key.
Use it wherever the wallet runs backfills: on wallet unlock, private wallet open, app resume, network reconnect, stream gap, or wallet restore.

Compare to getSignaturesForAddress

getSignaturesForAddress returns public signatures.
The RPC returns the public history.

Get Started

TypeScript Client
Rust Client

Prerequisites

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

pnpm add @heliuslabs/zolana @solana/kit

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: "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com",
  proverUrl: "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com:3001",
  allowInsecureHttp: true,
});

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

Derive the View Tag

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 is senderAddress.confidentialViewTag(), the sender’s Solana public key in confidential rings. The indexer uses it to return matching encrypted outputs.

Fetch Transaction Outputs from the Indexer

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

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

getShieldedTransactionsByTags fetches the encrypted outputs associated with senderViewTag.
atSlot(depositTx.slot) waits until the indexer has the deposit at that slot.
The indexer returns encrypted output data. It does not decrypt the private history.

Decrypt to Private History

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

const wallet = new Wallet({
  identity: senderAddress,
  registry: assets,
});
await decryptTransactions({
  wallet,
  authority: {
    syncMaterial: () =>
      Promise.resolve({
        identity: senderAddress,
        viewingKeys: [senderKeypair.viewingKey()],
        nullifierKey: senderKeypair.nullifierKey(),
      }),
  },
  transactions: depositResponse.transactions,
});
const history = wallet.privateTransactions();

senderKeypair supplies the sender’s viewing key for local decryption.
decryptTransactions decrypts matching outputs and writes history onto Wallet.
wallet.privateTransactions() reads the decrypted history.
decryptToBalances returns balances only.

Example Response:

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

See Concepts for how owner tagging and Private Solana Token Accounts work.

Full Code Example

Clone and run the example:

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

The examples use a confidential Ring on local/devnet here.

Prerequisites

The Rust examples require the latest stable Rust toolchain 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.1.0-alpha", features = ["indexer-api", "solana-rpc"] }
zolana-interface = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha", features = ["solana"] }
zolana-keypair = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.0-alpha" }
zolana-transaction = { git = "https://github.com/helius-labs/zolana", tag = "v0.1.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 solana_address::Address;
use zolana_client::{SolanaRpc, ZolanaClient};
use zolana_interface::DEFAULT_TREE_ADDRESS;

let tree: Address = DEFAULT_TREE_ADDRESS.parse()?;
let client = ZolanaClient::from_urls_allowing_insecure_http(
    SolanaRpc::new("https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY"),
    "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com",
    "http://zolnet-devnet-1779374825.eu-north-1.elb.amazonaws.com:3001",
    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 solana_address::Address;
use zolana_client::{SolanaRpc, ZolanaClient};
use zolana_interface::DEFAULT_TREE_ADDRESS;

let tree: Address = DEFAULT_TREE_ADDRESS.parse()?;
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,
)?;

Derive the View Tag

use zolana_client::Rpc;

let sender_tag = sender_shielded_address.confidential_view_tag()?;

sender_tag is sender_shielded_address.confidential_view_tag(), the sender’s Solana public key in confidential rings. The indexer uses it to return matching encrypted outputs.

Fetch Transaction Outputs from the Indexer

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 fetches the encrypted outputs associated with sender_tag.
IndexerRpcConfig::at_slot(slot) waits until the indexer has the deposit at that slot.
The indexer returns encrypted output data. It does not decrypt the private history.

Decrypt to Private History

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 supplies the sender’s viewing key for local decryption.
Wallet::sync decrypts matching outputs and writes history onto Wallet.
wallet.private_transactions() reads the decrypted history.
decrypt_transactions returns balances only.

Example Response:

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

Full Code Example

Clone and run the example:

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

Get Started

Data Streaming & Event Listening

Data APIs & RPCs

Trading

Sending Transactions

Wallet-as-a-Service

Privacy

Guides

Resources

Read Private History

Get Started

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to Private History

Full Code Example

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to Private History

Full Code Example

Read a Private Balance

Deposit

Transfer

Withdraw

Didn’t find what you were looking for?

​Get Started

​Prerequisites

​Derive the View Tag

​Fetch Transaction Outputs from the Indexer

​Decrypt to Private History

​Full Code Example

​Prerequisites

​Derive the View Tag

​Fetch Transaction Outputs from the Indexer

​Decrypt to Private History

​Full Code Example

​Related Guides

Read a Private Balance

Deposit

Transfer

Withdraw

​Didn’t find what you were looking for?

Get Started

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to Private History

Full Code Example

Prerequisites

Derive the View Tag

Fetch Transaction Outputs from the Indexer

Decrypt to Private History

Full Code Example

Related Guides

Didn’t find what you were looking for?