@dynamic-labs/sdk-react-core 4.80.0 → 4.82.0

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

@@ -0,0 +1,263 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _tslib = require('../../../../../_virtual/_tslib.cjs');
+var React = require('react');
+
+// Backoff schedule for the post-shield refresh. `shieldToken` resolves
+//  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.
+const REFRESH_DELAYS_MS = [
+    3000, 5000, 8000, 12000, 18000,
+];
+/**
+ * Selects which of `tokens` should attempt an auto-shield on this cycle.
+ * A token is a candidate when:
+ *  - it has a positive raw balance,
+ *  - the registry recognises it as shieldable,
+ *  - it has a usable idempotency key (address OR `isNative: true`), and
+ *  - we haven't already attempted it for this `accountAddress` this
+ *    session (`seenKeys`).
+ *
+ * Pure / module-scope so the effect body stays small (the cognitive
+ *  complexity counter doesn't have to walk into the predicate).
+ */
+const buildShieldCandidates = (args) => {
+    const { tokens, accountAddress, shieldHandle, seenKeys } = args;
+    return tokens.filter((token) => {
+        var _a;
+        if (!token.rawBalance || token.rawBalance <= 0)
+            return false;
+        if (!shieldHandle.canShieldToken({
+            address: token.address,
+            isNative: token.isNative,
+        })) {
+            return false;
+        }
+        const tokenKey = (_a = token.address) !== null && _a !== void 0 ? _a : (token.isNative ? '__native__' : '');
+        if (!tokenKey)
+            return false;
+        return !seenKeys.has(`${accountAddress}:${tokenKey}`);
+    });
+};
+/**
+ * Attempt to auto-shield a single token. Returns `true` only if the shield
+ * ceremony broadcast successfully. On any short-circuit (sponsorship miss,
+ * zero atomic units, dispatch error) the seen-key is removed so the next
+ * refresh can retry. Cancellation is checked via the `isCancelled` thunk
+ * so the effect-cleanup `cancelled` flag stays in scope.
+ */
+const tryShieldOneToken = (token, deps) => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    const { accountAddress, shieldHandle, seenKeys, isCancelled } = deps;
+    const tokenKey = (_a = token.address) !== null && _a !== void 0 ? _a : '__native__';
+    const key = `${accountAddress}:${tokenKey}`;
+    seenKeys.add(key);
+    let sponsored = false;
+    try {
+        sponsored =
+            (_c = (yield ((_b = shieldHandle.isShieldSponsored) === null || _b === void 0 ? void 0 : _b.call(shieldHandle, {
+                address: token.address,
+                isNative: token.isNative,
+            })))) !== null && _c !== void 0 ? _c : false;
+    }
+    catch (_e) {
+        sponsored = false;
+    }
+    if (isCancelled())
+        return false;
+    if (!sponsored) {
+        seenKeys.delete(key);
+        return false;
+    }
+    const atomic = BigInt(Math.round((_d = token.rawBalance) !== null && _d !== void 0 ? _d : 0));
+    if (atomic <= BigInt(0)) {
+        seenKeys.delete(key);
+        return false;
+    }
+    try {
+        yield shieldHandle.shieldToken({
+            amount: atomic,
+            isNative: token.isNative,
+            tokenAddress: token.address,
+        });
+        return true;
+    }
+    catch (_f) {
+        seenKeys.delete(key);
+        return false;
+    }
+});
+/**
+ * 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
+ * per-iteration errors (refresh is best-effort).
+ */
+const pollOnShielded = (onShielded, isCancelled) => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    for (const delay of REFRESH_DELAYS_MS) {
+        if (isCancelled())
+            return;
+        yield new Promise((resolve) => setTimeout(resolve, delay));
+        if (isCancelled())
+            return;
+        try {
+            yield onShielded();
+        }
+        catch (_g) {
+            /* swallow — refresh is best-effort */
+        }
+    }
+});
+const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, }) => {
+    // Tracks `(accountAddress:tokenAddress)` we've already attempted in this
+    //  session. Cleared implicitly on a full page reload.
+    const seenKeysRef = React.useRef(new Set());
+    const [isShielding, setIsShielding] = React.useState(false);
+    // Counter of in-flight `run()` promises. Each effect-run that has at
+    //  least one candidate increments on entry and decrements in `.finally()`.
+    //  Without this counter, a stale `run()` resolving after a re-fire could
+    //  flip `isShielding` to `false` while a *new* `run()` is still active —
+    //  the indicator would blink off mid-shield, and the empty-candidates
+    //  path of a new effect-run would also wrongly clear the indicator
+    //  belonging to a still-running ceremony. We only call `setIsShielding(false)`
+    //  when the counter reaches `0`.
+    const activeRunsRef = React.useRef(0);
+    // Tracks component-lifetime mount state. The per-effect `cancelled`
+    //  variable signals "this particular run is no longer relevant", but
+    //  it gets flipped to `true` whenever deps change (e.g. when an
+    //  `onShielded` balance refresh updates `unshieldedTokenBalances`).
+    //  Using `cancelled` to gate state cleanup would leave `isShielding`
+    //  stuck at `true` because the cancelled run's `.finally()` skips the
+    //  setState. `mountedRef` only flips on actual unmount.
+    //
+    //  Important: refs persist across React 18 Strict Mode's fake
+    //  unmount/re-mount cycle in dev. We MUST set `mountedRef.current =
+    //  true` at the start of the mount effect body (not just at
+    //  `useRef(true)` init), or Strict Mode's first cleanup leaves the
+    //  ref `false` for the entire second mount, and `setIsShielding(false)`
+    //  is permanently skipped.
+    const mountedRef = React.useRef(true);
+    React.useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    // Content fingerprint for the balance list. We re-run the effect only
+    //  when balances *meaningfully* change (token added/removed/balance
+    //  shifted), not on every render where the parent passes a new array
+    //  reference. Without this, parent re-renders re-fire the effect, the
+    //  cleanup sets `cancelled = true` on the in-flight run, and the
+    //  shieldToken dispatch never happens after the slow `isShieldSponsored`
+    //  network call resolves.
+    const balanceFingerprint = React.useMemo(() => (unshieldedTokenBalances !== null && unshieldedTokenBalances !== void 0 ? unshieldedTokenBalances : [])
+        .map((t) => {
+        var _a, _b;
+        return `${(_a = t.address) !== null && _a !== void 0 ? _a : '__native__'}|${t.isNative ? 1 : 0}|${(_b = t.rawBalance) !== null && _b !== void 0 ? _b : 0}`;
+    })
+        // Use `localeCompare` so the sort is locale-aware and stable across
+        //  JS engines (default `Array.prototype.sort` on strings is
+        //  implementation-defined for non-ASCII input — `localeCompare` is
+        //  the spec-mandated comparator for human-meaningful ordering).
+        .sort((a, b) => a.localeCompare(b))
+        .join(','), [unshieldedTokenBalances]);
+    React.useEffect(() => {
+        if (!accountAddress || !shieldHandle)
+            return;
+        if (!unshieldedTokenBalances || unshieldedTokenBalances.length === 0) {
+            return;
+        }
+        if (typeof shieldHandle.isShieldSponsored !== 'function')
+            return;
+        let cancelled = false;
+        const isCancelled = () => cancelled;
+        const candidates = buildShieldCandidates({
+            accountAddress,
+            seenKeys: seenKeysRef.current,
+            shieldHandle,
+            tokens: unshieldedTokenBalances,
+        });
+        if (candidates.length === 0) {
+            // No candidates this cycle — only clear the indicator if no other
+            //  run is still in flight. Without the counter check, a re-fire
+            //  whose cleanup cancelled the previous run would clobber the
+            //  still-active in-flight indicator owned by a different effect-run
+            //  (which can happen when deps churn during a ceremony).
+            if (mountedRef.current && activeRunsRef.current === 0) {
+                setIsShielding(false);
+            }
+            return;
+        }
+        // Flip the indicator on synchronously inside the effect so React
+        //  groups it with the initial render commit (the call site is
+        //  inherently `act()`-wrapped by `renderHook` / the user-event flow
+        //  that drove the props change). Setting it inside the async `run()`
+        //  fires the state update in a microtask AFTER the effect returns,
+        //  which trips React 18's "update not wrapped in act(...)" warning
+        //  that the test setup converts to a failure.
+        if (mountedRef.current)
+            setIsShielding(true);
+        activeRunsRef.current += 1;
+        const run = () => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+            let didShield = false;
+            for (const token of candidates) {
+                if (cancelled)
+                    return;
+                const ok = yield tryShieldOneToken(token, {
+                    accountAddress,
+                    isCancelled,
+                    seenKeys: seenKeysRef.current,
+                    shieldHandle,
+                });
+                if (ok)
+                    didShield = true;
+            }
+            if (didShield && !cancelled && onShielded) {
+                yield pollOnShielded(onShielded, isCancelled);
+            }
+        });
+        run()
+            .catch(() => {
+            /* swallow — see method jsdoc */
+        })
+            .finally(() => {
+            // Decrement the in-flight counter. Only clear the indicator if
+            //  this was the LAST active run — otherwise an overlapping run
+            //  (started by a re-fire while this one was mid-shield) is still
+            //  shielding and the UI should keep showing "Auto-shielding…".
+            activeRunsRef.current = Math.max(0, activeRunsRef.current - 1);
+            if (!mountedRef.current)
+                return;
+            if (activeRunsRef.current > 0)
+                return;
+            // Defer the setState by one macrotask via `setTimeout(0)`. In
+            //  production the 0ms delay is imperceptible. In tests it lets the
+            //  framework's afterEach `act()` drain wrap the trailing state
+            //  update, instead of firing it inside the synchronous microtask
+            //  drain of a `waitFor` poll where it sits OUTSIDE any act region
+            //  and trips React 18's "update not wrapped in act" warning gate.
+            //  We re-check the counter inside the timer callback because a
+            //  fresh effect-run could have incremented it during the 0ms gap.
+            setTimeout(() => {
+                if (mountedRef.current && activeRunsRef.current === 0) {
+                    setIsShielding(false);
+                }
+            }, 0);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // `unshieldedTokenBalances` is read inside the effect but tracked via
+        //  `balanceFingerprint` so reference-only changes don't re-fire and
+        //  cancel an in-flight shield ceremony.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [accountAddress, balanceFingerprint, shieldHandle, onShielded]);
+    return { isShielding };
+};
+
+exports.useAleoAutoShieldSponsoredTokens = useAleoAutoShieldSponsoredTokens;

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

@@ -0,0 +1,59 @@
+import { TokenBalance } from '@dynamic-labs/sdk-api-core';
+/**
+ * Connector duck-type — matches the `aleoShieldHandle` shape that
+ * `ActiveWalletBalance` already uses for the Shield Manually CTA. Kept
+ * here as a minimal local type so we don't pull a hard dependency on
+ * `@dynamic-labs/aleo` into sdk-react-core.
+ */
+type AleoShieldHandle = {
+    canShieldToken: (token: {
+        address?: string;
+        isNative?: boolean;
+    }) => boolean;
+    shieldToken: (args: {
+        tokenAddress: string;
+        isNative?: boolean;
+        amount: bigint;
+    }) => Promise<string>;
+    isShieldSponsored?: (token: {
+        address?: string;
+        isNative?: boolean;
+    }) => Promise<boolean>;
+};
+type UseAleoAutoShieldSponsoredTokensArgs = {
+    accountAddress: string | undefined;
+    unshieldedTokenBalances: TokenBalance[];
+    shieldHandle: AleoShieldHandle | undefined;
+    onShielded?: () => Promise<void> | void;
+};
+/**
+ * On Aleo wallet load (and on each subsequent unshielded-balance refresh),
+ * auto-shields tokens whose `transfer_public_to_private` transition the
+ * Aleo Feemaster currently sponsors. Tokens that aren't sponsored stay
+ * untouched — the user can still trigger them manually via the existing
+ * Shield Manually CTA, which dispatches with user-paid fees.
+ *
+ * Idempotency is per-session, keyed by `(accountAddress, tokenAddress)`.
+ * On error the key is removed so the next refresh can retry. Auto-shield
+ * runs sequentially so a single sponsored quota can't be drained by N
+ * concurrent dispatches; the caller's "single shield in flight" UX is
+ * preserved.
+ *
+ * Failures are swallowed by design — auto-shield is a background
+ * optimisation, never a user-facing flow.
+ */
+/**
+ * Return value of `useAleoAutoShieldSponsoredTokens`. Consumers can read
+ *  `isShielding` to render a small "Shielding…" indicator while a
+ *  background ceremony is in flight.
+ */
+export type UseAleoAutoShieldSponsoredTokensResult = {
+    /**
+     * `true` while at least one auto-shield ceremony is broadcasting
+     *  (between candidate selection and the post-success refresh callback).
+     *  Goes back to `false` on cleanup or once the run resolves.
+     */
+    isShielding: boolean;
+};
+export declare const useAleoAutoShieldSponsoredTokens: ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, }: UseAleoAutoShieldSponsoredTokensArgs) => UseAleoAutoShieldSponsoredTokensResult;
+export {};

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

