@nradko/metric-omm-sdk-v1 0.4.2 → 0.4.4

package/src/pool/liquidity.ts

@@ -1,6 +1,22 @@
 /**
- * MetricAMM SDK - Liquidity
- * Unified liquidity calculations and position operations.
+ * Liquidity position builders and calldata encoders.
+ *
+ * **Add liquidity (recommended path):**
+ * 1. `buildModifyLiquidityArgsForAddition` / `ForUniformAddition` / `ForUniformAdditionWithTotalTokenAmount`
+ * 2. `buildAddLiquidityExactSharesParamsFromBinTargets` (optional convenience)
+ * 3. `encodeAddLiquidityExactSharesSelfCalldata` or `encodeAddLiquidityExactSharesWithOwnerCalldata`
+ *    — target `addresses.liquidityAdder`
+ * 4. Approve token0 and token1 on the LiquidityAdder for `maxAmountToken0` / `maxAmountToken1`
+ *
+ * **Self vs WithOwner encoders:**
+ * - `*SelfCalldata` — credits liquidity to **`msg.sender`** (the transaction sender owns the position).
+ * - `*WithOwnerCalldata` — credits liquidity to **`owner`** (e.g. router, vault, or relayer paying on behalf of a user).
+ *   The caller still supplies tokens and must approve the LiquidityAdder; only the position owner differs.
+ *
+ * **Remove liquidity:** `buildModifyLiquidityArgsForRemoval` → `buildRemoveLiquidityPoolDelta`
+ * → `encodeRemoveLiquidityCalldata` — call the **pool** directly (no adder approval).
+ *
+ * Position identity is `(owner, salt)`; use the same `salt` for adds and removes.
  */
 
 import type { Address, PublicClient, Hex } from "viem";
@@ -40,19 +56,27 @@ function getLiquidityAdderFunction(name: string, inputCount: number) {
   return item;
 }
 
+/** High-level removal options (used by UI helpers). Prefer {@link BuildModifyLiquidityArgsForRemovalParams} in SDK code. */
 export interface RemoveLiquidityParams {
+  /** Percent of each selected bin's shares to burn (0–100). */
   percentageToRemove: number;
+  /** Explicit bin list; when omitted, scans `lowerBin`–`upperBin` for position shares. */
   bins?: number[];
   lowerBin?: number;
   upperBin?: number;
 }
 
+/** Per-bin removal: specify exactly one of `percentageToRemove` or `sharesToRemove`. */
 export interface BinRemovalSpec {
   bin: number;
   percentageToRemove?: number;
   sharesToRemove?: bigint;
 }
 
