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

package/dist/router/fromRoute.js

@@ -0,0 +1,187 @@
+/**
+ * Map route API POST /public/v1/evm/:chain_id/route responses to SimpleRouter swap params.
+ */
+import { getAddress } from "viem";
+import { resolveSwapPath } from "../swap/path.js";
+import { ceilDiv, toSlippageBps } from "./swap.js";
+const BPS_BASE = 10000n;
+function parseAddress(value, field) {
+    try {
+        return getAddress(value);
+    }
+    catch {
+        throw new Error(`invalid ${field}: ${value}`);
+    }
+}
+function parseAmount(value, field) {
+    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) {
+    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, option, tradeType) {
+    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, tokenIn, tokenOut) {
+    if (legs.length === 0) {
+        throw new Error("routes[0].legs must not be empty");
+    }
+    const pools = [];
+    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, slippagePercent) {
+    const slippageBps = toSlippageBps(slippagePercent);
+    return (amountOut * (BPS_BASE - slippageBps)) / BPS_BASE;
+}
+function amountInMaximumFromRoute(amountIn, slippagePercent) {
+    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) {
+    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) {
+    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,
+        },
+    };
+}
+//# sourceMappingURL=fromRoute.js.map

package/dist/router/fromRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fromRoute.js","sourceRoot":"","sources":["../../src/router/fromRoute.ts"],"names":[],"mappings":"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"}

package/dist/router/index.d.ts

