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

package/src/abis/MetricOmmSwapQuoter.ts

@@ -1,4 +1,15 @@
 export const MetricOmmSwapQuoterAbi = [
+  {
+    inputs: [
+      {
+        internalType: "uint128",
+        name: "amount",
+        type: "uint128",
+      },
+    ],
+    name: "AmountTooLarge",
+    type: "error",
+  },
   {
     inputs: [
       {
@@ -78,6 +89,27 @@ export const MetricOmmSwapQuoterAbi = [
     name: "InvalidPriceLimitForDirection",
     type: "error",
   },
+  {
+    inputs: [
+      {
+        internalType: "bool",
+        name: "zeroForOne",
+        type: "bool",
+      },
+      {
+        internalType: "uint128",
+        name: "priceLimitX64",
+        type: "uint128",
+      },
+    ],
+    name: "InvalidPriceLimitForDirection",
+    type: "error",
+  },
+  {
+    inputs: [],
+    name: "InvalidSwapDeltas",
+    type: "error",
+  },
   {
     inputs: [],
     name: "InvalidSwapDeltas",
@@ -192,12 +224,12 @@ export const MetricOmmSwapQuoterAbi = [
     outputs: [
       {
         internalType: "uint256",
-        name: "",
+        name: "totalIn",
         type: "uint256",
       },
       {
         internalType: "uint256",
-        name: "",
+        name: "totalOut",
         type: "uint256",
       },
     ],

package/src/abis/index.ts

@@ -5,7 +5,6 @@
 export { MetricOmmPoolAbi } from "./MetricOmmPool.js";
 export { MetricOmmPoolDataProviderAbi } from "./MetricOmmPoolDataProvider.js";
 export { MetricOmmSwapQuoterAbi } from "./MetricOmmSwapQuoter.js";
-export { MetricOmmPoolStateViewAbi } from "./MetricOmmPoolStateView.js";
 export { MetricOmmSimpleRouterAbi } from "./MetricOmmSimpleRouter.js";
 export { MetricOmmPoolLiquidityAdderAbi } from "./MetricOmmPoolLiquidityAdder.js";
 export { MetricOmmPoolFactoryAbi } from "./MetricOmmPoolFactory.js";

package/src/addresses.ts

@@ -38,8 +38,6 @@ export interface ChainAddresses {
   liquidityAdder: Address;
   /** MetricOmmPoolDataProvider (pool reads, swap depth, revert quotes). */
   dataProvider: Address;
-  /** MetricOmmPoolStateView (raw pool storage reads). */
-  stateView: Address;
   /** MetricOmmSimpleRouter (single- and multi-hop ERC-20 swaps). */
   simpleRouter: Address;
   /** MetricOmmSwapQuoter (live pool quotes via revert callback). */
@@ -62,16 +60,15 @@ export interface ChainAddresses {
 const PROTOCOL_ADDRESSES = {
   factory: "0x567C7205107257650dC73a73d87b879a45F5b6F6",
   poolDeployer: "0xBe34D0cEb6CF1acbf55dEf35E4dC3e17BDfb6AE4",
-  liquidityAdder: "0x323B95ABcE8b3025829980bb19d1Fd819808FCB2",
-  dataProvider: "0x5A100da447833D94b8e50AeD1916D7488D15D3fc",
-  stateView: "0xb40F8B0cfBB6a01c3232c6D063B1F87d1C0bE40f",
-  simpleRouter: "0x18f85056444452E718cD680A08f219B2347FE672",
-  quoter: "0x0000000000000000000000000000000000000000",
+  liquidityAdder: "0xA49acb20f33e4FB340f41d949fd7E4c48A242579",
+  dataProvider: "0x803Cb583c1FbE97e9cA7899bE77cC110A78B8737",
+  simpleRouter: "0x146D72ad62957F62ABCC14985aBFCC32a785F996",
+  quoter: "0x8A45A0239DE0C8f438392f2E5AFcbee316E64965",
   extensions: {
-    depositAllowlistExtension: "0x088B0CCBdb17531132173a30428f66c1d5A73794",
-    swapAllowlistExtension: "0x952D844e166E6FAaF73a5e56F0fB0C54543a0f69",
-    oracleValueStopLossExtension: "0x9694959a452283d86eBF4EF4eB5651dEAa1eCec1",
-    priceVelocityGuardExtension: "0xa53E5db6c18Ce258b3090F1470c5fE7f2e0215Fc",
+    depositAllowlistExtension: "0xEd246C7B6963E20aa4fCa4912Af8E2Bff6Ca5f4D",
+    swapAllowlistExtension: "0x54BF5ba3c5C6C513722a54771b2F2A609e2e3A75",
+    oracleValueStopLossExtension: "0x6063a740034E85d34cC55Bc7069BC7b7cdE888bf",
+    priceVelocityGuardExtension: "0xda4c0860d9fa8d254e425d485BD9C09BD2b051F7",
   },
 } as const satisfies Omit<ChainAddresses, "wrappedNative">;
 

package/src/dataProvider/index.ts

@@ -10,7 +10,6 @@ export {
   getBinStatesScaled,
   getBinTotalShares,
   getPositionBinSharesFromDataProvider,
-  getPositionBinSharesFromStateView,
   toPositionBinKey,
   getPositionBinSharesRange,
   getPriceProvider,

package/src/dataProvider/read.ts

@@ -1,6 +1,6 @@
 /**
  * MetricAMM SDK - DataProvider read functions
- * Batch reads via MetricOmmPoolDataProvider (mainnet lens; inherits StateView reads).
+ * Batch reads via MetricOmmPoolDataProvider.
  */
 
 import type { Address, PublicClient } from "viem";
@@ -341,6 +341,3 @@ export async function getPriceProvider(
     args: [poolAddress],
   })) as Address;
 }
-
-/** @deprecated Use getPositionBinSharesFromDataProvider */
-export const getPositionBinSharesFromStateView = getPositionBinSharesFromDataProvider;

package/src/index.ts

@@ -47,7 +47,6 @@ export {
   MetricOmmPoolAbi,
   MetricOmmPoolDataProviderAbi,
   MetricOmmSwapQuoterAbi,
-  MetricOmmPoolStateViewAbi,
   MetricOmmSimpleRouterAbi,
   MetricOmmPoolLiquidityAdderAbi,
   MetricOmmPoolFactoryAbi,
@@ -95,7 +94,6 @@ export {
   getBinStatesScaled,
   getBinTotalShares,
   getPositionBinSharesFromDataProvider,
-  getPositionBinSharesFromStateView,
   toPositionBinKey,
   getPositionBinSharesRange,
   getPriceProvider,
@@ -170,6 +168,17 @@ export {
   prepareExactOutputSingleCalldata,
   prepareExactInputCalldata,
   prepareExactOutputCalldata,
+  encodeMulticallCalldata,
+  encodeRefundETHCalldata,
+  encodeUnwrapWETH9Calldata,
+  prepareExactInputSingleAndUnwrapCalldata,
+  prepareExactInputAndUnwrapCalldata,
+  prepareExactInputSingleSupportingNativePaymentCalldata,
+  prepareExactInputSupportingNativePaymentCalldata,
+  prepareExactOutputSupportingNativePaymentCalldata,
+  prepareExactOutputSingleSupportingNativePaymentCalldata,
+  prepareExactOutputSingleAndUnwrapCalldata,
+  prepareExactOutputAndUnwrapCalldata,
   type ExactInputSingleParams,
   type ExactOutputSingleParams,
   type ExactInputParams,
@@ -178,6 +187,17 @@ export {
   type BuildExactOutputSingleParams,
   type BuildExactInputParams,
   type BuildExactOutputParams,
+  prepareExactInputFromRoute,
+  prepareExactOutputFromRoute,
+  type TradeType,
+  type RouteType,
+  type RouteLegResponse,
+  type RouteOptionResponse,
+  type RouteResponse,
+  type PrepareExactInputFromRouteParams,
+  type PrepareExactOutputFromRouteParams,
+  type PreparedExactInputFromRoute,
+  type PreparedExactOutputFromRoute,
 } from "./router/index.js";
 
 // ============ Factory Functions ============

package/src/pool/liquidity.ts

@@ -1,6 +1,16 @@
 /**
- * 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` — target `addresses.liquidityAdder`
+ * 4. Approve token0 and token1 on the LiquidityAdder for `maxAmountToken0` / `maxAmountToken1`
+ *
+ * **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 +50,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 +80,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 +122,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 +132,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 +142,7 @@ export interface BuildModifyLiquidityArgsForPercentageRemovalParams extends Buil
   upperBin?: number;
 }
 
+/** Granular per-bin removal specs. */
 export interface BuildModifyLiquidityArgsForRemovalParams extends BuildModifyLiquidityArgsBase {
   owner: Address;
   salt: bigint;
@@ -130,7 +160,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 +550,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 +636,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 +692,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 +703,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 +742,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 +772,11 @@ export async function buildAddLiquidityExactSharesParamsFromBinTargets(
   };
 }
 
+/**
+ * Encode `LiquidityAdder.addLiquidityExactShares(pool, salt, deltas, max0, max1, ext)`
+ * for `msg.sender` as position owner.
+ * Approve both pool tokens on the LiquidityAdder before sending.
+ */
 export function encodeAddLiquidityExactSharesSelfCalldata(params: {
   pool: Address;
   salt: bigint;
@@ -737,6 +799,10 @@ export function encodeAddLiquidityExactSharesSelfCalldata(params: {
   });
 }
 
+/**
+ * Same as {@link encodeAddLiquidityExactSharesSelfCalldata} but credits liquidity to `owner`
+ * (e.g. router or vault acting on behalf of a user).
+ */
 export function encodeAddLiquidityExactSharesWithOwnerCalldata(params: {
   pool: Address;
   owner: Address;
@@ -761,6 +827,10 @@ export function encodeAddLiquidityExactSharesWithOwnerCalldata(params: {
   });
 }
 
+/**
+ * Encode weighted add: `weightDeltas` are relative share weights; the adder scales to fit
+ * `maxAmountToken0` / `maxAmountToken1`. Use {@link scaleWeightedPoolDeltasToFitCaps} to pre-scale.
+ */
 export function encodeAddLiquidityWeightedSelfCalldata(params: {
   pool: Address;
   salt: bigint;
@@ -791,6 +861,7 @@ export function encodeAddLiquidityWeightedSelfCalldata(params: {
   });
 }
 
+/** Weighted add with explicit `owner` (7-arg overload on LiquidityAdder). */
 export function encodeAddLiquidityWeightedWithOwnerCalldata(params: {
   pool: Address;
   owner: Address;
@@ -823,6 +894,10 @@ export function encodeAddLiquidityWeightedWithOwnerCalldata(params: {
   });
 }
 
+/**
+ * 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 +916,7 @@ export function encodeRemoveLiquidityCalldata(params: {
   });
 }
 
+/** Build `{ salt, poolLiquidityDelta }` for {@link encodeRemoveLiquidityCalldata}. */
 export async function buildRemoveLiquidityPoolDelta(
   params: BuildModifyLiquidityArgsForRemovalParams,
 ): Promise<{ salt: bigint; poolLiquidityDelta: PoolLiquidityDelta }> {