@augustdigital/sdk 8.25.0 → 8.26.0

package/lib/adapters/sui/getters.d.ts

@@ -1,6 +1,12 @@
 import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
 /**
- * Fetch Ember vaults from API
+ * Fetch Ember vaults from API.
+ *
+ * Results are cached for {@link EMBER_CACHE_TTL_MS} (keyed by the full request
+ * URL, so different query options cache independently) and the request is
+ * aborted after {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts —
+ * are never cached and resolve to `[]`, preserving the long-standing
+ * fail-tolerant contract of this getter.
  */
 export declare function getEmberVaults(options?: IFetchEmberVaultsOptions): Promise<IEmberVault[]>;
 /**

package/lib/adapters/sui/getters.js

@@ -4,9 +4,32 @@ exports.getEmberVaults = getEmberVaults;
 exports.getEmberTVL = getEmberTVL;
 const constants_1 = require("./constants");
 const core_1 = require("../../core");
+const cache_1 = require("../../core/cache");
 const logger_1 = require("../../core/logger");
 /**
- * Fetch Ember vaults from API
+ * Hard ceiling on the Ember (Bluefin) vaults request. The endpoint is a
+ * third-party API awaited on the `getVaults` hot path; without a bound, a
+ * hung connection stalls every vault-list consumer indefinitely (the fetch
+ * options carry no signal and no timeout). Measured latency is 0.24–1.02s,
+ * so 5s is ~5× the observed worst case while still failing fast enough for
+ * callers racing `getVaults` against their own budgets.
+ */
+const EMBER_FETCH_TIMEOUT_MS = 5_000;
+/**
+ * TTL for the cached Ember vaults payload. The set of active Ember vaults
+ * changes rarely (the SDK additionally filters it to a hardcoded allowlist),
+ * so 5 minutes matches the freshness of the other list-shaped caches without
+ * letting a stale payload outlive a delisting for long.
+ */
+const EMBER_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Fetch Ember vaults from API.
+ *
+ * Results are cached for {@link EMBER_CACHE_TTL_MS} (keyed by the full request
+ * URL, so different query options cache independently) and the request is
+ * aborted after {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts —
+ * are never cached and resolve to `[]`, preserving the long-standing
+ * fail-tolerant contract of this getter.
  */
 async function getEmberVaults(options) {
     try {
@@ -19,12 +42,36 @@ async function getEmberVaults(options) {
             params.append('status', options.status);
         const queryString = params.toString();
         const url = `${constants_1.EMBER_API_BASE_URL}${queryString ? `?${queryString}` : ''}`;
-        const response = await fetch(url, core_1.DEFAULT_FETCH_OPTIONS);
-        if (!response.ok) {
-            throw new Error(`HTTP error! status: ${response.status}`);
+        const cacheKey = `ember-vaults-${url}`;
+        // The shared LRU is constructed with `allowStale: true`; opt out here so a
+        // payload past its TTL is refetched rather than served one last time —
+        // keeping the 5-minute bound above an exact contract.
+        const cached = cache_1.CACHE.get(cacheKey, { allowStale: false });
+        if (cached)
+            return cached;
+        // AbortController (not AbortSignal.timeout) for browser + older-Node parity.
+        // The timer stays armed through the body read: `fetch` resolves as soon as
+        // headers arrive, so clearing it there would leave a stalled `json()`
+        // unbounded — the exact hang the ceiling exists to prevent.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), EMBER_FETCH_TIMEOUT_MS);
+        let data;
+        try {
+            const response = await fetch(url, {
+                ...core_1.DEFAULT_FETCH_OPTIONS,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            data = await response.json();
+        }
+        finally {
+            clearTimeout(timer);
         }
-        const data = await response.json();
-        return Array.isArray(data) ? data : [];
+        const vaults = Array.isArray(data) ? data : [];
+        cache_1.CACHE.set(cacheKey, vaults, { ttl: EMBER_CACHE_TTL_MS });
+        return vaults;
     }
     catch (error) {
         logger_1.Logger.log.error('getEmberVaults', error);

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "8.25.0";
+export declare const SDK_VERSION = "8.26.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '8.25.0';
+exports.SDK_VERSION = '8.26.0';
 //# sourceMappingURL=version.js.map

package/lib/main.d.ts

@@ -7,9 +7,9 @@ import SolanaAdapter from './adapters/solana';
 import SuiAdapter from './adapters/sui';
 import StellarAdapter from './adapters/stellar';
 import EVMAdapter from './adapters/evm';
-import type { IAddress, IChainId, IVaultHistoricalParams, IWSMonitorHeaders } from './types';
+import type { IAddress, IChainId, IVaultHistoricalParams } from './types';
 import { AugustBase, type IAugustBase } from './core';
-import { AugustVaults, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
+import { AugustVaults, type IGetVaultsOptions, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
 import type { Signer, Wallet } from 'ethers';
 import type { IContractWriteOptions } from './modules/vaults/write.actions';
 import { AugustSubAccounts } from './modules/sub-accounts';
@@ -77,15 +77,12 @@ export declare class AugustSDK extends AugustBase {
     /**
      * Fetch all available vaults across configured networks.
      * Optionally filter by chain IDs and include loan/allocation data.
-     * @param options - Configuration for filtering and enriching vault data
+     * @param options - Configuration for filtering and enriching vault data —
+     * see {@link IGetVaultsOptions} for the full surface (`includeClosed`
+     * portfolio mode, `maxRetries`/`baseDelay` retry tuning)
      * @returns Array of vault objects with metadata and optional position data
      */
-    getVaults(options?: {
-        chainIds?: number[];
-        headers?: IWSMonitorHeaders;
-        loadSubaccounts?: boolean;
-        loadSnapshots?: boolean;
-    } & IVaultCustomOptions): Promise<import("./types").IVault[]>;
+    getVaults(options?: IGetVaultsOptions): Promise<import("./types").IVault[]>;
     getTotalDeposited(options?: {
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;

package/lib/main.js

@@ -207,7 +207,9 @@ class AugustSDK extends core_1.AugustBase {
     /**
      * Fetch all available vaults across configured networks.
      * Optionally filter by chain IDs and include loan/allocation data.
-     * @param options - Configuration for filtering and enriching vault data
+     * @param options - Configuration for filtering and enriching vault data —
+     * see {@link IGetVaultsOptions} for the full surface (`includeClosed`
+     * portfolio mode, `maxRetries`/`baseDelay` retry tuning)
      * @returns Array of vault objects with metadata and optional position data
      */
     async getVaults(options) {

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

@@ -1,4 +1,4 @@
-import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
+import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ITokenizedVault, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
 import type { IVaultBaseOptions } from './types';
 /**
  * Vault Data Getters
@@ -23,15 +23,22 @@ import type { IVaultBaseOptions } from './types';
  * @param loans - Include active loan data
  * @param allocations - Include DeFi/CeFi allocation breakdowns
  * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
  * @returns Complete vault object with optional enrichments
  */
-export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, }: {
+export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }: {
     vault: IAddress;
     loans?: boolean;
     allocations?: boolean;
     options: IVaultBaseOptions;
     loadSubaccounts?: boolean;
     loadSnapshots?: boolean;
+    tokenizedVault?: ITokenizedVault;
 }): Promise<IVault>;
 /**
  * Vault Loans

package/lib/modules/vaults/getters.js

@@ -112,13 +112,19 @@ const errors_1 = require("../../core/errors");
  * @param loans - Include active loan data
  * @param allocations - Include DeFi/CeFi allocation breakdowns
  * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
  * @returns Complete vault object with optional enrichments
  */
-async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, }) {
+async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }) {
     let returnedVault;
     try {
-        const tokenizedVaultRaw = await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots);
-        const tokenizedVault = tokenizedVaultRaw?.[0];
+        const tokenizedVault = prefetchedRow ??
+            (await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots))?.[0];
         const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
         switch (vaultVersion) {
             case 'sol-0': {

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

@@ -13,8 +13,8 @@ import { AugustBase, type IAugustBase } from '../../core';
 import SuiAdapter from '../../adapters/sui';
 import { type IContractWriteOptions, type INativeDepositOptions } from './write.actions';
 import type { Signer, Wallet } from 'ethers';
-import type { IVaultBaseOptions, IVaultCustomOptions } from './types';
-export type { IVaultBaseOptions, IVaultCustomOptions } from './types';
+import type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions } from './types';
+export type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions, } from './types';
 /**
  * Vault operations class handling multi-chain vault queries and user positions.
  * Supports both EVM and Solana vaults with unified interface.
@@ -64,32 +64,7 @@ export declare class AugustVaults extends AugustBase {
      * @param options Filtering and enrichment configuration
      * @returns Array of vault objects with optional loans/allocations/positions
      */
-    getVaults(options?: {
-        chainIds?: number[];
-        loadSubaccounts?: boolean;
-        loadSnapshots?: boolean;
-        /**
-         * Portfolio mode: include closed vaults in the result.
-         *
-         * By default (`false`) closed vaults are excluded, so marketplace /
-         * discovery callers never receive a `status: 'closed'` vault. When set,
-         * closed vaults are returned regardless of `is_visible` (closed +
-         * invisible vaults bucket as closed), so a consumer joining user
-         * positions can render a position held in a closed vault on the
-         * portfolio page.
-         *
-         * In this mode, loans/allocations enrichment is also skipped for closed
-         * vaults: they have none, and the per-vault enrichment
-         * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
-         * vault has no live strategy/debank data or no subaccounts, which would
-         * land the vault in the `failed` bucket and silently drop it before it
-         * reaches the filter. Skipping enrichment lets the vault survive on its
-         * backend metadata + base on-chain read.
-         *
-         * @default false
-         */
-        includeClosed?: boolean;
-    } & IVaultCustomOptions): Promise<import("../../types").IVault[]>;
+    getVaults(options?: IGetVaultsOptions): Promise<import("../../types").IVault[]>;
     /**
      * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
      * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.

package/lib/modules/vaults/main.js

@@ -53,6 +53,7 @@ __exportStar(require("./getters"), exports);
  * AugustVaults class
  */
 const fetcher_1 = require("./fetcher");
+const web3_1 = require("../../core/constants/web3");
 const ethers_1 = require("ethers");
 const getters_1 = require("./getters");
 const vaults_1 = require("../../services/subgraph/vaults");
@@ -152,22 +153,54 @@ class AugustVaults extends core_1.AugustBase {
         const vaultsPerChainId = options?.chainIds
             ? vaultsPerAvailableProviders.filter((v) => options.chainIds.includes(v.chain))
             : vaultsPerAvailableProviders;
-        // Fetch and transform (filter for active status)
-        const emberVaults = await this.suiService.getEmberVaults({
-            status: 'active',
+        // Skip vaults the post-enrichment filter (filterVaultsIntelligently +
+        // the includeClosed gate below) is guaranteed to drop, BEFORE paying
+        // their per-vault enrichment. `status` / `is_visible` land on the
+        // enriched vault verbatim from this backend row, so filtering on the row
+        // is exactly equivalent to filtering on the enriched result — it just
+        // saves the on-chain reads (and their retry backoff) for vaults that can
+        // never appear in the output. The post-filter below is kept unchanged as
+        // the authority on the final shape.
+        const enrichableVaults = vaultsPerChainId.filter((v) => {
+            const status = v?.status || 'unknown';
+            if (status === 'closed')
+                return !!options?.includeClosed;
+            if (status === 'active')
+                return true;
+            // Mirrors filterVaultsIntelligently: an unknown-status vault survives
+            // only through the invisible bucket; a visible one lands in `failed`.
+            return !(v?.is_visible ?? true);
         });
-        const activeEmberVaults = Array.isArray(emberVaults)
-            ? emberVaults.filter((v) => v?.status === 'active')
-            : [];
-        const whitelistedEmberVaults = activeEmberVaults.filter((v) => {
-            if (!v?.address)
-                return false;
-            const normalizedAddress = v.address.toLowerCase().trim();
-            return constants_1.ALLOWED_SUI_VAULT_ADDRESSES.includes(normalizedAddress);
-        });
-        const transformedVaults = this.suiService.transformEmberVaultsToIVaults(whitelistedEmberVaults);
+        // The backend row for each vault about to be enriched. getVault re-uses
+        // it instead of re-fetching `GET /tokenized_vault/{address}` per vault —
+        // the row came from the same list response (same load flags), so this is
+        // a pure de-duplication of backend traffic, not a freshness change.
+        const vaultRowsByAddress = new Map(enrichableVaults.map((row) => [String(row.address).toLowerCase(), row]));
+        // Ember (Sui) vaults come from a third-party API and are appended to the
+        // non-wallet result. When the caller scopes the query with `chainIds` and
+        // that scope excludes Sui, skip the fetch entirely — previously it was
+        // awaited unconditionally, so a slow Bluefin endpoint stalled even
+        // EVM-only and Solana/Stellar-only queries.
+        const includeSuiVaults = !options?.chainIds || options.chainIds.includes(web3_1.SUI_CHAIN_ID);
+        let transformedVaults = [];
+        if (includeSuiVaults) {
+            // Fetch and transform (filter for active status)
+            const emberVaults = await this.suiService.getEmberVaults({
+                status: 'active',
+            });
+            const activeEmberVaults = Array.isArray(emberVaults)
+                ? emberVaults.filter((v) => v?.status === 'active')
+                : [];
+            const whitelistedEmberVaults = activeEmberVaults.filter((v) => {
+                if (!v?.address)
+                    return false;
+                const normalizedAddress = v.address.toLowerCase().trim();
+                return constants_1.ALLOWED_SUI_VAULT_ADDRESSES.includes(normalizedAddress);
+            });
+            transformedVaults = this.suiService.transformEmberVaultsToIVaults(whitelistedEmberVaults);
+        }
         // Use comprehensive vault fetching for maximum coverage
-        const vaultFetchResult = await (0, fetcher_1.fetchVaultsComprehensive)(vaultsPerChainId, async (vault) => {
+        const vaultFetchResult = await (0, fetcher_1.fetchVaultsComprehensive)(enrichableVaults, async (vault) => {
             // Handle fallback RPC if provided
             const rpcUrl = vault.fallbackRpc || this.providers?.[vault.chain];
             // Closed vaults have no live loans/allocations. In portfolio mode,
@@ -188,6 +221,9 @@ class AugustVaults extends core_1.AugustBase {
                 vault: vault.address,
                 loans: shouldFetchLoans,
                 allocations: shouldFetchAllocations,
+                // Re-use the backend row from the list response instead of letting
+                // getVault re-fetch it per vault (an N+1 against the backend).
+                tokenizedVault: vaultRowsByAddress.get(String(vault.address).toLowerCase()),
                 options: {
                     rpcUrl,
                     solanaService: this.solanaService,
@@ -204,8 +240,8 @@ class AugustVaults extends core_1.AugustBase {
             });
             return v;
         }, {
-            maxRetries: 5,
-            baseDelay: 2000,
+            maxRetries: options?.maxRetries ?? 5,
+            baseDelay: options?.baseDelay ?? 2000,
             batchSize: 15,
             parallelLimit: 8,
             includeClosed: true,
@@ -257,8 +293,8 @@ class AugustVaults extends core_1.AugustBase {
             ...(options?.includeClosed ? filteredResults.closed : []),
             ...filteredResults.invisible,
         ];
-        if ((options.wallet && (0, ethers_1.isAddress)(options.wallet)) ||
-            (options.solanaWallet &&
+        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
@@ -294,7 +330,7 @@ class AugustVaults extends core_1.AugustBase {
                 position: positions?.find((pos) => pos.vault?.toLowerCase() === r.address?.toLowerCase()) || null,
             }));
         }
-        if (options.wallet && !(0, ethers_1.isAddress)(options.wallet)) {
+        if (options?.wallet && !(0, ethers_1.isAddress)(options.wallet)) {
             core_1.Logger.log.warn('getVaults:invalid_wallet', options.wallet);
         }
         // console.log(`#getVaults:`, filteredResponses);

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

@@ -69,3 +69,55 @@ export interface IVaultCustomOptions {
     solanaWallet?: string;
     stellarWallet?: string;
 }
+/**
+ * Options accepted by `getVaults` — on both the `AugustSDK` facade and the
+ * underlying `AugustVaults` module. Defined once so the two signatures cannot
+ * drift (the facade previously declared a narrower inline type that rejected
+ * documented options like `includeClosed` at compile time).
+ */
+export interface IGetVaultsOptions extends IVaultCustomOptions {
+    chainIds?: number[];
+    headers?: IWSMonitorHeaders;
+    loadSubaccounts?: boolean;
+    loadSnapshots?: boolean;
+    /**
+     * Portfolio mode: include closed vaults in the result.
+     *
+     * By default (`false`) closed vaults are excluded, so marketplace /
+     * discovery callers never receive a `status: 'closed'` vault. When set,
+     * closed vaults are returned regardless of `is_visible` (closed +
+     * invisible vaults bucket as closed), so a consumer joining user
+     * positions can render a position held in a closed vault on the
+     * portfolio page.
+     *
+     * In this mode, loans/allocations enrichment is also skipped for closed
+     * vaults: they have none, and the per-vault enrichment
+     * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
+     * vault has no live strategy/debank data or no subaccounts, which would
+     * land the vault in the `failed` bucket and silently drop it before it
+     * reaches the filter. Skipping enrichment lets the vault survive on its
+     * backend metadata + base on-chain read.
+     *
+     * @default false
+     */
+    includeClosed?: boolean;
+    /**
+     * Maximum primary-fetch attempts per vault before the fallback
+     * strategies (fallback RPCs, minimal fetch, extended retry) run.
+     * Attempt `n` waits `baseDelay * 2^(n-1)` ms before retrying, so the
+     * default (5 attempts, 2000 ms base) can spend up to 30s of backoff on
+     * a single persistently-failing vault. Callers racing this method
+     * against their own timeout should lower it (e.g. `2`) so one flaky
+     * vault cannot exhaust the whole budget.
+     *
+     * @default 5
+     */
+    maxRetries?: number;
+    /**
+     * Base backoff delay in **milliseconds** for the per-vault retry
+     * schedule (see `maxRetries`).
+     *
+     * @default 2000
+     */
+    baseDelay?: number;
+}

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

@@ -1,4 +1,4 @@
-import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness } from '../../types';
+import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness, IVaultVersion } from '../../types';
 import { ethers } from 'ethers';
 import type { WalletClient } from 'viem';
 /**
@@ -50,9 +50,14 @@ export declare function getVaultRewards(tokenizedVault: ITokenizedVault): {
  * @param provider - The provider
  * @param vaultAddress - The vault address
  * @param totalAssets - The total assets of the vault
+ * @param knownVersion - Optional pre-resolved vault version. Callers that
+ *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+ *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+ *   API's default load flags at that, a heavier payload on a different cache
+ *   key than the caller's own fetch — just to dispatch on the version.
  * @returns The idle assets
  */
-export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber): Promise<bigint>;
+export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber, knownVersion?: IVaultVersion): Promise<bigint>;
 export declare function getYieldLastRealizedOn(provider: IContractRunner, vaultAddress: IAddress): Promise<number>;
 /**
  * Format APY data from backend tokenized vault into the unified IVaultApy shape.

package/lib/modules/vaults/utils.js

@@ -133,11 +133,16 @@ function getVaultRewards(tokenizedVault) {
  * @param provider - The provider
  * @param vaultAddress - The vault address
  * @param totalAssets - The total assets of the vault
+ * @param knownVersion - Optional pre-resolved vault version. Callers that
+ *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+ *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+ *   API's default load flags at that, a heavier payload on a different cache
+ *   key than the caller's own fetch — just to dispatch on the version.
  * @returns The idle assets
  */
-async function getIdleAssets(provider, vaultAddress, underlying, totalAssets) {
-    const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress))?.[0];
-    const version = (0, vaults_1.getVaultVersionV2)(tokenizedVault);
+async function getIdleAssets(provider, vaultAddress, underlying, totalAssets, knownVersion) {
+    const version = knownVersion ??
+        (0, vaults_1.getVaultVersionV2)((await (0, core_1.fetchTokenizedVault)(vaultAddress))?.[0]);
     let idleAssets;
     switch (version) {
         case 'evm-0': {
@@ -522,7 +527,10 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         isDepositPaused: (0, vaults_1.isBadVault)(tokenizedVault.address),
         decimals: contractCalls.decimals,
         isWithdrawalPaused: contractCalls.withdrawalsPaused,
-        idleAssets: (0, core_1.toNormalizedBn)(await getIdleAssets(provider, tokenizedVault.address, contractCalls.asset, contractCalls.totalAssets), Number(contractCalls.decimals)),
+        idleAssets: (0, core_1.toNormalizedBn)(await getIdleAssets(provider, tokenizedVault.address, contractCalls.asset, contractCalls.totalAssets, 
+        // The row is already in hand — don't let getIdleAssets re-fetch it
+        // just to resolve the version.
+        (0, vaults_1.getVaultVersionV2)(tokenizedVault)), Number(contractCalls.decimals)),
     };
     // Version specific logic
     const version = (0, vaults_1.getVaultVersionV2)(tokenizedVault);

package/lib/sdk.d.ts

@@ -15998,15 +15998,12 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                   /**
                    * Fetch all available vaults across configured networks.
                    * Optionally filter by chain IDs and include loan/allocation data.
-                   * @param options - Configuration for filtering and enriching vault data
+                   * @param options - Configuration for filtering and enriching vault data —
+                   * see {@link IGetVaultsOptions} for the full surface (`includeClosed`
+                   * portfolio mode, `maxRetries`/`baseDelay` retry tuning)
                    * @returns Array of vault objects with metadata and optional position data
                    */
-                  getVaults(options?: {
-                      chainIds?: number[];
-                      headers?: IWSMonitorHeaders;
-                      loadSubaccounts?: boolean;
-                      loadSnapshots?: boolean;
-                  } & IVaultCustomOptions): Promise<IVault[]>;
+                  getVaults(options?: IGetVaultsOptions): Promise<IVault[]>;
                   getTotalDeposited(options?: {
                       loadSubaccounts?: boolean;
                       loadSnapshots?: boolean;
@@ -16793,32 +16790,7 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                    * @param options Filtering and enrichment configuration
                    * @returns Array of vault objects with optional loans/allocations/positions
                    */
-                  getVaults(options?: {
-                      chainIds?: number[];
-                      loadSubaccounts?: boolean;
-                      loadSnapshots?: boolean;
-                      /**
-                       * Portfolio mode: include closed vaults in the result.
-                       *
-                       * By default (`false`) closed vaults are excluded, so marketplace /
-                       * discovery callers never receive a `status: 'closed'` vault. When set,
-                       * closed vaults are returned regardless of `is_visible` (closed +
-                       * invisible vaults bucket as closed), so a consumer joining user
-                       * positions can render a position held in a closed vault on the
-                       * portfolio page.
-                       *
-                       * In this mode, loans/allocations enrichment is also skipped for closed
-                       * vaults: they have none, and the per-vault enrichment
-                       * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
-                       * vault has no live strategy/debank data or no subaccounts, which would
-                       * land the vault in the `failed` bucket and silently drop it before it
-                       * reaches the filter. Skipping enrichment lets the vault survive on its
-                       * backend metadata + base on-chain read.
-                       *
-                       * @default false
-                       */
-                      includeClosed?: boolean;
-                  } & IVaultCustomOptions): Promise<IVault[]>;
+                  getVaults(options?: IGetVaultsOptions): Promise<IVault[]>;
                   /**
                    * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
                    * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.
@@ -18830,9 +18802,14 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                  * @param provider - The provider
                                  * @param vaultAddress - The vault address
                                  * @param totalAssets - The total assets of the vault
+                                 * @param knownVersion - Optional pre-resolved vault version. Callers that
+                                 *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+                                 *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+                                 *   API's default load flags at that, a heavier payload on a different cache
+                                 *   key than the caller's own fetch — just to dispatch on the version.
                                  * @returns The idle assets
                                  */
-                                export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber): Promise<bigint>;
+                                export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber, knownVersion?: IVaultVersion): Promise<bigint>;
 
                                 /**
                                  * Create or reuse a cached Infura provider for the specified chain.
@@ -19348,15 +19325,22 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * @param loans - Include active loan data
                                   * @param allocations - Include DeFi/CeFi allocation breakdowns
                                   * @param options - RPC and service configuration
+                                  * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+                                  *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+                                  *   call earlier), passing it skips this function's own
+                                  *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+                                  *   traffic. The row must have been fetched with the same
+                                  *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
                                   * @returns Complete vault object with optional enrichments
                                   */
-                                 export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, }: {
+                                 export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }: {
                                      vault: IAddress;
                                      loans?: boolean;
                                      allocations?: boolean;
                                      options: IVaultBaseOptions;
                                      loadSubaccounts?: boolean;
                                      loadSnapshots?: boolean;
+                                     tokenizedVault?: ITokenizedVault;
                                  }): Promise<IVault>;
 
                                  /**
@@ -20756,6 +20740,59 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                      status?: string;
                                  }
 
+                                 /**
+                                  * Options accepted by `getVaults` — on both the `AugustSDK` facade and the
+                                  * underlying `AugustVaults` module. Defined once so the two signatures cannot
+                                  * drift (the facade previously declared a narrower inline type that rejected
+                                  * documented options like `includeClosed` at compile time).
+                                  */
+                                 export declare interface IGetVaultsOptions extends IVaultCustomOptions {
+                                     chainIds?: number[];
+                                     headers?: IWSMonitorHeaders;
+                                     loadSubaccounts?: boolean;
+                                     loadSnapshots?: boolean;
+                                     /**
+                                      * Portfolio mode: include closed vaults in the result.
+                                      *
+                                      * By default (`false`) closed vaults are excluded, so marketplace /
+                                      * discovery callers never receive a `status: 'closed'` vault. When set,
+                                      * closed vaults are returned regardless of `is_visible` (closed +
+                                      * invisible vaults bucket as closed), so a consumer joining user
+                                      * positions can render a position held in a closed vault on the
+                                      * portfolio page.
+                                      *
+                                      * In this mode, loans/allocations enrichment is also skipped for closed
+                                      * vaults: they have none, and the per-vault enrichment
+                                      * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
+                                      * vault has no live strategy/debank data or no subaccounts, which would
+                                      * land the vault in the `failed` bucket and silently drop it before it
+                                      * reaches the filter. Skipping enrichment lets the vault survive on its
+                                      * backend metadata + base on-chain read.
+                                      *
+                                      * @default false
+                                      */
+                                     includeClosed?: boolean;
+                                     /**
+                                      * Maximum primary-fetch attempts per vault before the fallback
+                                      * strategies (fallback RPCs, minimal fetch, extended retry) run.
+                                      * Attempt `n` waits `baseDelay * 2^(n-1)` ms before retrying, so the
+                                      * default (5 attempts, 2000 ms base) can spend up to 30s of backoff on
+                                      * a single persistently-failing vault. Callers racing this method
+                                      * against their own timeout should lower it (e.g. `2`) so one flaky
+                                      * vault cannot exhaust the whole budget.
+                                      *
+                                      * @default 5
+                                      */
+                                     maxRetries?: number;
+                                     /**
+                                      * Base backoff delay in **milliseconds** for the per-vault retry
+                                      * schedule (see `maxRetries`).
+                                      *
+                                      * @default 2000
+                                      */
+                                     baseDelay?: number;
+                                 }
+
                                  /**
                                   * Table of Contents
                                   * 1) Subaccounts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.25.0",
+  "version": "8.26.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [