upshift-sdk 8.20.1

package/lib/modules/vaults/getters.js

@@ -0,0 +1,3051 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSwapRouterDepositResult = void 0;
+exports.getVault = getVault;
+exports.getVaultLoans = getVaultLoans;
+exports.getVaultSubaccountLoans = getVaultSubaccountLoans;
+exports.getVaultAllocations = getVaultAllocations;
+exports.getVaultAvailableRedemptions = getVaultAvailableRedemptions;
+exports.getVaultRedemptionHistory = getVaultRedemptionHistory;
+exports.getVaultPositions = getVaultPositions;
+exports.getVaultApy = getVaultApy;
+exports.getRewardsStakingPositions = getRewardsStakingPositions;
+exports.getVaultTvl = getVaultTvl;
+exports.getVaultBorrowerHealthFactor = getVaultBorrowerHealthFactor;
+exports.getHealthFactorOfBorrowersByVault = getHealthFactorOfBorrowersByVault;
+exports.getUserPoints = getUserPoints;
+exports.registerUserForPoints = registerUserForPoints;
+exports.fetchPointsLeaderboard = fetchPointsLeaderboard;
+exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
+exports.assertPnlHistoryConsistent = assertPnlHistoryConsistent;
+exports.sumDepositsAtFaceValue = sumDepositsAtFaceValue;
+exports.getVaultUserLifetimePnl = getVaultUserLifetimePnl;
+exports.getVaultPnl = getVaultPnl;
+exports.getVaultHistoricalTimeseries = getVaultHistoricalTimeseries;
+exports.getVaultAnnualizedApy = getVaultAnnualizedApy;
+exports.getVaultSummary = getVaultSummary;
+exports.getVaultWithdrawals = getVaultWithdrawals;
+exports.getVaultPendingRedemptions = getVaultPendingRedemptions;
+exports.getPreviewRedemption = getPreviewRedemption;
+exports.getWithdrawalRequestsWithStatus = getWithdrawalRequestsWithStatus;
+const abis_1 = require("../../abis");
+const types_1 = require("../../types");
+const core_1 = require("../../core");
+const ethers_1 = require("ethers");
+const utils_1 = require("./utils");
+const subgraph_1 = require("../../services/subgraph");
+const vaults_1 = require("../../services/subgraph/vaults");
+const debank_1 = require("../../services/debank");
+const utils_2 = require("../../adapters/solana/utils");
+const SolanaGetters = __importStar(require("../../adapters/solana/getters"));
+const SolanaConstants = __importStar(require("../../adapters/solana/constants"));
+const StellarGetters = __importStar(require("../../adapters/stellar/getters"));
+const utils_3 = require("../../adapters/stellar/utils");
+const constants_1 = require("../../adapters/stellar/constants");
+const EVM = __importStar(require("../../adapters/evm"));
+const TokenizedVaultV2_1 = require("../../abis/TokenizedVaultV2");
+const TokenizedVaultV2Receipt_1 = require("../../abis/TokenizedVaultV2Receipt");
+const ethereum_block_by_date_1 = __importDefault(require("ethereum-block-by-date"));
+const octavfi_1 = require("../../services/octavfi");
+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");
+const errors_1 = require("../../core/errors");
+/**
+ * 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 {
+        const tokenizedVaultRaw = await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots);
+        const tokenizedVault = tokenizedVaultRaw?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        switch (vaultVersion) {
+            case 'sol-0': {
+                returnedVault = await SolanaGetters.getSolanaVault(tokenizedVault, options);
+                break;
+            }
+            case 'stellar-0': {
+                returnedVault = await StellarGetters.getStellarVault(tokenizedVault, options);
+                break;
+            }
+            case 'evm-2': {
+                returnedVault = await EVM.getEvmVaultV2(tokenizedVault, options);
+                break;
+            }
+            default: {
+                returnedVault = await EVM.getEvmVaultV1(tokenizedVault, options);
+                break;
+            }
+        }
+        if (returnedVault === null) {
+            return null;
+        }
+    }
+    catch (err) {
+        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';
+    if (!isEvmVault && (loans || allocations)) {
+        core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for non-EVM vaults — skipping', { vault, version: returnedVault.version });
+    }
+    if (isEvmVault && !(0, core_1.isBadVault)(vault) && (loans || allocations)) {
+        const [loansResult, allocationsResult] = await Promise.allSettled([
+            loans
+                ? getVaultLoans(returnedVault, options)
+                : Promise.resolve(undefined),
+            allocations
+                ? getVaultAllocations(vault, options)
+                : Promise.resolve(undefined),
+        ]);
+        if (loans) {
+            if (loansResult.status === 'fulfilled') {
+                returnedVault = {
+                    ...returnedVault,
+                    loans: loansResult.value,
+                };
+            }
+            else {
+                core_1.Logger.log.error('getVault:loans', loansResult.reason, {
+                    symbol: returnedVault.receipt.symbol,
+                });
+            }
+        }
+        if (allocations) {
+            if (allocationsResult.status === 'fulfilled') {
+                returnedVault = {
+                    ...returnedVault,
+                    allocations: allocationsResult.value,
+                };
+            }
+            else {
+                core_1.Logger.log.error('getVault:allocations', allocationsResult.reason, {
+                    symbol: returnedVault.receipt.symbol,
+                });
+                throw new Error('Failure fetching debank res');
+            }
+        }
+    }
+    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 []; // 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,
+                abi: abis_1.ABI_LENDING_POOL_V2,
+            });
+            [poolTotalSupply, poolDecimals] = await Promise.all([
+                poolContract.totalSupply(),
+                (0, core_1.getDecimals)(provider, vaultAddress),
+            ]);
+            poolTotalSupply = BigInt(poolTotalSupply).toString();
+            poolDecimals = Number(poolDecimals);
+        }
+        else {
+            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,
+                lender: l.lender,
+                borrower: l.borrower,
+                state: l.state,
+                totalRepaid: l.total_repaid,
+                principalToken: l.principal_token,
+                principalAmount: l.principal_amount,
+                interestAmount: l.interest_amount,
+                upcomingPayment: {
+                    amount: l.upcoming_payment.amount,
+                    dueDate: l.upcoming_payment.due_date,
+                },
+                apr: loanAprAfterFees,
+                initialPrincipalAmount: l.initial_principal_amount,
+                deployedDate: l.deployed_date,
+                isIdleCapital,
+                paymentInterval: l.payment_interval,
+                allocation,
+            };
+            return newLoanObj;
+        }))).filter((l) => l !== undefined);
+        return newLoans;
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultLoans', e, { vault });
+        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);
+    if (vaultVersion !== 'evm-0')
+        return [];
+    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.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,
+                abi: abis_1.ABI_LENDING_POOL_V2,
+            });
+            [poolTotalSupply, poolDecimals] = await Promise.all([
+                poolContract.totalSupply(),
+                (0, core_1.getDecimals)(provider, vaultAddress),
+            ]);
+            poolTotalSupply = BigInt(poolTotalSupply).toString();
+            poolDecimals = Number(poolDecimals);
+        }
+        else {
+            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,
+                lender: l.lender,
+                borrower: l.borrower,
+                state: l.state,
+                totalRepaid: l.total_repaid,
+                principalToken: l.principal_token,
+                principalAmount: l.principal_amount,
+                interestAmount: l.interest_amount,
+                upcomingPayment: {
+                    amount: l.upcoming_payment.amount,
+                    dueDate: l.upcoming_payment.due_date,
+                },
+                apr: loanAprAfterFees,
+                initialPrincipalAmount: l.initial_principal_amount,
+                deployedDate: l.deployed_date,
+                isIdleCapital,
+                paymentInterval: l.payment_interval,
+                allocation,
+            };
+            return newLoanObj;
+        }))).filter((l) => l !== undefined);
+        return newLoans;
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultSubaccountLoans', e, { vault });
+        throw new Error(`#getVaultSubaccountLoans::${vault}:${e?.message}`);
+    }
+}
+/**
+ * HTTP statuses that mean "no such record for this subaccount", not "something
+ * broke". The backend returns 404 for a subaccount with no CeFi/OTC position,
+ * which is the normal case for most vault borrowers.
+ */
+const EXPECTED_SUBACCOUNT_FETCH_STATUSES = new Set([204, 404]);
+/**
+ * Log a per-subaccount enrichment fetch failure at the right severity.
+ *
+ * Why: `getVaultAllocations` issues one CeFi and one OTC request per borrower
+ * on every call. Logging the "no record" responses at `error` level captured
+ * them as Sentry issues, producing thousands of `AugustServerError: Request
+ * failed: 404` events a day for a condition that is not a fault and that
+ * callers never need to act on. Expected statuses become breadcrumbs; genuine
+ * failures (5xx, auth, transport) stay at `error`.
+ *
+ * @param tag - Call-site tag, e.g. `getVaultAllocations:cefi`. Becomes the
+ *   `sdk.origin` Sentry tag for grouping.
+ * @param status - HTTP status, or `undefined` when the failure was a thrown
+ *   transport/typed error with no status attached.
+ * @param detail - Status text or error to attach as context.
+ * @param context - Identifiers scoping the failure (`vault`, `borrower`).
+ */
+function logSubaccountFetchFailure(tag, status, detail, context) {
+    if (status !== undefined && EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(status)) {
+        core_1.Logger.log.warn(tag, { ...context, status, reason: 'no record' });
+        return;
+    }
+    core_1.Logger.log.error(tag, detail, { ...context, status });
+}
+/**
+ * Extract the HTTP status from a thrown fetch error, when it carries one.
+ *
+ * `fetchAugustWithKey` throws `AugustServerError`/`AugustAuthError` for non-2xx
+ * responses, so the status-code branch in the callers is unreachable for those
+ * — the status has to be recovered from the error to classify it.
+ *
+ * @param error - Any thrown value.
+ * @returns The HTTP status, or `undefined` for errors without one (network
+ *   failures, aborts, programming errors).
+ */
+function httpStatusFromError(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? status : undefined;
+}
+/**
+ * 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 = [];
+    const otcPositions = {};
+    const defiPerBorrower = {};
+    const exposurePerCategory = {
+        supplying: [],
+        borrowing: [],
+        wallet: [],
+        walletBalance: 0,
+        cefiBalance: 0,
+        defiBalance: 0,
+        lending: [],
+        loanBalance: 0,
+    };
+    const netValue = { value: 0 };
+    let debankErr = false;
+    let unfilteredTokens = [];
+    const borrowerPortfolioFetchers = {
+        solana: async (borrower) => {
+            const portfolios = await (0, octavfi_1.fetchOctavfiPortfolios)([borrower]);
+            return portfolios.length > 0
+                ? (0, octavfi_1.transformOctavfiToDebank)(portfolios[0])
+                : 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') {
+            const loans = await getVaultLoans(vault, options);
+            uniqueBorrowers = [...new Set(loans.map((l) => l.borrower))];
+        }
+        else {
+            const eoa_operators = tokenizedVault.eoa_operators.map((s) => s.address);
+            uniqueBorrowers = [
+                ...tokenizedVault.subaccounts.map((s) => s.address),
+                ...eoa_operators,
+            ];
+        }
+    }
+    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,
+                            error: subaccountData.error,
+                        });
+                        continue;
+                    }
+                    // Transform to match existing parser format: { subaccount: { positions, app_positions, tokens } }
+                    const debankRes = {
+                        subaccount: {
+                            positions: subaccountData.positions || [],
+                            app_positions: subaccountData.app_positions || [],
+                            tokens: subaccountData.tokens || [],
+                        },
+                    };
+                    (0, debank_1.parseVaultLevelDebank)(debankRes, protocolExposure, tokenExposure, subaccountAddress, exposurePerCategory, netValue);
+                    unfilteredTokens = debankRes?.subaccount?.tokens;
+                    const debankPerLoan = (0, debank_1.parseLoanLevelDebank)(debankRes);
+                    defiPerBorrower[subaccountAddress] = debankPerLoan;
+                }
+            }
+        }
+        // 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') {
+                const fetcher = borrowerPortfolioFetchers[chainType];
+                if (fetcher) {
+                    try {
+                        const debankRes = await fetcher(borrower);
+                        if (debankRes) {
+                            (0, debank_1.parseVaultLevelDebank)(debankRes, protocolExposure, tokenExposure, borrower, exposurePerCategory, netValue);
+                            unfilteredTokens = debankRes?.subaccount?.tokens;
+                            defiPerBorrower[borrower] = (0, debank_1.parseLoanLevelDebank)(debankRes);
+                        }
+                        else {
+                            debankErr = true;
+                        }
+                    }
+                    catch (error) {
+                        core_1.Logger.log.error(`getVaultAllocations:${chainType}`, error, {
+                            vault,
+                            borrower,
+                        });
+                        debankErr = true;
+                    }
+                }
+                else {
+                    // Not an error: portfolio providers simply have no coverage for this
+                    // chain type yet (Stellar, Sui). Reporting it as an exception filled
+                    // Sentry with a known, permanent gap, and setting `debankErr` made
+                    // every Stellar vault throw `failure to fetch debank response`
+                    // instead of returning the CeFi/OTC/loan allocations it did resolve.
+                    core_1.Logger.log.warn(`getVaultAllocations:no_fetcher`, {
+                        vault,
+                        borrower,
+                        chainType,
+                        reason: `No portfolio fetcher for chain type: ${chainType}`,
+                    });
+                }
+            }
+            // 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) {
+                    // 404 means "this subaccount has no CeFi position", which is the
+                    // common case for most borrowers — a breadcrumb, not an exception.
+                    logSubaccountFetchFailure('getVaultAllocations:cefi', cefiResponse.status, cefiResponse.statusText, { vault, borrower });
+                }
+                if (cefiResponse.status === 200) {
+                    const cefiRes = (await cefiResponse.json());
+                    cefiExposure = [...cefiExposure, ...cefiRes];
+                }
+            }
+            catch (e) {
+                logSubaccountFetchFailure('getVaultAllocations:cefi', httpStatusFromError(e), e, { vault, 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) {
+                    // 404 means "this subaccount has no OTC positions" — expected for
+                    // nearly every borrower. See logSubaccountFetchFailure.
+                    logSubaccountFetchFailure('getVaultAllocations:otc', otcResponse.status, otcResponse.statusText, { vault, borrower });
+                }
+                if (otcResponse.status === 200) {
+                    const otcRes = (await otcResponse.json());
+                    otcPositions[borrower] = otcRes;
+                }
+            }
+            catch (e) {
+                logSubaccountFetchFailure('getVaultAllocations:otc', httpStatusFromError(e), e, { vault, borrower });
+            }
+        }
+    }
+    const walletBalance = exposurePerCategory.wallet.reduce((sum, item) => sum + item.amount, 0);
+    const defiBalance = protocolExposure.reduce((sum, item) => sum + item.netUsdValue, 0);
+    const cefiBalance = cefiExposure.reduce((sum, item) => sum + item.value, 0);
+    exposurePerCategory.walletBalance = walletBalance;
+    exposurePerCategory.defiBalance = defiBalance;
+    exposurePerCategory.cefiBalance = cefiBalance;
+    netValue.value += cefiBalance;
+    if (debankErr) {
+        throw Error('failure to fetch debank response');
+    }
+    return {
+        defi: protocolExposure,
+        cefi: cefiExposure,
+        otc: otcPositions,
+        tokens: tokenExposure,
+        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,
+    };
+}
+/**
+ * Coerce a subgraph numeric field to `bigint`, treating absent fields as zero.
+ *
+ * Why: the evm-1 and evm-2 subgraphs expose different field names on
+ * `WithdrawalRequested` — evm-1 emits `assets` plus explicit `year`/`month`/
+ * `day`, evm-2 emits `shares` and a raw `timestamp_`. Reading the wrong one
+ * yields `undefined`, and bare `BigInt(undefined)` throws
+ * `TypeError: Cannot convert undefined to a BigInt`, which aborted the whole
+ * redemption scan and returned an empty list to the caller (the second
+ * highest-volume SDK error in production).
+ *
+ * `BigInt(x) || BigInt(0)` does **not** protect against this — the throw
+ * happens before `||` is ever evaluated.
+ *
+ * @param value - Subgraph field: decimal string, number, bigint, `null`, or
+ *   `undefined`.
+ * @returns The value as `bigint`, or `0n` when absent or non-numeric.
+ */
+function subgraphAmountToBigInt(value) {
+    if (value === undefined || value === null || value === '')
+        return BigInt(0);
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return BigInt(0);
+    }
+}
+async function getVaultAvailableRedemptions({ vault, wallet, options, prefetchedReads, }) {
+    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 {
+                availableRedemptions: [],
+                pendingRedemptions: [],
+                ...(options.verbose && {
+                    processedWithdrawals: [],
+                    requestedWithdrawals: [],
+                }),
+            };
+        }
+        // setup
+        const provider = (0, core_1.createProvider)(options.rpcUrl);
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers, false, false))?.[0];
+        if (!tokenizedVault) {
+            return {
+                ...{
+                    availableRedemptions: [],
+                    pendingRedemptions: [],
+                },
+                ...(options.verbose && {
+                    processedWithdrawals: [],
+                    requestedWithdrawals: [],
+                }),
+            };
+        }
+        // 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,
+            provider,
+        });
+        if (version === 'evm-2') {
+            decimals = await (0, core_1.getDecimals)(provider, await (0, core_1.getReceiptTokenAddress)(provider, vault), false);
+        }
+        else {
+            decimals = await (0, core_1.getDecimals)(provider, vault);
+        }
+        const lagDuration = typeof prefetchedReads?.lagDuration === 'number'
+            ? prefetchedReads.lagDuration
+            : Number(await vaultContract.lagDuration());
+        const { withdrawalRequesteds, withdrawalProcesseds } = await (0, subgraph_1.getSubgraphAllWithdrawals)(vault, provider);
+        // format
+        const availableRedemptions = [];
+        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;
+            }
+            let month = 0;
+            let day = 0;
+            let year = 0;
+            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}`);
+                    continue;
+                }
+                else {
+                    if (!year || !month || !day || !ev.receiverAddr) {
+                        if (version !== 'evm-2') {
+                            core_1.Logger.log.warn('getVaultAvailableRedemptions', `Skipping event with missing required properties: ${ev}`);
+                            continue;
+                        }
+                    }
+                }
+            }
+            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)
+                    return false;
+                if (version === 'evm-2') {
+                    const procDate = new Date(Number(proc.timestamp_) * 1000);
+                    const procKey = (0, date_utils_1.formatDateKey)(procDate.getUTCFullYear(), procDate.getUTCMonth() + 1, procDate.getUTCDate());
+                    return procKey === requestDateKey;
+                }
+                const procDate = new Date(proc.processedOn);
+                const procKey = (0, date_utils_1.formatDateKey)(procDate.getUTCFullYear(), procDate.getUTCMonth() + 1, procDate.getUTCDate());
+                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;
+                            }
+                            const redDate = new Date(Number(red.timestamp_) * 1000);
+                            const redKey = (0, date_utils_1.formatDateKey)(redDate.getUTCFullYear(), redDate.getUTCMonth() + 1, redDate.getUTCDate());
+                            return redKey === requestDateKey;
+                        })
+                        : availableRedemptions.find((red) => subgraphAmountToBigInt(red.day.raw) ===
+                            subgraphAmountToBigInt(ev.day) &&
+                            subgraphAmountToBigInt(red.month.raw) ===
+                                subgraphAmountToBigInt(ev.month) &&
+                            subgraphAmountToBigInt(red.year.raw) ===
+                                subgraphAmountToBigInt(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) {
+                                            withdrawalProcesseds.splice(index, 1);
+                                        }
+                                    }
+                                    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 = subgraphAmountToBigInt(ev.shares);
+                                                // 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,
+                                                        hash: ev.transactionHash_ || ev.id,
+                                                        timestamp: Number(ev.timestamp_),
+                                                        receiver: ev.receiverAddr,
+                                                        day: (0, core_1.toNormalizedBn)(day, 0),
+                                                        month: (0, core_1.toNormalizedBn)(month, 0),
+                                                        year: (0, core_1.toNormalizedBn)(year, 0),
+                                                        amount: (0, core_1.toNormalizedBn)(subgraphAmountToBigInt(ev.shares), decimals),
+                                                        date: fullDate,
+                                                        vault,
+                                                        status: types_1.VaultRedemptionStatus.READY_TO_CLAIM,
+                                                    });
+                                                }
+                                            }
+                                            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,
+                                                timestamp: Number(ev.timestamp_),
+                                                receiver: ev.receiverAddr,
+                                                day: (0, core_1.toNormalizedBn)(day, 0),
+                                                month: (0, core_1.toNormalizedBn)(month, 0),
+                                                year: (0, core_1.toNormalizedBn)(year, 0),
+                                                amount: (0, core_1.toNormalizedBn)(subgraphAmountToBigInt(ev.shares), decimals),
+                                                date: fullDate,
+                                                vault,
+                                                status: types_1.VaultRedemptionStatus.AWAITING_COOLDOWN,
+                                            });
+                                        }
+                                    }
+                                    break;
+                                }
+                                default: {
+                                    // Safe to read the raw subgraph dates here: the validation
+                                    // block above `continue`s for any non-evm-2 event missing
+                                    // `year`/`month`/`day`, so this path is only reached with all
+                                    // three present. The coercion below therefore never
+                                    // substitutes 0 for a real date.
+                                    const trueClaimableAmount = await vaultContract?.getClaimableAmountByReceiver?.(subgraphAmountToBigInt(ev.year), subgraphAmountToBigInt(ev.month), subgraphAmountToBigInt(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,
+                                                        hash: ev.transactionHash_ || ev.id,
+                                                        timestamp: Number(ev.timestamp_),
+                                                        receiver: ev.receiverAddr,
+                                                        day: (0, core_1.toNormalizedBn)(ev.day, 0),
+                                                        month: (0, core_1.toNormalizedBn)(ev.month, 0),
+                                                        year: (0, core_1.toNormalizedBn)(ev.year, 0),
+                                                        amount: (0, core_1.toNormalizedBn)(trueClaimableAmount || BigInt(0), decimals),
+                                                        date: fullDate,
+                                                        vault,
+                                                        status: types_1.VaultRedemptionStatus.READY_TO_CLAIM,
+                                                    });
+                                                }
+                                            }
+                                            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,
+                                                timestamp: Number(ev.timestamp_),
+                                                receiver: ev.receiverAddr,
+                                                day: (0, core_1.toNormalizedBn)(ev.day, 0),
+                                                month: (0, core_1.toNormalizedBn)(ev.month, 0),
+                                                year: (0, core_1.toNormalizedBn)(ev.year, 0),
+                                                amount: (0, core_1.toNormalizedBn)(trueClaimableAmount, decimals),
+                                                date: fullDate,
+                                                vault,
+                                                status: types_1.VaultRedemptionStatus.AWAITING_COOLDOWN,
+                                            });
+                                        }
+                                    }
+                                    break;
+                                }
+                            }
+                        }
+                        catch (contractError) {
+                            core_1.Logger.log.error('getVaultAvailableRedemptions', `Contract call failed: ${contractError}`);
+                        }
+                    }
+                }
+            }
+            else {
+                if (foundRedemptionAgainstClaim) {
+                    availableRedemptions.push({
+                        id: ev.transactionHash_ || ev.id,
+                        hash: ev.transactionHash_ || ev.id,
+                        timestamp: Number(ev.timestamp_),
+                        receiver: ev.receiverAddr,
+                        day: (0, core_1.toNormalizedBn)(ev.day, 0),
+                        month: (0, core_1.toNormalizedBn)(ev.month, 0),
+                        year: (0, core_1.toNormalizedBn)(ev.year, 0),
+                        amount: (0, core_1.toNormalizedBn)(subgraphAmountToBigInt(ev.assets), decimals),
+                        date: fullDate,
+                        vault,
+                        status: types_1.VaultRedemptionStatus.AWAITING_COOLDOWN,
+                    });
+                }
+            }
+        }
+        return {
+            ...{
+                availableRedemptions,
+                pendingRedemptions,
+            },
+            ...(options.verbose && {
+                processedWithdrawals: withdrawalProcesseds,
+                requestedWithdrawals: withdrawalRequesteds,
+            }),
+        };
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultAvailableRedemptions', e, { vault, wallet });
+        return {
+            ...{
+                availableRedemptions: [],
+                pendingRedemptions: [],
+            },
+            ...(options.verbose && {
+                processedWithdrawals: [],
+                requestedWithdrawals: [],
+            }),
+        };
+    }
+}
+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) {
+            core_1.Logger.log.warn('getVaultRedemptionHistory', `Vault not found in backend: ${vault}`);
+            return [];
+        }
+        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; // Max concurrent RPC requests per batch
+        core_1.Logger.log.info('getVaultRedemptionHistory', {
+            vault,
+            version,
+            isV2,
+            chainId,
+            currentBlock,
+            cutoffBlock,
+            blockSkip,
+            totalRangeBlocks: currentBlock - cutoffBlock,
+        });
+        // Build all query ranges
+        const ranges = [];
+        let endBlock = currentBlock;
+        while (endBlock >= cutoffBlock) {
+            const fromBlock = Math.max(endBlock - blockSkip, cutoffBlock);
+            ranges.push({ from: fromBlock, to: endBlock });
+            endBlock = fromBlock - 1;
+        }
+        core_1.Logger.log.info('getVaultRedemptionHistory', {
+            totalBatches: Math.ceil(ranges.length / BATCH_SIZE),
+            totalChunks: ranges.length,
+            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);
+            const batchResults = await Promise.allSettled(batch.map((r) => poolContract.queryFilter('WithdrawalProcessed', BigInt(r.from), BigInt(r.to))));
+            const failed = batchResults.filter((r) => r.status === 'rejected');
+            if (failed.length > 0) {
+                const firstReason = failed[0].reason;
+                const firstMessage = firstReason instanceof Error
+                    ? firstReason.message
+                    : String(firstReason);
+                // Breadcrumb only — the throw below is caught and logged by this
+                // function's own catch block, so capturing here duplicated every
+                // failure into a second Sentry issue ("log fetch chunk(s) failed").
+                core_1.Logger.log.warn('getVaultRedemptionHistory', {
+                    reason: 'log fetch chunk(s) failed',
+                    failedChunks: failed.length,
+                    totalChunks: batch.length,
+                    firstReason: firstMessage,
+                });
+                throw new Error(`Failed to fetch WithdrawalProcessed logs (${failed.length}/${batch.length} chunk(s) rejected): ${firstMessage}`);
+            }
+            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)',
+            ]
+            : [
+                '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))];
+            const blockResults = await Promise.all(uniqueBlocks.map((bn) => provider.getBlock(bn)));
+            const timestamps = new Map();
+            blockResults.forEach((block) => {
+                if (block)
+                    timestamps.set(block.number, block.timestamp);
+            });
+            blockTimestamps = timestamps;
+        }
+        // format — iterate logs directly to preserve transactionHash
+        const redemptions = [];
+        logs.forEach((log) => {
+            const ev = iface.parseLog(log);
+            if (!ev?.args)
+                return;
+            let item;
+            if (isV2) {
+                const [assetsAmount, receiverAddr] = ev.args;
+                const blockTs = blockTimestamps?.get(log.blockNumber) ?? 0;
+                const blockDate = new Date(blockTs * 1000);
+                item = {
+                    receiver: receiverAddr,
+                    amount: (0, core_1.toNormalizedBn)(assetsAmount, decimals),
+                    processed: blockDate,
+                    requested: new Date(0), // evm-2 event has no requestedOn field; epoch 0 is a sentinel for "unknown"
+                    vault,
+                    transactionHash: log.transactionHash,
+                };
+            }
+            else {
+                const [assetsAmount, processedOn, receiverAddr, requestedOn] = ev.args;
+                item = {
+                    receiver: receiverAddr,
+                    amount: (0, core_1.toNormalizedBn)(assetsAmount, decimals),
+                    processed: new Date(Number(processedOn) * 1000),
+                    requested: new Date(Number(requestedOn) * 1000),
+                    vault,
+                    transactionHash: log.transactionHash,
+                };
+            }
+            if (wallet) {
+                if (item.receiver?.toLowerCase() === wallet.toLowerCase()) {
+                    redemptions.push(item);
+                }
+            }
+            else {
+                redemptions.push(item);
+            }
+        });
+        core_1.Logger.log.info('getVaultRedemptionHistory', redemptions.slice(0, 1));
+        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;
+    }
+}
+// Moved to core/helpers/swap-router.ts to break the adapters/evm ↔
+// modules/vaults/getters import cycle (CLAUDE.md §9); re-exported here for
+// back-compat with existing importers.
+var swap_router_1 = require("../../core/helpers/swap-router");
+Object.defineProperty(exports, "getSwapRouterDepositResult", { enumerable: true, get: function () { return swap_router_1.getSwapRouterDepositResult; } });
+/**
+ * Vault Positions
+ */
+async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, prefetchedReads, }) {
+    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';
+            if (BigInt(_balance.raw) > BigInt(0))
+                return 'STAKED';
+            return 'PENDING';
+        }
+        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);
+                        const vaultStateRes = await options.solanaService.getVaultState(vaultProgramId, SolanaConstants.vaultIdl, v.solana_vault_metadata?.vault_state_pda ?? undefined);
+                        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: [],
+                        pendingRedemptions: [],
+                        redeemable: balance,
+                        walletBalance: balance,
+                    };
+                }
+                if ((0, utils_3.isStellarAddress)(v.address)) {
+                    let balance = (0, core_1.toNormalizedBn)(0);
+                    if (stellarWallet && (0, utils_3.isStellarAddress)(stellarWallet)) {
+                        const stellarNetwork = v.stellar_vault_metadata?.network_name ?? 'mainnet';
+                        // Only use the configured RPC override for its own network.
+                        const stellarOverrideRpcUrl = options.stellarRpc?.network === stellarNetwork
+                            ? options.stellarRpc.rpcUrl
+                            : undefined;
+                        const position = await StellarGetters.getStellarUserPosition(v.address, stellarWallet, stellarNetwork, stellarOverrideRpcUrl);
+                        if (position && !position.decimalsFromFallback) {
+                            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 {
+                            core_1.Logger.log.warn('getVaultPositions', 'Stellar position query failed — showing zero balance', { vault: v.address, wallet: stellarWallet });
+                        }
+                    }
+                    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),
+                        availableRedemptions: [],
+                        pendingRedemptions: [],
+                        redeemable: (0, core_1.toNormalizedBn)(0),
+                        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,
+                });
+                // Batched reads only apply to the vault this call was made for —
+                // guard against a multi-row backend response reusing them.
+                const prefetched = v.address?.toLowerCase?.() === String(vault).toLowerCase()
+                    ? prefetchedReads
+                    : undefined;
+                // get vault metadata and balance based on version
+                let bal = BigInt(0);
+                if (version === 'evm-2') {
+                    const receiptAddress = await (0, core_1.getReceiptTokenAddress)(provider, vault);
+                    decimals = await (0, core_1.getDecimals)(provider, receiptAddress, false);
+                    if (wallet && (0, ethers_1.isAddress)(wallet)) {
+                        if (typeof prefetched?.balance === 'bigint') {
+                            bal = prefetched.balance;
+                        }
+                        else {
+                            const receiptContract = (0, core_1.createContract)({
+                                provider,
+                                abi: TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
+                                address: receiptAddress,
+                            });
+                            bal = await receiptContract.balanceOf(wallet);
+                        }
+                    }
+                }
+                else {
+                    decimals = await (0, core_1.getDecimals)(provider, vault);
+                    if (wallet && (0, ethers_1.isAddress)(wallet)) {
+                        bal =
+                            typeof prefetched?.balance === 'bigint'
+                                ? prefetched.balance
+                                : await vaultContract.balanceOf(wallet);
+                    }
+                }
+                const balance = (0, core_1.toNormalizedBn)(bal, decimals);
+                // check available redemptions
+                const { availableRedemptions, pendingRedemptions } = await getVaultAvailableRedemptions({
+                    vault: v.address,
+                    wallet,
+                    options,
+                    prefetchedReads: prefetched,
+                });
+                // 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),
+                    availableRedemptions,
+                    pendingRedemptions,
+                    redeemable: (0, core_1.toNormalizedBn)(aggregateAvailableRedemptions, decimals),
+                    walletBalance: balance,
+                };
+            }
+            catch (vaultError) {
+                core_1.Logger.log.error(`getVaultPositions`, `Error processing vault ${v.address}: ${vaultError}`);
+                return {
+                    vault,
+                    status: 'PENDING',
+                    availableRedemptions: [],
+                    pendingRedemptions: [],
+                    redeemable: (0, core_1.toNormalizedBn)(0),
+                    walletBalance: (0, core_1.toNormalizedBn)(0),
+                };
+            }
+        }));
+        return promises.flat();
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultPositions', e, {
+            vault,
+            wallet,
+            solanaWallet,
+            stellarWallet,
+        });
+        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 [
+                {
+                    value: tokenizedVault?.reported_apy?.apy || 0,
+                    timestamp: new Date().toISOString(),
+                },
+            ];
+        }
+        else {
+            // historical apy
+            function paramBuilder(params, baseUrl) {
+                if (!params)
+                    return '';
+                const urlParams = new URLSearchParams();
+                if (params.daysAgo)
+                    urlParams.append('days_ago', params.daysAgo.toString());
+                if (params.order)
+                    urlParams.append('order', params.order.toString());
+                if (params.interval)
+                    urlParams.append('interval', params.interval.toString());
+                const query = urlParams.toString();
+                if (!query)
+                    return '';
+                return baseUrl?.includes('?') ? `&${query}` : `?${query}`;
+            }
+            const baseUrl = core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.historicalApy(vault);
+            const historicalApy = await (0, core_1.fetchAugustPublic)(`${baseUrl}${paramBuilder(historical, baseUrl)}`, {
+                headers: options?.headers
+                    ? options?.headers
+                    : undefined,
+            });
+            if (!historicalApy.ok)
+                throw new Error('Failed to fetch historical apy.');
+            const historicalApyData = (await historicalApy.json());
+            return historicalApyData.data.values.map((val, index) => {
+                const respectiveDate = historicalApyData.data.labels[index];
+                return {
+                    timestamp: new Date(respectiveDate).toISOString(),
+                    value: val,
+                };
+            });
+        }
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultApy', e, { vault });
+        throw new Error(`#getVaultApy::${vault}:${e?.message}`);
+    }
+}
+async function getRewardsStakingPositions({ rpcUrl, wallet, coinGeckoKey, }) {
+    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 [];
+        }
+        if (wallet && !(0, ethers_1.isAddress)(wallet)) {
+            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)({
+                address: stakingTokenAddress,
+                provider: provider,
+                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) {
+                const formattedWallet = (0, ethers_1.getAddress)(wallet);
+                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;
+            const STAKED_APR = ((Number(normalizedRewardsPerSecond?.normalized) *
+                APR_MULTIPLIER *
+                rewardTokenPriceToMultiply) /
+                (Number(normalizedTotalStakedInPool?.normalized) * Number(1))) *
+                100;
+            const MAX_APR = ((Number(normalizedRewardsPerSecond?.normalized) *
+                APR_MULTIPLIER *
+                rewardTokenPriceToMultiply) /
+                (Number(normalizedTotalStakedInPool?.normalized) * Number(1))) *
+                100;
+            const activePosition = {
+                id: String(i),
+                rewardToken: {
+                    decimals: REWARDS_DECIMALS,
+                    symbol: REWARDS_SYMBOL,
+                    address: ethers_1.ZeroAddress,
+                    chain: REWARDS_CHAIN,
+                    redeemable: normalizedRedeemable,
+                    usd: normalizedRewardTokenPrice,
+                    name: REWARDS_NAME,
+                },
+                stakingToken: {
+                    decimals: Number(decimals),
+                    symbol: symbol,
+                    address: stakingTokenAddress,
+                    chain: REWARDS_CHAIN,
+                    totalStaked: normalizedTotalStakedBalance,
+                    usd: normalizedRewardTokenPrice,
+                    totalSupply: normalizedTotalStakedInPool,
+                    name: name,
+                },
+                rewardDistributor: contract,
+                rewardPerSecond: (0, core_1.toNormalizedBn)(rewardsPerSecond),
+                apy: STAKED_APR,
+                maxApy: MAX_APR,
+                chainId: REWARDS_CHAIN,
+            };
+            return activePosition;
+        }));
+        return positions;
+    }
+    catch (e) {
+        core_1.Logger.log.error('getStakingPositions', e, { wallet });
+        return [];
+    }
+}
+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 [
+                    {
+                        value: (0, core_1.toNormalizedBn)(0),
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
+            if (version === 'stellar-0') {
+                const stellarDecimals = _vaultExists?.stellar_vault_metadata?.deposit_token_decimals ??
+                    constants_1.STELLAR_FALLBACK_DECIMALS;
+                return [
+                    {
+                        value: (0, utils_1.backendTvlToNormalizedBn)(_vaultExists?.latest_reported_tvl, stellarDecimals),
+                        timestamp: new Date().toISOString(),
+                    },
+                ];
+            }
+            const provider = (0, core_1.createProvider)(options.rpcUrl, options.chainId);
+            switch (version) {
+                case 'evm-2': {
+                    const receiptTokenAddress = await (0, core_1.getReceiptTokenAddress)(provider, vault);
+                    const receiptTokenDecimals = await (0, core_1.getDecimals)(provider, receiptTokenAddress, false);
+                    const vaultContract = (0, core_1.createContract)({
+                        address: vault,
+                        abi: TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2,
+                        provider,
+                    });
+                    const totalAssets = await vaultContract.getTotalAssets();
+                    return [
+                        {
+                            value: (0, core_1.toNormalizedBn)(totalAssets, receiptTokenDecimals),
+                            timestamp: new Date().toISOString(),
+                        },
+                    ];
+                }
+                default: {
+                    const vaultContract = (0, core_1.createContract)({
+                        address: vault,
+                        abi: abis_1.ABI_LENDING_POOL_V2,
+                        provider,
+                    });
+                    const decimals = await (0, core_1.getDecimals)(provider, vault);
+                    const totalAssets = await vaultContract.totalAssets();
+                    return [
+                        {
+                            value: (0, core_1.toNormalizedBn)(totalAssets, decimals),
+                            timestamp: new Date().toISOString(),
+                        },
+                    ];
+                }
+            }
+            // 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,
+                abi: version === 'evm-2' ? TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2 : abis_1.ABI_LENDING_POOL_V2,
+                provider,
+            });
+            let minAbi = [];
+            let functionName = '';
+            let vaultDecimals = 0;
+            switch (version) {
+                case 'evm-2': {
+                    minAbi = ['function getTotalAssets() view returns (uint256)'];
+                    functionName = 'getTotalAssets';
+                    const receiptTokenAddress = await (0, core_1.getReceiptTokenAddress)(provider, vault);
+                    vaultDecimals = await (0, core_1.getDecimals)(provider, receiptTokenAddress, false);
+                    break;
+                }
+                default: {
+                    minAbi = ['function totalAssets() view returns (uint256)'];
+                    functionName = 'totalAssets';
+                    vaultDecimals = await (0, core_1.getDecimals)(provider, vault);
+                    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
+                : Date.now() * 60 * 1000;
+            const daysAgo = historical.daysAgo * 24 * 60 * 60 * 1000;
+            const dater = new ethereum_block_by_date_1.default(provider);
+            const startDate = historical.daysAgo
+                ? new Date(finalizedTimestamp - daysAgo)
+                : new Date(finalizedTimestamp);
+            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)),
+                    value: (0, core_1.toNormalizedBn)(readableTotalAssetsAtBlock?.[0], vaultDecimals),
+                };
+            }));
+            core_1.Logger.log.info('getVaultTvl:historical', totalAssetsHistorical.length);
+            return totalAssetsHistorical;
+        }
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultTvl', e, { vault });
+        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,
+            address: l.address,
+            abi: abis_1.ABI_LOAN,
+        });
+        const loanState = await loanContract.loanState();
+        if ((0, core_1.loanStateToReadable)(loanState) !== 'ACTIVE')
+            return undefined;
+        return l.address;
+    }));
+    const activeLoans = activeLoanResults
+        .map((r, i) => {
+        if (r.status === 'fulfilled')
+            return r.value;
+        core_1.Logger.log.warn('getVaultBorrowerHealthFactor:loanState', r.reason, {
+            vault,
+            loan: loans[i]?.address,
+        });
+        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,
+            address: l,
+            abi: abis_1.ABI_LOAN,
+        });
+        return {
+            borrower: (await loanContract.borrower()),
+            loan: l,
+        };
+    }));
+    const formattedLoansArray = formattedSettled
+        .map((r, i) => {
+        if (r.status === 'fulfilled')
+            return r.value;
+        core_1.Logger.log.warn('getVaultBorrowerHealthFactor:borrower', r.reason, {
+            vault,
+            loan: activeLoans[i],
+        });
+        return undefined;
+    })
+        .filter((entry) => entry !== undefined);
+    const uniqueBorrowers = [
+        ...new Set(formattedLoansArray.map((l) => l.borrower)),
+    ];
+    const borrowerResponses = {};
+    for (const b of uniqueBorrowers) {
+        try {
+            const response = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.health_factor(b));
+            if (response.status === 200) {
+                borrowerResponses[b] = await response.json();
+            }
+        }
+        catch (err) {
+            core_1.Logger.log.warn('getVaultBorrowerHealthFactor:health_factor', err, {
+                vault,
+                borrower: b,
+            });
+        }
+    }
+    formattedLoansArray.forEach((loan) => {
+        loan.health_factor = borrowerResponses[loan.borrower];
+    });
+    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)) ?? [])
+        : await (0, core_1.fetchTokenizedVaults)(undefined, options?.headers, false, false);
+    const healthFactorResults = await Promise.allSettled(vaults.map(async (v) => {
+        return getVaultBorrowerHealthFactor({
+            vault: v.address,
+            options,
+        });
+    }));
+    const healthFactorsByPool = {};
+    vaults.forEach((pool, index) => {
+        const result = healthFactorResults[index];
+        const key = pool.address.toLowerCase();
+        if (result?.status === 'fulfilled') {
+            healthFactorsByPool[key] = result.value;
+            return;
+        }
+        core_1.Logger.log.warn('getHealthFactorOfBorrowersByVault:vault', result?.reason, {
+            vault: pool.address,
+        });
+        healthFactorsByPool[key] = [];
+    });
+    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) {
+            throw new Error('User address parameter is undefined.');
+        }
+        const endpoint = core_1.WEBSERVER_ENDPOINTS.public.points.byUserAddress(userAddress);
+        const response = await (0, core_1.fetchAugustPublic)(endpoint, {
+            headers: options?.headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch points: ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (e) {
+        core_1.Logger.log.error('getUserPoints', e, { userAddress });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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) {
+            throw new Error('User address parameter is undefined.');
+        }
+        if (!chainId || !signature || !nonce || !expiry) {
+            throw new Error('chainId, signature, nonce, and expiry are required for registering a user');
+        }
+        const response = await (0, core_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.points.register, {
+            method: 'post',
+            server: 'public',
+            headers: options?.headers,
+            data: {
+                user_address: userAddress,
+                ...(referrerAddress && { referrer_address: referrerAddress }),
+                chain_id: chainId,
+                signature,
+                nonce,
+                expiry,
+            },
+        });
+        return response;
+    }
+    catch (e) {
+        core_1.Logger.log.error('registerUserForPoints', e, {
+            userAddress,
+            referrerAddress,
+        });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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 || {};
+        const searchParams = new URLSearchParams({
+            page: page.toString(),
+            perPage: perPage.toString(),
+            sortBy,
+        });
+        const response = await (0, core_1.fetchAugustPublic)(`${core_1.WEBSERVER_ENDPOINTS.public.points.leaderboard}?${searchParams.toString()}`, {
+            headers: options?.headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch leaderboard: ${response.statusText}`);
+        }
+        return await response.json();
+    }
+    catch (e) {
+        core_1.Logger.log.error('fetchPointsLeaderboard', e, { params });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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);
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
+        if (!tokenizedVault) {
+            throw new Error(`Vault ${vault} not found`);
+        }
+        const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        let assetsUpdatedOn;
+        switch (version) {
+            case 'evm-2': {
+                const contract = (0, core_1.createContract)({
+                    provider,
+                    address: vault,
+                    abi: TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2,
+                });
+                assetsUpdatedOn = await contract.assetsUpdatedOn();
+                break;
+            }
+            case 'evm-0': {
+                const contract = (0, core_1.createContract)({
+                    provider,
+                    address: vault,
+                    abi: abis_1.ABI_LENDING_POOL_V3,
+                });
+                assetsUpdatedOn = await contract.assetsUpdatedOn();
+                break;
+            }
+            case 'sol-0':
+            case 'stellar-0': {
+                return 0;
+            }
+            default: {
+                // Old lending pools don't have assetsUpdatedOn function
+                // Return 0 for legacy vaults
+                return 0;
+            }
+        }
+        return Number(assetsUpdatedOn);
+    }
+    catch (e) {
+        core_1.Logger.log.error('getYieldLastRealizedOn', e, { vault });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        throw new Error(`#getYieldLastRealizedOn::${vault}:${errorMessage}`);
+    }
+}
+/**
+ * Guard against the 2026-07-09 lifetime-PnL over-inflation failure mode.
+ *
+ * Lifetime PnL is `currentPosition + totalWithdrawn - totalDeposited`. When the
+ * deposit/withdrawal history fails to load it collapses to empty, so both
+ * `totalDeposited` and `totalWithdrawn` read as zero. If the wallet still holds
+ * a live on-chain position, the formula degenerates to reporting the entire
+ * position as pure profit — a plausible-looking but wrong number.
+ *
+ * This guard rejects exactly that state: a non-zero position with no recorded
+ * deposits *and* no recorded withdrawals. Any of the following is treated as
+ * consistent and passes:
+ * - deposits are present (the normal, computable case);
+ * - withdrawals are present (a fully-exited-then-re-entered position is still
+ *   computable — the withdrawal records prove history loaded);
+ * - the current position is zero (the wallet never interacted or fully exited,
+ *   so a zero PnL is correct, not inflated).
+ *
+ * Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot
+ * path with no added latency.
+ *
+ * Known imprecision — vault shares are transferable ERC-20 receipt tokens, so a
+ * wallet that *received* shares via a direct token transfer (never deposited,
+ * never withdrew) legitimately has `position > 0` with no history records and
+ * will throw `HISTORY_UNAVAILABLE` even though its history loaded fine. This is
+ * not a regression — the pre-guard formula reported that same position as 100%
+ * profit, which was also wrong — but the error message is misleading for that
+ * (rare) path. If receipt-token transfer becomes a real user flow, distinguish
+ * it here (e.g. by checking for a share-transfer event) rather than widening
+ * the guard.
+ *
+ * @param params - See {@link PnlHistoryConsistencyParams}.
+ * @returns `void` when the history is consistent.
+ * @throws {@link AugustHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
+ *   and `context: { vault, wallet }` when a non-zero position has neither
+ *   deposits nor withdrawals recorded. The message carries the
+ *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
+ *   other errors leaving the getter.
+ * @example
+ * ```ts
+ * assertPnlHistoryConsistent({
+ *   vault,
+ *   wallet,
+ *   hasDeposits: depositsByAsset.size > 0,
+ *   totalWithdrawnRaw,
+ *   currentPositionRaw: currentPositionValue.raw,
+ * });
+ * ```
+ */
+function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }) {
+    const positionExists = currentPositionRaw > BigInt(0);
+    const noHistory = !hasDeposits && totalWithdrawnRaw === BigInt(0);
+    if (positionExists && noHistory) {
+        throw new errors_1.AugustHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:transaction history unavailable — a live position exists but no deposits or withdrawals were indexed, so lifetime PnL cannot be computed without over-reporting the entire position as profit`, { context: { vault, wallet } });
+    }
+}
+/**
+ * Sum a wallet's per-asset deposits into the vault's own decimals, at face
+ * value — 1 unit of any deposited asset is treated as 1 unit of the vault's
+ * reporting currency, with no live price conversion.
+ *
+ * Used by {@link getVaultUserLifetimePnl} for `totalDeposited`. Pre-deposit
+ * multi-asset vaults only accept dollar-pegged stablecoins (USDC, USDT, DAI,
+ * USDS, RLUSD, etc.) into a dollar-denominated vault, so face value is a
+ * reasonable stand-in for USD value. This intentionally does NOT re-quote
+ * through a live price oracle: doing so priced a historical deposit at
+ * today's market rate, so `totalDeposited` (and lifetimePnl) drifted between
+ * calls purely from stablecoin peg noise, and approximately re-inflated
+ * deposits back toward face value — which silently excluded the vault's
+ * entry fee from PnL. The fee is money the user actually paid, so PnL must
+ * be computed net of it.
+ *
+ * @param depositsByAsset - Raw deposited amount per asset, keyed by
+ *   lowercased asset address (or `'default'` / `'lz-default'` for
+ *   single-asset / cross-chain rows).
+ * @param assetDecimals - Decimals for each key in `depositsByAsset`.
+ * @param vaultDecimals - The vault's own decimals — the target scale every
+ *   asset is rescaled to.
+ * @returns Total deposited, in raw base units at `vaultDecimals`.
+ */
+function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
+    let total = BigInt(0);
+    for (const [assetAddress, rawAmount] of depositsByAsset) {
+        const assetDec = assetDecimals.get(assetAddress) ?? vaultDecimals;
+        if (assetDec === vaultDecimals) {
+            total += rawAmount;
+        }
+        else if (assetDec > vaultDecimals) {
+            total += rawAmount / BigInt(10 ** (assetDec - vaultDecimals));
+        }
+        else {
+            total += rawAmount * BigInt(10 ** (vaultDecimals - assetDec));
+        }
+    }
+    return total;
+}
+/**
+ * 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
+ *
+ * `totalDeposited` is the face value of what the user actually paid in
+ * (each deposited asset's raw amount, rescaled to the vault's decimals — no
+ * live price conversion), so any entry/exit fee the vault charges is
+ * automatically counted as a cost against PnL rather than excluded from it.
+ * Pre-deposit multi-asset vaults are assumed to only accept dollar-pegged
+ * stablecoins into a dollar-denominated vault; a vault accepting a
+ * non-pegged deposit asset would need deposit-time price conversion, which
+ * this function does not perform.
+ *
+ * @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)
+            throw new Error('Vault input parameter is undefined.');
+        if (!wallet)
+            throw new Error('Wallet input parameter is undefined.');
+        (0, utils_3.assertNotStellar)(vault, 'Lifetime PnL');
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        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),
+            getVaultPositions({
+                vault,
+                wallet,
+                options,
+            }),
+            (0, core_1.fetchTokenizedVault)(vault, options?.headers, false, false),
+        ]);
+        const tokenizedVault = tokenizedVaultResult?.[0];
+        if (!tokenizedVault) {
+            throw new Error(`Vault ${vault} not found`);
+        }
+        // getDecimals resolves to `undefined` on a failed/absent decimals() read.
+        // Unguarded, that undefined flows into `10 ** decimals` (=> NaN) and
+        // toNormalizedBn(x, undefined), and the first BigInt(NaN) throws the opaque
+        // "The number NaN cannot be converted to a BigInt" error. Decimals must come
+        // from the chain — never assume a fallback — so fail fast with actionable
+        // context. Transient RPC blips recover on the caller's retry.
+        if (typeof decimals !== 'number' || !Number.isFinite(decimals)) {
+            throw new Error(`Failed to resolve decimals for vault ${vault}`);
+        }
+        // Fetch LayerZero deposits/redeems for supported vaults
+        const lzVaultKey = (0, deposits_1.isLayerZeroVault)(vault);
+        let lzDeposits = [];
+        let lzRedeems = [];
+        if (lzVaultKey) {
+            const lzPromises = [
+                (0, deposits_1.queryLayerZeroDeposits)(lzVaultKey, wallet)
+                    .then((d) => {
+                    lzDeposits = d;
+                })
+                    .catch((e) => {
+                    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) => {
+                    lzRedeems = r;
+                })
+                    .catch((e) => {
+                    core_1.Logger.log.warn('getVaultUserLifetimePnl:lzRedeems', `Failed to fetch LZ redeems for ${lzVaultKey}: ${e}`);
+                }));
+            }
+            await Promise.all(lzPromises);
+        }
+        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,
+                    abi: abis_1.ABI_LENDING_POOL_V2,
+                });
+                try {
+                    underlyingAssetAddress = (await vaultContract.asset());
+                    const underlyingContract = (0, core_1.createContract)({
+                        provider,
+                        address: underlyingAssetAddress,
+                        abi: abis_1.ABI_ERC20,
+                    });
+                    underlyingTokenSymbol = await underlyingContract.symbol();
+                }
+                catch (e) {
+                    core_1.Logger.log.warn('getVaultUserLifetimePnl:getUnderlyingSymbol', `Failed to get underlying token symbol: ${e}, falling back to receipt token symbol`);
+                    underlyingTokenSymbol =
+                        tokenizedVault.receipt_token_symbol || 'UNKNOWN';
+                }
+            }
+            catch (e) {
+                core_1.Logger.log.warn('getVaultUserLifetimePnl:getUnderlyingSymbol', `Failed to get underlying token symbol: ${e}, falling back to receipt token symbol`);
+                underlyingTokenSymbol =
+                    tokenizedVault.receipt_token_symbol || 'UNKNOWN';
+            }
+            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';
+                const current = depositsByAsset.get(assetKey) ?? BigInt(0);
+                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);
+                depositsByAsset.set(assetKey, current + amount);
+            }
+        }
+        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') {
+                assetDecimals.set(assetAddress, decimals);
+            }
+            else {
+                const dec = await (0, core_1.getDecimals)(provider, assetAddress, false);
+                assetDecimals.set(assetAddress, dec);
+            }
+        }));
+        const totalDepositedNativeRaw = sumDepositsAtFaceValue(depositsByAsset, assetDecimals, decimals);
+        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)
+            : Promise.resolve(0);
+        const vaultContract = (0, core_1.createContract)({
+            provider,
+            address: vault,
+            abi: version === 'evm-2' ? TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2 : abis_1.ABI_LENDING_POOL_V2,
+        });
+        let sharePriceRaw = BigInt(0);
+        try {
+            // Retried on transport blips only (bounded, no fallback); a vault that
+            // genuinely has no `lpTokenAddress()` still throws into the catch below.
+            const lpTokenAddress = version === 'evm-2'
+                ? await (0, core_1.getReceiptTokenAddressOrThrow)(provider, vault, 'getVaultUserLifetimePnl:receiptToken')
+                : vault;
+            let currentShares = BigInt(0);
+            if (version === 'evm-2') {
+                const lpTokenContract = (0, core_1.createContract)({
+                    provider,
+                    address: lpTokenAddress,
+                    abi: TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
+                });
+                currentShares = await lpTokenContract.balanceOf(wallet);
+            }
+            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) {
+                        if (rti.chain !== tokenizedVault.chain &&
+                            rti.address &&
+                            rti.chain) {
+                            remoteChains.push({
+                                chain: rti.chain,
+                                address: rti.address,
+                            });
+                        }
+                    }
+                }
+                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)) {
+                            const chainId = Number(chainIdStr);
+                            if (chainId !== tokenizedVault.chain) {
+                                remoteChains.push({
+                                    chain: chainId,
+                                    address: address,
+                                });
+                            }
+                        }
+                    }
+                }
+                if (remoteChains.length > 0) {
+                    const remoteBalances = await Promise.all(remoteChains.map(async ({ chain, address }) => {
+                        try {
+                            const rpcUrls = (0, core_1.getFallbackRpcUrls)(chain);
+                            if (!rpcUrls.length) {
+                                core_1.Logger.log.warn('getVaultUserLifetimePnl:lzRemoteBalance', `No RPC URL for chain ${chain}, skipping balance check`);
+                                return BigInt(0);
+                            }
+                            const remoteProvider = (0, core_1.createProvider)(rpcUrls[0]);
+                            const remoteTokenContract = (0, core_1.createContract)({
+                                provider: remoteProvider,
+                                address,
+                                abi: abis_1.ABI_ERC20,
+                            });
+                            const [rawBalance, remoteDecimals] = await Promise.all([
+                                remoteTokenContract.balanceOf(wallet),
+                                remoteTokenContract.decimals(),
+                            ]);
+                            const remDec = Number(remoteDecimals) || decimals;
+                            // Normalize remote balance to hub chain decimals
+                            if (remDec > decimals) {
+                                return rawBalance / BigInt(10 ** (remDec - decimals));
+                            }
+                            else if (remDec < decimals) {
+                                return rawBalance * BigInt(10 ** (decimals - remDec));
+                            }
+                            return rawBalance;
+                        }
+                        catch (e) {
+                            core_1.Logger.log.warn('getVaultUserLifetimePnl:lzRemoteBalance', `Failed to fetch balance on chain ${chain}: ${e}`);
+                            return BigInt(0);
+                        }
+                    }));
+                    for (const bal of remoteBalances) {
+                        currentShares += bal;
+                    }
+                }
+            }
+            if (version === 'evm-2') {
+                sharePriceRaw = await vaultContract.getSharePrice();
+            }
+            else {
+                const [totalAssets, totalSupply] = await Promise.all([
+                    vaultContract.totalAssets(),
+                    vaultContract.totalSupply(),
+                ]);
+                if (totalSupply === BigInt(0)) {
+                    sharePriceRaw = BigInt(10 ** decimals); // 1:1 if no supply
+                }
+                else {
+                    sharePriceRaw = (totalAssets * BigInt(10 ** decimals)) / totalSupply;
+                }
+            }
+            const currentPositionValueRaw = (currentShares * sharePriceRaw) / BigInt(10 ** decimals);
+            currentPositionValue = (0, core_1.toNormalizedBn)(currentPositionValueRaw, decimals);
+        }
+        catch (e) {
+            core_1.Logger.log.warn('getVaultUserLifetimePnl:getCurrentSharesAndPrice', `Failed to get current shares and share price: ${e}, falling back to wallet balance`);
+            if (currentPosition?.walletBalance) {
+                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);
+        // Guard the 2026-07-09 over-inflation incident: a live position with no
+        // deposits *and* no withdrawals means the history failed to load, and the
+        // PnL formula would report the whole position as profit. Fail loudly with a
+        // typed error instead of returning a fabricated number.
+        assertPnlHistoryConsistent({
+            vault,
+            wallet,
+            hasDeposits: depositsByAsset.size > 0,
+            totalWithdrawnRaw,
+            currentPositionRaw: BigInt(currentPositionValue.raw),
+        });
+        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`);
+        }
+        // totalDeposited is already in the vault's own decimals (face value,
+        // computed above) — convert to USD with the same underlying price used
+        // for the other two legs below, so all three legs share one conversion
+        // factor instead of drifting independently against each other.
+        const totalDeposited = (0, core_1.toNormalizedBn)(totalDepositedNativeRaw, decimals);
+        const totalDepositedUsd = Number(totalDeposited.normalized) * effectiveTokenPrice;
+        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;
+        // 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 lifetimePnlUsd to native units
+        const lifetimePnlUsdScaled = BigInt(Math.round(lifetimePnlUsd * Number(scaleFactor)));
+        const lifetimePnlRaw = tokenPriceScaled > BigInt(0)
+            ? (lifetimePnlUsdScaled * BigInt(10 ** decimals)) / tokenPriceScaled
+            : BigInt(0);
+        const lifetimePnl = (0, core_1.toNormalizedBn)(lifetimePnlRaw, decimals);
+        const pnlPercentage = totalDepositedUsd > 0
+            ? Number.parseFloat(((lifetimePnlUsd / totalDepositedUsd) * 100).toFixed(2))
+            : 0;
+        return {
+            tokenSymbol: underlyingTokenSymbol,
+            totalDeposited,
+            totalDepositedUsd,
+            totalWithdrawn,
+            totalWithdrawnUsd,
+            currentPositionValue,
+            currentPositionValueUsd,
+            lifetimePnl,
+            lifetimePnlUsd,
+            pnlPercentage,
+        };
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultUserLifetimePnl', e, { vault, wallet });
+        // Preserve the typed history guard so callers can distinguish an
+        // unavailable-history failure from a generic getter error. Its message
+        // already carries the `#getVaultUserLifetimePnl::vault::wallet` prefix.
+        if (e instanceof errors_1.AugustHistoryUnavailableError)
+            throw e;
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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)
+            throw new Error('Vault input parameter is undefined.');
+        (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,
+            allocations: false,
+            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) {
+            return {
+                totalPnl: (0, core_1.toNormalizedBn)(0, vaultData.decimals),
+                pnlUsd: 0,
+            };
+        }
+        if (!vaultData.historical_snapshots ||
+            !Array.isArray(vaultData.historical_snapshots) ||
+            vaultData.historical_snapshots.length === 0) {
+            return {
+                totalPnl: (0, core_1.toNormalizedBn)(0, vaultData.decimals),
+                pnlUsd: 0,
+            };
+        }
+        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]; // 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?.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);
+        }
+        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,
+            pnlUsd,
+        };
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultPnl', e, { vault });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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)
+            throw new Error('Vault input parameter is undefined.');
+        const response = await (0, core_1.fetchVaultHistoricalTimeseries)(vault, nDays, options?.headers);
+        return response;
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultHistoricalTimeseries', e, { vault, nDays });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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) {
+            throw new Error('Vault address parameter is undefined.');
+        }
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const endpoint = core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.annualizedApy(vault);
+        const response = await (0, core_1.fetchAugustPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch annualized APY: ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultAnnualizedApy', e, { vault });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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) {
+            throw new Error('Vault address parameter is undefined.');
+        }
+        (0, utils_3.assertNotStellar)(vault, 'Vault summary');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const endpoint = core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.summary(vault);
+        const response = await (0, core_1.fetchAugustPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch vault summary: ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultSummary', e, { vault });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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) {
+            throw new Error('Vault address parameter is undefined.');
+        }
+        (0, utils_3.assertNotStellar)(vault, 'Vault withdrawals');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        if (!chain) {
+            throw new Error('Chain parameter is undefined.');
+        }
+        const endpoint = core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.withdrawals(chain, vault);
+        const response = await (0, core_1.fetchAugustPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch vault withdrawals: ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultWithdrawals', e, { vault, chain });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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)
+            throw new Error('Vault address parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        if (pastDays !== undefined && (pastDays < 1 || pastDays > 30))
+            throw new Error('pastDays must be between 1 and 30');
+        if (futureDays !== undefined && (futureDays < 1 || futureDays > 30))
+            throw new Error('futureDays must be between 1 and 30');
+        const params = new URLSearchParams();
+        if (pastDays !== undefined)
+            params.set('past_days', pastDays.toString());
+        if (futureDays !== undefined)
+            params.set('future_days', futureDays.toString());
+        const qs = params.toString();
+        const endpoint = `${core_1.WEBSERVER_ENDPOINTS.public.vaults.pendingRedemptions(vault)}${qs ? `?${qs}` : ''}`;
+        const response = await (0, core_1.fetchAugustPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch pending redemptions: ${response.statusText}`);
+        }
+        const raw = await response.json();
+        return {
+            vault: {
+                address: raw.vault.address,
+                chainId: raw.vault.chain_id,
+                name: raw.vault.name,
+                symbol: raw.vault.symbol,
+            },
+            asset: {
+                address: raw.asset.address,
+                symbol: raw.asset.symbol,
+                decimals: raw.asset.decimals,
+            },
+            liquidity: {
+                available: raw.liquidity.available,
+            },
+            summary: {
+                totalPending: raw.summary.total_pending,
+                pendingCount: raw.summary.pending_count,
+                pendingToLiquidityRatio: raw.summary.pending_to_liquidity_ratio,
+                isLiquiditySufficient: raw.summary.is_liquidity_sufficient,
+                shortfall: raw.summary.shortfall,
+                nextRedemptionDate: raw.summary.next_redemption_date,
+                isOverdue: raw.summary.is_overdue,
+            },
+            redemptionsByDate: raw.redemptions_by_date.map((item) => ({
+                date: item.date,
+                assets: item.assets,
+                daysUntilDue: item.days_until_due,
+                isOverdue: item.is_overdue,
+            })),
+        };
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultPendingRedemptions', e, {
+            vault,
+            pastDays,
+            futureDays,
+        });
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        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 an INormalizedNumber with `normalized` and `raw` fields
+ */
+async function getPreviewRedemption({ vault, sharesAmount, options, }) {
+    try {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        (0, utils_3.assertNotStellar)(vault, 'Preview redemption');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const provider = (0, core_1.createProvider)(options.rpcUrl);
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        let assets;
+        let decimals;
+        if (vaultVersion === 'evm-2') {
+            const contract = (0, core_1.createContract)({
+                address: vault,
+                abi: TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2,
+                provider,
+            });
+            // Retried on transport blips only (bounded, no fallback); a misroute
+            // still surfaces the original error.
+            const lpTokenAddress = await (0, core_1.getReceiptTokenAddressOrThrow)(provider, vault, 'getPreviewRedemption:receiptToken');
+            const lpTokenContract = (0, core_1.createContract)({
+                address: lpTokenAddress,
+                abi: abis_1.ABI_LENDING_POOL_V2,
+                provider,
+            });
+            decimals = Number(await lpTokenContract.decimals());
+            const sharesBigInt = BigInt((0, core_1.toNormalizedBn)(sharesAmount, decimals).raw);
+            const [assetsAmount] = await contract.previewRedemption(sharesBigInt, false);
+            assets = assetsAmount;
+        }
+        else {
+            const contract = (0, core_1.createContract)({
+                address: vault,
+                abi: abis_1.ABI_LENDING_POOL_V2,
+                provider,
+            });
+            decimals = Number(await contract.decimals());
+            const sharesBigInt = BigInt((0, core_1.toNormalizedBn)(sharesAmount, decimals).raw);
+            assets = await contract.previewRedeem(sharesBigInt);
+        }
+        return (0, core_1.toNormalizedBn)(assets, decimals);
+    }
+    catch (e) {
+        core_1.Logger.log.error('previewRedemption', e, { vault, sharesAmount });
+        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) {
+        return {
+            functionName: 'unknown',
+            year: 0,
+            month: 0,
+            day: 0,
+            error: 'Transaction not found',
+        };
+    }
+    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:
+ *   - `vault` — Vault address to query.
+ *   - `receiver` — (Optional) Filter by receiver address.
+ *   - `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.
+ *   - `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}`);
+            return [];
+        }
+        const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        const isV2 = version === 'evm-2';
+        const vaultAbi = isV2 ? TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2 : abis_1.ABI_LENDING_POOL_V2;
+        const vaultContract = (0, core_1.createContract)({
+            address: vaultAddress,
+            abi: vaultAbi,
+            provider,
+        });
+        let lagDuration = 86400; // Default: 1 day
+        try {
+            const lagValue = await vaultContract.lagDuration?.();
+            if (lagValue !== undefined && lagValue !== null) {
+                lagDuration = Number(lagValue);
+            }
+        }
+        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({
+                vault: vaultAddress,
+                wallet: receiver,
+                lookbackBlocks,
+                options,
+            }),
+            provider.getBlockNumber(),
+        ]);
+        if (!withdrawalRequests.length) {
+            return [];
+        }
+        const chainId = tokenizedVault.chain;
+        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()) {
+                return false;
+            }
+            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);
+                    if (!decoded.error) {
+                        return {
+                            ...processed,
+                            decodedDate: {
+                                year: decoded.year,
+                                month: decoded.month,
+                                day: decoded.day,
+                            },
+                        };
+                    }
+                }
+                catch (e) {
+                    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,
+                    decodedDate: {
+                        year: fallbackDate.year,
+                        month: fallbackDate.month,
+                        day: fallbackDate.day,
+                    },
+                };
+            }
+            // 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,
+                decodedDate: {
+                    year: processedDate.getUTCFullYear(),
+                    month: processedDate.getUTCMonth() + 1,
+                    day: processedDate.getUTCDate(),
+                },
+            };
+        }));
+        // 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) {
+                continue;
+            }
+            const dateKey = (0, date_utils_1.formatDateKey)(processed.decodedDate.year, processed.decodedDate.month, processed.decodedDate.day);
+            const key = `${processed.receiver.toLowerCase()}:${dateKey}`;
+            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';
+                processedTxHash = processedEvent.transactionHash;
+                try {
+                    assetsReceived = BigInt(processedEvent.amount.raw);
+                }
+                catch (e) {
+                    core_1.Logger.log.warn(`Failed to parse assets as BigInt: ${e}`);
+                }
+            }
+            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({
+                transactionHash: req.transactionHash_,
+                requestTimestamp,
+                shares: (() => {
+                    try {
+                        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`);
+                            return BigInt(0);
+                        }
+                        core_1.Logger.log.info('getWithdrawalRequestsWithStatus', `Truncated decimal shares "${req.shares}" → ${truncated}`);
+                        return BigInt(truncated);
+                    }
+                })(),
+                receiver: req.receiverAddr,
+                claimableDate: {
+                    year: claimableDate.year,
+                    month: claimableDate.month,
+                    day: claimableDate.day,
+                },
+                claimableEpoch: claimableDate.epoch,
+                status,
+                processedTransactionHash: processedTxHash,
+                assetsReceived,
+            });
+        }
+        return results;
+    }
+    catch (e) {
+        core_1.Logger.log.error('getWithdrawalRequestsWithStatus', e, {
+            vaultAddress: params.vault,
+            hasReceiver: !!params.receiver,
+        });
+        throw new Error(`Failed to get withdrawal requests with status: ${e instanceof Error ? e.message : 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=getters.js.map