@dynamic-labs/sdk-react-core 4.84.0 → 4.85.0

package/src/lib/utils/hooks/useAleoAutoShieldSponsoredTokens/pollOnShielded.js

@@ -5,7 +5,7 @@ import { __awaiter } from '../../../../../_virtual/_tslib.js';
 //  when the relay accepts the broadcast, not when the public→private
 //  transition confirms on-chain. Aleo block time + RecordScanner indexer
 //  lag means the immediate post-broadcast fetch usually returns the
-//  pre-confirmation balance, so we re-poll for ~45s before giving up.
+//  pre-confirmation balance, so we re-poll on a backoff schedule.
 //
 //  Shared between the auto-shield hook (background) and the widget's
 //  manual Shield Manually CTA (foreground), so both flows update the
@@ -13,23 +13,41 @@ import { __awaiter } from '../../../../../_virtual/_tslib.js';
 //  the manual flow refreshed exactly once and the unshielded row
 //  stayed at its pre-broadcast value for the full RecordScanner lag,
 //  making a successful shield look like a no-op.
+//
+//  Total window ≈106s. Provable's mapping endpoint typically reflects
+//  a `transfer_public_to_private` within ~30s of broadcast, but the
+//  RecordScanner index lag for the new private record can stretch to
+//  ~90s in the worst case. The tail entries (25s, 35s) keep the poll
+//  alive across the upper end of that range without spamming requests
+//  during the common case (most balances converge inside the first
+//  three iterations and the convergence predicate exits the loop).
 const REFRESH_DELAYS_MS = [
-    3000, 5000, 8000, 12000, 18000,
+    3000, 5000, 8000, 12000, 18000, 25000, 35000,
 ];
 /**
  * After a successful shield broadcast, poll `onShielded` on a backoff
  * schedule so the consumer sees both the shielded and unshielded balances
- * update without a manual refresh click. Stops early on cancel; swallows
+ * update without a manual refresh click. Stops early on cancel or when
+ * the optional `hasConverged` predicate returns true; swallows
  * per-iteration errors (refresh is best-effort).
  *
  * `isCancelled` is a thunk so callers can hook it up to whatever liveness
  * signal they have (effect cleanup `cancelled` flag, abort signal, mount
  * ref, etc.) without this module having to know about React lifecycle.
+ *
+ * `hasConverged` is optional and lets callers exit early once the
+ * post-shield state has actually materialized (e.g. the just-shielded
+ * token's unshielded balance has dropped). When omitted, the schedule
+ * runs to completion. Checked both before each delay and after each
+ * refresh so a refresh that produces the converged state ends the loop
+ * immediately.
  */
-const pollOnShielded = (onShielded, isCancelled) => __awaiter(void 0, void 0, void 0, function* () {
+const pollOnShielded = (onShielded, isCancelled, hasConverged) => __awaiter(void 0, void 0, void 0, function* () {
     for (const delay of REFRESH_DELAYS_MS) {
         if (isCancelled())
             return;
+        if (hasConverged === null || hasConverged === void 0 ? void 0 : hasConverged())
+            return;
         yield new Promise((resolve) => setTimeout(resolve, delay));
         if (isCancelled())
             return;
@@ -39,6 +57,8 @@ const pollOnShielded = (onShielded, isCancelled) => __awaiter(void 0, void 0, vo
         catch (_a) {
             /* swallow — refresh is best-effort */
         }
+        if (hasConverged === null || hasConverged === void 0 ? void 0 : hasConverged())
+            return;
     }
 });
 

package/src/lib/utils/hooks/useAleoAutoShieldSponsoredTokens/useAleoAutoShieldSponsoredTokens.cjs

@@ -47,7 +47,7 @@ const buildShieldCandidates = (args) => {
  */
 const tryShieldOneToken = (token, deps) => _tslib.__awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
-    const { accountAddress, shieldHandle, seenKeys, isCancelled, inFlightTokenKeys, } = deps;
+    const { accountAddress, shieldHandle, seenKeys, isCancelled, inFlightTokenKeys, onShieldDispatched, } = deps;
     const tokenKey = buildTokenKey.buildTokenKey(token) || nativeTokenKey.nativeTokenKey;
     const key = `${accountAddress}:${tokenKey}`;
     seenKeys.add(key);
@@ -80,9 +80,19 @@ const tryShieldOneToken = (token, deps) => _tslib.__awaiter(void 0, void 0, void
             isNative: token.isNative,
             tokenAddress: token.address,
         });
+        // Optimistic-UI hand-off: notify the consumer the broadcast was
+        //  accepted so it can deduct the unshielded balance locally and
+        //  prepend a synthesised shielded row. Synchronous and best-effort;
+        //  failures inside the callback don't roll back the shield.
+        try {
+            onShieldDispatched === null || onShieldDispatched === void 0 ? void 0 : onShieldDispatched({ amount: atomic, token });
+        }
+        catch (_e) {
+            /* swallow — optimistic hand-off is best-effort */
+        }
         return true;
     }
-    catch (_e) {
+    catch (_f) {
         seenKeys.delete(key);
         return false;
     }
@@ -90,7 +100,7 @@ const tryShieldOneToken = (token, deps) => _tslib.__awaiter(void 0, void 0, void
         inFlightTokenKeys === null || inFlightTokenKeys === void 0 ? void 0 : inFlightTokenKeys.delete(tokenKey);
     }
 });
-const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, }) => {
+const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, onShieldDispatched, }) => {
     // Tracks `(accountAddress:tokenAddress)` we've already attempted in this
     //  session. Cleared implicitly on a full page reload.
     const seenKeysRef = React.useRef(new Set());
@@ -218,6 +228,7 @@ const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalan
                     accountAddress,
                     inFlightTokenKeys: inFlightKeysAdapter,
                     isCancelled,
+                    onShieldDispatched,
                     seenKeys: seenKeysRef.current,
                     shieldHandle,
                 });