@@ -1,6 +1,13 @@
 /**
- * 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 { buildExactInputParams, buildExactOutputParams, encodeExactInputCalldata, encodeExactOutputCalldata, encodeZeroForOneBitMap, prepareExactInputCalldata, prepareExactOutputCalldata, type ExactInputParams, type ExactOutputParams, type BuildExactInputParams, type BuildExactOutputParams, } from "./swapPath.js";
 export { buildExactInputSingleParams, buildExactOutputSingleParams, encodeExactInputSingleCalldata, encodeExactOutputSingleCalldata, prepareExactInputSingleCalldata, prepareExactOutputSingleCalldata, type ExactInputSingleParams, type ExactOutputSingleParams, 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,gCAAgC,EAChC,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,GAClC,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,gCAAgC,EAChC,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,GAClC,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,uBAAuB,IAAI,0BAA0B,EACrD,wBAAwB,IAAI,2BAA2B,EACvD,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,gCAAgC,EACrC,KAAK,iCAAiC,EACtC,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,GAClC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,wCAAwC,EACxC,kCAAkC,EAClC,sDAAsD,EACtD,gDAAgD,EAChD,iDAAiD,EACjD,uDAAuD,EACvD,yCAAyC,EACzC,mCAAmC,GACpC,MAAM,iBAAiB,CAAC"}

package/dist/router/index.js

@@ -1,6 +1,13 @@
 /**
- * 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 { buildExactInputParams, buildExactOutputParams, encodeExactInputCalldata, encodeExactOutputCalldata, encodeZeroForOneBitMap, prepareExactInputCalldata, prepareExactOutputCalldata, } from "./swapPath.js";
 export { buildExactInputSingleParams, buildExactOutputSingleParams, encodeExactInputSingleCalldata, encodeExactOutputSingleCalldata, prepareExactInputSingleCalldata, prepareExactOutputSingleCalldata, } from "./swap.js";
+export { routeToExactInputParams as prepareExactInputFromRoute, routeToExactOutputParams as prepareExactOutputFromRoute, } from "./fromRoute.js";
+export { encodeMulticallCalldata, encodeRefundETHCalldata, encodeUnwrapWETH9Calldata, } from "../peripheryPayments/index.js";
+export { prepareExactInputSingleAndUnwrapCalldata, prepareExactInputAndUnwrapCalldata, prepareExactInputSingleSupportingNativePaymentCalldata, prepareExactInputSupportingNativePaymentCalldata, prepareExactOutputSupportingNativePaymentCalldata, prepareExactOutputSingleSupportingNativePaymentCalldata, prepareExactOutputSingleAndUnwrapCalldata, prepareExactOutputAndUnwrapCalldata, } from "./nativeSwap.js";
 //# sourceMappingURL=index.js.map

package/dist/router/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,GAK3B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,gCAAgC,GAKjC,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,GAK3B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,EAC/B,+BAA+B,EAC/B,gCAAgC,GAKjC,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,uBAAuB,IAAI,0BAA0B,EACrD,wBAAwB,IAAI,2BAA2B,GAUxD,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,wCAAwC,EACxC,kCAAkC,EAClC,sDAAsD,EACtD,gDAAgD,EAChD,iDAAiD,EACjD,uDAAuD,EACvD,yCAAyC,EACzC,mCAAmC,GACpC,MAAM,iBAAiB,CAAC"}

package/dist/router/nativeSwap.d.ts

@@ -0,0 +1,47 @@
+import type { Address, Hex } from "viem";
+import type { ExactInputParams, ExactOutputParams } from "./swapPath.js";
+import type { ExactInputSingleParams, ExactOutputSingleParams } from "./swap.js";
+/** 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 declare function prepareExactInputSingleSupportingNativePaymentCalldata(params: ExactInputSingleParams): Hex;
+/** 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 declare function prepareExactInputSupportingNativePaymentCalldata(params: ExactInputParams): Hex;
+/** 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 declare function prepareExactOutputSingleSupportingNativePaymentCalldata(params: ExactOutputSingleParams): Hex;
+/** 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 declare function prepareExactOutputSupportingNativePaymentCalldata(params: ExactOutputParams): Hex;
+/**
+ * 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 declare function prepareExactInputSingleAndUnwrapCalldata(params: ExactInputSingleParams, simpleRouter: Address): Hex;
+/** 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 declare function prepareExactInputAndUnwrapCalldata(params: ExactInputParams, simpleRouter: Address): Hex;
+/**
+ * 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 declare function prepareExactOutputSingleAndUnwrapCalldata(params: ExactOutputSingleParams, simpleRouter: Address): Hex;
+/**
+ * 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 declare function prepareExactOutputAndUnwrapCalldata(params: ExactOutputParams, simpleRouter: Address): Hex;
+//# sourceMappingURL=nativeSwap.d.ts.map

package/dist/router/nativeSwap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeSwap.d.ts","sourceRoot":"","sources":["../../src/router/nativeSwap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAgBjF;;;;GAIG;AACH,wBAAgB,sDAAsD,CACpE,MAAM,EAAE,sBAAsB,GAC7B,GAAG,CAML;AAED;;;;GAIG;AACH,wBAAgB,gDAAgD,CAAC,MAAM,EAAE,gBAAgB,GAAG,GAAG,CAM9F;AAED;;;;MAIM;AACN,wBAAgB,uDAAuD,CACrE,MAAM,EAAE,uBAAuB,GAC9B,GAAG,CAKL;AAED;;;;MAIM;AACN,wBAAgB,iDAAiD,CAAC,MAAM,EAAE,iBAAiB,GAAG,GAAG,CAEhG;AAED;;;GAGG;AACH,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,sBAAsB,EAC9B,YAAY,EAAE,OAAO,GACpB,GAAG,CAKL;AAED;;MAEM;AACN,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,OAAO,GACpB,GAAG,CAKL;AAED;;;GAGG;AACH,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,uBAAuB,EAC/B,YAAY,EAAE,OAAO,GACpB,GAAG,CAKL;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,OAAO,GACpB,GAAG,CAKL"}

package/dist/router/nativeSwap.js

@@ -0,0 +1,89 @@
+import { encodeExactInputSingleCalldata, encodeExactOutputSingleCalldata } from "./swap.js";
+import { encodeExactInputCalldata, encodeExactOutputCalldata } from "./swapPath.js";
+import { encodeMulticallCalldata, encodeRefundETHCalldata, encodeUnwrapWETH9Calldata, } from "../peripheryPayments/index.js";
+function withRouterRecipient(params, simpleRouter) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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, simpleRouter) {
+    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, simpleRouter) {
+    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, simpleRouter) {
+    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, simpleRouter) {
+    return encodeMulticallCalldata([
+        encodeExactOutputCalldata(withRouterRecipient(params, simpleRouter)),
+        encodeUnwrapWETH9Calldata(params.amountOut, params.recipient),
+    ]);
+}
+//# sourceMappingURL=nativeSwap.js.map

package/dist/router/nativeSwap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeSwap.js","sourceRoot":"","sources":["../../src/router/nativeSwap.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,8BAA8B,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5F,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,+BAA+B,CAAC;AAEvC,SAAS,mBAAmB,CAC1B,MAAS,EACT,YAAqB;IAErB,OAAO,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sDAAsD,CACpE,MAA8B;IAE9B,OAAO,uBAAuB,CAAC;QAC7B,8BAA8B,CAAC,MAAM,CAAC;QACtC,wJAAwJ;QACxJ,uBAAuB,EAAE;KAC1B,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gDAAgD,CAAC,MAAwB;IACvF,OAAO,uBAAuB,CAAC;QAC7B,wBAAwB,CAAC,MAAM,CAAC;QAChC,wJAAwJ;QACxJ,uBAAuB,EAAE;KAC1B,CAAC,CAAC;AACL,CAAC;AAED;;;;MAIM;AACN,MAAM,UAAU,uDAAuD,CACrE,MAA+B;IAE/B,OAAO,uBAAuB,CAAC;QAC7B,+BAA+B,CAAC,MAAM,CAAC;QACvC,uBAAuB,EAAE;KAC1B,CAAC,CAAC;AACL,CAAC;AAED;;;;MAIM;AACN,MAAM,UAAU,iDAAiD,CAAC,MAAyB;IACzF,OAAO,uBAAuB,CAAC,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAC;AACjG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wCAAwC,CACtD,MAA8B,EAC9B,YAAqB;IAErB,OAAO,uBAAuB,CAAC;QAC7B,8BAA8B,CAAC,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACzE,yBAAyB,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,SAAS,CAAC;KACrE,CAAC,CAAC;AACL,CAAC;AAED;;MAEM;AACN,MAAM,UAAU,kCAAkC,CAChD,MAAwB,EACxB,YAAqB;IAErB,OAAO,uBAAuB,CAAC;QAC7B,wBAAwB,CAAC,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACnE,yBAAyB,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,SAAS,CAAC;KACrE,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yCAAyC,CACvD,MAA+B,EAC/B,YAAqB;IAErB,OAAO,uBAAuB,CAAC;QAC7B,+BAA+B,CAAC,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC1E,yBAAyB,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC;KAC9D,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mCAAmC,CACjD,MAAyB,EACzB,YAAqB;IAErB,OAAO,uBAAuB,CAAC;QAC7B,yBAAyB,CAAC,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACpE,yBAAyB,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC;KAC9D,CAAC,CAAC;AACL,CAAC"}

package/dist/router/swap.d.ts

@@ -1,45 +1,80 @@
 /**
- * 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";
 import type { PublicClient } from "viem";
+/**
+ * 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;
     priceLimitX64: bigint;
     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;
@@ -52,13 +87,59 @@ 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 declare function toSlippageBps(slippagePercent: number): bigint;
+/** Ceiling division for bigint values. Used when rounding slippage up on exact-output swaps. */
 export declare function ceilDiv(numerator: bigint, denominator: bigint): bigint;
