Transaction History

This guide covers querying and filtering transaction history using the Privacy Boost React SDK’s useTransactions hook.

Basic Usage

import { useTransactions } from '@sunnyside-io/privacy-boost-react';

function TransactionList() {
  const { transactions, isLoading, fetchHistory } = useTransactions();

  useEffect(() => {
    fetchHistory();
  }, []);

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {transactions.map((tx) => (
        <li key={tx.txHash}>
          {tx.type}: {tx.amount?.toString() ?? '-'}
        </li>
      ))}
    </ul>
  );
}

Return Value

interface UseTransactionsResult {
  // Reactive data (locally-tracked transactions)
  transactions: PendingTransaction[];
  recentTransactions: PendingTransaction[];
  pending: PendingTransaction[];   // status === 'pending' || 'preconfirmed'
  isLoading: boolean;
  hasPending: boolean;
  pendingCount: number;

  // Filtered views
  shields: PendingTransaction[];
  unshields: PendingTransaction[];
  transfers: PendingTransaction[];

  // Actions
  fetchHistory(params?: FetchHistoryParams): Promise<TransactionsResponse>;
  refreshPending(): Promise<number>;
  getByHash(txHash: string): PendingTransaction | undefined;
  getByType(type: TransactionType): PendingTransaction[];
  getByStatus(status: TransactionStatus): PendingTransaction[];
}

pending includes both pending and preconfirmed transactions — anything still in-flight from finality’s perspective. Use tx.phase (see Transaction Lifecycle) to distinguish the spendable preconfirmed transfers from the rest.

Transaction Types

interface TransactionNote {
  value: string;
  direction: string;
  isChange: boolean;
  leafIndex?: number;
  nullifier?: string;
  counterParty?: string;
  counterPartyType?: string;
}

interface Transaction {
  txHash: string;
  txType: string;       // 'shield' | 'unshield' | 'transfer'
  direction: string;    // 'incoming' | 'outgoing'
  value: string;
  tokenId: number;
  createdAt: number;
  counterparty?: string;
  counterpartyType?: string;
  notes: TransactionNote[];
}

interface TransactionsResponse {
  data: Transaction[];
  limit: number;
  next?: string;
}

Fetching History

Basic Fetch

const { fetchHistory } = useTransactions();

useEffect(() => {
  fetchHistory();
}, []);

With Filters

// Only deposits
await fetchHistory({ txType: 'deposit' });

// Limited results
await fetchHistory({ limit: 10 });

// Cursor-based pagination
await fetchHistory({ limit: 10, cursor: 'next-cursor-value' });

Filter Parameters

interface FetchHistoryParams {
  txType?: string;
  limit?: number;
  cursor?: string;
}

Complete Example

import { useState, useEffect } from 'react';
import { useTransactions } from '@sunnyside-io/privacy-boost-react';

