@augustdigital/sdk 8.10.0 → 8.12.0

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) {
@@ -1058,7 +1065,11 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                     let balance = (0, core_1.toNormalizedBn)(0);
                     if (stellarWallet && (0, utils_3.isStellarAddress)(stellarWallet)) {
                         const stellarNetwork = v.stellar_vault_metadata?.network_name ?? 'mainnet';
-                        const position = await StellarGetters.getStellarUserPosition(v.address, stellarWallet, stellarNetwork);
+                        // Only use the configured RPC override for its own network.
+                        const stellarOverrideRpcUrl = options.stellarRpc?.network === stellarNetwork
+                            ? options.stellarRpc.rpcUrl
+                            : undefined;
+                        const position = await StellarGetters.getStellarUserPosition(v.address, stellarWallet, stellarNetwork, stellarOverrideRpcUrl);
                         if (position && !position.decimalsFromFallback) {
                             balance = (0, core_1.toNormalizedBn)(BigInt(position.shares), position.decimals);
                         }
@@ -1096,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);
@@ -1122,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));
@@ -1855,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

@@ -23,6 +23,12 @@ export declare class AugustVaults extends AugustBase {
     private solanaService;
     private suiService;
     private headers;
+    /**
+     * Consumer-supplied Soroban RPC override for Stellar vault reads, with the
+     * network it was configured for so it's only applied to matching-network
+     * vaults (see `IVaultBaseOptions.stellarRpc`).
+     */
+    private _stellarRpc?;
     constructor(baseConfig: IAugustBase, solana: SolanaAdapter, sui: SuiAdapter);
     /**
      * @description deposit underlying token into the specified pool with adapter support. This is for when we cannot pass in a signer in sdk and need to do so as an arg
@@ -44,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
      */
@@ -196,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;

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.
@@ -74,10 +75,23 @@ class AugustVaults extends core_1.AugustBase {
     solanaService;
     suiService;
     headers = null;
+    /**
+     * Consumer-supplied Soroban RPC override for Stellar vault reads, with the
+     * network it was configured for so it's only applied to matching-network
+     * vaults (see `IVaultBaseOptions.stellarRpc`).
+     */
+    _stellarRpc;
     constructor(baseConfig, solana, sui) {
         super(baseConfig);
         this.solanaService = solana;
         this.suiService = sui || new sui_1.default();
+        // Network defaults to mainnet, matching the StellarAdapter constructor.
+        this._stellarRpc = baseConfig.stellar?.rpcUrl
+            ? {
+                rpcUrl: baseConfig.stellar.rpcUrl,
+                network: baseConfig.stellar.network ?? 'mainnet',
+            }
+            : undefined;
         this.headers = {
             'x-environment': this.monitoring?.['x-environment'],
             'x-user-id': this.monitoring?.['x-user-id'],
@@ -107,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
      */
@@ -166,6 +191,7 @@ class AugustVaults extends core_1.AugustBase {
                 options: {
                     rpcUrl,
                     solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
                     env: this.monitoring?.env,
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
@@ -234,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,
@@ -243,10 +277,12 @@ class AugustVaults extends core_1.AugustBase {
                 options: {
                     rpcUrl: this.providers?.[v.chain],
                     solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
                     env: this.monitoring?.env,
                     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
@@ -316,6 +352,7 @@ class AugustVaults extends core_1.AugustBase {
                     ? this.providers?.[chainId]
                     : this.activeNetwork?.rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -340,6 +377,7 @@ class AugustVaults extends core_1.AugustBase {
                         ? this.providers?.[chainId]
                         : this.activeNetwork?.rpcUrl,
                     solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
                     env: this.monitoring?.env,
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
@@ -385,6 +423,7 @@ class AugustVaults extends core_1.AugustBase {
             subgraphKey: this.keys?.graph,
             chainId: chainId,
             solanaService: this.solanaService,
+            stellarRpc: this._stellarRpc,
             headers: this.headers,
         });
         return vaultResponse;
@@ -416,6 +455,7 @@ class AugustVaults extends core_1.AugustBase {
             subgraphKey: this.keys?.graph,
             chainId: chainId,
             solanaService: this.solanaService,
+            stellarRpc: this._stellarRpc,
             headers: this.headers,
         });
         return vaultResponse;
@@ -447,6 +487,7 @@ class AugustVaults extends core_1.AugustBase {
                     ? this.providers?.[chainId]
                     : this.activeNetwork?.rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -527,6 +568,7 @@ class AugustVaults extends core_1.AugustBase {
                     ? this.providers?.[chainId]
                     : this.activeNetwork?.rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -588,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.');
@@ -611,6 +664,7 @@ class AugustVaults extends core_1.AugustBase {
                         ? this.providers?.[chainId]
                         : this.activeNetwork?.rpcUrl,
                     solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
                     env: this.monitoring?.env,
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
@@ -624,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,
@@ -632,11 +693,13 @@ class AugustVaults extends core_1.AugustBase {
                 options: {
                     rpcUrl: this.providers?.[v.chain],
                     solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
                     env: this.monitoring?.env,
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
                     headers: this.headers,
                 },
+                prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
             })));
             const flattened = vaultResponses.flat();
             let final;
@@ -659,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,
@@ -667,11 +737,13 @@ class AugustVaults extends core_1.AugustBase {
             options: {
                 rpcUrl: this.providers?.[v.chain],
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
                 headers: this.headers,
             },
+            prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
         })));
         const flattened = vaultResponses.flat();
         let final;
@@ -706,6 +778,16 @@ class AugustVaults extends core_1.AugustBase {
                 chainId: _chainId,
                 type: h.type,
                 transactionHash: h.transactionHash_,
+                // Deposit rows on multi-asset (pre-deposit) vaults carry the actual
+                // 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
@@ -826,6 +908,7 @@ class AugustVaults extends core_1.AugustBase {
                     ? this.providers?.[chainId]
                     : this.requireActiveNetwork().rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -851,6 +934,7 @@ class AugustVaults extends core_1.AugustBase {
                     ? this.providers?.[chainId]
                     : this.requireActiveNetwork().rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -1033,6 +1117,7 @@ class AugustVaults extends core_1.AugustBase {
                 rpcUrl: rpcUrl,
                 chainId: resolvedChainId,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -1056,6 +1141,7 @@ class AugustVaults extends core_1.AugustBase {
             options: {
                 rpcUrl: rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -1103,6 +1189,7 @@ class AugustVaults extends core_1.AugustBase {
                         ? this.providers?.[chainId]
                         : rpcUrl || this.requireActiveNetwork().rpcUrl,
                     solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
                     env: this.monitoring?.env,
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
@@ -1376,6 +1463,7 @@ class AugustVaults extends core_1.AugustBase {
             options: {
                 rpcUrl: chainId ? this.providers?.[chainId] : this.activeNetwork.rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
@@ -1428,6 +1516,7 @@ class AugustVaults extends core_1.AugustBase {
             options: {
                 rpcUrl,
                 solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
                 env: this.monitoring?.env,
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,

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

@@ -0,0 +1,65 @@
+import type { IAddress, ITokenizedVault } from '../../types';
+/**
+ * Per-vault on-chain reads resolved ahead of the positions fan-out, so
+ * `getVaultPositions` / `getVaultAvailableRedemptions` can skip their own
+ * `balanceOf` / `lagDuration` RPCs. A missing field means the read was not
+ * (or could not be) prefetched — the getter falls back to its own call.
+ * @internal
+ */
+export interface IPrefetchedVaultReads {
+    /** Raw share/receipt-token balance of the wallet (`balanceOf`). */
+    balance?: bigint;
+    /** Vault redemption lag in seconds (`lagDuration`). */
+    lagDuration?: number;
+}
+/**
+ * Minimal shape of a backend tokenized-vault row the prefetch needs. The
+ * full backend response type is looser than this; only these fields are read.
+ * @internal
+ */
+interface IPrefetchableVault {
+    address: string;
+    chain: number;
+    chain_type?: string;
+    /**
+     * Backend vault kind. `getVaultVersionV2` reads this to classify evm-2
+     * (`multiAssetVault`) vaults whose address isn't in the hardcoded
+     * `MULTI_ASSET_VAULTS` list; without it such a vault would be misclassified
+     * as evm-1 and the batch would target the vault itself for `balanceOf`
+     * instead of its receipt token.
+     */
+    internal_type?: ITokenizedVault['internal_type'];
+}
+/**
+ * Batch the two non-cacheable per-vault reads (`balanceOf`, `lagDuration`)
+ * for a vault list via Multicall3, grouped by chain, ahead of the per-vault
+ * positions fan-out.
+ *
+ * Scope and fallback rules (task 52):
+ * - Only EVM vaults on chains with a configured provider AND a verified
+ *   Multicall3 deployment are batched. Solana/Stellar vaults, unverified
+ *   chains (e.g. Citrea 4114), and provider-less chains are skipped — they
+ *   keep today's exact per-vault read path.
+ * - `balanceOf` targets the receipt token for evm-2 vaults (resolved through
+ *   the same cached `getReceiptTokenAddress` the getters use) and the vault
+ *   itself for evm-1. Without an EVM wallet only `lagDuration` is batched.
+ * - Failures never propagate: a reverting vault call is simply absent from
+ *   the result map, and a whole-chain error drops that chain's entries. The
+ *   worst case is always "no prefetch → per-vault fallback", never wrong data.
+ *
+ * RPC cost: per batched chain, `ceil(reads / 10)` `eth_call`s (+1 cold
+ * `lpTokenAddress` per evm-2 vault) instead of ~2 `eth_call`s per vault.
+ *
+ * @param vaults Backend tokenized-vault rows about to be fanned out over.
+ * @param wallet Optional EVM wallet for `balanceOf` reads.
+ * @param providers Chain-id → RPC-url map (the module's `this.providers`).
+ * @returns Map keyed by lowercased vault address; vaults with no batched
+ *   reads have no entry.
+ * @internal
+ */
+export declare function prefetchVaultPositionReads({ vaults, wallet, providers, }: {
+    vaults: IPrefetchableVault[];
+    wallet?: IAddress;
+    providers?: Partial<Record<number, string>>;
+}): Promise<Map<string, IPrefetchedVaultReads>>;
+export {};

package/lib/modules/vaults/prefetch.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prefetchVaultPositionReads = prefetchVaultPositionReads;
+const ethers_1 = require("ethers");
+const abis_1 = require("../../abis");
+const TokenizedVaultV2Receipt_1 = require("../../abis/TokenizedVaultV2Receipt");
+const core_1 = require("../../core");
+/**
+ * Batch the two non-cacheable per-vault reads (`balanceOf`, `lagDuration`)
+ * for a vault list via Multicall3, grouped by chain, ahead of the per-vault
+ * positions fan-out.
+ *
+ * Scope and fallback rules (task 52):
+ * - Only EVM vaults on chains with a configured provider AND a verified
+ *   Multicall3 deployment are batched. Solana/Stellar vaults, unverified
+ *   chains (e.g. Citrea 4114), and provider-less chains are skipped — they
+ *   keep today's exact per-vault read path.
+ * - `balanceOf` targets the receipt token for evm-2 vaults (resolved through
+ *   the same cached `getReceiptTokenAddress` the getters use) and the vault
+ *   itself for evm-1. Without an EVM wallet only `lagDuration` is batched.
+ * - Failures never propagate: a reverting vault call is simply absent from
+ *   the result map, and a whole-chain error drops that chain's entries. The
+ *   worst case is always "no prefetch → per-vault fallback", never wrong data.
+ *
+ * RPC cost: per batched chain, `ceil(reads / 10)` `eth_call`s (+1 cold
+ * `lpTokenAddress` per evm-2 vault) instead of ~2 `eth_call`s per vault.
+ *
+ * @param vaults Backend tokenized-vault rows about to be fanned out over.
+ * @param wallet Optional EVM wallet for `balanceOf` reads.
+ * @param providers Chain-id → RPC-url map (the module's `this.providers`).
+ * @returns Map keyed by lowercased vault address; vaults with no batched
+ *   reads have no entry.
+ * @internal
+ */
+async function prefetchVaultPositionReads({ vaults, wallet, providers, }) {
+    const reads = new Map();
+    const hasWallet = !!(wallet && (0, ethers_1.isAddress)(wallet));
+    const byChain = new Map();
+    for (const v of vaults) {
+        if (!v?.address || !(0, ethers_1.isAddress)(v.address))
+            continue;
+        if (!(0, core_1.isMulticall3Supported)(v.chain))
+            continue;
+        if (!providers?.[v.chain])
+            continue;
+        const group = byChain.get(v.chain) ?? [];
+        group.push(v);
+        byChain.set(v.chain, group);
+    }
+    await Promise.all(Array.from(byChain.entries()).map(async ([chain, chainVaults]) => {
+        try {
+            // Same cache key as the getters (`createProvider(rpcUrl)` without a
+            // chainId) so the receipt-token/decimals caches stay shared.
+            const provider = (0, core_1.createProvider)(providers[chain]);
+            // Resolve each vault's `balanceOf` target — the receipt token for
+            // evm-2 vaults (one `lpTokenAddress` read each on a cold cache),
+            // the vault itself otherwise. Bound the fan-out to
+            // `MULTICALL3_BATCH_SIZE` concurrent reads (CLAUDE.md §4.1): a wallet
+            // with many uncached evm-2 vaults on one chain would otherwise burst
+            // N simultaneous reads before the aggregate3 batch even fires.
+            const balanceTargets = [];
+            for (let i = 0; i < chainVaults.length; i += core_1.MULTICALL3_BATCH_SIZE) {
+                const slice = chainVaults.slice(i, i + core_1.MULTICALL3_BATCH_SIZE);
+                const resolved = await Promise.all(slice.map(async (v) => {
+                    if (!hasWallet)
+                        return undefined;
+                    if ((0, core_1.getVaultVersionV2)(v) === 'evm-2') {
+                        // Cached + in-flight-deduped; a cold miss costs the same
+                        // `lpTokenAddress` read the getter itself would make.
+                        return (0, core_1.getReceiptTokenAddress)(provider, v.address);
+                    }
+                    return v.address;
+                }));
+                balanceTargets.push(...resolved);
+            }
+            const calls = [];
+            const slots = [];
+            chainVaults.forEach((v, i) => {
+                calls.push({
+                    target: v.address,
+                    abi: abis_1.ABI_LENDING_POOL_V2,
+                    functionName: 'lagDuration',
+                });
+                slots.push({ address: v.address, field: 'lagDuration' });
+                const target = balanceTargets[i];
+                if (hasWallet && target && (0, ethers_1.isAddress)(target)) {
+                    calls.push({
+                        target: target,
+                        abi: target === v.address
+                            ? abis_1.ABI_LENDING_POOL_V2
+                            : TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
+                        functionName: 'balanceOf',
+                        args: [wallet],
+                    });
+                    slots.push({ address: v.address, field: 'balance' });
+                }
+            });
+            const results = await (0, core_1.multicall3Aggregate)(provider, chain, calls);
+            results.forEach((r, i) => {
+                if (!r.success)
+                    return;
+                const slot = slots[i];
+                const key = slot.address.toLowerCase();
+                const entry = reads.get(key) ?? {};
+                if (slot.field === 'lagDuration') {
+                    entry.lagDuration = Number(r.value);
+                }
+                else {
+                    entry.balance = BigInt(r.value);
+                }
+                reads.set(key, entry);
+            });
+        }
+        catch (e) {
+            core_1.Logger.log.warn('prefetchVaultPositionReads', `chain ${chain} prefetch failed — falling back to per-vault reads`, e);
+        }
+    }));
+    return reads;
+}
+//# sourceMappingURL=prefetch.js.map

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

@@ -1,5 +1,5 @@
 import type { Connection } from '@solana/web3.js';
-import type { IAddress, IEnv, IWSMonitorHeaders } from '../../types';
+import type { IAddress, IEnv, IStellarNetwork, IWSMonitorHeaders } from '../../types';
 /**
  * Structural interface for the Solana adapter surface used by vault operations.
  * Avoids importing the concrete SolanaAdapter class to prevent circular dependencies.
@@ -40,6 +40,16 @@ export interface IVaultBaseOptions {
     subgraphKey?: string;
     chainId?: number;
     solanaService?: ISolanaService;
+    /**
+     * Optional Soroban RPC override (e.g. a keyed Alchemy URL) for Stellar vault
+     * reads, threaded from the SDK's `stellar` config. Carries the network it was
+     * configured for so it is only applied to matching-network vaults — a testnet
+     * override must not be used for a mainnet read. Unset → built-in endpoints.
+     */
+    stellarRpc?: {
+        rpcUrl: string;
+        network: IStellarNetwork;
+    };
     headers?: IWSMonitorHeaders;
     /**
      * Portfolio mode: when true, the per-vault EVM getter does NOT null out a