@augustdigital/sdk 9.5.0 → 9.7.0

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

@@ -1,4 +1,4 @@
-import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ITokenizedVault, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
+import { type IAddress, type IHistoricalTimeseriesPoint, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ISubgraphTransfer, type ITokenizedVault, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
 import type { IVaultBaseOptions } from './types';
 /**
  * Vault Data Getters
@@ -337,15 +337,10 @@ export interface PnlHistoryConsistencyParams {
  * Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot
  * path with no added latency.
  *
- * Known imprecision — vault shares are transferable ERC-20 receipt tokens, so a
- * wallet that *received* shares via a direct token transfer (never deposited,
- * never withdrew) legitimately has `position > 0` with no history records and
- * will throw `HISTORY_UNAVAILABLE` even though its history loaded fine. This is
- * not a regression — the pre-guard formula reported that same position as 100%
- * profit, which was also wrong — but the error message is misleading for that
- * (rare) path. If receipt-token transfer becomes a real user flow, distinguish
- * it here (e.g. by checking for a share-transfer event) rather than widening
- * the guard.
+ * Shares received by a direct token transfer (never deposited, never withdrew)
+ * reach this guard as deposits: {@link getVaultUserLifetimePnl} prices them
+ * with {@link transferCostBasis} first. The guard still throws for such a
+ * wallet when its transfers cannot be read or priced.
  *
  * @param params - See {@link PnlHistoryConsistencyParams}.
  * @returns `void` when the history is consistent.
@@ -366,6 +361,53 @@ export interface PnlHistoryConsistencyParams {
  * ```
  */
 export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
+/** Inputs the lifetime-PnL price guard inspects. */
+export interface PnlTokenPriceParams {
+    /** Vault contract address, used for the error message and context. */
+    vault: IAddress;
+    /** User wallet address, used for the error message and context. */
+    wallet: IAddress;
+    /**
+     * The vault's underlying asset (`asset()`) that was priced, or `undefined`
+     * when `asset()` could not be read and no price lookup was possible.
+     */
+    asset: IAddress | undefined;
+    /**
+     * USD price of `asset` as resolved by the price server. `0` means the lookup
+     * failed or the token is unknown to it (`fetchTokenPriceByAddress` never
+     * throws).
+     */
+    tokenPriceUsd: number;
+}
+/**
+ * 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 AugustPriceUnavailableError} 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,
+ * });
+ * ```
+ */
+export declare function assertPnlTokenPrice({ vault, wallet, asset, tokenPriceUsd, }: PnlTokenPriceParams): number;
 /**
  * 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
@@ -391,6 +433,88 @@ export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits,
  * @returns Total deposited, in raw base units at `vaultDecimals`.
  */
 export declare function sumDepositsAtFaceValue(depositsByAsset: Map<string, bigint>, assetDecimals: Map<string, number>, vaultDecimals: number): bigint;
+/** The receipt-token transfer fields the transfer cost basis reads. */
+export type PnlTransfer = Pick<ISubgraphTransfer, 'from' | 'to' | 'value' | 'timestamp_'>;
+/**
+ * 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.
+ *
+ * @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.
+ * @returns The peer-to-peer transfers, in input order. Addresses compare
+ *   case-insensitively.
+ * @example
+ * ```ts
+ * const peer = selectPeerTransfers(transfers, wallet, vault);
+ * ```
+ */
+export declare function selectPeerTransfers<T extends PnlTransfer>(transfers: T[], wallet: IAddress, vault: IAddress): T[];
+/** Inputs {@link transferCostBasis} prices. */
+export interface TransferCostBasisParams {
+    /** Peer transfers touching `wallet` — see {@link selectPeerTransfers}. */
+    transfers: PnlTransfer[];
+    /** The wallet whose cost basis is being computed. */
+    wallet: IAddress;
+    /** The vault contract address, used for the error message and context. */
+    vault: IAddress;
+    /**
+     * The vault's daily history from `fetchVaultHistoricalTimeseries`, keyed by
+     * UTC date (`YYYY-MM-DD`). Only `asset_share_ratio` (assets per share) is
+     * read.
+     */
+    history: Record<string, Pick<IHistoricalTimeseriesPoint, 'asset_share_ratio'>>;
+}
+/** Asset amounts that peer transfers moved into and out of a position. */
+export interface TransferCostBasis {
+    /** Assets the received shares were worth on arrival, raw at vault decimals. */
+    receivedRaw: bigint;
+    /** Assets the sent shares were worth when they left, raw at vault decimals. */
+    sentRaw: bigint;
+}
+/**
+ * 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. 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.
+ *
+ * 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 AugustHistoryUnavailableError} (`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,
+ * });
+ * ```
+ */
+export declare function transferCostBasis({ transfers, wallet, vault, history, }: TransferCostBasisParams): TransferCostBasis;
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *
@@ -408,10 +532,27 @@ export declare function sumDepositsAtFaceValue(depositsByAsset: Map<string, bigi
  * 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 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.
+ *
  * @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 AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+ *   live position has no indexed deposits, withdrawals or priceable share
+ *   transfers.
+ * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+ *   underlying asset has no USD price, or `asset()` cannot be read.
  */
 export declare function getVaultUserLifetimePnl({ vault, wallet, options, }: {
     vault: IAddress;

package/lib/modules/vaults/getters.js

@@ -54,7 +54,10 @@ 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.getVaultUserLifetimePnl = getVaultUserLifetimePnl;
 exports.getVaultPnl = getVaultPnl;
 exports.getVaultHistoricalTimeseries = getVaultHistoricalTimeseries;
@@ -1540,13 +1543,26 @@ async function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, o
                     }
                 }
                 const balance = (0, core_1.toNormalizedBn)(bal, decimals);
-                // check available redemptions
-                const { availableRedemptions, pendingRedemptions } = await getVaultAvailableRedemptions({
-                    vault: v.address,
-                    wallet,
-                    options,
-                    prefetchedReads: prefetched,
-                });
+                // 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
@@ -2260,15 +2276,10 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  * Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot
  * path with no added latency.
  *
- * Known imprecision — vault shares are transferable ERC-20 receipt tokens, so a
- * wallet that *received* shares via a direct token transfer (never deposited,
- * never withdrew) legitimately has `position > 0` with no history records and
- * will throw `HISTORY_UNAVAILABLE` even though its history loaded fine. This is
- * not a regression — the pre-guard formula reported that same position as 100%
- * profit, which was also wrong — but the error message is misleading for that
- * (rare) path. If receipt-token transfer becomes a real user flow, distinguish
- * it here (e.g. by checking for a share-transfer event) rather than widening
- * the guard.
+ * Shares received by a direct token transfer (never deposited, never withdrew)
+ * reach this guard as deposits: {@link getVaultUserLifetimePnl} prices them
+ * with {@link transferCostBasis} first. The guard still throws for such a
+ * wallet when its transfers cannot be read or priced.
  *
  * @param params - See {@link PnlHistoryConsistencyParams}.
  * @returns `void` when the history is consistent.
@@ -2295,6 +2306,39 @@ function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawn
         throw new errors_1.AugustHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:transaction history unavailable — a live position exists but no deposits or withdrawals were indexed, so lifetime PnL cannot be computed without over-reporting the entire position as profit`, { context: { vault, wallet } });
     }
 }
+/**
+ * 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 AugustPriceUnavailableError} 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.AugustPriceUnavailableError(`#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
@@ -2335,6 +2379,130 @@ function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
     }
     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.
+ *
+ * @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.
+ * @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) {
+    const self = wallet.toLowerCase();
+    const excluded = new Set([ethers_1.ZeroAddress.toLowerCase(), vault.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. 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.
+ *
+ * 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 AugustHistoryUnavailableError} (`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, }) {
+    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.AugustHistoryUnavailableError(`#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))
+        return { receivedRaw, sentRaw: BigInt(0) };
+    return { receivedRaw, sentRaw };
+}
+// 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) {
+    const none = { receivedRaw: BigInt(0), sentRaw: BigInt(0) };
+    try {
+        const transfers = selectPeerTransfers(await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, vault, undefined, {
+            receiptSubgraph: true,
+        }), wallet, vault);
+        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 });
+    }
+    catch (e) {
+        core_1.Logger.log.warn('getVaultUserLifetimePnl:transferCostBasis', `Failed to price shares received by transfer: ${e}`);
+        return none;
+    }
+}
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *
@@ -2352,10 +2520,27 @@ function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
  * 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 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.