package/src/lib/utils/hooks/useAleoAutoShieldSponsoredTokens/useAleoAutoShieldSponsoredTokens.d.ts

@@ -25,6 +25,10 @@ type UseAleoAutoShieldSponsoredTokensArgs = {
     unshieldedTokenBalances: TokenBalance[];
     shieldHandle: AleoShieldHandle | undefined;
     onShielded?: () => Promise<void> | void;
+    onShieldDispatched?: (info: {
+        token: TokenBalance;
+        amount: bigint;
+    }) => void;
 };
 /**
  * On Aleo wallet load (and on each subsequent unshielded-balance refresh),
@@ -66,5 +70,5 @@ export type UseAleoAutoShieldSponsoredTokensResult = {
      */
     currentlyShieldingTokenKeys: ReadonlySet<string>;
 };
-export declare const useAleoAutoShieldSponsoredTokens: ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, }: UseAleoAutoShieldSponsoredTokensArgs) => UseAleoAutoShieldSponsoredTokensResult;
+export declare const useAleoAutoShieldSponsoredTokens: ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, onShieldDispatched, }: UseAleoAutoShieldSponsoredTokensArgs) => UseAleoAutoShieldSponsoredTokensResult;
 export {};

package/src/lib/utils/hooks/useAleoAutoShieldSponsoredTokens/useAleoAutoShieldSponsoredTokens.js

@@ -43,7 +43,7 @@ const buildShieldCandidates = (args) => {
  */
 const tryShieldOneToken = (token, deps) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
-    const { accountAddress, shieldHandle, seenKeys, isCancelled, inFlightTokenKeys, } = deps;
+    const { accountAddress, shieldHandle, seenKeys, isCancelled, inFlightTokenKeys, onShieldDispatched, } = deps;
     const tokenKey = buildTokenKey(token) || nativeTokenKey;
     const key = `${accountAddress}:${tokenKey}`;
     seenKeys.add(key);
@@ -76,9 +76,19 @@ const tryShieldOneToken = (token, deps) => __awaiter(void 0, void 0, void 0, fun
             isNative: token.isNative,
             tokenAddress: token.address,
         });
+        // Optimistic-UI hand-off: notify the consumer the broadcast was
+        //  accepted so it can deduct the unshielded balance locally and
+        //  prepend a synthesised shielded row. Synchronous and best-effort;
+        //  failures inside the callback don't roll back the shield.
+        try {
+            onShieldDispatched === null || onShieldDispatched === void 0 ? void 0 : onShieldDispatched({ amount: atomic, token });
+        }
+        catch (_e) {
+            /* swallow — optimistic hand-off is best-effort */
+        }
         return true;
     }
-    catch (_e) {
+    catch (_f) {
         seenKeys.delete(key);
         return false;
     }
@@ -86,7 +96,7 @@ const tryShieldOneToken = (token, deps) => __awaiter(void 0, void 0, void 0, fun
         inFlightTokenKeys === null || inFlightTokenKeys === void 0 ? void 0 : inFlightTokenKeys.delete(tokenKey);
     }
 });
