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

package/src/lib/widgets/DynamicWidget/components/ActiveWalletBalance/ActiveWalletBalance.js

@@ -1,7 +1,7 @@
 'use client'
 import { __awaiter } from '../../../../../../_virtual/_tslib.js';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useState, useRef, useMemo, useCallback, useEffect } from 'react';
+import { useState, useRef, useMemo, useEffect, useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
 import '../../../../context/DynamicContext/useDynamicContext/useDynamicContext.js';
 import { useInternalDynamicContext } from '../../../../context/DynamicContext/useDynamicContext/useInternalDynamicContext/useInternalDynamicContext.js';
@@ -123,6 +123,7 @@ import '../../views/ReceiveWalletFunds/ReceiveWalletFunds.js';
 import '../../../../store/state/multichainBalances.js';
 import '@dynamic-labs/store';
 import '../../../../shared/utils/functions/getInitialUrl/getInitialUrl.js';
+import { applyOptimisticUnshieldedDeductions, applyOptimisticShieldedAdditions, reconcileOptimisticShields } from './optimisticShield.js';
 import { TokenBalanceList } from './TokenBalanceList/TokenBalanceList.js';
 
 /** Component to display token balances for the primary wallet */
@@ -149,6 +150,57 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         includeNativeBalance: true,
     });
     const { tokenBalances: shieldedTokenBalances, isLoading: isLoadingShielded, refetch: refetchShielded, supportsShielded, } = useAleoShieldedBalances();
