@pafi-dev/trading 0.4.0 → 0.4.2

package/dist/index.js

@@ -71,7 +71,7 @@ async function quoteExactInput(client, quoterAddress, exactCurrency, path, exact
     address: quoterAddress,
     abi: v4QuoterAbi,
     functionName: "quoteExactInput",
-    args: [{ exactCurrency, path, exactAmount: BigInt(exactAmount) }]
+    args: [{ exactCurrency, path, exactAmount }]
   });
   return { amountOut, gasEstimate, path };
 }
@@ -84,7 +84,7 @@ async function quoteExactInputSingle(client, quoterAddress, poolKey, zeroForOne,
       {
         poolKey,
         zeroForOne,
-        exactAmount: BigInt(exactAmount),
+        exactAmount,
         hookData
       }
     ]
@@ -101,13 +101,7 @@ async function quoteBestRoute(client, quoterAddress, exactCurrency, routes, exac
         {
           exactCurrency,
           path,
-          // `as unknown as number` cast — the V4 quoter's solidity
-          // signature takes `uint256` (a bigint at the wire level), but
-          // our pinned ABI types it as `number`. The runtime is fine
-          // (bigint serializes correctly) — this cast tells TS to skip
-          // the structural check until we re-generate the ABI with the
-          // correct uint256 type. Tracked: SDK_CORE_TRADING_AUDIT.md H11.
-          exactAmount: BigInt(exactAmount)
+          exactAmount
         }
       ]
     })),
@@ -148,6 +142,84 @@ async function findBestQuote(client, chainId, tokenIn, tokenOut, exactAmount, po
   }
   return quoteBestRoute(client, quoter, tokenIn, paths, exactAmount);
 }
+async function quoteExactOutput(client, quoterAddress, exactCurrency, path, exactAmount) {
+  const [amountIn, gasEstimate] = await client.readContract({
+    address: quoterAddress,
+    abi: v4QuoterAbi,
+    functionName: "quoteExactOutput",
+    args: [{ exactCurrency, path, exactAmount }]
+  });
+  return { amountIn, gasEstimate, path };
+}
+async function quoteExactOutputSingle(client, quoterAddress, poolKey, zeroForOne, exactAmount, hookData) {
+  const [amountIn, gasEstimate] = await client.readContract({
+    address: quoterAddress,
+    abi: v4QuoterAbi,
+    functionName: "quoteExactOutputSingle",
+    args: [
+      {
+        poolKey,
+        zeroForOne,
+        exactAmount,
+        hookData
+      }
+    ]
+  });
+  return { amountIn, gasEstimate };
+}
+async function quoteBestRouteExactOut(client, quoterAddress, exactCurrency, routes, exactAmount) {
+  const results = await client.multicall({
+    contracts: routes.map((path) => ({
+      address: quoterAddress,
+      abi: v4QuoterAbi,
+      functionName: "quoteExactOutput",
+      args: [
+        {
+          exactCurrency,
+          path,
+          exactAmount
+        }
+      ]
+    })),
+    allowFailure: true
+  });
+  const allRoutes = [];
+  let firstFailure;
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    if (r.status === "success") {
+      const [amountIn, gasEstimate] = r.result;
+      allRoutes.push({ amountIn, gasEstimate, path: routes[i] });
+    } else if (firstFailure === void 0) {
+      const errMsg = r.error instanceof Error ? r.error.message : String(r.error ?? "unknown");
+      firstFailure = errMsg;
+    }
+  }
+  if (allRoutes.length === 0) {
+    throw new Error(
+      `No valid exact-output routes found to ${exactCurrency} (${routes.length} candidates probed)` + (firstFailure ? `; first failure: ${firstFailure}` : "")
+    );
+  }
+  const bestRoute = allRoutes.reduce(
+    (best, current) => current.amountIn < best.amountIn ? current : best
+  );
+  return { bestRoute, allRoutes };
+}
+async function findBestQuoteExactOut(client, chainId, tokenIn, tokenOut, exactAmount, pools = [], quoterAddress, maxHops = 3) {
+  const quoter = quoterAddress ?? V4_QUOTER_ADDRESSES[chainId];
+  if (!quoter) {
+    throw new Error(`No V4 Quoter address configured for chain ${chainId}`);
+  }
+  const commonPools = COMMON_POOLS2[chainId] ?? [];
+  const allPools = [...pools, ...commonPools];
+  const paths = buildAllPaths(allPools, tokenOut, tokenIn, maxHops);
+  if (paths.length === 0) {
+    throw new Error(
+      `No exact-output paths found to ${tokenOut} from ${tokenIn}`
+    );
+  }
+  return quoteBestRouteExactOut(client, quoter, tokenOut, paths, exactAmount);
+}
 
 // src/swap/approval.ts
 import { encodeFunctionData } from "viem";
