@augustdigital/sdk 9.6.0 → 9.7.1

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.
@@ -438,6 +433,88 @@ export declare function assertPnlTokenPrice({ vault, wallet, asset, tokenPriceUs
  * @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.
  *
@@ -459,12 +536,21 @@ export declare function sumDepositsAtFaceValue(depositsByAsset: Map<string, bigi
  * 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 or withdrawals.
+ *   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.
  */

package/lib/modules/vaults/getters.js

@@ -56,6 +56,8 @@ 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;
@@ -1541,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
@@ -2261,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.
@@ -2369,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.
  *
@@ -2390,12 +2524,21 @@ function sumDepositsAtFaceValue(depositsByAsset, assetDecimals, vaultDecimals) {
  * 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 or withdrawals.
+ *   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.
  */
@@ -2546,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) => {

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

@@ -245,7 +245,8 @@ export declare class AugustVaults extends AugustBase {
      * @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 or withdrawals.
+     *   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.
      */

package/lib/modules/vaults/main.js

@@ -934,7 +934,8 @@ class AugustVaults extends core_1.AugustBase {
      * @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 or withdrawals.
+     *   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.
      */