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

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,
+    },
+  };
+}

package/src/router/index.ts

@@ -1,5 +1,9 @@
 /**
- * MetricAMM SDK - Router Functions
+ * SimpleRouter swap API — quotes, calldata encoding, and native ETH multicall helpers.
+ *
+ * **ERC-20 swap:** `buildExactInputSingleParams` → `encodeExactInputSingleCalldata` → send to `simpleRouter`.
+
+ * Approve `tokenIn` on the router for ERC-20 input (not required for ETH input).
  */
 
 export {
@@ -28,3 +32,34 @@ export {
   type BuildExactInputSingleParams,
   type BuildExactOutputSingleParams,
 } from "./swap.js";
+
+export {
+  routeToExactInputParams as prepareExactInputFromRoute,
+  routeToExactOutputParams as prepareExactOutputFromRoute,
+  type TradeType,
+  type RouteType,
+  type RouteLegResponse,
+  type RouteOptionResponse,
+  type RouteResponse,
+  type PrepareExactInputFromRouteParams,
+  type PrepareExactOutputFromRouteParams,
+  type PreparedExactInputFromRoute,
+  type PreparedExactOutputFromRoute,
+} from "./fromRoute.js";
+
+export {
+  encodeMulticallCalldata,
+  encodeRefundETHCalldata,
+  encodeUnwrapWETH9Calldata,
+} from "./utils.js";
+
+export {
+  prepareExactInputSingleAndUnwrapCalldata,
+  prepareExactInputAndUnwrapCalldata,
+  prepareExactInputSingleSupportingNativePaymentCalldata,
+  prepareExactInputSupportingNativePaymentCalldata,
+  prepareExactOutputSupportingNativePaymentCalldata,
+  prepareExactOutputSingleSupportingNativePaymentCalldata,
+  prepareExactOutputSingleAndUnwrapCalldata,
+  prepareExactOutputAndUnwrapCalldata,
+} from "./nativeSwap.js";

package/src/router/nativeSwap.ts

@@ -0,0 +1,123 @@
+import type { Address, Hex } from "viem";
+import type { ExactInputParams, ExactOutputParams } from "./swapPath.js";
+import type { ExactInputSingleParams, ExactOutputSingleParams } from "./swap.js";
+import { encodeExactInputSingleCalldata, encodeExactOutputSingleCalldata } from "./swap.js";
+import { encodeExactInputCalldata, encodeExactOutputCalldata } from "./swapPath.js";
+import {
+  encodeMulticallCalldata,
+  encodeRefundETHCalldata,
+  encodeUnwrapWETH9Calldata,
+} from "./utils.js";
+
+function withRouterRecipient<T extends { recipient: Address }>(
+  params: T,
+  simpleRouter: Address,
+): T {
+  return { ...params, recipient: simpleRouter };
+}
+
+/** Single-hop exact input when `tokenIn` is wrappedNative - `tokenIn` MUST be wrappedNative.
+ * Set `msg.value` to a value that you want to pay with native ETH on the transaction.
+ * The remaining amount will be paid with wrappedNative (if it is approved, otherwise it will revert).
+ * Any unused native ETH will be refunded to the caller.
+ */
+export function prepareExactInputSingleSupportingNativePaymentCalldata(
+  params: ExactInputSingleParams,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeExactInputSingleCalldata(params),
+    // Refund is needed because it is possible (vary rare) that the router will not consume whole amountIn while still output the required amountOutMinimum.
+    encodeRefundETHCalldata(),
+  ]);
+}
+
+/** Multihop exact input when the first token is wrappedNative - `tokenIn` MUST be wrappedNative.
+ * Set `msg.value` to a value that you want to pay with native ETH on the transaction.
+ * The remaining amount will be paid with wrappedNative (if it is approved, otherwise it will revert).
+ * Any unused native ETH will be refunded to the caller.
+ */
+export function prepareExactInputSupportingNativePaymentCalldata(params: ExactInputParams): Hex {
+  return encodeMulticallCalldata([
+    encodeExactInputCalldata(params),
+    // Refund is needed because it is possible (vary rare) that the router will not consume whole amountIn while still output the required amountOutMinimum.
+    encodeRefundETHCalldata(),
+  ]);
+}
+
+/** Single-hop exact output when `tokenIn` is wrappedNative - `tokenIn` MUST be wrappedNative.
+ * Set `msg.value` to a value that you want to pay with native ETH on the transaction.
+ * The remaining amount will be paid with wrappedNative (if it is approved, otherwise it will revert)
+ * Any unused native ETH will be refunded to the caller.
+ *  */
+export function prepareExactOutputSingleSupportingNativePaymentCalldata(
+  params: ExactOutputSingleParams,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeExactOutputSingleCalldata(params),
+    encodeRefundETHCalldata(),
+  ]);
+}
+
+/** Multihop exact output when the first token is wrappedNative - `tokenIn` MUST be wrappedNative.
+ * Set `msg.value` to a value that you want to pay with native ETH on the transaction.
+ * The remaining amount will be paid with wrappedNative (if it is approved, otherwise it will revert)
+ * Any unused native ETH will be refunded to the caller.
+ *  */
+export function prepareExactOutputSupportingNativePaymentCalldata(params: ExactOutputParams): Hex {
+  return encodeMulticallCalldata([encodeExactOutputCalldata(params), encodeRefundETHCalldata()]);
+}
+
+/**
+ * Single-hop exact input with ETH output — `tokenOut` MUST be wrappedNative.
+ * Unwraps the whole amount of wrappedNative to native ETH and sends it to the recipient.
+ */
+export function prepareExactInputSingleAndUnwrapCalldata(
+  params: ExactInputSingleParams,
+  simpleRouter: Address,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeExactInputSingleCalldata(withRouterRecipient(params, simpleRouter)),
+    encodeUnwrapWETH9Calldata(params.amountOutMinimum, params.recipient),
+  ]);
+}
+
+/** Multihop exact input with ETH output - `tokenOut` MUST be wrappedNative.
+ * Unwraps the whole amount of wrappedNative to native ETH and sends it to the recipient.
+ *  */
+export function prepareExactInputAndUnwrapCalldata(
+  params: ExactInputParams,
+  simpleRouter: Address,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeExactInputCalldata(withRouterRecipient(params, simpleRouter)),
+    encodeUnwrapWETH9Calldata(params.amountOutMinimum, params.recipient),
+  ]);
+}
+
+/**
+ * Single-hop exact output with ETH output — `tokenOut` MUST be wrappedNative.
+ * Unwraps the whole amount of wrappedNative to native ETH and sends it to the recipient.
+ */
+export function prepareExactOutputSingleAndUnwrapCalldata(
+  params: ExactOutputSingleParams,
+  simpleRouter: Address,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeExactOutputSingleCalldata(withRouterRecipient(params, simpleRouter)),
+    encodeUnwrapWETH9Calldata(params.amountOut, params.recipient),
+  ]);
+}
+
+/**
+ * Multihop exact output with ETH output — `tokenOut` MUST be wrappedNative.
+ * Unwraps the whole amount of wrappedNative to native ETH and sends it to the recipient.
+ */
+export function prepareExactOutputAndUnwrapCalldata(
+  params: ExactOutputParams,
+  simpleRouter: Address,
+): Hex {
+  return encodeMulticallCalldata([
+    encodeExactOutputCalldata(withRouterRecipient(params, simpleRouter)),
+    encodeUnwrapWETH9Calldata(params.amountOut, params.recipient),
+  ]);
+}

