@augustdigital/sdk 8.11.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) {
@@ -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;

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

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