@augustdigital/sdk 9.5.0 → 9.6.0

package/lib/main.js

@@ -430,6 +430,11 @@ class AugustSDK extends core_1.AugustBase {
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.
      * @param props - Vault address, wallet address, and optional chain ID
      * @returns Lifetime PnL data including realized and unrealized PnL in both native token and USD
+     * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+     *   live position has no indexed deposits or withdrawals.
+     * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+     *   vault's underlying asset has no USD price — the USD fields are never
+     *   computed from a stand-in price.
      */
     async getVaultUserLifetimePnl(props) {
         return await this.vaults.getVaultUserLifetimePnl(props);

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

@@ -366,6 +366,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
@@ -408,10 +455,18 @@ 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.
+ *
  * @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.
+ * @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,6 +54,7 @@ exports.registerUserForPoints = registerUserForPoints;
 exports.fetchPointsLeaderboard = fetchPointsLeaderboard;
 exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
 exports.assertPnlHistoryConsistent = assertPnlHistoryConsistent;
+exports.assertPnlTokenPrice = assertPnlTokenPrice;
 exports.sumDepositsAtFaceValue = sumDepositsAtFaceValue;
 exports.getVaultUserLifetimePnl = getVaultUserLifetimePnl;
 exports.getVaultPnl = getVaultPnl;
@@ -2295,6 +2296,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
@@ -2352,10 +2386,18 @@ 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.
+ *
  * @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.
+ * @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 {
@@ -2663,25 +2705,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 +2748,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,10 @@ 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 or withdrawals.
+     * @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,10 @@ 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 or withdrawals.
+     * @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}.

package/lib/modules/vaults/write.actions.js

@@ -19,6 +19,7 @@ exports.rwaRedeemAsset = rwaRedeemAsset;
 exports.swapAndDeposit = swapAndDeposit;
 exports.depositViaSwapRouter = depositViaSwapRouter;
 exports.depositNativeViaSwapRouter = depositNativeViaSwapRouter;
+exports.isNativeSwapRouterDepositSupported = isNativeSwapRouterDepositSupported;
 exports.swapRouterDeposit = swapRouterDeposit;
 const ethers_1 = require("ethers");
 const abis_1 = require("../../abis");
@@ -1407,7 +1408,7 @@ async function dispatchViaSwapRouter(args) {
         const wrappedNative = core_1.SWAP_ROUTER_WRAPPED_NATIVE[args.chainId];
         if (!wrappedNative ||
             args.underlyingAsset.toLowerCase() !== wrappedNative.toLowerCase()) {
-            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultDeposit (SwapRouter): native deposit is only supported when the vault's reference asset is the chain's wrapped-native token. Vault ${args.target} underlying ${args.underlyingAsset} is not. Wrap to ${wrappedNative ?? 'WETH'} first and call again with depositAsset = the wrapped token.`, {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `vaultDeposit (SwapRouter): native deposit is only supported when the vault's reference asset is the chain's wrapped-native token. Vault ${args.target} underlying ${args.underlyingAsset} is not. Wrap to ${wrappedNative ?? 'WETH'} first and call again with depositAsset = the wrapped token. Check isNativeSwapRouterDepositSupported(chainId, vault, options) before offering this path to avoid hitting this error.`, {
                 context: {
                     vault: args.target,
                     underlying: args.underlyingAsset,
@@ -1694,6 +1695,14 @@ async function depositViaSwapRouter(signer, options) {
  * 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`.
@@ -1727,6 +1736,78 @@ async function depositNativeViaSwapRouter(signer, options) {
     core_1.Logger.log.info('depositNativeViaSwapRouter:tx_hash', hash);
     return hash;
 }
+/**
+ * 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
+ * ```
+ */
+async function isNativeSwapRouterDepositSupported(chainId, vault, options) {
+    const wrappedNative = core_1.SWAP_ROUTER_WRAPPED_NATIVE[chainId];
+    const routerAddress = (0, core_1.getSwapRouterAddress)(chainId);
+    if (!wrappedNative || !routerAddress)
+        return false;
+    try {
+        const provider = (0, core_1.createProvider)(options.rpcUrl, chainId);
+        const vaultContract = (0, core_1.createContract)({
+            address: vault,
+            provider,
+            abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+        });
+        const routerContract = (0, core_1.createContract)({
+            address: routerAddress,
+            provider,
+            abi: abis_1.ABI_SWAP_ROUTER,
+        });
+        const [asset, info] = await Promise.all([
+            vaultContract.asset(),
+            routerContract.vaultInfo(vault),
+        ]);
+        const wrapped = wrappedNative.toLowerCase();
+        return (asset.toLowerCase() === wrapped &&
+            info?.referenceAsset?.toLowerCase() === wrapped);
+    }
+    catch (error) {
+        core_1.Logger.log.warn('isNativeSwapRouterDepositSupported', 'vault or router read failed — treating as unsupported', { vault, chainId, error });
+        return false;
+    }
+}
 /**
  * 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
@@ -1746,7 +1827,10 @@ async function depositNativeViaSwapRouter(signer, options) {
  *  - 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}.