@augustdigital/sdk 8.11.0 → 8.13.0

package/lib/core/helpers/vault-version.js

@@ -16,7 +16,21 @@ function getAddressChainType(address) {
         return 'sui';
     return 'evm';
 }
-// @todo: move to backend
+/**
+ * Classify a vault's protocol version from its address alone.
+ *
+ * @deprecated Use {@link getVaultVersionV2} instead. This V1 classifier can only
+ * recognise a multi-asset vault (`evm-2`) if its address is hard-coded in the
+ * static `MULTI_ASSET_VAULTS` list. Any multi-asset vault missing from that list
+ * is silently misclassified as `evm-1`, which broke deposit preview/simulation in
+ * the 2026-07-06 Sentora incident. `getVaultVersionV2` reads the backend
+ * `internal_type` (falling back to the static list only as a safety net), so new
+ * vaults classify correctly without a code change. Retained as a non-breaking
+ * shim; scheduled for removal in the next major.
+ *
+ * @param vault - The vault contract address (EVM `0x…`, Solana, or Stellar).
+ * @returns The vault version slug, or `undefined` for empty/invalid input.
+ */
 function getVaultVersion(vault) {
     if (!vault)
         return;

package/lib/core/helpers/vaults.d.ts

@@ -8,7 +8,7 @@ export declare const isBadVault: (address?: string) => boolean;
 import { getAddressChainType, getVaultVersion, getVaultVersionV2 } from './vault-version';
 export { getAddressChainType, getVaultVersion, getVaultVersionV2 };
 export declare const REWARD_DISTRIBUTOR_ADDRESS: (chainId: number) => string[];
-export declare const AVAX_PRICE_FEED_ADDRESS: (chainId: number) => "0xFF3EEb22B5E3dE6e705b44749C2559d704923FD7" | "0x";
+export declare const AVAX_PRICE_FEED_ADDRESS: (chainId: number) => "0x" | "0xFF3EEb22B5E3dE6e705b44749C2559d704923FD7";
 export declare function getVaultSymbol(vault: IAddress, provider: IContractRunner): Promise<string | undefined>;
 /**
  * @deprecated

package/lib/core/index.d.ts

@@ -11,9 +11,11 @@ export * from './constants/web3';
 export * from './constants/vaults';
 export * from './constants/swap-router';
 export * from './helpers/web3';
+export * from './helpers/multicall';
 export * from './helpers/vaults';
 export * from './helpers/chain-error';
 export * from './helpers/core';
 export * from './helpers/adapters';
 export * from './helpers/signer';
 export * from './helpers/swap-router';
+export * from './helpers/revert-decode';

package/lib/core/index.js

@@ -27,10 +27,12 @@ __exportStar(require("./constants/web3"), exports);
 __exportStar(require("./constants/vaults"), exports);
 __exportStar(require("./constants/swap-router"), exports);
 __exportStar(require("./helpers/web3"), exports);
+__exportStar(require("./helpers/multicall"), exports);
 __exportStar(require("./helpers/vaults"), exports);
 __exportStar(require("./helpers/chain-error"), exports);
 __exportStar(require("./helpers/core"), exports);
 __exportStar(require("./helpers/adapters"), exports);
 __exportStar(require("./helpers/signer"), exports);
 __exportStar(require("./helpers/swap-router"), exports);
+__exportStar(require("./helpers/revert-decode"), exports);
 //# sourceMappingURL=index.js.map

package/lib/main.d.ts

@@ -279,6 +279,52 @@ export declare class AugustSDK extends AugustBase {
         untilTs?: number;
         types?: ('withdraw-request' | 'deposit' | 'withdraw-processed' | 'redeem')[];
     }): Promise<import("./types").IVaultUserHistoryItem[]>;
+    /**
+     * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+     * chain — the any-token set a deposit UI can offer as swap-and-deposit inputs.
+     *
+     * Delegates to {@link AugustVaults.getSwapRouterWhitelistedTokens}, which
+     * reconstructs the set from the router's `TokenEnabled` events and verifies
+     * each against the on-chain `whitelistedTokens` mapping (not enumerable).
+     * Returns `[]` when no router is deployed on `chainId` or no provider is
+     * configured for it.
+     *
+     * @param chainId - EVM chain ID to resolve the allowlist for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed whitelisted token addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);
+     * ```
+     */
+    getSwapRouterWhitelistedTokens(chainId: number, options?: {
+        fromBlock?: number;
+    }): Promise<IAddress[]>;
+    /**
+     * Resolve the vaults currently eligible for the any-token `SwapRouter`
+     * deposit surface on a chain — every vault the router has `enableVault`-ed
+     * whose on-chain registration is still live.
+     *
+     * Delegates to {@link AugustVaults.getSwapRouterEligibleVaults}, which
+     * reconstructs the set from the router's `VaultEnabled` events and verifies
+     * each vault's current `vaultInfo` registration (not enumerable). Returns
+     * `[]` when no router is deployed on `chainId` or no provider is configured
+     * for it. On-chain eligibility only — app-level policy (e.g. OVault
+     * exclusions) remains the caller's responsibility.
+     *
+     * @param chainId - EVM chain ID to resolve eligible vaults for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed eligible vault addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const vaults = await augustSdk.getSwapRouterEligibleVaults(1);
+     * ```
+     */
+    getSwapRouterEligibleVaults(chainId: number, options?: {
+        fromBlock?: number;
+    }): Promise<IAddress[]>;
     /**
      * Get lifetime PnL for a user in a specific vault.
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.

package/lib/main.js

@@ -343,6 +343,52 @@ class AugustSDK extends core_1.AugustBase {
     async getVaultActivity(props) {
         return await this.vaults.getVaultActivity(props);
     }
+    /**
+     * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+     * chain — the any-token set a deposit UI can offer as swap-and-deposit inputs.
+     *
+     * Delegates to {@link AugustVaults.getSwapRouterWhitelistedTokens}, which
+     * reconstructs the set from the router's `TokenEnabled` events and verifies
+     * each against the on-chain `whitelistedTokens` mapping (not enumerable).
+     * Returns `[]` when no router is deployed on `chainId` or no provider is
+     * configured for it.
+     *
+     * @param chainId - EVM chain ID to resolve the allowlist for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed whitelisted token addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);
+     * ```
+     */
+    async getSwapRouterWhitelistedTokens(chainId, options) {
+        return await this.vaults.getSwapRouterWhitelistedTokens(chainId, options);
+    }
+    /**
+     * Resolve the vaults currently eligible for the any-token `SwapRouter`
+     * deposit surface on a chain — every vault the router has `enableVault`-ed
+     * whose on-chain registration is still live.
+     *
+     * Delegates to {@link AugustVaults.getSwapRouterEligibleVaults}, which
+     * reconstructs the set from the router's `VaultEnabled` events and verifies
+     * each vault's current `vaultInfo` registration (not enumerable). Returns
+     * `[]` when no router is deployed on `chainId` or no provider is configured
+     * for it. On-chain eligibility only — app-level policy (e.g. OVault
+     * exclusions) remains the caller's responsibility.
+     *
+     * @param chainId - EVM chain ID to resolve eligible vaults for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed eligible vault addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const vaults = await augustSdk.getSwapRouterEligibleVaults(1);
+     * ```
+     */
+    async getSwapRouterEligibleVaults(chainId, options) {
+        return await this.vaults.getSwapRouterEligibleVaults(chainId, options);
+    }
     /**
      * Get lifetime PnL for a user in a specific vault.
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.

package/lib/modules/vaults/getters.d.ts

@@ -53,12 +53,22 @@ export declare function getVaultSubaccountLoans(vault: VaultAddress | IVault, op
  * @returns Detailed allocation data with exposure categorization
  */
 export declare function getVaultAllocations(vault: IAddress, options: IVaultBaseOptions): Promise<IVaultAllocations>;
-export declare function getVaultAvailableRedemptions({ vault, wallet, options, }: {
+export declare function getVaultAvailableRedemptions({ vault, wallet, options, prefetchedReads, }: {
     vault: IAddress;
     wallet?: IAddress;
     options: IVaultBaseOptions & {
         verbose?: boolean;
     };
+    /**
+     * Values already read via a Multicall3 batch (see
+     * `modules/vaults/prefetch.ts`). When `lagDuration` is present the
+     * per-vault `lagDuration()` RPC is skipped; when omitted, behavior is
+     * exactly the pre-batching per-call path.
+     * @internal
+     */
+    prefetchedReads?: {
+        lagDuration?: number;
+    };
 }): Promise<{
     processedWithdrawals: ISubgraphWithdrawProccessed[];
     requestedWithdrawals: import("../../types").ISubgraphWithdrawRequest[];
@@ -71,15 +81,28 @@ export declare function getVaultRedemptionHistory({ vault, wallet, lookbackBlock
     lookbackBlocks?: number;
     options: IVaultBaseOptions;
 }): Promise<IVaultRedemptionHistoryItem[]>;
+export { getSwapRouterDepositResult } from '../../core/helpers/swap-router';
 /**
  * Vault Positions
  */
-export declare function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, }: {
+export declare function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, prefetchedReads, }: {
     vault: IAddress;
     wallet?: IAddress;
     solanaWallet?: string;
     stellarWallet?: string;
     options: IVaultBaseOptions;
+    /**
+     * Per-vault values already read via a Multicall3 batch at the fan-out call
+     * sites (see `modules/vaults/prefetch.ts`). Supplied fields skip the
+     * corresponding `balanceOf` / `lagDuration` RPC for the vault matching the
+     * `vault` parameter; when omitted, behavior is exactly the pre-batching
+     * per-call path.
+     * @internal
+     */
+    prefetchedReads?: {
+        balance?: bigint;
+        lagDuration?: number;
+    };
 }): Promise<IVaultPosition[]>;
 /**
  * @deprecated use getVaultHistoricalTimeseries instead

package/lib/modules/vaults/getters.js

@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSwapRouterDepositResult = void 0;
 exports.getVault = getVault;
 exports.getVaultLoans = getVaultLoans;
 exports.getVaultSubaccountLoans = getVaultSubaccountLoans;
@@ -548,7 +549,7 @@ async function getVaultAllocations(vault, options) {
         unfilteredTokens: unfilteredTokens,
     };
 }
-async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
+async function getVaultAvailableRedemptions({ vault, wallet, options, prefetchedReads, }) {
     try {
         // Stellar vaults don't support on-chain redemptions yet
         if ((0, utils_3.isStellarAddress)(vault)) {
@@ -592,8 +593,9 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
         else {
             decimals = await (0, core_1.getDecimals)(provider, vault);
         }
-        const ld = await vaultContract.lagDuration();
-        const lagDuration = Number(ld);
+        const lagDuration = typeof prefetchedReads?.lagDuration === 'number'
+            ? prefetchedReads.lagDuration
+            : Number(await vaultContract.lagDuration());
         const { withdrawalRequesteds, withdrawalProcesseds } = await (0, subgraph_1.getSubgraphAllWithdrawals)(vault, provider);
         // format
         const availableRedemptions = [];
@@ -991,10 +993,15 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
         throw e;
     }
 }
+// Moved to core/helpers/swap-router.ts to break the adapters/evm ↔
+// modules/vaults/getters import cycle (CLAUDE.md §9); re-exported here for
+// back-compat with existing importers.
+var swap_router_1 = require("../../core/helpers/swap-router");
+Object.defineProperty(exports, "getSwapRouterDepositResult", { enumerable: true, get: function () { return swap_router_1.getSwapRouterDepositResult; } });
 /**
  * Vault Positions
  */
-async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, }) {
+async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, prefetchedReads, }) {
     try {
         const tokenizedVaults = await (0, core_1.fetchTokenizedVault)(vault ? vault : undefined, options?.headers, false, false);
         if (!tokenizedVaults || tokenizedVaults.length === 0) {
@@ -1100,24 +1107,37 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                     abi: abis_1.ABI_LENDING_POOL_V2,
                     address: v.address,
                 });
+                // Batched reads only apply to the vault this call was made for —
+                // guard against a multi-row backend response reusing them.
+                const prefetched = v.address?.toLowerCase?.() === String(vault).toLowerCase()
+                    ? prefetchedReads
+                    : undefined;
                 // get vault metadata and balance based on version
                 let bal = BigInt(0);
                 if (version === 'evm-2') {
                     const receiptAddress = await (0, core_1.getReceiptTokenAddress)(provider, vault);
                     decimals = await (0, core_1.getDecimals)(provider, receiptAddress, false);
                     if (wallet && (0, ethers_1.isAddress)(wallet)) {
-                        const receiptContract = (0, core_1.createContract)({
-                            provider,
-                            abi: TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
-                            address: receiptAddress,
-                        });
-                        bal = await receiptContract.balanceOf(wallet);
+                        if (typeof prefetched?.balance === 'bigint') {
+                            bal = prefetched.balance;
+                        }
+                        else {
+                            const receiptContract = (0, core_1.createContract)({
+                                provider,
+                                abi: TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
+                                address: receiptAddress,
+                            });
+                            bal = await receiptContract.balanceOf(wallet);
+                        }
                     }
                 }
                 else {
                     decimals = await (0, core_1.getDecimals)(provider, vault);
                     if (wallet && (0, ethers_1.isAddress)(wallet)) {
-                        bal = await vaultContract.balanceOf(wallet);
+                        bal =
+                            typeof prefetched?.balance === 'bigint'
+                                ? prefetched.balance
+                                : await vaultContract.balanceOf(wallet);
                     }
                 }
                 const balance = (0, core_1.toNormalizedBn)(bal, decimals);
@@ -1126,6 +1146,7 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                     vault: v.address,
                     wallet,
                     options,
+                    prefetchedReads: prefetched,
                 });
                 // get aggregate redemption amount
                 const aggregateAvailableRedemptions = availableRedemptions.reduce((acc, curr) => acc + BigInt(curr.amount.raw), BigInt(0));