+    // Optimistic shield ledger. A shield broadcast resolves before the
+    //  public-balance mapping flips and well before the RecordScanner
+    //  index reflects the new private record, so naively trusting the
+    //  server feed shows a stale unshielded balance and an unchanged
+    //  shielded balance for ~10–90s after the user clicks. Pushing an
+    //  entry here deducts the burned amount from unshielded and prepends
+    //  / bumps the matching shielded row, then `reconcileOptimisticShields`
+    //  drops the entry as soon as either server feed catches up.
+    const [optimisticShields, setOptimisticShields] = useState([]);
+    const effectiveUnshieldedTokenBalances = useMemo(() => applyOptimisticUnshieldedDeductions(unshieldedTokenBalances !== null && unshieldedTokenBalances !== void 0 ? unshieldedTokenBalances : [], optimisticShields), [unshieldedTokenBalances, optimisticShields]);
+    const effectiveShieldedTokenBalances = useMemo(() => applyOptimisticShieldedAdditions(shieldedTokenBalances, optimisticShields), [shieldedTokenBalances, optimisticShields]);
+    // Reconcile + GC optimistic entries whenever either server feed
+    //  updates. The reconciler is pure; we short-circuit the state write
+    //  when nothing changed so downstream memos don't churn on every
+    //  refresh tick.
+    useEffect(() => {
+        setOptimisticShields((current) => {
+            if (current.length === 0)
+                return current;
+            const next = reconcileOptimisticShields(current, unshieldedTokenBalances !== null && unshieldedTokenBalances !== void 0 ? unshieldedTokenBalances : [], shieldedTokenBalances, Date.now());
+            return next.length === current.length ? current : next;
+        });
+    }, [unshieldedTokenBalances, shieldedTokenBalances]);
+    // Push helper used by both the manual Shield Manually CTA and the
+    //  auto-shield hook so the optimistic UI semantics are identical
+    //  whichever flow dispatches the broadcast.
+    const recordOptimisticShield = useCallback((info) => {
+        const { token, amount } = info;
+        const matchingShielded = shieldedTokenBalances.find((t) => token.isNative
+            ? Boolean(t.isNative)
+            : !t.isNative && t.address === token.address);
+        setOptimisticShields((current) => {
+            var _a, _b, _c, _d;
+            return [
+                ...current,
+                {
+                    amount,
+                    createdAtMs: Date.now(),
+                    decimals: (_a = token.decimals) !== null && _a !== void 0 ? _a : 0,
+                    isNative: Boolean(token.isNative),
+                    logoURI: (_b = token.logoURI) !== null && _b !== void 0 ? _b : '',
+                    name: token.name,
+                    preShieldShieldedRaw: BigInt(Math.round((_c = matchingShielded === null || matchingShielded === void 0 ? void 0 : matchingShielded.rawBalance) !== null && _c !== void 0 ? _c : 0)),
+                    preShieldUnshieldedRaw: BigInt(Math.round((_d = token.rawBalance) !== null && _d !== void 0 ? _d : 0)),
+                    price: token.price,
+                    symbol: token.symbol,
+                    tokenAddress: token.address,
+                },
+            ];
+        });
+    }, [shieldedTokenBalances]);
     /**
      * Tab state for chains that have a shielded/unshielded split. Defaults to
      * shielded so Aleo wallets land on their primary balance type. Other
@@ -193,11 +245,22 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
     //  Manually CTA, which prompts the user-paid confirmation modal.
     const { isShielding: isAutoShielding, currentlyShieldingTokenKeys: autoShieldingTokenKeys, } = useAleoAutoShieldSponsoredTokens({
         accountAddress: primaryWallet === null || primaryWallet === void 0 ? void 0 : primaryWallet.address,
-        onShielded: useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
-            yield fetchAccountBalances(true);
-            yield refetchShielded();
+        onShieldDispatched: recordOptimisticShield,
+        onShielded: useCallback(
+        // Parallel refresh — same reasoning as the manual shield path:
+        //  shield ops move value across both tabs, and serializing the
+        //  two refreshes doubled the visible latency for the Shielded
+        //  tab in the common case.
+        () => __awaiter(void 0, void 0, void 0, function* () {
+            return Promise.all([fetchAccountBalances(true), refetchShielded()]).then(() => undefined);
         }), [fetchAccountBalances, refetchShielded]),
         shieldHandle: aleoShieldHandle,
+        // Auto-shield reads the raw server feed (not the optimistic one):
+        //  once we deduct optimistically the to-be-shielded token drops to
+        //  zero in the effective list, which would suppress the next
+        //  auto-shield run before this one finishes. The auto-shield hook
+        //  has its own per-session idempotency (`seenKeys`) so it won't
+        //  re-fire for the same token anyway.
         unshieldedTokenBalances: unshieldedTokenBalances,
     });
     // Liveness handle for the manual post-shield poll — set to true when
@@ -210,12 +273,25 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
             isUnmountedRef.current = true;
         };
     }, []);
+    // Latest server-side unshielded list mirrored into a ref so the
+    //  post-shield convergence check can read the freshest value after
+    //  each polled refresh. `unshieldedTokenBalances` is closure-captured
+    //  by `handleShieldToken` at callback construction time, so without
+    //  this ref the predicate would read the pre-shield list forever and
+    //  the poll would never exit early. Reads from the raw server feed,
+    //  NOT the optimistic one — convergence means "on-chain effect
+    //  observed", which is only meaningful against the actual server
+    //  state.
+    const unshieldedTokenBalancesRef = useRef(unshieldedTokenBalances);
+    useEffect(() => {
+        unshieldedTokenBalancesRef.current = unshieldedTokenBalances;
+    }, [unshieldedTokenBalances]);
     // Token currently awaiting user-paid fee confirmation. Set when
     //  Shield Manually is clicked on a token Feemaster doesn't sponsor;
     //  cleared on Cancel or after the modal's Shield button dispatches.
     const [pendingShieldToken, setPendingShieldToken] = useState(null);
     const handleShieldToken = useCallback((token) => __awaiter(void 0, void 0, void 0, function* () {
-        var _f;
+        var _f, _g;
         if (!aleoShieldHandle || shieldingAddress)
             return;
         // `rawBalance` is the atomic-units count redcoast surfaces (number).
@@ -225,6 +301,14 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         const atomic = BigInt(Math.round((_f = token.rawBalance) !== null && _f !== void 0 ? _f : 0));
         if (atomic <= BigInt(0))
             return;
+        // Snapshot the pre-shield unshielded balance for the convergence
+        //  predicate below. Aleo's `transfer_public_to_private` burns the
+        //  public mapping value, so a successful shield must show up as a
+        //  drop in this token's `rawBalance`. Polling exits early once
+        //  that drop materializes — no need to keep refreshing on the
+        //  long-tail schedule when we've already observed the on-chain
+        //  effect.
+        const preShieldRawBalance = (_g = token.rawBalance) !== null && _g !== void 0 ? _g : 0;
         setShieldingAddress(token.address);
         let didBroadcast = false;
         try {
@@ -234,11 +318,22 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
                 tokenAddress: token.address,
             });
             didBroadcast = true;
-            // Refresh the unshielded list so the just-shielded balance drops to
-            // 0 in the redcoast feed. The shielded side will pick the new
-            // record up on its own polling once the RecordScanner indexes.
-            yield fetchAccountBalances(true);
-            yield refetchShielded();
+            // Optimistic balance update: deduct the burned amount from
+            //  unshielded and bump (or synthesise) the matching shielded
+            //  row before the server-side feeds catch up. Without this the
+            //  Shield Manually CTA flickers back into view during the
+            //  indexing tail and a fast user can issue a second shield
+            //  that fails server-side (validator rejects the now-zero
+            //  public balance) and looks to them like the first one
+            //  failed.
+            recordOptimisticShield({ amount: atomic, token });
+            // Refresh both tabs in parallel. Shield moves value across the
+            //  shielded/unshielded boundary, so both lists need to
+            //  converge. Running them in parallel (vs. sequential) halves
+            //  the visible refresh latency and shortens the window where
+            //  `useTokenBalances`' `isLoading` guard could drop a
+            //  concurrent fetch.
+            yield Promise.all([fetchAccountBalances(true), refetchShielded()]);
         }
         catch (err) {
             logger.debug('[ActiveWalletBalance] shieldToken failed', err);
@@ -249,7 +344,7 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         // The relay-accepted broadcast resolves *before* the
         //  public→private transition finalizes on-chain, so the immediate
         //  refresh above sees the pre-confirmation balance. Re-poll on the
-        //  shared backoff so the Unshielded row visibly drops to 0 and the
+        //  shared backoff so the Unshielded row visibly drops and the
         //  Shielded row picks the new record up without a manual reload.
         //  Polling is best-effort — errors are swallowed inside
         //  `pollOnShielded`. Skip when the broadcast itself failed; there's
@@ -257,10 +352,27 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         if (!didBroadcast)
             return;
         yield pollOnShielded(() => __awaiter(void 0, void 0, void 0, function* () {
-            yield fetchAccountBalances(true);
-            yield refetchShielded();
-        }), () => isUnmountedRef.current);
-    }), [aleoShieldHandle, fetchAccountBalances, refetchShielded, shieldingAddress]);
+            yield Promise.all([fetchAccountBalances(true), refetchShielded()]);
+        }), () => isUnmountedRef.current, () => {
+            var _a, _b;
+            // Convergence: the just-shielded token's unshielded raw
+            //  balance has dropped below the pre-shield value. We read
+            //  via the ref so we see whatever the store published after
+            //  the most recent poll, not the closure-captured list from
+            //  callback construction time. We don't require an exact 0
+            //  — additional unshielded credits could land between scans;
+            //  any decrease is sufficient evidence the burn took effect.
+            const current = (_a = unshieldedTokenBalancesRef.current) === null || _a === void 0 ? void 0 : _a.find((t) => t.address === token.address && t.isNative === token.isNative);
+            const currentRaw = (_b = current === null || current === void 0 ? void 0 : current.rawBalance) !== null && _b !== void 0 ? _b : 0;
+            return currentRaw < preShieldRawBalance;
+        });
+    }), [
+        aleoShieldHandle,
+        fetchAccountBalances,
+        recordOptimisticShield,
+        refetchShielded,
+        shieldingAddress,
+    ]);
     const getSecondaryAction = useCallback((token) => {
         // Only on the Unshielded tab, only when the connector exposes shield
         // helpers, only for tokens registered as shieldable, only for tokens
@@ -323,12 +435,12 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         shieldingAddress,
     ]);
     const tokenBalances = useMemo(() => supportsShielded && activeShieldTab === 'shielded'
-        ? shieldedTokenBalances
-        : unshieldedTokenBalances, [
+        ? effectiveShieldedTokenBalances
+        : effectiveUnshieldedTokenBalances, [
         activeShieldTab,
-        shieldedTokenBalances,
+        effectiveShieldedTokenBalances,
+        effectiveUnshieldedTokenBalances,
         supportsShielded,
-        unshieldedTokenBalances,
     ]);
     const filteredTokenBalances = useMemo(() => (tokenBalances === null || tokenBalances === void 0 ? void 0 : tokenBalances.filter((token) => token.name)) || [], [tokenBalances]);
     const totalValue = useMemo(() => filteredTokenBalances.reduce((acc, token) => acc + ((token === null || token === void 0 ? void 0 : token.marketValue) || 0), 0), [filteredTokenBalances]);
@@ -371,8 +483,14 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         setIsRefreshing(true);
         setIsSuccess(false);
         try {
-            if (supportsShielded && activeShieldTab === 'shielded') {
-                yield refetchShielded();
+            // Chains with a shielded/unshielded split (Aleo) refresh BOTH
+            //  tabs on a single click. A shield op moves value across the
+            //  boundary, so refreshing only the active tab leaves the other
+            //  visibly stale — the original complaint that drove this fix.
+            //  Other chains never had `refetchShielded` (no-op fallback) so
+            //  they still just hit `fetchAccountBalances` here.
+            if (supportsShielded) {
+                yield Promise.all([refetchShielded(), fetchAccountBalances(true)]);
             }
             else {
                 yield fetchAccountBalances(true);
@@ -396,7 +514,6 @@ const ActiveWalletBalance = ({ isLoading = false, }) => {
         fetchAccountBalances,
         refetchShielded,
         supportsShielded,
-        activeShieldTab,
     ]);
     const primaryWalletNativeBalance = () => {
         if (!primaryWallet ||

package/src/lib/widgets/DynamicWidget/components/ActiveWalletBalance/optimisticShield.cjs

@@ -0,0 +1,134 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// Default safety-net stale window for optimistic entries. Tuned to
+//  comfortably outlast the post-shield polling schedule (~106s) so
+//  reconciliation has a chance to fire on the real server-side state
+//  before the safety net trips.
+const OPTIMISTIC_SHIELD_STALE_MS = 180000;
+const matches = (entry, token) => {
+    if (entry.isNative)
+        return Boolean(token.isNative);
+    return !token.isNative && entry.tokenAddress === token.address;
+};
+/**
+ * Reduce each unshielded token's `rawBalance` by the sum of pending
+ * optimistic shields for the same `(address, isNative)`, clamped to 0.
+ * `balance` and `marketValue` scale by the same ratio so the fiat
+ * column doesn't disagree with the optimistic raw balance.
+ *
+ * Tokens with no pending optimistic shield pass through by reference
+ * (no copy) so downstream memos / identity comparisons don't churn on
+ * every render.
+ */
+const applyOptimisticUnshieldedDeductions = (balances, optimisticShields) => {
+    if (optimisticShields.length === 0)
+        return balances;
+    return balances.map((token) => {
+        var _a, _b;
+        const adjustments = optimisticShields.filter((o) => matches(o, token));
+        if (adjustments.length === 0)
+            return token;
+        const currentRaw = BigInt(Math.round((_a = token.rawBalance) !== null && _a !== void 0 ? _a : 0));
+        const totalAdjustment = adjustments.reduce((sum, o) => sum + o.amount, BigInt(0));
+        const newRaw = currentRaw > totalAdjustment ? currentRaw - totalAdjustment : BigInt(0);
+        // Ratio-scale display-units balance + fiat so they stay consistent
+        //  with the optimistic raw value. `currentRaw === 0n` happens when
+        //  the server feed has already caught up to zero but reconciliation
+        //  hasn't fired yet; treat ratio as 0 to keep display at 0.
+        const ratio = currentRaw > BigInt(0) ? Number(newRaw) / Number(currentRaw) : 0;
+        return Object.assign(Object.assign({}, token), { balance: ((_b = token.balance) !== null && _b !== void 0 ? _b : 0) * ratio, marketValue: token.marketValue !== undefined ? token.marketValue * ratio : undefined, rawBalance: Number(newRaw), rawBalanceString: newRaw.toString() });
+    });
+};
+/**
+ * Apply optimistic shield additions to the shielded balance list. For
+ * each optimistic shield with a matching `(address, isNative)` entry
+ * already in `shielded`, bump that entry; otherwise prepend a fresh
+ * synthesized row built from the entry's captured metadata.
+ *
+ * Returns a fresh array only when at least one optimistic shield
+ * applies. When `optimisticShields` is empty we pass through the
+ * input array by reference so consumers that compare by identity
+ * don't churn.
+ */
+const applyOptimisticShieldedAdditions = (shielded, optimisticShields) => {
+    if (optimisticShields.length === 0)
+        return shielded;
+    const consumedIndices = new Set();
+    const merged = shielded.map((token) => {
+        var _a, _b;
+        const adjustments = optimisticShields.filter((o, idx) => {
+            if (!matches(o, token))
+                return false;
+            consumedIndices.add(idx);
+            return true;
+        });
+        if (adjustments.length === 0)
+            return token;
+        const totalAtomic = adjustments.reduce((sum, o) => sum + o.amount, BigInt(0));
+        const newRaw = BigInt(Math.round((_a = token.rawBalance) !== null && _a !== void 0 ? _a : 0)) + totalAtomic;
+        const decimals = (_b = token.decimals) !== null && _b !== void 0 ? _b : 0;
+        const denominator = Math.pow(10, decimals);
+        const newDisplay = Number(newRaw) / denominator;
+        return Object.assign(Object.assign({}, token), { balance: newDisplay, marketValue: token.price !== undefined
+                ? newDisplay * token.price
+                : token.marketValue, rawBalance: Number(newRaw), rawBalanceString: newRaw.toString() });
+    });
+    // Prepend synthesized rows for any optimistic shield that didn't
+    //  fold into an existing shielded row above. New rows go to the top
+    //  of the list so the just-shielded token is immediately visible.
+    const synthesized = [];
+    optimisticShields.forEach((entry, idx) => {
+        if (consumedIndices.has(idx))
+            return;
+        const denominator = Math.pow(10, entry.decimals);
+        const display = Number(entry.amount) / denominator;
+        const marketValue = entry.price !== undefined ? display * entry.price : undefined;
+        synthesized.push(Object.assign(Object.assign({ address: entry.tokenAddress, balance: display, decimals: entry.decimals, isNative: entry.isNative, logoURI: entry.logoURI, name: entry.name, rawBalance: Number(entry.amount), rawBalanceString: entry.amount.toString(), symbol: entry.symbol }, (entry.price !== undefined ? { price: entry.price } : {})), (marketValue !== undefined ? { marketValue } : {})));
+    });
+    return [...synthesized, ...merged];
+};
+/**
+ * Filter the optimistic shield list down to entries that are still
+ * relevant. An entry is dropped when any of:
+ *
+ *  - the unshielded server feed reports a `rawBalance` strictly less
+ *    than `preShieldUnshieldedRaw` for that token (the burn was
+ *    observed on-chain),
+ *  - the shielded server feed reports a `rawBalance` strictly greater
+ *    than `preShieldShieldedRaw` for that token (the new record was
+ *    indexed),
+ *  - the unshielded server no longer lists the token at all (rare,
+ *    but means the public balance is effectively zero — our
+ *    optimistic deduct is moot),
+ *  - the entry is older than `staleMs` (safety net for shields whose
+ *    on-chain effect is masked by parallel inbound credits).
+ *
+ * Pure / module-scope so it's trivially unit-testable; the widget
+ * just calls it on every server-side balance update.
+ */
+const reconcileOptimisticShields = (optimisticShields, unshieldedTokenBalances, shieldedTokenBalances, nowMs, staleMs = OPTIMISTIC_SHIELD_STALE_MS) => optimisticShields.filter((entry) => {
+    var _a, _b;
+    if (nowMs - entry.createdAtMs > staleMs)
+        return false;
+    const unshielded = unshieldedTokenBalances.find((t) => matches(entry, t));
+    if (!unshielded)
+        return false;
+    const serverUnshielded = BigInt(Math.round((_a = unshielded.rawBalance) !== null && _a !== void 0 ? _a : 0));
+    if (serverUnshielded < entry.preShieldUnshieldedRaw)
+        return false;
+    const shielded = shieldedTokenBalances.find((t) => matches(entry, t));
+    const serverShielded = shielded
+        ? BigInt(Math.round((_b = shielded.rawBalance) !== null && _b !== void 0 ? _b : 0))
+        : BigInt(0);
+    if (serverShielded > entry.preShieldShieldedRaw)
+        return false;
+    return true;
+});
+
+exports.OPTIMISTIC_SHIELD_STALE_MS = OPTIMISTIC_SHIELD_STALE_MS;
+exports.applyOptimisticShieldedAdditions = applyOptimisticShieldedAdditions;
+exports.applyOptimisticUnshieldedDeductions = applyOptimisticUnshieldedDeductions;
+exports.reconcileOptimisticShields = reconcileOptimisticShields;

