@augustdigital/sdk 9.8.0 → 9.9.0

package/lib/modules/vaults/getters.js

@@ -58,6 +58,11 @@ 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;
@@ -2388,12 +2393,15 @@ function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
  * 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.
+ * 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
@@ -2401,9 +2409,9 @@ function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
  * const peer = selectPeerTransfers(transfers, wallet, vault);
  * ```
  */
-function selectPeerTransfers(transfers, wallet, vault) {
+function selectPeerTransfers(transfers, wallet, vault, exclude = []) {
     const self = wallet.toLowerCase();
-    const excluded = new Set([ethers_1.ZeroAddress.toLowerCase(), vault.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();
@@ -2423,9 +2431,11 @@ function selectPeerTransfers(transfers, wallet, vault) {
  * 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. 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.
+ * 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.
@@ -2446,7 +2456,7 @@ function selectPeerTransfers(transfers, wallet, vault) {
  * });
  * ```
  */
-function transferCostBasis({ transfers, wallet, vault, history, }) {
+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)
@@ -2478,29 +2488,341 @@ function transferCostBasis({ transfers, wallet, vault, history, }) {
             sentRaw += assetsAt(shares, transfer.timestamp_);
         }
     }
-    if (receivedRaw === BigInt(0))
+    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. 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) {
+async function fetchTransferCostBasis(vault, wallet, provider, headers, exclude = []) {
     const none = { receivedRaw: BigInt(0), sentRaw: BigInt(0) };
+    let shareTransfers = [];
     try {
-        const transfers = selectPeerTransfers(await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, vault, undefined, {
-            receiptSubgraph: true,
-        }), wallet, vault);
+        shareTransfers = await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, vault, undefined, { receiptSubgraph: true });
+        const transfers = selectPeerTransfers(shareTransfers, wallet, vault, exclude);
         if (transfers.length === 0)
-            return none;
-        const earliest = Math.min(...transfers.map((t) => Number(t.timestamp_)));
-        const nDays = Math.ceil((Date.now() / 1000 - earliest) / 86_400) + 1;
-        const { data } = await (0, core_1.fetchVaultHistoricalTimeseries)(vault, nDays, headers);
-        return transferCostBasis({ transfers, wallet, vault, history: data });
+            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 none;
+        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;
     }
 }
 /**
@@ -2524,13 +2846,39 @@ async function fetchTransferCostBasis(vault, wallet, provider, headers) {
  * 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 received by transfer: when history has no deposit, peer transfers of
- * the share token (see {@link selectPeerTransfers}) are valued at the vault's
- * daily share ratio ({@link transferCostBasis}) — received shares become
- * `totalDeposited`, sent shares add to `totalWithdrawn`. PnL for such a wallet
- * therefore runs from the day its shares arrived. This costs one extra
- * subgraph query, plus one backend timeseries request when transfers exist,
- * and only for wallets with no indexed deposit.
+ * 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. LayerZero
+ * OVaults count transfers only when history holds no deposit, because their
+ * composer delivers cross-chain deposits by transfer.
+ *
+ * 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.
+ *
+ * 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. For
+ * non-LayerZero vaults the transfer query runs in parallel with the history
+ * read; for LayerZero vaults it runs only when history holds no deposit.
  *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
@@ -2554,6 +2902,17 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         if (!(0, ethers_1.isAddress)(wallet))
             throw new Error(`Wallet input parameter is not an address: ${String(wallet)}`);
         const provider = (0, core_1.createProvider)(options.rpcUrl);
+        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),
@@ -2579,7 +2938,6 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             throw new Error(`Failed to resolve decimals for vault ${vault}`);
         }
         // Fetch LayerZero deposits/redeems for supported vaults
-        const lzVaultKey = (0, deposits_1.isLayerZeroVault)(vault);
         let lzDeposits = [];
         let lzRedeems = [];
         if (lzVaultKey) {
@@ -2639,19 +2997,25 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             }
             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
+        // 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);
-        for (const historyItem of userHistory) {
+        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);
-            // ignore bad transactions when calculating pnl
-            if ((0, core_1.isBadTransaction)(historyItem.transactionHash_, tokenizedVault.chain)) {
-                continue;
-            }
             if (historyItem.type === 'deposit') {
                 // Use assetIn if available (V2 vaults), otherwise use a default key
                 // Use proper type guard instead of type assertion
@@ -2663,7 +3027,7 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             }
             else if (historyItem.type === 'withdraw-request') {
                 // Withdraw requests are in shares, need conversion to assets
-                totalWithdrawalsInShares += amount;
+                requestedShares += amount;
             }
             else if (historyItem.type === 'withdraw-processed' &&
                 historyItem.isInstant) {
@@ -2671,6 +3035,18 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                 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) {
@@ -2689,15 +3065,35 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
                 totalWithdrawalsInShares += BigInt(lzRedeem.shareAmt);
             }
         }
-        // A wallet can hold shares it never deposited (a migration airdrop, a DEX
-        // purchase). Only when history has no deposit at all do received shares
-        // become the cost basis, so a depositor's PnL is computed as before.
-        if (depositsByAsset.size === 0) {
-            const { receivedRaw, sentRaw } = await fetchTransferCostBasis(vault, wallet, provider, options?.headers);
-            if (receivedRaw > BigInt(0))
-                depositsByAsset.set('default', receivedRaw);
-            totalWithdrawalsInAssets += sentRaw;
+        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) => {
@@ -2845,7 +3241,14 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             // For non-evm-2 or when share price is 0, treat shares as assets
             totalWithdrawnRaw += totalWithdrawalsInShares;
         }
-        const totalWithdrawn = (0, core_1.toNormalizedBn)(totalWithdrawnRaw, decimals);
+        const 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
@@ -2853,8 +3256,8 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         assertPnlHistoryConsistent({
             vault,
             wallet,
-            hasDeposits: depositsByAsset.size > 0,
-            totalWithdrawnRaw,
+            hasDeposits: hasDeposits || costBasis.receivedByTransferRaw > BigInt(0),
+            totalWithdrawnRaw: costBasis.withdrawnAssetsRaw,
             currentPositionRaw: BigInt(currentPositionValue.raw),
         });
         const tokenPriceUsd = assertPnlTokenPrice({
@@ -2867,8 +3270,10 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         // computed above) — convert to USD with the same underlying price used
         // for the other two legs below, so all three legs share one conversion
         // factor instead of drifting independently against each other.
-        const totalDeposited = (0, core_1.toNormalizedBn)(totalDepositedNativeRaw, decimals);
+        const 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)
@@ -2896,6 +3301,8 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             lifetimePnl,
             lifetimePnlUsd,
             pnlPercentage,
+            receivedByTransfer,
+            receivedByTransferUsd,
         };
     }
     catch (e) {

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

@@ -7,7 +7,7 @@
  * Export getters
  */
 export * from './getters';