@@ -1859,6 +1880,15 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         if (!tokenizedVault) {
             throw new Error(`Vault ${vault} not found`);
         }
+        // getDecimals resolves to `undefined` on a failed/absent decimals() read.
+        // Unguarded, that undefined flows into `10 ** decimals` (=> NaN) and
+        // toNormalizedBn(x, undefined), and the first BigInt(NaN) throws the opaque
+        // "The number NaN cannot be converted to a BigInt" error. Decimals must come
+        // from the chain — never assume a fallback — so fail fast with actionable
+        // context. Transient RPC blips recover on the caller's retry.
+        if (typeof decimals !== 'number' || !Number.isFinite(decimals)) {
+            throw new Error(`Failed to resolve decimals for vault ${vault}`);
+        }
         // Fetch LayerZero deposits/redeems for supported vaults
         const lzVaultKey = (0, deposits_1.isLayerZeroVault)(vault);
         let lzDeposits = [];

package/lib/modules/vaults/main.d.ts

@@ -50,6 +50,17 @@ export declare class AugustVaults extends AugustBase {
      * Includes closed vaults that are still visible (`status: 'closed'`,
      * `is_visible: true`) so consumers can render positions held in closed
      * vaults; closed vaults with `is_visible: false` are excluded.
+     *
+     * RPC volume (worst case, wallet enrichment path): the per-vault
+     * `balanceOf`/`lagDuration` reads are aggregated into chunked Multicall3
+     * `aggregate3` batches per chain (10 calls per chunk) on chains where the
+     * canonical Multicall3 deployment is verified; other chains (e.g. Citrea
+     * 4114) keep one `eth_call` per read. Measured with
+     * `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
+     * 54 after (~35% fewer; 124 per-vault `eth_call`s collapse into ~13
+     * `aggregate3` calls — the remaining requests are the per-vault cached
+     * decimals/receipt-token reads on a cold cache).
      * @param options Filtering and enrichment configuration
      * @returns Array of vault objects with optional loans/allocations/positions
      */
@@ -202,7 +213,18 @@ export declare class AugustVaults extends AugustBase {
         lookbackBlocks?: number;
     }): Promise<import("../../types").IVaultRedemptionHistoryItem[]>;
     /**
+     * Fetch the wallet's positions across vaults — a single vault, one chain,
+     * or every chain with a configured provider.
      *
+     * RPC volume (worst case, multi-vault paths): the two non-cacheable
+     * per-vault reads (`balanceOf`, `lagDuration`) are aggregated into chunked
+     * Multicall3 `aggregate3` batches per chain (10 calls per chunk) on chains
+     * where the canonical deployment is verified; unverified chains (e.g.
+     * Citrea 4114) and non-EVM vaults keep one `eth_call` per read. Measured
+     * with `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
+     * 54 after (~35% fewer). A vault whose batched read fails (e.g. paused)
+     * falls back to its own per-vault reads — never to a zeroed balance.
      */
     getVaultPositions({ vault, wallet, chainId, showAllVaults, solanaWallet, stellarWallet, options, }: {
         vault?: IAddress;
@@ -306,6 +328,59 @@ export declare class AugustVaults extends AugustBase {
         untilTs?: number;
         types?: IVaultUserHistoryItem['type'][];
     }): Promise<IVaultUserHistoryItem[]>;
+    /**
+     * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+     * chain — the any-token set a deposit UI can offer as swap-and-deposit inputs,
+     * each verified `true` against the router's on-chain allowlist.
+     *
+     * Reconstructs the set from the router's `TokenEnabled` event history and
+     * re-checks `whitelistedTokens(token)` for each (the mapping is not
+     * enumerable). See {@link getSwapRouterWhitelistedTokens} for the full
+     * two-stage behavior and RPC cost. Uses this instance's configured provider
+     * for `chainId`; returns `[]` (no RPC) when no router is deployed there or no
+     * provider is configured.
+     *
+     * @param chainId - EVM chain ID to resolve the allowlist for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed whitelisted token addresses; `[]` when unavailable.
+     *   Callers still exclude a target vault's natively-accepted assets (those
+     *   deposit without a swap).
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);
+     * ```
+     */
+    getSwapRouterWhitelistedTokens(chainId: number, options?: {
+        fromBlock?: number;
+    }): Promise<IAddress[]>;
+    /**
+     * Resolve the vaults currently eligible for the any-token `SwapRouter`
+     * deposit surface on a chain — every vault the router has `enableVault`-ed
+     * whose on-chain registration is still live.
+     *
+     * Reconstructs the set from the router's `VaultEnabled` event history and
+     * re-checks `vaultInfo(vault).referenceAsset != 0` for each (the mapping is
+     * not enumerable). See {@link getSwapRouterEligibleVaults} for the full
+     * two-stage behavior and RPC cost. Uses this instance's configured provider
+     * for `chainId`; returns `[]` (no RPC) when no router is deployed there or no
+     * provider is configured.
+     *
+     * On-chain eligibility only — app-level policy (e.g. excluding vaults with
+     * their own OVault deposit flow) remains the caller's responsibility.
+     *
+     * @param chainId - EVM chain ID to resolve eligible vaults for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed eligible vault addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const vaults = await augustSdk.getSwapRouterEligibleVaults(1);
+     * ```
+     */
+    getSwapRouterEligibleVaults(chainId: number, options?: {
+        fromBlock?: number;
+    }): Promise<IAddress[]>;
     /**
      * @function getStakingPositions gets all available reward staking positions
      * @param wallet optionally passed user wallet address

package/lib/modules/vaults/main.js

@@ -66,6 +66,7 @@ const constants_1 = require("../../adapters/sui/constants");
 const vaults_2 = require("../../core/constants/vaults");
 const write_actions_1 = require("./write.actions");
 const read_actions_1 = require("./read.actions");
+const prefetch_1 = require("./prefetch");
 /**
  * Vault operations class handling multi-chain vault queries and user positions.
  * Supports both EVM and Solana vaults with unified interface.
@@ -120,6 +121,17 @@ class AugustVaults extends core_1.AugustBase {
      * Includes closed vaults that are still visible (`status: 'closed'`,
      * `is_visible: true`) so consumers can render positions held in closed
      * vaults; closed vaults with `is_visible: false` are excluded.
+     *
+     * RPC volume (worst case, wallet enrichment path): the per-vault
+     * `balanceOf`/`lagDuration` reads are aggregated into chunked Multicall3
+     * `aggregate3` batches per chain (10 calls per chunk) on chains where the
+     * canonical Multicall3 deployment is verified; other chains (e.g. Citrea
+     * 4114) keep one `eth_call` per read. Measured with
+     * `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
+     * 54 after (~35% fewer; 124 per-vault `eth_call`s collapse into ~13
+     * `aggregate3` calls — the remaining requests are the per-vault cached
+     * decimals/receipt-token reads on a cold cache).
      * @param options Filtering and enrichment configuration
      * @returns Array of vault objects with optional loans/allocations/positions
      */
@@ -248,6 +260,14 @@ class AugustVaults extends core_1.AugustBase {
         if ((options.wallet && (0, ethers_1.isAddress)(options.wallet)) ||
             (options.solanaWallet &&
                 utils_1.SolanaUtils.isSolanaAddress(options.solanaWallet))) {
+            // Batch the per-vault balanceOf/lagDuration reads (Multicall3, grouped
+            // by chain) before fanning out — vaults the batch couldn't serve fall
+            // back to their own reads inside getVaultPositions.
+            const prefetchedReads = await (0, prefetch_1.prefetchVaultPositionReads)({
+                vaults: vaultsPerAvailableProviders,
+                wallet: options.wallet,
+                providers: this.providers,
+            });
             // fetch all positions for user wallet
             const vaultResponses = await (0, core_1.promiseSettle)(vaultsPerAvailableProviders.map((v) => (0, getters_1.getVaultPositions)({
                 vault: v.address,
@@ -262,6 +282,7 @@ class AugustVaults extends core_1.AugustBase {
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
                 },
+                prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
             })), 5, // 5 retries
             2000);
             // return vault object with position property
@@ -609,7 +630,18 @@ class AugustVaults extends core_1.AugustBase {
         });
     }
     /**
+     * Fetch the wallet's positions across vaults — a single vault, one chain,
+     * or every chain with a configured provider.
      *
+     * RPC volume (worst case, multi-vault paths): the two non-cacheable
+     * per-vault reads (`balanceOf`, `lagDuration`) are aggregated into chunked
+     * Multicall3 `aggregate3` batches per chain (10 calls per chunk) on chains
+     * where the canonical deployment is verified; unverified chains (e.g.
+     * Citrea 4114) and non-EVM vaults keep one `eth_call` per read. Measured
+     * with `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
+     * 54 after (~35% fewer). A vault whose batched read fails (e.g. paused)
+     * falls back to its own per-vault reads — never to a zeroed balance.
      */
     async getVaultPositions({ vault, wallet, chainId, showAllVaults, solanaWallet, stellarWallet, options, }) {
         // if (!this.authorized) throw new Error('Not authorized.');
@@ -646,6 +678,13 @@ class AugustVaults extends core_1.AugustBase {
         const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, false, false);
         if (chainId) {
             const vaultsPerChain = allVaults.filter((v) => v.chain === chainId);
+            // Batch balanceOf/lagDuration via Multicall3 before the per-vault
+            // fan-out; un-batched vaults fall back to their own reads.
+            const prefetchedReads = await (0, prefetch_1.prefetchVaultPositionReads)({
+                vaults: vaultsPerChain,
+                wallet,
+                providers: this.providers,
+            });
             const vaultResponses = await Promise.all(vaultsPerChain.map((v) => (0, getters_1.getVaultPositions)({
                 vault: v.address,
                 solanaWallet,
@@ -660,6 +699,7 @@ class AugustVaults extends core_1.AugustBase {
                     subgraphKey: this.keys?.graph,
                     headers: this.headers,
                 },
+                prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
             })));
             const flattened = vaultResponses.flat();
             let final;
@@ -682,6 +722,13 @@ class AugustVaults extends core_1.AugustBase {
             // outer catch, and silently return PENDING (then get filtered out).
             (v?.chain_type === 'solana' && !!this.solanaService) ||
             (this.providers?.[v?.chain] ? true : false));
+        // Batch balanceOf/lagDuration via Multicall3, grouped by chain, before
+        // the per-vault fan-out; un-batched vaults fall back to their own reads.
+        const prefetchedReads = await (0, prefetch_1.prefetchVaultPositionReads)({
+            vaults: vaultsPerAvailableProviders,
+            wallet,
+            providers: this.providers,
+        });
         const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map((v) => (0, getters_1.getVaultPositions)({
             vault: v.address,
             solanaWallet,
@@ -696,6 +743,7 @@ class AugustVaults extends core_1.AugustBase {
                 subgraphKey: this.keys?.graph,
                 headers: this.headers,
             },
+            prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
         })));
         const flattened = vaultResponses.flat();
         let final;
@@ -734,6 +782,12 @@ class AugustVaults extends core_1.AugustBase {
                 // deposited token address; propagate it so consumers render the right
                 // asset symbol instead of guessing the vault's first deposit asset.
                 assetIn: h.assetIn,
+                // withdraw-request rows carry the burned share amount. Normalize with
+                // the vault decimals (the share token's own decimals) so UIs can show
+                // the receipt-token quantity that was actually burned.
+                shares: h.shares
+                    ? (0, core_1.toNormalizedBn)(BigInt(h.shares), h.decimals)
+                    : undefined,
             }));
         }
         // Helper function to fetch history for a vault