package/src/lib/widgets/DynamicWidget/components/ActiveWalletBalance/optimisticShield.d.ts

@@ -0,0 +1,69 @@
+import { TokenBalance } from '@dynamic-labs/sdk-api-core';
+/**
+ * In-memory record of a shield operation that has been accepted by the
+ *  prover/relay but not yet observed on-chain by either the public
+ *  balance mapping (Provable's `/mapping/balances/...` endpoint) or
+ *  the RecordScanner index. Until reconciliation drops it, the entry
+ *  forces the widget to display the post-shield state — unshielded
+ *  rawBalance reduced by `amount`, shielded rawBalance increased by
+ *  the same — so the Shield Manually CTA disappears the moment the
+ *  shield is broadcast instead of flickering back into view during
+ *  the indexing tail and tempting the user into a second shield.
+ */
+export type OptimisticShieldEntry = {
+    tokenAddress: string;
+    isNative: boolean;
+    amount: bigint;
+    preShieldUnshieldedRaw: bigint;
+    preShieldShieldedRaw: bigint;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logoURI: string;
+    price?: number;
+    createdAtMs: number;
+};
+export declare const OPTIMISTIC_SHIELD_STALE_MS = 180000;
+/**
+ * Reduce each unshielded token's `rawBalance` by the sum of pending
+ * optimistic shields for the same `(address, isNative)`, clamped to 0.
+ * `balance` and `marketValue` scale by the same ratio so the fiat
+ * column doesn't disagree with the optimistic raw balance.
+ *
+ * Tokens with no pending optimistic shield pass through by reference
+ * (no copy) so downstream memos / identity comparisons don't churn on
+ * every render.
+ */
+export declare const applyOptimisticUnshieldedDeductions: (balances: TokenBalance[], optimisticShields: ReadonlyArray<OptimisticShieldEntry>) => TokenBalance[];
+/**
+ * Apply optimistic shield additions to the shielded balance list. For
+ * each optimistic shield with a matching `(address, isNative)` entry
+ * already in `shielded`, bump that entry; otherwise prepend a fresh
+ * synthesized row built from the entry's captured metadata.
+ *
+ * Returns a fresh array only when at least one optimistic shield
+ * applies. When `optimisticShields` is empty we pass through the
+ * input array by reference so consumers that compare by identity
+ * don't churn.
+ */
+export declare const applyOptimisticShieldedAdditions: (shielded: TokenBalance[], optimisticShields: ReadonlyArray<OptimisticShieldEntry>) => TokenBalance[];
+/**
+ * Filter the optimistic shield list down to entries that are still
+ * relevant. An entry is dropped when any of:
+ *
+ *  - the unshielded server feed reports a `rawBalance` strictly less
+ *    than `preShieldUnshieldedRaw` for that token (the burn was
+ *    observed on-chain),
+ *  - the shielded server feed reports a `rawBalance` strictly greater
+ *    than `preShieldShieldedRaw` for that token (the new record was
+ *    indexed),
+ *  - the unshielded server no longer lists the token at all (rare,
+ *    but means the public balance is effectively zero — our
+ *    optimistic deduct is moot),
+ *  - the entry is older than `staleMs` (safety net for shields whose
+ *    on-chain effect is masked by parallel inbound credits).
+ *
+ * Pure / module-scope so it's trivially unit-testable; the widget
+ * just calls it on every server-side balance update.
+ */
+export declare const reconcileOptimisticShields: (optimisticShields: ReadonlyArray<OptimisticShieldEntry>, unshieldedTokenBalances: TokenBalance[], shieldedTokenBalances: TokenBalance[], nowMs: number, staleMs?: number) => OptimisticShieldEntry[];