-const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, }) => {
+const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, onShieldDispatched, }) => {
     // Tracks `(accountAddress:tokenAddress)` we've already attempted in this
     //  session. Cleared implicitly on a full page reload.
     const seenKeysRef = useRef(new Set());
@@ -214,6 +224,7 @@ const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalan
                     accountAddress,
                     inFlightTokenKeys: inFlightKeysAdapter,
                     isCancelled,
+                    onShieldDispatched,
                     seenKeys: seenKeysRef.current,
                     shieldHandle,
                 });

package/src/lib/utils/hooks/useAleoShieldedBalances/useAleoShieldedBalances.cjs

@@ -8,6 +8,7 @@ var React = require('react');
 var sdkApiCore = require('@dynamic-labs/sdk-api-core');
 require('../../../context/DynamicContext/useDynamicContext/useDynamicContext.cjs');
 var useInternalDynamicContext = require('../../../context/DynamicContext/useDynamicContext/useInternalDynamicContext/useInternalDynamicContext.cjs');
+var UserWalletsContext = require('../../../context/UserWalletsContext/UserWalletsContext.cjs');
 var getAleoCuratedPrices = require('../../../data/api/aleo/getAleoCuratedPrices.cjs');
 var dynamicContextProps = require('../../../store/state/dynamicContextProps/dynamicContextProps.cjs');
 