-import type { IAddress, IChainId, INormalizedNumber, IVaultHistoricalParams, IVaultPosition, IVaultUserHistoryItem } from '../../types';
+import type { IAddress, IChainId, IGetOriginInfoOptions, INormalizedNumber, IOriginInfo, IVaultHistoricalParams, IVaultPosition, IVaultUserHistoryItem } from '../../types';
 import type SolanaAdapter from '../../adapters/solana';
 import { AugustBase, type IAugustBase } from '../../core';
 import SuiAdapter from '../../adapters/sui';
@@ -382,6 +382,23 @@ export declare class AugustVaults extends AugustBase {
     getSwapRouterEligibleVaults(chainId: number, options?: {
         fromBlock?: number;
     }): Promise<IAddress[]>;
+    /**
+     * Read a SwapRouter origin code's on-chain registration through this
+     * instance's provider for `chainId`. See {@link getOriginInfo} for the
+     * registration rule and caching.
+     *
+     * @param options - `chainId` and the `bytes32` `originCode` to look up.
+     * @returns {@link IOriginInfo}.
+     * @throws AugustValidationError (`INVALID_CHAIN`) when no provider is
+     *   configured for `chainId`; (`INVALID_INPUT`) for a malformed code.
+     * @throws AugustSDKError when the `origins(bytes32)` read fails.
+     * @worstCaseRpcCalls 1 — one `origins(bytes32)` read, cached for 5 minutes.
+     * @example
+     * ```ts
+     * const info = await augustSdk.getOriginInfo({ chainId: 1, originCode });
+     * ```
+     */
+    getOriginInfo(options: Omit<IGetOriginInfoOptions, 'rpcUrl'>): Promise<IOriginInfo>;
     /**
      * @function getStakingPositions gets all available reward staking positions
      * @param wallet optionally passed user wallet address