package/src/router/swap.ts

@@ -1,5 +1,10 @@
 /**
- * MetricAMM SDK - SimpleRouter single-hop swap helpers.
+ * SimpleRouter single-hop swap helpers.
+ *
+ * Typical ERC-20 flow:
+ * 1. `buildExactInputSingleParams` / `buildExactOutputSingleParams` — quote + slippage
+ * 2. `encodeExactInputSingleCalldata` — calldata for `walletClient.writeContract` or `sendTransaction`
+ * 3. Approve `tokenIn` on the SimpleRouter before sending (not needed for native ETH; see `nativeSwap.ts`)
  */
 
 import type { Address, Hex } from "viem";
@@ -13,25 +18,44 @@ import type { PublicClient } from "viem";
 
 const BPS_BASE = 10_000n;
 
+/**
+ * Arguments for `MetricOmmSimpleRouter.exactInputSingle`.
+ * Pass to `encodeExactInputSingleCalldata` or native prepare helpers when `tokenIn` is WETH.
+ */
 export type ExactInputSingleParams = {
+  /** Pool to swap through. */
   pool: Address;
+  /** Input token (`addresses.wrappedNative` when swapping from native ETH). */
   tokenIn: Address;
+  /** Output token (`addresses.wrappedNative` when unwrapping to ETH in a follow-up call). */
   tokenOut: Address;
+  /** `true` when swapping token0 → token1 for this pool. */
   zeroForOne: boolean;
+  /** Exact input amount in `tokenIn` native decimals. */
   amountIn: bigint;
+  /** Minimum acceptable output; reverts if less is received. */
   amountOutMinimum: bigint;
+  /** Address that receives output tokens. */
   recipient: Address;
+  /** Unix timestamp after which the swap reverts. */
   deadline: bigint;
+  /** Q64.64 price bound; use `0` / `MAX_UINT128` defaults from builders when unsure. */
   priceLimitX64: bigint;
+  /** Per-pool extension calldata; omit for pools without extensions. */
   extensionData?: Hex;
 };
 