function TransactionHistory() {
  const { transactions, isLoading, fetchHistory } = useTransactions();
  const [filter, setFilter] = useState<string>('all');

  useEffect(() => {
    if (filter === 'all') {
      fetchHistory({ limit: 50 });
    } else {
      fetchHistory({ txType: filter, limit: 50 });
    }
  }, [filter, fetchHistory]);

  const formatAmount = (amount: bigint, decimals = 18) => {
    return (Number(amount) / 10 ** decimals).toFixed(4);
  };

  const formatDate = (timestamp: number) => {
    return new Date(timestamp).toLocaleDateString();
  };

  return (
    <div>
      {/* Filter Tabs */}
      <div className="tabs">
        {['all', 'deposit', 'withdraw', 'transfer'].map((type) => (
          <button
            key={type}
            onClick={() => setFilter(type)}
            className={filter === type ? 'active' : ''}
          >
            {type.charAt(0).toUpperCase() + type.slice(1)}
          </button>
        ))}
      </div>

      {/* Loading State */}
      {isLoading && <div>Loading transactions...</div>}

      {/* Transaction List */}
      {!isLoading && transactions.length === 0 && (
        <p>No transactions found</p>
      )}

      <table>
        <thead>
          <tr>
            <th>Type</th>
            <th>Amount</th>
            <th>Status</th>
            <th>Date</th>
          </tr>
        </thead>
        <tbody>
          {transactions.map((tx) => (
            <tr key={tx.txHash}>
              <td>
                <span className={`type-${tx.type}`}>
                  {tx.type}
                </span>
                {tx.direction === 'incoming' && ' (received)'}
              </td>
              <td>{tx.amount ? formatAmount(tx.amount) : '-'}</td>
              <td>
                <span className={`status-${tx.status}`}>
                  {tx.status}
                </span>
              </td>
              <td>{formatDate(tx.createdAt)}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

function TransactionDetail({ tx }: { tx: Transaction }) {
  return (
    <div className="tx-detail">
      <h3>{tx.txType.toUpperCase()}</h3>

      <div className="row">
        <label>Direction</label>
        <span>{tx.direction}</span>
      </div>

      <div className="row">
        <label>Value</label>
        <span>{tx.value}</span>
      </div>

      <div className="row">
        <label>Transaction Hash</label>
        <a
          href={`https://etherscan.io/tx/${tx.txHash}`}
          target="_blank"
          rel="noopener noreferrer"
        >
          {tx.txHash.slice(0, 20)}...
        </a>
      </div>

      {tx.counterparty && (
        <div className="row">
          <label>Counterparty</label>
          <span>{tx.counterparty.slice(0, 20)}...</span>
        </div>
      )}

      <div className="row">
        <label>Date</label>
        <span>{new Date(tx.createdAt).toLocaleString()}</span>
      </div>

      {tx.notes.length > 0 && (
        <div className="notes">
          <label>Notes ({tx.notes.length})</label>
          {tx.notes.map((note, i) => (
            <div key={i}>
              {note.direction}: {note.value}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Refresh Transactions

function RefreshableHistory() {
  const { transactions, isLoading, fetchHistory } = useTransactions();
  const [lastRefresh, setLastRefresh] = useState<Date | null>(null);

  const handleRefresh = async () => {
    await fetchHistory();
    setLastRefresh(new Date());
  };

  return (
    <div>
      <div className="header">
        <h3>Transaction History</h3>
        <button onClick={handleRefresh} disabled={isLoading}>
          {isLoading ? 'Refreshing...' : 'Refresh'}
        </button>
      </div>

      {lastRefresh && (
        <small>Last refreshed: {lastRefresh.toLocaleTimeString()}</small>
      )}

      {/* Transaction list */}
    </div>
  );
}

Preconfirmation and Auto-Polling

In-flight transactions pass through pending → preconfirmed → completed (or failed). useTransactions auto-polls whenever any transaction is in flight and exposes two callbacks so you can react to the transitions without owning the polling loop yourself.

const { transactions, hasPending } = useTransactions({
  // default true — turn off if you want to drive polling manually
  autoPoll: true,
  pollInterval: 3000,

  // Fires once per transaction the first time it reaches `preconfirmed`.
  // For transfers, this is the cue that the output note is spendable —
  // safe to enable a chained transfer/unshield against it.
  onPreconfirmed: (txs) => {
    for (const tx of txs) {
      console.log('preconfirmed', tx.type, tx.txHash);
    }
  },

  // Fires when the last in-flight transaction reaches a terminal status
  // (`completed` or `failed`). Preconfirmed-but-unfinalized txs do NOT
  // trigger this — polling continues until finality.
  onAllResolved: (resolved) => {
    console.log('all resolved', resolved.length);
  },
});

Gating chained actions on preconfirmation

Branch on tx.phase rather than tx.status — phase === 'spendable' is the first moment a transfer’s output note can be used as input for the next private action.

function ChainNext({ parentTxHash }: { parentTxHash: string }) {
  const { getByHash } = useTransactions();
  const parent = getByHash(parentTxHash);

  const canChain = parent?.phase === 'spendable' || parent?.phase === 'final';

  return <button disabled={!canChain}>Send again</button>;
}

See Transaction Lifecycle for the full state machine and recommended UX patterns.

Quickstart

Setup

SDKs

Transactions

Transaction History

Basic Usage

Return Value

Transaction Types

Fetching History

Basic Fetch

With Filters

Filter Parameters

Complete Example

Refresh Transactions

Preconfirmation and Auto-Polling

Gating chained actions on preconfirmation

Next Steps

​Transaction History

​Basic Usage

​Return Value

​Transaction Types

​Fetching History

​Basic Fetch

​With Filters

​Filter Parameters

​Complete Example

​Transaction Details Modal

​Refresh Transactions

​Preconfirmation and Auto-Polling

​Gating chained actions on preconfirmation

​Next Steps

Transaction History

Basic Usage

Return Value

Transaction Types

Fetching History

Basic Fetch

With Filters

Filter Parameters

Complete Example

Transaction Details Modal

Refresh Transactions

Preconfirmation and Auto-Polling

Gating chained actions on preconfirmation

Next Steps