+/**
+ * Sentinel passed as `specAmount0` / `specAmount1` on removals — no minimum output enforced.
+ * Same value the pool uses for "accept any amount" on `modifyLiquidity` removes.
+ */
 export const NO_SLIPPAGE_LIMIT = MAX_INT128;
 
 type ModifyLiquidityParams = {
@@ -62,30 +86,39 @@ type ModifyLiquidityParams = {
   specAmount1: bigint;
 };
 
+/**
+ * Tuple for low-level `modifyLiquidity` on the pool:
+ * `[salt, deltas, specAmount0, specAmount1]`.
+ * Prefer LiquidityAdder encode helpers for additions.
+ */
 export type ModifyLiquidityArgs = readonly [bigint, LiquidityDelta[], bigint, bigint];
 
 export interface BuildModifyLiquidityArgsBase {
   publicClient: PublicClient;
-  /** MetricOmmPoolDataProvider address (`addresses.dataProvider` on mainnet). */
+  /** MetricOmmPoolDataProvider (`addresses.dataProvider`). */
   dataProviderAddress: Address;
   poolAddress: Address;
+  /** Extra headroom on spec amounts (percent); `0` = exact computed caps. */
   specAmountBufferPercent?: number;
 }
 
-/** Addition builders read pool immutables via `getImmutables()` — removal only needs the data provider lens. */
+/** Addition builders need the factory to read pool immutables (decimals, bin range). */
 export interface BuildModifyLiquidityArgsWithFactory extends BuildModifyLiquidityArgsBase {
   factoryAddress: Address;
 }
 
+/** Per-bin target amounts for {@link buildModifyLiquidityArgsForAddition}. */
 export interface BuildModifyLiquidityArgsForAdditionParams extends BuildModifyLiquidityArgsWithFactory {
   bins: LiquidityBinValueInput[];
-  /** Human-readable price (token1 per token0). Omit when using currentPriceX64. */
+  /** Human price token1/token0; omit when `currentPriceX64` is set. */
   currentPrice?: number;
-  /** On-chain Q64 price. Preferred over currentPrice when available from slot0 / oracle. */
+  /** Q64.64 price from slot0; preferred over `currentPrice`. */
   currentPriceX64?: bigint;
+  /** Position salt; default `0n`. Reuse across adds to the same position. */
   salt?: bigint;
 }
 
+/** Same value in every bin from `lowerBin` through `upperBin` inclusive. */
 export interface BuildModifyLiquidityArgsForUniformAdditionParams extends BuildModifyLiquidityArgsWithFactory {
   amountInTokensPerBin: bigint;
   amountIsInToken0: boolean;
@@ -95,6 +128,7 @@ export interface BuildModifyLiquidityArgsForUniformAdditionParams extends BuildM
   salt?: bigint;
 }
 
+/** Split a total token budget across `bins` (optional `weights`); calibrates share scaling on-chain. */
 export interface BuildModifyLiquidityArgsForUniformAdditionWithTotalTokenAmountParams extends BuildModifyLiquidityArgsWithFactory {
   bins: number[];
   weights?: number[];
@@ -104,6 +138,7 @@ export interface BuildModifyLiquidityArgsForUniformAdditionWithTotalTokenAmountP
   salt?: bigint;
 }
 
+/** Remove the same percentage from all bins with liquidity (or from explicit `bins`). */
 export interface BuildModifyLiquidityArgsForPercentageRemovalParams extends BuildModifyLiquidityArgsBase {
   owner: Address;
   salt: bigint;
@@ -113,6 +148,7 @@ export interface BuildModifyLiquidityArgsForPercentageRemovalParams extends Buil
   upperBin?: number;
 }
 
+/** Granular per-bin removal specs. */
 export interface BuildModifyLiquidityArgsForRemovalParams extends BuildModifyLiquidityArgsBase {
   owner: Address;
   salt: bigint;
@@ -130,7 +166,10 @@ function resolvePriceE18(params: { currentPrice?: number; currentPriceX64?: bigi
 }
 
 /**
- * Prepare uniform liquidity distribution across a bin range.
+ * Uniform liquidity: same token amount in every bin from `lowerBin` to `upperBin`.
+ * Delegates to {@link buildModifyLiquidityArgsForAddition}.
+ *
+ * @returns `[salt, deltas, specAmount0, specAmount1]` — max token caps for the adder.
  */
 export async function buildModifyLiquidityArgsForUniformAddition({
   publicClient,
@@ -517,6 +556,11 @@ export async function buildModifyLiquidityArgsForAddition({
   return toModifyLiquidityArgs(computed);
 }
 
+/**
+ * Remove liquidity by explicit per-bin specs (percentage or absolute shares).
+ *
+ * `specAmount0` / `specAmount1` are set to {@link NO_SLIPPAGE_LIMIT} (accept any output).
+ */
 export async function buildModifyLiquidityArgsForRemoval(
   params: BuildModifyLiquidityArgsForRemovalParams,
 ): Promise<ModifyLiquidityArgs> {
@@ -598,6 +642,10 @@ export async function buildModifyLiquidityArgsForRemoval(
   return toModifyLiquidityArgs(computed);
 }
 
+/**
+ * Remove the same `percentageToRemove` from every bin that has position shares.
+ * When `bins` is omitted, discovers bins via `getPositionBinSharesRange(lowerBin, upperBin)`.
+ */
 export async function buildModifyLiquidityArgsForPercentageRemoval({
   publicClient,
   dataProviderAddress,
@@ -650,6 +698,7 @@ export async function buildModifyLiquidityArgsForPercentageRemoval({
   });
 }
 
+/** Convert positive `deltaShares` from a modify plan into `PoolLiquidityDelta` for the adder. */
 export function additionPlanToPoolLiquidityDelta(
   deltas: readonly LiquidityDelta[],
 ): PoolLiquidityDelta {
@@ -660,6 +709,7 @@ export function additionPlanToPoolLiquidityDelta(
   };
 }
 
+/** Convert negative `deltaShares` from a modify plan into burn `PoolLiquidityDelta` for `removeLiquidity`. */
 export function removalPlanToPoolLiquidityDelta(
   deltas: readonly LiquidityDelta[],
 ): PoolLiquidityDelta {
@@ -698,6 +748,19 @@ export function scaleWeightedPoolDeltasToFitCaps(params: {
   return { binIdxs: weights.binIdxs, shares };
 }
 
+/**
+ * Convenience wrapper: bin targets → adder-ready `{ salt, poolLiquidityDelta, maxAmountToken0, maxAmountToken1 }`.
+ *
+ * @example
+ * ```ts
+ * const add = await buildAddLiquidityExactSharesParamsFromBinTargets({
+ *   publicClient, factoryAddress, dataProviderAddress, poolAddress,
+ *   bins: [{ bin: 0, targetValueInToken: parseUnits("100", 6), targetValueInToken0: false }],
+ *   currentPriceX64: slot0.priceX64,
+ * });
+ * const data = encodeAddLiquidityExactSharesSelfCalldata({ pool: poolAddress, ...add });
+ * ```
+ */
 export async function buildAddLiquidityExactSharesParamsFromBinTargets(
   params: BuildModifyLiquidityArgsForAdditionParams,
 ): Promise<{
@@ -715,6 +778,27 @@ export async function buildAddLiquidityExactSharesParamsFromBinTargets(
   };
 }
 
+/** Cursor bounds that disable weighted-add cursor checks (matches on-chain test helpers). */
+export const UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS = {
+  minimalCurBin: -128,
+  minimalPosition: 0n,
+  maximalCurBin: 127,
+  maximalPosition: MAX_UINT104,
+} as const;
+
+export type LiquidityCursorBounds = {
+  minimalCurBin: number;
+  minimalPosition: bigint;
+  maximalCurBin: number;
+  maximalPosition: bigint;
+};
+
+/**
+ * Encode `LiquidityAdder.addLiquidityExactShares` for the transaction sender.
+ *
+ * Creates or increases the position `(msg.sender, salt)` — liquidity is credited to whoever
+ * sends the transaction. Approve both pool tokens on the LiquidityAdder before sending.
+ */
 export function encodeAddLiquidityExactSharesSelfCalldata(params: {
   pool: Address;
   salt: bigint;
@@ -737,6 +821,13 @@ export function encodeAddLiquidityExactSharesSelfCalldata(params: {
   });
 }
 
+/**
+ * Encode `LiquidityAdder.addLiquidityExactShares` for an explicit position owner.
+ *
+ * Creates or increases the position `(owner, salt)` while `msg.sender` pays for the deposit
+ * (e.g. router, vault, or meta-transaction relayer acting on behalf of `owner`).
+ * Approve both pool tokens on the LiquidityAdder before sending.
+ */
 export function encodeAddLiquidityExactSharesWithOwnerCalldata(params: {
   pool: Address;
   owner: Address;
@@ -761,6 +852,13 @@ export function encodeAddLiquidityExactSharesWithOwnerCalldata(params: {
   });
 }
 
+/**
+ * Encode weighted add for the transaction sender.
+ *
+ * `weightDeltas` are relative share weights; the adder scales to fit
+ * `maxAmountToken0` / `maxAmountToken1`. Use {@link scaleWeightedPoolDeltasToFitCaps} to pre-scale.
+ * Creates or increases the position `(msg.sender, salt)`.
+ */
 export function encodeAddLiquidityWeightedSelfCalldata(params: {
   pool: Address;
   salt: bigint;
@@ -782,15 +880,21 @@ export function encodeAddLiquidityWeightedSelfCalldata(params: {
       { binIdxs: [...params.weightDeltas.binIdxs], shares: [...params.weightDeltas.shares] },
       params.maxAmountToken0,
       params.maxAmountToken1,
-      params.minimalCurBin ?? -128,
-      params.minimalPosition ?? 0n,
-      params.maximalCurBin ?? 127,
-      params.maximalPosition ?? MAX_UINT104,
+      params.minimalCurBin ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.minimalCurBin,
+      params.minimalPosition ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.minimalPosition,
+      params.maximalCurBin ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.maximalCurBin,
+      params.maximalPosition ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.maximalPosition,
       params.extensionData ?? EMPTY_EXTENSION_DATA,
     ],
   });
 }
 
+/**
+ * Encode weighted add for an explicit position owner.
+ *
+ * Same as {@link encodeAddLiquidityWeightedSelfCalldata} but credits liquidity to `(owner, salt)`
+ * while `msg.sender` pays for the deposit.
+ */
 export function encodeAddLiquidityWeightedWithOwnerCalldata(params: {
   pool: Address;
   owner: Address;
@@ -814,15 +918,19 @@ export function encodeAddLiquidityWeightedWithOwnerCalldata(params: {
       { binIdxs: [...params.weightDeltas.binIdxs], shares: [...params.weightDeltas.shares] },
       params.maxAmountToken0,
       params.maxAmountToken1,
-      params.minimalCurBin ?? -128,
-      params.minimalPosition ?? 0n,
-      params.maximalCurBin ?? 127,
-      params.maximalPosition ?? MAX_UINT104,
+      params.minimalCurBin ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.minimalCurBin,
+      params.minimalPosition ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.minimalPosition,
+      params.maximalCurBin ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.maximalCurBin,
+      params.maximalPosition ?? UNCONSTRAINED_LIQUIDITY_CURSOR_BOUNDS.maximalPosition,
       params.extensionData ?? EMPTY_EXTENSION_DATA,
     ],
   });
 }
 
+/**
+ * Encode `Pool.removeLiquidity(owner, salt, deltas, extensionData)`.
+ * Send to the **pool** contract; no token approval required (tokens are sent out).
+ */
 export function encodeRemoveLiquidityCalldata(params: {
   owner: Address;
   salt: bigint;
@@ -841,6 +949,7 @@ export function encodeRemoveLiquidityCalldata(params: {
   });
 }
 
+/** Build `{ salt, poolLiquidityDelta }` for {@link encodeRemoveLiquidityCalldata}. */
 export async function buildRemoveLiquidityPoolDelta(
   params: BuildModifyLiquidityArgsForRemovalParams,
 ): Promise<{ salt: bigint; poolLiquidityDelta: PoolLiquidityDelta }> {

package/src/pool/nativeLiquidity.ts

@@ -0,0 +1,71 @@
+import type { Hex } from "viem";
+import {
+  encodeAddLiquidityExactSharesSelfCalldata,
+  encodeAddLiquidityExactSharesWithOwnerCalldata,
+  encodeAddLiquidityWeightedSelfCalldata,
+  encodeAddLiquidityWeightedWithOwnerCalldata,
+} from "./liquidity.js";
+import { encodeMulticallCalldata, encodeRefundETHCalldata } from "../peripheryPayments/index.js";
+
+type ExactSharesSelfParams = Parameters<typeof encodeAddLiquidityExactSharesSelfCalldata>[0];
+type ExactSharesWithOwnerParams = Parameters<
+  typeof encodeAddLiquidityExactSharesWithOwnerCalldata
+>[0];
+type WeightedSelfParams = Parameters<typeof encodeAddLiquidityWeightedSelfCalldata>[0];
+type WeightedWithOwnerParams = Parameters<typeof encodeAddLiquidityWeightedWithOwnerCalldata>[0];
+
+/**
+ * Exact-shares add with native ETH for the pool WETH leg.
+ * Credits liquidity to `(msg.sender, salt)`. Set `msg.value` on the transaction;
+ * unused ETH is refunded to the caller.
+ */
+export function prepareAddLiquidityExactSharesSelfSupportingNativePaymentCalldata(
+  params: ExactSharesSelfParams,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeAddLiquidityExactSharesSelfCalldata(params),
+    encodeRefundETHCalldata(),
+  ]);
+}
+
+/**
+ * Exact-shares add with native ETH for the pool WETH leg.
+ * Credits liquidity to `(owner, salt)` while `msg.sender` pays. Set `msg.value` on the
+ * transaction; unused ETH is refunded to the caller.
+ */
+export function prepareAddLiquidityExactSharesWithOwnerSupportingNativePaymentCalldata(
+  params: ExactSharesWithOwnerParams,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeAddLiquidityExactSharesWithOwnerCalldata(params),
+    encodeRefundETHCalldata(),
+  ]);
+}
+
+/**
+ * Weighted add with native ETH for the pool WETH leg.
+ * Credits liquidity to `(msg.sender, salt)`. Set `msg.value` on the transaction;
+ * unused ETH is refunded to the caller.
+ */
+export function prepareAddLiquidityWeightedSelfSupportingNativePaymentCalldata(
+  params: WeightedSelfParams,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeAddLiquidityWeightedSelfCalldata(params),
+    encodeRefundETHCalldata(),
+  ]);
+}
+
+/**
+ * Weighted add with native ETH for the pool WETH leg.
+ * Credits liquidity to `(owner, salt)` while `msg.sender` pays. Set `msg.value` on the
+ * transaction; unused ETH is refunded to the caller.
+ */
+export function prepareAddLiquidityWeightedWithOwnerSupportingNativePaymentCalldata(
+  params: WeightedWithOwnerParams,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeAddLiquidityWeightedWithOwnerCalldata(params),
+    encodeRefundETHCalldata(),
+  ]);
+}

package/src/router/fromRoute.ts

@@ -0,0 +1,318 @@
+/**
+ * Map route API POST /public/v1/evm/:chain_id/route responses to SimpleRouter swap params.
+ */
+
+import type { Address, Hex, PublicClient } from "viem";
+import { getAddress } from "viem";
+import { resolveSwapPath } from "../swap/path.js";
+import { ceilDiv, toSlippageBps } from "./swap.js";
+import type { ExactInputParams, ExactOutputParams } from "./swapPath.js";
+import type { ExactInputSingleParams, ExactOutputSingleParams } from "./swap.js";
+
+const BPS_BASE = 10_000n;
+
+/** Wire tradeType from the route API. */
+export type TradeType = "exact_in" | "exact_out";
+
+/** Wire routeType from the route API. */
+export type RouteType = "direct" | "one_hop";
+
+/** One hop in a route API response (RouteLegResponse). */
+export type RouteLegResponse = {
+  tradeType: TradeType;
+  poolAddress: string;
+  pair: string;
+  zeroForOne: boolean;
+  tokenIn: string;
+  tokenOut: string;
+  amountIn: string;
+  amountOut: string;
+  effectivePriceX64: string;
+  priceImpactE6: string;
+  priceLimitX64: string;
+};
+
+/** One execution path in a route API response (RouteOptionResponse). */
+export type RouteOptionResponse = {
+  tradeType: TradeType;
+  routeType: RouteType;
+  amountIn: string;
+  amountOut: string;
+  effectivePriceX64: string;
+  priceImpactE6: string;
+  legs: RouteLegResponse[];
+};
+
+/** Route API response (RouteResponse). */
+export type RouteResponse = {
+  tokenIn: string;
+  tokenOut: string;
+  tradeType: TradeType;
+  amountIn: string;
+  amountOut: string;
+  effectivePriceX64: string;
+  priceImpactBestRoute: string;
+  candidatesConsidered: number;
+  routes: RouteOptionResponse[];
+};
+
+export type PrepareExactInputFromRouteParams = {
+  publicClient: PublicClient;
+  route: RouteResponse;
+  recipient: Address;
+  deadline: bigint;
+  /** Human-readable slippage tolerance applied to the selected route's `amountOut`, e.g. `0.5` = 0.5%. */
+  slippagePercent: number;
+  extensionDatas?: readonly Hex[];
+};
+
+export type PrepareExactOutputFromRouteParams = {
+  publicClient: PublicClient;
+  route: RouteResponse;
+  recipient: Address;
+  deadline: bigint;
+  /** Human-readable slippage tolerance applied to the selected route's `amountIn`, e.g. `0.5` = 0.5%. */
+  slippagePercent: number;
+  extensionDatas?: readonly Hex[];
+};
+
+export type PreparedExactInputFromRoute =
+  | { kind: "single"; params: ExactInputSingleParams }
+  | { kind: "multihop"; params: ExactInputParams };
+
+export type PreparedExactOutputFromRoute =
+  | { kind: "single"; params: ExactOutputSingleParams }
+  | { kind: "multihop"; params: ExactOutputParams };
+
+function parseAddress(value: string, field: string): Address {
+  try {
+    return getAddress(value);
+  } catch {
+    throw new Error(`invalid ${field}: ${value}`);
+  }
+}
+
+function parseAmount(value: string, field: string): bigint {
+  try {
+    const amount = BigInt(value);
+    if (amount < 0n) {
+      throw new Error(`${field} must be non-negative`);
+    }
+    return amount;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("must be non-negative")) {
+      throw error;
+    }
+    throw new Error(`invalid ${field}: ${value}`, { cause: error });
+  }
+}
+
+function selectRouteOption(route: RouteResponse): RouteOptionResponse {
+  if (route.routes.length === 0) {
+    throw new Error("route.routes must not be empty");
+  }
+  if (route.routes.length > 1) {
+    throw new Error("route was split across multiple routes; re-request with maxRoutes=1");
+  }
+  return route.routes[0]!;
+}
+
+function assertTradeType(
+  route: RouteResponse,
+  option: RouteOptionResponse,
+  tradeType: TradeType,
+): void {
+  if (route.tradeType !== tradeType) {
+    throw new Error(
+      `route tradeType must be ${tradeType}; use ${
+        tradeType === "exact_in" ? "prepareExactOutputFromRoute" : "prepareExactInputFromRoute"
+      } for ${tradeType === "exact_in" ? "exact_out" : "exact_in"}`,
+    );
+  }
+  if (option.tradeType !== tradeType) {
+    throw new Error(`routes[0].tradeType must be ${tradeType}`);
+  }
+}
+
+function validateRouteLegs(
+  legs: RouteLegResponse[],
+  tokenIn: Address,
+  tokenOut: Address,
+): Address[] {
+  if (legs.length === 0) {
+    throw new Error("routes[0].legs must not be empty");
+  }
+
+  const pools: Address[] = [];
+  for (let i = 0; i < legs.length; i++) {
+    const leg = legs[i]!;
+    const legTokenIn = parseAddress(leg.tokenIn, `legs[${i}].tokenIn`);
+    const legTokenOut = parseAddress(leg.tokenOut, `legs[${i}].tokenOut`);
+    pools.push(parseAddress(leg.poolAddress, `legs[${i}].poolAddress`));
+
+    if (i === 0 && legTokenIn !== tokenIn) {
+      throw new Error(`legs[0].tokenIn (${legTokenIn}) does not match route.tokenIn (${tokenIn})`);
+    }
+    if (i === legs.length - 1 && legTokenOut !== tokenOut) {
+      throw new Error(
+        `legs[${i}].tokenOut (${legTokenOut}) does not match route.tokenOut (${tokenOut})`,
+      );
+    }
+    if (i > 0) {
+      const prevLegTokenOut = parseAddress(legs[i - 1]!.tokenOut, `legs[${i - 1}].tokenOut`);
+      if (legTokenIn !== prevLegTokenOut) {
+        throw new Error(
+          `legs[${i}].tokenIn (${legTokenIn}) does not connect to legs[${i - 1}].tokenOut (${prevLegTokenOut})`,
+        );
+      }
+    }
+  }
+
+  return pools;
+}
+
+function amountOutMinimumFromRoute(amountOut: bigint, slippagePercent: number): bigint {
+  const slippageBps = toSlippageBps(slippagePercent);
+  return (amountOut * (BPS_BASE - slippageBps)) / BPS_BASE;
+}
+
+function amountInMaximumFromRoute(amountIn: bigint, slippagePercent: number): bigint {
+  const slippageBps = toSlippageBps(slippagePercent);
+  return ceilDiv(amountIn * (BPS_BASE + slippageBps), BPS_BASE);
+}
+
+/**
+ * Convert a route API exact-in response into SimpleRouter exact-input swap params.
+ *
+ * Resolves swap direction on-chain, applies slippage to the quoted `amountOut`, and
+ * returns params ready for `encodeExactInputSingleCalldata` or `encodeExactInputCalldata`.
+ */
+export async function routeToExactInputParams(
+  params: PrepareExactInputFromRouteParams,
+): Promise<PreparedExactInputFromRoute> {
+  const { route, publicClient, recipient, deadline, slippagePercent, extensionDatas } = params;
+
+  const tokenIn = parseAddress(route.tokenIn, "tokenIn");
+  const tokenOut = parseAddress(route.tokenOut, "tokenOut");
+  const option = selectRouteOption(route);
+  assertTradeType(route, option, "exact_in");
+
+  const requestedAmountIn = parseAmount(route.amountIn, "amountIn");
+  const amountIn = parseAmount(option.amountIn, "routes[0].amountIn");
+  if (amountIn !== requestedAmountIn) {
+    throw new Error(
+      "routes[0].amountIn does not match request amountIn; partial fill is not supported",
+    );
+  }
+  const quotedAmountOut = parseAmount(option.amountOut, "routes[0].amountOut");
+  const amountOutMinimum = amountOutMinimumFromRoute(quotedAmountOut, slippagePercent);
+
+  const pools = validateRouteLegs(option.legs, tokenIn, tokenOut);
+  const {
+    tokens,
+    zeroForOnes,
+    extensionDatas: resolvedExtensionDatas,
+    zeroForOneBitMap,
+  } = await resolveSwapPath(publicClient, tokenIn, tokenOut, pools, extensionDatas);
+
+  if (pools.length === 1) {
+    const leg = option.legs[0]!;
+    return {
+      kind: "single",
+      params: {
+        pool: pools[0]!,
+        tokenIn,
+        tokenOut,
+        zeroForOne: zeroForOnes[0]!,
+        amountIn,
+        amountOutMinimum,
+        recipient,
+        deadline,
+        priceLimitX64: parseAmount(leg.priceLimitX64, "legs[0].priceLimitX64"),
+        extensionData: resolvedExtensionDatas[0],
+      },
+    };
+  }
+
+  return {
+    kind: "multihop",
+    params: {
+      tokens,
+      pools,
+      extensionDatas: resolvedExtensionDatas,
+      zeroForOneBitMap,
+      amountIn,
+      amountOutMinimum,
+      recipient,
+      deadline,
+    },
+  };
+}
+
+/**
+ * Convert a route API exact-out response into SimpleRouter exact-output swap params.
+ *
+ * Resolves swap direction on-chain, applies slippage to the quoted `amountIn`, and
+ * returns params ready for `encodeExactOutputSingleCalldata` or `encodeExactOutputCalldata`.
+ */
+export async function routeToExactOutputParams(
+  params: PrepareExactOutputFromRouteParams,
+): Promise<PreparedExactOutputFromRoute> {
+  const { route, publicClient, recipient, deadline, slippagePercent, extensionDatas } = params;
+
+  const tokenIn = parseAddress(route.tokenIn, "tokenIn");
+  const tokenOut = parseAddress(route.tokenOut, "tokenOut");
+  const option = selectRouteOption(route);
+  assertTradeType(route, option, "exact_out");
+
+  const requestedAmountOut = parseAmount(route.amountOut, "amountOut");
+  const amountOut = parseAmount(option.amountOut, "routes[0].amountOut");
+  if (amountOut !== requestedAmountOut) {
+    throw new Error(
+      "routes[0].amountOut does not match request amountOut; partial fill is not supported",
+    );
+  }
+  const quotedAmountIn = parseAmount(option.amountIn, "routes[0].amountIn");
+  const amountInMaximum = amountInMaximumFromRoute(quotedAmountIn, slippagePercent);
+
+  const pools = validateRouteLegs(option.legs, tokenIn, tokenOut);
+  const {
+    tokens,
+    zeroForOnes,
+    extensionDatas: resolvedExtensionDatas,
+    zeroForOneBitMap,
+  } = await resolveSwapPath(publicClient, tokenIn, tokenOut, pools, extensionDatas);
+
+  if (pools.length === 1) {
+    const leg = option.legs[0]!;
+    return {
+      kind: "single",
+      params: {
+        pool: pools[0]!,
+        tokenIn,
+        tokenOut,
+        zeroForOne: zeroForOnes[0]!,
+        amountOut,
+        amountInMaximum,
+        recipient,
+        deadline,
+        priceLimitX64: parseAmount(leg.priceLimitX64, "legs[0].priceLimitX64"),
+        extensionData: resolvedExtensionDatas[0],
+      },
+    };
+  }
+
+  return {
+    kind: "multihop",
+    params: {
+      tokens,
+      pools,
+      extensionDatas: resolvedExtensionDatas,
+      zeroForOneBitMap,
+      amountOut,
+      amountInMaximum,
+      recipient,
+      deadline,
+    },
+  };
+}