package/src/lib/widgets/DynamicWidget/components/ActiveWalletBalance/optimisticShield.js

@@ -0,0 +1,127 @@
+'use client'
+// Default safety-net stale window for optimistic entries. Tuned to
+//  comfortably outlast the post-shield polling schedule (~106s) so
+//  reconciliation has a chance to fire on the real server-side state
+//  before the safety net trips.
+const OPTIMISTIC_SHIELD_STALE_MS = 180000;
+const matches = (entry, token) => {
+    if (entry.isNative)
+        return Boolean(token.isNative);
+    return !token.isNative && entry.tokenAddress === token.address;
+};
+/**
+ * Reduce each unshielded token's `rawBalance` by the sum of pending
+ * optimistic shields for the same `(address, isNative)`, clamped to 0.
+ * `balance` and `marketValue` scale by the same ratio so the fiat
+ * column doesn't disagree with the optimistic raw balance.
+ *
+ * Tokens with no pending optimistic shield pass through by reference
+ * (no copy) so downstream memos / identity comparisons don't churn on
+ * every render.
+ */
+const applyOptimisticUnshieldedDeductions = (balances, optimisticShields) => {
+    if (optimisticShields.length === 0)
+        return balances;
+    return balances.map((token) => {
+        var _a, _b;
+        const adjustments = optimisticShields.filter((o) => matches(o, token));
+        if (adjustments.length === 0)
+            return token;
+        const currentRaw = BigInt(Math.round((_a = token.rawBalance) !== null && _a !== void 0 ? _a : 0));
+        const totalAdjustment = adjustments.reduce((sum, o) => sum + o.amount, BigInt(0));
+        const newRaw = currentRaw > totalAdjustment ? currentRaw - totalAdjustment : BigInt(0);
+        // Ratio-scale display-units balance + fiat so they stay consistent
+        //  with the optimistic raw value. `currentRaw === 0n` happens when
+        //  the server feed has already caught up to zero but reconciliation
+        //  hasn't fired yet; treat ratio as 0 to keep display at 0.
+        const ratio = currentRaw > BigInt(0) ? Number(newRaw) / Number(currentRaw) : 0;
+        return Object.assign(Object.assign({}, token), { balance: ((_b = token.balance) !== null && _b !== void 0 ? _b : 0) * ratio, marketValue: token.marketValue !== undefined ? token.marketValue * ratio : undefined, rawBalance: Number(newRaw), rawBalanceString: newRaw.toString() });
+    });
+};
+/**
+ * Apply optimistic shield additions to the shielded balance list. For
+ * each optimistic shield with a matching `(address, isNative)` entry
+ * already in `shielded`, bump that entry; otherwise prepend a fresh
+ * synthesized row built from the entry's captured metadata.
+ *
+ * Returns a fresh array only when at least one optimistic shield
+ * applies. When `optimisticShields` is empty we pass through the
+ * input array by reference so consumers that compare by identity
+ * don't churn.
+ */
+const applyOptimisticShieldedAdditions = (shielded, optimisticShields) => {
+    if (optimisticShields.length === 0)
+        return shielded;
+    const consumedIndices = new Set();
+    const merged = shielded.map((token) => {
+        var _a, _b;
+        const adjustments = optimisticShields.filter((o, idx) => {
+            if (!matches(o, token))
+                return false;
+            consumedIndices.add(idx);
+            return true;
+        });
+        if (adjustments.length === 0)
+            return token;
+        const totalAtomic = adjustments.reduce((sum, o) => sum + o.amount, BigInt(0));
+        const newRaw = BigInt(Math.round((_a = token.rawBalance) !== null && _a !== void 0 ? _a : 0)) + totalAtomic;
+        const decimals = (_b = token.decimals) !== null && _b !== void 0 ? _b : 0;
+        const denominator = Math.pow(10, decimals);
+        const newDisplay = Number(newRaw) / denominator;
+        return Object.assign(Object.assign({}, token), { balance: newDisplay, marketValue: token.price !== undefined
+                ? newDisplay * token.price
+                : token.marketValue, rawBalance: Number(newRaw), rawBalanceString: newRaw.toString() });
+    });
+    // Prepend synthesized rows for any optimistic shield that didn't
+    //  fold into an existing shielded row above. New rows go to the top
+    //  of the list so the just-shielded token is immediately visible.
+    const synthesized = [];
+    optimisticShields.forEach((entry, idx) => {
+        if (consumedIndices.has(idx))
+            return;
+        const denominator = Math.pow(10, entry.decimals);
+        const display = Number(entry.amount) / denominator;
+        const marketValue = entry.price !== undefined ? display * entry.price : undefined;
+        synthesized.push(Object.assign(Object.assign({ address: entry.tokenAddress, balance: display, decimals: entry.decimals, isNative: entry.isNative, logoURI: entry.logoURI, name: entry.name, rawBalance: Number(entry.amount), rawBalanceString: entry.amount.toString(), symbol: entry.symbol }, (entry.price !== undefined ? { price: entry.price } : {})), (marketValue !== undefined ? { marketValue } : {})));
+    });
+    return [...synthesized, ...merged];
+};
+/**
+ * Filter the optimistic shield list down to entries that are still
+ * relevant. An entry is dropped when any of:
+ *
+ *  - the unshielded server feed reports a `rawBalance` strictly less
+ *    than `preShieldUnshieldedRaw` for that token (the burn was
+ *    observed on-chain),
+ *  - the shielded server feed reports a `rawBalance` strictly greater
+ *    than `preShieldShieldedRaw` for that token (the new record was
+ *    indexed),
+ *  - the unshielded server no longer lists the token at all (rare,
+ *    but means the public balance is effectively zero — our
+ *    optimistic deduct is moot),
+ *  - the entry is older than `staleMs` (safety net for shields whose
+ *    on-chain effect is masked by parallel inbound credits).
+ *
+ * Pure / module-scope so it's trivially unit-testable; the widget
+ * just calls it on every server-side balance update.
+ */
+const reconcileOptimisticShields = (optimisticShields, unshieldedTokenBalances, shieldedTokenBalances, nowMs, staleMs = OPTIMISTIC_SHIELD_STALE_MS) => optimisticShields.filter((entry) => {
+    var _a, _b;
+    if (nowMs - entry.createdAtMs > staleMs)
+        return false;
+    const unshielded = unshieldedTokenBalances.find((t) => matches(entry, t));
+    if (!unshielded)
+        return false;
+    const serverUnshielded = BigInt(Math.round((_a = unshielded.rawBalance) !== null && _a !== void 0 ? _a : 0));
+    if (serverUnshielded < entry.preShieldUnshieldedRaw)
+        return false;
+    const shielded = shieldedTokenBalances.find((t) => matches(entry, t));
+    const serverShielded = shielded
+        ? BigInt(Math.round((_b = shielded.rawBalance) !== null && _b !== void 0 ? _b : 0))
+        : BigInt(0);
+    if (serverShielded > entry.preShieldShieldedRaw)
+        return false;
+    return true;
+});
+
+export { OPTIMISTIC_SHIELD_STALE_MS, applyOptimisticShieldedAdditions, applyOptimisticUnshieldedDeductions, reconcileOptimisticShields };