+/**
+ * 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 declare function buildExactInputSingleParams(params: BuildExactInputSingleParams): Promise<ExactInputSingleParams>;
+/**
+ * Build single-hop exact-output swap params with live quote and slippage.
+ * Sets `amountInMaximum` from quoted input plus `slippagePercent`.
+ */
 export declare function buildExactOutputSingleParams(params: BuildExactOutputSingleParams): Promise<ExactOutputSingleParams>;
+/**
+ * Encode `exactInputSingle` calldata for `addresses.simpleRouter`.
+ * Approve `tokenIn` on the router before sending (unless using native ETH prepare helpers).
+ */
 export declare function encodeExactInputSingleCalldata(params: ExactInputSingleParams): Hex;
+/** Alias for {@link encodeExactInputSingleCalldata}. */
 export declare const prepareExactInputSingleCalldata: typeof encodeExactInputSingleCalldata;
+/** Encode `exactOutputSingle` calldata for `addresses.simpleRouter`. */
 export declare function encodeExactOutputSingleCalldata(params: ExactOutputSingleParams): Hex;
+/** Alias for {@link encodeExactOutputSingleCalldata}. */
 export declare const prepareExactOutputSingleCalldata: typeof encodeExactOutputSingleCalldata;
 //# sourceMappingURL=swap.d.ts.map

