@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/modules/vaults/getters.js

@@ -84,6 +84,31 @@ const date_utils_1 = require("./utils/date-utils");
 const call_data_decoder_1 = require("./utils/call-data-decoder");
 const deposits_1 = require("../../services/layerzero/deposits");
 const redeems_1 = require("../../services/layerzero/redeems");
+/**
+ * Vault Data Getters
+ *
+ * Main query functions for vault data across chains:
+ * - getVault: Comprehensive vault details with loans/allocations
+ * - getVaultLoans: Active loan data with on-chain enrichment
+ * - getVaultAllocations: DeFi/CeFi/OTC allocation breakdowns
+ * - getVaultAvailableRedemptions: Claimable redemption requests
+ * - getVaultRedemptionHistory: Historical redemption data
+ * - getVaultPositions: User positions across vaults
+ * - getVaultApy: @deprecated Current and historical APY data
+ * - getRewardsStakingPositions: Staking positions and rewards
+ * - getVaultTvl: Current and historical TVL
+ * - getVaultHistoricalTimeseries: Time series data for vault metrics
+ */
+/**
+ * Fetch comprehensive vault data including on-chain state and backend metadata.
+ * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
+ * Optionally enriches with loan and allocation data.
+ * @param vault Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
+ * @param loans Include active loan data
+ * @param allocations Include DeFi/CeFi allocation breakdowns
+ * @param options RPC and service configuration
+ * @returns Complete vault object with optional enrichments
+ */
 async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, }) {
     let returnedVault;
     try {
@@ -116,6 +141,8 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
         core_1.Logger.log.error('getVault', err, { vault });
         throw new Error(`#getVault::${vault}: ${err?.message}`);
     }
+    // Loans/allocations enrichment is only supported for EVM vaults.
+    // Non-EVM vaults already include empty defaults.
     const isEvmVault = returnedVault.version !== 'sol-0' &&
         returnedVault.version !== 'stellar-0' &&
         returnedVault.version !== 'sui-0';
@@ -161,19 +188,25 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
     }
     return returnedVault;
 }
+/**
+ * Vault Loans
+ */
 async function getVaultLoans(vault, options) {
+    // sanitize
     const vaultAddress = typeof vault === 'string' ? vault : vault.address;
     const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress, options?.headers))?.[0];
     const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
     if (vaultVersion !== 'evm-0')