+ *
  * @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 AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+ *   live position has no indexed deposits, withdrawals or priceable share
+ *   transfers.
+ * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+ *   underlying asset has no USD price, or `asset()` cannot be read.
  */
 async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
     try {
@@ -2504,6 +2689,15 @@ 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;
+        }
         // Fetch decimals for each unique asset in parallel
         const assetDecimals = new Map();
         await Promise.all(Array.from(depositsByAsset.keys()).map(async (assetAddress) => {
@@ -2663,25 +2857,25 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
             totalWithdrawnRaw,
             currentPositionRaw: BigInt(currentPositionValue.raw),
         });
-        const tokenPriceUsd = await pricePromise;
-        // Validate token price and log warning if invalid
-        const effectiveTokenPrice = tokenPriceUsd > 0 ? tokenPriceUsd : 1;
-        if (tokenPriceUsd <= 0) {
-            core_1.Logger.log.warn('getVaultUserLifetimePnl:tokenPrice', `Invalid underlying token price: ${tokenPriceUsd}, using fallback of 1`);
-        }
+        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)(totalDepositedNativeRaw, decimals);
-        const totalDepositedUsd = Number(totalDeposited.normalized) * effectiveTokenPrice;
-        const totalWithdrawnUsd = Number(totalWithdrawn.normalized) * effectiveTokenPrice;
-        const currentPositionValueUsd = Number(currentPositionValue.normalized) * effectiveTokenPrice;
+        const totalDepositedUsd = Number(totalDeposited.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(effectiveTokenPrice * Number(scaleFactor)));
+        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)
@@ -2706,10 +2900,12 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
     }
     catch (e) {
         core_1.Logger.log.error('getVaultUserLifetimePnl', e, { vault, wallet });
-        // Preserve the typed history guard so callers can distinguish an
-        // unavailable-history failure from a generic getter error. Its message
-        // already carries the `#getVaultUserLifetimePnl::vault::wallet` prefix.
-        if (e instanceof errors_1.AugustHistoryUnavailableError)
+        // 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.AugustHistoryUnavailableError ||
+            e instanceof errors_1.AugustPriceUnavailableError)
             throw e;
         const errorMessage = e instanceof Error ? e.message : String(e);
         throw new Error(`#getVaultUserLifetimePnl::${vault}::${wallet}:${errorMessage}`);

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

