@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/modules/sub-accounts/fetcher.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchSubaccountSummary = exports.fetchSubaccountOtcPositions = exports.fetchSubaccountCefiPositions = exports.fetchSubaccountLoans = exports.fetchSubaccountHeathFactor = void 0;
 const core_1 = require("../../core");
+/**
+ * Fetch subaccount health factor for a given subaccount address
+ */
 const fetchSubaccountHeathFactor = async (address, augustKey, headers) => {
     const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.health_factor(address), {
         headers,
@@ -12,6 +15,9 @@ const fetchSubaccountHeathFactor = async (address, augustKey, headers) => {
     return response.json();
 };
 exports.fetchSubaccountHeathFactor = fetchSubaccountHeathFactor;
+/**
+ * Fetch subaccount loans details
+ */
 const fetchSubaccountLoans = async (payload, augustKey, headers) => {
     const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.loans(payload.address, payload.side, payload.active), {
         headers,
@@ -22,6 +28,9 @@ const fetchSubaccountLoans = async (payload, augustKey, headers) => {
     return response.json();
 };
 exports.fetchSubaccountLoans = fetchSubaccountLoans;
+/**
+ * Fetch the subaccount CeFi positions
+ */
 const fetchSubaccountCefiPositions = async (address, augustKey, headers) => {
     const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.cefi(address), {
         headers,
@@ -32,6 +41,9 @@ const fetchSubaccountCefiPositions = async (address, augustKey, headers) => {
     return response.json();
 };
 exports.fetchSubaccountCefiPositions = fetchSubaccountCefiPositions;
+/**
+ * Fetch the subaccount OTC positions
+ */
 const fetchSubaccountOtcPositions = async (address, augustKey, headers) => {
     const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.otc_positions(address), {
         headers,
@@ -42,6 +54,9 @@ const fetchSubaccountOtcPositions = async (address, augustKey, headers) => {
     return response.json();
 };
 exports.fetchSubaccountOtcPositions = fetchSubaccountOtcPositions;
+/**
+ * Fetch the subaccount summary view
+ */
 const fetchSubaccountSummary = async (address, augustKey, headers) => {
     const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.summary(address), {
         headers,

package/lib/modules/sub-accounts/main.d.ts

@@ -1,8 +1,19 @@
-import { AugustBase, IAugustBase } from '../../core';
-import { IAddress } from '../../types';
+import { AugustBase, type IAugustBase } from '../../core';
+import type { IAddress } from '../../types';
+/**
+ * Subaccount operation class interacting with August Subaccounts
+ * Subaccount is a smart contract wallet that serves as the fundamental infrastructure for August's platform.
+ * It functions as a cross-margin account designed for optimal capital efficiency.
+ * Most of the operations require a August API key to perform
+ */
 export declare class AugustSubAccounts extends AugustBase {
     private headers;
     constructor(baseConfig: IAugustBase);
+    /**
+     * Retrieves the health factor for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns The health factor data including collateral value, loan value, and health factor ratio
+     */
     getSubaccountHealthFactor(subaccountAddress: IAddress): Promise<{
         id: `0x${string}`;
         dateTime: string;
@@ -10,9 +21,31 @@ export declare class AugustSubAccounts extends AugustBase {
         totalCollateral: number;
         totalLoan: number;
     }>;
+    /**
+     * Retrieves loan positions for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @param side - Filter by loan side: 'BOTH' for all loans, 'LENDER' for lent positions, 'BORROWER' for borrowed positions
+     * @param active - When true, returns only active loans; when false, returns all loans including closed ones
+     * @returns List of loan positions matching the specified filters
+     */
     getSubaccountLoans(subaccountAddress: IAddress, side: 'BOTH' | 'LENDER' | 'BORROWER', active: boolean): Promise<import("../../types").IWSSubaccountLoan[]>;
+    /**
+     * Retrieves CeFi (Centralized Finance) positions for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns List of CeFi positions held by the subaccount
+     */
     getSubaccountCefiPositions(subaccountAddress: IAddress): Promise<import("../../types").IWSSubaccountCefi[]>;
+    /**
+     * Retrieves OTC (Over-The-Counter) positions for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns List of OTC positions held by the subaccount
+     */
     getSubaccountOtcPositions(subaccountAddress: IAddress): Promise<import("../../types").IOTCPosition[]>;
+    /**
+     * Retrieves the summary view for a subaccount or EOA operator.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns The full summary including portfolio, loanbook, tokens, and account values
+     */
     getSubaccountSummary(subaccountAddress: IAddress): Promise<{
         address: `0x${string}`;
         name: string;

package/lib/modules/sub-accounts/main.js

@@ -1,18 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AugustSubAccounts = void 0;
+/**
+ * The August Sub Accounts Module.
+ *
+ * @module AugustSubAccounts
+ */
 const fetcher_1 = require("./fetcher");
 const utils_1 = require("./utils");
 const core_1 = require("../../core");
+/**
+ * Subaccount operation class interacting with August Subaccounts
+ * Subaccount is a smart contract wallet that serves as the fundamental infrastructure for August's platform.
+ * It functions as a cross-margin account designed for optimal capital efficiency.
+ * Most of the operations require a August API key to perform
+ */
 class AugustSubAccounts extends core_1.AugustBase {
+    headers = null;
     constructor(baseConfig) {
         super(baseConfig);
-        this.headers = null;
         this.headers = {
             'x-environment': this.monitoring?.['x-environment'],
             'x-user-id': this.monitoring?.['x-user-id'],
         };
     }
+    /**
+     * Retrieves the health factor for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns The health factor data including collateral value, loan value, and health factor ratio
+     */
     async getSubaccountHealthFactor(subaccountAddress) {
         const response = await (0, fetcher_1.fetchSubaccountHeathFactor)(subaccountAddress, this.keys.august, this.headers);
         return {
@@ -23,18 +39,40 @@ class AugustSubAccounts extends core_1.AugustBase {
             totalLoan: response.total_loan_value,
         };
     }
+    /**
+     * Retrieves loan positions for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @param side - Filter by loan side: 'BOTH' for all loans, 'LENDER' for lent positions, 'BORROWER' for borrowed positions
+     * @param active - When true, returns only active loans; when false, returns all loans including closed ones
+     * @returns List of loan positions matching the specified filters
+     */
     async getSubaccountLoans(subaccountAddress, side, active) {
         const response = await (0, fetcher_1.fetchSubaccountLoans)({ address: subaccountAddress, active, side }, this.keys.august, this.headers);
         return response;
     }
+    /**
+     * Retrieves CeFi (Centralized Finance) positions for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns List of CeFi positions held by the subaccount
+     */
     async getSubaccountCefiPositions(subaccountAddress) {
         const response = await (0, fetcher_1.fetchSubaccountCefiPositions)(subaccountAddress, this.keys.august, this.headers);
         return response;
     }
+    /**
+     * Retrieves OTC (Over-The-Counter) positions for a subaccount.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns List of OTC positions held by the subaccount
+     */
     async getSubaccountOtcPositions(subaccountAddress) {
         const response = await (0, fetcher_1.fetchSubaccountOtcPositions)(subaccountAddress, this.keys.august, this.headers);
         return response;
     }
+    /**
+     * Retrieves the summary view for a subaccount or EOA operator.
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns The full summary including portfolio, loanbook, tokens, and account values
+     */
     async getSubaccountSummary(subaccountAddress) {
         const response = await (0, fetcher_1.fetchSubaccountSummary)(subaccountAddress, this.keys.august, this.headers);
         return (0, utils_1.transformSubaccountSummary)(response);

package/lib/modules/sub-accounts/utils.d.ts

@@ -1,4 +1,7 @@
-import { IWSSubaccountSummary } from '../../types';
+import type { IWSSubaccountSummary } from '../../types';
+/**
+ * Transform the raw API response to camelCase
+ */
 export declare const transformSubaccountSummary: (response: IWSSubaccountSummary) => {
     address: `0x${string}`;
     name: string;

package/lib/modules/sub-accounts/utils.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformSubaccountSummary = void 0;
+/**
+ * Transform the raw API response to camelCase
+ */
 const transformSubaccountSummary = (response) => {
     return {
         address: response.address,

package/lib/modules/vaults/adapter.helpers.d.ts

@@ -1,6 +1,15 @@
-import { BaseContract, Signer, Wallet } from 'ethers';
-import { IAddress } from '../../types';
-import { IVaultAdapterConfig } from '../../types/vaults';
+/**
+ * Adapter Helper Functions
+ *
+ * Functions to support deposits with alternative tokens through swap adapters,
+ * wrapper contracts, and Paraswap integration.
+ */
+import type { BaseContract, Signer, Wallet } from 'ethers';
+import type { IAddress } from '../../types';
+import type { IVaultAdapterConfig } from '../../types/vaults';
+/**
+ * Get quote from Paraswap for token swap
+ */
 export declare function getParaswapQuote({ srcToken, destToken, amount, network, srcDecimals, destDecimals, }: {
     srcToken: string;
     destToken: string;
@@ -9,6 +18,9 @@ export declare function getParaswapQuote({ srcToken, destToken, amount, network,
     srcDecimals: number;
     destDecimals: number;
 }): Promise<any>;
+/**
+ * Build swap and deposit transaction for Paraswap bridge
+ */
 export declare function buildSwapAndDepositTransaction({ signer, srcToken, srcDecimals, destToken, destDecimals, amount, network, adapterConfig, userAddress, }: {
     signer: Signer | Wallet;
     srcToken: IAddress;
@@ -20,6 +32,9 @@ export declare function buildSwapAndDepositTransaction({ signer, srcToken, srcDe
     adapterConfig: IVaultAdapterConfig;
     userAddress: IAddress;
 }): Promise<BaseContract>;
+/**
+ * Build native/wrapped token deposit transaction
+ */
 export declare function buildNativeDepositTransaction({ signer, srcToken, amount, poolName, adapterConfig, userAddress, }: {
     signer: Signer | Wallet;
     srcToken: IAddress;
@@ -33,6 +48,9 @@ export declare function buildNativeDepositTransaction({ signer, srcToken, amount
     args: any[];
     value?: bigint;
 }>;
+/**
+ * Preview adapter deposit output
+ */
 export declare function previewAdapterDeposit({ signer, vaultAddress, srcToken, srcAmount, srcDecimals, destToken, destDecimals, adapterConfig, chainId, }: {
     signer: Signer | Wallet;
     vaultAddress: IAddress;

package/lib/modules/vaults/adapter.helpers.js

@@ -1,4 +1,10 @@
 "use strict";
+/**
+ * Adapter Helper Functions
+ *
+ * Functions to support deposits with alternative tokens through swap adapters,
+ * wrapper contracts, and Paraswap integration.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getParaswapQuote = getParaswapQuote;
 exports.buildSwapAndDepositTransaction = buildSwapAndDepositTransaction;
@@ -7,10 +13,19 @@ exports.previewAdapterDeposit = previewAdapterDeposit;
 const adapters_1 = require("../../core/constants/adapters");
 const abis_1 = require("../../abis");
 const core_1 = require("../../core");
+/**
+ * Paraswap API endpoints
+ */
 const PARASWAP_PRICES_API = 'https://api.paraswap.io/prices';
+/**
+ * Paraswap partner configuration
+ */
 const PARASWAP_PARTNER = 'august';
 const PARASWAP_PARTNER_ADDRESS = '0xb60ee0FA5B6bA917255A03e744967E0Bda531dD0';
 const PARASWAP_VERSION = '6.2';
+/**
+ * Get quote from Paraswap for token swap
+ */
 async function getParaswapQuote({ srcToken, destToken, amount, network, srcDecimals, destDecimals, }) {
     const params = new URLSearchParams();
     params.append('network', network);
@@ -32,7 +47,13 @@ async function getParaswapQuote({ srcToken, destToken, amount, network, srcDecim
     const data = await response.json();
     return data?.priceRoute || {};
 }
+// Note: buildParaswapTransaction is kept for potential future use
+// Currently transaction building is handled directly in buildSwapAndDepositTransaction
+/**
+ * Build swap and deposit transaction for Paraswap bridge
+ */
 async function buildSwapAndDepositTransaction({ signer, srcToken, srcDecimals, destToken, destDecimals, amount, network, adapterConfig, userAddress, }) {
+    // Get price quote from Paraswap
     const priceRoute = await getParaswapQuote({
         srcToken,
         destToken,
@@ -44,6 +65,8 @@ async function buildSwapAndDepositTransaction({ signer, srcToken, srcDecimals, d
     if (!priceRoute || !priceRoute.destAmount) {
         throw new Error('No price route found from Paraswap');
     }
+    // Create adapter contract
+    // Note: Transaction data will be built in the calling code
     const adapterContract = (0, core_1.createContract)({
         address: adapterConfig.wrapperAddress,
         provider: signer,
@@ -51,6 +74,9 @@ async function buildSwapAndDepositTransaction({ signer, srcToken, srcDecimals, d
     });
     return adapterContract;
 }
+/**
+ * Build native/wrapped token deposit transaction
+ */
 async function buildNativeDepositTransaction({ signer, srcToken, amount, poolName, adapterConfig, userAddress, }) {
     const isNative = srcToken === '0x0000000000000000000000000000000000000000';
     const wrapperContract = (0, core_1.createContract)({
@@ -59,6 +85,7 @@ async function buildNativeDepositTransaction({ signer, srcToken, amount, poolNam
         abi: (adapterConfig.abi ||
             abis_1.ABI_WRAPPER_ADAPTER),
     });
+    // Handle different pool types
     if (poolName === adapters_1.POOL_NAMES.ETH_TREEHOUSE_GROWTH) {
         if (isNative) {
             return {
@@ -101,6 +128,7 @@ async function buildNativeDepositTransaction({ signer, srcToken, amount, poolNam
             ],
         };
     }
+    // Default native deposit
     if (isNative && adapterConfig.isNativeTokenDeposit) {
         return {
             contract: wrapperContract,
@@ -111,7 +139,11 @@ async function buildNativeDepositTransaction({ signer, srcToken, amount, poolNam
     }
     throw new Error('Unsupported deposit configuration');
 }
+/**
+ * Preview adapter deposit output
+ */
 async function previewAdapterDeposit({ signer, vaultAddress, srcToken, srcAmount, srcDecimals, destToken, destDecimals, adapterConfig, chainId, }) {
+    // If using Paraswap bridge, get quote
     if (adapterConfig.bridgeId === 2) {
         const quote = await getParaswapQuote({
             srcToken,
@@ -123,6 +155,7 @@ async function previewAdapterDeposit({ signer, vaultAddress, srcToken, srcAmount
         });
         return BigInt(quote.destAmount || 0);
     }
+    // If view adapter is available, use it
     if (adapterConfig.viewAdapter) {
         const viewContract = (0, core_1.createContract)({
             address: adapterConfig.viewAdapter,
@@ -145,6 +178,7 @@ async function previewAdapterDeposit({ signer, vaultAddress, srcToken, srcAmount
         const output = await viewContract.getRsETHAmountToMint(srcToken, BigInt(srcAmount));
         return BigInt(output);
     }
+    // Default: assume 1:1 ratio
     return BigInt(srcAmount);
 }
 //# sourceMappingURL=adapter.helpers.js.map

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

@@ -1,3 +1,37 @@
+import type { IAddress } from '../../types';
+/**
+ * Fetch the set of vaults whose deposit/withdraw history is served from the
+ * backend Mongo snapshot (`/upshift/vault_history`) rather than their (retired)
+ * Goldsky subgraph.
+ *
+ * This is the routing source of truth: a vault appears here only once its
+ * history has been backfilled, so the SDK can never reroute a vault to empty
+ * snapshot data ahead of its backfill. Result is cached for 10 minutes.
+ *
+ * Side effects: one HTTP GET to the public API (cached).
+ *
+ * @returns A set of lowercased vault addresses. Empty on any error — callers
+ *   then fall back to the subgraph path, which is the safe default while
+ *   subgraphs still exist.
+ */
+export declare function fetchArchivedVaults(): Promise<Set<string>>;
+/**
+ * Whether a vault's history should be served from the backend snapshot rather
+ * than its subgraph. Backed by {@link fetchArchivedVaults} (cached).
+ *
+ * @param vaultAddress - The vault contract address (any casing).
+ * @returns `true` if the vault has a backfilled history snapshot.
+ */
+export declare function isArchivedVault(vaultAddress: IAddress): Promise<boolean>;
+/**
+ * Specialized vault fetching with enhanced retry logic and fallback strategies
+ * This function attempts to fetch vault data with multiple fallback approaches
+ *
+ * The return shape is "success flag wins": when `success === true`, `data` is
+ * the resolved value (which may legitimately be falsy — `0`, `''`, `0n`,
+ * `null`); when `success === false`, `error` is populated. Callers must branch
+ * on `success`, not on the truthiness of `data`.
+ */
 export declare function fetchVaultWithFallback<T>(vaultAddress: string, fetchFn: () => Promise<T>, options?: {
     maxRetries?: number;
     baseDelay?: number;
@@ -9,6 +43,10 @@ export declare function fetchVaultWithFallback<T>(vaultAddress: string, fetchFn:
     error?: Error;
     strategy: string;
 }>;
+/**
+ * Batch vault fetching with intelligent retry and fallback
+ * Ensures maximum vault coverage by trying multiple strategies
+ */
 export declare function fetchVaultsBatch<T>(vaults: Array<{
     address: string;
     fetchFn: () => Promise<T>;
@@ -31,6 +69,10 @@ export declare function fetchVaultsBatch<T>(vaults: Array<{
     totalAttempted: number;
     successRate: number;
 }>;
+/**
+ * Comprehensive vault fetching that handles all failure points
+ * This function ensures maximum vault coverage by implementing multiple strategies
+ */
 export declare function fetchVaultsComprehensive<T>(vaults: Array<{
     address: string;
     chain: number;
@@ -73,6 +115,9 @@ export declare function fetchVaultsComprehensive<T>(vaults: Array<{
         rpcFailures: Record<number, number>;
     };
 }>;
+/**
+ * Enhanced vault filtering that preserves more vaults while maintaining quality
+ */
 export declare function filterVaultsIntelligently<T extends {
     status?: string;
     isVisible?: boolean;

package/lib/modules/vaults/fetcher.js

@@ -1,11 +1,62 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchVaultMetadata = void 0;
+exports.fetchArchivedVaults = fetchArchivedVaults;
+exports.isArchivedVault = isArchivedVault;
 exports.fetchVaultWithFallback = fetchVaultWithFallback;
 exports.fetchVaultsBatch = fetchVaultsBatch;
 exports.fetchVaultsComprehensive = fetchVaultsComprehensive;
 exports.filterVaultsIntelligently = filterVaultsIntelligently;
 const core_1 = require("../../core");
+const ARCHIVED_VAULTS_CACHE_KEY = 'archived_vaults';
+const ARCHIVED_VAULTS_TTL_MS = 10 * 60 * 1000;
+/**
+ * Fetch the set of vaults whose deposit/withdraw history is served from the
+ * backend Mongo snapshot (`/upshift/vault_history`) rather than their (retired)
+ * Goldsky subgraph.
+ *
+ * This is the routing source of truth: a vault appears here only once its
+ * history has been backfilled, so the SDK can never reroute a vault to empty
+ * snapshot data ahead of its backfill. Result is cached for 10 minutes.
+ *
+ * Side effects: one HTTP GET to the public API (cached).
+ *
+ * @returns A set of lowercased vault addresses. Empty on any error — callers
+ *   then fall back to the subgraph path, which is the safe default while
+ *   subgraphs still exist.
+ */
+async function fetchArchivedVaults() {
+    const cached = core_1.CACHE.get(ARCHIVED_VAULTS_CACHE_KEY);
+    if (cached)
+        return cached;
+    try {
+        const response = await (0, core_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.archivedVaults);
+        if (response.status !== 200) {
+            core_1.Logger.log.error('fetchArchivedVaults', `non-200 from archived endpoint: ${response.status}`);
+            return new Set();
+        }
+        const addresses = (await response.json());
+        const set = new Set(addresses.map((a) => a.toLowerCase()));
+        core_1.CACHE.set(ARCHIVED_VAULTS_CACHE_KEY, set, { ttl: ARCHIVED_VAULTS_TTL_MS });
+        return set;
+    }
+    catch (e) {
+        core_1.Logger.log.error('fetchArchivedVaults', e);
+        return new Set();
+    }
+}
+/**
+ * Whether a vault's history should be served from the backend snapshot rather
+ * than its subgraph. Backed by {@link fetchArchivedVaults} (cached).
+ *
+ * @param vaultAddress - The vault contract address (any casing).
+ * @returns `true` if the vault has a backfilled history snapshot.
+ */
+async function isArchivedVault(vaultAddress) {
+    const archived = await fetchArchivedVaults();
+    return archived.has(vaultAddress.toLowerCase());
+}
+/** @internal */
 async function runWithConcurrency(tasks, limit) {
     if (!Number.isFinite(limit) || limit <= 0) {
         throw new Error(`runWithConcurrency: limit must be a positive finite number, got ${limit}`);
@@ -13,6 +64,8 @@ async function runWithConcurrency(tasks, limit) {
     const results = new Array(tasks.length);
     let nextIndex = 0;
     const workerCount = Math.min(Math.floor(limit), tasks.length);
+    // `nextIndex++` is safe across workers — JS is single-threaded and the
+    // increment runs to completion before any worker yields at `await`.
     const workers = Array.from({ length: workerCount }, async () => {
         while (true) {
             const i = nextIndex++;
@@ -24,6 +77,15 @@ async function runWithConcurrency(tasks, limit) {
     await Promise.all(workers);
     return results;
 }
+/**
+ * Specialized vault fetching with enhanced retry logic and fallback strategies
+ * This function attempts to fetch vault data with multiple fallback approaches
+ *
+ * The return shape is "success flag wins": when `success === true`, `data` is
+ * the resolved value (which may legitimately be falsy — `0`, `''`, `0n`,
+ * `null`); when `success === false`, `error` is populated. Callers must branch
+ * on `success`, not on the truthiness of `data`.
+ */
 async function fetchVaultWithFallback(vaultAddress, fetchFn, options = {}) {
     const { maxRetries = 3, baseDelay = 1000 } = options;
     try {
@@ -42,6 +104,10 @@ async function fetchVaultWithFallback(vaultAddress, fetchFn, options = {}) {
         strategy: 'all-failed',
     };
 }
+/**
+ * Batch vault fetching with intelligent retry and fallback
+ * Ensures maximum vault coverage by trying multiple strategies
+ */
 async function fetchVaultsBatch(vaults, options = {}) {
     const { maxRetries = 3, baseDelay = 1000, batchSize = 10, parallelLimit = batchSize, } = options;
     const successful = [];
@@ -57,6 +123,10 @@ async function fetchVaultsBatch(vaults, options = {}) {
                     maxRetries,
                     baseDelay,
                 });
+                // Branch on `result.success` only — not on truthiness of `result.data`.
+                // A successful fetch can legitimately resolve to a falsy value
+                // (`0`, `''`, `0n`, `null`); the cast respects the function's
+                // documented contract that `data` is present on the success branch.
                 if (result.success) {
                     successful.push({
                         index: globalIndex,
@@ -81,6 +151,7 @@ async function fetchVaultsBatch(vaults, options = {}) {
             }
         });
         await runWithConcurrency(batchTasks, parallelLimit);
+        // Small delay between batches to be respectful to RPC endpoints
         if (i + batchSize < vaults.length) {
             await new Promise((resolve) => setTimeout(resolve, 100));
         }
@@ -93,8 +164,14 @@ async function fetchVaultsBatch(vaults, options = {}) {
         successRate,
     };
 }
+/**
+ * Comprehensive vault fetching that handles all failure points
+ * This function ensures maximum vault coverage by implementing multiple strategies
+ */
 async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
-    const { maxRetries = 5, baseDelay = 2000, batchSize = 10, parallelLimit = batchSize, includeClosed: _includeClosed = false, includeInvisible: _includeInvisible = false, fallbackRpcUrls = {}, timeout = 60000, } = options;
+    const { maxRetries = 5, baseDelay = 2000, batchSize = 10, parallelLimit = batchSize, includeClosed: _includeClosed = false, // Reserved for future filtering
+    includeInvisible: _includeInvisible = false, // Reserved for future filtering
+    fallbackRpcUrls = {}, timeout = 60000, } = options;
     const successful = [];
     const failed = [];
     const rpcFailures = {};
@@ -106,6 +183,7 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
             totalAttempted++;
             let attempts = 0;
             let lastError;
+            // Strategy 1: Primary fetch with retry
             for (attempts = 1; attempts <= maxRetries; attempts++) {
                 try {
                     const data = await Promise.race([
@@ -123,12 +201,13 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
                 catch (error) {
                     lastError = error;
                     if (attempts < maxRetries) {
-                        const delay = baseDelay * Math.pow(2, attempts - 1);
+                        const delay = baseDelay * 2 ** (attempts - 1);
                         core_1.Logger.log.warn('fetchVaultsComprehensive', `Vault ${vault.address} attempt ${attempts} failed, retrying in ${delay}ms: ${error.message}`);
                         await new Promise((resolve) => setTimeout(resolve, delay));
                     }
                 }
             }
+            // Strategy 2: Try with fallback RPC endpoints
             if (fallbackRpcUrls[vault.chain] &&
                 fallbackRpcUrls[vault.chain].length > 0) {
                 for (const fallbackRpc of fallbackRpcUrls[vault.chain]) {
@@ -154,6 +233,7 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
                     }
                 }
             }
+            // Strategy 3: Try with minimal data fetching (if fetchFn supports it)
             try {
                 const data = await Promise.race([
                     fetchFn({ ...vault, minimal: true }),
@@ -173,6 +253,7 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
+            // Strategy 4: Extended retry with longer delays
             try {
                 const extendedDelay = baseDelay * 3;
                 await new Promise((resolve) => setTimeout(resolve, extendedDelay));
@@ -194,6 +275,7 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
+            // All strategies failed
             failed.push({
                 index: globalIndex,
                 error: lastError || new Error('All strategies failed'),
@@ -201,9 +283,11 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
                 chain: vault.chain,
                 attempts: attempts + 2,
             });
+            // Track RPC failures by chain
             rpcFailures[vault.chain] = (rpcFailures[vault.chain] || 0) + 1;
         });
         await runWithConcurrency(batchTasks, parallelLimit);
+        // Small delay between batches to be respectful to RPC endpoints
         if (i + batchSize < vaults.length) {
             await new Promise((resolve) => setTimeout(resolve, 200));
         }
@@ -218,12 +302,15 @@ async function fetchVaultsComprehensive(vaults, fetchFn, options = {}) {
             totalVaults: vaults.length,
             successfulVaults: successful.length,
             failedVaults: failed.length,
-            closedVaults: 0,
-            invisibleVaults: 0,
+            closedVaults: 0, // Will be calculated by the calling code
+            invisibleVaults: 0, // Will be calculated by the calling code
             rpcFailures,
         },
     };
 }
+/**
+ * Enhanced vault filtering that preserves more vaults while maintaining quality
+ */
 function filterVaultsIntelligently(vaults, options = {}) {
     const { includeClosed = true, includeInvisible = true, includeNull = false, minStatus = ['active', 'closed'], } = options;
     const active = [];