> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Read Private History

> Guide to read a wallet's private transaction history from the indexer with a full code example.

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

```mermaid theme={"system"}
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'lineColor':           '#FF6B35',
    'primaryTextColor':    '#737373',
    'primaryBorderColor':  '#9CA3AF',
    'actorBkg':            '#FFFFFF',
    'actorBorder':         '#9CA3AF',
    'actorTextColor':      '#737373',
    'signalColor':         '#FF6B35',
    'signalTextColor':     '#737373',
    'labelBoxBkgColor':    '#FF6B351F',
    'labelBoxBorderColor': '#FF6B35',
    'noteBkgColor':        '#F5F5F5',
    'noteTextColor':       '#737373',
    'noteBorderColor':     '#9CA3AF'
  }
}}%%
sequenceDiagram
    participant Wallet
    participant RPC as RPC Provider

    Wallet->>RPC: getShieldedTransactionsByTags
    RPC-->>Wallet: Encrypted transactions
    Note over Wallet: Decrypt
    Note over Wallet: Decrypt to private history
```

> [accordion] Compare to getSignaturesForAddress
>
> 1. `getSignaturesForAddress` returns public signatures.
> 2. The RPC returns the public history.
>
> ```mermaid theme={"system"}
> %%{init: {
>   'theme': 'base',
>   'themeVariables': {
>     'lineColor':           '#FF6B35',
>     'primaryTextColor':    '#737373',
>     'primaryBorderColor':  '#9CA3AF',
>     'actorBkg':            '#FFFFFF',
>     'actorBorder':         '#9CA3AF',
>     'actorTextColor':      '#737373',
>     'signalColor':         '#FF6B35',
>     'signalTextColor':     '#737373',
>     'labelBoxBkgColor':    '#FF6B351F',
>     'labelBoxBorderColor': '#FF6B35',
>     'noteBkgColor':        '#F5F5F5',
>     'noteTextColor':       '#737373',
>     'noteBorderColor':     '#9CA3AF'
>   }
> }}%%
> sequenceDiagram
>     participant Wallet
>     participant RPC
>
>     Wallet->>RPC: getSignaturesForAddress
>     RPC-->>Wallet: Public signatures
> ```

## Get Started