@@ -244,6 +244,11 @@ export declare class AugustVaults extends AugustBase {
      * Get lifetime PnL for a user in a specific vault.
      * @param props Vault address, wallet address, and optional chain ID
      * @returns Lifetime PnL data including realized and unrealized PnL
+     * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+     *   live position has no indexed deposits, withdrawals or priceable share
+     *   transfers.
+     * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+     *   vault's underlying asset has no USD price.
      */
     getVaultUserLifetimePnl({ vault, wallet, chainId, }: {
         vault: IAddress;

package/lib/modules/vaults/main.js

@@ -933,6 +933,11 @@ class AugustVaults extends core_1.AugustBase {
      * Get lifetime PnL for a user in a specific vault.
      * @param props Vault address, wallet address, and optional chain ID
      * @returns Lifetime PnL data including realized and unrealized PnL
+     * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+     *   live position has no indexed deposits, withdrawals or priceable share
+     *   transfers.
+     * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+     *   vault's underlying asset has no USD price.
      */
     async getVaultUserLifetimePnl({ vault, wallet, chainId, }) {
         if (!(0, ethers_1.isAddress)(wallet))

package/lib/modules/vaults/write.actions.d.ts

@@ -535,6 +535,14 @@ export declare function depositViaSwapRouter(signer: Signer | Wallet, options: I
  * before depositing — only valid when the vault's reference asset equals
  * the wrapped-native token.
  *
+ * **Wrap-only limitation**: the on-chain SwapRouter has no ETH→other-asset
+ * swap leg, so this only ever reaches a WETH-accepting vault (see
+ * {@link SWAP_ROUTER_WRAPPED_NATIVE}). There is no atomic native-ETH deposit
+ * into a non-WETH-reference vault (e.g. a USDC vault) — deposit the wrapped
+ * native token instead (already whitelisted, routes through the swap leg for
+ * a non-reference-asset vault). Use {@link isNativeSwapRouterDepositSupported}
+ * to check eligibility before offering this path in a UI.
+ *
  * No ERC-20 approval is needed; `amount` travels as `msg.value`.
  *
  * @param signer - ethers `Signer` or `Wallet`.
@@ -545,6 +553,51 @@ export declare function depositViaSwapRouter(signer: Signer | Wallet, options: I
  * addresses, or zero amount.
  */
 export declare function depositNativeViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterNativeDepositOptions): Promise<string>;
+/**
+ * Whether a vault can take a native-ETH (chain-native token) SwapRouter
+ * deposit — the pre-flight check for {@link depositNativeViaSwapRouter} and
+ * {@link swapRouterDeposit} with a zero-address `depositAsset`.
+ *
+ * The on-chain SwapRouter only wraps native ETH to the chain's wrapped-native
+ * token and deposits that — it has no ETH→other-asset swap leg (see
+ * {@link SWAP_ROUTER_WRAPPED_NATIVE}). So a native deposit needs all three: a
+ * SwapRouter deployed on `chainId`, the vault registered on that router with
+ * the wrapped-native token as its `vaultInfo(vault).referenceAsset` (a
+ * deposit into an unregistered vault reverts with `InvalidVault`), and the
+ * vault's own on-chain `asset()` equal to that same token. Use this to gate a
+ * "deposit ETH" UI option before the user picks it, instead of discovering
+ * the answer via a thrown {@link AugustValidationError} or an on-chain revert.
+ *
+ * It checks configuration only — a deposit that passes this check can still
+ * fail on balance, gas, a paused vault, or a deposit cap.
+ *
+ * Read-only and provider-agnostic (no signer required) — safe to call before
+ * a wallet is connected. Makes no backend call.
+ *
+ * @param chainId - EVM chain ID the vault is deployed on.
+ * @param vault - August vault address to check.
+ * @param options - `rpcUrl` for `chainId`, passed to `createProvider`.
+ * @returns `true` iff a SwapRouter exists on `chainId`, the vault is
+ *   registered on it with the wrapped-native reference asset, and the vault's
+ *   `asset()` is that token. `false` — never throws — for a chain with no
+ *   SwapRouter deployment, a missing/invalid `rpcUrl`, an unreadable vault or
+ *   router, an unregistered vault, or a vault whose reference asset isn't the
+ *   wrapped-native token.
+ * @worstCaseRpcCalls 2 — the vault's `asset()` and the router's
+ *   `vaultInfo(vault)`, read in parallel. None on a chain with no SwapRouter.
+ * @example
+ * ```ts
+ * const canDepositEth = await isNativeSwapRouterDepositSupported(
+ *   1,
+ *   '0x1234000000000000000000000000000000005678',
+ *   { rpcUrl: 'https://eth-mainnet.example/v2/KEY' },
+ * );
+ * // true only if that vault is a router-registered WETH vault on mainnet
+ * ```
+ */
+export declare function isNativeSwapRouterDepositSupported(chainId: number, vault: IAddress, options: {
+    rpcUrl: string;
+}): Promise<boolean>;
 /**
  * Deposit into an August vault through the on-chain `SwapRouter`, selecting the
  * correct router path from the deposit asset. This is the high-level, explicit
@@ -564,7 +617,10 @@ export declare function depositNativeViaSwapRouter(signer: Signer | Wallet, opti
  *  - equals the reference asset → direct router deposit, no swap
  *    ({@link depositViaSwapRouter});
  *  - the zero address → native-token deposit ({@link depositNativeViaSwapRouter}),
- *    valid only when the reference asset is the chain's wrapped-native token;
+ *    valid only when the reference asset is the chain's wrapped-native token —
+ *    the router only wraps ETH, it never swaps it, so this throws for any
+ *    other reference asset (see {@link SWAP_ROUTER_WRAPPED_NATIVE} for why, and
+ *    {@link isNativeSwapRouterDepositSupported} to check first);
  *  - any other ERC-20 → a swap to the reference asset (Paraswap quote pinned to
  *    the chain's whitelisted aggregator, fail-closed on router/selector drift)
  *    bundled into {@link swapAndDeposit}.