-        return [];
+        return []; // only evm-0 uses subaccount loans
     try {
         let poolTotalSupply;
         let poolDecimals;
         const chainId = options?.chainId || tokenizedVault?.chain;
         const provider = (0, core_1.createProvider)(options.rpcUrl);
         const tokenizedVaultLoans = await (0, core_1.fetchTokenizedVaultLoans)(vaultAddress, chainId);
+        // if user passed IAddress or a full IVault
         if (typeof vault === 'string') {
+            // fetch necessary data
             const poolContract = (0, core_1.createContract)({
                 provider,
                 address: vaultAddress,
@@ -190,14 +223,21 @@ async function getVaultLoans(vault, options) {
             poolTotalSupply = vault.totalSupply.raw;
             poolDecimals = vault.decimals;
         }
+        // fetch and format all the loans
         const newLoans = (await Promise.all((Array.isArray(tokenizedVaultLoans) ? tokenizedVaultLoans : [])?.map(async (l) => {
+            // variables
             const borrower = l.borrower;
+            // calculate allocation
             const allocation = l.principal_amount /
                 Number((0, ethers_1.formatUnits)(poolTotalSupply, poolDecimals));
+            // get august loan fee from oracle
             const loanFeeRate = await (0, core_1.getLoanOracleFeeRate)(provider, 'LOAN.REPAY.INTERESTS', l.address, chainId);
+            // calculate loan level apr
             const loanApr = Number(l.apr || 0) / 100;
             const loanAprAfterFees = loanApr * (1 - loanFeeRate / 100);
+            // determine if capital is deployed
             const isIdleCapital = core_1.IDLE_CAPITAL_BORROWER_ADDRESS.includes(borrower);
+            // build new obj
             const newLoanObj = {
                 vault: vaultAddress,
                 address: l.address,
@@ -228,7 +268,11 @@ async function getVaultLoans(vault, options) {
         throw new Error(`#getVaultLoans::${vault}:${e?.message}`);
     }
 }
+/**
+ * Vault Subaccount Loans
+ */
 async function getVaultSubaccountLoans(vault, options) {
+    // sanitize
     const vaultAddress = typeof vault === 'string' ? vault : vault.address;
     const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress, options?.headers))?.[0];
     const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
@@ -240,7 +284,9 @@ async function getVaultSubaccountLoans(vault, options) {
         const chainId = options?.chainId || tokenizedVault?.chain;
         const provider = (0, core_1.createProvider)(options.rpcUrl);
         const tokenizedVaultLoans = await (0, core_1.fetchTokenizedVaultSubaccountLoans)(vaultAddress, chainId);
+        // if user passed IAddress or a full IVault
         if (typeof vault === 'string') {
+            // fetch necessary data
             const poolContract = (0, core_1.createContract)({
                 provider,
                 address: vaultAddress,
@@ -257,14 +303,21 @@ async function getVaultSubaccountLoans(vault, options) {
             poolTotalSupply = vault.totalSupply.raw;
             poolDecimals = vault.decimals;
         }
+        // fetch and format all the loans
         const newLoans = (await Promise.all((Array.isArray(tokenizedVaultLoans) ? tokenizedVaultLoans : [])?.map(async (l) => {
+            // variables
             const borrower = l.borrower;
+            // calculate allocation
             const allocation = l.principal_amount /
                 Number((0, ethers_1.formatUnits)(poolTotalSupply, poolDecimals));
+            // get august loan fee from oracle
             const loanFeeRate = await (0, core_1.getLoanOracleFeeRate)(provider, 'LOAN.REPAY.INTERESTS', l.address, chainId);
+            // calculate loan level apr
             const loanApr = Number(l.apr || 0) / 100;
             const loanAprAfterFees = loanApr * (1 - loanFeeRate / 100);
+            // determine if capital is deployed
             const isIdleCapital = core_1.IDLE_CAPITAL_BORROWER_ADDRESS.includes(borrower);
+            // build new obj
             const newLoanObj = {
                 vault: vaultAddress,
                 address: l.address,
@@ -295,7 +348,19 @@ async function getVaultSubaccountLoans(vault, options) {
         throw new Error(`#getVaultSubaccountLoans::${vault}:${e?.message}`);
     }
 }
+/**
+ * Vault Allocations
+ */
+/**
+ * Fetch comprehensive vault asset allocation breakdown.
+ * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
+ * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+ * @param vault Vault address
+ * @param options RPC configuration
+ * @returns Detailed allocation data with exposure categorization
+ */
 async function getVaultAllocations(vault, options) {
+    // to be used on upshift UI
     const protocolExposure = [];
     const tokenExposure = [];
     let cefiExposure = [];
@@ -322,8 +387,10 @@ async function getVaultAllocations(vault, options) {
                 : null;
         },
     };
+    // Determine wallets to fetch allocation responses from
     let uniqueBorrowers = [];
     const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
+    // fetch all vault unique subaccounts/loan borrowers
     try {
         const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
         if (vaultVersion === 'evm-0') {
@@ -341,25 +408,30 @@ async function getVaultAllocations(vault, options) {
     catch (e) {
         core_1.Logger.log.error('getVaultAllocations:borrowers', e);
     }
+    // if hardcoded subaccount exists for vault, use that
     const hardcodedSubaccount = Object.values(core_1.VAULT_ALLOCATION_SUBACCOUNTS).find((entry) => entry.address.toLowerCase() === vault.toLowerCase() && !entry.useDebank);
     if (hardcodedSubaccount) {
         const debankRes = await (0, debank_1.fetchDebankResponse)(hardcodedSubaccount.subaccount);
         if (debankRes === false) {
             debankErr = true;
         }
+        // pull data from debank results
         (0, debank_1.parseVaultLevelDebank)(debankRes, protocolExposure, tokenExposure, hardcodedSubaccount.subaccount, exposurePerCategory, netValue);
         unfilteredTokens = debankRes?.subaccount?.tokens;
         const debankPerLoan = (0, debank_1.parseLoanLevelDebank)(debankRes);
         defiPerBorrower[hardcodedSubaccount.subaccount] = debankPerLoan;
     }
     else {
+        // Fetch DeBank data for all subaccounts in a single request (EVM only)
         if ((0, core_1.getAddressChainType)(vault) === 'evm') {
             const vaultDebankData = await (0, debank_1.fetchVaultDebankResponse)(vault, options?.headers);
             if (vaultDebankData === false) {
                 debankErr = true;
             }
             else {
+                // Process DeBank data for each subaccount
                 for (const [subaccountAddress, subaccountData] of Object.entries(vaultDebankData)) {
+                    // Skip if subaccount has an error
                     if ('error' in subaccountData) {
                         core_1.Logger.log.error('getVaultAllocations:debank:subaccount', {
                             subaccountAddress,
@@ -367,6 +439,7 @@ async function getVaultAllocations(vault, options) {
                         });
                         continue;
                     }
+                    // Transform to match existing parser format: { subaccount: { positions, app_positions, tokens } }
                     const debankRes = {
                         subaccount: {
                             positions: subaccountData.positions || [],
@@ -381,6 +454,8 @@ async function getVaultAllocations(vault, options) {
                 }
             }
         }
+        // Fetch portfolio data for non-EVM borrowers (EVM handled by fetchVaultDebankResponse above).
+        // CeFi and OTC fetches below run for ALL borrowers regardless of chain type.
         for (const borrower of uniqueBorrowers) {
             const chainType = (0, core_1.getAddressChainType)(borrower);
             if (chainType !== 'evm') {
@@ -414,6 +489,7 @@ async function getVaultAllocations(vault, options) {
                     debankErr = true;
                 }
             }
+            // fetch cefi_positions
             try {
                 const cefiResponse = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.cefi(borrower), { headers: options?.headers });
                 if (cefiResponse.status !== 200) {
@@ -430,6 +506,7 @@ async function getVaultAllocations(vault, options) {
             catch (e) {
                 core_1.Logger.log.error('getVaultAllocations:cefi', e, { borrower });
             }
+            // fetch otc_positions
             try {
                 const otcResponse = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.otc_positions(borrower), { headers: options?.headers });
                 if (otcResponse.status !== 200) {
@@ -466,11 +543,14 @@ async function getVaultAllocations(vault, options) {
         defiPerBorrower,
         exposurePerCategory,
         netValue: netValue.value,
+        // this would be the debank token response field without any parsing. Different from
+        // tokens. Could use a better name tho
         unfilteredTokens: unfilteredTokens,
     };
 }
 async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
     try {
+        // Stellar vaults don't support on-chain redemptions yet
         if ((0, utils_3.isStellarAddress)(vault)) {
             core_1.Logger.log.warn('getVaultAvailableRedemptions', `Available redemptions is not yet supported for Stellar vaults: ${vault}`);
             return {
@@ -482,6 +562,7 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                 }),
             };
         }
+        // setup
         const provider = (0, core_1.createProvider)(options.rpcUrl);
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers, false, false))?.[0];
         if (!tokenizedVault) {
@@ -496,8 +577,10 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                 }),
             };
         }
+        // version split logic
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
         let decimals;
+        // Use ABI_LENDING_POOL_V2 for both versions as it has the methods we need
         const vaultContract = (0, core_1.createContract)({
             address: vault,
             abi: abis_1.ABI_LENDING_POOL_V2,
@@ -512,9 +595,11 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
         const ld = await vaultContract.lagDuration();
         const lagDuration = Number(ld);
         const { withdrawalRequesteds, withdrawalProcesseds } = await (0, subgraph_1.getSubgraphAllWithdrawals)(vault, provider);
+        // format
         const availableRedemptions = [];
         const pendingRedemptions = [];
         for (const ev of withdrawalRequesteds) {
+            // ensure event is defined
             if (!ev || typeof ev !== 'object') {
                 core_1.Logger.log.warn('getVaultAvailableRedemptions', `Skipping invalid event: ${ev}`);
                 continue;
@@ -523,11 +608,13 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
             let day;
             let year;
             if (version === 'evm-2') {
+                // Use UTC-based computeClaimableDate to mirror contract logic exactly
                 const claimable = (0, date_utils_1.computeClaimableDate)(Number(ev.timestamp_), lagDuration);
                 year = claimable.year;
                 month = claimable.month;
                 day = claimable.day;
             }
+            // Validate required event properties
             if (!ev.year || !ev.month || !ev.day || !ev.receiverAddr) {
                 if (version !== 'evm-2') {
                     core_1.Logger.log.warn('getVaultAvailableRedemptions', `Skipping event with missing required properties: ${ev}`);
@@ -545,9 +632,12 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
             const fullDate = version === 'evm-2'
                 ? new Date(Date.UTC(year, month - 1, day))
                 : new Date(Number(ev.year), Number(ev.month) - 1, Number(ev.day));
+            // Match request to processed event using deterministic UTC date key
             const requestDateKey = version === 'evm-2'
                 ? (0, date_utils_1.formatDateKey)(year, month, day)
                 : (0, date_utils_1.formatDateKey)(Number(ev.year), Number(ev.month), Number(ev.day));
+            // NOTE: evm-2 subgraph does not emit WithdrawalProcessed events, so matching
+            // relies on timestamp-based date comparison for evm-2 (deterministic for evm-1).
             const foundRedemptionAgainstClaim = withdrawalProcesseds.find((h) => {
                 const proc = h;
                 if (proc.receiverAddr !== ev.receiverAddr)
@@ -562,9 +652,11 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                 return procKey === requestDateKey;
             });
             if (wallet && (0, ethers_1.isAddress)(wallet)) {
+                // check if connected users address
                 if (ev?.receiverAddr?.toLowerCase() === wallet.toLowerCase()) {
                     const alreadyRedeemed = version === 'evm-2'
                         ? withdrawalProcesseds.find((red) => {
+                            // Match by receiver + UTC date key (deterministic)
                             if (red.receiverAddr.toLowerCase() !== wallet.toLowerCase()) {
                                 return false;
                             }
@@ -576,9 +668,11 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                             BigInt(red.month.raw) === BigInt(ev.month) &&
                             BigInt(red.year.raw) === BigInt(ev.year));
                     if (!(foundRedemptionAgainstClaim && alreadyRedeemed)) {
+                        // double check if user has already claimed
                         try {
                             switch (version) {
                                 case 'evm-2': {
+                                    // this is to avoid edge case where old withdrawal A is already redeemed but we are now looking at withdrawal B that is not yet pending
                                     if (alreadyRedeemed) {
                                         const index = withdrawalProcesseds.findIndex((item) => item.id === alreadyRedeemed.id);
                                         if (index !== -1) {
@@ -586,12 +680,16 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                                         }
                                     }
                                     if (!alreadyRedeemed) {
+                                        // Recompute claimable date (includes lag + 300s manipulation window) to determine if claimable now
                                         const claimable = (0, date_utils_1.computeClaimableDate)(Number(ev.timestamp_), lagDuration);
                                         const pendingCondition = (0, date_utils_1.isClaimableNow)(claimable.epoch, Math.floor(Date.now() / 1000));
                                         if (pendingCondition) {
+                                            // Has passed lag duration - check if claim is not settled before adding to pending
                                             try {
                                                 const burnableAmount = (await vaultContract?.getBurnableAmountByReceiver?.(BigInt(year), BigInt(month), BigInt(day), (0, ethers_1.getAddress)(ev.receiverAddr))) || BigInt(0);
                                                 const claimAmount = BigInt(ev.shares) || BigInt(0);
+                                                // If burnableAmount >= claimAmount, claim hasn't been settled by processAllClaims
+                                                // Only add to pending if it's still unsettled
                                                 if (burnableAmount >= claimAmount) {
                                                     pendingRedemptions.push({
                                                         id: ev.transactionHash_ || ev.id,
@@ -610,9 +708,11 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                                             }
                                             catch (burnableError) {
                                                 core_1.Logger.log.warn('getVaultAvailableRedemptions', `Failed to check burnable amount for pending redemption: ${burnableError}`);
+                                                // If check fails, don't add to pending to be safe
                                             }
                                         }
                                         else {
+                                            // Hasn't passed lag duration - add to available redemptions only
                                             availableRedemptions.push({
                                                 id: ev.transactionHash_ || ev.id,
                                                 hash: ev.transactionHash_ || ev.id,
@@ -633,15 +733,19 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                                 default: {
                                     const trueClaimableAmount = await vaultContract?.getClaimableAmountByReceiver?.(BigInt(ev.year), BigInt(ev.month), BigInt(ev.day), (0, ethers_1.getAddress)(wallet));
                                     if (trueClaimableAmount > BigInt(0)) {
+                                        // Use computeClaimableDate for UTC-correct date with lag
                                         const v1Claimable = (0, date_utils_1.computeClaimableDate)(Number(ev.timestamp_), lagDuration);
                                         const pendingCondition = (0, date_utils_1.isClaimableNow)(v1Claimable.epoch, Math.floor(Date.now() / 1000));
                                         if (pendingCondition) {
+                                            // Has passed lag duration - check if claim is not settled before adding to pending
                                             try {
                                                 year = v1Claimable.year;
                                                 month = v1Claimable.month;
                                                 day = v1Claimable.day;
                                                 const burnableAmount = (await vaultContract?.getBurnableAmountByReceiver?.(BigInt(year), BigInt(month), BigInt(day), (0, ethers_1.getAddress)(ev.receiverAddr))) || BigInt(0);
                                                 const claimAmount = trueClaimableAmount || BigInt(0);
+                                                // If burnableAmount >= claimAmount, claim hasn't been settled by processAllClaims
+                                                // Only add to pending if it's still unsettled
                                                 if (burnableAmount >= claimAmount) {
                                                     pendingRedemptions.push({
                                                         id: ev.transactionHash_ || ev.id,
@@ -660,9 +764,11 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
                                             }
                                             catch (burnableError) {
                                                 core_1.Logger.log.warn('getVaultAvailableRedemptions', `Failed to check burnable amount for pending redemption: ${burnableError}`);
+                                                // If check fails, don't add to pending to be safe
                                             }
                                         }
                                         else {
+                                            // Hasn't passed lag duration - add to available redemptions only
                                             availableRedemptions.push({
                                                 id: ev.transactionHash_ || ev.id,
                                                 hash: ev.transactionHash_ || ev.id,
@@ -733,10 +839,12 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, }) {
 }
 async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, options, }) {
     try {
+        // Stellar vaults: no on-chain redemption history yet
         if ((0, utils_3.isStellarAddress)(vault)) {
             core_1.Logger.log.warn('getVaultRedemptionHistory', `Redemption history is not yet supported for Stellar vaults: ${vault}`);
             return [];
         }
+        // setup
         const provider = (0, core_1.createProvider)(options.rpcUrl);
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers, false, false))?.[0];
         if (!tokenizedVault) {
@@ -746,16 +854,18 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
         const chainId = tokenizedVault.chain;
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
         const isV2 = version === 'evm-2';
+        // Use correct ABI based on vault version — different WithdrawalProcessed event signatures
         const vaultAbi = isV2 ? TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2 : abis_1.ABI_LENDING_POOL_V2;
         const poolContract = (0, core_1.createContract)({
             address: vault,
             abi: vaultAbi,
             provider,
         });
+        // query getLogs
         const currentBlock = await provider.getBlockNumber();
         const blockSkip = (0, core_1.determineBlockSkipInternal)(chainId);
         const cutoffBlock = currentBlock - (lookbackBlocks ?? (0, core_1.determineBlockCutoff)(chainId));
-        const BATCH_SIZE = 20;
+        const BATCH_SIZE = 20; // Max concurrent RPC requests per batch
         core_1.Logger.log.info('getVaultRedemptionHistory', {
             vault,
             version,
@@ -766,6 +876,7 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
             blockSkip,
             totalRangeBlocks: currentBlock - cutoffBlock,
         });
+        // Build all query ranges
         const ranges = [];
         let endBlock = currentBlock;
         while (endBlock >= cutoffBlock) {
@@ -779,6 +890,11 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
             firstRange: ranges[0],
             lastRange: ranges[ranges.length - 1],
         });
+        // Execute in batches to avoid RPC rate limits on high-block-count chains.
+        // Use allSettled + explicit throw so a chunk failure surfaces to the caller
+        // instead of silently returning an empty result (which used to corrupt
+        // `getWithdrawalRequestsWithStatus` into reporting `ready_to_claim` for
+        // requests that were already processed).
         const logs = [];
         for (let i = 0; i < ranges.length; i += BATCH_SIZE) {
             const batch = ranges.slice(i, i + BATCH_SIZE);
@@ -799,6 +915,8 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
             const batchLogs = batchResults.flatMap((r) => r.status === 'fulfilled' ? r.value : []);
             logs.push(...batchLogs);
         }
+        // evm-1: WithdrawalProcessed(uint256 assetsAmount, uint256 processedOn, address receiverAddr, uint256 requestedOn)
+        // evm-2: WithdrawalProcessed(uint256 assetsAmount, address indexed receiverAddr)
         const iface = new ethers_1.ethers.Interface(isV2
             ? [
                 'event WithdrawalProcessed(uint256 assetsAmount, address indexed receiverAddr)',
@@ -806,7 +924,9 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
             : [
                 'event WithdrawalProcessed(uint256 assetsAmount, uint256 processedOn, address receiverAddr, uint256 requestedOn)',
             ]);
+        // get pool decimals
         const decimals = await (0, core_1.getDecimals)(provider, vault);
+        // For evm-2 events (no timestamps in event), fetch block timestamps
         let blockTimestamps;
         if (isV2 && logs.length > 0) {
             const uniqueBlocks = [...new Set(logs.map((l) => l.blockNumber))];
@@ -817,6 +937,7 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
                     blockTimestamps.set(block.number, block.timestamp);
             });
         }
+        // format — iterate logs directly to preserve transactionHash
         const redemptions = [];
         logs.forEach((log) => {
             const ev = iface.parseLog(log);
@@ -831,7 +952,7 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
                     receiver: receiverAddr,
                     amount: (0, core_1.toNormalizedBn)(assetsAmount, decimals),
                     processed: blockDate,
-                    requested: new Date(0),
+                    requested: new Date(0), // evm-2 event has no requestedOn field; epoch 0 is a sentinel for "unknown"
                     vault,
                     transactionHash: log.transactionHash,
                 };
@@ -860,16 +981,25 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
         return redemptions;
     }
     catch (e) {
+        // Log loudly and re-throw. Previously this caught all errors and returned
+        // [], which silently corrupted callers (notably getWithdrawalRequestsWithStatus,
+        // which would then report `ready_to_claim` for already-processed requests).
+        // Returning [] is reserved for the explicit early returns inside the try
+        // (unsupported chains, vault not in backend) — not for unexpected failures.
         core_1.Logger.log.error('getVaultRedemptionHistory', e, { vault, wallet });
         throw e;
     }
 }
+/**
+ * Vault Positions
+ */
 async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, }) {
     try {
         const tokenizedVaults = await (0, core_1.fetchTokenizedVault)(vault ? vault : undefined, options?.headers, false, false);
         if (!tokenizedVaults || tokenizedVaults.length === 0) {
             return [];
         }
+        // check if there are redemptions available or if you stake in this pool
         function renderStatus(_redemptions, _balance) {
             if (_redemptions?.length)
                 return 'REDEEM';
@@ -879,10 +1009,18 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
         }
         const promises = await Promise.all(tokenizedVaults.map(async (v) => {
             try {
+                // @solana: skip if not solana address
                 if (utils_2.SolanaUtils.isSolanaAddress(v.address)) {
+                    // Default decimals: backend metadata, then SDK fallback. The mint's
+                    // own decimals (read below) override this once we have a real
+                    // tokenAmount response.
                     const fallbackShareDecimals = v.solana_vault_metadata?.deposit_token_decimals ??
                         SolanaConstants.fallbackDecimals;
                     let balance = (0, core_1.toNormalizedBn)(0, fallbackShareDecimals);
+                    // Defensive: without a Solana adapter we can't fetch on-chain
+                    // state. The outer filter in modules/vaults/main.ts already gates
+                    // on `this.solanaService`, so this is a belt-and-suspenders guard
+                    // for any external caller that constructs `options` by hand.
                     if (utils_2.SolanaUtils.isSolanaAddress(solanaWallet) &&
                         options.solanaService) {
                         const vaultProgramId = utils_2.SolanaUtils.resolveProgramId(String(v.address), v.solana_vault_metadata);
@@ -890,12 +1028,23 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                         const vaultState = vaultStateRes?.vaultState;
                         const { shareMint } = vaultState ?? { shareMint: null };
                         if (shareMint) {
+                            // Always use the raw helper — it returns the on-chain u64
+                            // string and the mint's true decimals. The legacy `uiAmount`
+                            // (JS number) path lost precision and silently encoded `.raw`
+                            // against 18 decimals when fed back through `toNormalizedBn`
+                            // without a decimals argument, which broke every downstream
+                            // BigInt consumer (redemptions, max actions, allowances).
                             const raw = await options.solanaService.fetchUserShareBalanceRaw(solanaWallet, shareMint);
                             const decimals = raw.decimals ?? fallbackShareDecimals;
                             balance = (0, core_1.toNormalizedBn)(BigInt(raw.amount), decimals);
                         }
                     }
                     return {
+                        // Mirror the Stellar branch — return the backend's `v.address`,
+                        // not the outer `vault` parameter (which can be undefined for
+                        // multi-vault calls). No `as IAddress` cast: Solana base58 is
+                        // not 0x-hex; the IAddress typing across non-EVM positions is a
+                        // known wart documented in IVaultPosition.
                         vault: v.address,
                         status: renderStatus([], balance),
                         availableRedemptions: [],
@@ -913,6 +1062,9 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                             balance = (0, core_1.toNormalizedBn)(BigInt(position.shares), position.decimals);
                         }
                         else if (position) {
+                            // decimals() read failed: trusting the fallback (7) would
+                            // mis-scale the balance for ERC4626 offset vaults (AUGUST-6381).
+                            // Show zero rather than a confidently-wrong value.
                             core_1.Logger.log.warn('getVaultPositions', 'Stellar decimals() unresolved — refusing to scale balance with fallback decimals (showing zero)', { vault: v.address, wallet: stellarWallet });
                         }
                         else {
@@ -922,6 +1074,7 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                     else if (stellarWallet) {
                         core_1.Logger.log.warn('getVaultPositions', 'Invalid stellarWallet address format', { vault: v.address, stellarWallet });
                     }
+                    // Stellar vaults have no on-chain redemption queue yet — redeemable is always 0
                     return {
                         vault: v.address,
                         status: renderStatus([], balance),
@@ -931,14 +1084,18 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                         walletBalance: balance,
                     };
                 }
+                // create provider
                 const provider = (0, core_1.createProvider)(options.rpcUrl);
+                // version split logic
                 let decimals;
                 const version = (0, core_1.getVaultVersionV2)(v);
+                // Use ABI_LENDING_POOL_V2 as the common ABI for vault operations
                 const vaultContract = (0, core_1.createContract)({
                     provider,
                     abi: abis_1.ABI_LENDING_POOL_V2,
                     address: v.address,
                 });
+                // get vault metadata and balance based on version
                 let bal = BigInt(0);
                 if (version === 'evm-2') {
                     const receiptAddress = await (0, core_1.getReceiptTokenAddress)(provider, vault);
@@ -959,12 +1116,15 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                     }
                 }
                 const balance = (0, core_1.toNormalizedBn)(bal, decimals);
+                // check available redemptions
                 const { availableRedemptions, pendingRedemptions } = await getVaultAvailableRedemptions({
                     vault: v.address,
                     wallet,
                     options,
                 });
+                // get aggregate redemption amount
                 const aggregateAvailableRedemptions = availableRedemptions.reduce((acc, curr) => acc + BigInt(curr.amount.raw), BigInt(0));
+                // return obj
                 return {
                     vault,
                     status: renderStatus(availableRedemptions, balance),
@@ -998,10 +1158,14 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
         throw new Error(`#getVaultPositions::${vault}:${e?.message}`);
     }
 }
+/**
+ * @deprecated use getVaultHistoricalTimeseries instead
+ */
 async function getVaultApy({ vault, options, historical, }) {
     try {
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
+        // only looking for current apy
         if (!historical) {
             const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
             return [
@@ -1012,6 +1176,7 @@ async function getVaultApy({ vault, options, historical, }) {
             ];
         }
         else {
+            // historical apy
             function paramBuilder(params, baseUrl) {
                 if (!params)
                     return '';
@@ -1051,15 +1216,16 @@ async function getVaultApy({ vault, options, historical, }) {
     }
 }
 async function getRewardsStakingPositions({ rpcUrl, wallet, coinGeckoKey, }) {
-    const REWARDS_CHAIN = 43114;
-    const REWARDS_SYMBOL = 'AVAX';
-    const REWARDS_DECIMALS = 18;
-    const REWARDS_NAME = 'Avalanche';
+    const REWARDS_CHAIN = 43114; // avalanche
+    const REWARDS_SYMBOL = 'AVAX'; // avalanche
+    const REWARDS_DECIMALS = 18; // avalanche
+    const REWARDS_NAME = 'Avalanche'; // avalanche
     const APR_MULTIPLIER = 31536000;
     const UP_AUSD_SYMBOL = 'upAUSD';
     try {
         const provider = (0, core_1.createProvider)(rpcUrl);
         const chainId = await (0, core_1.getChainId)(provider);
+        // Validate chain has rewards distributor
         if (chainId !== REWARDS_CHAIN) {
             core_1.Logger.log.warn('getStakingPositions:unsupported_chain', chainId);
             return [];
@@ -1068,15 +1234,19 @@ async function getRewardsStakingPositions({ rpcUrl, wallet, coinGeckoKey, }) {
             core_1.Logger.log.warn('getStakingPositions:invalid_wallet', wallet);
             return [];
         }
+        // get reward distributor contract addresses
         const rewardDistributorAddresses = (0, core_1.REWARD_DISTRIBUTOR_ADDRESS)(chainId);
+        // loop through each reward distributor contract address
         const positions = await Promise.all(rewardDistributorAddresses.map(async (contract, i) => {
             const rewardContract = (0, core_1.createContract)({
                 address: contract,
                 provider: provider,
                 abi: abis_1.ABI_REWARD_DISTRIBUTOR,
             });
+            // get reward distributor metadata
             const totalStaked = await rewardContract.totalStaked();
             const rewardsPerSecond = await rewardContract.rewardsPerSecond();
+            // get staking token metadata
             const stakingTokenCalls = ['decimals', 'symbol', 'name', 'totalSupply'];
             const stakingTokenAddress = (await rewardContract.stakingToken());
             const stakingTokenContract = (0, core_1.createContract)({
@@ -1085,6 +1255,7 @@ async function getRewardsStakingPositions({ rpcUrl, wallet, coinGeckoKey, }) {
                 abi: abis_1.ABI_ERC20,
             });
             const [decimals, symbol, name] = await Promise.all(stakingTokenCalls.map((staking) => stakingTokenContract[staking]()));
+            // if wallet address is passed, pull user balance of staked tokens
             let balance;
             let earned;
             if (wallet) {
@@ -1092,12 +1263,15 @@ async function getRewardsStakingPositions({ rpcUrl, wallet, coinGeckoKey, }) {
                 balance = await rewardContract.balanceOf(formattedWallet);
                 earned = await rewardContract.earned(formattedWallet);
             }
+            // get appropriate token price
             const rewardTokenPriceInUsd = await (0, core_1.fetchTokenPrice)(REWARDS_SYMBOL, null, coinGeckoKey);
             const normalizedRewardTokenPrice = (0, core_1.toNormalizedBn)(rewardTokenPriceInUsd);
+            // normalize numbers
             const normalizedTotalStakedInPool = (0, core_1.toNormalizedBn)(totalStaked, decimals);
             const normalizedRedeemable = (0, core_1.toNormalizedBn)(earned, REWARDS_DECIMALS);
             const normalizedRewardsPerSecond = (0, core_1.toNormalizedBn)(rewardsPerSecond, REWARDS_DECIMALS);
             const normalizedTotalStakedBalance = (0, core_1.toNormalizedBn)(balance, decimals);
+            // calculate APR's
             const rewardTokenPriceToMultiply = symbol === UP_AUSD_SYMBOL
                 ? Number(normalizedRewardTokenPrice?.normalized)
                 : 1;
@@ -1151,12 +1325,15 @@ async function getVaultTvl({ vault, options, historical, }) {
     try {
         if (!vault)
             throw new Error('Vault input parameter is undefined.');
+        // Verify vault exists
         const _vaultExists = (await (0, core_1.fetchTokenizedVault)(vault))?.[0];
         if (!_vaultExists) {
             throw new Error(`Vault ${vault} not found in backend`);
         }
+        // only wanting current APR
         if (!historical) {
             const version = (0, core_1.getVaultVersionV2)(_vaultExists);
+            // Non-EVM early returns (no provider needed)
             if (version === 'sol-0') {
                 return [
                     {
@@ -1209,17 +1386,33 @@ async function getVaultTvl({ vault, options, historical, }) {
                     ];
                 }
             }
+            // const vaultRes = await getVault({
+            //   vault,
+            //   options,
+            //   loans: false,
+            //   allocations: false,
+            // });
+            // const returnObj = [
+            //   { value: vaultRes.totalSupply, timestamp: new Date().toISOString() },
+            // ];
+            // Logger.log.info('getVaultTvl:current', returnObj);
+            // return returnObj;
         }
         else {
+            // historical tvl
+            // check vault version early to guard non-EVM chains
             const version = (0, core_1.getVaultVersionV2)(_vaultExists);
             if (version === 'stellar-0' || version === 'sol-0') {
                 core_1.Logger.log.warn('getVaultTvl:historical', 'Historical TVL not supported for non-EVM vaults', { vault, version });
                 return [];
             }
+            // if no order is passed but inputParams are passed
             if (typeof historical !== 'undefined' && !historical.order)
                 historical.order = 'desc';
+            // days is default interval
             if (typeof historical !== 'undefined' && !historical.interval)
                 historical.interval = 'days';
+            // setup
             const provider = (0, core_1.createProvider)(options.rpcUrl);
             const vaultContract = (0, core_1.createContract)({
                 address: vault,
@@ -1244,6 +1437,8 @@ async function getVaultTvl({ vault, options, historical, }) {
                     break;
                 }
             }
+            // block trackback setup
+            // Get the latest finalized block to ensure all queried blocks are confirmed
             const finalizedBlock = await provider.getBlock('finalized');
             const finalizedTimestamp = finalizedBlock
                 ? finalizedBlock.timestamp * 1000
@@ -1253,19 +1448,26 @@ async function getVaultTvl({ vault, options, historical, }) {
             const startDate = historical.daysAgo
                 ? new Date(finalizedTimestamp - daysAgo)
                 : new Date(finalizedTimestamp);
-            const blocks = await dater.getEvery(historical.interval, startDate.toUTCString(), new Date(finalizedTimestamp).toUTCString());
+            const blocks = await dater.getEvery(historical.interval, // Period
+            startDate.toUTCString(), // Start date
+            new Date(finalizedTimestamp).toUTCString());
+            // order blocks array
             const orderedBlocks = historical.order === 'desc' ? (0, core_1.orderObjArrByDate)(blocks) : blocks;
+            // minimal ABI
             const totalAssetsHistorical = await (0, core_1.promiseSettle)(orderedBlocks?.map(async ({ block, date }) => {
+                // get totalAssets at said block
                 const totalAssetsAtBlock = await provider.call({
                     to: vaultContract,
                     data: new ethers_1.Interface(minAbi).encodeFunctionData(functionName, []),
                     blockTag: block,
                 });
+                // cover case when data returned is 0
                 if (totalAssetsAtBlock === '0x')
                     return {
                         timestamp: (0, core_1.dateToUnix)(new Date(date)),
                         value: (0, core_1.toNormalizedBn)(0, 0),
                     };
+                // decode back to readable
                 const readableTotalAssetsAtBlock = new ethers_1.Interface(minAbi).decodeFunctionResult(functionName, totalAssetsAtBlock);
                 return {
                     timestamp: (0, core_1.dateToUnix)(new Date(date)),
@@ -1281,9 +1483,27 @@ async function getVaultTvl({ vault, options, historical, }) {
         throw new Error(`Failed to fetch TVL for ${vault}: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Build the per-loan borrower / health-factor list for a single vault.
+ *
+ * Resilience: individual loan reads (`loanState()`, `borrower()`) and the
+ * per-borrower August backend call are isolated with `Promise.allSettled` and
+ * try/catch so one bad loan — a test loan whose address isn't a real contract,
+ * a borrower the backend doesn't recognize, an intermittent RPC error — drops
+ * that single row from the result instead of rejecting the whole batch. Failed
+ * rows are logged via `Logger.log.warn`; the loan is still returned with
+ * `health_factor: undefined` so callers can render an explicit empty state
+ * rather than a perpetual loading skeleton.
+ *
+ * @param vault Vault address to scope the fetch to.
+ * @param options Standard vault options — `rpcUrl` must point at `vault`'s chain.
+ * @returns Array of `IVaultBorrowerHealthFactor`, one entry per active loan.
+ */
 async function getVaultBorrowerHealthFactor({ vault, options, }) {
     const provider = (0, core_1.createProvider)(options.rpcUrl);
     const loans = await getVaultLoans(vault, options);
+    // Read each loan's on-chain state; drop loans whose RPC call fails so a
+    // single bad contract (e.g. a test loan address) can't sink the batch.
     const activeLoanResults = await Promise.allSettled(loans.map(async (l) => {
         const loanContract = (0, core_1.createContract)({
             provider,
@@ -1306,6 +1526,7 @@ async function getVaultBorrowerHealthFactor({ vault, options, }) {
         return undefined;
     })
         .filter((l) => l !== undefined);
+    // Same fault-tolerance for the per-loan borrower() read.
     const formattedSettled = await Promise.allSettled(activeLoans.map(async (l) => {
         const loanContract = (0, core_1.createContract)({
             provider,
@@ -1351,6 +1572,26 @@ async function getVaultBorrowerHealthFactor({ vault, options, }) {
     });
     return formattedLoansArray;
 }
+/**
+ * Aggregate borrower-health-factor data, optionally scoped to a single vault.
+ *
+ * - When `vault` is provided, only that vault's tokenized record is fetched
+ *   and only its loans are read. This is the path callers should use when
+ *   they already know which vault they care about — it skips the cross-chain
+ *   fanout entirely.
+ * - When `vault` is omitted, the function fetches every tokenized vault and
+ *   builds health factors for each, preserving the legacy behavior. Per-vault
+ *   failures are isolated with `Promise.allSettled` so one bad vault returns
+ *   an empty array instead of rejecting the whole map.
+ *
+ * The returned map is keyed by **lowercased** vault address so callers can
+ * look up entries without worrying about EIP-55 checksum casing in either the
+ * backend response or the caller's input.
+ *
+ * @param options Standard vault options — `rpcUrl` should match `vault`'s chain.
+ * @param vault Optional vault address to scope the fetch to.
+ * @returns Map of lowercased vault address → array of borrower-health-factor rows.
+ */
 async function getHealthFactorOfBorrowersByVault({ options, vault, }) {
     const vaults = vault
         ? ((await (0, core_1.fetchTokenizedVault)(vault, options?.headers)) ?? [])
@@ -1376,6 +1617,13 @@ async function getHealthFactorOfBorrowersByVault({ options, vault, }) {
     });
     return healthFactorsByPool;
 }
+/**
+ * Fetch user points from the backend API endpoint.
+ * This replaces client-side points calculation with server-side processing.
+ * @param userAddress User wallet address (EVM or Solana)
+ * @param options Request options including headers
+ * @returns Points data from the backend API
+ */
 async function getUserPoints({ userAddress, options, }) {
     try {
         if (!userAddress) {
@@ -1397,6 +1645,62 @@ async function getUserPoints({ userAddress, options, }) {
         throw new Error(`#getUserPoints::${userAddress}:${errorMessage}`);
     }
 }
+/**
+ * Register a user for the points program, authenticated by a wallet signature.
+ *
+ * The caller must obtain a personal_sign (EIP-191) signature over the
+ * canonical message template below — the backend reconstructs the same
+ * string from these fields and verifies the signature recovers to
+ * `userAddress`. Building the message client-side and server-side from the
+ * same primitives means a hostile client cannot show one message in the
+ * wallet prompt while submitting a different one for validation.
+ *
+ * Canonical message (`\n`-separated, no trailing newline):
+ *
+ * ```
+ * Upshift: register {userAddress.toLowerCase()}
+ * referrer: {referrerAddress.toLowerCase() || "none"}
+ * chain: {chainId}
+ * nonce: {nonce}
+ * expires: {expiry}
+ * ```
+ *
+ * @param userAddress EVM wallet address being registered. Must match the
+ *   signer that produced `signature`. Lowercased before being embedded in
+ *   the canonical message.
+ * @param referrerAddress Optional EVM address that referred this user.
+ *   Lowercased when embedded; the literal string `"none"` is used when
+ *   absent. Tampering with this field after signing produces 401.
+ * @param chainId Chain on which the wallet signed. For smart-contract wallets
+ *   (Safe etc.) this is the chain whose RPC the backend will use to run the
+ *   EIP-1271 `isValidSignature` check; for EOAs it still pins the signature
+ *   to a chain so it can't be replayed cross-chain. Must be one of the chains
+ *   Upshift supports (see backend `SUPPORTED_REGISTRATION_CHAINS`).
+ * @param signature `0x`-prefixed hex of the personal_sign signature over
+ *   the canonical message. Single-use: replays within ~10 min are rejected.
+ * @param nonce Caller-generated random string (8–128 chars). Pair with
+ *   `userAddress` to form the single-use key in the backend's nonce store.
+ * @param expiry Unix timestamp (seconds). Must be in the future and within
+ *   the backend's TTL window (currently 10 min).
+ * @param options Request options (headers).
+ * @returns Raw `Response` from the backend. 200 on success, 401 for
+ *   expired / replayed / mismatched-signer / tampered-referrer, 422 for an
+ *   unsupported `chainId`.
+ *
+ * @example
+ * ```ts
+ * const nonce = crypto.randomUUID().replace(/-/g, '');
+ * const expiry = Math.floor(Date.now() / 1000) + 300;
+ * const message =
+ *   `Upshift: register ${address.toLowerCase()}\n` +
+ *   `referrer: ${referrer?.toLowerCase() ?? 'none'}\n` +
+ *   `chain: ${chainId}\n` +
+ *   `nonce: ${nonce}\n` +
+ *   `expires: ${expiry}`;
+ * const signature = await walletClient.signMessage({ account: address, message });
+ * await registerUserForPoints({ userAddress: address, referrerAddress: referrer, chainId, signature, nonce, expiry });
+ * ```
+ */
 async function registerUserForPoints({ userAddress, referrerAddress, chainId, signature, nonce, expiry, options, }) {
     try {
         if (!userAddress) {
@@ -1429,6 +1733,12 @@ async function registerUserForPoints({ userAddress, referrerAddress, chainId, si
         throw new Error(`#registerUserForPoints::${userAddress}:${errorMessage}`);
     }
 }
+/**
+ * Fetch the points leaderboard data.
+ * @param params Optional parameters for pagination and sorting
+ * @param options Request options including headers
+ * @returns Leaderboard response data
+ */
 async function fetchPointsLeaderboard({ params, options, }) {
     try {
         const { page = 1, perPage = 10, sortBy = 'totalPoints' } = params || {};
@@ -1451,6 +1761,13 @@ async function fetchPointsLeaderboard({ params, options, }) {
         throw new Error(`#fetchPointsLeaderboard::${errorMessage}`);
     }
 }
+/**
+ * Fetch the timestamp when yield was last realized for a vault.
+ * Returns the assetsUpdatedOn timestamp from the vault contract.
+ * @param vault Vault contract address
+ * @param options RPC configuration
+ * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+ */
 async function getYieldLastRealizedOn({ vault, options, }) {
     try {
         const provider = (0, core_1.createProvider)(options.rpcUrl);
@@ -1484,6 +1801,8 @@ async function getYieldLastRealizedOn({ vault, options, }) {
                 return 0;
             }
             default: {
+                // Old lending pools don't have assetsUpdatedOn function
+                // Return 0 for legacy vaults
                 return 0;
             }
         }
@@ -1495,6 +1814,19 @@ async function getYieldLastRealizedOn({ vault, options, }) {
         throw new Error(`#getYieldLastRealizedOn::${vault}:${errorMessage}`);
     }
 }
+/**
+ * Calculate lifetime PnL for a user in a specific vault.
+ *
+ * Basic logic:
+ * 1. Get user's list of deposits and withdrawals from subgraph
+ * 2. Fetch user's current assets (balanceOf * sharePrice via convertToAssets)
+ * 3. Calculate PnL = assets withdrawn + current assets - assets deposited
+ *
+ * @param vault Vault contract address
+ * @param wallet User wallet address
+ * @param options RPC configuration and service options
+ * @returns Lifetime PnL data in both native token and USD
+ */
 async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
     try {
         if (!vault)
@@ -1507,6 +1839,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         if (!(0, ethers_1.isAddress)(wallet))
             throw new Error(`Wallet input parameter is not an address: ${String(wallet)}`);
         const provider = (0, core_1.createProvider)(options.rpcUrl);
+        // Parallelize independent operations
         const [decimals, userHistory, positions, tokenizedVaultResult] = await Promise.all([
             (0, core_1.getDecimals)(provider, vault),
             (0, vaults_1.getSubgraphUserHistory)(wallet, provider, vault),
@@ -1521,6 +1854,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         if (!tokenizedVault) {
             throw new Error(`Vault ${vault} not found`);
         }
+        // Fetch LayerZero deposits/redeems for supported vaults
         const lzVaultKey = (0, deposits_1.isLayerZeroVault)(vault);
         let lzDeposits = [];
         let lzRedeems = [];
@@ -1534,6 +1868,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                     core_1.Logger.log.warn('getVaultUserLifetimePnl:lzDeposits', `Failed to fetch LZ deposits for ${lzVaultKey}: ${e}`);
                 }),
             ];
+            // Only earnAUSD has redeem events currently
             if (lzVaultKey === 'earnAUSD') {
                 lzPromises.push((0, redeems_1.queryLayerZeroRedeems)(wallet)
                     .then((r) => {
@@ -1547,10 +1882,12 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         }
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
         const currentPosition = positions.find((pos) => pos.vault?.toLowerCase() === vault.toLowerCase());
+        // Start underlyingSymbol fetch (runs in parallel with processHistory)
         const underlyingSymbolPromise = (async () => {
             let underlyingTokenSymbol = 'UNKNOWN';
             let underlyingAssetAddress;
             try {
+                // Use ABI_LENDING_POOL_V2 which has the asset() method
                 const vaultContract = (0, core_1.createContract)({
                     provider,
                     address: vault,
@@ -1578,15 +1915,22 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             }
             return { underlyingTokenSymbol, underlyingAssetAddress };
         })();
+        // Process history - count all withdrawal requests (both processed and pending)
+        // We don't count processed withdrawals separately to avoid double counting
+        // Group deposit amounts by asset address to handle different decimals
         const depositsByAsset = new Map();
+        // Separate withdrawal tracking: shares need conversion, assets don't
         let totalWithdrawalsInShares = BigInt(0);
         let totalWithdrawalsInAssets = BigInt(0);
         for (const historyItem of userHistory) {
             const amount = BigInt(historyItem.amount);
+            // ignore bad transactions when calculating pnl
             if ((0, core_1.isBadTransaction)(historyItem.transactionHash_, tokenizedVault.chain)) {
                 continue;
             }
             if (historyItem.type === 'deposit') {
+                // Use assetIn if available (V2 vaults), otherwise use a default key
+                // Use proper type guard instead of type assertion
                 const assetKey = 'assetIn' in historyItem && typeof historyItem.assetIn === 'string'
                     ? historyItem.assetIn.toLowerCase()
                     : 'default';
@@ -1594,15 +1938,21 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                 depositsByAsset.set(assetKey, current + amount);
             }
             else if (historyItem.type === 'withdraw-request') {
+                // Withdraw requests are in shares, need conversion to assets
                 totalWithdrawalsInShares += amount;
             }
             else if (historyItem.type === 'withdraw-processed' &&
                 historyItem.isInstant) {
+                // Instant withdrawals are already in assets, no conversion needed
                 totalWithdrawalsInAssets += amount;
             }
         }
+        // Include LayerZero cross-chain deposits and redeems
         if (lzVaultKey && lzDeposits.length > 0) {
             for (const lzDeposit of lzDeposits) {
+                // LZ deposits assetAmt is the underlying asset amount deposited in hub-chain decimals.
+                // This assumes the LZ subgraph indexes amounts in the same decimals as the hub vault
+                // (e.g. 6 for USDC). If source/hub decimals diverge, normalization would be needed here.
                 const assetKey = 'lz-default';
                 const amount = BigInt(lzDeposit.assetAmt);
                 const current = depositsByAsset.get(assetKey) ?? BigInt(0);
@@ -1611,9 +1961,11 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         }
         if (lzVaultKey && lzRedeems.length > 0) {
             for (const lzRedeem of lzRedeems) {
+                // LZ redeems shareAmt is in shares, needs conversion via share price
                 totalWithdrawalsInShares += BigInt(lzRedeem.shareAmt);
             }
         }
+        // Fetch decimals for each unique asset in parallel
         const assetDecimals = new Map();
         await Promise.all(Array.from(depositsByAsset.keys()).map(async (assetAddress) => {
             if (assetAddress === 'default' || assetAddress === 'lz-default') {
@@ -1624,15 +1976,18 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                 assetDecimals.set(assetAddress, dec);
             }
         }));
+        // Store deposits as a map: assetAddress -> INormalizedNumber (with correct decimals)
         const totalDepositedRaw = new Map();
         for (const [assetAddress, rawAmount] of depositsByAsset) {
             const assetDec = assetDecimals.get(assetAddress) ?? decimals;
             totalDepositedRaw.set(assetAddress, (0, core_1.toNormalizedBn)(rawAmount, assetDec));
         }
+        // Fetch USD prices for each unique deposit asset in parallel
         const assetPrices = new Map();
         if (tokenizedVault.chain) {
             await Promise.all(Array.from(depositsByAsset.keys()).map(async (assetAddress) => {
                 if (assetAddress === 'default' || assetAddress === 'lz-default') {
+                    // Will use underlying asset price later
                     assetPrices.set(assetAddress, 0);
                 }
                 else {
@@ -1648,6 +2003,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             }));
         }
         const { underlyingTokenSymbol, underlyingAssetAddress } = await underlyingSymbolPromise;
+        // Calculate current position value and fetch price in parallel
         let currentPositionValue = (0, core_1.toNormalizedBn)(0, decimals);
         const pricePromise = underlyingAssetAddress && tokenizedVault.chain
             ? (0, core_1.fetchTokenPriceByAddress)(underlyingAssetAddress, tokenizedVault.chain, options?.headers).catch(() => 0)
@@ -1674,7 +2030,10 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             else {
                 currentShares = await vaultContract.balanceOf(wallet);
             }
+            // For LayerZero vaults, include receipt token balances on remote chains
             if (lzVaultKey) {
+                // Build list of remote chains to check: prefer receipt_token_integrations from API,
+                // fall back to LAYERZERO_VAULTS spoke chain config (OVault shareOFT addresses)
                 const remoteChains = [];
                 if (tokenizedVault.receipt_token_integrations?.length) {
                     for (const rti of tokenizedVault.receipt_token_integrations) {
@@ -1689,6 +2048,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                     }
                 }
                 else {
+                    // Fallback: use spoke chain addresses from LAYERZERO_VAULTS config
                     const lzVaultConfig = deposits_1.LAYERZERO_VAULTS[lzVaultKey];
                     if (lzVaultConfig.spokeChains) {
                         for (const [chainIdStr, address] of Object.entries(lzVaultConfig.spokeChains)) {
@@ -1721,6 +2081,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                                 remoteTokenContract.decimals(),
                             ]);
                             const remDec = Number(remoteDecimals) || decimals;
+                            // Normalize remote balance to hub chain decimals
                             if (remDec > decimals) {
                                 return rawBalance / BigInt(10 ** (remDec - decimals));
                             }
@@ -1748,7 +2109,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                     vaultContract.totalSupply(),
                 ]);
                 if (totalSupply === BigInt(0)) {
-                    sharePriceRaw = BigInt(10 ** decimals);
+                    sharePriceRaw = BigInt(10 ** decimals); // 1:1 if no supply
                 }
                 else {
                     sharePriceRaw = (totalAssets * BigInt(10 ** decimals)) / totalSupply;
@@ -1763,22 +2124,28 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                 currentPositionValue = currentPosition.walletBalance;
             }
         }
+        // Calculate totalWithdrawn combining shares (converted) and assets (as-is)
         let totalWithdrawnRaw = totalWithdrawalsInAssets;
         if (version === 'evm-2' && sharePriceRaw > BigInt(0)) {
+            // Only convert shares to assets, instant withdrawals are already in assets
             totalWithdrawnRaw +=
                 (totalWithdrawalsInShares * sharePriceRaw) / BigInt(10 ** decimals);
         }
         else {
+            // For non-evm-2 or when share price is 0, treat shares as assets
             totalWithdrawnRaw += totalWithdrawalsInShares;
         }
         const totalWithdrawn = (0, core_1.toNormalizedBn)(totalWithdrawnRaw, decimals);
         const tokenPriceUsd = await pricePromise;
+        // Validate token price and log warning if invalid
         const effectiveTokenPrice = tokenPriceUsd > 0 ? tokenPriceUsd : 1;
         if (tokenPriceUsd <= 0) {
             core_1.Logger.log.warn('getVaultUserLifetimePnl:tokenPrice', `Invalid underlying token price: ${tokenPriceUsd}, using fallback of 1`);
         }
+        // Sum all deposited amounts in USD using each asset's own price
         let totalDepositedUsd = 0;
         for (const [assetAddress, normalizedAmount] of totalDepositedRaw) {
+            // Use the asset-specific price, or underlying price for 'default'
             const assetPrice = assetAddress === 'default' || assetAddress === 'lz-default'
                 ? effectiveTokenPrice
                 : assetPrices.get(assetAddress) || effectiveTokenPrice;
@@ -1786,14 +2153,18 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         }
         const totalWithdrawnUsd = Number(totalWithdrawn.normalized) * effectiveTokenPrice;
         const currentPositionValueUsd = Number(currentPositionValue.normalized) * effectiveTokenPrice;
+        // Calculate lifetimePnl in USD first (since deposits may be in different tokens with different prices)
         const lifetimePnlUsd = currentPositionValueUsd + totalWithdrawnUsd - totalDepositedUsd;
-        const scaleFactor = BigInt(10 ** 18);
+        // Use BigInt-scaled arithmetic to minimize precision loss when converting USD to native
+        const scaleFactor = BigInt(10 ** 18); // High precision scale
         const tokenPriceScaled = BigInt(Math.round(effectiveTokenPrice * Number(scaleFactor)));
+        // Convert totalDepositedUsd to native units for backwards compatibility
         const totalDepositedUsdScaled = BigInt(Math.round(totalDepositedUsd * Number(scaleFactor)));
         const totalDepositedNativeRaw = tokenPriceScaled > BigInt(0)
             ? (totalDepositedUsdScaled * BigInt(10 ** decimals)) / tokenPriceScaled
             : BigInt(0);
         const totalDeposited = (0, core_1.toNormalizedBn)(totalDepositedNativeRaw, decimals);
+        // Convert lifetimePnlUsd to native units
         const lifetimePnlUsdScaled = BigInt(Math.round(lifetimePnlUsd * Number(scaleFactor)));
         const lifetimePnlRaw = tokenPriceScaled > BigInt(0)
             ? (lifetimePnlUsdScaled * BigInt(10 ** decimals)) / tokenPriceScaled
@@ -1821,6 +2192,14 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         throw new Error(`#getVaultUserLifetimePnl::${vault}::${wallet}:${errorMessage}`);
     }
 }
+/**
+ * Calculate PnL for a vault (vault-level, not user-specific).
+ * Returns the vault's overall profit and loss across all users.
+ *
+ * @param vault Vault contract address
+ * @param options RPC configuration and service options
+ * @returns Vault PnL in USD and notional value
+ */
 async function getVaultPnl({ vault, options, }) {
     try {
         if (!vault)
@@ -1828,6 +2207,7 @@ async function getVaultPnl({ vault, options, }) {
         (0, utils_3.assertNotStellar)(vault, 'Vault PnL');
         if (!(0, ethers_1.isAddress)(vault))
             throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        // Get vault data
         const vaultData = await getVault({
             vault,
             loans: false,
@@ -1837,6 +2217,7 @@ async function getVaultPnl({ vault, options, }) {
         if (!vaultData) {
             throw new Error(`Vault ${vault} not found`);
         }
+        // Check if vault has daily_pnl_per_share and historical_snapshots
         if (!vaultData.dailyPnlPerShare ||
             !Array.isArray(vaultData.dailyPnlPerShare) ||
             vaultData.dailyPnlPerShare.length === 0) {
@@ -1854,38 +2235,49 @@ async function getVaultPnl({ vault, options, }) {
             };
         }
         const decimals = vaultData.decimals;
+        // Filter out dates with zero PnL
         const validDailyPnl = vaultData.dailyPnlPerShare.filter((dayData) => dayData.value && dayData.value !== 0);
+        // Create a map of historical_snapshots by date (YYYY-MM-DD) for quick lookup
         const snapshotsByDate = new Map();
         vaultData.historical_snapshots.forEach((snapshot) => {
             const snapshotDate = new Date(snapshot.snapshot_datetime);
-            const dateKey = snapshotDate.toISOString().split('T')[0];
+            const dateKey = snapshotDate.toISOString().split('T')[0]; // YYYY-MM-DD
             snapshotsByDate.set(dateKey, snapshot);
         });
+        // Calculate PnL for each day using historical_snapshots
         let totalPnlRaw = BigInt(0);
         validDailyPnl.forEach((dayData) => {
             const dayTimestamp = dayData.timestamp;
             const dailyPnlPerShare = dayData.value;
+            // Get date key (YYYY-MM-DD) from timestamp
             const dayDate = new Date(dayTimestamp);
             const dateKey = dayDate.toISOString().split('T')[0];
+            // Find matching snapshot for this date
             const snapshot = snapshotsByDate.get(dateKey);
             if (!snapshot || !snapshot.total_shares) {
                 core_1.Logger.log.warn('getVaultPnl:snapshotNotFound', `No snapshot found for date ${dateKey}`);
                 return;
             }
+            // Convert normalized numbers to BigInt using toNormalizedBn's normalized string
             const dailyPnlNorm = (0, core_1.toNormalizedBn)(dailyPnlPerShare, decimals);
             const totalSharesNorm = (0, core_1.toNormalizedBn)(snapshot.total_shares, decimals);
+            // Convert normalized strings to BigInt (split, pad fraction, combine) - all inline
             const [dailyWhole = '0', dailyFrac = ''] = dailyPnlNorm.normalized.split('.');
             const dailyPnlPerShareScaled = BigInt(dailyWhole + (dailyFrac || '').padEnd(decimals, '0').slice(0, decimals));
             const [sharesWhole = '0', sharesFrac = ''] = totalSharesNorm.normalized.split('.');
             const totalSharesScaled = BigInt(sharesWhole +
                 (sharesFrac || '').padEnd(decimals, '0').slice(0, decimals));
+            // Calculate: daily_pnl_per_share[day] * total_shares[day] (both in raw units)
             const dayPnlRaw = (dailyPnlPerShareScaled * totalSharesScaled) / BigInt(10 ** decimals);
             totalPnlRaw += dayPnlRaw;
         });
+        // Convert totalPnlRaw (BigInt) to normalized number using toNormalizedBn
         const totalPnl = (0, core_1.toNormalizedBn)(totalPnlRaw, decimals);
         const totalPnlNormalized = Number(totalPnl.normalized);
         const chainId = vaultData.chainId;
+        // Get receipt token address (HLPe) from vaultData - no need for on-chain lookup
         const lpTokenAddress = vaultData.receipt.address;
+        // Fetch HLPe (lpTokenAddress) price in USD
         let tokenPriceUsd = 0;
         try {
             tokenPriceUsd = await (0, core_1.fetchTokenPriceByAddress)(lpTokenAddress, chainId, options?.headers);
@@ -1893,6 +2285,7 @@ async function getVaultPnl({ vault, options, }) {
         catch (error) {
             core_1.Logger.log.warn('getVaultPnl:priceFetch', `Failed to fetch HLPe token price: ${error}`);
         }
+        // Convert to USD and format to 6 decimal places
         const pnlUsd = Number((totalPnlNormalized * tokenPriceUsd).toFixed(6));
         return {
             totalPnl,
@@ -1905,6 +2298,14 @@ async function getVaultPnl({ vault, options, }) {
         throw new Error(`#getVaultPnl::${vault}:${errorMessage}`);
     }
 }
+/*
+ * Fetch historical timeseries data for a vault.
+ * Returns TVL, APY, PnL, share price, and other metrics over time.
+ * @param vault Vault contract address
+ * @param nDays Number of days of historical data (default 30, min 1)
+ * @param options Request options including headers
+ * @returns Historical timeseries data with date string keys
+ */
 async function getVaultHistoricalTimeseries({ vault, nDays, options, }) {
     try {
         if (!vault)
@@ -1918,6 +2319,19 @@ async function getVaultHistoricalTimeseries({ vault, nDays, options, }) {
         throw new Error(`#getVaultHistoricalTimeseries::${vault}:${errorMessage}`);
     }
 }
+/**
+ * Fetch 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 contract address
+ * @param options Request options including headers
+ * @returns Annualized APY data including liquidity APY
+ */
 async function getVaultAnnualizedApy({ vault, options, }) {
     try {
         if (!vault) {
@@ -1942,6 +2356,12 @@ async function getVaultAnnualizedApy({ vault, options, }) {
         throw new Error(`#getVaultAnnualizedApy::${vault}:${errorMessage}`);
     }
 }
+/**
+ * Fetch summary data for a vault (name, type, chain, recent returns).
+ * @param vault Vault contract address
+ * @param options Request options including headers
+ * @returns Vault summary data
+ */
 async function getVaultSummary({ vault, options, }) {
     try {
         if (!vault) {
@@ -1967,6 +2387,13 @@ async function getVaultSummary({ vault, options, }) {
         throw new Error(`#getVaultSummary::${vault}:${errorMessage}`);
     }
 }
+/**
+ * Fetch withdrawal summary and pending queue for a vault.
+ * @param vault Vault contract address
+ * @param chain Chain identifier (e.g., chain ID as string)
+ * @param options Request options including headers
+ * @returns Withdrawal summary and pending queue
+ */
 async function getVaultWithdrawals({ vault, chain, options, }) {
     try {
         if (!vault) {
@@ -1995,6 +2422,14 @@ async function getVaultWithdrawals({ vault, chain, options, }) {
         throw new Error(`#getVaultWithdrawals::${vault}::${chain}:${errorMessage}`);
     }
 }
+/**
+ * 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)
+ * @param options Request options including headers
+ * @returns Pending redemptions grouped by date with liquidity summary
+ */
 async function getVaultPendingRedemptions({ vault, pastDays, futureDays, options, }) {
     try {
         if (!vault)
@@ -2062,6 +2497,13 @@ async function getVaultPendingRedemptions({ vault, pastDays, futureDays, options
         throw new Error(`#getVaultPendingRedemptions::${vault}:${errorMessage}`);
     }
 }
+/**
+ * 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 options RPC configuration
+ * @returns The amount of assets as INormalizedNumber { normalized, raw }
+ */
 async function getPreviewRedemption({ vault, sharesAmount, options, }) {
     try {
         if (!vault)
@@ -2109,6 +2551,13 @@ async function getPreviewRedemption({ vault, sharesAmount, options, }) {
         throw new Error(`Failed to preview redemption for ${vault}: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Helper: Decode a processing transaction to extract (year, month, day).
+ *
+ * Note: Multicall-wrapped transactions cannot be decoded from calldata or logs
+ * (the WithdrawalProcessed event doesn't include the date). When decoding fails,
+ * the caller falls back to timestamp-based date estimation.
+ */
 async function decodeProcessingTransaction(txHash, provider, iface) {
     const tx = await provider.getTransaction(txHash);
     if (!tx) {
@@ -2122,14 +2571,74 @@ async function decodeProcessingTransaction(txHash, provider, iface) {
     }
     return (0, call_data_decoder_1.decodeWithdrawalProcessing)(tx.data, iface);
 }
+/**
+ * Returns all withdrawal requests for a vault, enriched with computed claimable dates
+ * and current processing status.
+ *
+ * The unique identifier for matching requests to processed events is:
+ * (receiver, claimableDate.year, claimableDate.month, claimableDate.day)
+ *
+ * This is the primary method for integrators to reliably track withdrawal status
+ * when multiple requests are submitted by the same receiver.
+ *
+ * ## Data sources
+ * - **Withdrawal requests** come from the subgraph (all historical requests).
+ * - **Processed events** come from on-chain `WithdrawalProcessed` logs, which are
+ *   limited to a finite lookback window determined by the chain's block parameters.
+ *
+ * ## Lookback window & filtering
+ * On-chain logs only cover a limited number of recent blocks (e.g. ~20 days on Monad,
+ * ~21 days on Ethereum). The `lookbackBlocks` parameter controls how far back to scan
+ * and is applied uniformly to both data sources: it bounds the `WithdrawalProcessed`
+ * log query *and* drops any withdrawal request whose submission timestamp falls outside
+ * the window — regardless of whether a matching processed event was found. Callers who
+ * need deeper history should widen `lookbackBlocks`.
+ *
+ * ## Status determination
+ * - `'processed'` — A matching `WithdrawalProcessed` event was found (by receiver + claimable date).
+ * - `'ready_to_claim'` — Claimable date has passed (within the lookback window) but no processed event found.
+ * - `'pending'` — Claimable date is still in the future.
+ *
+ * @param params - Query parameters
+ * @param params.vault - Vault address to query
+ * @param params.receiver - (Optional) Filter by receiver address
+ * @param params.lookbackBlocks - (Optional) On-chain log lookback window in blocks.
+ *   Defaults to a chain-specific value (e.g. 150,000 for Ethereum, 3,456,000 for Monad).
+ *   Increasing this scans more history but requires more RPC calls.
+ * @param params.options - Standard vault query options (provider, RPC URL, etc.)
+ * @returns Array of withdrawal requests with status and claimable dates
+ *
+ * @example
+ * ```typescript
+ * const requests = await getWithdrawalRequestsWithStatus({
+ *   vault: '0xVault...',
+ *   receiver: '0xReceiver...'
+ * });
+ *
+ * // Results show exact status + claimable date
+ * requests.forEach(req => {
+ *   console.log(
+ *     `${req.claimableDate.year}-${req.claimableDate.month}-${req.claimableDate.day}: ${req.status}`
+ *   );
+ * });
+ *
+ * // With custom lookback window (e.g. 30 days on Ethereum ≈ 216,000 blocks)
+ * const moreResults = await getWithdrawalRequestsWithStatus({
+ *   vault: '0xVault...',
+ *   lookbackBlocks: 216_000,
+ * });
+ * ```
+ */
 async function getWithdrawalRequestsWithStatus(params) {
     try {
         const { vault, receiver, lookbackBlocks, options } = params;
+        // Input validation
         if (!vault || !(0, ethers_1.isAddress)(vault)) {
             throw new Error('Invalid vault address');
         }
         const vaultAddress = (0, ethers_1.getAddress)(vault);
         const provider = (0, core_1.createProvider)(options.rpcUrl);
+        // Fetch vault metadata and lag duration
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress, options?.headers, false, false))?.[0];
         if (!tokenizedVault) {
             core_1.Logger.log.warn('getWithdrawalRequestsWithStatus', `Vault not found in backend: ${vaultAddress}`);
@@ -2143,7 +2652,7 @@ async function getWithdrawalRequestsWithStatus(params) {
             abi: vaultAbi,
             provider,
         });
-        let lagDuration = 86400;
+        let lagDuration = 86400; // Default: 1 day
         try {
             const lagValue = await vaultContract.lagDuration?.();
             if (lagValue !== undefined && lagValue !== null) {
@@ -2153,6 +2662,9 @@ async function getWithdrawalRequestsWithStatus(params) {
         catch (e) {
             core_1.Logger.log.warn('getWithdrawalRequestsWithStatus', `Failed to fetch lagDuration from vault ${vaultAddress}, using default 1 day — status determinations may be inaccurate: ${e instanceof Error ? e.message : 'Unknown error'}`);
         }
+        // Fetch subgraph requests, on-chain processed events, and the current block
+        // in parallel. Current block is needed to derive the block-based lookback
+        // cutoff applied uniformly to both data sources.
         const [withdrawalRequests, processedEvents, currentBlock] = await Promise.all([
             (0, vaults_1.getSubgraphWithdrawRequests)(vaultAddress, provider),
             getVaultRedemptionHistory({
@@ -2170,6 +2682,10 @@ async function getWithdrawalRequestsWithStatus(params) {
         const effectiveLookbackBlocks = lookbackBlocks ?? (0, core_1.determineBlockCutoff)(chainId);
         const blockCutoff = currentBlock - effectiveLookbackBlocks;
         const now = Math.floor(Date.now() / 1000);
+        // Filter by receiver (if provided) and drop any request whose submission
+        // block is outside the lookback window — uniformly, regardless of whether
+        // a matching processed event exists. Using block_number (not timestamp)
+        // keeps this consistent with the on-chain log scan's block-based cutoff.
         const filteredRequests = withdrawalRequests.filter((req) => {
             if (receiver &&
                 req.receiverAddr?.toLowerCase() !== receiver.toLowerCase()) {
@@ -2177,8 +2693,10 @@ async function getWithdrawalRequestsWithStatus(params) {
             }
             return Number(req.block_number) >= blockCutoff;
         });
+        // Pre-decode all processed transactions in parallel for performance
         const iface = new ethers_1.Interface(vaultAbi);
         const decodedProcessed = await Promise.all((processedEvents || []).map(async (processed) => {
+            // Try calldata decoding first (deterministic)
             if (processed.transactionHash) {
                 try {
                     const decoded = await decodeProcessingTransaction(processed.transactionHash, provider, iface);
@@ -2197,8 +2715,12 @@ async function getWithdrawalRequestsWithStatus(params) {
                     core_1.Logger.log.warn('getWithdrawalRequestsWithStatus', `Failed to decode processed transaction ${processed.transactionHash}: ${e instanceof Error ? e.message : 'Unknown error'}`);
                 }
             }
+            // Fallback: use original request timestamp to compute claimable date,
+            // or if unavailable (evm-2: requested=epoch 0), use the processed block
+            // timestamp as the date directly (processing happens on the claimable date).
             const requestedEpoch = Math.floor(processed.requested.getTime() / 1000);
             if (requestedEpoch > 0) {
+                // evm-1: we have the original request timestamp → compute claimable date
                 const fallbackDate = (0, date_utils_1.computeClaimableDate)(requestedEpoch, lagDuration);
                 return {
                     ...processed,
@@ -2209,6 +2731,8 @@ async function getWithdrawalRequestsWithStatus(params) {
                     },
                 };
             }
+            // evm-2: no request timestamp — use processed block date directly
+            // (processing occurs on the claimable date, so the block date IS the date)
             const processedDate = processed.processed;
             return {
                 ...processed,
@@ -2219,6 +2743,11 @@ async function getWithdrawalRequestsWithStatus(params) {
                 },
             };
         }));
+        // Build deterministic lookup map: (receiver + year + month + day) → processed events
+        // A single WithdrawalProcessed event covers the entire day's batch for a
+        // receiver — all requests whose claimable date falls on that day should
+        // match it. We keep an array per key only to preserve every event we saw
+        // for visibility; matching is a non-destructive peek at the first entry.
         const processedMap = new Map();
         for (const processed of decodedProcessed) {
             if (!processed.decodedDate) {
@@ -2229,15 +2758,24 @@ async function getWithdrawalRequestsWithStatus(params) {
             const existing = processedMap.get(key) ?? [];
             processedMap.set(key, [...existing, processed]);
         }
+        // Compute status for each withdrawal request. The lookback window was
+        // already applied up-front when pruning filteredRequests, so every request
+        // reaching this loop is within the window by construction.
         const results = [];
         for (const req of filteredRequests) {
+            // timestamp_ is a Unix epoch string (seconds)
             const requestTimestamp = Number(req.timestamp_);
+            // Compute claimable date from timestamp + lagDuration (UTC)
             const claimableDate = (0, date_utils_1.computeClaimableDate)(requestTimestamp, lagDuration);
+            // Determine status: check processed first, then claimability
             let status = 'pending';
             let processedTxHash;
             let assetsReceived;
+            // Match deterministically by (receiver, year, month, day)
             const dateKey = (0, date_utils_1.formatDateKey)(claimableDate.year, claimableDate.month, claimableDate.day);
             const lookupKey = `${req.receiverAddr.toLowerCase()}:${dateKey}`;
+            // Peek — do not consume. The processing event covers the whole day for
+            // this receiver, so every request on that day matches the same event.
             const processedEvent = processedMap.get(lookupKey)?.[0];
             if (processedEvent) {
                 status = 'processed';
@@ -2250,6 +2788,7 @@ async function getWithdrawalRequestsWithStatus(params) {
                 }
             }
             else if ((0, date_utils_1.isClaimableNow)(claimableDate.epoch, now)) {
+                // Claimable date is recent (within lookback) and not yet processed
                 status = 'ready_to_claim';
             }
             results.push({
@@ -2260,6 +2799,7 @@ async function getWithdrawalRequestsWithStatus(params) {
                         return BigInt(req.shares);
                     }
                     catch {
+                        // Handle decimal strings from subgraph (e.g. "1234.0")
                         const truncated = Math.trunc(Number(req.shares));
                         if (!Number.isFinite(truncated)) {
                             core_1.Logger.log.warn('getWithdrawalRequestsWithStatus', `Cannot parse shares value "${req.shares}" — defaulting to 0`);