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

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 "../peripheryPayments/index.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 "../peripheryPayments/index.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;

package/src/router/swapPath.ts

@@ -1,6 +1,10 @@
 /**
- * MetricAMM SDK - SimpleRouter multihop swap helpers.
+ * SimpleRouter multihop swap helpers.
+ *
+ * Multihop swaps walk `pools` in order; intermediate tokens remain on the router between hops.
+ * For ERC-20 paths, approve the router for `tokenIn` once before sending the transaction.
  */
+
 import type { Address, Hex, PublicClient } from "viem";
 import { encodeFunctionData } from "viem";
 import { quoteLiveExactIn, quoteLiveExactOut } from "../quoter/quotePath.js";
@@ -10,10 +14,18 @@ import { ceilDiv, toSlippageBps } from "./swap.js";
 
 const BPS_BASE = 10_000n;
 
+/**
+ * Arguments for `MetricOmmSimpleRouter.exactInput` (multihop exact input).
+ * `tokens` and `zeroForOneBitMap` are usually produced by {@link buildExactInputParams}.
+ */
 export type ExactInputParams = {
+  /** Path tokens, length `pools.length + 1`. */
   tokens: Address[];
+  /** One pool per hop, in swap order. */
   pools: Address[];
+  /** Extension calldata per hop; use `0x` when a pool has no extension. */
   extensionDatas: Hex[];
+  /** Bit `i` set when hop `i` is token0 → token1. */
   zeroForOneBitMap: bigint;
   amountIn: bigint;
   amountOutMinimum: bigint;
@@ -21,6 +33,7 @@ export type ExactInputParams = {
   deadline: bigint;
 };
 
+/** Arguments for `MetricOmmSimpleRouter.exactOutput` (multihop exact output). */
 export type ExactOutputParams = {
   tokens: Address[];
   pools: Address[];
@@ -32,10 +45,12 @@ export type ExactOutputParams = {
   deadline: bigint;
 };
 
+/** Inputs for {@link buildExactInputParams}. */
 export interface BuildExactInputParams {
   publicClient: PublicClient;
   tokenIn: Address;
   tokenOut: Address;
+  /** Ordered pool addresses connecting `tokenIn` → `tokenOut`. */
   pools: readonly Address[];
   extensionDatas?: readonly Hex[];
   recipient: Address;
@@ -43,8 +58,10 @@ export interface BuildExactInputParams {
   slippagePercent: number;
   deadline: bigint;
   quoterAddress?: Address;
+  wrappedNative?: Address;
 }
 
+/** Inputs for {@link buildExactOutputParams}. */
 export interface BuildExactOutputParams {
   publicClient: PublicClient;
   tokenIn: Address;
@@ -56,6 +73,7 @@ export interface BuildExactOutputParams {
   slippagePercent: number;
   deadline: bigint;
   quoterAddress?: Address;
+  wrappedNative?: Address;
 }
 
 function toExactInputStruct(params: ExactInputParams) {
@@ -84,6 +102,29 @@ function toExactOutputStruct(params: ExactOutputParams) {
   };
 }
 
+/**
+ * Build multihop exact-input params: resolves path, quotes output, applies slippage.
+ *
+ * @example
+ * ```ts
+ * const pathParams = await buildExactInputParams({
+ *   publicClient,
+ *   tokenIn: tokenA,
+ *   tokenOut: tokenC,
+ *   pools: [poolAB, poolBC],
+ *   recipient: account,
+ *   amountIn: parseUnits("1", 18),
+ *   slippagePercent: 0.5,
+ *   deadline,
+ *   quoterAddress: addresses.quoter,
+ * });
+ * await walletClient.sendTransaction({
+ *   to: addresses.simpleRouter,
+ *   data: encodeExactInputCalldata(pathParams),
+ *   account,
+ * });
+ * ```
+ */
 export async function buildExactInputParams(
   params: BuildExactInputParams,
 ): Promise<ExactInputParams> {
@@ -121,6 +162,7 @@ export async function buildExactInputParams(
   };
 }
 
+/** Build multihop exact-output params with live quote and slippage on `amountInMaximum`. */
 export async function buildExactOutputParams(
   params: BuildExactOutputParams,
 ): Promise<ExactOutputParams> {
@@ -158,6 +200,7 @@ export async function buildExactOutputParams(
   };
 }
 
+/** Encode `exactInput` multihop calldata. */
 export function encodeExactInputCalldata(params: ExactInputParams): Hex {
   return encodeFunctionData({
     abi: SIMPLE_ROUTER_ABI,
@@ -166,8 +209,10 @@ export function encodeExactInputCalldata(params: ExactInputParams): Hex {
   });
 }
 
+/** Alias for {@link encodeExactInputCalldata}. */
 export const prepareExactInputCalldata = encodeExactInputCalldata;
 
+/** Encode `exactOutput` multihop calldata. */
 export function encodeExactOutputCalldata(params: ExactOutputParams): Hex {
   return encodeFunctionData({
     abi: SIMPLE_ROUTER_ABI,
@@ -176,6 +221,7 @@ export function encodeExactOutputCalldata(params: ExactOutputParams): Hex {
   });
 }
 
+/** Alias for {@link encodeExactOutputCalldata}. */
 export const prepareExactOutputCalldata = encodeExactOutputCalldata;
 
 export { encodeZeroForOneBitMap } from "../swap/path.js";