@owney/sdk 0.7.28-beta.3 → 0.7.28-beta.5

package/dist/index.cjs

@@ -2884,6 +2884,33 @@ function swapChain(chainId) {
   return CHAINS[chainId];
 }
 
+// src/lib/swap/swap.gas-check.ts
+var CLASSIC_SWAP_GAS = 300000n;
+var APPROVE_GAS2 = 60000n;
+var isNative = (address) => address.toLowerCase().startsWith("0xeeee");
+async function swapGasShortfall(deps, quote) {
+  if (quote.rail !== "classic" || isNative(quote.src.address)) return null;
+  const gas = CLASSIC_SWAP_GAS + APPROVE_GAS2;
+  const [balance, gasPrice] = await Promise.all([
+    deps.readNativeBalance(),
+    deps.getMaxFeePerGas()
+  ]);
+  const required = gas * gasPrice;
+  return balance < required ? { chainId: quote.src.chainId, balance, required } : null;
+}
+function swapGasError(shortfall, nativeSymbol) {
+  return new OwneyError(
+    "SWAP_INSUFFICIENT_GAS",
+    `This swap needs a little ${nativeSymbol} for network fees, and your wallet has too little. Add some ${nativeSymbol}, or choose a different asset to receive.`,
+    {
+      chainId: shortfall.chainId,
+      symbol: nativeSymbol,
+      balance: shortfall.balance.toString(),
+      required: shortfall.required.toString()
+    }
+  );
+}
+
 // src/lib/swap/swap.arrival.ts
 var DEFAULT_TIMEOUT_MS = 18e4;
 var DEFAULT_POLL_MS = 4e3;
@@ -3074,6 +3101,10 @@ var DEFAULT_POLL_MS2 = 5e3;
 var MAX_BACKOFF_MS = 3e4;
 var backoffFor = (failures, base4) => Math.min(base4 * 2 ** Math.min(failures, 5), MAX_BACKOFF_MS);
 var DEFAULT_TIMEOUT_MS2 = 15 * 60 * 1e3;