@@ -173,6 +174,12 @@ const buildCreditsBalance = (records, networkId, lookupCurated) => {
     if (creditsRecords.length === 0)
         return undefined;
     const totalMicrocredits = creditsRecords.reduce((sum, r) => sum + BigInt(r.microcredits), BigInt(0));
+    // Skip the row entirely when every credits record summed to zero
+    //  (typically partially-spent change records the indexer hasn't
+    //  pruned yet). A "0 ALEO" entry in the Shielded tab is just noise
+    //  the user can't act on.
+    if (totalMicrocredits === BigInt(0))
+        return undefined;
     // BigInt → number for the TokenBalance shape. Aleo balances stay well
     // below Number.MAX_SAFE_INTEGER for a single wallet (max u64 supply is
     // 1.5B credits = 1.5e15 microcredits; Number can hold up to ~9e15).
@@ -227,6 +234,14 @@ const buildTokenBalances = (records, networkId, lookupCurated) => {
         const spec = specsByContract.get(contractAddress);
         if (!spec)
             continue;
+        // Skip tokens whose every matched record summed to zero. Provable
+        //  occasionally surfaces serialized records with `amount: 0u128`
+        //  (e.g. partially-spent change records that haven't been pruned by
+        //  the indexer yet); without this filter the Shielded tab shows a
+        //  row with "0 USAD" / "0 USDCx" that the user can't act on, which
+        //  is just noise.
+        if (total === BigInt(0))
+            continue;
         const rawBalance = Number(total);
         const rawBalanceString = total.toString();
         const balance = rawBalance / Math.pow(10, spec.decimals);
@@ -269,14 +284,37 @@ const buildTokenBalances = (records, networkId, lookupCurated) => {
  *   - The connector doesn't expose `listOwnedRecords` (e.g. external Aleo wallet)
  *   - The user owns no records that match a known program/record pair
  */
-const useAleoShieldedBalances = () => {
+const useAleoShieldedBalances = (args = {}) => {
+    const { accountAddress, tokenAddresses, includeNativeBalance = true, includeFiat = true, chainName, networkId, } = args;
     const { primaryWallet, network } = useInternalDynamicContext.useInternalDynamicContext();
+    const { userWallets } = UserWalletsContext.useInternalUserWallets();
     const [tokenBalances, setTokenBalances] = React.useState([]);
     const [isLoading, setIsLoading] = React.useState(false);
     const [error, setError] = React.useState();
-    const connector = primaryWallet === null || primaryWallet === void 0 ? void 0 : primaryWallet.connector;
+    // `accountAddress` is treated as an override of the primary wallet:
+    //  walk the user-wallets list looking for a matching address (case-
+    //  insensitive to be tolerant of how the address is formatted at the
+    //  call site — Aleo addresses are bech32 and casing-insensitive in
+    //  practice). When no `accountAddress` is provided, fall back to the
+    //  primary wallet to preserve the existing single-wallet semantics.
+    const targetWallet = React.useMemo(() => {
+        var _a;
+        if (!accountAddress)
+            return primaryWallet;
+        const normalized = accountAddress.toLowerCase();
+        return ((_a = userWallets.find((w) => { var _a; return ((_a = w.address) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === normalized; })) !== null && _a !== void 0 ? _a : undefined);
+    }, [accountAddress, primaryWallet, userWallets]);
+    const connector = targetWallet === null || targetWallet === void 0 ? void 0 : targetWallet.connector;
     const isAleo = (connector === null || connector === void 0 ? void 0 : connector.connectedChain) === sdkApiCore.ChainEnum.Aleo;
-    const supportsShielded = isAleo &&
+    // When a `chainName` override is passed, treat anything other than
+    //  `ChainEnum.Aleo` as "the caller explicitly asked for a non-Aleo
+    //  chain we don't support yet" and short-circuit. Today Aleo is the
+    //  only chain with a private-balance path, but customers should be
+    //  able to call the public hook with whatever `chainName` matches
+    //  their app's active chain and have it transparently no-op.
+    const chainNameSupported = chainName === undefined || chainName === sdkApiCore.ChainEnum.Aleo;
+    const supportsShielded = chainNameSupported &&
+        isAleo &&
         typeof (connector === null || connector === void 0 ? void 0 : connector.listOwnedRecords) === 'function';
     // Mirror the live connector into a ref so `fetchShielded` can read it
     //  without depending on the (often unstable) object reference. Some test
@@ -286,7 +324,36 @@ const useAleoShieldedBalances = () => {
     const connectorRef = React.useRef(connector);
     connectorRef.current = connector;
     const connectorKey = connector === null || connector === void 0 ? void 0 : connector.key;
-    const networkKey = network !== undefined && network !== null ? String(network) : undefined;
+    // When a `networkId` override is provided, use it instead of the
+    //  context's `network` value when resolving the Aleo network param.
+    //  Empty string falls back to undefined so `resolveAleoNetwork`
+    //  returns `aleoNetworkParam: undefined` and the prices fetch is
+    //  skipped (matching the behaviour when no network is known).
+    const effectiveNetwork = networkId !== null && networkId !== void 0 ? networkId : network;
+    const networkKey = effectiveNetwork !== undefined && effectiveNetwork !== null
+        ? String(effectiveNetwork)
+        : undefined;
+    // Normalise the address filter once per render into a stable
+    //  primitive key (sorted, comma-joined, lowercased) so the
+    //  `useCallback` dep below doesn't invalidate on every render when the
+    //  caller passes a fresh array literal each time (which is the typical
+    //  pattern in React function components). The matching Set is derived
+    //  from the same key to keep both memos in lockstep.
+    const tokenAddressFilterKey = React.useMemo(() => {
+        if (!tokenAddresses)
+            return undefined;
+        return [...tokenAddresses]
+            .map((a) => a.toLowerCase())
+            .sort((a, b) => a.localeCompare(b))
+            .join('|');
+    }, [tokenAddresses]);
+    const tokenAddressFilter = React.useMemo(() => {
+        if (tokenAddressFilterKey === undefined)
+            return undefined;
+        if (tokenAddressFilterKey === '')
+            return new Set();
+        return new Set(tokenAddressFilterKey.split('|'));
+    }, [tokenAddressFilterKey]);
     const fetchShielded = React.useCallback(() => _tslib.__awaiter(void 0, void 0, void 0, function* () {
         var _a;
         const liveConnector = connectorRef.current;
@@ -305,9 +372,15 @@ const useAleoShieldedBalances = () => {
             //  token row, leaving the widget with no price source. Prices are
             //  best-effort: a failure leaves balances unpriced rather than
             //  dropping the shielded list entirely.
+            //
+            //  When the caller opts out of fiat (`includeFiat: false`) we skip
+            //  the curated-prices fetch entirely — same semantic as
+            //  `useTokenBalances` honouring its own `includeFiat` flag. Logos
+            //  for matched tokens then fall through to the bundled defaults
+            //  (`ALEO_CREDITS_LOGO`, `UNKNOWN_TOKEN_LOGO`, spec overrides).
             const { safeNetworkId, aleoNetworkParam } = resolveAleoNetwork(networkKey);
             const environmentId = dynamicContextProps.getEnvironmentId();
-            const shouldFetchPrices = Boolean(aleoNetworkParam && environmentId);
+            const shouldFetchPrices = Boolean(includeFiat && aleoNetworkParam && environmentId);
             const [result, priceList] = yield Promise.all([
                 liveConnector.listOwnedRecords(),
                 shouldFetchPrices && aleoNetworkParam
@@ -320,11 +393,16 @@ const useAleoShieldedBalances = () => {
             const records = (_a = result === null || result === void 0 ? void 0 : result.records) !== null && _a !== void 0 ? _a : [];
             const lookupCurated = buildCuratedTokenLookup(priceList);
             const balances = [];
-            const credits = buildCreditsBalance(records, safeNetworkId, lookupCurated);
-            if (credits)
-                balances.push(credits);
+            if (includeNativeBalance) {
+                const credits = buildCreditsBalance(records, safeNetworkId, lookupCurated);
+                if (credits)
+                    balances.push(credits);
+            }
             balances.push(...buildTokenBalances(records, safeNetworkId, lookupCurated));
-            setTokenBalances(balances);
+            const filtered = tokenAddressFilter
+                ? balances.filter((b) => { var _a; return tokenAddressFilter.has(((_a = b.address) !== null && _a !== void 0 ? _a : '').toLowerCase()); })
+                : balances;
+            setTokenBalances(filtered);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -334,7 +412,14 @@ const useAleoShieldedBalances = () => {
         finally {
             setIsLoading(false);
         }
-    }), [connectorKey, networkKey, supportsShielded]);
+    }), [
+        connectorKey,
+        includeFiat,
+        includeNativeBalance,
+        networkKey,
+        supportsShielded,
+        tokenAddressFilter,
+    ]);
     React.useEffect(() => {
         if (!supportsShielded) {
             setTokenBalances((prev) => (prev.length === 0 ? prev : []));

package/src/lib/utils/hooks/useAleoShieldedBalances/useAleoShieldedBalances.d.ts

@@ -1,4 +1,20 @@
-import { TokenBalance } from '@dynamic-labs/sdk-api-core';
+import { ChainEnum, TokenBalance } from '@dynamic-labs/sdk-api-core';
+/**
+ * Optional inputs that mirror the corresponding `useTokenBalances`
+ *  params so the public `usePrivateTokenBalances` hook can pass through
+ *  the same shape. Defaults here are tuned for the **widget's existing
+ *  consumer** (`ActiveWalletBalance`), which expects the native ALEO
+ *  row + fiat lookup to be on by default. The public hook overrides
+ *  these defaults to match `useTokenBalances`' false / false.
+ */
+export type UseAleoShieldedBalancesArgs = {
+    accountAddress?: string;
+    tokenAddresses?: string[];
+    includeNativeBalance?: boolean;
+    includeFiat?: boolean;
+    chainName?: ChainEnum;
+    networkId?: number;
+};
 /**
  * Hook that returns the active wallet's shielded (private) Aleo token
  * balances as a `TokenBalance[]` so the widget can render them through the
@@ -15,7 +31,7 @@ import { TokenBalance } from '@dynamic-labs/sdk-api-core';
  *   - The connector doesn't expose `listOwnedRecords` (e.g. external Aleo wallet)
  *   - The user owns no records that match a known program/record pair
  */
-export declare const useAleoShieldedBalances: () => {
+export declare const useAleoShieldedBalances: (args?: UseAleoShieldedBalancesArgs) => {
     tokenBalances: TokenBalance[];
     isLoading: boolean;
     error: string | undefined;

package/src/lib/utils/hooks/useAleoShieldedBalances/useAleoShieldedBalances.js

@@ -1,9 +1,10 @@
 'use client'
 import { __awaiter } from '../../../../../_virtual/_tslib.js';
-import { useState, useRef, useCallback, useEffect } from 'react';
+import { useState, useMemo, useRef, useCallback, useEffect } from 'react';
 import { ChainEnum } from '@dynamic-labs/sdk-api-core';
 import '../../../context/DynamicContext/useDynamicContext/useDynamicContext.js';
 import { useInternalDynamicContext } from '../../../context/DynamicContext/useDynamicContext/useInternalDynamicContext/useInternalDynamicContext.js';
+import { useInternalUserWallets } from '../../../context/UserWalletsContext/UserWalletsContext.js';
 import { getAleoCuratedPrices } from '../../../data/api/aleo/getAleoCuratedPrices.js';
 import { getEnvironmentId } from '../../../store/state/dynamicContextProps/dynamicContextProps.js';
 
@@ -169,6 +170,12 @@ const buildCreditsBalance = (records, networkId, lookupCurated) => {
     if (creditsRecords.length === 0)
         return undefined;
     const totalMicrocredits = creditsRecords.reduce((sum, r) => sum + BigInt(r.microcredits), BigInt(0));
+    // Skip the row entirely when every credits record summed to zero
+    //  (typically partially-spent change records the indexer hasn't
+    //  pruned yet). A "0 ALEO" entry in the Shielded tab is just noise
+    //  the user can't act on.
+    if (totalMicrocredits === BigInt(0))
+        return undefined;
     // BigInt → number for the TokenBalance shape. Aleo balances stay well
     // below Number.MAX_SAFE_INTEGER for a single wallet (max u64 supply is
     // 1.5B credits = 1.5e15 microcredits; Number can hold up to ~9e15).
@@ -223,6 +230,14 @@ const buildTokenBalances = (records, networkId, lookupCurated) => {
         const spec = specsByContract.get(contractAddress);
         if (!spec)
             continue;
+        // Skip tokens whose every matched record summed to zero. Provable
+        //  occasionally surfaces serialized records with `amount: 0u128`
+        //  (e.g. partially-spent change records that haven't been pruned by
+        //  the indexer yet); without this filter the Shielded tab shows a
+        //  row with "0 USAD" / "0 USDCx" that the user can't act on, which
+        //  is just noise.
+        if (total === BigInt(0))
+            continue;
         const rawBalance = Number(total);
         const rawBalanceString = total.toString();
         const balance = rawBalance / Math.pow(10, spec.decimals);
@@ -265,14 +280,37 @@ const buildTokenBalances = (records, networkId, lookupCurated) => {
  *   - The connector doesn't expose `listOwnedRecords` (e.g. external Aleo wallet)
  *   - The user owns no records that match a known program/record pair
  */
-const useAleoShieldedBalances = () => {
+const useAleoShieldedBalances = (args = {}) => {
+    const { accountAddress, tokenAddresses, includeNativeBalance = true, includeFiat = true, chainName, networkId, } = args;
     const { primaryWallet, network } = useInternalDynamicContext();
+    const { userWallets } = useInternalUserWallets();
     const [tokenBalances, setTokenBalances] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState();
-    const connector = primaryWallet === null || primaryWallet === void 0 ? void 0 : primaryWallet.connector;
+    // `accountAddress` is treated as an override of the primary wallet:
+    //  walk the user-wallets list looking for a matching address (case-
+    //  insensitive to be tolerant of how the address is formatted at the
+    //  call site — Aleo addresses are bech32 and casing-insensitive in
+    //  practice). When no `accountAddress` is provided, fall back to the
+    //  primary wallet to preserve the existing single-wallet semantics.
+    const targetWallet = useMemo(() => {
+        var _a;
+        if (!accountAddress)
+            return primaryWallet;
+        const normalized = accountAddress.toLowerCase();
+        return ((_a = userWallets.find((w) => { var _a; return ((_a = w.address) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === normalized; })) !== null && _a !== void 0 ? _a : undefined);
+    }, [accountAddress, primaryWallet, userWallets]);
+    const connector = targetWallet === null || targetWallet === void 0 ? void 0 : targetWallet.connector;
     const isAleo = (connector === null || connector === void 0 ? void 0 : connector.connectedChain) === ChainEnum.Aleo;
-    const supportsShielded = isAleo &&
+    // When a `chainName` override is passed, treat anything other than
+    //  `ChainEnum.Aleo` as "the caller explicitly asked for a non-Aleo
+    //  chain we don't support yet" and short-circuit. Today Aleo is the
+    //  only chain with a private-balance path, but customers should be
+    //  able to call the public hook with whatever `chainName` matches
+    //  their app's active chain and have it transparently no-op.
+    const chainNameSupported = chainName === undefined || chainName === ChainEnum.Aleo;
+    const supportsShielded = chainNameSupported &&
+        isAleo &&
         typeof (connector === null || connector === void 0 ? void 0 : connector.listOwnedRecords) === 'function';
     // Mirror the live connector into a ref so `fetchShielded` can read it
     //  without depending on the (often unstable) object reference. Some test
@@ -282,7 +320,36 @@ const useAleoShieldedBalances = () => {
     const connectorRef = useRef(connector);
     connectorRef.current = connector;
     const connectorKey = connector === null || connector === void 0 ? void 0 : connector.key;
-    const networkKey = network !== undefined && network !== null ? String(network) : undefined;
+    // When a `networkId` override is provided, use it instead of the
+    //  context's `network` value when resolving the Aleo network param.
+    //  Empty string falls back to undefined so `resolveAleoNetwork`
+    //  returns `aleoNetworkParam: undefined` and the prices fetch is
+    //  skipped (matching the behaviour when no network is known).
+    const effectiveNetwork = networkId !== null && networkId !== void 0 ? networkId : network;
+    const networkKey = effectiveNetwork !== undefined && effectiveNetwork !== null
+        ? String(effectiveNetwork)
+        : undefined;
+    // Normalise the address filter once per render into a stable
+    //  primitive key (sorted, comma-joined, lowercased) so the
+    //  `useCallback` dep below doesn't invalidate on every render when the
+    //  caller passes a fresh array literal each time (which is the typical
+    //  pattern in React function components). The matching Set is derived
+    //  from the same key to keep both memos in lockstep.
+    const tokenAddressFilterKey = useMemo(() => {
+        if (!tokenAddresses)
+            return undefined;
+        return [...tokenAddresses]
+            .map((a) => a.toLowerCase())
+            .sort((a, b) => a.localeCompare(b))
+            .join('|');
+    }, [tokenAddresses]);
+    const tokenAddressFilter = useMemo(() => {
+        if (tokenAddressFilterKey === undefined)
+            return undefined;
+        if (tokenAddressFilterKey === '')
+            return new Set();
+        return new Set(tokenAddressFilterKey.split('|'));
+    }, [tokenAddressFilterKey]);
     const fetchShielded = useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
         const liveConnector = connectorRef.current;
@@ -301,9 +368,15 @@ const useAleoShieldedBalances = () => {
             //  token row, leaving the widget with no price source. Prices are
             //  best-effort: a failure leaves balances unpriced rather than
             //  dropping the shielded list entirely.
+            //
+            //  When the caller opts out of fiat (`includeFiat: false`) we skip
+            //  the curated-prices fetch entirely — same semantic as
+            //  `useTokenBalances` honouring its own `includeFiat` flag. Logos
+            //  for matched tokens then fall through to the bundled defaults
+            //  (`ALEO_CREDITS_LOGO`, `UNKNOWN_TOKEN_LOGO`, spec overrides).
             const { safeNetworkId, aleoNetworkParam } = resolveAleoNetwork(networkKey);
             const environmentId = getEnvironmentId();
-            const shouldFetchPrices = Boolean(aleoNetworkParam && environmentId);
+            const shouldFetchPrices = Boolean(includeFiat && aleoNetworkParam && environmentId);
             const [result, priceList] = yield Promise.all([
                 liveConnector.listOwnedRecords(),
                 shouldFetchPrices && aleoNetworkParam
@@ -316,11 +389,16 @@ const useAleoShieldedBalances = () => {
             const records = (_a = result === null || result === void 0 ? void 0 : result.records) !== null && _a !== void 0 ? _a : [];
             const lookupCurated = buildCuratedTokenLookup(priceList);
             const balances = [];
-            const credits = buildCreditsBalance(records, safeNetworkId, lookupCurated);
-            if (credits)
-                balances.push(credits);
+            if (includeNativeBalance) {
+                const credits = buildCreditsBalance(records, safeNetworkId, lookupCurated);
+                if (credits)
+                    balances.push(credits);
+            }
             balances.push(...buildTokenBalances(records, safeNetworkId, lookupCurated));
-            setTokenBalances(balances);
+            const filtered = tokenAddressFilter
+                ? balances.filter((b) => { var _a; return tokenAddressFilter.has(((_a = b.address) !== null && _a !== void 0 ? _a : '').toLowerCase()); })
+                : balances;
+            setTokenBalances(filtered);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -330,7 +408,14 @@ const useAleoShieldedBalances = () => {
         finally {
             setIsLoading(false);
         }
-    }), [connectorKey, networkKey, supportsShielded]);
+    }), [
+        connectorKey,
+        includeFiat,
+        includeNativeBalance,
+        networkKey,
+        supportsShielded,
+        tokenAddressFilter,
+    ]);
     useEffect(() => {
         if (!supportsShielded) {
             setTokenBalances((prev) => (prev.length === 0 ? prev : []));

package/src/lib/utils/hooks/useDynamicWaas/useDynamicWaas.cjs

@@ -88,7 +88,7 @@ const configWaasWalletConnector = ({ walletConnector, environmentId, apiBaseUrl,
 };
 const useDynamicWaas = () => {
     var _a, _b, _c, _d, _e, _f, _g;
-    const { setShowAuthFlow, primaryWallet } = useInternalDynamicContext.useInternalDynamicContext();
+    const { setShowAuthFlow } = useInternalDynamicContext.useInternalDynamicContext();
     const { addedWalletsIds, userWallets } = UserWalletsContext.useInternalUserWallets();
     const user = useUser.useUser();
     const apiBaseUrl = dynamicContextProps.useApiBaseUrl();
@@ -468,8 +468,8 @@ const useDynamicWaas = () => {
     });
     const upgradeToDynamicWaas = React.useCallback((_j) => _tslib.__awaiter(void 0, [_j], void 0, function* ({ privateKey, wallet, password, }) {
         isUpgrading.current = true;
-        if (!primaryWallet) {
-            throw new utils.DynamicError('Primary wallet not found');
+        if (!wallet) {
+            throw new utils.DynamicError('Wallet to upgrade was not provided');
         }
         const chainName = wallet.chain;
         const walletId = wallet.id;
@@ -514,7 +514,7 @@ const useDynamicWaas = () => {
             }
             throw new utils.DynamicError('Upgrade failed, please try again.');
         }
-    }), [environmentId, getWaasWalletConnector, primaryWallet, refresh]);
+    }), [environmentId, getWaasWalletConnector, refresh]);
     /**
      * Returns WaaS wallet instances from `userWallets` filtered by `key === 'dynamicwaas'`.
      *

package/src/lib/utils/hooks/useDynamicWaas/useDynamicWaas.js

@@ -84,7 +84,7 @@ const configWaasWalletConnector = ({ walletConnector, environmentId, apiBaseUrl,
 };
 const useDynamicWaas = () => {
     var _a, _b, _c, _d, _e, _f, _g;
-    const { setShowAuthFlow, primaryWallet } = useInternalDynamicContext();
+    const { setShowAuthFlow } = useInternalDynamicContext();
     const { addedWalletsIds, userWallets } = useInternalUserWallets();
     const user = useUser();
     const apiBaseUrl = useApiBaseUrl();
@@ -464,8 +464,8 @@ const useDynamicWaas = () => {
     });
     const upgradeToDynamicWaas = useCallback((_j) => __awaiter(void 0, [_j], void 0, function* ({ privateKey, wallet, password, }) {
         isUpgrading.current = true;
-        if (!primaryWallet) {
-            throw new DynamicError('Primary wallet not found');
+        if (!wallet) {
+            throw new DynamicError('Wallet to upgrade was not provided');
         }
         const chainName = wallet.chain;
         const walletId = wallet.id;
@@ -510,7 +510,7 @@ const useDynamicWaas = () => {
             }
             throw new DynamicError('Upgrade failed, please try again.');
         }
-    }), [environmentId, getWaasWalletConnector, primaryWallet, refresh]);
+    }), [environmentId, getWaasWalletConnector, refresh]);
     /**
      * Returns WaaS wallet instances from `userWallets` filtered by `key === 'dynamicwaas'`.
      *

package/src/lib/utils/hooks/usePrivateTokenBalances/index.d.ts

@@ -0,0 +1,2 @@
+export { usePrivateTokenBalances } from './usePrivateTokenBalances';
+export type { UsePrivateTokenBalancesArgs, UsePrivateTokenBalancesReturn, } from './usePrivateTokenBalances';

package/src/lib/utils/hooks/usePrivateTokenBalances/usePrivateTokenBalances.cjs

@@ -0,0 +1,27 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var useAleoShieldedBalances = require('../useAleoShieldedBalances/useAleoShieldedBalances.cjs');
+
+const usePrivateTokenBalances = (args = {}) => {
+    const { accountAddress, tokenAddresses, includeNativeBalance = false, includeFiat = false, chainName, networkId, } = args;
+    const { tokenBalances, isLoading, error, refetch, supportsShielded } = useAleoShieldedBalances.useAleoShieldedBalances({
+        accountAddress,
+        chainName,
+        includeFiat,
+        includeNativeBalance,
+        networkId,
+        tokenAddresses,
+    });
+    return {
+        error,
+        isLoading,
+        refetch,
+        supportsPrivateBalances: supportsShielded,
+        tokenBalances,
+    };
+};
+
+exports.usePrivateTokenBalances = usePrivateTokenBalances;