@augustdigital/sdk 9.9.1 → 9.11.0

package/lib/core/errors/index.d.ts

@@ -15,7 +15,7 @@
  * ```
  */
 /** Stable error codes attached to SDK errors. */
-export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'TRANSACTION_UNCONFIRMED' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
 /** Options accepted by every SDK error constructor. */
 export interface AugustErrorOptions {
     /** Original error preserved for stack-trace chaining. */
@@ -145,5 +145,33 @@ export declare class AugustPriceUnavailableError extends AugustSDKError {
      */
     constructor(message: string, options?: AugustErrorOptions);
 }
+/**
+ * A transaction was sent but its outcome could not be established
+ * (`TRANSACTION_UNCONFIRMED`). It may have landed: check {@link signature}
+ * before resubmitting, or a deposit or redeem can execute twice.
+ * `context.reason` says what was seen (e.g. `expired_not_found`: the blockhash
+ * expired and no lookup found it, so it very likely never landed).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.solana.vaultDeposit(programId, idl, wallet, amount, undefined, vault);
+ * } catch (err) {
+ *   if (err instanceof AugustTransactionError) showPending(err.signature);
+ *   else throw err;
+ * }
+ * ```
+ */
+export declare class AugustTransactionError extends AugustSDKError {
+    /** Signature of the transaction that was sent. */
+    readonly signature: string;
+    /**
+     * @param message - Human-readable description, naming the signature.
+     * @param signature - Signature of the transaction that was sent.
+     * @param options - Standard SDK error options.
+     */
+    constructor(message: string, signature: string, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AugustPriceUnavailableError = exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
+exports.AugustTransactionError = exports.AugustPriceUnavailableError = exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
 exports.isAugustSDKError = isAugustSDKError;
 /** Base class for all SDK errors. */
 class AugustSDKError extends Error {
@@ -212,6 +212,41 @@ class AugustPriceUnavailableError extends AugustSDKError {
     }
 }
 exports.AugustPriceUnavailableError = AugustPriceUnavailableError;
+/**
+ * A transaction was sent but its outcome could not be established
+ * (`TRANSACTION_UNCONFIRMED`). It may have landed: check {@link signature}
+ * before resubmitting, or a deposit or redeem can execute twice.
+ * `context.reason` says what was seen (e.g. `expired_not_found`: the blockhash
+ * expired and no lookup found it, so it very likely never landed).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.solana.vaultDeposit(programId, idl, wallet, amount, undefined, vault);
+ * } catch (err) {
+ *   if (err instanceof AugustTransactionError) showPending(err.signature);
+ *   else throw err;
+ * }
+ * ```
+ */
+class AugustTransactionError extends AugustSDKError {
+    /** Signature of the transaction that was sent. */
+    signature;
+    /**
+     * @param message - Human-readable description, naming the signature.
+     * @param signature - Signature of the transaction that was sent.
+     * @param options - Standard SDK error options.
+     */
+    constructor(message, signature, options) {
+        super('TRANSACTION_UNCONFIRMED', message, options);
+        this.name = 'AugustTransactionError';
+        this.signature = signature;
+    }
+    toJSON() {
+        return { ...super.toJSON(), signature: this.signature };
+    }
+}
+exports.AugustTransactionError = AugustTransactionError;
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 function isAugustSDKError(err) {
     return (err instanceof AugustSDKError ||

package/lib/core/helpers/concurrency.d.ts

@@ -35,3 +35,17 @@
  * @internal
  */
 export declare function mapWithConcurrency<TIn, TOut>(items: readonly TIn[], limit: number, task: (item: TIn, index: number) => Promise<TOut>): Promise<TOut[]>;
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ *
+ * @param promise - The call to bound. It keeps running after a timeout; only
+ *   the wait is abandoned.
+ * @param ms - Timeout in milliseconds. Values below 0 are treated as 0.
+ * @param label - Names the call in the rejection message.
+ * @returns What `promise` resolves to.
+ * @throws `Error("<label> timed out after <ms>ms")` on timeout, or whatever
+ *   `promise` rejects with.
+ * @internal
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;

package/lib/core/helpers/concurrency.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapWithConcurrency = mapWithConcurrency;
+exports.withTimeout = withTimeout;
 /**
  * Map over `items` running at most `limit` tasks at a time.
  *
@@ -55,4 +56,24 @@ async function mapWithConcurrency(items, limit, task) {
     await Promise.all(Array.from({ length: width }, worker));
     return results;
 }
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ *
+ * @param promise - The call to bound. It keeps running after a timeout; only
+ *   the wait is abandoned.
+ * @param ms - Timeout in milliseconds. Values below 0 are treated as 0.
+ * @param label - Names the call in the rejection message.
+ * @returns What `promise` resolves to.
+ * @throws `Error("<label> timed out after <ms>ms")` on timeout, or whatever
+ *   `promise` rejects with.
+ * @internal
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), Math.max(0, ms));
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
 //# sourceMappingURL=concurrency.js.map

package/lib/core/helpers/swap-router.d.ts

@@ -169,6 +169,23 @@ export declare function readSwapRouterVaultInfo(runner: IContractRunner, chainId
  * @internal
  */
 export declare function readSwapRouterTokenWhitelisted(runner: IContractRunner, chainId: number, token: IAddress): Promise<boolean>;
+/**
+ * Read whether a chain's `SwapRouter` is paused (`isPaused()`), cached for 15
+ * seconds. Every router entry point (`deposit`, `swapAndDeposit`,
+ * `depositNativeToken`) reverts with `ContractIsPaused` while the router is
+ * paused, so callers check this before routing a deposit or sending an
+ * approval to the router.
+ *
+ * @param runner - Contract runner (provider or signer) used for the read.
+ * @param chainId - EVM chain ID.
+ * @returns `true` while the router is paused; `false` when it is not, or on a
+ *   chain with no SwapRouter (no RPC).
+ * @throws When the `isPaused()` read fails. Callers wrap it in
+ *   {@link AugustSDKError}.
+ * @worstCaseRpcCalls 1 — one `isPaused()` call; none on a cache hit.
+ * @internal
+ */
+export declare function readSwapRouterPaused(runner: IContractRunner, chainId: number): Promise<boolean>;
 /**
  * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
  * chain — the any-token set a UI can offer as swap-and-deposit inputs.

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

@@ -10,6 +10,7 @@ exports.getOriginInfo = getOriginInfo;
 exports.readOriginInfo = readOriginInfo;
 exports.readSwapRouterVaultInfo = readSwapRouterVaultInfo;
 exports.readSwapRouterTokenWhitelisted = readSwapRouterTokenWhitelisted;
+exports.readSwapRouterPaused = readSwapRouterPaused;
 exports.getSwapRouterWhitelistedTokens = getSwapRouterWhitelistedTokens;
 exports.getSwapRouterEligibleVaults = getSwapRouterEligibleVaults;
 const ethers_1 = require("ethers");
@@ -332,6 +333,49 @@ async function readSwapRouterTokenWhitelisted(runner, chainId, token) {
     cache_1.CACHE.set(cacheKey, whitelisted, { ttl: SWAP_ROUTER_ORIGIN_INFO_TTL_MS });
     return whitelisted;
 }
+/**
+ * Cache TTL for a SwapRouter's pause state (15 seconds). Far shorter than the
+ * 5-minute TTL of the other router reads: the owner pauses the router to stop
+ * deposits during an incident, so a pause must reach the deposit-route
+ * resolver within seconds. Long enough that the resolver and the router write
+ * it hands off to share one `isPaused()` read.
+ */
+const SWAP_ROUTER_PAUSED_TTL_MS = 15 * 1000;
+/**
+ * Read whether a chain's `SwapRouter` is paused (`isPaused()`), cached for 15
+ * seconds. Every router entry point (`deposit`, `swapAndDeposit`,
+ * `depositNativeToken`) reverts with `ContractIsPaused` while the router is
+ * paused, so callers check this before routing a deposit or sending an
+ * approval to the router.
+ *
+ * @param runner - Contract runner (provider or signer) used for the read.
+ * @param chainId - EVM chain ID.
+ * @returns `true` while the router is paused; `false` when it is not, or on a
+ *   chain with no SwapRouter (no RPC).
+ * @throws When the `isPaused()` read fails. Callers wrap it in
+ *   {@link AugustSDKError}.
+ * @worstCaseRpcCalls 1 — one `isPaused()` call; none on a cache hit.
+ * @internal
+ */
+async function readSwapRouterPaused(runner, chainId) {
+    const router = getSwapRouterAddress(chainId);
+    if (!router)
+        return false;
+    const cacheKey = `swap-router-paused-${chainId}-${router.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 paused = (await contract.isPaused()) === true;
+    cache_1.CACHE.set(cacheKey, paused, { ttl: SWAP_ROUTER_PAUSED_TTL_MS });
+    return paused;
+}
 /** Cache TTL for a chain's resolved SwapRouter token allowlist (5 minutes). */
 const SWAP_ROUTER_WHITELIST_TTL_MS = 5 * 60 * 1000;
 /**

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

@@ -311,6 +311,16 @@ export interface PnlHistoryConsistencyParams {
      * (subgraph deposits or LayerZero cross-chain deposits).
      */
     hasDeposits: boolean;
+    /**
+     * Whether the indexed deposits explain every share mint to the wallet (see
+     * {@link historyCoversMints}). Defaults to `true`.
+     */
+    mintsMatchHistory?: boolean;
+    /**
+     * Shares received by peer transfer, priced in raw base units (asset
+     * decimals) by {@link transferCostBasis}. Defaults to zero.
+     */
+    receivedByTransferRaw?: bigint;
     /** Total withdrawn, in raw base units (asset decimals). */
     totalWithdrawnRaw: bigint;
     /** Current on-chain position value, in raw base units (asset decimals). */
@@ -326,9 +336,14 @@ export interface PnlHistoryConsistencyParams {
  * position as pure profit — a plausible-looking but wrong number.
  *
  * This guard rejects exactly that state: a non-zero position with no recorded
- * deposits *and* no recorded withdrawals. Any of the following is treated as
- * consistent and passes:
+ * deposits, no shares received by transfer *and* no recorded withdrawals. It
+ * also rejects a non-zero position with no recorded deposits when a share mint
+ * to the wallet has no matching deposit (`mintsMatchHistory: false`): the mint
+ * proves a deposit the history failed to return, so neither a peer transfer
+ * nor a withdrawal makes the cost basis complete. Otherwise, any of the
+ * following is treated as consistent and passes:
  * - deposits are present (the normal, computable case);
+ * - shares were received by transfer and priced (see {@link transferCostBasis});
  * - withdrawals are present (a fully-exited-then-re-entered position is still
  *   computable — the withdrawal records prove history loaded);
  * - the current position is zero (the wallet never interacted or fully exited,
@@ -338,15 +353,17 @@ export interface PnlHistoryConsistencyParams {
  * path with no added latency.
  *
  * 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.
+ * reach this guard as `receivedByTransferRaw`: {@link getVaultUserLifetimePnl}
+ * prices them with {@link transferCostBasis} first. The guard still throws for
+ * such a wallet when its transfers cannot be read or priced, or when a share
+ * mint to it has no indexed deposit.
  *
  * @param params - See {@link PnlHistoryConsistencyParams}.
  * @returns `void` when the history is consistent.
  * @throws {@link AugustHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
- *   and `context: { vault, wallet }` when a non-zero position has neither
- *   deposits nor withdrawals recorded. The message carries the
+ *   and `context: { vault, wallet }` when a non-zero position has no deposits
+ *   recorded and either a share mint without a matching deposit or neither
+ *   received shares nor withdrawals. The message carries the
  *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
  *   other errors leaving the getter.
  * @example
@@ -355,12 +372,14 @@ export interface PnlHistoryConsistencyParams {
  *   vault,
  *   wallet,
  *   hasDeposits: depositsByAsset.size > 0,
+ *   mintsMatchHistory,
+ *   receivedByTransferRaw: costBasis.receivedByTransferRaw,
  *   totalWithdrawnRaw,
  *   currentPositionRaw: currentPositionValue.raw,
  * });
  * ```
  */
-export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
+export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, mintsMatchHistory, receivedByTransferRaw, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
 /** Inputs the lifetime-PnL price guard inspects. */
 export interface PnlTokenPriceParams {
     /** Vault contract address, used for the error message and context. */
@@ -728,7 +747,9 @@ export interface PnlCostBasis {
  *
  * 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
+ * returned before transfers counted for depositors. A wallet with no deposit
+ * still gets a basis here when its history misses a mint, but
+ * {@link assertPnlHistoryConsistent} rejects it. On a LayerZero OVault the
  * caller leaves the hub composer and share OFT out of the transfers (see
  * {@link selectPeerTransfers}): the composer's deliveries are already counted
  * as LayerZero deposits, and shares bridged to a spoke chain still count in the
@@ -789,16 +810,18 @@ export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDepo
  * 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.
+ * deposited is not credited with the received shares as profit. On LayerZero
+ * OVaults, transfers from or to the hub composer and share OFT do not count,
+ * because the composer delivers cross-chain deposits by transfer and those
+ * are already counted as LayerZero deposits.
  *
  * Gaps in the indexed history: a share mint with no `Deposit` event counts as
  * a deposit of the assets in its `ReserveDeposit` event
  * ({@link selectReserveDeposits}; High Growth ETH emits it for Kelp gain-adapter
  * deposits), and a withdrawal request the vault logged twice counts once
  * ({@link countWithdrawalRequestsOnce}). Transfers fold in for a depositor only
- * once every mint is explained.
+ * once every mint is explained. A wallet with no indexed deposit and a mint
+ * that no deposit explains throws `HISTORY_UNAVAILABLE`.
  *
  * Tokenized Vault V2 redemptions carry only shares, so a settled one counts at
  * the assets the vault paid, or at the share ratio on its claim date when the
@@ -813,9 +836,8 @@ export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDepo
  * 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.
+ * so the latest earlier day still prices it. The transfer query runs for
+ * every vault, in parallel with the history read.
  *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
@@ -823,7 +845,8 @@ export declare function pnlCostBasis({ depositedRaw, withdrawnAssetsRaw, hasDepo
  * @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.
+ *   transfers, or has no indexed deposit while a share mint to the wallet has
+ *   no matching deposit.
  * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
  *   underlying asset has no USD price, or `asset()` cannot be read.
  */

package/lib/modules/vaults/getters.js

@@ -2273,9 +2273,14 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  * position as pure profit — a plausible-looking but wrong number.
  *
  * This guard rejects exactly that state: a non-zero position with no recorded
- * deposits *and* no recorded withdrawals. Any of the following is treated as
- * consistent and passes:
+ * deposits, no shares received by transfer *and* no recorded withdrawals. It
+ * also rejects a non-zero position with no recorded deposits when a share mint
+ * to the wallet has no matching deposit (`mintsMatchHistory: false`): the mint
+ * proves a deposit the history failed to return, so neither a peer transfer
+ * nor a withdrawal makes the cost basis complete. Otherwise, any of the
+ * following is treated as consistent and passes:
  * - deposits are present (the normal, computable case);
+ * - shares were received by transfer and priced (see {@link transferCostBasis});
  * - withdrawals are present (a fully-exited-then-re-entered position is still
  *   computable — the withdrawal records prove history loaded);
  * - the current position is zero (the wallet never interacted or fully exited,
@@ -2285,15 +2290,17 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  * path with no added latency.
  *
  * 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.
+ * reach this guard as `receivedByTransferRaw`: {@link getVaultUserLifetimePnl}
+ * prices them with {@link transferCostBasis} first. The guard still throws for
+ * such a wallet when its transfers cannot be read or priced, or when a share
+ * mint to it has no indexed deposit.
  *
  * @param params - See {@link PnlHistoryConsistencyParams}.
  * @returns `void` when the history is consistent.
  * @throws {@link AugustHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
- *   and `context: { vault, wallet }` when a non-zero position has neither
- *   deposits nor withdrawals recorded. The message carries the
+ *   and `context: { vault, wallet }` when a non-zero position has no deposits
+ *   recorded and either a share mint without a matching deposit or neither
+ *   received shares nor withdrawals. The message carries the
  *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
  *   other errors leaving the getter.
  * @example
@@ -2302,16 +2309,23 @@ async function getYieldLastRealizedOn({ vault, options, }) {
  *   vault,
  *   wallet,
  *   hasDeposits: depositsByAsset.size > 0,
+ *   mintsMatchHistory,
+ *   receivedByTransferRaw: costBasis.receivedByTransferRaw,
  *   totalWithdrawnRaw,
  *   currentPositionRaw: currentPositionValue.raw,
  * });
  * ```
  */
-function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }) {
-    const positionExists = currentPositionRaw > BigInt(0);
-    const noHistory = !hasDeposits && totalWithdrawnRaw === BigInt(0);
-    if (positionExists && noHistory) {
-        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 } });
+function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, mintsMatchHistory = true, receivedByTransferRaw = BigInt(0), totalWithdrawnRaw, currentPositionRaw, }) {
+    if (currentPositionRaw <= BigInt(0) || hasDeposits)
+        return;
+    const missingDeposit = !mintsMatchHistory;
+    const noHistory = receivedByTransferRaw === BigInt(0) && totalWithdrawnRaw === BigInt(0);
+    if (missingDeposit || noHistory) {
+        const reason = missingDeposit
+            ? 'a share mint has no indexed deposit'
+            : 'no deposits or withdrawals were indexed';
+        throw new errors_1.AugustHistoryUnavailableError(`#getVaultUserLifetimePnl::${vault}::${wallet}:transaction history unavailable — a live position exists but ${reason}, so lifetime PnL cannot be computed without over-reporting the entire position as profit`, { context: { vault, wallet } });
     }
 }
 /**
@@ -2713,7 +2727,9 @@ function settleV2Redemptions({ history, lagDuration, ratios, now, }) {
  *
  * 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
+ * returned before transfers counted for depositors. A wallet with no deposit
+ * still gets a basis here when its history misses a mint, but
+ * {@link assertPnlHistoryConsistent} rejects it. On a LayerZero OVault the
  * caller leaves the hub composer and share OFT out of the transfers (see
  * {@link selectPeerTransfers}): the composer's deliveries are already counted
  * as LayerZero deposits, and shares bridged to a spoke chain still count in the
@@ -2855,16 +2871,18 @@ async function readV2Redemptions(provider, vault, history, headers) {
  * 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.
+ * deposited is not credited with the received shares as profit. On LayerZero
+ * OVaults, transfers from or to the hub composer and share OFT do not count,
+ * because the composer delivers cross-chain deposits by transfer and those
+ * are already counted as LayerZero deposits.
  *
  * Gaps in the indexed history: a share mint with no `Deposit` event counts as
  * a deposit of the assets in its `ReserveDeposit` event
  * ({@link selectReserveDeposits}; High Growth ETH emits it for Kelp gain-adapter
  * deposits), and a withdrawal request the vault logged twice counts once
  * ({@link countWithdrawalRequestsOnce}). Transfers fold in for a depositor only
- * once every mint is explained.
+ * once every mint is explained. A wallet with no indexed deposit and a mint
+ * that no deposit explains throws `HISTORY_UNAVAILABLE`.
  *
  * Tokenized Vault V2 redemptions carry only shares, so a settled one counts at
  * the assets the vault paid, or at the share ratio on its claim date when the
@@ -2879,9 +2897,8 @@ async function readV2Redemptions(provider, vault, history, headers) {
  * 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.
+ * so the latest earlier day still prices it. The transfer query runs for
+ * every vault, in parallel with the history read.
  *
  * @param vault - Vault contract address
  * @param wallet - User wallet address
@@ -2889,7 +2906,8 @@ async function readV2Redemptions(provider, vault, history, headers) {
  * @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.
+ *   transfers, or has no indexed deposit while a share mint to the wallet has
+ *   no matching deposit.
  * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
  *   underlying asset has no USD price, or `asset()` cannot be read.
  */
@@ -3259,7 +3277,9 @@ async function getVaultUserLifetimePnl({ vault, wallet, options, }) {
         assertPnlHistoryConsistent({
             vault,
             wallet,
-            hasDeposits: hasDeposits || costBasis.receivedByTransferRaw > BigInt(0),
+            hasDeposits,
+            mintsMatchHistory,
+            receivedByTransferRaw: costBasis.receivedByTransferRaw,
             totalWithdrawnRaw: costBasis.withdrawnAssetsRaw,
             currentPositionRaw: BigInt(currentPositionValue.raw),
         });

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

@@ -172,8 +172,11 @@ export type ApproveResult =
 /**
  * Why {@link getDepositRoute} kept a deposit on the vault's native path.
  * `no-origin-code` is what every SDK without `attribution.originCode` gets.
+ * `router-paused` means the SwapRouter's owner paused it: the deposit goes
+ * straight to the vault, even under `attribution.strictOrigin`, until the
+ * router is unpaused.
  */
-export type DepositRouteReason = 'no-origin-code' | 'no-router' | 'chain-not-supported' | 'permit' | 'native-token' | 'adapter' | 'vault-not-registered' | 'asset-not-accepted' | 'router-token-not-whitelisted' | 'origin-not-registered';
+export type DepositRouteReason = 'no-origin-code' | 'no-router' | 'chain-not-supported' | 'permit' | 'native-token' | 'adapter' | 'vault-not-registered' | 'asset-not-accepted' | 'router-token-not-whitelisted' | 'router-paused' | 'origin-not-registered';
 /** A deposit's route — the SwapRouter or the vault's native path — and the address to approve. */
 export type IDepositRoute = {
     /**
@@ -199,23 +202,25 @@ export type IGetDepositRouteOptions = Pick<IContractWriteOptions, 'target' | 'de
  * Ethereum mainnet ({@link ORIGIN_ATTRIBUTION_CHAINS}) and has a SwapRouter,
  * the vault is registered on it, the vault accepts the asset directly (its
  * reference asset, or a Tokenized Vault V2 whitelisted asset — deposited
- * as-is, never swapped), the router whitelists the asset, the deposit is not a
- * permit, native-token or adapter deposit, and the code is registered.
- * Otherwise it is `native` with a `reason`.
+ * as-is, never swapped), the router whitelists the asset, the router is not
+ * paused, the deposit is not a permit, native-token or adapter deposit, and
+ * the code is registered. Otherwise it is `native` with a `reason`. A paused
+ * router gives `router-paused` even under `attribution.strictOrigin`.
  *
  * @param signer - ethers `Signer` / `Wallet` used for the reads.
  * @param options - {@link IGetDepositRouteOptions}; `depositAsset` defaults
  *   to the vault's underlying.
  * @returns {@link IDepositRoute}.
  * @throws AugustValidationError on an invalid `target`, or an unregistered
- *   code under `attribution.strictOrigin`.
+ *   code under `attribution.strictOrigin` while the router is not paused.
  * @throws AugustSDKError when a backend, vault or router read fails.
- * @worstCaseRpcCalls 7 — the backend vault row, `asset()`, the router's
+ * @worstCaseRpcCalls 8 — the backend vault row, `asset()`, the router's
  *   `vaultInfo`, the vault's `assetsWhitelistAddress()` and
  *   `getWhitelistedAssets()` (Tokenized Vault V2 non-reference asset only),
- *   the router's `whitelistedTokens(asset)`, and the router's `origins`. The
- *   router reads and `getWhitelistedAssets()` are cached for 5 minutes. No
- *   router read without a code or off Ethereum mainnet.
+ *   the router's `whitelistedTokens(asset)`, `isPaused()` and `origins`. The
+ *   router reads and `getWhitelistedAssets()` are cached for 5 minutes, except
+ *   `isPaused()` (15 seconds). No router read without a code or off Ethereum
+ *   mainnet.
  * @example
  * ```ts
  * const route = await augustSdk.evm.getDepositRoute({ target: vault, depositAsset: usdt });
@@ -555,7 +560,8 @@ export declare function rwaRedeemAsset(signer: Signer | Wallet, options: IRwaRed
  * addresses, empty/oversized swap arrays, or an origin code not registered on
  * the router (a per-call code, or the instance code under
  * `attribution.strictOrigin`), before any approval.
- * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ * @throws {@link AugustSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
  *
  * @example
  * ```ts
@@ -598,7 +604,8 @@ export declare function swapAndDeposit(signer: Signer | Wallet, options: ISwapAn
  * per-call code, or the instance code under `attribution.strictOrigin`),
  * before any approval; with code `ACCOUNT_NOT_FUNDED` when the account cannot
  * cover gas.
- * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ * @throws {@link AugustSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
  */
 export declare function depositViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterDirectDepositOptions): Promise<string>;
 /**
@@ -626,7 +633,8 @@ export declare function depositViaSwapRouter(signer: Signer | Wallet, options: I
  * per-call code, or the instance code under `attribution.strictOrigin`),
  * before any approval; with code `ACCOUNT_NOT_FUNDED` when the account cannot
  * cover gas.
- * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ * @throws {@link AugustSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
  */
 export declare function depositNativeViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterNativeDepositOptions): Promise<string>;
 /**
@@ -724,14 +732,16 @@ export declare function isNativeSwapRouterDepositSupported(chainId: number, vaul
  *   not registered on the router (a per-call code, or the instance code under
  *   `attribution.strictOrigin`), before any approval; with code
  *   `ACCOUNT_NOT_FUNDED` when the account cannot cover gas.
- * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
- * @worstCaseRpcCalls 10 on the swap path into a Tokenized Vault V2 —
+ * @throws {@link AugustSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
+ * @worstCaseRpcCalls 11 on the swap path into a Tokenized Vault V2 —
  *   tokenized-vault metadata, reference asset + decimals, deposit-token
  *   decimals, the router's `vaultInfo` and `whitelistedTokens`, the vault's
  *   `assetsWhitelistAddress()` and `getWhitelistedAssets()`, the quote, the
- *   origin code's `origins` (none for the zero sentinel), and the allowance
- *   read. The router reads and `getWhitelistedAssets()` are cached for 5
- *   minutes.
+ *   router's `isPaused()`, the origin code's `origins` (none for the zero
+ *   sentinel), and the allowance read. The router reads and
+ *   `getWhitelistedAssets()` are cached for 5 minutes, except `isPaused()`
+ *   (15 seconds).
  * @example
  * ```ts
  * // USDT deposited into a USDC-reference vault → swapped to USDC en route.