+var NOT_FOUND_GRACE_MS = 2 * 60 * 1e3;
+function isNotFound(error) {
+  return error instanceof OwneyError && error.details?.statusCode === 404;
+}
 async function runFusionOrder(deps, options) {
   const {
     orderHash,
@@ -3084,6 +3115,7 @@ async function runFusionOrder(deps, options) {
   } = options;
   const deadline = deps.now() + timeoutMs;
   let failures = 0;
+  let notFoundSince;
   const published = /* @__PURE__ */ new Set();
   onStage?.("swapping");
   for (; ; ) {
@@ -3125,7 +3157,20 @@ async function runFusionOrder(deps, options) {
     try {
       ({ status } = await deps.orderStatus(orderHash));
       failures = 0;
-    } catch {
+      notFoundSince = void 0;
+    } catch (error) {
+      if (isNotFound(error)) {
+        notFoundSince ??= deps.now();
+        if (deps.now() - notFoundSince >= NOT_FOUND_GRACE_MS) {
+          throw new OwneyError(
+            "SWAP_ORDER_NOT_FOUND",
+            "The swap provider has no record of this order, so nothing was exchanged.",
+            { orderHash }
+          );
+        }
+      } else {
+        notFoundSince = void 0;
+      }
       failures += 1;
       await deps.sleep(backoffFor(failures, pollIntervalMs));
       continue;
@@ -3183,9 +3228,9 @@ async function runSameChainOrder(deps, options) {
   for (; ; ) {
     if (deps.now() >= deadline) {
       throw new OwneyError(
-        "SWAP_ORDER_EXPIRED",
-        "No one filled the swap in time. Nothing was exchanged and your funds are still in your wallet.",
-        { orderHash }
+        "SWAP_REQUEST_FAILED",
+        "Timed out waiting for the swap to fill. It may still complete \u2014 if it does, the swapped funds will be in your wallet. Check before retrying.",
+        { orderHash, settlementUnconfirmed: true }
       );
     }
     let status;
@@ -3382,8 +3427,8 @@ async function runClassic(deps, options) {
   onStage?.("quoting");
   debugLog("owney-sdk", "swap: fetching classic calldata");
   let { tx } = await deps.api.swapTx(swapTxRequest);
-  const isNative = BigInt(tx.value ?? "0") > 0n;
-  if (!isNative) {
+  const isNative2 = BigInt(tx.value ?? "0") > 0n;
+  if (!isNative2) {
     const needed = amount;
     const current = await deps.readAllowance(tx.to);
     debugLog("owney-sdk", "swap: allowance", {
@@ -3533,10 +3578,16 @@ async function runFusion(deps, options, walletAddress) {
   debugLog("owney-sdk", "swap: awaiting signature in wallet", {
     signingOnChain: quote.src.chainId
   });
-  const signature = await awaitWalletPrompt(
-    () => deps.signTypedData(built.typedData),
-    "sign the swap"
-  );
+  let signature;
+  try {
+    signature = await awaitWalletPrompt(
+      () => deps.signTypedData(built.typedData),
+      "sign the swap"
+    );
+  } catch (error) {
+    clearOrder(built.orderHash);
+    throw error;
+  }
   debugLog("owney-sdk", "swap: signed, submitting to relayer");
   await deps.api.submitOrder({
     srcChainId: quote.src.chainId,
@@ -3564,7 +3615,7 @@ async function runFusion(deps, options, walletAddress) {
       ...onStage ? { onStage } : {}
     });
   } catch (error) {
-    if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED")) {
+    if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED" || error.code === "SWAP_ORDER_NOT_FOUND")) {
       clearOrder(built.orderHash);
     }
     throw error;
@@ -4443,6 +4494,15 @@ function makeSponsoredCallsCallback(deps) {
 
 // src/client.ts
 var WALLET_CATCHUP_TIMEOUT_MS = 3e4;
+function shortfallBalance(error, asked) {
+  if (!(error instanceof OwneyError)) return void 0;
+  if (error.code !== "DEPOSIT_INSUFFICIENT_BALANCE") return void 0;
+  const seen = error.details?.balance;
+  if (typeof seen !== "string") return void 0;
+  const balance = BigInt(seen);
+  if (balance <= 0n || balance >= asked) return void 0;
+  return (asked - balance) * 100n <= asked ? balance : void 0;
+}
 function encodeMultiAgentCursor(map) {
   return Buffer.from(JSON.stringify(map), "utf8").toString("base64");
 }
@@ -5649,6 +5709,38 @@ var OwneySDK = class {
     const balance = await this.readTokenBalance(chainId, token);
     return (balance < received ? balance : received).toString();
   }
+  /**
+   * Deposit a swap's output, retrying once at the balance the deposit saw.
+   *
+   * `settleSwapDepositAmount` approves and THEN reads, but the read and the
+   * deposit's own pre-check can disagree: the approval is confirmed through
+   * the wallet's node, the read goes to a pinned RPC, and gas paid in WETH
+   * (MetaMask offers this to a wallet with no ETH) can land after either.
+   * ROUT-618 failed that way with the settle step in place.
+   *
+   * The pre-check reports the balance it saw, and that is the authority, so
+   * a shortfall is retried once at that figure. Only a small one: a node that
+   * has not caught up can read near zero, and depositing that would leave the
+   * rest of the swap stranded behind a "success".
+   */
+  async depositSwapOutput(options) {
+    const attempt = (amount) => this.deposit({
+      amount,
+      asset: options.asset,
+      ...options.agentId ? { agentId: options.agentId } : {}
+    });
+    try {
+      return {
+        deposit: await attempt(options.amount),
+        deposited: options.amount
+      };
+    } catch (error) {
+      const balance = shortfallBalance(error, BigInt(options.amount));
+      if (balance === void 0) throw error;
+      const deposited = balance.toString();
+      return { deposit: await attempt(deposited), deposited };
+    }
+  }
   async walletSeesBalance(chainId, token, amount) {
     const provider = this.requireConnectedProvider();
     const state = this.requireState();
@@ -5674,9 +5766,39 @@ var OwneySDK = class {
    * Runs a quoted swap. A named seam rather than an inline `executeSwap` call
    * so the deposit half of `swapAndDeposit` can be exercised on its own.
    */
-  runSwap(quote, options) {
+  async runSwap(quote, options) {
+    await this.checkSwapGas(quote);
     return executeSwap(this.buildSwapDeps(quote), { quote, ...options });
   }
+  /**
+   * Throws SWAP_INSUFFICIENT_GAS when the wallet cannot pay for this swap.
+   *
+   * Only the classic rail is ever refused: it is the one where the user sends
+   * the transactions. Call it on a preview quote to warn BEFORE a withdrawal
+   * moves anything — `withdrawAndSwap` repeats it on its own quote, but by
+   * then the funds have already left the agent (ROUT-622).
+   */
+  async checkSwapGas(quote) {
+    const state = this.requireState();
+    const chain = swapChain(quote.src.chainId);
+    if (!chain) return;
+    const pub = (0, import_viem9.createPublicClient)({
+      chain,
+      transport: swapReadTransport(quote.src.chainId, this.zyfaiRpcUrls)
+    });
+    const shortfall = await swapGasShortfall(
+      {
+        readNativeBalance: () => pub.getBalance({ address: state.walletAddress }),
+        // The 1559 ceiling, as the wrap reserve reads it.
+        getMaxFeePerGas: async () => {
+          const fees = await pub.estimateFeesPerGas();
+          return fees.maxFeePerGas ?? pub.getGasPrice();
+        }
+      },
+      quote
+    );
+    if (shortfall) throw swapGasError(shortfall, chain.nativeCurrency.symbol);
+  }
   /**
    * The half of the swap deps that only ever talks to the routing API.
    *
@@ -5748,8 +5870,15 @@ var OwneySDK = class {
       );
     }
     await this.ensureSwapChain(entry.chainId);
-    const deposit = await this.deposit({
-      amount: entry.received,
+    const token = entry.symbol === "WETH" ? SPONSORED_WETH_BY_CHAIN[entry.chainId] : void 0;
+    const amount = token ? await this.settleSwapDepositAmount(
+      entry.chainId,
+      token,
+      entry.symbol,
+      BigInt(entry.received)
+    ) : entry.received;
+    const { deposit } = await this.depositSwapOutput({
+      amount,
       asset: entry.symbol,
       ...entry.agentId ? { agentId: entry.agentId } : {}
     });
@@ -5799,7 +5928,7 @@ var OwneySDK = class {
           status: "completed"
         });
       } catch (error) {
-        if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED")) {
+        if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED" || error.code === "SWAP_ORDER_NOT_FOUND")) {
           clearOrder(order.orderHash);
           updateWithdrawSwap(order.orderHash, { status: "refunded" });
         } else {
@@ -5989,12 +6118,12 @@ var OwneySDK = class {
         options.to.symbol,
         BigInt(swap.received)
       );
-      const deposit = await this.deposit({
+      const { deposit, deposited } = await this.depositSwapOutput({
         amount,
         asset: options.to.symbol,
         ...options.agentId ? { agentId: options.agentId } : {}
       });
-      return { swap, deposit, deposited: amount };
+      return { swap, deposit, deposited };
     } catch (error) {
       const pending = {
         id: `${quote.dst.chainId}-${options.to.symbol}-${Date.now()}`,
@@ -6098,6 +6227,7 @@ var OwneySDK = class {
         walletAddress: state.walletAddress
       });
       await this.ensureSwapChain(quote.src.chainId);
+      await this.checkSwapGas(quote);
       const swap = await executeSwap(this.buildSwapDeps(quote), {
         quote,
         walletAddress: state.walletAddress,

package/dist/index.d.cts

@@ -964,7 +964,7 @@ type AgentApyOptions = {
     chainId?: number;
 };
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "SWAP_ORDER_NOT_FOUND" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -1393,12 +1393,36 @@ declare class OwneySDK {
      *   where the sponsor covers the transfer and Permit2 never applies.
      */
     private settleSwapDepositAmount;
+    /**
+     * Deposit a swap's output, retrying once at the balance the deposit saw.
+     *
+     * `settleSwapDepositAmount` approves and THEN reads, but the read and the
+     * deposit's own pre-check can disagree: the approval is confirmed through
+     * the wallet's node, the read goes to a pinned RPC, and gas paid in WETH
+     * (MetaMask offers this to a wallet with no ETH) can land after either.
+     * ROUT-618 failed that way with the settle step in place.
+     *
+     * The pre-check reports the balance it saw, and that is the authority, so
+     * a shortfall is retried once at that figure. Only a small one: a node that
+     * has not caught up can read near zero, and depositing that would leave the
+     * rest of the swap stranded behind a "success".
+     */
+    private depositSwapOutput;
     private walletSeesBalance;
     /**
      * Runs a quoted swap. A named seam rather than an inline `executeSwap` call
      * so the deposit half of `swapAndDeposit` can be exercised on its own.
      */
     private runSwap;
+    /**
+     * Throws SWAP_INSUFFICIENT_GAS when the wallet cannot pay for this swap.
+     *
+     * Only the classic rail is ever refused: it is the one where the user sends
+     * the transactions. Call it on a preview quote to warn BEFORE a withdrawal
+     * moves anything — `withdrawAndSwap` repeats it on its own quote, but by
+     * then the funds have already left the agent (ROUT-622).
+     */
+    checkSwapGas(quote: SwapQuote): Promise<void>;
     /**
      * The half of the swap deps that only ever talks to the routing API.
      *

package/dist/index.d.ts

@@ -964,7 +964,7 @@ type AgentApyOptions = {
     chainId?: number;
 };
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "SWAP_ORDER_NOT_FOUND" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -1393,12 +1393,36 @@ declare class OwneySDK {
      *   where the sponsor covers the transfer and Permit2 never applies.
      */
     private settleSwapDepositAmount;
+    /**
+     * Deposit a swap's output, retrying once at the balance the deposit saw.
+     *
+     * `settleSwapDepositAmount` approves and THEN reads, but the read and the
+     * deposit's own pre-check can disagree: the approval is confirmed through
+     * the wallet's node, the read goes to a pinned RPC, and gas paid in WETH
+     * (MetaMask offers this to a wallet with no ETH) can land after either.
+     * ROUT-618 failed that way with the settle step in place.
+     *
+     * The pre-check reports the balance it saw, and that is the authority, so
+     * a shortfall is retried once at that figure. Only a small one: a node that
+     * has not caught up can read near zero, and depositing that would leave the
+     * rest of the swap stranded behind a "success".
+     */
+    private depositSwapOutput;
     private walletSeesBalance;
     /**
      * Runs a quoted swap. A named seam rather than an inline `executeSwap` call
      * so the deposit half of `swapAndDeposit` can be exercised on its own.
      */
     private runSwap;
+    /**
+     * Throws SWAP_INSUFFICIENT_GAS when the wallet cannot pay for this swap.
+     *
+     * Only the classic rail is ever refused: it is the one where the user sends
+     * the transactions. Call it on a preview quote to warn BEFORE a withdrawal
+     * moves anything — `withdrawAndSwap` repeats it on its own quote, but by
+     * then the funds have already left the agent (ROUT-622).
+     */
+    checkSwapGas(quote: SwapQuote): Promise<void>;
     /**
      * The half of the swap deps that only ever talks to the routing API.
      *

package/dist/index.js

@@ -2854,6 +2854,33 @@ function swapChain(chainId) {
   return CHAINS[chainId];
 }
 
+// src/lib/swap/swap.gas-check.ts
+var CLASSIC_SWAP_GAS = 300000n;
+var APPROVE_GAS2 = 60000n;
+var isNative = (address) => address.toLowerCase().startsWith("0xeeee");
+async function swapGasShortfall(deps, quote) {
+  if (quote.rail !== "classic" || isNative(quote.src.address)) return null;
+  const gas = CLASSIC_SWAP_GAS + APPROVE_GAS2;
+  const [balance, gasPrice] = await Promise.all([
+    deps.readNativeBalance(),
+    deps.getMaxFeePerGas()
+  ]);
+  const required = gas * gasPrice;
+  return balance < required ? { chainId: quote.src.chainId, balance, required } : null;
+}
+function swapGasError(shortfall, nativeSymbol) {
+  return new OwneyError(
+    "SWAP_INSUFFICIENT_GAS",
+    `This swap needs a little ${nativeSymbol} for network fees, and your wallet has too little. Add some ${nativeSymbol}, or choose a different asset to receive.`,
+    {
+      chainId: shortfall.chainId,
+      symbol: nativeSymbol,
+      balance: shortfall.balance.toString(),
+      required: shortfall.required.toString()
+    }
+  );
+}
+
 // src/lib/swap/swap.arrival.ts
 var DEFAULT_TIMEOUT_MS = 18e4;
 var DEFAULT_POLL_MS = 4e3;
@@ -3044,6 +3071,10 @@ var DEFAULT_POLL_MS2 = 5e3;
 var MAX_BACKOFF_MS = 3e4;
 var backoffFor = (failures, base4) => Math.min(base4 * 2 ** Math.min(failures, 5), MAX_BACKOFF_MS);
 var DEFAULT_TIMEOUT_MS2 = 15 * 60 * 1e3;
+var NOT_FOUND_GRACE_MS = 2 * 60 * 1e3;
+function isNotFound(error) {
+  return error instanceof OwneyError && error.details?.statusCode === 404;
+}
 async function runFusionOrder(deps, options) {
   const {
     orderHash,
@@ -3054,6 +3085,7 @@ async function runFusionOrder(deps, options) {
   } = options;
   const deadline = deps.now() + timeoutMs;
   let failures = 0;
+  let notFoundSince;
   const published = /* @__PURE__ */ new Set();
   onStage?.("swapping");
   for (; ; ) {
@@ -3095,7 +3127,20 @@ async function runFusionOrder(deps, options) {
     try {
       ({ status } = await deps.orderStatus(orderHash));
       failures = 0;
-    } catch {
+      notFoundSince = void 0;
+    } catch (error) {
+      if (isNotFound(error)) {
+        notFoundSince ??= deps.now();
+        if (deps.now() - notFoundSince >= NOT_FOUND_GRACE_MS) {
+          throw new OwneyError(
+            "SWAP_ORDER_NOT_FOUND",
+            "The swap provider has no record of this order, so nothing was exchanged.",
+            { orderHash }
+          );
+        }
+      } else {
+        notFoundSince = void 0;
+      }
       failures += 1;
       await deps.sleep(backoffFor(failures, pollIntervalMs));
       continue;
@@ -3153,9 +3198,9 @@ async function runSameChainOrder(deps, options) {
   for (; ; ) {
     if (deps.now() >= deadline) {
       throw new OwneyError(
-        "SWAP_ORDER_EXPIRED",
-        "No one filled the swap in time. Nothing was exchanged and your funds are still in your wallet.",
-        { orderHash }
+        "SWAP_REQUEST_FAILED",
+        "Timed out waiting for the swap to fill. It may still complete \u2014 if it does, the swapped funds will be in your wallet. Check before retrying.",
+        { orderHash, settlementUnconfirmed: true }
       );
     }
     let status;
@@ -3352,8 +3397,8 @@ async function runClassic(deps, options) {
   onStage?.("quoting");
   debugLog("owney-sdk", "swap: fetching classic calldata");
   let { tx } = await deps.api.swapTx(swapTxRequest);
-  const isNative = BigInt(tx.value ?? "0") > 0n;
-  if (!isNative) {
+  const isNative2 = BigInt(tx.value ?? "0") > 0n;
+  if (!isNative2) {
     const needed = amount;
     const current = await deps.readAllowance(tx.to);
     debugLog("owney-sdk", "swap: allowance", {
@@ -3503,10 +3548,16 @@ async function runFusion(deps, options, walletAddress) {
   debugLog("owney-sdk", "swap: awaiting signature in wallet", {
     signingOnChain: quote.src.chainId
   });
-  const signature = await awaitWalletPrompt(
-    () => deps.signTypedData(built.typedData),
-    "sign the swap"
-  );
+  let signature;
+  try {
+    signature = await awaitWalletPrompt(
+      () => deps.signTypedData(built.typedData),
+      "sign the swap"
+    );
+  } catch (error) {
+    clearOrder(built.orderHash);
+    throw error;
+  }
   debugLog("owney-sdk", "swap: signed, submitting to relayer");
   await deps.api.submitOrder({
     srcChainId: quote.src.chainId,
@@ -3534,7 +3585,7 @@ async function runFusion(deps, options, walletAddress) {
       ...onStage ? { onStage } : {}
     });
   } catch (error) {
-    if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED")) {
+    if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED" || error.code === "SWAP_ORDER_NOT_FOUND")) {
       clearOrder(built.orderHash);
     }
     throw error;
@@ -4424,6 +4475,15 @@ function makeSponsoredCallsCallback(deps) {
 
 // src/client.ts
 var WALLET_CATCHUP_TIMEOUT_MS = 3e4;
+function shortfallBalance(error, asked) {
+  if (!(error instanceof OwneyError)) return void 0;
+  if (error.code !== "DEPOSIT_INSUFFICIENT_BALANCE") return void 0;
+  const seen = error.details?.balance;
+  if (typeof seen !== "string") return void 0;
+  const balance = BigInt(seen);
+  if (balance <= 0n || balance >= asked) return void 0;
+  return (asked - balance) * 100n <= asked ? balance : void 0;
+}
 function encodeMultiAgentCursor(map) {
   return Buffer.from(JSON.stringify(map), "utf8").toString("base64");
 }
@@ -5630,6 +5690,38 @@ var OwneySDK = class {
     const balance = await this.readTokenBalance(chainId, token);
     return (balance < received ? balance : received).toString();
   }
+  /**
+   * Deposit a swap's output, retrying once at the balance the deposit saw.
+   *
+   * `settleSwapDepositAmount` approves and THEN reads, but the read and the
+   * deposit's own pre-check can disagree: the approval is confirmed through
+   * the wallet's node, the read goes to a pinned RPC, and gas paid in WETH
+   * (MetaMask offers this to a wallet with no ETH) can land after either.
+   * ROUT-618 failed that way with the settle step in place.
+   *
+   * The pre-check reports the balance it saw, and that is the authority, so
+   * a shortfall is retried once at that figure. Only a small one: a node that
+   * has not caught up can read near zero, and depositing that would leave the
+   * rest of the swap stranded behind a "success".
+   */
+  async depositSwapOutput(options) {
+    const attempt = (amount) => this.deposit({
+      amount,
+      asset: options.asset,
+      ...options.agentId ? { agentId: options.agentId } : {}
+    });
+    try {
+      return {
+        deposit: await attempt(options.amount),
+        deposited: options.amount
+      };
+    } catch (error) {
+      const balance = shortfallBalance(error, BigInt(options.amount));
+      if (balance === void 0) throw error;
+      const deposited = balance.toString();
+      return { deposit: await attempt(deposited), deposited };
+    }
+  }
   async walletSeesBalance(chainId, token, amount) {
     const provider = this.requireConnectedProvider();
     const state = this.requireState();
@@ -5655,9 +5747,39 @@ var OwneySDK = class {
    * Runs a quoted swap. A named seam rather than an inline `executeSwap` call
    * so the deposit half of `swapAndDeposit` can be exercised on its own.
    */
-  runSwap(quote, options) {
+  async runSwap(quote, options) {
+    await this.checkSwapGas(quote);
     return executeSwap(this.buildSwapDeps(quote), { quote, ...options });
   }
+  /**
+   * Throws SWAP_INSUFFICIENT_GAS when the wallet cannot pay for this swap.
+   *
+   * Only the classic rail is ever refused: it is the one where the user sends
+   * the transactions. Call it on a preview quote to warn BEFORE a withdrawal
+   * moves anything — `withdrawAndSwap` repeats it on its own quote, but by
+   * then the funds have already left the agent (ROUT-622).
+   */
+  async checkSwapGas(quote) {
+    const state = this.requireState();
+    const chain = swapChain(quote.src.chainId);
+    if (!chain) return;
+    const pub = createPublicClient2({
+      chain,
+      transport: swapReadTransport(quote.src.chainId, this.zyfaiRpcUrls)
+    });
+    const shortfall = await swapGasShortfall(
+      {
+        readNativeBalance: () => pub.getBalance({ address: state.walletAddress }),
+        // The 1559 ceiling, as the wrap reserve reads it.
+        getMaxFeePerGas: async () => {
+          const fees = await pub.estimateFeesPerGas();
+          return fees.maxFeePerGas ?? pub.getGasPrice();
+        }
+      },
+      quote
+    );
+    if (shortfall) throw swapGasError(shortfall, chain.nativeCurrency.symbol);
+  }
   /**
    * The half of the swap deps that only ever talks to the routing API.
    *
@@ -5729,8 +5851,15 @@ var OwneySDK = class {
       );
     }
     await this.ensureSwapChain(entry.chainId);
-    const deposit = await this.deposit({
-      amount: entry.received,
+    const token = entry.symbol === "WETH" ? SPONSORED_WETH_BY_CHAIN[entry.chainId] : void 0;
+    const amount = token ? await this.settleSwapDepositAmount(
+      entry.chainId,
+      token,
+      entry.symbol,
+      BigInt(entry.received)
+    ) : entry.received;
+    const { deposit } = await this.depositSwapOutput({
+      amount,
       asset: entry.symbol,
       ...entry.agentId ? { agentId: entry.agentId } : {}
     });
@@ -5780,7 +5909,7 @@ var OwneySDK = class {
           status: "completed"
         });
       } catch (error) {
-        if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED")) {
+        if (error instanceof OwneyError && (error.code === "SWAP_ORDER_REFUNDED" || error.code === "SWAP_ORDER_CANCELLED" || error.code === "SWAP_ORDER_NOT_FOUND")) {
           clearOrder(order.orderHash);
           updateWithdrawSwap(order.orderHash, { status: "refunded" });
         } else {
@@ -5970,12 +6099,12 @@ var OwneySDK = class {
         options.to.symbol,
         BigInt(swap.received)
       );
-      const deposit = await this.deposit({
+      const { deposit, deposited } = await this.depositSwapOutput({
         amount,
         asset: options.to.symbol,
         ...options.agentId ? { agentId: options.agentId } : {}
       });
-      return { swap, deposit, deposited: amount };
+      return { swap, deposit, deposited };
     } catch (error) {
       const pending = {
         id: `${quote.dst.chainId}-${options.to.symbol}-${Date.now()}`,
@@ -6079,6 +6208,7 @@ var OwneySDK = class {
         walletAddress: state.walletAddress
       });
       await this.ensureSwapChain(quote.src.chainId);
+      await this.checkSwapGas(quote);
       const swap = await executeSwap(this.buildSwapDeps(quote), {
         quote,
         walletAddress: state.walletAddress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owney/sdk",
-  "version": "0.7.28-beta.3",
+  "version": "0.7.28-beta.5",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",