@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/modules/vaults/main.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * The August Vaults Module.
+ *
+ * @module AugustVaults
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -40,7 +45,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AugustVaults = void 0;
+/**
+ * Export getters
+ */
 __exportStar(require("./getters"), exports);
+/**
+ * AugustVaults class
+ */
 const fetcher_1 = require("./fetcher");
 const ethers_1 = require("ethers");
 const getters_1 = require("./getters");
@@ -55,6 +66,10 @@ 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");
+/**
+ * Vault operations class handling multi-chain vault queries and user positions.
+ * Supports both EVM and Solana vaults with unified interface.
+ */
 class AugustVaults extends core_1.AugustBase {
     constructor(baseConfig, solana, sui) {
         super(baseConfig);
@@ -66,20 +81,51 @@ class AugustVaults extends core_1.AugustBase {
             'x-user-id': this.monitoring?.['x-user-id'],
         };
     }
+    /**
+     * @description deposit underlying token into the specified pool with adapter support. This is for when we cannot pass in a signer in sdk and need to do so as an arg
+     * @param signer signer / wallet object
+     * @param options object including pool contract address, user wallet address, string amount, and optional depositAsset
+     * @returns deposit tx hash
+     */
     async vaultDeposit(signer, options) {
         return (0, write_actions_1.vaultDeposit)(signer, options);
     }
+    /**
+     * @description deposit native token (ETH/AVAX/etc) into a vault using MultiAssetNativeDepositWrapper
+     * @param signer signer / wallet object
+     * @param options object including wrapper contract address, receiver address (optional), and amount
+     * @returns deposit tx hash
+     */
     async depositNative(signer, options) {
         return (0, write_actions_1.depositNative)(signer, options);
     }
+    /**
+     * Fetch all vaults across configured networks with optional enrichment.
+     * Automatically filters by available providers and optionally by chain IDs.
+     * 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.
+     * @param options Filtering and enrichment configuration
+     * @returns Array of vault objects with optional loans/allocations/positions
+     */
     async getVaults(options) {
+        // if (!(this.authorized && this.augustKey)) // @todo: commented out for integrators
         const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, options?.loadSubaccounts, options?.loadSnapshots);
-        const vaultsPerAvailableProviders = allVaults.filter((v) => v?.chain_type === 'stellar' ||
+        const vaultsPerAvailableProviders = allVaults.filter((v) => 
+        // Stellar vaults are backend-only (no RPC provider required)
+        v?.chain_type === 'stellar' ||
+            // Solana vaults use this.solanaService (not this.providers). Without
+            // an explicit pass-through here they get silently dropped on any
+            // instance whose ACTIVE_RPC_URLS() doesn't register chainId -1.
+            // Gate on solanaService presence so we don't let a vault through that
+            // we have no adapter to fetch — that would crash the inner getter and
+            // turn into a PENDING entry that the final filter drops anyway.
             (v?.chain_type === 'solana' && !!this.solanaService) ||
             (this.providers?.[v?.chain] ? true : false));
         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',
         });
@@ -93,11 +139,21 @@ class AugustVaults extends core_1.AugustBase {
             return constants_1.ALLOWED_SUI_VAULT_ADDRESSES.includes(normalizedAddress);
         });
         const transformedVaults = this.suiService.transformEmberVaultsToIVaults(whitelistedEmberVaults);