package/dist/router/swap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swap.d.ts","sourceRoot":"","sources":["../../src/router/swap.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAOzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAIzC,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,GAAG,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,GAAG,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAKtE;AAoCD,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAsCjC;AAED,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,4BAA4B,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAsClC;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,sBAAsB,GAAG,GAAG,CAMlF;AAED,eAAO,MAAM,+BAA+B,uCAAiC,CAAC;AAE9E,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,uBAAuB,GAAG,GAAG,CAMpF;AAED,eAAO,MAAM,gCAAgC,wCAAkC,CAAC"}
+{"version":3,"file":"swap.d.ts","sourceRoot":"","sources":["../../src/router/swap.ts"],"names":[],"mappings":"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"}

package/dist/router/swap.js

@@ -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 { encodeFunctionData } from "viem";
 import { defaultPriceLimitX64 } from "../quoter/quotePath.js";
@@ -8,12 +13,17 @@ import { resolveSwapPath } from "../swap/path.js";
 import { SIMPLE_ROUTER_ABI } from "../constants.js";
 import { EMPTY_EXTENSION_DATA } from "../extensions/types.js";
 const BPS_BASE = 10000n;
+/**
+ * Convert a human slippage percent to basis points (1 bp = 0.01%).
+ * @example toSlippageBps(0.5) // 50n
+ */
 export function toSlippageBps(slippagePercent) {
     if (!Number.isFinite(slippagePercent) || slippagePercent < 0 || slippagePercent > 100) {
         throw new Error("slippagePercent must be a finite number between 0 and 100");
     }
     return BigInt(Math.round(slippagePercent * 100));
 }
+/** Ceiling division for bigint values. Used when rounding slippage up on exact-output swaps. */
 export function ceilDiv(numerator, denominator) {
     if (denominator <= 0n) {
         throw new Error("denominator must be > 0");
@@ -51,6 +61,35 @@ function toExactOutputSingleStruct(params) {
         extensionData: withExtensionData(params.extensionData),
     };
 }
+/**
+ * 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) {
     const slippageBps = toSlippageBps(params.slippagePercent);
     const { zeroForOnes } = await resolveSwapPath(params.publicClient, params.tokenIn, params.tokenOut, [params.pool], params.extensionData ? [params.extensionData] : undefined);
@@ -81,6 +120,10 @@ export async function buildExactInputSingleParams(params) {
         extensionData: params.extensionData,
     };
 }
+/**
+ * Build single-hop exact-output swap params with live quote and slippage.
+ * Sets `amountInMaximum` from quoted input plus `slippagePercent`.
+ */
 export async function buildExactOutputSingleParams(params) {
     const slippageBps = toSlippageBps(params.slippagePercent);
     const { zeroForOnes } = await resolveSwapPath(params.publicClient, params.tokenIn, params.tokenOut, [params.pool], params.extensionData ? [params.extensionData] : undefined);
@@ -111,6 +154,10 @@ export async function buildExactOutputSingleParams(params) {
         extensionData: params.extensionData,
     };
 }
+/**
+ * Encode `exactInputSingle` calldata for `addresses.simpleRouter`.
+ * Approve `tokenIn` on the router before sending (unless using native ETH prepare helpers).
+ */
 export function encodeExactInputSingleCalldata(params) {
     return encodeFunctionData({
         abi: SIMPLE_ROUTER_ABI,
@@ -118,7 +165,9 @@ export function encodeExactInputSingleCalldata(params) {
         args: [toExactInputSingleStruct(params)],
     });
 }
+/** Alias for {@link encodeExactInputSingleCalldata}. */
 export const prepareExactInputSingleCalldata = encodeExactInputSingleCalldata;
+/** Encode `exactOutputSingle` calldata for `addresses.simpleRouter`. */
 export function encodeExactOutputSingleCalldata(params) {
     return encodeFunctionData({
         abi: SIMPLE_ROUTER_ABI,
@@ -126,5 +175,6 @@ export function encodeExactOutputSingleCalldata(params) {
         args: [toExactOutputSingleStruct(params)],
     });
 }
+/** Alias for {@link encodeExactOutputSingleCalldata}. */
 export const prepareExactOutputSingleCalldata = encodeExactOutputSingleCalldata;
 //# sourceMappingURL=swap.js.map