@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/modules/vaults/getters.js

@@ -0,0 +1,4079 @@
+"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.assertPnlTokenPrice = assertPnlTokenPrice;
+exports.sumDepositsAtFaceValue = sumDepositsAtFaceValue;
+exports.selectPeerTransfers = selectPeerTransfers;
+exports.transferCostBasis = transferCostBasis;
+exports.historyCoversMints = historyCoversMints;
+exports.selectReserveDeposits = selectReserveDeposits;
+exports.countWithdrawalRequestsOnce = countWithdrawalRequestsOnce;
+exports.settleV2Redemptions = settleV2Redemptions;
+exports.pnlCostBasis = pnlCostBasis;
+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 cache_1 = require("../../core/cache");
+const concurrency_1 = require("../../core/helpers/concurrency");
+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 withdrawal_queue_1 = require("../../adapters/solana/withdrawal-queue");
+const web3_js_1 = require("@solana/web3.js");
+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 untangled_1 = require("../../services/untangled");
+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. EVM vaults only — there is no
+ *   non-EVM loan book to read, so other families keep the empty default.
+ * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+ *   vaults (via DeBank), Stellar vaults (via the Untangled portfolio API) and
+ *   Solana vaults (each operator's cached Octav portfolio). Sui has no
+ *   portfolio provider and keeps the empty default.
+ * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
+ * @returns Complete vault object with optional enrichments
+ * @throws {@link UpshiftNetworkError} (`NETWORK_ERROR`) when `allocations` is
+ *   requested and a borrower's portfolio read (DeBank for EVM, Octav for
+ *   Solana) fails. The whole call fails rather than returning the vault with
+ *   empty allocations; pass `allocations: false` for a read that does not
+ *   depend on the portfolio provider.
+ */
+async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }) {
+    let returnedVault;
+    // Hoisted out of the try so the allocations enrichment below can reuse the
+    // row instead of re-fetching it.
+    let tokenizedVault;
+    try {
+        tokenizedVault =
+            prefetchedRow ??
+                (await (0, core_1.fetchTokenizedVault)(vault, options?.headers, loadSubaccounts, loadSnapshots))?.[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) {
+        // A provider fault (rate limit, socket reset, an empty response to one of
+        // the vault's argument-free views) is not an SDK or caller defect: the
+        // caller sees the same throw either way, so it is recorded as a breadcrumb
+        // rather than a billed Sentry issue. Everything else stays at error.
+        (0, core_1.logChainError)('getVault', err, (0, core_1.isRetryableRpcError)(err) || (0, core_1.isEmptyViewResponse)(err), { vault });
+        throw new Error(`#getVault::${vault}: ${err?.message}`);
+    }
+    // Loans enrichment stays EVM-only — there is no non-EVM loan book to read.
+    // Allocations additionally covers Stellar (Untangled) and Solana (Octav, per
+    // operator); gating it on `isEvmVault` left `getVaultAllocations` unreachable
+    // for both, so callers got the empty default while the standalone getter
+    // returned real data. Sui has no provider and keeps the empty default.
+    const isEvmVault = returnedVault.version !== 'sol-0' &&
+        returnedVault.version !== 'stellar-0' &&
+        returnedVault.version !== 'sui-0';
+    const supportsLoans = isEvmVault;
+    const supportsAllocations = isEvmVault ||
+        returnedVault.version === 'stellar-0' ||
+        returnedVault.version === 'sol-0';
+    const readLoans = loans && supportsLoans;
+    const readAllocations = allocations && supportsAllocations;
+    if ((loans && !supportsLoans) || (allocations && !supportsAllocations)) {
+        core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for this vault — skipping', { vault, version: returnedVault.version });
+    }
+    if (!(0, core_1.isBadVault)(vault) && (readLoans || readAllocations)) {
+        // `getVaultAllocations` reads `.subaccounts`/`.eoa_operators` off the row to
+        // discover borrowers, so the row is withheld unless it can carry them and
+        // the getter fetches a full one itself. Both guards matter: `loadSubaccounts:
+        // false` can answer with the keys present but empty, and a row threaded in
+        // from `getVaults` comes from the list endpoint rather than this one. Getting
+        // either wrong resolves zero borrowers with no error — the silent-empty
+        // failure this de-duplication exists to avoid.
+        const allocationsRow = loadSubaccounts !== false &&
+            tokenizedVault?.subaccounts &&
+            tokenizedVault?.eoa_operators
+            ? tokenizedVault
+            : undefined;
+        const [loansResult, allocationsResult] = await Promise.allSettled([
+            readLoans
+                ? getVaultLoans(returnedVault, options)
+                : Promise.resolve(undefined),
+            readAllocations
+                ? getVaultAllocations(vault, options, allocationsRow)
+                : Promise.resolve(undefined),
+        ]);
+        if (readLoans) {
+            if (loansResult.status === 'fulfilled') {
+                returnedVault = {
+                    ...returnedVault,
+                    loans: loansResult.value,
+                };
+            }
+            else {
+                core_1.Logger.log.error('getVault:loans', loansResult.reason, {
+                    symbol: returnedVault.receipt.symbol,
+                });
+            }
+        }
+        if (readAllocations) {
+            if (allocationsResult.status === 'fulfilled') {
+                returnedVault = {
+                    ...returnedVault,
+                    allocations: allocationsResult.value,
+                };
+            }
+            else {
+                core_1.Logger.log.error('getVault:allocations', allocationsResult.reason, {
+                    symbol: returnedVault.receipt.symbol,
+                });
+                // Fail the whole read, matching EVM: a vault returned without the
+                // allocations the caller asked for would be indistinguishable from
+                // one that has none. Callers that prefer a partial vault can retry
+                // with `allocations: false`.
+                throw new errors_1.UpshiftNetworkError('getVault: failed to fetch vault allocations from the portfolio provider. Retry, or call getVault with allocations: false.', {
+                    context: { vault: String(vault) },
+                    cause: allocationsResult.reason,
+                });
+            }
+        }
+    }
+    return returnedVault;
+}
+/**
+ * Shared implementation behind {@link getVaultLoans} and
+ * {@link getVaultSubaccountLoans}, which differ only in which backend loan
+ * list they read and in the label used for logs and error messages.
+ *
+ * Returns `[]` for any vault that is not `evm-0` (only evm-0 lending pools
+ * have loans). Otherwise fetches the loan list once, reads the pool's
+ * `totalSupply` and decimals on-chain when `vault` is an address (skipped
+ * when a full `IVault` is passed), and reads one loan-oracle fee rate per
+ * loan in parallel.
+ *
+ * @param vault - Vault address, or an already-loaded `IVault`.
+ * @param options - RPC URL, optional chain ID override, and monitoring headers.
+ * @param fetchLoans - Backend fetcher for the loan list
+ *   (`fetchTokenizedVaultLoans` or `fetchTokenizedVaultSubaccountLoans`).
+ * @param label - Public method name used in the log entry and error message.
+ * @returns The formatted loans.
+ * @throws Error prefixed `#<label>::<vault>:` when any fetch fails.
+ */
+async function buildVaultLoans(vault, options, fetchLoans, label) {
+    // sanitize
+    const vaultAddress = typeof vault === 'string' ? vault : vault.address;
+    const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress, options?.headers, false, false))?.[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 fetchLoans(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 upshift 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(label, e, { vault });
+        throw new Error(`#${label}::${vault}:${e?.message}`);
+    }
+}
+/**
+ * Vault Loans
+ */
+async function getVaultLoans(vault, options) {
+    return buildVaultLoans(vault, options, core_1.fetchTokenizedVaultLoans, 'getVaultLoans');
+}
+/**
+ * Vault Subaccount Loans
+ */
+async function getVaultSubaccountLoans(vault, options) {
+    return buildVaultLoans(vault, options, core_1.fetchTokenizedVaultSubaccountLoans, 'getVaultSubaccountLoans');
+}
+/**
+ * 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.
+ *
+ * `400` is here for the same reason. The CeFi and OTC endpoints answer `400`
+ * for a borrower they do not track — a well-formed, checksummed EVM address
+ * that simply has no record on that side — and every `getVaultAllocations`
+ * call re-asks for the same untracked borrowers on every render. In Sentry
+ * that produced ~2.7k `UpshiftServerError: Request failed: 400` events across
+ * two issues in two days, all from the same handful of borrowers, none of them
+ * actionable. Both fetches are strictly best-effort enrichment: the vault's
+ * allocations are returned either way, so a `400` here can never mean the
+ * caller's request was malformed.
+ *
+ * This demotes the *log severity* only — nothing about the response handling
+ * changes, and any other status (401, 5xx, transport failures) is still an
+ * error-level Sentry issue.
+ *
+ * **Maintainer note on the `400` entry specifically.** Unlike `204`/`404`, a
+ * `400` is semantically "the client sent something wrong", so this demotion is
+ * safe only for as long as these two endpoints use `400` to mean "unknown
+ * borrower". If either ever starts returning `400` for a genuinely malformed
+ * request — a real defect in how the SDK builds the URL or body — this set
+ * would silence it. Should that contract change, drop `400` from here and let
+ * the backend distinguish the two cases with a status of its own.
+ */
+const EXPECTED_SUBACCOUNT_FETCH_STATUSES = new Set([204, 400, 404]);
+/**
+ * How long a per-borrower CeFi/OTC enrichment result stays cached, in ms.
+ *
+ * `getVaultAllocations` asks for the same borrowers on every call, and a vault
+ * page re-renders far more often than a CeFi balance changes. Without a cache
+ * each render re-issued one request per borrower — together, the two endpoints
+ * accounted for ~15.7k of the weekly `UpshiftTimeoutError` events in production.
+ *
+ * A `null` answer ("this borrower has no CeFi/OTC record") is cached alongside
+ * real data: it is the common case and just as worth remembering as a hit.
+ * Failures are NOT cached — they leave the key absent so the next call retries.
+ *
+ * 60s keeps a burst of renders on a single request while staying well inside
+ * the freshness any allocation view needs. Entries live in the shared process
+ * `CACHE`, so `CACHE.clear()` drops them along with everything else.
+ */
+const SUBACCOUNT_ENRICHMENT_TTL_MS = 1000 * 60;
+/** Shared-cache key for a borrower's CeFi positions. */
+const cefiCacheKey = (borrower) => `subaccount-cefi-${borrower}`;
+/** Shared-cache key for a borrower's OTC positions. */
+const otcCacheKey = (borrower) => `subaccount-otc-${borrower}`;
+/**
+ * Maximum simultaneous subaccount enrichment requests.
+ *
+ * Each borrower costs 2 requests (CeFi + OTC), so a window of 5 means at most
+ * 5 open connections to the Upshift API from one `getVaultAllocations` call.
+ * Worst-case RPC/HTTP volume for a 40-borrower vault: 80 requests, 5 at a time,
+ * versus 80 sequential before — and versus 80 simultaneous had this been a bare
+ * `Promise.all`.
+ */
+const SUBACCOUNT_FETCH_CONCURRENCY = 5;
+/**
+ * Fetch one borrower's CeFi positions, memoized for
+ * {@link SUBACCOUNT_ENRICHMENT_TTL_MS}.
+ *
+ * @param borrower - Subaccount/borrower address.
+ * @param options - Vault options carrying `upshiftKey` and monitoring headers.
+ * @param vault - Vault address, for log context only.
+ * @returns The borrower's CeFi positions, or `null` when the backend has no
+ *   record (or the fetch failed — this is best-effort enrichment and never
+ *   throws).
+ */
+async function fetchSubaccountCefi(borrower, options, vault) {
+    const key = cefiCacheKey(borrower);
+    // `has` rather than a truthiness check: `null` is a cached answer ("no
+    // record for this borrower"), not a miss.
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    try {
+        const cefiResponse = await (0, core_1.fetchUpshiftWithKey)(options.upshiftKey, core_1.WEBSERVER_ENDPOINTS.subaccount.cefi(borrower), { headers: options?.headers });
+        if (cefiResponse.status === 200) {
+            const cefiRes = (await cefiResponse.json());
+            cache_1.CACHE.set(key, cefiRes, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+            return cefiRes;
+        }
+        // 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 (EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(cefiResponse.status)) {
+            // A known "no record" answer is a stable fact about this borrower; cache
+            // it so the next render does not re-ask.
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+    catch (e) {
+        const status = httpStatusFromError(e);
+        logSubaccountFetchFailure('getVaultAllocations:cefi', status, e, {
+            vault,
+            borrower,
+        });
+        if (status !== undefined &&
+            EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(status)) {
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+}
+/**
+ * Fetch one borrower's OTC positions, memoized for
+ * {@link SUBACCOUNT_ENRICHMENT_TTL_MS}. Mirrors {@link fetchSubaccountCefi}.
+ *
+ * @param borrower - Subaccount/borrower address.
+ * @param options - Vault options carrying `upshiftKey` and monitoring headers.
+ * @param vault - Vault address, for log context only.
+ * @returns The borrower's OTC position, or `null` when absent or unfetchable.
+ */
+async function fetchSubaccountOtc(borrower, options, vault) {
+    const key = otcCacheKey(borrower);
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    try {
+        const otcResponse = await (0, core_1.fetchUpshiftWithKey)(options.upshiftKey, core_1.WEBSERVER_ENDPOINTS.subaccount.otc_positions(borrower), { headers: options?.headers });
+        if (otcResponse.status === 200) {
+            const otcRes = (await otcResponse.json());
+            cache_1.CACHE.set(key, otcRes, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+            return otcRes;
+        }
+        // 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 (EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(otcResponse.status)) {
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+    catch (e) {
+        const status = httpStatusFromError(e);
+        logSubaccountFetchFailure('getVaultAllocations:otc', status, e, {
+            vault,
+            borrower,
+        });
+        if (status !== undefined &&
+            EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(status)) {
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+}
+/**
+ * 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 `UpshiftServerError: 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.
+ *
+ * `fetchUpshiftWithKey` throws `UpshiftServerError`/`UpshiftAuthError` 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.
+ *
+ * DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana
+ * borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API —
+ * one vault-level call covering the idle buffer, Stellar protocol positions,
+ * custody wallets, and capital bridged to other chains. The Stellar path adds
+ * exactly 1 HTTP call and zero for every other chain; when it fails, the
+ * exposure section comes back empty and the CeFi, OTC and loan allocations are
+ * still returned.
+ *
+ * @param vault - Vault address
+ * @param options - RPC configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVault` fetched it one call earlier),
+ *   passing it skips this function's own `GET /tokenized_vault/{address}` — a
+ *   pure de-duplication of backend traffic. The row must carry the subaccount
+ *   data this function reads (`.subaccounts`, `.eoa_operators`), so it must not
+ *   have been fetched with `loadSubaccounts: false`; a row fetched that way
+ *   would silently resolve zero borrowers.
+ * @returns Detailed allocation data with exposure categorization
+ * @throws {@link UpshiftNetworkError} (`NETWORK_ERROR`) when any borrower's
+ *   portfolio read (DeBank for EVM, Octav for Solana) fails.
+ */
+async function getVaultAllocations(vault, options, tokenizedVault) {
+    // 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 = [];
+    // Untangled publishes the vault's asset composition as its own decomposition of
+    // tvlUsd, with no join to `byProtocol`. It therefore cannot be accumulated into
+    // `tokenExposure` alongside the synthesized position tokens without
+    // double-counting, so it replaces those rows below for Stellar vaults.
+    let untangledAssets = null;
+    // How much of `tokenExposure` the Untangled parse produced. Only that prefix is
+    // replaced: the accumulator is shared with the per-borrower loop that runs
+    // afterwards, and a borrower on a chain with portfolio coverage would otherwise
+    // have its rows silently dropped rather than double-counted.
+    let untangledTokenCount = 0;
+    let vaultOctav;
+    const borrowerPortfolioFetchers = {
+        solana: async (borrower) => {
+            vaultOctav ??= (0, octavfi_1.fetchVaultOctavResponse)(vault, options?.headers);
+            const response = await vaultOctav;
+            const portfolio = response ? response[borrower] : undefined;
+            return portfolio && !('error' in portfolio)
+                ? (0, octavfi_1.transformOctavfiToDebank)(portfolio)
+                : null;
+        },
+    };
+    // Determine wallets to fetch allocation responses from
+    let uniqueBorrowers = [];
+    const vaultRow = tokenizedVault ??
+        (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
+    // Started now so the fresh vault-state read overlaps the portfolio fetches
+    // below. It never rejects.
+    const solanaAumRead = (0, core_1.getAddressChainType)(vault) === 'solana' && vaultRow
+        ? SolanaGetters.getSolanaVaultAumUsd(vaultRow, options)
+        : undefined;
+    // fetch all vault unique subaccounts/loan borrowers
+    try {
+        const vaultVersion = (0, core_1.getVaultVersionV2)(vaultRow);
+        if (vaultVersion === 'evm-0') {
+            const loans = await getVaultLoans(vault, options);
+            uniqueBorrowers = [...new Set(loans.map((l) => l.borrower))];
+        }
+        else {
+            const eoa_operators = vaultRow.eoa_operators.map((s) => s.address);
+            uniqueBorrowers = [
+                ...vaultRow.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;
+                }
+            }
+        }
+        else if ((0, core_1.getAddressChainType)(vault) === 'stellar') {
+            // Untangled reconciles the whole Stellar vault in one call — idle buffer,
+            // Stellar protocol positions, custody wallets, and value bridged to other
+            // chains. It is keyed by vault, not by borrower, so it runs here rather
+            // than in the per-borrower loop below, which would multiply the totals.
+            const untangledExposure = await (0, untangled_1.fetchUntangledVaultExposure)(vault);
+            // A miss leaves the exposure section empty — never `debankErr`. See the
+            // `no_fetcher` branch below for why throwing here was wrong.
+            if (untangledExposure) {
+                const untangledRes = (0, untangled_1.transformUntangledToDebank)(untangledExposure);
+                (0, debank_1.parseVaultLevelDebank)(untangledRes, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue);
+                unfilteredTokens = untangledRes.subaccount.tokens;
+                untangledAssets = (0, untangled_1.untangledAssetExposure)(untangledExposure);
+                untangledTokenCount = tokenExposure.length;
+                defiPerBorrower[vault] = (0, debank_1.parseLoanLevelDebank)(untangledRes);
+            }
+        }
+        // Fetch portfolio data for non-EVM borrowers (EVM handled by fetchVaultDebankResponse above).
+        // Sequential by design: this branch only runs for non-EVM borrowers (a
+        // handful per vault) and each parser call mutates the shared accumulators
+        // below, which are not safe to interleave.
+        for (const borrower of uniqueBorrowers) {
+            const chainType = (0, core_1.getAddressChainType)(borrower);
+            if (chainType === 'evm')
+                continue;
+            const fetcher = borrowerPortfolioFetchers[chainType];
+            if (!fetcher) {
+                // 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}`,
+                });
+                continue;
+            }
+            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;
+            }
+        }
+        // CeFi and OTC enrichment runs for ALL borrowers regardless of chain type.
+        // Previously sequential — one borrower's slow (or timing-out) request
+        // delayed every borrower behind it, so a vault with N borrowers serialised
+        // 2N requests. Now cached per borrower and run through a bounded window:
+        // fewer requests, and the ones that remain overlap without stampeding the
+        // API. Both fetchers swallow their own failures, so no result is rejected.
+        const subaccountPositions = await (0, concurrency_1.mapWithConcurrency)(uniqueBorrowers, SUBACCOUNT_FETCH_CONCURRENCY, async (borrower) => ({
+            borrower,
+            cefi: await fetchSubaccountCefi(borrower, options, vault),
+            otc: await fetchSubaccountOtc(borrower, options, vault),
+        }));
+        // Fold sequentially so the accumulated order stays deterministic and
+        // independent of which request finished first.
+        for (const { borrower, cefi, otc } of subaccountPositions) {
+            if (cefi) {
+                cefiExposure = [...cefiExposure, ...cefi];
+            }
+            if (otc) {
+                otcPositions[borrower] = otc;
+            }
+        }
+    }
+    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) {
+        // Provider-agnostic: EVM borrowers resolve through DeBank, Solana
+        // borrowers through Octav.
+        throw new errors_1.UpshiftNetworkError('getVaultAllocations: failed to fetch a borrower portfolio from the portfolio provider (DeBank/Octav). Retry the call.', { context: { vault: String(vault) } });
+    }
+    // The idle balance sits with no operator, so the residual is taken against
+    // deployed AUM alone; counting idle would report it as unattributed.
+    const solanaAum = await solanaAumRead;
+    const unattributed = solanaAum
+        ? {
+            usd: solanaAum.deployedUsd - (defiBalance + walletBalance + cefiBalance),
+            onChainAumUsd: solanaAum.deployedUsd + solanaAum.idleUsd,
+            idleUsd: solanaAum.idleUsd,
+        }
+        : undefined;
+    return {
+        defi: protocolExposure,
+        cefi: cefiExposure,
+        otc: otcPositions,
+        tokens: untangledAssets?.length
+            ? [...untangledAssets, ...tokenExposure.slice(untangledTokenCount)]
+            : tokenExposure,
+        defiPerBorrower,
+        exposurePerCategory,
+        netValue: netValue.value,
+        ...(unattributed && { unattributed }),
+        // 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);
+    }
+}
+/**
+ * Read `lagDuration()` off a vault, tolerating vaults that do not implement it.
+ *
+ * Why this exists: `getVaultAvailableRedemptions` binds every vault — v1 and
+ * v2 — to `ABI_LENDING_POOL_V2` because that ABI carries the superset of
+ * methods the scan needs. `lagDuration()` is not in that superset for every
+ * deployed pool. Calling it on a pool without the function reaches the
+ * fallback-less contract, which returns empty calldata, and ethers reports it
+ * as `missing revert data (action="call", data=null, …, code=CALL_EXCEPTION)`.
+ * That threw out of the whole redemption scan and became the single
+ * highest-volume error in production Sentry (~5.5k events over two days from
+ * three server deployments), while also returning an empty redemption list to
+ * every caller for the affected vaults.
+ *
+ * A missing `lagDuration()` means "this pool has no claim lag", which is what
+ * `0` encodes — the same value the v1 branch of the caller assumes.
+ *
+ * The empty response is **retried before it is believed**, because a provider
+ * that truncates an `eth_call` produces the identical shape: falling straight
+ * to `0` for a vault that really does have a lag would shift every computed
+ * claimable date. Only after the retries agree is the function treated as
+ * absent. A genuine revert carrying revert data still propagates, so real
+ * breakage stays loud.
+ *
+ * **The absence is memoized, the value is not.** Paying the retry budget (3
+ * `eth_call`s plus ~750ms of backoff) on every call for a vault that will never
+ * implement `lagDuration()` would trade an error flood for a latency and
+ * RPC-volume regression on exactly the vaults this path targets — a dashboard
+ * re-rendering redemptions pays it per render (CLAUDE.md §4.1, §4.2). Whether a
+ * deployed pool implements the function is fixed by its bytecode, so a
+ * confirmed absence is cacheable forever; the lag *value* is operator-settable
+ * and is deliberately never cached.
+ *
+ * Caveat on "fixed by its bytecode": an **upgradeable proxy** could gain a
+ * `lagDuration()` in a later implementation, and a process holding the memo
+ * would keep answering `0` for it. Bounded, not unbounded — `CACHE` carries a
+ * 24h TTL and `allowStale: true`, which serves an expired entry exactly once
+ * before evicting it, so the vault is re-read on the following call. Vaults
+ * behind an upgradeable proxy that add the function mid-process therefore
+ * misreport a zero lag for at most that window. Accepted deliberately: no
+ * deployed pool does this today, and the alternative is re-paying the retry
+ * budget forever for the vaults this path exists to serve.
+ *
+ * @param vaultContract - Anything exposing the vault's `lagDuration()` view;
+ *   structurally typed so both `ethers.Contract` and the ABI-typed contract
+ *   returned by `createContract` satisfy it.
+ * @param vault - Vault address, for the breadcrumb only.
+ * @param scope - Cache scope for the absence memo — the RPC endpoint the read
+ *   went through. Scoping by endpoint (rather than globally by address) keeps
+ *   the same address on two chains in separate entries.
+ * @returns The lag in seconds, or `0` when the vault has no `lagDuration()`.
+ * @throws The original error for any failure that is not an empty response.
+ */
+async function readLagDuration(vaultContract, vault, scope) {
+    const absenceKey = `lag-absent-${scope}-${vault.toLowerCase()}`;
+    // A vault proven not to implement the function cannot start implementing it.
+    if (cache_1.CACHE.get(absenceKey) === true)
+        return 0;
+    try {
+        return Number(await (0, core_1.retryOnTransientRpc)('getVaultAvailableRedemptions:lagDuration', () => vaultContract.lagDuration(), { vault }, (error) => (0, core_1.isRetryableRpcError)(error) ||
+            (0, core_1.isEmptyViewResponse)(error, LAG_DURATION_SELECTOR)));
+    }
+    catch (error) {
+        if (!(0, core_1.isEmptyViewResponse)(error, LAG_DURATION_SELECTOR))
+            throw error;
+        // Retries agreed the response is empty — record the absence so the next
+        // call short-circuits instead of re-paying the full retry budget.
+        cache_1.CACHE.set(absenceKey, true);
+        core_1.Logger.log.warn('getVaultAvailableRedemptions', {
+            vault,
+            reason: 'vault does not implement lagDuration(); assuming no claim lag',
+        });
+        return 0;
+    }
+}
+/**
+ * `lagDuration()` — `keccak256("lagDuration()")[0..4]`. Scopes the
+ * empty-response tolerance in {@link readLagDuration} to exactly that call, so
+ * an empty response to any *other* view still surfaces as an error.
+ */
+const LAG_DURATION_SELECTOR = '0x24e86d67';
+/**
+ * A Solana wallet's withdrawal-queue requests on one vault, for
+ * `getVaultPositions` and `getVaultAvailableRedemptions`. Empty when the vault
+ * has no queue, the wallet has no request, or the service cannot name the queue
+ * program (including where the queue is not deployed); a failed read is logged
+ * and reads as empty, like the balance reads beside it.
+ *
+ * RPC: see `getSolanaWithdrawalRedemptions` (one `getAccountInfo` for a vault
+ * with no queue; up to one more `getProgramAccounts` and one
+ * `getMultipleAccountsInfo`).
+ */
+async function readSolanaRedemptions(input) {
+    const empty = {
+        availableRedemptions: [],
+        pendingRedemptions: [],
+    };
+    const { tokenizedVault, solanaService, vaultState } = input;
+    if (!vaultState.shareMint)
+        return empty;
+    try {
+        const queueProgramId = (0, withdrawal_queue_1.resolveQueueProgramId)(solanaService);
+        if (!queueProgramId)
+            return empty;
+        const metadata = tokenizedVault.solana_vault_metadata;
+        const programId = utils_2.SolanaUtils.resolveProgramId(String(tokenizedVault.address), metadata);
+        return await (0, withdrawal_queue_1.getSolanaWithdrawalRedemptions)({
+            connection: solanaService.connection,
+            queueProgramId,
+            vaultStateAddress: metadata?.vault_state_pda
+                ? new web3_js_1.PublicKey(metadata.vault_state_pda)
+                : utils_2.SolanaUtils.deriveVaultStatePda(programId),
+            shareMint: new web3_js_1.PublicKey(vaultState.shareMint),
+            owner: new web3_js_1.PublicKey(input.wallet),
+            vault: tokenizedVault.address,
+            depositDecimals: input.depositDecimals,
+        });
+    }
+    catch (error) {
+        core_1.Logger.log.warn('readSolanaRedemptions', 'Withdrawal requests read failed', {
+            vault: tokenizedVault.address,
+            error,
+        });
+        return empty;
+    }
+}
+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: [],
+                }),
+            };
+        }
+        // Solana: the wallet's withdrawal-queue requests. There is no processed
+        // history to report, so the verbose lists are always empty.
+        if (utils_2.SolanaUtils.isSolanaAddress(vault)) {
+            const empty = {
+                availableRedemptions: [],
+                pendingRedemptions: [],
+                ...(options.verbose && {
+                    processedWithdrawals: [],
+                    requestedWithdrawals: [],
+                }),
+            };
+            const solanaService = options.solanaService;
+            if (!wallet || !utils_2.SolanaUtils.isSolanaAddress(wallet) || !solanaService) {
+                return empty;
+            }
+            const solanaVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers, false, false))?.[0];
+            if (!solanaVault)
+                return empty;
+            const vaultStateRes = await solanaService.getVaultState(utils_2.SolanaUtils.resolveProgramId(String(solanaVault.address), solanaVault.solana_vault_metadata), SolanaConstants.vaultIdl, solanaVault.solana_vault_metadata?.vault_state_pda ?? undefined);
+            const vaultState = vaultStateRes?.vaultState;
+            if (!vaultState)
+                return empty;
+            return {
+                ...empty,
+                ...(await readSolanaRedemptions({
+                    tokenizedVault: solanaVault,
+                    wallet,
+                    solanaService,
+                    vaultState,
+                    depositDecimals: vaultStateRes?.depositMintDecimals ??
+                        solanaVault.solana_vault_metadata?.deposit_token_decimals ??
+                        SolanaConstants.fallbackDecimals,
+                })),
+            };
+        }
+        // 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
+            : await readLagDuration(vaultContract, vault, options.rpcUrl);
+        // With a wallet, every row of another receiver is discarded below, so
+        // filter server-side to cut the Goldsky payload (~0.9 MB on busy vaults,
+        // AUGUST-8317). `verbose` callers get the raw lists back, so they keep the
+        // unfiltered read.
+        const receiverFilter = wallet && (0, ethers_1.isAddress)(wallet) && !options.verbose ? wallet : undefined;
+        const { withdrawalRequesteds, withdrawalProcesseds } = await (0, subgraph_1.getSubgraphAllWithdrawals)(vault, provider, {
+            receiver: receiverFilter,
+        });
+        // 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. evm-2 events carry a raw
+            // `timestamp_` from which the date was just computed — a malformed
+            // timestamp yields NaN date parts, which would otherwise flow into the
+            // date keys below and never match anything. evm-1 events carry the
+            // date explicitly.
+            const missingRequired = version === 'evm-2'
+                ? !year || !month || !day || !ev.receiverAddr
+                : !ev.year || !ev.month || !ev.day || !ev.receiverAddr;
+            if (missingRequired) {
+                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));
+        // Max concurrent `eth_getLogs` requests per batch. Kept well under the
+        // per-second cap of the smallest provider plan we run against (QuickNode:
+        // 50/s) because this scan is not the only caller on the connection — a
+        // page rendering several vaults runs several of these concurrently. At 20
+        // the batches reliably tripped `-32007 50/second request limit reached`,
+        // which the retry below now absorbs and this ceiling mostly avoids.
+        const BATCH_SIZE = 8;
+        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) => 
+            // `eth_getLogs` over a fixed block range is idempotent, so a chunk
+            // rejected by a rate limiter or a flaky socket is safe to repeat.
+            // Without this a single `-32007` burst aborted the whole scan and
+            // the caller lost the redemption history entirely — the same failure
+            // mode the throw below was added to make visible.
+            (0, core_1.retryOnTransientRpc)('getVaultRedemptionHistory:chunk', () => poolContract.queryFilter('WithdrawalProcessed', BigInt(r.from), BigInt(r.to)), { vault, fromBlock: r.from, toBlock: 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);
+                    let redemptions = {
+                        availableRedemptions: [],
+                        pendingRedemptions: [],
+                    };
+                    // 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);
+                        }
+                        if (vaultState) {
+                            redemptions = await readSolanaRedemptions({
+                                tokenizedVault: v,
+                                wallet: solanaWallet,
+                                solanaService: options.solanaService,
+                                vaultState,
+                                depositDecimals: vaultStateRes?.depositMintDecimals ?? fallbackShareDecimals,
+                            });
+                        }
+                    }
+                    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,
+                        // Any queued request, waiting or claimable, marks the position
+                        // REDEEM; the shares it escrows are no longer in the wallet.
+                        status: renderStatus([
+                            ...redemptions.availableRedemptions,
+                            ...redemptions.pendingRedemptions,
+                        ], balance),
+                        availableRedemptions: redemptions.availableRedemptions,
+                        pendingRedemptions: redemptions.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, v.address);
+                    // `getReceiptTokenAddress` never throws: after its bounded retries
+                    // it resolves `undefined`. Passing that on used to crash with
+                    // `Cannot read properties of undefined (reading 'balanceOf')`
+                    // (Sentry AUGUST-JS-SDK-V2-ZF, AUGUST-8347), which hid the real
+                    // cause — a failed RPC read. Throw a typed error instead; the
+                    // per-vault catch below turns it into a `readFailed` row.
+                    if (!receiptAddress) {
+                        throw new errors_1.UpshiftNetworkError('getVaultPositions: receipt token address unresolved for evm-2 vault', { context: { vault: v.address, chainId: v.chain } });
+                    }
+                    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, v.address);
+                    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);
+                // Redemption requests are keyed by receiver, so without an EVM
+                // wallet there is nothing of the caller's to find. Skip the read
+                // rather than delegate: the wallet-less path of
+                // `getVaultAvailableRedemptions` lists EVERY receiver's processed
+                // requests for the vault, which in a positions read surfaced other
+                // users' withdrawals as the caller's and flipped the status to
+                // REDEEM for every EVM vault in a Stellar/Solana-only session
+                // (AUGUST-7938). Skipping also saves one subgraph query per EVM
+                // vault for those callers.
+                const { availableRedemptions, pendingRedemptions } = wallet && (0, ethers_1.isAddress)(wallet)
+                    ? await getVaultAvailableRedemptions({
+                        vault: v.address,
+                        wallet,
+                        options,
+                        prefetchedReads: prefetched,
+                    })
+                    : {
+                        availableRedemptions: [],
+                        pendingRedemptions: [],
+                    };
+                // get aggregate redemption amount
+                const aggregateAvailableRedemptions = availableRedemptions.reduce((acc, curr) => acc + BigInt(curr.amount.raw), BigInt(0));
+                // return obj
+                return {
+                    vault: v.address,
+                    status: renderStatus(availableRedemptions, balance),
+                    availableRedemptions,
+                    pendingRedemptions,
+                    redeemable: (0, core_1.toNormalizedBn)(aggregateAvailableRedemptions, decimals),
+                    walletBalance: balance,
+                };
+            }
+            catch (vaultError) {
+                // Pass the error object (not a string) so typed errors keep
+                // their code/context/correlationId through to the logger.
+                core_1.Logger.log.error(`getVaultPositions`, vaultError, {
+                    vault: v.address,
+                    chainId: v.chain,
+                });
+                // Keep the zero `PENDING` row so callers' default filter still
+                // drops it, but flag it so `showAllVaults` callers can tell a
+                // failed read from an empty position (AUGUST-8347).
+                return {
+                    vault: v.address,
+                    status: 'PENDING',
+                    readFailed: true,
+                    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, false, false))?.[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.fetchUpshiftPublic)(`${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, undefined, false, false))?.[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');
+            // Fall back to wall-clock "now" (ms) when the provider returns no
+            // finalized block — the old `Date.now() * 60 * 1000` placed the window
+            // 60,000x into the future.
+            const finalizedTimestamp = finalizedBlock
+                ? finalizedBlock.timestamp * 1000
+                : Date.now();
+            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 Upshift 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.fetchUpshiftWithKey)(options.upshiftKey, 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, false, false)) ?? [])
+        : 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.fetchUpshiftPublic)(endpoint, {
+            headers: options?.headers,
+        });
+        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.fetchUpshiftPublic)(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.fetchUpshiftPublic)(`${core_1.WEBSERVER_ENDPOINTS.public.points.leaderboard}?${searchParams.toString()}`, {
+            headers: options?.headers,
+        });
+        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, false, false))?.[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 lifetime-PnL over-inflation when the deposit history fails to load.
+ *
+ * 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, no shares received by transfer *and* no recorded withdrawals. It
+ * also rejects a non-zero position with no recorded deposits when a share mint
+ * to the wallet has no matching deposit (`mintsMatchHistory: false`): the mint
+ * proves a deposit the history failed to return, so neither a peer transfer
+ * nor a withdrawal makes the cost basis complete. Otherwise, any of the
+ * following is treated as consistent and passes:
+ * - deposits are present (the normal, computable case);
+ * - shares were received by transfer and priced (see {@link transferCostBasis});
+ * - 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.
+ *
+ * Shares received by a direct token transfer (never deposited, never withdrew)
+ * reach this guard as `receivedByTransferRaw`: {@link getVaultUserLifetimePnl}
+ * prices them with {@link transferCostBasis} first. The guard still throws for
+ * such a wallet when its transfers cannot be read or priced, or when a share
+ * mint to it has no indexed deposit.
+ *
+ * @param params - See {@link PnlHistoryConsistencyParams}.
+ * @returns `void` when the history is consistent.
+ * @throws {@link UpshiftHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
+ *   and `context: { vault, wallet }` when a non-zero position has no deposits
+ *   recorded and either a share mint without a matching deposit or neither
+ *   received shares nor withdrawals. 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,
+ *   mintsMatchHistory,
+ *   receivedByTransferRaw: costBasis.receivedByTransferRaw,
+ *   totalWithdrawnRaw,
+ *   currentPositionRaw: currentPositionValue.raw,
+ * });
+ * ```
+ */
+function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, mintsMatchHistory = true, receivedByTransferRaw = BigInt(0), totalWithdrawnRaw, currentPositionRaw, }) {
+    if (currentPositionRaw <= BigInt(0) || hasDeposits)
+        return;
+    const missingDeposit = !mintsMatchHistory;
+    const noHistory = receivedByTransferRaw === BigInt(0) && totalWithdrawnRaw === BigInt(0);
+    if (missingDeposit || noHistory) {
+        const reason = missingDeposit
+            ? 'a share mint has no indexed deposit'
+            : 'no deposits or withdrawals were indexed';
+        throw new errors_1.UpshiftHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:transaction history unavailable — a live position exists but ${reason}, so lifetime PnL cannot be computed without over-reporting the entire position as profit`, { context: { vault, wallet } });
+    }
+}
+/**
+ * Guard against converting lifetime PnL to USD with a fabricated price.
+ *
+ * Every USD field `getVaultUserLifetimePnl` returns is a native amount times
+ * the underlying asset's USD price. When the price server has no price, the
+ * only honest outcome is "no USD value" — substituting a stand-in (the getter
+ * previously used `1`) reports a non-dollar vault's position at $1 per asset,
+ * a plausible-looking but wrong number that callers cannot detect.
+ *
+ * Pure and synchronous — no RPC, no I/O.
+ *
+ * @param params - See {@link PnlTokenPriceParams}.
+ * @returns `tokenPriceUsd`, unchanged, when it is a finite number above zero.
+ * @throws {@link UpshiftPriceUnavailableError} with code `PRICE_UNAVAILABLE`
+ *   and `context: { vault, wallet, asset }` when the price is zero, negative,
+ *   or not finite. The message carries the
+ *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
+ *   other errors leaving the getter.
+ * @example
+ * ```ts
+ * const price = assertPnlTokenPrice({
+ *   vault,
+ *   wallet,
+ *   asset: underlyingAssetAddress,
+ *   tokenPriceUsd: await pricePromise,
+ * });
+ * ```
+ */
+function assertPnlTokenPrice({ vault, wallet, asset, tokenPriceUsd, }) {
+    if (Number.isFinite(tokenPriceUsd) && tokenPriceUsd > 0)
+        return tokenPriceUsd;
+    throw new errors_1.UpshiftPriceUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:underlying token price unavailable for ${asset ?? 'an unreadable asset()'} — USD values cannot be computed without fabricating a price`, { context: { vault, wallet, asset: asset ?? null } });
+}
+/**
+ * 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;
+}
+/**
+ * Keep the receipt-token transfers that moved shares between `wallet` and
+ * another holder.
+ *
+ * Vault shares are transferable ERC-20 tokens, so a wallet can hold a position
+ * it never deposited into — a migration airdrop, a DEX purchase, a transfer from
+ * another wallet. Mints (from the zero address), burns (to it) and transfers to
+ * or from the vault itself are dropped: those are the deposit and withdrawal
+ * legs the subgraph history already records, and counting them again would
+ * double the cost basis. Transfers to or from `exclude` are dropped too.
+ *
+ * @param transfers - Receipt-token transfers touching `wallet`, as returned by
+ *   the vault's transfer subgraph.
+ * @param wallet - The wallet whose position is being valued.
+ * @param vault - The vault contract address.
+ * @param exclude - Other counterparties whose transfers are not peer
+ *   transfers, such as a LayerZero OVault's hub composer and share OFT
+ *   (`hubComposer` / `hubShareOFT` in `LAYERZERO_VAULTS`). Defaults to none.
+ * @returns The peer-to-peer transfers, in input order. Addresses compare
+ *   case-insensitively.
+ * @example
+ * ```ts
+ * const peer = selectPeerTransfers(transfers, wallet, vault);
+ * ```
+ */
+function selectPeerTransfers(transfers, wallet, vault, exclude = []) {
+    const self = wallet.toLowerCase();
+    const excluded = new Set([ethers_1.ZeroAddress, vault, ...exclude].map((address) => address.toLowerCase()));
+    return transfers.filter((transfer) => {
+        const from = transfer.from.toLowerCase();
+        const to = transfer.to.toLowerCase();
+        if (from === to || excluded.has(from) || excluded.has(to))
+            return false;
+        return from === self || to === self;
+    });
+}
+/**
+ * Value peer share transfers in the vault's asset, at the vault's share ratio
+ * on the day each one happened.
+ *
+ * Used by {@link getVaultUserLifetimePnl} when a wallet has no indexed
+ * deposits: received shares become its cost basis and sent shares count as
+ * withdrawn, so lifetime PnL for a transfer recipient reads "PnL since the
+ * shares arrived" rather than failing or reporting the whole position as
+ * profit. A day with no usable ratio takes the latest earlier day's, and a
+ * transfer older than the history takes the earliest day's.
+ *
+ * Sent shares count only against a received basis by default. A wallet that
+ * sent shares but received none gets a zero basis, so the lifetime-PnL history
+ * guard still decides for it instead of reporting the sent shares as profit.
+ * `countSentWithoutReceipt: true` reports them anyway, for a caller that knows
+ * the wallet also deposited.
+ *
+ * Pure and synchronous. Assumes, as the getter does, that shares and assets
+ * share the vault's decimals.
+ *
+ * @param params - See {@link TransferCostBasisParams}.
+ * @returns The received and sent asset amounts, raw at the vault's decimals;
+ *   both zero when no shares were received.
+ * @throws {@link UpshiftHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when no
+ *   day in `history` carries a positive, finite `asset_share_ratio`.
+ * @example
+ * ```ts
+ * const { data } = await fetchVaultHistoricalTimeseries(vault, nDays);
+ * const { receivedRaw, sentRaw } = transferCostBasis({
+ *   transfers: selectPeerTransfers(transfers, wallet, vault),
+ *   wallet,
+ *   vault,
+ *   history: data,
+ * });
+ * ```
+ */
+function transferCostBasis({ transfers, wallet, vault, history, countSentWithoutReceipt = false, }) {
+    const ratios = Object.entries(history)
+        .filter(([, day]) => Number.isFinite(day.asset_share_ratio) &&
+        (day.asset_share_ratio ?? 0) > 0)
+        .map(([date, day]) => ({ date, ratio: day.asset_share_ratio }))
+        .sort((a, b) => a.date.localeCompare(b.date));
+    if (ratios.length === 0) {
+        throw new errors_1.UpshiftHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:no share ratio history to price shares received by transfer`, { context: { vault, wallet } });
+    }
+    const scale = BigInt(10) ** BigInt(18);
+    const assetsAt = (shares, timestamp) => {
+        const date = new Date(Number(timestamp) * 1000).toISOString().slice(0, 10);
+        let ratio = ratios[0].ratio;
+        for (const entry of ratios) {
+            if (entry.date > date)
+                break;
+            ratio = entry.ratio;
+        }
+        return (shares * BigInt(Math.round(ratio * 1e18))) / scale;
+    };
+    const self = wallet.toLowerCase();
+    let receivedRaw = BigInt(0);
+    let sentRaw = BigInt(0);
+    for (const transfer of transfers) {
+        const shares = BigInt(transfer.value);
+        if (transfer.to.toLowerCase() === self) {
+            receivedRaw += assetsAt(shares, transfer.timestamp_);
+        }
+        else if (transfer.from.toLowerCase() === self) {
+            sentRaw += assetsAt(shares, transfer.timestamp_);
+        }
+    }
+    if (receivedRaw === BigInt(0) && !countSentWithoutReceipt) {
+        return { receivedRaw, sentRaw: BigInt(0) };
+    }
+    return { receivedRaw, sentRaw };
+}
+/**
+ * Check that a wallet's indexed deposit history accounts for every share mint
+ * its share-token ledger shows.
+ *
+ * A deposit mints shares to the wallet in the same transaction, so a mint with
+ * no deposit of the same hash means the history is missing that deposit (an
+ * older deposit the subgraph never indexed, or one a third party made for the
+ * wallet). Folding peer transfers into such a history would credit the wallet
+ * for shares it sent while missing what it paid for them, so
+ * {@link getVaultUserLifetimePnl} only folds transfers for a depositor when
+ * this holds.
+ *
+ * Pure and synchronous. Hashes and addresses compare case-insensitively.
+ *
+ * @param params - See {@link HistoryCoversMintsParams}.
+ * @returns `true` when every mint to `wallet` has a matching deposit, including
+ *   when there are no mints.
+ * @example
+ * ```ts
+ * const covered = historyCoversMints({
+ *   transfers,
+ *   wallet,
+ *   depositTransactionHashes: history
+ *     .filter((item) => item.type === 'deposit')
+ *     .map((item) => item.transactionHash_),
+ * });
+ * ```
+ */
+function historyCoversMints({ transfers, wallet, depositTransactionHashes, }) {
+    const self = wallet.toLowerCase();
+    const zero = ethers_1.ZeroAddress.toLowerCase();
+    const deposits = new Set(depositTransactionHashes.map((hash) => hash.toLowerCase()));
+    return transfers.every((transfer) => transfer.from.toLowerCase() !== zero ||
+        transfer.to.toLowerCase() !== self ||
+        deposits.has(transfer.transactionHash_.toLowerCase()));
+}
+/**
+ * Keep the `ReserveDeposit` events that explain a share mint the indexed
+ * deposit history misses.
+ *
+ * High Growth ETH mints shares for deposits made through Kelp's gain adapter
+ * with a `ReserveDeposit` event instead of an ERC-4626 `Deposit`, so those
+ * deposits are absent from the user history and fail {@link historyCoversMints}.
+ * An event counts only when its transaction mints shares to `wallet` and holds
+ * no indexed deposit, so a deposit is never counted twice.
+ *
+ * Pure and synchronous. Hashes and addresses compare case-insensitively.
+ *
+ * @param params - See {@link SelectReserveDepositsParams}.
+ * @returns The matching events, in input order.
+ * @example
+ * ```ts
+ * const reserve = selectReserveDeposits({
+ *   reserveDeposits: await getSubgraphUserReserveDeposits(wallet, provider, vault),
+ *   transfers,
+ *   wallet,
+ *   depositTransactionHashes,
+ * });
+ * ```
+ */
+function selectReserveDeposits({ reserveDeposits, transfers, wallet, depositTransactionHashes, }) {
+    const self = wallet.toLowerCase();
+    const zero = ethers_1.ZeroAddress.toLowerCase();
+    const deposits = new Set(depositTransactionHashes.map((hash) => hash.toLowerCase()));
+    const unmatchedMints = new Set(transfers
+        .filter((transfer) => transfer.from.toLowerCase() === zero &&
+        transfer.to.toLowerCase() === self &&
+        !deposits.has(transfer.transactionHash_.toLowerCase()))
+        .map((transfer) => transfer.transactionHash_.toLowerCase()));
+    return reserveDeposits.filter((deposit) => deposit.account.toLowerCase() === self &&
+        unmatchedMints.has(deposit.transactionHash_.toLowerCase()));
+}
+/**
+ * Drop withdrawal-request rows the vault logged more than once for a single
+ * request.
+ *
+ * A redemption requested through Kelp's gain adapter makes High Growth ETH emit
+ * `WithdrawalRequested` twice for one share transfer, and the subgraph indexes
+ * both. In a transaction where the share ledger shows the wallet sending shares
+ * to the vault `n` times, at most `n` request rows are kept. A transaction the
+ * ledger shows no such transfer for keeps every row, so a missing ledger leaves
+ * the history unchanged.
+ *
+ * Pure and synchronous. Hashes and addresses compare case-insensitively.
+ *
+ * @param params - See {@link CountWithdrawalRequestsOnceParams}.
+ * @returns The history without the surplus request rows, in input order.
+ * @example
+ * ```ts
+ * const history = countWithdrawalRequestsOnce({ history: userHistory, transfers, wallet, vault });
+ * ```
+ */
+function countWithdrawalRequestsOnce({ history, transfers, wallet, vault, }) {
+    const self = wallet.toLowerCase();
+    const target = vault.toLowerCase();
+    const remaining = new Map();
+    for (const transfer of transfers) {
+        if (transfer.from.toLowerCase() !== self ||
+            transfer.to.toLowerCase() !== target)
+            continue;
+        const hash = transfer.transactionHash_.toLowerCase();
+        remaining.set(hash, (remaining.get(hash) ?? 0) + 1);
+    }
+    return history.filter((item) => {
+        if (item.type !== 'withdraw-request')
+            return true;
+        const hash = item.transactionHash_.toLowerCase();
+        const left = remaining.get(hash);
+        if (left === undefined)
+            return true;
+        if (left === 0)
+            return false;
+        remaining.set(hash, left - 1);
+        return true;
+    });
+}
+/**
+ * Value a wallet's Tokenized Vault V2 redemption requests, which carry only
+ * shares.
+ *
+ * Every processed withdrawal (`WithdrawalProcessed.assetsAmount`) counts at the
+ * assets the vault paid. Its shares, estimated at the vault's
+ * `asset_share_ratio` on the day it was processed, retire the oldest requests
+ * first. Request shares left over count at the ratio on their claim date (see
+ * `computeClaimableDate`) once claimable: the subgraph lacks some processed rows
+ * (none for earnAUSD before 2026-02-01), and that ratio lands within about
+ * 0.05% of what the vault paid. Shares not yet claimable are left to the
+ * current share price. Matching by amount, not by claim date, keeps the result
+ * right when a vault processes a request before the date today's `lagDuration`
+ * implies. A leftover under 0.5% of a request that a later processed
+ * withdrawal followed is rounding from the daily ratio, so it is dropped.
+ *
+ * Pure and synchronous. Assumes, as the getter does, that shares and assets
+ * share the vault's decimals. A day with no usable ratio takes the latest
+ * earlier day's, and a date older than the history takes the earliest day's.
+ *
+ * @param params - See {@link SettleV2RedemptionsParams}.
+ * @returns The settled assets and the shares left to the current price; every
+ *   requested share is pending when `ratios` holds no usable day.
+ * @example
+ * ```ts
+ * const { settledAssetsRaw, pendingShares } = settleV2Redemptions({
+ *   history,
+ *   lagDuration: 259_200,
+ *   ratios: (await fetchVaultHistoricalTimeseries(vault, nDays)).data,
+ *   now: Math.floor(Date.now() / 1000),
+ * });
+ * ```
+ */
+function settleV2Redemptions({ history, lagDuration, ratios, now, }) {
+    const requests = history
+        .filter((item) => item.type === 'withdraw-request')
+        .sort((a, b) => Number(a.timestamp_) - Number(b.timestamp_));
+    const days = Object.entries(ratios)
+        .filter(([, day]) => Number.isFinite(day.asset_share_ratio) &&
+        (day.asset_share_ratio ?? 0) > 0)
+        .map(([date, day]) => ({
+        date,
+        ratio: BigInt(Math.round(day.asset_share_ratio * 1e18)),
+    }))
+        .sort((a, b) => a.date.localeCompare(b.date));
+    if (days.length === 0) {
+        return {
+            settledAssetsRaw: BigInt(0),
+            pendingShares: requests.reduce((sum, item) => sum + BigInt(item.amount), BigInt(0)),
+        };
+    }
+    const scale = BigInt(10) ** BigInt(18);
+    const ratioOn = (date) => days.filter((day) => day.date <= date).pop()?.ratio ?? days[0].ratio;
+    const utcDay = (timestamp) => new Date(Number(timestamp) * 1000).toISOString().slice(0, 10);
+    let settledAssetsRaw = BigInt(0);
+    let retiredShares = BigInt(0);
+    let lastProcessedAt = Number.NEGATIVE_INFINITY;
+    for (const item of history) {
+        if (item.type !== 'withdraw-processed' || item.isInstant)
+            continue;
+        const assets = BigInt(item.amount);
+        settledAssetsRaw += assets;
+        retiredShares += (assets * scale) / ratioOn(utcDay(item.timestamp_));
+        lastProcessedAt = Math.max(lastProcessedAt, Number(item.timestamp_));
+    }
+    let pendingShares = BigInt(0);
+    for (const item of requests) {
+        const shares = BigInt(item.amount);
+        const retired = retiredShares < shares ? retiredShares : shares;
+        retiredShares -= retired;
+        const open = shares - retired;
+        // A sliver left on a request processed later is ratio rounding.
+        if (open === BigInt(0) ||
+            (open * BigInt(200) <= shares &&
+                lastProcessedAt >= Number(item.timestamp_)))
+            continue;
+        const claim = (0, date_utils_1.computeClaimableDate)(Number(item.timestamp_), lagDuration);
+        if ((0, date_utils_1.isClaimableNow)(claim.epoch, now)) {
+            const key = (0, date_utils_1.formatDateKey)(claim.year, claim.month, claim.day);
+            settledAssetsRaw += (open * ratioOn(key)) / scale;
+        }
+        else {
+            pendingShares += open;
+        }
+    }
+    return { settledAssetsRaw, pendingShares };
+}
+/**
+ * Fold peer share transfers into a wallet's lifetime-PnL cost basis.
+ *
+ * Shares a wallet received from another holder (a migration airdrop, a DEX
+ * purchase, a transfer from another wallet) cost the wallet their value on
+ * arrival, so they add to the deposited amount; shares it sent away count as
+ * withdrawn. This applies whether or not the wallet also deposited, so a holder
+ * who received shares and then topped up is not credited with the received
+ * shares as profit, and a depositor who moved its shares elsewhere (a lending
+ * market, a DEX) is not shown as having lost them. A wallet with no deposit and
+ * no received shares keeps a zero basis, so the history guard still decides.
+ *
+ * A depositor whose history misses a mint ({@link historyCoversMints}) is the
+ * exception: its transfers do not count, so the result matches what the getter
+ * returned before transfers counted for depositors. A wallet with no deposit
+ * still gets a basis here when its history misses a mint, but
+ * {@link assertPnlHistoryConsistent} rejects it. On a LayerZero OVault the
+ * caller leaves the hub composer and share OFT out of the transfers (see
+ * {@link selectPeerTransfers}): the composer's deliveries are already counted
+ * as LayerZero deposits, and shares bridged to a spoke chain still count in the
+ * position.
+ *
+ * Pure and synchronous.
+ *
+ * @param params - See {@link PnlCostBasisParams}.
+ * @returns The deposited and withdrawn amounts to compute PnL from, and the
+ *   transfer-priced part of the deposited amount (zero when transfers did not
+ *   count).
+ * @example
+ * ```ts
+ * const basis = pnlCostBasis({
+ *   depositedRaw,
+ *   withdrawnAssetsRaw,
+ *   hasDeposits: depositedRaw > BigInt(0),
+ *   mintsMatchHistory: historyCoversMints({
+ *     transfers,
+ *     wallet,
+ *     depositTransactionHashes,
+ *   }),
+ *   transfers: transferCostBasis({
+ *     transfers,
+ *     wallet,
+ *     vault,
+ *     history,
+ *     countSentWithoutReceipt: true,
+ *   }),
+ * });
+ * ```
+ */
+function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDeposits, mintsMatchHistory, transfers, }) {
+    if (hasDeposits && !mintsMatchHistory) {
+        return {
+            depositedRaw,
+            withdrawnAssetsRaw,
+            receivedByTransferRaw: BigInt(0),
+        };
+    }
+    const sentRaw = hasDeposits || transfers.receivedRaw > BigInt(0)
+        ? transfers.sentRaw
+        : BigInt(0);
+    return {
+        depositedRaw: depositedRaw + transfers.receivedRaw,
+        withdrawnAssetsRaw: withdrawnAssetsRaw + sentRaw,
+        receivedByTransferRaw: transfers.receivedRaw,
+    };
+}
+// One receipt-transfer subgraph query, plus one backend timeseries request when
+// peer transfers exist. Any failure yields a zero basis, which leaves the
+// getter exactly where it was without transfers (the history guard decides).
+async function fetchTransferCostBasis(vault, wallet, provider, headers, exclude = []) {
+    const none = { receivedRaw: BigInt(0), sentRaw: BigInt(0) };
+    let shareTransfers = [];
+    try {
+        shareTransfers = await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, vault, undefined, { receiptSubgraph: true });
+        const transfers = selectPeerTransfers(shareTransfers, wallet, vault, exclude);
+        if (transfers.length === 0)
+            return { basis: none, shareTransfers };
+        const data = await fetchShareRatios(vault, Math.min(...transfers.map((t) => Number(t.timestamp_))), headers);
+        return {
+            basis: transferCostBasis({
+                transfers,
+                wallet,
+                vault,
+                history: data,
+                countSentWithoutReceipt: true,
+            }),
+            shareTransfers,
+        };
+    }
+    catch (e) {
+        core_1.Logger.log.warn('getVaultUserLifetimePnl:transferCostBasis', `Failed to price shares received by transfer: ${e}`);
+        return { basis: none, shareTransfers };
+    }
+}
+// The vault's daily history from `since` (unix seconds) on. A vault whose
+// history stops before then (a closed vault) is read in full instead, so the
+// latest earlier day still prices it.
+async function fetchShareRatios(vault, since, headers) {
+    const nDays = Math.ceil((Date.now() / 1000 - since) / 86_400) + 1;
+    const { data } = await (0, core_1.fetchVaultHistoricalTimeseries)(vault, nDays, headers);
+    const usable = Object.values(data ?? {}).some((day) => Number.isFinite(day.asset_share_ratio) &&
+        (day.asset_share_ratio ?? 0) > 0);
+    if (usable)
+        return data;
+    return (await (0, core_1.fetchVaultHistoricalTimeseries)(vault, 3650, headers)).data;
+}
+// Values a Tokenized Vault V2 wallet's redemption requests: one lagDuration()
+// read and one backend timeseries request. Undefined when either fails, so the
+// caller values every request at the current share price.
+async function readV2Redemptions(provider, vault, history, headers) {
+    try {
+        const contract = (0, core_1.createContract)({
+            provider,
+            address: vault,
+            abi: TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2,
+        });
+        const now = Math.floor(Date.now() / 1000);
+        const earliest = Math.min(...history
+            .filter((item) => item.type === 'withdraw-request')
+            .map((item) => Number(item.timestamp_)));
+        const [lagDuration, data] = await Promise.all([
+            readLagDuration(contract, vault, 'getVaultUserLifetimePnl'),
+            fetchShareRatios(vault, earliest, headers),
+        ]);
+        return settleV2Redemptions({ history, lagDuration, ratios: data, now });
+    }
+    catch (e) {
+        core_1.Logger.log.warn('getVaultUserLifetimePnl:v2Redemptions', `Failed to value redemption requests: ${e}`);
+        return undefined;
+    }
+}
+/**
+ * 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.
+ *
+ * Every USD field is the native amount times the underlying asset's USD price
+ * from the price server. There is no stand-in price: when none resolves the
+ * getter throws rather than returning USD values it cannot know.
+ *
+ * Shares moved by transfer: peer transfers of the share token (see
+ * {@link selectPeerTransfers}) are valued at the vault's daily share ratio
+ * ({@link transferCostBasis}) and folded in by {@link pnlCostBasis} — received
+ * shares add to `totalDeposited` (and are reported again as
+ * `receivedByTransfer`), sent shares add to `totalWithdrawn`. This holds
+ * alongside indexed deposits, so a wallet that received shares and also
+ * deposited is not credited with the received shares as profit. On LayerZero
+ * OVaults, transfers from or to the hub composer and share OFT do not count,
+ * because the composer delivers cross-chain deposits by transfer and those
+ * are already counted as LayerZero deposits.
+ *
+ * Gaps in the indexed history: a share mint with no `Deposit` event counts as
+ * a deposit of the assets in its `ReserveDeposit` event
+ * ({@link selectReserveDeposits}; High Growth ETH emits it for Kelp gain-adapter
+ * deposits), and a withdrawal request the vault logged twice counts once
+ * ({@link countWithdrawalRequestsOnce}). Transfers fold in for a depositor only
+ * once every mint is explained. A wallet with no indexed deposit and a mint
+ * that no deposit explains throws `HISTORY_UNAVAILABLE`.
+ *
+ * Tokenized Vault V2 redemptions carry only shares, so a settled one counts at
+ * the assets the vault paid, or at the share ratio on its claim date when the
+ * subgraph has no processed row for it ({@link settleV2Redemptions}). Only a
+ * request not yet claimable is valued at the current share price. When the lag
+ * or the ratio history cannot be read, every request is valued at the current
+ * share price instead.
+ *
+ * Request cost: one receipt-transfer subgraph query (and a `symbol()` RPC read)
+ * per call, plus one backend timeseries request when peer transfers exist and
+ * one `reserveDeposits` subgraph query when a mint has no indexed deposit, and
+ * for a Tokenized Vault V2 wallet with redemption requests, a `lagDuration()`
+ * read plus one backend timeseries request. A timeseries window with no usable
+ * ratio (a closed vault whose history stopped earlier) is read again in full,
+ * so the latest earlier day still prices it. The transfer query runs for
+ * every vault, in parallel with the history read.
+ *
+ * @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
+ * @throws {@link UpshiftHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+ *   live position has no indexed deposits, withdrawals or priceable share
+ *   transfers, or has no indexed deposit while a share mint to the wallet has
+ *   no matching deposit.
+ * @throws {@link UpshiftPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+ *   underlying asset has no USD price, or `asset()` cannot be read.
+ */
+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);
+        const lzVaultKey = (0, deposits_1.isLayerZeroVault)(vault);
+        const headers = options?.headers;
+        // Peer transfers always count (see pnlCostBasis), so start that read
+        // alongside the history instead of after it. A LayerZero OVault's hub
+        // composer and share OFT are not peers.
+        const transferCostBasisPromise = fetchTransferCostBasis(vault, wallet, provider, headers, lzVaultKey
+            ? [
+                deposits_1.LAYERZERO_VAULTS[lzVaultKey].hubComposer,
+                deposits_1.LAYERZERO_VAULTS[lzVaultKey].hubShareOFT,
+            ]
+            : []);
+        // 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
+        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 };
+        })();
+        const { basis: transfers, shareTransfers } = await transferCostBasisPromise;
+        // Process history - count all withdrawal requests (both processed and pending)
+        // We don't count processed withdrawals separately to avoid double counting,
+        // except on Tokenized Vault V2 (below), whose requests carry only shares.
+        // 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);
+        let requestedShares = BigInt(0);
+        // ignore bad transactions when calculating pnl
+        const history = countWithdrawalRequestsOnce({
+            history: userHistory,
+            transfers: shareTransfers,
+            wallet,
+            vault,
+        }).filter((item) => !(0, core_1.isBadTransaction)(item.transactionHash_, tokenizedVault.chain));
+        for (const historyItem of history) {
+            const amount = BigInt(historyItem.amount);
+            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
+                requestedShares += amount;
+            }
+            else if (historyItem.type === 'withdraw-processed' &&
+                historyItem.isInstant) {
+                // Instant withdrawals are already in assets, no conversion needed
+                totalWithdrawalsInAssets += amount;
+            }
+        }
+        // A V2 request is worth what the vault paid when it settled it, not the
+        // current share price (see settleV2Redemptions).
+        const v2Redemptions = version === 'evm-2' && requestedShares > BigInt(0)
+            ? await readV2Redemptions(provider, vault, history, headers)
+            : undefined;
+        if (v2Redemptions) {
+            totalWithdrawalsInShares += v2Redemptions.pendingShares;
+            totalWithdrawalsInAssets += v2Redemptions.settledAssetsRaw;
+        }
+        else {
+            totalWithdrawalsInShares += requestedShares;
+        }
+        // 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);
+            }
+        }
+        const depositTransactionHashes = userHistory
+            .filter((item) => item.type === 'deposit')
+            .map((item) => item.transactionHash_);
+        let mintsMatchHistory = historyCoversMints({
+            transfers: shareTransfers,
+            wallet,
+            depositTransactionHashes,
+        });
+        if (!mintsMatchHistory) {
+            const reserveDeposits = selectReserveDeposits({
+                reserveDeposits: await (0, vaults_1.getSubgraphUserReserveDeposits)(wallet, provider, vault),
+                transfers: shareTransfers,
+                wallet,
+                depositTransactionHashes,
+            }).filter((deposit) => !(0, core_1.isBadTransaction)(deposit.transactionHash_, tokenizedVault.chain));
+            for (const deposit of reserveDeposits) {
+                depositsByAsset.set('default', (depositsByAsset.get('default') ?? BigInt(0)) +
+                    BigInt(deposit.assets));
+            }
+            mintsMatchHistory = historyCoversMints({
+                transfers: shareTransfers,
+                wallet,
+                depositTransactionHashes: [
+                    ...depositTransactionHashes,
+                    ...reserveDeposits.map((deposit) => deposit.transactionHash_),
+                ],
+            });
+        }
+        const hasDeposits = depositsByAsset.size > 0;
+        // 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 costBasis = pnlCostBasis({
+            depositedRaw: totalDepositedNativeRaw,
+            withdrawnAssetsRaw: totalWithdrawnRaw,
+            hasDeposits,
+            mintsMatchHistory,
+            transfers,
+        });
+        const totalWithdrawn = (0, core_1.toNormalizedBn)(costBasis.withdrawnAssetsRaw, 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,
+            mintsMatchHistory,
+            receivedByTransferRaw: costBasis.receivedByTransferRaw,
+            totalWithdrawnRaw: costBasis.withdrawnAssetsRaw,
+            currentPositionRaw: BigInt(currentPositionValue.raw),
+        });
+        const tokenPriceUsd = assertPnlTokenPrice({
+            vault,
+            wallet,
+            asset: underlyingAssetAddress,
+            tokenPriceUsd: await pricePromise,
+        });
+        // 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)(costBasis.depositedRaw, decimals);
+        const totalDepositedUsd = Number(totalDeposited.normalized) * tokenPriceUsd;
+        const receivedByTransfer = (0, core_1.toNormalizedBn)(costBasis.receivedByTransferRaw, decimals);
+        const receivedByTransferUsd = Number(receivedByTransfer.normalized) * tokenPriceUsd;
+        const totalWithdrawnUsd = Number(totalWithdrawn.normalized) * tokenPriceUsd;
+        const currentPositionValueUsd = Number(currentPositionValue.normalized) * tokenPriceUsd;
+        // 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(tokenPriceUsd * 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,
+            receivedByTransfer,
+            receivedByTransferUsd,
+        };
+    }
+    catch (e) {
+        core_1.Logger.log.error('getVaultUserLifetimePnl', e, { vault, wallet });
+        // Preserve the typed history and price guards so callers can distinguish
+        // an unavailable-history or unavailable-price failure from a generic getter
+        // error. Their messages already carry the
+        // `#getVaultUserLifetimePnl::vault::wallet` prefix.
+        if (e instanceof errors_1.UpshiftHistoryUnavailableError ||
+            e instanceof errors_1.UpshiftPriceUnavailableError)
+            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.
+ *
+ * Sums, over the vault's whole history, each day's change in assets per share
+ * times that day's total shares, then prices the result at the receipt
+ * token's current USD price. The daily history comes from
+ * `GET /tokenized_vault/{vault}/historical-timeseries`, the replacement for the
+ * deprecated `load_snapshots` flag on the vault read.
+ *
+ * Network: one backend vault read, one timeseries read and one price read.
+ *
+ * @param vault - Vault contract address
+ * @param options - RPC configuration and service options
+ * @returns Vault PnL in the deposit asset (`totalPnl`) and in USD (`pnlUsd`).
+ *   Both are zero for a vault with no recorded history. `pnlUsd` is also zero
+ *   when the receipt token price cannot be fetched.
+ * @throws Error when `vault` is missing, is a Stellar vault, is not an
+ *   address, or the vault or its history cannot be read.
+ */
+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)}`);
+        // The vault row only supplies decimals, chain and receipt token, so skip
+        // its subaccounts and snapshots. 3650 days reads the full history, as
+        // `fetchShareRatios` does.
+        const [vaultData, { data: history }] = await Promise.all([
+            getVault({
+                vault,
+                loans: false,
+                allocations: false,
+                options,
+                loadSubaccounts: false,
+                loadSnapshots: false,
+            }),
+            (0, core_1.fetchVaultHistoricalTimeseries)(vault, 3650, options?.headers),
+        ]);
+        if (!vaultData) {
+            throw new Error(`Vault ${vault} not found`);
+        }
+        const decimals = vaultData.decimals;
+        // `daily_pnl` is the day's change in assets per share. It is zero on the
+        // first day and on forward-filled (`missing`) days, so those add nothing.
+        let totalPnlRaw = BigInt(0);
+        Object.values(history ?? {}).forEach((day) => {
+            if (!day.daily_pnl || !day.total_shares)
+                return;
+            // Convert normalized numbers to BigInt using toNormalizedBn's normalized string
+            const dailyPnlNorm = (0, core_1.toNormalizedBn)(day.daily_pnl, decimals);
+            const totalSharesNorm = (0, core_1.toNormalizedBn)(day.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;
+        });
+        // No history (or no PnL in it) prices to zero, so skip the price read.
+        if (totalPnlRaw === BigInt(0)) {
+            return { totalPnl: (0, core_1.toNormalizedBn)(0, decimals), pnlUsd: 0 };
+        }
+        // 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 in the next major release.
+ * 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.fetchUpshiftPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        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.fetchUpshiftPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        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.fetchUpshiftPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        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.fetchUpshiftPublic)(endpoint, {
+            headers: options?.headers,
+            server: 'public',
+        });
+        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, false, false))?.[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);
+}
+/**
+ * Upper bound on concurrent `getTransaction` decodes inside
+ * {@link getWithdrawalRequestsWithStatus}. One RPC per processed event; eight
+ * in flight keeps latency near the fully-parallel case without letting a long
+ * lookback window open hundreds of simultaneous requests to one endpoint.
+ */
+const PROCESSED_DECODE_CONCURRENCY = 8;
+/**
+ * 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
+ *
+ * @worstCaseRpcCalls 1 (`lagDuration`) + the `eth_getLogs` scan in
+ *   `getVaultRedemptionHistory` + 1 (`eth_blockNumber`) + one `getTransaction`
+ *   per `WithdrawalProcessed` event in the lookback window, run at most
+ *   {@link PROCESSED_DECODE_CONCURRENCY} at a time. A vault with 50 processed
+ *   withdrawals in the window therefore makes ~53 RPC calls plus the log
+ *   scan, never more than 8 of them concurrently.
+ *
+ * @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,
+        });
+        // Same resolution as getVaultAvailableRedemptions: a vault that does not
+        // implement `lagDuration()` has no claim lag (0). The old 86400 default
+        // here put every claimable-date key one day after the one the
+        // redemptions scan computed, so matching requests to processed events
+        // failed and already-processed requests surfaced as `ready_to_claim`.
+        const lagDuration = await readLagDuration(vaultContract, vaultAddress, options.rpcUrl);
+        // 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, at most
+        // PROCESSED_DECODE_CONCURRENCY in flight: each decode is a
+        // `getTransaction` RPC, and a vault with hundreds of processed
+        // withdrawals in the lookback window would otherwise open them all at
+        // once against a single endpoint.
+        const iface = new ethers_1.Interface(vaultAbi);
+        const decodedProcessed = await (0, concurrency_1.mapWithConcurrency)(processedEvents || [], PROCESSED_DECODE_CONCURRENCY, 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