+        // Use comprehensive vault fetching for maximum coverage
         const vaultFetchResult = await (0, fetcher_1.fetchVaultsComprehensive)(vaultsPerChainId, async (vault) => {
+            // Handle fallback RPC if provided
             const rpcUrl = vault.fallbackRpc || this.providers?.[vault.chain];
-            const shouldFetchLoans = !vault.minimal &&
+            // Closed vaults have no live loans/allocations. In portfolio mode,
+            // skip that enrichment so a closed vault is never dropped just because
+            // getVaultAllocations re-throws (no debank data / no subaccounts).
+            const isClosedVault = vault.status === 'closed';
+            const skipClosedEnrichment = !!options?.includeClosed && isClosedVault;
+            // Handle minimal data fetching
+            const shouldFetchLoans = !skipClosedEnrichment &&
+                !vault.minimal &&
                 (typeof options?.loans !== 'undefined' ? options?.loans : true);
-            const shouldFetchAllocations = !vault.minimal &&
+            const shouldFetchAllocations = !skipClosedEnrichment &&
+                !vault.minimal &&
                 (typeof options?.allocations !== 'undefined'
                     ? options?.allocations
                     : true);
@@ -111,6 +167,9 @@ class AugustVaults extends core_1.AugustBase {
                     env: this.monitoring?.env,
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
+                    // Portfolio mode: let the EVM getter resolve closed + invisible
+                    // vaults instead of null-ing them, so the closed vault survives.
+                    includeClosed: options?.includeClosed,
                 },
                 loadSubaccounts: options?.loadSubaccounts,
                 loadSnapshots: options?.loadSnapshots,
@@ -125,14 +184,17 @@ class AugustVaults extends core_1.AugustBase {
             includeInvisible: false,
             timeout: 60000,
             fallbackRpcUrls: {
+                // Use configured fallback RPC endpoints for each chain
                 1: (0, core_1.getFallbackRpcUrls)(1),
                 56: (0, core_1.getFallbackRpcUrls)(56),
                 43114: (0, core_1.getFallbackRpcUrls)(43114),
                 8453: (0, core_1.getFallbackRpcUrls)(8453),
                 42161: (0, core_1.getFallbackRpcUrls)(42161),
                 137: (0, core_1.getFallbackRpcUrls)(137),
+                // [SPECIAL_CHAINS.solana.chainId]: getFallbackRpcUrls(SPECIAL_CHAINS.solana.chainId),
             },
         });
+        // Log vault fetching results in DEV mode
         core_1.Logger.log.info('getVaults', `Total: ${vaultFetchResult.coverageReport.totalVaults}, ` +
             `Success: ${vaultFetchResult.coverageReport.successfulVaults}, ` +
             `Failed: ${vaultFetchResult.coverageReport.failedVaults}, ` +
@@ -145,6 +207,7 @@ class AugustVaults extends core_1.AugustBase {
                 attempts: f.attempts,
             })));
         }
+        // Use intelligent filtering to preserve more vaults
         const vaultResponses = vaultFetchResult.successful
             .sort((a, b) => a.index - b.index)
             .map((item) => item.data);
@@ -153,13 +216,23 @@ class AugustVaults extends core_1.AugustBase {
             includeInvisible: true,
             minStatus: ['active', 'closed'],
         });
+        // Closed vaults are included in the result ONLY when the caller opts in via
+        // `includeClosed` (portfolio mode). By default they are dropped, so the
+        // marketplace / discovery callers never receive a closed vault and don't
+        // have to filter `status === 'closed'` themselves. The portfolio passes
+        // `includeClosed: true` so a user's position in a closed vault can be
+        // joined against this list. Note: closed + invisible vaults land in the
+        // `closed` bucket (the status check precedes the visibility check in
+        // filterVaultsIntelligently), so this single gate covers them too.
         const filteredResponses = [
             ...filteredResults.active,
+            ...(options?.includeClosed ? filteredResults.closed : []),
             ...filteredResults.invisible,
         ];
         if ((options.wallet && (0, ethers_1.isAddress)(options.wallet)) ||
             (options.solanaWallet &&
                 utils_1.SolanaUtils.isSolanaAddress(options.solanaWallet))) {
+            // fetch all positions for user wallet
             const vaultResponses = await (0, core_1.promiseSettle)(vaultsPerAvailableProviders.map((v) => (0, getters_1.getVaultPositions)({
                 vault: v.address,
                 wallet: options.wallet,
@@ -172,7 +245,9 @@ class AugustVaults extends core_1.AugustBase {
                     augustKey: this.keys?.august,
                     subgraphKey: this.keys?.graph,
                 },
-            })), 5, 2000);
+            })), 5, // 5 retries
+            2000);
+            // return vault object with position property
             const positions = vaultResponses
                 .flat()
                 .filter((v) => v.status !== 'PENDING');
@@ -181,11 +256,18 @@ 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);
         return [...filteredResponses, ...transformedVaults];
     }
+    /**
+     * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
+     * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.
+     * @param options Optional configuration for loading vaults
+     * @returns Total deposited amount in USD (sum of all latest_reported_tvl values)
+     */
     async getTotalDeposited(options) {
         const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, options?.loadSubaccounts, options?.loadSnapshots);
         let total = 0;
@@ -199,15 +281,28 @@ class AugustVaults extends core_1.AugustBase {
         });
         return total;
     }