> [tab] TypeScript Client
>
> **Step 1**
>
> ### Prerequisites
>
> > [!NOTE]
> >
> > The TypeScript examples require Node.js 24 or later, pnpm 11.18.0, and the Solana CLI.
>
> ```bash theme={"system"}
> pnpm add @heliuslabs/zolana@^0.5.0-alpha @solana/kit@^8.3.0
> ```
>
> Source: [sdk-libs/ts](https://github.com/helius-labs/zolana/tree/ts-sdk-v0.5.0-alpha/sdk-libs/ts)
>
> > [accordion] Connect to Endpoints
> >
> > > [tab] Devnet
> > >
> > > ```bash theme={"system"}
> > > pnpm install
> > > cp .env.example .env
> > > ```
> > >
> > > Add a [Helius API key](https://dashboard.helius.dev/):
> > >
> > > ```bash .env theme={"system"}
> > > API_KEY=YOUR_API_KEY
> > > ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json
> > > ```
> > >
> > > ```ts theme={"system"}
> > > import { createZolanaClient } from "@heliuslabs/zolana";
> > >
> > > const client = await createZolanaClient({
> > >   solanaRpcUrl: "https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY",
> > > });
> > > ```
> > >
> > > The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See [How to Get Devnet SOL](https://www.helius.dev/docs/rpc/devnet-sol.md).
> >
> > > [tab] Localnet
> > >
> > > 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.
> > >
> > > ```bash theme={"system"}
> > > cargo install --git https://github.com/helius-labs/zolana --tag v0.5.0-alpha zolana-cli
> > > zolana dev start
> > > ```
> > >
> > > ```ts theme={"system"}
> > > import { createZolanaClient } from "@heliuslabs/zolana";
> > >
> > > const client = await createZolanaClient({});
> > > ```
>
> **Step 2**
>
> ### Derive the View Tag
>
> ```typescript theme={"system"}
> 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.
>
> **Step 3**
>
> ### Fetch Transaction Outputs from the Indexer
>
> ```typescript theme={"system"}
> 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.
>
> **Step 4**
>
> ### Decrypt to Private History
>
> ```typescript theme={"system"}
> 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)` supplies the sender's keys for local decryption.
> * `decryptTransactions` decrypts matching outputs and writes history onto `Wallet`.
> * `wallet.privateTransactions()` reads the decrypted history.
> * `decryptToBalances` returns balances only.
>
> **Example Response:**
>
> ```ts theme={"system"}
> [
>   {
>     id: { signature: "5x…", slot: 291044100n, index: 0n },
>     kind: "deposit",
>     direction: "inbound",
>     status: "confirmed",
>     asset: SOL_MINT,
>     amount: 100_000_000n,
>     counterpartyViewingPublicKey: undefined,
>   },
> ]
> ```
>
> > [!NOTE]
> >
> > See [Private State and UTXOs](https://www.helius.dev/docs/privacy/concepts/utxo.md) for how owner tagging and Private Solana Token Accounts work.
>
> ### Full Code Example
>
> Clone and run the example:
>
> ```bash theme={"system"}
> git clone https://github.com/helius-labs/zolana-examples.git
> cd zolana-examples/typescript-client
> pnpm install
> pnpm example examples/read_history.ts
> ```
>
> > [!NOTE]
> >
> > The examples use a confidential Ring on local/devnet [here](https://github.com/helius-labs/zolana-examples/blob/main/typescript-client/examples/read_history.ts).

> [tab] Rust Client
>
> **Step 1**
>
> ### Prerequisites
>
> > [!NOTE]
> >
> > The Rust examples require Rust 1.98.1 and the Solana CLI v4.0.2. See the [Solana installation guide](https://solana.com/docs/intro/installation).
>
> ```toml Cargo.toml theme={"system"}
> [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" }
> ```
>
> Source: [sdk-libs/client](https://github.com/helius-labs/zolana/tree/v0.5.0-alpha/sdk-libs/client)
>
> > [accordion] Connect to Endpoints
> >
> > > [tab] Devnet
> > >
> > > Add a [Helius API key](https://dashboard.helius.dev/):
> > >
> > > ```bash .env theme={"system"}
> > > API_KEY=YOUR_API_KEY
> > > ZOLANA_PAYER_KEYPAIR=~/.config/solana/id.json
> > > ```
> > >
> > > ```rust theme={"system"}
> > > 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)?;
> > > ```
> > >
> > > The examples use the Solana CLI wallet as the payer by default. The payer must hold devnet SOL. See [How to Get Devnet SOL](https://www.helius.dev/docs/rpc/devnet-sol.md).
> >
> > > [tab] Localnet
> > >
> > > ```bash theme={"system"}
> > > cargo install --git https://github.com/helius-labs/zolana --tag v0.5.0-alpha zolana-cli
> > > zolana dev start
> > > ```
> > >
> > > ```rust theme={"system"}
> > > 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",
> > > )?;
> > > ```
>
> **Step 2**
>
> ### Derive the View Tag
>
> ```rust theme={"system"}
> 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.
>
> **Step 3**
>
> ### Fetch Transaction Outputs from the Indexer
>
> ```rust theme={"system"}
> 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.
>
> **Step 4**
>
> ### Decrypt to Private History
>
> ```rust theme={"system"}
> 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` 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_spendable` returns verified balances and UTXOs with data, not transaction history.
>
> **Example Response:**
>
> ```rust theme={"system"}
> [
>     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:
>
> ```bash theme={"system"}
> git clone https://github.com/helius-labs/zolana-examples.git
> cd zolana-examples/rust-client
> cargo run -p rust-client-example --example read_history
> ```
>
> > [!NOTE]
> >
> > The examples use a confidential Ring on local/devnet [here](https://github.com/helius-labs/zolana-examples/blob/main/rust-client/examples/read_history.rs).

## Related Guides

> [card] [Read a Private Balance](https://www.helius.dev/docs/privacy/guides/read-balance.md)

> [card] [Deposit](https://www.helius.dev/docs/privacy/guides/deposit.md)

> [card] [Transfer](https://www.helius.dev/docs/privacy/guides/transfer.md)

> [card] [Withdraw](https://www.helius.dev/docs/privacy/guides/withdraw.md)

## Didn't find what you were looking for?

Reach out! [Telegram](https://t.me/tilo_light) | [E-Mail](mailto:sales@helius.xyz) | [Contact](https://www.helius.dev/contact)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.