@@ -180,8 +252,11 @@ function buildPermit2ApprovalCalldata(token, spender, amount, expiration) {
 import { encodeAbiParameters, encodePacked } from "viem";
 var V4_SWAP = 16;
 var SWAP_EXACT_IN = 7;
+var SWAP_EXACT_OUT_SINGLE = 8;
+var SWAP_EXACT_OUT = 9;
 var SETTLE_ALL = 12;
 var TAKE_ALL = 15;
+var UINT128_MAX = 2n ** 128n - 1n;
 var PATH_KEY_ABI_COMPONENTS = [
   { name: "intermediateCurrency", type: "address" },
   { name: "fee", type: "uint256" },
@@ -199,6 +274,16 @@ var EXACT_INPUT_PARAMS_ABI = [
   { name: "amountIn", type: "uint128" },
   { name: "amountOutMinimum", type: "uint128" }
 ];
+var EXACT_OUTPUT_PARAMS_ABI = [
+  { name: "currencyOut", type: "address" },
+  {
+    name: "path",
+    type: "tuple[]",
+    components: PATH_KEY_ABI_COMPONENTS
+  },
+  { name: "amountOut", type: "uint128" },
+  { name: "amountInMaximum", type: "uint128" }
+];
 function buildV4SwapInput(currencyIn, path, amountIn, minAmountOut, outputCurrency) {
   const actions = encodePacked(
     ["uint8", "uint8", "uint8"],
@@ -250,7 +335,81 @@ function buildUniversalRouterExecuteArgs(currencyIn, path, amountIn, minAmountOu
   ];
   return { commands, inputs };
 }
+function buildV4SwapInputExactOut(currencyOut, path, amountOut, maxAmountIn, inputCurrency) {
+  if (amountOut <= 0n || amountOut > UINT128_MAX) {
+    throw new Error(
+      `buildV4SwapInputExactOut: amountOut (${amountOut}) must be in (0, 2^128-1]`
+    );
+  }
+  if (maxAmountIn <= 0n || maxAmountIn > UINT128_MAX) {
+    throw new Error(
+      `buildV4SwapInputExactOut: maxAmountIn (${maxAmountIn}) must be in (0, 2^128-1]`
+    );
+  }
+  const actions = encodePacked(
+    ["uint8", "uint8", "uint8"],
+    [SWAP_EXACT_OUT, SETTLE_ALL, TAKE_ALL]
+  );
+  const swapParam = encodeAbiParameters(
+    [{ name: "swap", type: "tuple", components: EXACT_OUTPUT_PARAMS_ABI }],
+    [
+      {
+        currencyOut,
+        path: path.map((p) => ({
+          intermediateCurrency: p.intermediateCurrency,
+          fee: BigInt(p.fee),
+          tickSpacing: p.tickSpacing,
+          hooks: p.hooks,
+          hookData: p.hookData
+        })),
+        amountOut,
+        amountInMaximum: maxAmountIn
+      }
+    ]
+  );
+  const settleParam = encodeAbiParameters(
+    [
+      { name: "currency", type: "address" },
+      { name: "maxAmount", type: "uint256" }
+    ],
+    [inputCurrency, maxAmountIn]
+  );
+  const takeParam = encodeAbiParameters(
+    [
+      { name: "currency", type: "address" },
+      { name: "minAmount", type: "uint256" }
+    ],
+    [currencyOut, amountOut]
+  );
+  return encodeAbiParameters(
+    [
+      { name: "actions", type: "bytes" },
+      { name: "params", type: "bytes[]" }
+    ],
+    [actions, [swapParam, settleParam, takeParam]]
+  );
+}
+function buildUniversalRouterExecuteArgsExactOut(currencyOut, path, amountOut, maxAmountIn, inputCurrency) {
+  const commands = encodePacked(["uint8"], [V4_SWAP]);
+  const inputs = [
+    buildV4SwapInputExactOut(
+      currencyOut,
+      path,
+      amountOut,
+      maxAmountIn,
+      inputCurrency
+    )
+  ];
+  return { commands, inputs };
+}
+var _buildSwapFromQuoteWarned = false;
 function buildSwapFromQuote(params) {
+  if (!_buildSwapFromQuoteWarned) {
+    _buildSwapFromQuoteWarned = true;
+    console.warn(
+      "[PAFI] DEPRECATION (v1.4+): `buildSwapFromQuote` from @pafi-dev/trading is deprecated and will be removed in v2.0. Use `buildUniversalRouterExecuteArgs` directly with `quote.bestRoute.path`."
+    );
+  }
   return buildUniversalRouterExecuteArgs(
     params.currencyIn,
     params.quote.path,
@@ -358,6 +517,82 @@ function buildSwapUserOp(params) {
     }
   });
 }
+function buildSwapUserOpExactOut(params) {
+  if (params.amountOut <= 0n) {
+    throw new Error("buildSwapUserOpExactOut: amountOut must be positive");
+  }
+  if (params.maxAmountIn <= 0n) {
+    throw new Error("buildSwapUserOpExactOut: maxAmountIn must be positive");
+  }
+  if (params.gasFeeAmountInput < 0n) {
+    throw new Error(
+      "buildSwapUserOpExactOut: gasFeeAmountInput must be non-negative"
+    );
+  }
+  if (params.swapPath.length === 0) {
+    throw new Error(
+      "buildSwapUserOpExactOut: swapPath must contain at least one PathKey"
+    );
+  }
+  const PERMIT2_EXPIRATION_MAX = 2n ** 48n - 1n;
+  if (params.deadline <= 0n || params.deadline > PERMIT2_EXPIRATION_MAX) {
+    throw new Error(
+      `buildSwapUserOpExactOut: deadline (${params.deadline}) must be unix seconds in (0, 2^48-1]. Did you accidentally pass milliseconds?`
+    );
+  }
+  const { commands, inputs } = buildUniversalRouterExecuteArgsExactOut(
+    params.outputTokenAddress,
+    params.swapPath,
+    params.amountOut,
+    params.maxAmountIn,
+    params.inputTokenAddress
+  );
+  const swapCallData = encodeFunctionData2({
+    abi: universalRouterAbi2,
+    functionName: "execute",
+    args: [commands, inputs, params.deadline]
+  });
+  const permit2ApproveData = buildPermit2ApprovalCalldata(
+    params.inputTokenAddress,
+    params.universalRouterAddress,
+    params.maxAmountIn,
+    Number(params.deadline)
+  );
+  const operations = [];
+  if (params.gasFeeAmountInput > 0n) {
+    operations.push(
+      erc20TransferOp(
+        params.inputTokenAddress,
+        params.feeRecipient,
+        params.gasFeeAmountInput
+      )
+    );
+  }
+  operations.push(
+    erc20ApproveOp(params.inputTokenAddress, PERMIT2_ADDRESS, params.maxAmountIn),
+    rawCallOp(PERMIT2_ADDRESS, permit2ApproveData),
+    rawCallOp(params.universalRouterAddress, swapCallData)
+  );
+  return buildPartialUserOperation({
+    sender: params.userAddress,
+    nonce: params.aaNonce,
+    operations,
+    gasLimits: {
+      // +50k headroom for the additional pre-swap ERC-20 transfer when
+      // the input-side fee is non-zero. Keeps margin even when fee=0n.
+      callGasLimit: params.gasLimits?.callGasLimit ?? 750000n,
+      verificationGasLimit: params.gasLimits?.verificationGasLimit ?? 150000n,
+      preVerificationGas: params.gasLimits?.preVerificationGas ?? 50000n
+    }
+  });
+}
+
+// src/swap/slippage.ts
+var MAX_SLIPPAGE_BPS = 5e3;
+function isValidSlippageBps(value) {
+  if (value === void 0) return true;
+  return Number.isInteger(value) && value >= 0 && value <= MAX_SLIPPAGE_BPS;
+}
 
 // src/api/handlers.ts
 var TradingHandlers = class {
@@ -446,10 +681,9 @@ var TradingHandlers = class {
    * net. Quote response surfaces both `estimatedOutputAmount` (gross)
    * and `outputNet` so the FE can display reality.
    *
-   * v0.3.1 — `authenticatedAddress` first param. Caller (issuer
-   * controller / FE proxy) MUST pass the address extracted from the
-   * verified session/JWT. Handler asserts it equals
-   * `request.userAddress`. See SDK_CORE_TRADING_AUDIT.md C6.
+   * `authenticatedAddress` first param: caller (issuer controller / FE
+   * proxy) MUST pass the address extracted from the verified
+   * session/JWT. Handler asserts it equals `request.userAddress`.
    */
   async handleSwap(authenticatedAddress, request) {
     if (getAddress(authenticatedAddress) !== getAddress(request.userAddress)) {
@@ -471,6 +705,13 @@ var TradingHandlers = class {
         "handleSwap: amount must be positive"
       );
     }
+    if (!isValidSlippageBps(request.slippageBps)) {
+      throw new ValidationError(
+        "INVALID_SLIPPAGE",
+        `handleSwap: slippageBps (${request.slippageBps}) must be an integer in [0, ${MAX_SLIPPAGE_BPS}]`,
+        { received: request.slippageBps, max: MAX_SLIPPAGE_BPS }
+      );
+    }
     const { pafiFeeRecipient } = getContractAddresses(request.chainId);
     const universalRouter = UNIVERSAL_ROUTER_ADDRESSES[request.chainId];
     if (!universalRouter) {
@@ -558,6 +799,198 @@ var TradingHandlers = class {
     };
   }
   // =========================================================================
+  // GET /quote/exact-out — V4 exact-output quote
+  // =========================================================================
+  /**
+   * Quote the input required to receive `request.amount` of the output
+   * token via Uniswap V4. Input-side operator fee is auto-quoted, so
+   * `inputGross = estimatedInputAmount + feeAmountInput` is the total
+   * the user must hold.
+   *
+   * Returns `quoteError: "QUOTE_UNAVAILABLE"` rather than throwing when
+   * no path exists.
+   */
+  async handleQuoteExactOut(request) {
+    if (request.chainId !== this.chainId) {
+      throw new ValidationError(
+        "UNSUPPORTED_CHAIN_ID",
+        `handleQuoteExactOut: unsupported chainId ${request.chainId}`,
+        { requested: request.chainId, supported: this.chainId }
+      );
+    }
+    if (request.amount === 0n) {
+      return {
+        outputAmount: 0n,
+        estimatedInputAmount: 0n,
+        inputGross: 0n,
+        feeAmountInput: 0n,
+        gasEstimate: 0n
+      };
+    }
+    const inputTokenAddress = getAddress(request.inputTokenAddress);
+    const outputTokenAddress = getAddress(request.outputTokenAddress);
+    const pools = request.pools ?? [];
+    try {
+      const best = await findBestQuoteExactOut(
+        this.provider,
+        request.chainId,
+        inputTokenAddress,
+        outputTokenAddress,
+        request.amount,
+        pools
+      );
+      const feeAmountInput = await quoteOperatorFeeInput(
+        this.provider,
+        request.chainId,
+        inputTokenAddress
+      ).catch(() => 0n);
+      const estimatedInputAmount = best.bestRoute.amountIn;
+      return {
+        outputAmount: request.amount,
+        estimatedInputAmount,
+        inputGross: estimatedInputAmount + feeAmountInput,
+        feeAmountInput,
+        gasEstimate: best.bestRoute.gasEstimate
+      };
+    } catch {
+      return {
+        outputAmount: request.amount,
+        estimatedInputAmount: 0n,
+        inputGross: 0n,
+        feeAmountInput: 0n,
+        gasEstimate: 0n,
+        quoteError: "QUOTE_UNAVAILABLE"
+      };
+    }
+  }
+  // =========================================================================
+  // POST /swap/exact-out — V4 exact-output swap UserOp
+  // =========================================================================
+  /**
+   * Build a V4 exact-output swap UserOp.
+   *
+   * Quotes the best exact-output route, applies slippage as a CEILING on
+   * `maxAmountIn` (so the cap is never silently tightened by floor
+   * division), then encodes a 4-step batch:
+   *
+   *   inputToken.transfer(feeRecipient, gasFeeAmountInput)  [if > 0]
+   *     → input.approve(Permit2, maxAmountIn)
+   *     → Permit2.approve(router, maxAmountIn)
+   *     → UniversalRouter.execute (V4 SWAP_EXACT_OUT)
+   *
+   * Operator fee is INPUT-token-side (charged before swap) so the user
+   * receives exactly `request.amount` of output.
+   *
+   * `authenticatedAddress` first param: caller MUST pass the address
+   * extracted from the verified session/JWT. Handler asserts equality
+   * with `request.userAddress`.
+   */
+  async handleSwapExactOut(authenticatedAddress, request) {
+    if (getAddress(authenticatedAddress) !== getAddress(request.userAddress)) {
+      throw new ValidationError(
+        "USER_ADDRESS_MISMATCH",
+        `handleSwapExactOut: authenticatedAddress (${authenticatedAddress}) does not match request.userAddress (${request.userAddress})`
+      );
+    }
+    if (request.chainId !== this.chainId) {
+      throw new ValidationError(
+        "UNSUPPORTED_CHAIN_ID",
+        `handleSwapExactOut: unsupported chainId ${request.chainId}`,
+        { requested: request.chainId, supported: this.chainId }
+      );
+    }
+    if (request.amount <= 0n) {
+      throw new ValidationError(
+        "INVALID_AMOUNT",
+        "handleSwapExactOut: amount must be positive"
+      );
+    }
+    if (!isValidSlippageBps(request.slippageBps)) {
+      throw new ValidationError(
+        "INVALID_SLIPPAGE",
+        `handleSwapExactOut: slippageBps (${request.slippageBps}) must be an integer in [0, ${MAX_SLIPPAGE_BPS}]`,
+        { received: request.slippageBps, max: MAX_SLIPPAGE_BPS }
+      );
+    }
+    const { pafiFeeRecipient } = getContractAddresses(request.chainId);
+    const universalRouter = UNIVERSAL_ROUTER_ADDRESSES[request.chainId];
+    if (!universalRouter) {
+      throw new ValidationError(
+        "ROUTER_NOT_DEPLOYED",
+        `handleSwapExactOut: no UniversalRouter for chainId ${request.chainId}`
+      );
+    }
+    const inputTokenAddress = getAddress(request.inputTokenAddress);
+    const outputTokenAddress = getAddress(request.outputTokenAddress);
+    const userAddress = getAddress(request.userAddress);
+    const pools = request.pools ?? [];
+    let quoteResult;
+    try {
+      quoteResult = await findBestQuoteExactOut(
+        this.provider,
+        request.chainId,
+        inputTokenAddress,
+        outputTokenAddress,
+        request.amount,
+        pools
+      );
+    } catch (err) {
+      const cause = err instanceof Error ? err.message : String(err);
+      throw new ValidationError(
+        "NO_SWAP_PATH",
+        `handleSwapExactOut: no swap path found from ${inputTokenAddress} to ${outputTokenAddress} (cause: ${cause})`
+      );
+    }
+    const gasFeeAmountInput = request.gasFeeAmountInput !== void 0 ? request.gasFeeAmountInput : await quoteOperatorFeeInput(
+      this.provider,
+      request.chainId,
+      inputTokenAddress
+    ).catch(() => 0n);
+    const hops = quoteResult.bestRoute.path.length;
+    const slippageBps = request.slippageBps ?? (hops > 1 ? 100 : 50);
+    const estimatedInputAmount = quoteResult.bestRoute.amountIn;
+    const slippageNumerator = estimatedInputAmount * BigInt(1e4 + slippageBps);
+    const maxAmountIn = (slippageNumerator + 9999n) / 10000n;
+    const deadline = BigInt(Math.floor(Date.now() / 1e3) + 5 * 60);
+    const userOp = buildSwapUserOpExactOut({
+      userAddress,
+      aaNonce: request.aaNonce,
+      inputTokenAddress,
+      outputTokenAddress,
+      universalRouterAddress: universalRouter,
+      amountOut: request.amount,
+      maxAmountIn,
+      swapPath: quoteResult.bestRoute.path,
+      deadline,
+      gasFeeAmountInput,
+      feeRecipient: pafiFeeRecipient
+    });
+    const userOpFallback = gasFeeAmountInput > 0n ? buildSwapUserOpExactOut({
+      userAddress,
+      aaNonce: request.aaNonce,
+      inputTokenAddress,
+      outputTokenAddress,
+      universalRouterAddress: universalRouter,
+      amountOut: request.amount,
+      maxAmountIn,
+      swapPath: quoteResult.bestRoute.path,
+      deadline,
+      gasFeeAmountInput: 0n,
+      feeRecipient: pafiFeeRecipient
+    }) : void 0;
+    return {
+      userOp,
+      userOpFallback,
+      outputAmount: request.amount,
+      estimatedInputAmount,
+      maxAmountIn,
+      hops,
+      deadline,
+      feeAmountUsed: gasFeeAmountInput,
+      feeRecipient: pafiFeeRecipient
+    };
+  }
+  // =========================================================================
   // POST /perp-deposit
   // =========================================================================
   /**
@@ -764,6 +1197,17 @@ async function quoteOperatorFeeOutput(provider, chainId, outputTokenAddress) {
     pointTokenAddress: outputTokenAddress
   });
 }
+async function quoteOperatorFeeInput(provider, chainId, inputTokenAddress) {
+  const { usdt } = getContractAddresses(chainId);
+  if (usdt && getAddress(inputTokenAddress) === getAddress(usdt)) {
+    return quoteOperatorFeeUsdt({ provider, chainId });
+  }
+  return quoteOperatorFeePt({
+    provider,
+    chainId,
+    pointTokenAddress: inputTokenAddress
+  });
+}
 
 // src/pools.ts
 import { fetchPafiPools, PAFI_SUBGRAPH_URL } from "@pafi-dev/core";
@@ -778,6 +1222,29 @@ import {
   BATCH_EXECUTOR_7702_IMPL
 } from "@pafi-dev/core";
 async function swapDirect(params) {
+  const universalRouter = UNIVERSAL_ROUTER_ADDRESSES2[params.chainId];
+  if (!universalRouter) {
+    throw new Error(`swapDirect: no UniversalRouter for chainId ${params.chainId}`);
+  }
+  if (params.amount <= 0n) {
+    throw new Error("swapDirect: amount must be positive");
+  }
+  if (!isValidSlippageBps(params.slippageBps)) {
+    throw new Error(
+      `swapDirect: slippageBps (${params.slippageBps}) must be an integer in [0, ${MAX_SLIPPAGE_BPS}]`
+    );
+  }
+  const account = params.walletClient.account;
+  if (!account) {
+    throw new Error(
+      "swapDirect: walletClient has no account attached \u2014 cannot send tx"
+    );
+  }
+  if (account.address.toLowerCase() !== params.userAddress.toLowerCase()) {
+    throw new Error(
+      `swapDirect: walletClient.account.address (${account.address}) must equal userAddress (${params.userAddress}) \u2014 the native tx must be sent from the same EOA whose 7702-delegated bytecode is being executed`
+    );
+  }
   const code = await params.publicClient.getCode({
     address: params.userAddress
   });
@@ -793,13 +1260,6 @@ async function swapDirect(params) {
       `swapDirect: user delegated to ${delegate} which is not a PAFI-recognised impl (expected ${SIMPLE_7702_IMPL_BASE_MAINNET} or ${BATCH_EXECUTOR_7702_IMPL}). Continuing \u2014 execute will revert if the impl doesn't expose executeBatch.`
     );
   }
-  const universalRouter = UNIVERSAL_ROUTER_ADDRESSES2[params.chainId];
-  if (!universalRouter) {
-    throw new Error(`swapDirect: no UniversalRouter for chainId ${params.chainId}`);
-  }
-  if (params.amount <= 0n) {
-    throw new Error("swapDirect: amount must be positive");
-  }
   let quoteResult;
   try {
     quoteResult = await findBestQuote(
@@ -842,12 +1302,124 @@ async function swapDirect(params) {
     gasFeeAmountOutput,
     feeRecipient: pafiFeeRecipient
   });
+  const txHash = await params.walletClient.sendTransaction({
+    account,
+    chain: params.walletClient.chain,
+    to: params.userAddress,
+    value: 0n,
+    data: userOp.callData
+  });
+  let receipt;
+  if (params.waitForReceipt !== false) {
+    try {
+      receipt = await params.publicClient.waitForTransactionReceipt({
+        hash: txHash
+      });
+    } catch (err) {
+      params.onWarning?.(
+        `swapDirect: tx ${txHash} sent but receipt fetch failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  return {
+    txHash,
+    receipt,
+    estimatedOutputAmount,
+    minAmountOut,
+    hops,
+    deadline,
+    feeAmountUsed: gasFeeAmountOutput
+  };
+}
+
+// src/direct/swapDirectExactOut.ts
+import {
+  UNIVERSAL_ROUTER_ADDRESSES as UNIVERSAL_ROUTER_ADDRESSES3,
+  getContractAddresses as getContractAddresses3,
+  parseEip7702DelegatedAddress as parseEip7702DelegatedAddress2,
+  detectDelegateImpl as detectDelegateImpl2,
+  SIMPLE_7702_IMPL_BASE_MAINNET as SIMPLE_7702_IMPL_BASE_MAINNET2,
+  BATCH_EXECUTOR_7702_IMPL as BATCH_EXECUTOR_7702_IMPL2
+} from "@pafi-dev/core";
+async function swapDirectExactOut(params) {
+  const universalRouter = UNIVERSAL_ROUTER_ADDRESSES3[params.chainId];
+  if (!universalRouter) {
+    throw new Error(
+      `swapDirectExactOut: no UniversalRouter for chainId ${params.chainId}`
+    );
+  }
+  if (params.amount <= 0n) {
+    throw new Error("swapDirectExactOut: amount must be positive");
+  }
+  if (!isValidSlippageBps(params.slippageBps)) {
+    throw new Error(
+      `swapDirectExactOut: slippageBps (${params.slippageBps}) must be an integer in [0, ${MAX_SLIPPAGE_BPS}]`
+    );
+  }
   const account = params.walletClient.account;
   if (!account) {
     throw new Error(
-      "swapDirect: walletClient has no account attached \u2014 cannot send tx"
+      "swapDirectExactOut: walletClient has no account attached \u2014 cannot send tx"
     );
   }
+  if (account.address.toLowerCase() !== params.userAddress.toLowerCase()) {
+    throw new Error(
+      `swapDirectExactOut: walletClient.account.address (${account.address}) must equal userAddress (${params.userAddress}) \u2014 the native tx must be sent from the same EOA whose 7702-delegated bytecode is being executed`
+    );
+  }
+  const code = await params.publicClient.getCode({
+    address: params.userAddress
+  });
+  const delegate = parseEip7702DelegatedAddress2(code);
+  if (!delegate) {
+    throw new Error(
+      `swapDirectExactOut: user ${params.userAddress} is not EIP-7702 delegated. Run \`delegateDirect()\` first or use the AA path via \`TradingHandlers.handleSwapExactOut()\` + sponsor-relayer.`
+    );
+  }
+  const impl = detectDelegateImpl2(delegate);
+  if (impl === "unknown") {
+    params.onWarning?.(
+      `swapDirectExactOut: user delegated to ${delegate} which is not a PAFI-recognised impl (expected ${SIMPLE_7702_IMPL_BASE_MAINNET2} or ${BATCH_EXECUTOR_7702_IMPL2}). Continuing \u2014 execute will revert if the impl doesn't expose executeBatch.`
+    );
+  }
+  let quoteResult;
+  try {
+    quoteResult = await findBestQuoteExactOut(
+      params.publicClient,
+      params.chainId,
+      params.inputTokenAddress,
+      params.outputTokenAddress,
+      params.amount,
+      params.pools ?? []
+    );
+  } catch (err) {
+    const cause = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `swapDirectExactOut: no swap path found from ${params.inputTokenAddress} to ${params.outputTokenAddress} (cause: ${cause})`
+    );
+  }
+  const hops = quoteResult.bestRoute.path.length;
+  const slippageBps = params.slippageBps ?? (hops > 1 ? 100 : 50);
+  const estimatedInputAmount = quoteResult.bestRoute.amountIn;
+  const slippageNumerator = estimatedInputAmount * BigInt(1e4 + slippageBps);
+  const maxAmountIn = (slippageNumerator + 9999n) / 10000n;
+  const gasFeeAmountInput = params.gasFeeAmountInput ?? 0n;
+  const deadline = params.deadline ?? BigInt(Math.floor(Date.now() / 1e3) + 5 * 60);
+  const { pafiFeeRecipient } = getContractAddresses3(params.chainId);
+  const userOp = buildSwapUserOpExactOut({
+    userAddress: params.userAddress,
+    aaNonce: 0n,
+    // ignored on the native-tx path; nonce comes from EOA tx count
+    inputTokenAddress: params.inputTokenAddress,
+    outputTokenAddress: params.outputTokenAddress,
+    universalRouterAddress: universalRouter,
+    amountOut: params.amount,
+    maxAmountIn,
+    swapPath: quoteResult.bestRoute.path,
+    deadline,
+    gasFeeAmountInput,
+    feeRecipient: pafiFeeRecipient
+  });
   const txHash = await params.walletClient.sendTransaction({
     account,
     chain: params.walletClient.chain,
@@ -863,18 +1435,19 @@ async function swapDirect(params) {
       });
     } catch (err) {
       params.onWarning?.(
-        `swapDirect: tx ${txHash} sent but receipt fetch failed: ${err instanceof Error ? err.message : String(err)}`
+        `swapDirectExactOut: tx ${txHash} sent but receipt fetch failed: ${err instanceof Error ? err.message : String(err)}`
       );
     }
   }
   return {
     txHash,
     receipt,
-    estimatedOutputAmount,
-    minAmountOut,
+    outputAmount: params.amount,
+    estimatedInputAmount,
+    maxAmountIn,
     hops,
     deadline,
-    feeAmountUsed: gasFeeAmountOutput
+    feeAmountUsed: gasFeeAmountInput
   };
 }
 
@@ -887,11 +1460,11 @@ import {
   TOKEN_HASHES as TOKEN_HASHES2,
   buildPerpDepositViaRelay as buildPerpDepositViaRelay2,
   computeAccountId as computeAccountId2,
-  detectDelegateImpl as detectDelegateImpl2,
-  getContractAddresses as getContractAddresses3,
-  parseEip7702DelegatedAddress as parseEip7702DelegatedAddress2,
-  BATCH_EXECUTOR_7702_IMPL as BATCH_EXECUTOR_7702_IMPL2,
-  SIMPLE_7702_IMPL_BASE_MAINNET as SIMPLE_7702_IMPL_BASE_MAINNET2
+  detectDelegateImpl as detectDelegateImpl3,
+  getContractAddresses as getContractAddresses4,
+  parseEip7702DelegatedAddress as parseEip7702DelegatedAddress3,
+  BATCH_EXECUTOR_7702_IMPL as BATCH_EXECUTOR_7702_IMPL3,
+  SIMPLE_7702_IMPL_BASE_MAINNET as SIMPLE_7702_IMPL_BASE_MAINNET3
 } from "@pafi-dev/core";
 async function perpDepositDirect(params) {
   if (params.amount <= 0n) {
@@ -900,16 +1473,16 @@ async function perpDepositDirect(params) {
   const code = await params.publicClient.getCode({
     address: params.userAddress
   });
-  const delegate = parseEip7702DelegatedAddress2(code);
+  const delegate = parseEip7702DelegatedAddress3(code);
   if (!delegate) {
     throw new Error(
       `perpDepositDirect: user ${params.userAddress} is not EIP-7702 delegated. Run \`delegateDirect()\` first or use the AA path via \`TradingHandlers.handlePerpDeposit()\` + sponsor-relayer.`
     );
   }
-  const impl = detectDelegateImpl2(delegate);
+  const impl = detectDelegateImpl3(delegate);
   if (impl === "unknown") {
     params.onWarning?.(
-      `perpDepositDirect: user delegated to ${delegate} (not a PAFI-recognised impl ${SIMPLE_7702_IMPL_BASE_MAINNET2} / ${BATCH_EXECUTOR_7702_IMPL2}). Continuing \u2014 execute will revert if the impl doesn't expose executeBatch.`
+      `perpDepositDirect: user delegated to ${delegate} (not a PAFI-recognised impl ${SIMPLE_7702_IMPL_BASE_MAINNET3} / ${BATCH_EXECUTOR_7702_IMPL3}). Continuing \u2014 execute will revert if the impl doesn't expose executeBatch.`
     );
   }
   const vault = ORDERLY_VAULT_ADDRESSES2[params.chainId];
@@ -944,7 +1517,7 @@ async function perpDepositDirect(params) {
       `perpDepositDirect: broker "${params.brokerId}" is not whitelisted on Orderly Vault`
     );
   }
-  const { orderlyRelay: relayAddress, pafiFeeRecipient } = getContractAddresses3(
+  const { orderlyRelay: relayAddress, pafiFeeRecipient } = getContractAddresses4(
     params.chainId
   );
   const RELAY_FEE_FLOOR_USDC = 2000000n;
@@ -1024,23 +1597,33 @@ async function perpDepositDirect(params) {
 }
 export {
   PAFI_SUBGRAPH_URL,
+  SWAP_EXACT_OUT,
+  SWAP_EXACT_OUT_SINGLE,
   TradingHandlers,
   buildAllPaths,
   buildErc20ApprovalCalldata,
   buildPermit2ApprovalCalldata,
   buildSwapFromQuote,
   buildSwapUserOp,
+  buildSwapUserOpExactOut,
   buildUniversalRouterExecuteArgs,
+  buildUniversalRouterExecuteArgsExactOut,
   buildV4SwapInput,
+  buildV4SwapInputExactOut,
   checkAllowance,
   combineRoutes,
   fetchPafiPools,
   findBestQuote,
+  findBestQuoteExactOut,
   perpDepositDirect,
   quoteBestRoute,
+  quoteBestRouteExactOut,
   quoteExactInput,
   quoteExactInputSingle,
+  quoteExactOutput,
+  quoteExactOutputSingle,
   simulateSwap,
-  swapDirect
+  swapDirect,
+  swapDirectExactOut
 };
 //# sourceMappingURL=index.js.map