+    /**
+     * Fetch detailed data for a single vault with optional enrichment.
+     * Automatically includes loans and allocations unless explicitly disabled.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @param options Enrichment and wallet options
+     * @returns Single vault object with optional position data
+     */
     async getVault({ vault, chainId, options, loadSubaccounts, loadSnapshots, }) {
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
+        // if (!isAddress(vault))
+        //   throw new Error(
+        //     `Vault input parameter is not an address: ${String(vault)}`,
+        //   );
         if (typeof chainId !== 'undefined') {
             if (!this.providers?.[chainId]) {
                 const error = new Error(`Missing RPC URL for chainId ${chainId}`);
                 core_1.Logger.log.error('getVault:missing_provider', error, { chainId });
             }
         }
+        // get vault data
         const vaultResponse = await (0, getters_1.getVault)({
             vault: vault,
             loans: typeof options?.loans !== 'undefined' ? options?.loans : true,
@@ -232,6 +327,7 @@ class AugustVaults extends core_1.AugustBase {
                 (options?.solanaWallet &&
                     utils_1.SolanaUtils.isSolanaAddress(options?.solanaWallet)) ||
                 (options?.stellarWallet && (0, utils_2.isStellarAddress)(options?.stellarWallet)))) {
+            // fetch all positions for user wallet
             const vaultResponses = await (0, getters_1.getVaultPositions)({
                 vault: vault,
                 solanaWallet: options?.solanaWallet,
@@ -248,18 +344,25 @@ class AugustVaults extends core_1.AugustBase {
                     headers: this.headers,
                 },
             });
+            // return vault object with position property
             const positions = vaultResponses.filter((v) => v.status !== 'PENDING');
             return {
                 ...vaultResponse,
                 position: positions?.find((pos) => pos.vault?.toLowerCase() === vault?.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('getVault:invalid_wallet', options?.wallet);
         }
+        // console.log(`#getVault::${vaultResponse.symbol}:`, vaultResponse);
         return vaultResponse;
     }
+    /**
+     *
+     */
     async getVaultLoans({ vault, chainId, }) {
+        // Sanitize
+        // if (!this.authorized) throw new Error('Not authorized.');
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
         if (!(0, ethers_1.isAddress)(vault))
@@ -270,6 +373,7 @@ class AugustVaults extends core_1.AugustBase {
                 core_1.Logger.log.error('getVaultLoans:missing_provider', error, { chainId });
             }
         }
+        // get vault loans data
         const vaultResponse = await (0, getters_1.getVaultLoans)(vault, {
             rpcUrl: chainId
                 ? this.providers?.[chainId]
@@ -283,7 +387,11 @@ class AugustVaults extends core_1.AugustBase {
         });
         return vaultResponse;
     }
+    /**
+     *
+     */
     async getVaultSubaccountLoans({ vault, chainId, }) {
+        // Sanitize
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
         if (!(0, ethers_1.isAddress)(vault))
@@ -296,6 +404,7 @@ class AugustVaults extends core_1.AugustBase {
                 });
             }
         }
+        // get vault subaccount loans data
         const vaultResponse = await (0, getters_1.getVaultSubaccountLoans)(vault, {
             rpcUrl: chainId
                 ? this.providers?.[chainId]
@@ -309,7 +418,12 @@ class AugustVaults extends core_1.AugustBase {
         });
         return vaultResponse;
     }
+    /**
+     *
+     */
     async getVaultAllocations({ vault, chainId, }) {
+        // Sanitize
+        // if (!this.authorized) throw new Error('Not authorized.');
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
         if (!(0, ethers_1.isAddress)(vault) &&
@@ -324,6 +438,7 @@ class AugustVaults extends core_1.AugustBase {
                 });
             }
         }
