Skip to main content

Balance Management

This guide covers querying and displaying token balances using the Privacy Boost React SDK.

Basic Usage

import { useBalances } from '@testinprod-io/privacy-boost-react';

function BalanceDisplay() {
  const { balances, loading } = useBalances();

  if (loading) return <div>Loading balances...</div>;

  return (
    <ul>
      {balances.map((balance) => (
        <li key={balance.tokenAddress}>
          {balance.symbol}: {balance.formattedShielded} (shielded)
        </li>
      ))}
    </ul>
  );
}

useBalances Return Value

PropertyTypeDescription
balancesFormattedBalance[]All token balances with formatted strings
loadingbooleanWhether balances are loading
lastSyncednumber | nullTimestamp of last sync
getBalance(tokenAddress) => FormattedBalanceGet balance for a specific token
getShieldedBalance(tokenAddress) => bigintGet raw shielded balance
getWalletBalance(tokenAddress) => bigintGet raw wallet balance
totalShieldedbigintTotal shielded balance across all tokens
tokenCountnumberNumber of tokens with balances

Balance Types

interface FormattedBalance {
  tokenAddress: Hex;
  shielded: bigint;
  wallet: bigint;
  symbol?: string;
  decimals?: number;
  formattedShielded: string;
  formattedWallet: string;
}

Syncing Balances

import { useVault, useBalances } from '@testinprod-io/privacy-boost-react';

function SyncButton() {
  const { syncAllBalances } = useVault();
  const [syncing, setSyncing] = useState(false);

  const handleSync = async () => {
    setSyncing(true);
    await syncAllBalances();
    setSyncing(false);
  };

  return (
    <button onClick={handleSync} disabled={syncing}>
      {syncing ? 'Syncing...' : 'Sync Balances'}
    </button>
  );
}

Complete Example

import { useBalances, useVault } from '@testinprod-io/privacy-boost-react';

function BalanceList() {
  const { balances, loading, lastSynced, tokenCount } = useBalances();
  const { syncAllBalances } = useVault();
  const [syncing, setSyncing] = useState(false);

  const handleRefresh = async () => {
    setSyncing(true);
    await syncAllBalances();
    setSyncing(false);
  };

  return (
    <div>
      <div className="header">
        <h3>Balances ({tokenCount} tokens)</h3>
        <button onClick={handleRefresh} disabled={syncing}>
          {syncing ? 'Refreshing...' : 'Refresh'}
        </button>
      </div>

      {lastSynced && (
        <small>Last synced: {new Date(lastSynced).toLocaleTimeString()}</small>
      )}

      {loading ? (
        <div>Loading...</div>
      ) : (
        <table>
          <thead>
            <tr>
              <th>Token</th>
              <th>Shielded</th>
              <th>Wallet</th>
            </tr>
          </thead>
          <tbody>
            {balances.map((balance) => (
              <tr key={balance.tokenAddress}>
                <td>{balance.symbol}</td>
                <td>{balance.formattedShielded}</td>
                <td>{balance.formattedWallet}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}
    </div>
  );
}

Best Practices

1. Use Formatted Values for Display

The formattedShielded and formattedWallet strings are already human-readable. Use them directly instead of manually formatting.

2. Refresh After Operations

Always sync balances after deposits, withdrawals, or transfers.

3. Show Loading States

Balance syncing requires network calls. Always show a loading indicator.

Next Steps