@@ -0,0 +1,259 @@
+'use client'
+import { __awaiter } from '../../../../../_virtual/_tslib.js';
+import { useRef, useState, useEffect, useMemo } from 'react';
+
+// Backoff schedule for the post-shield refresh. `shieldToken` resolves
+//  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.
+const REFRESH_DELAYS_MS = [
+    3000, 5000, 8000, 12000, 18000,
+];
+/**
+ * Selects which of `tokens` should attempt an auto-shield on this cycle.
+ * A token is a candidate when:
+ *  - it has a positive raw balance,
+ *  - the registry recognises it as shieldable,
+ *  - it has a usable idempotency key (address OR `isNative: true`), and
+ *  - we haven't already attempted it for this `accountAddress` this
+ *    session (`seenKeys`).
+ *
+ * Pure / module-scope so the effect body stays small (the cognitive
+ *  complexity counter doesn't have to walk into the predicate).
+ */
+const buildShieldCandidates = (args) => {
+    const { tokens, accountAddress, shieldHandle, seenKeys } = args;
+    return tokens.filter((token) => {
+        var _a;
+        if (!token.rawBalance || token.rawBalance <= 0)
+            return false;
+        if (!shieldHandle.canShieldToken({
+            address: token.address,
+            isNative: token.isNative,
+        })) {
+            return false;
+        }
+        const tokenKey = (_a = token.address) !== null && _a !== void 0 ? _a : (token.isNative ? '__native__' : '');
+        if (!tokenKey)
+            return false;
+        return !seenKeys.has(`${accountAddress}:${tokenKey}`);
+    });
+};
+/**
+ * Attempt to auto-shield a single token. Returns `true` only if the shield
+ * ceremony broadcast successfully. On any short-circuit (sponsorship miss,
+ * zero atomic units, dispatch error) the seen-key is removed so the next
+ * refresh can retry. Cancellation is checked via the `isCancelled` thunk
+ * so the effect-cleanup `cancelled` flag stays in scope.
+ */
+const tryShieldOneToken = (token, deps) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    const { accountAddress, shieldHandle, seenKeys, isCancelled } = deps;
+    const tokenKey = (_a = token.address) !== null && _a !== void 0 ? _a : '__native__';
+    const key = `${accountAddress}:${tokenKey}`;
+    seenKeys.add(key);
+    let sponsored = false;
+    try {
+        sponsored =
+            (_c = (yield ((_b = shieldHandle.isShieldSponsored) === null || _b === void 0 ? void 0 : _b.call(shieldHandle, {
+                address: token.address,
+                isNative: token.isNative,
+            })))) !== null && _c !== void 0 ? _c : false;
+    }
+    catch (_e) {
+        sponsored = false;
+    }
+    if (isCancelled())
+        return false;
+    if (!sponsored) {
+        seenKeys.delete(key);
+        return false;
+    }
+    const atomic = BigInt(Math.round((_d = token.rawBalance) !== null && _d !== void 0 ? _d : 0));
+    if (atomic <= BigInt(0)) {
+        seenKeys.delete(key);
+        return false;
+    }
+    try {
+        yield shieldHandle.shieldToken({
+            amount: atomic,
+            isNative: token.isNative,
+            tokenAddress: token.address,
+        });
+        return true;
+    }
+    catch (_f) {
+        seenKeys.delete(key);
+        return false;
+    }
+});
+/**
+ * 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
+ * per-iteration errors (refresh is best-effort).
+ */
+const pollOnShielded = (onShielded, isCancelled) => __awaiter(void 0, void 0, void 0, function* () {
+    for (const delay of REFRESH_DELAYS_MS) {
+        if (isCancelled())
+            return;
+        yield new Promise((resolve) => setTimeout(resolve, delay));
+        if (isCancelled())
+            return;
+        try {
+            yield onShielded();
+        }
+        catch (_g) {
+            /* swallow — refresh is best-effort */
+        }
+    }
+});
+const useAleoAutoShieldSponsoredTokens = ({ accountAddress, unshieldedTokenBalances, shieldHandle, onShielded, }) => {
+    // Tracks `(accountAddress:tokenAddress)` we've already attempted in this
+    //  session. Cleared implicitly on a full page reload.
+    const seenKeysRef = useRef(new Set());
+    const [isShielding, setIsShielding] = useState(false);
+    // Counter of in-flight `run()` promises. Each effect-run that has at
+    //  least one candidate increments on entry and decrements in `.finally()`.
+    //  Without this counter, a stale `run()` resolving after a re-fire could
+    //  flip `isShielding` to `false` while a *new* `run()` is still active —
+    //  the indicator would blink off mid-shield, and the empty-candidates
+    //  path of a new effect-run would also wrongly clear the indicator
+    //  belonging to a still-running ceremony. We only call `setIsShielding(false)`
+    //  when the counter reaches `0`.
+    const activeRunsRef = useRef(0);
+    // Tracks component-lifetime mount state. The per-effect `cancelled`
+    //  variable signals "this particular run is no longer relevant", but
+    //  it gets flipped to `true` whenever deps change (e.g. when an
+    //  `onShielded` balance refresh updates `unshieldedTokenBalances`).
+    //  Using `cancelled` to gate state cleanup would leave `isShielding`
+    //  stuck at `true` because the cancelled run's `.finally()` skips the
+    //  setState. `mountedRef` only flips on actual unmount.
+    //
+    //  Important: refs persist across React 18 Strict Mode's fake
+    //  unmount/re-mount cycle in dev. We MUST set `mountedRef.current =
+    //  true` at the start of the mount effect body (not just at
+    //  `useRef(true)` init), or Strict Mode's first cleanup leaves the
+    //  ref `false` for the entire second mount, and `setIsShielding(false)`
+    //  is permanently skipped.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    // Content fingerprint for the balance list. We re-run the effect only
+    //  when balances *meaningfully* change (token added/removed/balance
+    //  shifted), not on every render where the parent passes a new array
+    //  reference. Without this, parent re-renders re-fire the effect, the
+    //  cleanup sets `cancelled = true` on the in-flight run, and the
+    //  shieldToken dispatch never happens after the slow `isShieldSponsored`
+    //  network call resolves.
+    const balanceFingerprint = useMemo(() => (unshieldedTokenBalances !== null && unshieldedTokenBalances !== void 0 ? unshieldedTokenBalances : [])
+        .map((t) => {
+        var _a, _b;
+        return `${(_a = t.address) !== null && _a !== void 0 ? _a : '__native__'}|${t.isNative ? 1 : 0}|${(_b = t.rawBalance) !== null && _b !== void 0 ? _b : 0}`;
+    })
+        // Use `localeCompare` so the sort is locale-aware and stable across
+        //  JS engines (default `Array.prototype.sort` on strings is
+        //  implementation-defined for non-ASCII input — `localeCompare` is
+        //  the spec-mandated comparator for human-meaningful ordering).
+        .sort((a, b) => a.localeCompare(b))
+        .join(','), [unshieldedTokenBalances]);
+    useEffect(() => {
+        if (!accountAddress || !shieldHandle)
+            return;
+        if (!unshieldedTokenBalances || unshieldedTokenBalances.length === 0) {
+            return;
+        }
+        if (typeof shieldHandle.isShieldSponsored !== 'function')
+            return;
+        let cancelled = false;
+        const isCancelled = () => cancelled;
+        const candidates = buildShieldCandidates({
+            accountAddress,
+            seenKeys: seenKeysRef.current,
+            shieldHandle,
+            tokens: unshieldedTokenBalances,
+        });
+        if (candidates.length === 0) {
+            // No candidates this cycle — only clear the indicator if no other
+            //  run is still in flight. Without the counter check, a re-fire
+            //  whose cleanup cancelled the previous run would clobber the
+            //  still-active in-flight indicator owned by a different effect-run
+            //  (which can happen when deps churn during a ceremony).
+            if (mountedRef.current && activeRunsRef.current === 0) {
+                setIsShielding(false);
+            }
+            return;
+        }
+        // Flip the indicator on synchronously inside the effect so React
+        //  groups it with the initial render commit (the call site is
+        //  inherently `act()`-wrapped by `renderHook` / the user-event flow
+        //  that drove the props change). Setting it inside the async `run()`
+        //  fires the state update in a microtask AFTER the effect returns,
+        //  which trips React 18's "update not wrapped in act(...)" warning
+        //  that the test setup converts to a failure.
+        if (mountedRef.current)
+            setIsShielding(true);
+        activeRunsRef.current += 1;
+        const run = () => __awaiter(void 0, void 0, void 0, function* () {
+            let didShield = false;
+            for (const token of candidates) {
+                if (cancelled)
+                    return;
+                const ok = yield tryShieldOneToken(token, {
+                    accountAddress,
+                    isCancelled,
+                    seenKeys: seenKeysRef.current,
+                    shieldHandle,
+                });
+                if (ok)
+                    didShield = true;
+            }
+            if (didShield && !cancelled && onShielded) {
+                yield pollOnShielded(onShielded, isCancelled);
+            }
+        });
+        run()
+            .catch(() => {
+            /* swallow — see method jsdoc */
+        })
+            .finally(() => {
+            // Decrement the in-flight counter. Only clear the indicator if
+            //  this was the LAST active run — otherwise an overlapping run
+            //  (started by a re-fire while this one was mid-shield) is still
+            //  shielding and the UI should keep showing "Auto-shielding…".
+            activeRunsRef.current = Math.max(0, activeRunsRef.current - 1);
+            if (!mountedRef.current)
+                return;
+            if (activeRunsRef.current > 0)
+                return;
+            // Defer the setState by one macrotask via `setTimeout(0)`. In
+            //  production the 0ms delay is imperceptible. In tests it lets the
+            //  framework's afterEach `act()` drain wrap the trailing state
+            //  update, instead of firing it inside the synchronous microtask
+            //  drain of a `waitFor` poll where it sits OUTSIDE any act region
+            //  and trips React 18's "update not wrapped in act" warning gate.
+            //  We re-check the counter inside the timer callback because a
+            //  fresh effect-run could have incremented it during the 0ms gap.
+            setTimeout(() => {
+                if (mountedRef.current && activeRunsRef.current === 0) {
+                    setIsShielding(false);
+                }
+            }, 0);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // `unshieldedTokenBalances` is read inside the effect but tracked via
+        //  `balanceFingerprint` so reference-only changes don't re-fire and
+        //  cancel an in-flight shield ceremony.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [accountAddress, balanceFingerprint, shieldHandle, onShielded]);
+    return { isShielding };
+};
+
+export { useAleoAutoShieldSponsoredTokens };

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

@@ -0,0 +1 @@
+export { useAleoShieldedBalances } from './useAleoShieldedBalances';