+        // get vault allocations data
         try {
             const vaultResponse = await (0, getters_1.getVaultAllocations)(vault, {
                 rpcUrl: chainId
@@ -351,7 +466,15 @@ class AugustVaults extends core_1.AugustBase {
             };
         }
     }
+    /**
+     * @deprecated use getVaultHistoricalTimeseries instead
+     * @function getVaultApy gets the vault/pool APR, both current and historical
+     * @param vault pool/vault contract address
+     * @param historical (optional) When passed, returns the historical records of the pool/vault APR
+     * @returns a value or array of objects containing the APR and timestamp
+     */
     async getVaultApy({ vault, historical, }) {
+        // if (!this.authorized) throw new Error('Not authorized.');
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
         if (!(0, ethers_1.isAddress)(vault) && !(0, utils_2.isStellarAddress)(vault))
@@ -366,6 +489,12 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * @function getVaultHistoricalTimeseries gets historical timeseries data for a vault
+     * @param vault Vault contract address
+     * @param nDays Number of days of historical data (default 30, min 1)
+     * @returns Historical timeseries data with TVL, APY, PnL, share price, and other metrics
+     */
     async getVaultHistoricalTimeseries({ vault, nDays, }) {
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
@@ -378,6 +507,9 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     *
+     */
     async getVaultAvailableRedemptions({ vault, chainId, wallet, verbose, }) {
         if (!this.authorized)
             throw new Error('Not authorized.');
@@ -401,6 +533,35 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Historical redemption requests for a vault (settled, cancelled, and
+     * pending-but-out-of-window). Filterable by wallet.
+     *
+     * Stellar vaults return `[]` — on-chain redemption history is not yet
+     * indexed for that adapter.
+     *
+     * @param vault - Vault address (EVM or Stellar). Stellar input is
+     *   accepted but always resolves to an empty array for now.
+     * @param chainId - Chain id to resolve the RPC URL against. Falls
+     *   back to the active network.
+     * @param wallet - Optional EVM wallet filter; when omitted the
+     *   response includes every wallet that has ever redeemed against
+     *   the vault.
+     * @param lookbackBlocks - How far back to scan for redemption logs.
+     *   Defaults to the SDK's internal lookback when omitted.
+     * @returns The same array shape `getVaultRedemptionHistory` returns
+     *   at the module level — historical redemption records, newest
+     *   first.
+     *
+     * @example
+     * ```ts
+     * const history = await sdk.vaultsModule.getVaultRedemptionHistory({
+     *   vault: '0xVault',
+     *   chainId: 8453,
+     *   wallet: '0xWallet',
+     * });
+     * ```
+     */
     async getVaultRedemptionHistory({ vault, chainId, wallet, lookbackBlocks, }) {
         if (!this.authorized)
             throw new Error('Not authorized.');
@@ -424,10 +585,16 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     *
+     */
     async getVaultPositions({ vault, wallet, chainId, showAllVaults, solanaWallet, stellarWallet, options, }) {
+        // if (!this.authorized) throw new Error('Not authorized.');
+        // Validate that at least one wallet type is provided
         if (solanaWallet && !utils_1.SolanaUtils.isSolanaAddress(solanaWallet)) {
             throw new Error('Solana wallet parameter must be provided and be a valid Solana address');
         }
+        // Validate EVM wallet if provided
         if (wallet && !(0, ethers_1.isAddress)(wallet)) {
             throw new Error(`Wallet parameter is not a valid address: ${String(wallet)}`);
         }
@@ -478,7 +645,16 @@ class AugustVaults extends core_1.AugustBase {
             core_1.Logger.log.info(`getPositions::${chainId || 'all'}:`, final.map((v) => v.vault));
             return final;
         }
-        const vaultsPerAvailableProviders = allVaults.filter((v) => v?.chain_type === 'stellar' ||
+        const vaultsPerAvailableProviders = allVaults.filter((v) => 
+        // Stellar vaults are backend-only (no RPC provider required)
+        v?.chain_type === 'stellar' ||
+            // Solana vaults use this.solanaService (not this.providers). Without
+            // this clause every Solana position is dropped on any instance where
+            // ACTIVE_RPC_URLS() doesn't register chainId -1 — which is exactly
+            // how the jitoSOL "missing position" regression manifested. Gate on
+            // solanaService presence so we don't pass Solana vaults through with
+            // no adapter to read them — the inner getter would crash, hit the
+            // outer catch, and silently return PENDING (then get filtered out).
             (v?.chain_type === 'solana' && !!this.solanaService) ||
             (this.providers?.[v?.chain] ? true : false));
         const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map((v) => (0, getters_1.getVaultPositions)({
@@ -501,15 +677,23 @@ class AugustVaults extends core_1.AugustBase {
             final = flattened;
         else
             final = flattened.filter((v) => v?.status !== 'PENDING');
+        // console.log(`#getPositions::${chainId || 'all'}:`, final);
         return final;
     }
+    /**
+     *
+     */
     async getUserHistory({ wallet, chainId, vault, }) {
+        // Santize
+        // if (!this.authorized) throw new Error('Not authorized.');
         if (!(0, ethers_1.isAddress)(wallet))
             throw new Error(`Wallet parameter is not an address: ${String(wallet)}`);
+        // Get Chain ID — required for subgraph queries
         const _chainId = chainId || this.activeNetwork?.chainId;
         if (!_chainId) {
             throw new Error('Chain ID is required for getUserHistory. Pass chainId explicitly or configure an active network.');
         }
+        // Format history initialization
         let finalArray = [];
         function formatHistory(history) {
             return history.map((h) => ({
@@ -522,10 +706,17 @@ class AugustVaults extends core_1.AugustBase {
                 transactionHash: h.transactionHash_,
             }));
         }
+        // Helper function to fetch history for a vault
+        // For LayerZero-enabled vaults (coreUSDC, upUSDC), queries BOTH the standard
+        // subgraph and the LayerZero subgraph, since deposits can be either same-chain
+        // or cross-chain via LayerZero
         const fetchVaultHistory = async (vaultAddress, vaultChainId) => {
+            // Always query the standard subgraph
             const provider = (0, core_1.createProvider)(this.providers?.[vaultChainId]);
             const standardHistory = await (0, vaults_1.getSubgraphUserHistory)(wallet, provider, vaultAddress);
             const formattedStandard = formatHistory(standardHistory);
+            // If this vault also supports LayerZero cross-chain deposits,
+            // query the LayerZero subgraph and merge results
             const layerZeroVaultKey = (0, deposits_1.isLayerZeroVault)(vaultAddress);
             if (layerZeroVaultKey) {
                 try {
@@ -539,6 +730,7 @@ class AugustVaults extends core_1.AugustBase {
                         type: 'deposit',
                         transactionHash: deposit.transactionHash_,
                     }));
+                    // For earnAUSD, also query LayerZero redeems
                     let formattedLayerZeroRedeems = [];
                     if (layerZeroVaultKey === 'earnAUSD') {
                         try {
@@ -557,6 +749,9 @@ class AugustVaults extends core_1.AugustBase {
                             core_1.Logger.log.warn('getUserHistory:layerzero:redeems', `Failed to fetch LayerZero redeems for earnAUSD: ${redeemError.message}`);
                         }
                     }
+                    // Deduplicate against standard subgraph history only — LZ deposits and
+                    // LZ redeems are not deduped against each other because a single tx can
+                    // legitimately emit both a Deposited and a Redeemed event.
                     const seenTxHashes = new Set(formattedStandard.map((h) => h.transactionHash?.toLowerCase()));
                     const uniqueLayerZero = formattedLayerZero.filter((h) => !seenTxHashes.has(h.transactionHash?.toLowerCase()));
                     const uniqueLayerZeroRedeems = formattedLayerZeroRedeems.filter((h) => !seenTxHashes.has(h.transactionHash?.toLowerCase()));
@@ -567,17 +762,21 @@ class AugustVaults extends core_1.AugustBase {
                     ];
                 }
                 catch (error) {
+                    // If LayerZero query fails, still return standard history
                     core_1.Logger.log.warn('getUserHistory:layerzero', `Failed to fetch LayerZero deposits for ${layerZeroVaultKey}: ${error.message}`);
                     return formattedStandard;
                 }
             }
             return formattedStandard;
         };
+        // If vault is provided, return history for that vault
         if (vault) {
             finalArray = await fetchVaultHistory(vault, chainId);
         }
         else {
+            // Fetch all vaults
             const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, false, false);
+            // If chainId is provided, return history for all vaults on that chain
             if (chainId) {
                 const vaultsPerChain = allVaults.filter((v) => v.chain === chainId);
                 const vaultResponses = await Promise.all(vaultsPerChain.map((v) => fetchVaultHistory(v.address, v.chain)));
@@ -585,6 +784,8 @@ class AugustVaults extends core_1.AugustBase {
                 finalArray = flattened;
             }
             else {
+                // Else, fetch all history for all vaults across all initialized chains
+                // LayerZero vaults query subgraphs directly and don't need a provider
                 const vaultsPerAvailableProviders = allVaults.filter((v) => this.providers?.[v?.chain] || (0, deposits_1.isLayerZeroVault)(v.address));
                 const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map((v) => fetchVaultHistory(v.address, v.chain)));
                 const flattened = vaultResponses.flat();
@@ -594,6 +795,11 @@ class AugustVaults extends core_1.AugustBase {
         core_1.Logger.log.info('getUserHistory', `${wallet}::${finalArray.length}`);
         return finalArray;
     }
+    /**
+     * Get lifetime PnL for a user in a specific vault.
+     * @param props Vault address, wallet address, and optional chain ID
+     * @returns Lifetime PnL data including realized and unrealized PnL
+     */
     async getVaultUserLifetimePnl({ vault, wallet, chainId, }) {
         if (!(0, ethers_1.isAddress)(wallet))
             throw new Error(`Wallet parameter is not an address: ${String(wallet)}`);
@@ -616,6 +822,12 @@ class AugustVaults extends core_1.AugustBase {
             coingeckoKey: this.keys?.coingecko,
         });
     }
+    /**
+     * Get PnL for a vault (vault-level, not user-specific).
+     * Returns the vault's overall profit and loss across all users.
+     * @param props Vault address and optional chain ID
+     * @returns Vault PnL in USD and notional value
+     */
     async getVaultPnl({ vault, chainId, }) {
         if (!(0, ethers_1.isAddress)(vault))
             throw new Error(`Vault parameter is not an address: ${String(vault)}`);
@@ -634,9 +846,15 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     *
+     */
     async getUserTransfers({ wallet, chainId, vault, options, }) {
+        // Santize
+        // if (!this.authorized) throw new Error('Not authorized.');
         if (!(0, ethers_1.isAddress)(wallet))
             throw new Error(`Wallet parameter is not an address: ${String(wallet)}`);
+        // Format history initialization
         let finalArray = [];
         function formatTransfers(transfers) {
             return transfers.map((t) => ({
@@ -650,13 +868,16 @@ class AugustVaults extends core_1.AugustBase {
                 transactionHash: t.transactionHash_,
             }));
         }
+        // If vault is provided, return history for that vault
         if (vault) {
             const provider = (0, core_1.createProvider)(this.providers?.[chainId]);
             const userHistory = await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, vault);
             finalArray = formatTransfers(userHistory);
         }
         else {
+            // Fetch all vaults
             const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, false, false);
+            // If chainId is provided, return history for all vaults on that chain
             if (chainId) {
                 const vaultsPerChain = allVaults.filter((v) => v.chain === chainId);
                 const vaultResponses = await Promise.all(vaultsPerChain.map(async (v) => {
@@ -668,6 +889,7 @@ class AugustVaults extends core_1.AugustBase {
                 finalArray = formatTransfers(flattened);
             }
             else {
+                // Else, fetch all history for all vaults across all initialized chains
                 const vaultsPerAvailableProviders = allVaults.filter((v) => this.providers?.[v?.chain] ? true : false);
                 const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map(async (v) => {
                     const provider = (0, core_1.createProvider)(this.providers?.[v.chain]);
@@ -681,6 +903,12 @@ class AugustVaults extends core_1.AugustBase {
         core_1.Logger.log.info('getUserTransfers', `${wallet}::${finalArray.length}`);
         return finalArray;
     }
+    /**
+     * @function getStakingPositions gets all available reward staking positions
+     * @param wallet optionally passed user wallet address
+     * @param chainId optionally passed chainId
+     * @returns all available staking positions for connected or passed network(s)
+     */
     async getStakingPositions(wallet, chainId) {
         if (chainId) {
             const positions = await (0, getters_1.getRewardsStakingPositions)({
@@ -699,6 +927,12 @@ class AugustVaults extends core_1.AugustBase {
         }));
         return positions.flat();
     }
+    /**
+     * @function getVaultTvl gets the vault/pool TVL, both current and historical
+     * @param vault pool/vault contract address
+     * @param historical (optional) When passed, returns the historical records of the pool/vault TVL
+     * @returns an object or array of objects containing the TVL and timestamp
+     */
     async getVaultTvl({ vault, chainId, historical, }) {
         if (!this.authorized)
             throw new Error('Not authorized.');
@@ -724,6 +958,12 @@ class AugustVaults extends core_1.AugustBase {
             historical: historical,
         });
     }
+    /**
+     * @function getYieldLastRealizedOn gets the timestamp when yield was last realized for a vault
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+     */
     async getYieldLastRealizedOn({ vault, chainId, }) {
         const rpcUrl = chainId
             ? this.providers?.[chainId]
@@ -740,6 +980,27 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Gets borrower health-factor data for vaults on a chain, optionally
+     * scoped to a single vault.
+     *
+     * Pass `vault` whenever the caller knows which pool it cares about —
+     * this skips the all-vaults cross-chain fanout and only reads the loans
+     * for that one pool. The response map is keyed by **lowercased** vault
+     * address; look entries up with `address.toLowerCase()`.
+     *
+     * Individual loan failures (bad/test loan contracts, unrecognized
+     * borrowers) are isolated and logged rather than rejecting the batch.
+     *
+     * @param chainId Optional chain to scope the read to. When omitted,
+     *   iterates the SDK's configured providers and returns the flattened
+     *   list (legacy shape — prefer passing a chain).
+     * @param vault Optional vault address. When provided alongside
+     *   `chainId`, only that vault's data is fetched.
+     * @returns When `chainId` is set, an object map of lowercased vault
+     *   address → array of borrower-health-factor rows. When `chainId` is
+     *   omitted, a flat array (legacy behavior, kept for backward compat).
+     */
     async getVaultBorrowerHealthFactor(chainId, vault) {
         if (chainId) {
             const health_factors = await (0, getters_1.getHealthFactorOfBorrowersByVault)({
@@ -769,6 +1030,11 @@ class AugustVaults extends core_1.AugustBase {
         }));
         return health_factors.flat();
     }
+    /**
+     * @function getUserPoints fetches user points from the backend API
+     * @param userAddress User wallet address
+     * @returns Points data from the backend API
+     */
     async getUserPoints(userAddress) {
         const { getUserPoints } = await Promise.resolve().then(() => __importStar(require('./getters')));
         return await getUserPoints({
@@ -782,6 +1048,22 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Register a user for the points program, authenticated by a wallet signature.
+     *
+     * The caller produces a personal_sign signature over a canonical message
+     * built from these primitives — see `registerUserForPoints` in
+     * `./getters` for the exact template and a worked example.
+     *
+     * @param userAddress EVM wallet address being registered.
+     * @param referrerAddress Optional referrer EVM address.
+     * @param chainId Chain on which the wallet signed; powers the EIP-1271
+     *   fallback for smart-contract wallets and pins the signature cross-chain.
+     * @param signature 0x-prefixed hex personal_sign signature over the canonical message.
+     * @param nonce Single-use random string (8–128 chars).
+     * @param expiry Unix seconds; must be in the future, within the backend's TTL.
+     * @returns Raw `Response` from the backend.
+     */
     async registerUserForPoints(userAddress, referrerAddress, chainId, signature, nonce, expiry) {
         const { registerUserForPoints } = await Promise.resolve().then(() => __importStar(require('./getters')));
         return await registerUserForPoints({
@@ -800,6 +1082,11 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * @function fetchPointsLeaderboard fetches the points leaderboard data
+     * @param params Optional parameters for pagination and sorting
+     * @returns Leaderboard response data
+     */
     async fetchPointsLeaderboard(params) {
         const { fetchPointsLeaderboard } = await Promise.resolve().then(() => __importStar(require('./getters')));
         return await fetchPointsLeaderboard({
@@ -813,6 +1100,18 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Get annualized APY metrics for a vault.
+     *
+     * Supported Vaults: cUSDO, tETH, wstETH, rsETH
+     *
+     * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
+     * These fields will be removed on 2026-01-01.
+     * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+     *
+     * @param vault Vault address
+     * @returns Annualized APY data including liquidity APY
+     */
     async getVaultAnnualizedApy(vault) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
@@ -831,6 +1130,11 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Get summary data for a vault (name, type, chain, recent returns).
+     * @param vault Vault address
+     * @returns Vault summary data
+     */
     async getVaultSummary(vault) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
@@ -849,6 +1153,12 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Get withdrawal summary and pending queue for a vault.
+     * @param vault Vault address
+     * @param chainId Chain ID (will be converted to chain name)
+     * @returns Withdrawal summary and pending queue
+     */
     async getVaultWithdrawals(vault, chainId) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
@@ -869,6 +1179,13 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Fetch pending redemptions for a vault with liquidity analysis.
+     * @param vault - Vault contract address
+     * @param pastDays - Number of past days to include (default 7, min 1, max 30)
+     * @param futureDays - Number of future days to include (default 14, min 1, max 30)
+     * @returns Pending redemptions grouped by date with liquidity summary
+     */
     async getVaultPendingRedemptions({ vault, pastDays, futureDays, }) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
@@ -888,6 +1205,13 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Preview the amount of assets that would be received for redeeming shares (queued redemption).
+     * @param vault Vault contract address
+     * @param sharesAmount Amount of shares to redeem (human-readable, raw bigint, or string)
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns The amount of assets as INormalizedNumber { normalized, raw }
+     */
     async previewRedemption({ vault, sharesAmount, chainId, }) {
         const rpcUrl = chainId
             ? this.providers?.[chainId]
@@ -901,6 +1225,28 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Get all withdrawal requests for a vault with deterministic status tracking.
+     *
+     * Matches requests to processed events by `(receiver, claimableDate)` tuple.
+     *
+     * **Status values:**
+     * - `'processed'` — Matching `WithdrawalProcessed` event found on-chain.
+     * - `'ready_to_claim'` — Claimable date has passed, no processed event found yet.
+     * - `'pending'` — Claimable date is still in the future.
+     *
+     * **Lookback window:** Processed events are fetched from on-chain logs, which
+     * only cover a finite block range. Requests whose claimable date is older than
+     * this window with no matching processed event are excluded (assumed already
+     * processed). Use `lookbackBlocks` to widen or narrow the scan range.
+     *
+     * @param vault - Vault contract address
+     * @param receiver - Optional receiver address to filter by
+     * @param lookbackBlocks - Optional on-chain log lookback window in blocks.
+     *   Defaults to chain-specific value (e.g. 150,000 for Ethereum, 3,456,000 for Monad).
+     * @param chainId - Optional chain id for the vault address
+     * @returns Array of withdrawal requests with status and claimable dates
+     */
     async getWithdrawalRequestsWithStatus(vault, receiver, lookbackBlocks, chainId) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
@@ -923,9 +1269,23 @@ class AugustVaults extends core_1.AugustBase {
             },
         });
     }
+    /**
+     * Redeem vault shares for an underlying asset via instant redemption (RWA subaccount).
+     * Resolves the vault address to the RwaRedeemSubaccount internally.
+     * Handles vault share approval automatically.
+     * @param signer - Signer / wallet object
+     * @param vault - Vault contract address
+     * @param asset - Redeemable asset address (e.g. USDC, USDT)
+     * @param amount - Amount of vault shares to redeem
+     * @param minOut - Minimum output amount in output asset units (slippage protection)
+     * @param chainId - Optional chain ID (uses active network if not provided)
+     * @param wait - Wait for transaction confirmation
+     * @returns transaction hash
+     */
     async rwaRedeemAsset(signer, { vault, asset, amount, minOut, chainId, wait, }) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
+        // Fetch vault data to resolve subaccount address and decimals
         const vaultData = await (0, getters_1.getVault)({
             vault,
             loans: false,
@@ -945,6 +1305,7 @@ class AugustVaults extends core_1.AugustBase {
             throw new Error(`Vault ${vault} does not support instant redemption.`);
         }
         const { subaccountAddress, redeemableAssets } = vaultData.instant_redeem_config;
+        // Resolve output asset decimals from config
         const redeemableAsset = redeemableAssets.find((a) => a.address.toLowerCase() === asset.toLowerCase());
         if (!redeemableAsset) {
             throw new Error(`Asset ${asset} is not redeemable for vault ${vault}.`);
@@ -961,12 +1322,22 @@ class AugustVaults extends core_1.AugustBase {
             wait,
         });
     }
+    /**
+     * Preview the output amount for an RWA instant redemption.
+     * Resolves the vault address to the RwaRedeemSubaccount internally.
+     * @param vault - Vault contract address
+     * @param asset - Redeemable asset address (e.g. USDC, USDT)
+     * @param amount - Amount of vault shares to preview
+     * @param chainId - Optional chain ID (uses active network if not provided)
+     * @returns normalized number of the expected output amount (in output asset decimals)
+     */
     async previewRwaRedemption({ vault, asset, amount, chainId, }) {
         if (!vault)
             throw new Error('Vault address parameter is undefined.');
         const rpcUrl = chainId
             ? this.providers?.[chainId]
             : this.activeNetwork.rpcUrl;
+        // Fetch vault data to resolve subaccount address and decimals
         const vaultData = await (0, getters_1.getVault)({
             vault,
             loans: false,
@@ -986,6 +1357,7 @@ class AugustVaults extends core_1.AugustBase {
             throw new Error(`Vault ${vault} does not support instant redemption.`);
         }
         const { subaccountAddress, redeemableAssets } = vaultData.instant_redeem_config;
+        // Resolve output asset decimals from config
         const redeemableAsset = redeemableAssets.find((a) => a.address.toLowerCase() === asset.toLowerCase());
         if (!redeemableAsset) {
             throw new Error(`Asset ${asset} is not redeemable for vault ${vault}.`);