+/**
+ * Arguments for `MetricOmmSimpleRouter.exactOutputSingle`.
+ */
 export type ExactOutputSingleParams = {
   pool: Address;
   tokenIn: Address;
   tokenOut: Address;
   zeroForOne: boolean;
+  /** Exact output amount in `tokenOut` native decimals. */
   amountOut: bigint;
+  /** Maximum input willing to spend (slippage cap). */
   amountInMaximum: bigint;
   recipient: Address;
   deadline: bigint;
@@ -39,20 +63,31 @@ export type ExactOutputSingleParams = {
   extensionData?: Hex;
 };
 
+/**
+ * Inputs for {@link buildExactInputSingleParams}.
+ * Quotes live on-chain via the SwapQuoter and applies `slippagePercent` to derive `amountOutMinimum`.
+ */
 export interface BuildExactInputSingleParams {
   publicClient: PublicClient;
   pool: Address;
   tokenIn: Address;
   tokenOut: Address;
   recipient: Address;
+  /** Input amount in `tokenIn` decimals (wei for ETH / WETH). */
   amountIn: bigint;
+  /** Human-readable slippage tolerance, e.g. `0.5` = 0.5%. */
   slippagePercent: number;
+  /** Optional price bound; defaults from quoter direction when omitted. */
   priceLimitX64?: bigint;
   deadline: bigint;
   extensionData?: Hex;
+  /** Override when `addresses.quoter` is unset. */
   quoterAddress?: Address;
+  /** `addresses.wrappedNative` — required when `tokenIn` or `tokenOut` is native (zero address). */
+  wrappedNative?: Address;
 }
 
+/** Inputs for {@link buildExactOutputSingleParams}. */
 export interface BuildExactOutputSingleParams {
   publicClient: PublicClient;
   pool: Address;
@@ -65,8 +100,13 @@ export interface BuildExactOutputSingleParams {
   deadline: bigint;
   extensionData?: Hex;
   quoterAddress?: Address;
+  wrappedNative?: Address;
 }
 
+/**
+ * Convert a human slippage percent to basis points (1 bp = 0.01%).
+ * @example toSlippageBps(0.5) // 50n
+ */
 export function toSlippageBps(slippagePercent: number): bigint {
   if (!Number.isFinite(slippagePercent) || slippagePercent < 0 || slippagePercent > 100) {
     throw new Error("slippagePercent must be a finite number between 0 and 100");
@@ -74,6 +114,7 @@ export function toSlippageBps(slippagePercent: number): bigint {
   return BigInt(Math.round(slippagePercent * 100));
 }
 
+/** Ceiling division for bigint values. Used when rounding slippage up on exact-output swaps. */
 export function ceilDiv(numerator: bigint, denominator: bigint): bigint {
   if (denominator <= 0n) {
     throw new Error("denominator must be > 0");
@@ -115,6 +156,35 @@ function toExactOutputSingleStruct(params: ExactOutputSingleParams) {
   };
 }
 
+/**
+ * Build single-hop exact-input swap params with live quote and slippage.
+ *
+ * Resolves `zeroForOne`, quotes `amountOut`, and sets `amountOutMinimum`.
+ * For native ETH input, use `prepareExactInputSingleSupportingNativePaymentCalldata` and set `msg.value` on the transaction.
+ * (params will contain WETH as `tokenIn`).
+ *
+ * @example
+ * ```ts
+ * const params = await buildExactInputSingleParams({
+ *   publicClient,
+ *   pool,
+ *   tokenIn: usdc,
+ *   tokenOut: weth,
+ *   recipient: account,
+ *   amountIn: parseUnits("100", 6),
+ *   slippagePercent: 0.5,
+ *   deadline: BigInt(Math.floor(Date.now() / 1000) + 1200),
+ *   quoterAddress: addresses.quoter,
+ * });
+ * await walletClient.writeContract({
+ *   address: addresses.simpleRouter,
+ *   abi: MetricOmmSimpleRouterAbi,
+ *   functionName: "exactInputSingle",
+ *   args: [params],
+ *   account,
+ * });
+ * ```
+ */
 export async function buildExactInputSingleParams(
   params: BuildExactInputSingleParams,
 ): Promise<ExactInputSingleParams> {
@@ -157,6 +227,10 @@ export async function buildExactInputSingleParams(
   };
 }
 
+/**
+ * Build single-hop exact-output swap params with live quote and slippage.
+ * Sets `amountInMaximum` from quoted input plus `slippagePercent`.
+ */
 export async function buildExactOutputSingleParams(
   params: BuildExactOutputSingleParams,
 ): Promise<ExactOutputSingleParams> {
@@ -199,6 +273,10 @@ export async function buildExactOutputSingleParams(
   };
 }
 
+/**
+ * Encode `exactInputSingle` calldata for `addresses.simpleRouter`.
+ * Approve `tokenIn` on the router before sending (unless using native ETH prepare helpers).
+ */
 export function encodeExactInputSingleCalldata(params: ExactInputSingleParams): Hex {
   return encodeFunctionData({
     abi: SIMPLE_ROUTER_ABI,
@@ -207,8 +285,10 @@ export function encodeExactInputSingleCalldata(params: ExactInputSingleParams):
   });
 }
 
+/** Alias for {@link encodeExactInputSingleCalldata}. */
 export const prepareExactInputSingleCalldata = encodeExactInputSingleCalldata;
 
+/** Encode `exactOutputSingle` calldata for `addresses.simpleRouter`. */
 export function encodeExactOutputSingleCalldata(params: ExactOutputSingleParams): Hex {
   return encodeFunctionData({
     abi: SIMPLE_ROUTER_ABI,
@@ -217,4 +297,5 @@ export function encodeExactOutputSingleCalldata(params: ExactOutputSingleParams)
   });
 }
 
+/** Alias for {@link encodeExactOutputSingleCalldata}. */
 export const prepareExactOutputSingleCalldata = encodeExactOutputSingleCalldata;