@augustdigital/sdk 9.8.0 → 9.9.1

package/lib/core/helpers/swap-router.js

@@ -6,10 +6,15 @@ exports.getSwapRouterName = getSwapRouterName;
 exports.isSwapRouterEligible = isSwapRouterEligible;
 exports.resolveOriginCode = resolveOriginCode;
 exports.getSwapRouterDepositResult = getSwapRouterDepositResult;
+exports.getOriginInfo = getOriginInfo;
+exports.readOriginInfo = readOriginInfo;
+exports.readSwapRouterVaultInfo = readSwapRouterVaultInfo;
+exports.readSwapRouterTokenWhitelisted = readSwapRouterTokenWhitelisted;
 exports.getSwapRouterWhitelistedTokens = getSwapRouterWhitelistedTokens;
 exports.getSwapRouterEligibleVaults = getSwapRouterEligibleVaults;
 const ethers_1 = require("ethers");
 const swap_router_1 = require("../constants/swap-router");
+const attribution_1 = require("../attribution");
 const abis_1 = require("../../abis");
 const errors_1 = require("../errors");
 const cache_1 = require("../cache");
@@ -59,7 +64,7 @@ function getSwapRouterName(chainId) {
  *
  * This gates the (flag-controlled) swap-router deposit UI and can fail-fast a
  * {@link swapRouterDeposit} call. It does **not** affect {@link vaultDeposit},
- * which is always the native/multiasset/adapter path.
+ * which never swaps (see `getDepositRoute` for when it uses the router).
  *
  * @param vaultAddress - August vault address.
  * @returns `true` when the vault is in {@link SWAP_ROUTER_ELIGIBLE_VAULTS}.
@@ -84,21 +89,33 @@ exports.vaultUsesSwapRouter = isSwapRouterEligible;
 /**
  * Normalize an optional origin code to the value to send on-chain.
  *
- * Returns the caller-supplied code when present, otherwise the default
- * (all-zero) sentinel from {@link ORIGIN_CODES}. Validates that any
+ * Returns the caller-supplied code when present (an explicit all-zero
+ * sentinel opts one call out), otherwise the SDK instance's
+ * `attribution.originCode` when `chainId` is in
+ * {@link ORIGIN_ATTRIBUTION_CHAINS} (Ethereum mainnet only), otherwise the
+ * default (all-zero) sentinel from {@link ORIGIN_CODES}. Validates that any
  * supplied code is exactly 32 bytes (66 chars including the `0x` prefix);
  * the on-chain SwapRouter reverts with `InvalidOrigin` otherwise, but
  * surfacing the failure here as a typed SDK error gives partners a
  * grepable Sentry event instead of a generic `execution reverted`.
  *
  * @param provided - Optional caller-supplied origin code.
+ * @param chainId - Chain the deposit is sent on. The instance code is never
+ *   returned without it, or on a chain outside
+ *   {@link ORIGIN_ATTRIBUTION_CHAINS}.
  * @returns The 32-byte origin code to pass to the router.
  * @throws {@link AugustValidationError} when `provided` is not a 32-byte hex string.
  */
-function resolveOriginCode(provided) {
-    if (provided === undefined)
-        return swap_router_1.ORIGIN_CODES.default;
-    if (!/^0x[0-9a-fA-F]{64}$/.test(provided)) {
+function resolveOriginCode(provided, chainId) {
+    if (provided === undefined) {
+        const instanceCode = (0, attribution_1.getOriginCode)();
+        return instanceCode &&
+            chainId !== undefined &&
+            swap_router_1.ORIGIN_ATTRIBUTION_CHAINS.includes(chainId)
+            ? instanceCode
+            : swap_router_1.ORIGIN_CODES.default;
+    }
+    if (!swap_router_1.ORIGIN_CODE_PATTERN.test(provided)) {
         throw new errors_1.AugustValidationError('INVALID_INPUT', `resolveOriginCode: originCode must be a 32-byte hex string (66 chars incl. 0x), got "${provided}" (${provided.length} chars)`, { context: { provided, expectedLength: 66 } });
     }
     return provided;
@@ -181,6 +198,140 @@ async function getSwapRouterDepositResult(signer, { txHash, vault }) {
     }
     return null;
 }
+/** Cache TTL for resolved origin-code, vault and token registrations (5 minutes). */
+const SWAP_ROUTER_ORIGIN_INFO_TTL_MS = 5 * 60 * 1000;
+/**
+ * Read how an origin code is registered on a chain's `SwapRouter`: whether it
+ * exists, its origin fee, and its fee collector.
+ *
+ * Check a partner code with this before configuring it as
+ * `attribution.originCode` — the router reverts every deposit carrying an
+ * unregistered code with `InvalidOrigin`. A code is registered when its
+ * collector is non-zero (`addOrigin` always sets one); a zero-fee code is
+ * still registered but never emits `OriginFeeApplied`. Cached per (chain,
+ * router, code) for 5 minutes.
+ *
+ * @param options - {@link IGetOriginInfoOptions}.
+ * @returns {@link IOriginInfo}; `registered: false` with a zero fee and
+ *   collector, and no RPC, on a chain with no SwapRouter deployment.
+ * @throws {@link AugustValidationError} when `originCode` is not a 32-byte hex
+ *   string.
+ * @throws {@link AugustSDKError} when the `origins(bytes32)` read fails.
+ * @worstCaseRpcCalls 1 — one `origins(bytes32)` call; none on a cache hit.
+ * @example
+ * ```ts
+ * const info = await getOriginInfo({ chainId: 1, originCode, rpcUrl });
+ * if (!info.registered) throw new Error('origin code is not registered');
+ * ```
+ */
+async function getOriginInfo({ chainId, originCode, rpcUrl, }) {
+    if (!swap_router_1.ORIGIN_CODE_PATTERN.test(originCode)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `getOriginInfo: originCode must be a 32-byte hex string (66 chars incl. 0x), got ${String(originCode).length} chars`, { context: { chainId, expectedLength: 66 } });
+    }
+    try {
+        return await readOriginInfo(chainId, originCode, () => (0, web3_1.createProvider)(rpcUrl, chainId));
+    }
+    catch (e) {
+        if (e instanceof errors_1.AugustSDKError)
+            throw e;
+        throw new errors_1.AugustSDKError('UNKNOWN', `getOriginInfo failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { chainId } });
+    }
+}
+/**
+ * {@link getOriginInfo} without input validation, reading through a caller
+ * runner (created lazily, only on a cache miss). Shared with the deposit-route
+ * resolver so both hit the same cache entry.
+ * @internal
+ */
+async function readOriginInfo(chainId, originCode, runner) {
+    const unregistered = {
+        registered: false,
+        originFeeBps: 0,
+        collector: ethers_1.ethers.ZeroAddress,
+    };
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return unregistered;
+    const cacheKey = `swap-router-origin-${chainId}-${router.toLowerCase()}-${originCode.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached)
+        return cached;
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider: runner(),
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return unregistered;
+    const [originFee, originFeeCollector] = await contract.origins(originCode);
+    const info = {
+        registered: originFeeCollector !== ethers_1.ethers.ZeroAddress,
+        originFeeBps: Number(originFee),
+        collector: originFeeCollector,
+    };
+    cache_1.CACHE.set(cacheKey, info, { ttl: SWAP_ROUTER_ORIGIN_INFO_TTL_MS });
+    return info;
+}
+/**
+ * Read a vault's `SwapRouter` registration (`vaultInfo`), cached for 5
+ * minutes like the other router reads.
+ *
+ * @returns The router's `referenceAsset` for the vault (the zero address when
+ *   it is not registered) and its `vaultType`; `undefined` on a chain with no
+ *   SwapRouter.
+ * @internal
+ */
+async function readSwapRouterVaultInfo(runner, chainId, vault) {
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return undefined;
+    const cacheKey = `swap-router-vault-info-${chainId}-${router.toLowerCase()}-${vault.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached)
+        return cached;
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider: runner,
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return undefined;
+    const [, vaultType, referenceAsset] = await contract.vaultInfo(vault);
+    const info = {
+        referenceAsset: referenceAsset,
+        vaultType: Number(vaultType),
+    };
+    cache_1.CACHE.set(cacheKey, info, { ttl: SWAP_ROUTER_ORIGIN_INFO_TTL_MS });
+    return info;
+}
+/**
+ * Read whether a chain's `SwapRouter` whitelists `token`
+ * (`whitelistedTokens`), cached for 5 minutes like the other router reads.
+ * `SwapRouter.deposit` reverts `InputTokenNotWhitelisted` for any token it
+ * does not whitelist, the vault's reference asset included.
+ *
+ * @returns `false` on a chain with no SwapRouter.
+ * @internal
+ */
+async function readSwapRouterTokenWhitelisted(runner, chainId, token) {
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return false;
+    const cacheKey = `swap-router-token-whitelisted-${chainId}-${router.toLowerCase()}-${token.toLowerCase()}`;
+    const cached = await (0, cache_1.getSafeCache)(cacheKey);
+    if (cached !== null)
+        return cached;
+    const contract = (0, web3_1.createContract)({
+        address: router,
+        provider: runner,
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    if (!contract)
+        return false;
+    const whitelisted = (await contract.whitelistedTokens(token)) === true;
+    cache_1.CACHE.set(cacheKey, whitelisted, { ttl: SWAP_ROUTER_ORIGIN_INFO_TTL_MS });
+    return whitelisted;
+}
 /** Cache TTL for a chain's resolved SwapRouter token allowlist (5 minutes). */
 const SWAP_ROUTER_WHITELIST_TTL_MS = 5 * 60 * 1000;
 /**

package/lib/main.d.ts

@@ -89,10 +89,12 @@ export declare class AugustSDK extends AugustBase {
     }): Promise<number>;
     /**
      * Deposit into a vault with an explicit signer. When `depositAsset` differs
-     * from the vault's underlying asset the deposit is routed through the
-     * matching adapter (native wrapper, swap router, or permit path).
+     * from the vault's underlying asset the deposit goes through the vault's
+     * multi-asset `deposit`, permit path, or configured adapter. It never swaps
+     * (use `evm.swapRouterDeposit` for that); with `attribution.originCode` set,
+     * eligible deposits go through the SwapRouter (see `evm.getDepositRoute`).
      * @param signer - ethers Signer or Wallet that sends the transaction
-     * @param options - Vault address (`target`), depositor `wallet`, `amount`, and optional `depositAsset`, `wait`, `receiver`, `slippageBps`
+     * @param options - Vault address (`target`), depositor `wallet`, `amount`, and optional `depositAsset`, `wait`, `isDepositWithPermit`
      * @returns Deposit transaction hash
      */
     vaultDeposit(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
@@ -350,6 +352,22 @@ export declare class AugustSDK extends AugustBase {
     getSwapRouterEligibleVaults(chainId: number, options?: {
         fromBlock?: number;
     }): Promise<IAddress[]>;
+    /**
+     * Read a SwapRouter origin code's on-chain registration (registered, fee in
+     * bps, collector). Delegates to {@link AugustVaults.getOriginInfo}.
+     * @param options - `chainId` and the `bytes32` `originCode` to look up.
+     * @returns `{ registered, originFeeBps, collector }`.
+     * @throws AugustValidationError when no provider is configured for `chainId`
+     *   or `originCode` is malformed.
+     * @example
+     * ```ts
+     * const { registered } = await augustSdk.getOriginInfo({ chainId: 1, originCode });
+     * ```
+     */
+    getOriginInfo(options: {
+        chainId: number;
+        originCode: `0x${string}`;
+    }): Promise<import("./types").IOriginInfo>;
     /**
      * Get lifetime PnL for a user in a specific vault.
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.

package/lib/main.js

@@ -220,10 +220,12 @@ class AugustSDK extends core_1.AugustBase {
     }
     /**
      * Deposit into a vault with an explicit signer. When `depositAsset` differs
-     * from the vault's underlying asset the deposit is routed through the
-     * matching adapter (native wrapper, swap router, or permit path).
+     * from the vault's underlying asset the deposit goes through the vault's
+     * multi-asset `deposit`, permit path, or configured adapter. It never swaps
+     * (use `evm.swapRouterDeposit` for that); with `attribution.originCode` set,
+     * eligible deposits go through the SwapRouter (see `evm.getDepositRoute`).
      * @param signer - ethers Signer or Wallet that sends the transaction
-     * @param options - Vault address (`target`), depositor `wallet`, `amount`, and optional `depositAsset`, `wait`, `receiver`, `slippageBps`
+     * @param options - Vault address (`target`), depositor `wallet`, `amount`, and optional `depositAsset`, `wait`, `isDepositWithPermit`
      * @returns Deposit transaction hash
      */
     async vaultDeposit(signer, options) {
@@ -425,6 +427,21 @@ class AugustSDK extends core_1.AugustBase {
     async getSwapRouterEligibleVaults(chainId, options) {
         return await this.vaults.getSwapRouterEligibleVaults(chainId, options);
     }
+    /**
+     * Read a SwapRouter origin code's on-chain registration (registered, fee in
+     * bps, collector). Delegates to {@link AugustVaults.getOriginInfo}.
+     * @param options - `chainId` and the `bytes32` `originCode` to look up.
+     * @returns `{ registered, originFeeBps, collector }`.
+     * @throws AugustValidationError when no provider is configured for `chainId`
+     *   or `originCode` is malformed.
+     * @example
+     * ```ts
+     * const { registered } = await augustSdk.getOriginInfo({ chainId: 1, originCode });
+     * ```
+     */
+    async getOriginInfo(options) {
+        return await this.vaults.getOriginInfo(options);
+    }
     /**
      * Get lifetime PnL for a user in a specific vault.
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.

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

@@ -1,4 +1,4 @@
-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 IAddress, type IHistoricalTimeseriesPoint, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ISubgraphReserveDeposit, type ISubgraphTransfer, type ISubgraphUserHistoryItem, 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
@@ -444,12 +444,15 @@ export type PnlTransfer = Pick<ISubgraphTransfer, 'from' | 'to' | 'value' | 'tim
  * 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
@@ -457,7 +460,7 @@ export type PnlTransfer = Pick<ISubgraphTransfer, 'from' | 'to' | 'value' | 'tim
  * const peer = selectPeerTransfers(transfers, wallet, vault);
  * ```
  */
-export declare function selectPeerTransfers<T extends PnlTransfer>(transfers: T[], wallet: IAddress, vault: IAddress): T[];
+export declare function selectPeerTransfers<T extends PnlTransfer>(transfers: T[], wallet: IAddress, vault: IAddress, exclude?: string[]): T[];
 /** Inputs {@link transferCostBasis} prices. */
 export interface TransferCostBasisParams {
     /** Peer transfers touching `wallet` — see {@link selectPeerTransfers}. */
@@ -472,6 +475,13 @@ export interface TransferCostBasisParams {
      * read.
      */
     history: Record<string, Pick<IHistoricalTimeseriesPoint, 'asset_share_ratio'>>;
+    /**
+     * Report sent shares even when none were received. Defaults to `false`, which
+     * zeroes them so a zero-deposit wallet's history guard still decides; pass
+     * `true` when the caller applies that rule itself, as {@link pnlCostBasis}
+     * does.
+     */
+    countSentWithoutReceipt?: boolean;
 }
 /** Asset amounts that peer transfers moved into and out of a position. */
 export interface TransferCostBasis {
@@ -491,9 +501,11 @@ export interface TransferCostBasis {
  * 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.
@@ -514,7 +526,242 @@ export interface TransferCostBasis {
  * });
  * ```
  */
-export declare function transferCostBasis({ transfers, wallet, vault, history, }: TransferCostBasisParams): TransferCostBasis;
+export declare function transferCostBasis({ transfers, wallet, vault, history, countSentWithoutReceipt, }: TransferCostBasisParams): TransferCostBasis;
+/** Inputs {@link historyCoversMints} compares. */
+export interface HistoryCoversMintsParams {
+    /** Every share-token transfer touching `wallet`, mints included. */
+    transfers: Pick<ISubgraphTransfer, 'from' | 'to' | 'transactionHash_'>[];
+    /** The wallet whose history is being checked. */
+    wallet: IAddress;
+    /** Transaction hashes of the wallet's indexed deposits. */
+    depositTransactionHashes: string[];
+}
+/**
+ * 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_),
+ * });
+ * ```
+ */
+export declare function historyCoversMints({ transfers, wallet, depositTransactionHashes, }: HistoryCoversMintsParams): boolean;
+/** Inputs {@link selectReserveDeposits} matches. */
+export interface SelectReserveDepositsParams {
+    /** The wallet's `ReserveDeposit` events (see `getSubgraphUserReserveDeposits`). */
+    reserveDeposits: ISubgraphReserveDeposit[];
+    /** Every share-token transfer touching `wallet`, mints included. */
+    transfers: Pick<ISubgraphTransfer, 'from' | 'to' | 'transactionHash_'>[];
+    /** The wallet whose history is being completed. */
+    wallet: IAddress;
+    /** Transaction hashes of the wallet's indexed deposits. */
+    depositTransactionHashes: string[];
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+export declare function selectReserveDeposits({ reserveDeposits, transfers, wallet, depositTransactionHashes, }: SelectReserveDepositsParams): ISubgraphReserveDeposit[];
+/** Inputs {@link countWithdrawalRequestsOnce} reads. */
+export interface CountWithdrawalRequestsOnceParams {
+    /** The wallet's user history (see `getSubgraphUserHistory`). */
+    history: ISubgraphUserHistoryItem[];
+    /** Every share-token transfer touching `wallet`. */
+    transfers: Pick<ISubgraphTransfer, 'from' | 'to' | 'transactionHash_'>[];
+    /** The wallet whose history is being read. */
+    wallet: IAddress;
+    /** The vault contract address. */
+    vault: IAddress;
+}
+/**
+ * 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 });
+ * ```
+ */
+export declare function countWithdrawalRequestsOnce({ history, transfers, wallet, vault, }: CountWithdrawalRequestsOnceParams): ISubgraphUserHistoryItem[];
+/** Inputs {@link settleV2Redemptions} values. */
+export interface SettleV2RedemptionsParams {
+    /** The wallet's user history (see `getSubgraphUserHistory`). */
+    history: ISubgraphUserHistoryItem[];
+    /** The vault's `lagDuration()`, in seconds. */
+    lagDuration: number;
+    /**
+     * The vault's daily history from `fetchVaultHistoricalTimeseries`, keyed by
+     * UTC date (`YYYY-MM-DD`). Only `asset_share_ratio` (assets per share) is
+     * read.
+     */
+    ratios: Record<string, Pick<IHistoricalTimeseriesPoint, 'asset_share_ratio'>>;
+    /** The current time, in unix seconds. */
+    now: number;
+}
+/** What a wallet's Tokenized Vault V2 redemption requests are worth. */
+export interface V2RedemptionValue {
+    /** Assets paid, or due, for requests past their claim date; raw at vault decimals. */
+    settledAssetsRaw: bigint;
+    /** Shares to value at the current share price, raw. */
+    pendingShares: bigint;
+}
+/**
+ * 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),
+ * });
+ * ```
+ */
+export declare function settleV2Redemptions({ history, lagDuration, ratios, now, }: SettleV2RedemptionsParams): V2RedemptionValue;
+/** Inputs {@link pnlCostBasis} folds together. */
+export interface PnlCostBasisParams {
+    /** Indexed deposits at face value, raw at the vault's decimals. */
+    depositedRaw: bigint;
+    /** Withdrawals already in asset terms, raw at the vault's decimals. */
+    withdrawnAssetsRaw: bigint;
+    /** Whether history indexed any deposit, LayerZero deposits included. */
+    hasDeposits: boolean;
+    /** Whether the history accounts for every share mint (see {@link historyCoversMints}). */
+    mintsMatchHistory: boolean;
+    /**
+     * Peer transfers priced by {@link transferCostBasis} with
+     * `countSentWithoutReceipt: true`.
+     */
+    transfers: TransferCostBasis;
+}
+/** The cost basis {@link getVaultUserLifetimePnl} computes PnL against. */
+export interface PnlCostBasis {
+    /** Indexed deposits plus shares received by transfer, raw at vault decimals. */
+    depositedRaw: bigint;
+    /** Asset-terms withdrawals plus shares sent by transfer, raw at vault decimals. */
+    withdrawnAssetsRaw: bigint;
+    /** The part of `depositedRaw` that came from shares received by transfer. */
+    receivedByTransferRaw: bigint;
+}
+/**
+ * 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,
+ *   }),
+ * });
+ * ```
+ */
+export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDeposits, mintsMatchHistory, transfers, }: PnlCostBasisParams): PnlCostBasis;
 /**
  * Calculate lifetime PnL for a user in a specific vault.
  *
@@ -536,13 +783,39 @@ export declare function transferCostBasis({ transfers, wallet, vault, history, }
  * 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