@@ -1016,6 +1070,79 @@ class AugustVaults extends core_1.AugustBase {
             return true;
         });
     }
+    /**
+     * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+     * chain — the any-token set a deposit UI can offer as swap-and-deposit inputs,
+     * each verified `true` against the router's on-chain allowlist.
+     *
+     * Reconstructs the set from the router's `TokenEnabled` event history and
+     * re-checks `whitelistedTokens(token)` for each (the mapping is not
+     * enumerable). See {@link getSwapRouterWhitelistedTokens} for the full
+     * two-stage behavior and RPC cost. Uses this instance's configured provider
+     * for `chainId`; returns `[]` (no RPC) when no router is deployed there or no
+     * provider is configured.
+     *
+     * @param chainId - EVM chain ID to resolve the allowlist for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed whitelisted token addresses; `[]` when unavailable.
+     *   Callers still exclude a target vault's natively-accepted assets (those
+     *   deposit without a swap).
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);
+     * ```
+     */
+    async getSwapRouterWhitelistedTokens(chainId, options) {
+        if (!(0, core_1.getSwapRouterAddress)(chainId))
+            return [];
+        const rpcUrl = this.providers?.[chainId];
+        if (!rpcUrl) {
+            core_1.Logger.log.warn('getSwapRouterWhitelistedTokens', `no provider configured for chain ${chainId}`);
+            return [];
+        }
+        return (0, core_1.getSwapRouterWhitelistedTokens)(chainId, {
+            rpcUrl,
+            fromBlock: options?.fromBlock,
+        });
+    }
+    /**
+     * Resolve the vaults currently eligible for the any-token `SwapRouter`
+     * deposit surface on a chain — every vault the router has `enableVault`-ed
+     * whose on-chain registration is still live.
+     *
+     * Reconstructs the set from the router's `VaultEnabled` event history and
+     * re-checks `vaultInfo(vault).referenceAsset != 0` for each (the mapping is
+     * not enumerable). See {@link getSwapRouterEligibleVaults} for the full
+     * two-stage behavior and RPC cost. Uses this instance's configured provider
+     * for `chainId`; returns `[]` (no RPC) when no router is deployed there or no
+     * provider is configured.
+     *
+     * On-chain eligibility only — app-level policy (e.g. excluding vaults with
+     * their own OVault deposit flow) remains the caller's responsibility.
+     *
+     * @param chainId - EVM chain ID to resolve eligible vaults for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed eligible vault addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const vaults = await augustSdk.getSwapRouterEligibleVaults(1);
+     * ```
+     */
+    async getSwapRouterEligibleVaults(chainId, options) {
+        if (!(0, core_1.getSwapRouterAddress)(chainId))
+            return [];
+        const rpcUrl = this.providers?.[chainId];
+        if (!rpcUrl) {
+            core_1.Logger.log.warn('getSwapRouterEligibleVaults', `no provider configured for chain ${chainId}`);
+            return [];
+        }
+        return (0, core_1.getSwapRouterEligibleVaults)(chainId, {
+            rpcUrl,
+            fromBlock: options?.fromBlock,
+        });
+    }
     /**
      * @function getStakingPositions gets all available reward staking positions
      * @param wallet optionally passed user wallet address