@nradko/metric-omm-sdk-v1 0.0.16

package/src/stateView/read.ts

@@ -0,0 +1,355 @@
+/**
+ * MetricAMM SDK - StateView Read Functions
+ * Efficient batch read functions using the StateView contract
+ */
+
+import type { Address, PublicClient } from "viem";
+import { STATE_VIEW_ABI } from "../constants.js";
+import type {
+  Slot0,
+  Slot1,
+  BinStateExternal,
+  BinStatesExternal,
+  BinStatesScaled,
+  FeeConfig,
+  PositionBinSharesResult,
+} from "../types.js";
+
+/**
+ * Get slot0 data efficiently (all in one call)
+ */
+export async function getSlot0(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+): Promise<Slot0> {
+  const result = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "slot0",
+    args: [poolAddress],
+  })) as any[];
+
+  return {
+    pauseLevel: Number(result[0]),
+    curBinIdx: Number(result[1]),
+    curPosInBin: result[2],
+    curBinDistFromProvidedPrice: Number(result[3]),
+    spreadFeeE6: Number(result[4]),
+    notionalFeeE8: Number(result[5]),
+  };
+}
+
+/**
+ * Get slot1 data (total scaled token amounts in bins)
+ */
+export async function getSlot1(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+): Promise<Slot1> {
+  const result = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "slot1",
+    args: [poolAddress],
+  })) as any[];
+
+  return {
+    totalScaledToken0InBins: result[0],
+    totalScaledToken1InBins: result[1],
+  };
+}
+
+/**
+ * Get bin state with balances in external (native token decimal) units
+ */
+export async function getBinStateExternal(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  binIdx: number,
+): Promise<BinStateExternal> {
+  const result = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "binState",
+    args: [poolAddress, binIdx],
+  })) as any[];
+
+  return {
+    token0Balance: result[0],
+    token1Balance: result[1],
+    lengthE6: result[2],
+    addFeeBuyE6: result[3],
+    addFeeSellE6: result[4],
+  };
+}
+
+/**
+ * Get multiple bin states efficiently (batch read)
+ */
+export async function getBinStatesExternal(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  binIndices: number[],
+): Promise<BinStatesExternal> {
+  const result = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "binStates",
+    args: [poolAddress, binIndices],
+  })) as any[];
+
+  return {
+    token0Balances: result[0],
+    token1Balances: result[1],
+    lengthsInUnits: result[2],
+    addFeeBuysE6: result[3],
+    addFeeSellsE6: result[4],
+    totalShares: result[5],
+  };
+}
+
+/**
+ * Get multiple bin states in scaled (internal) units (parallel reads).
+ */
+export async function getBinStatesScaled(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  binIndices: number[],
+): Promise<BinStatesScaled> {
+  const scaledReads = binIndices.map(
+    (binIdx) =>
+      publicClient.readContract({
+        address: stateViewAddress,
+        abi: STATE_VIEW_ABI,
+        functionName: "binStateScaled",
+        args: [poolAddress, binIdx],
+      }) as Promise<readonly [bigint, bigint, number, number, number]>,
+  );
+  const shareReads = binIndices.map(
+    (binIdx) =>
+      publicClient.readContract({
+        address: stateViewAddress,
+        abi: STATE_VIEW_ABI,
+        functionName: "binTotalShares",
+        args: [poolAddress, binIdx],
+      }) as Promise<bigint>,
+  );
+
+  const [scaled, shares] = await Promise.all([Promise.all(scaledReads), Promise.all(shareReads)]);
+
+  return {
+    token0BalancesScaled: scaled.map((r) => r[0]),
+    token1BalancesScaled: scaled.map((r) => r[1]),
+    lengthsInUnits: scaled.map((r) => r[2]),
+    addFeeBuysE6: scaled.map((r) => r[3]),
+    addFeeSellsE6: scaled.map((r) => r[4]),
+    totalShares: shares,
+  };
+}
+
+/**
+ * Get bin total shares
+ */
+export async function getBinTotalShares(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  binIdx: number,
+): Promise<bigint> {
+  return (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "binTotalShares",
+    args: [poolAddress, binIdx],
+  })) as bigint;
+}
+
+/**
+ * Get user position shares via StateView
+ */
+export async function getPositionBinSharesFromStateView(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  owner: Address,
+  salt: bigint,
+  binIdx: number,
+): Promise<bigint> {
+  return (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "positionBinShares",
+    args: [poolAddress, owner, salt, binIdx],
+  })) as bigint;
+}
+
+/**
+ * Create a position bin key (matches Solidity's toPositionBinKey)
+ * Layout: [address(160)] | [salt(80)] | [bin(16)] = 256 bits
+ */
+export function toPositionBinKey(owner: Address, salt: bigint, bin: number): `0x${string}` {
+  // Convert owner address to bigint (160 bits)
+  const ownerBigInt = BigInt(owner);
+  // Salt is 80 bits, bin is 16 bits (signed, convert to uint16)
+  const binUint16 = bin < 0 ? BigInt(bin + 0x10000) : BigInt(bin);
+  // Pack: owner << 96 | salt << 16 | bin
+  const packed =
+    (ownerBigInt << 96n) | ((salt & 0xffffffffffffffffffffn) << 16n) | (binUint16 & 0xffffn);
+  return `0x${packed.toString(16).padStart(64, "0")}` as `0x${string}`;
+}
+
+/**
+ * Get user position shares for a range of bins via StateView batch call
+ *
+ * @param publicClient - Viem public client
+ * @param stateViewAddress - StateView contract address
+ * @param poolAddress - Pool address
+ * @param owner - Position owner (e.g., NFTPositionManager address)
+ * @param salt - Position salt (e.g., NFT token ID)
+ * @param lowerBin - Lower bin index (inclusive)
+ * @param upperBin - Upper bin index (inclusive)
+ * @returns Array of { binIdx, shares } for bins with non-zero shares
+ */
+export async function getPositionBinSharesRange(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  owner: Address,
+  salt: bigint,
+  lowerBin: number,
+  upperBin: number,
+): Promise<PositionBinSharesResult[]> {
+  const binIndices: number[] = [];
+  const positionBinKeys: `0x${string}`[] = [];
+
+  for (let bin = lowerBin; bin <= upperBin; bin++) {
+    binIndices.push(bin);
+    positionBinKeys.push(toPositionBinKey(owner, salt, bin));
+  }
+
+  // Batch read all bin shares using the new positionBinSharesBatch function
+  const results = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "positionBinSharesBatch",
+    args: [poolAddress, positionBinKeys],
+  })) as bigint[];
+
+  const positionShares: PositionBinSharesResult[] = [];
+  for (let i = 0; i < binIndices.length; i++) {
+    const shares = results[i];
+    if (shares > 0n) {
+      positionShares.push({
+        binIdx: binIndices[i],
+        shares,
+      });
+    }
+  }
+
+  return positionShares;
+}
+
+/**
+ * Get user position shares for specific (possibly non-contiguous) bins via StateView batch call.
+ *
+ * Unlike getPositionBinSharesRange which scans a contiguous range,
+ * this function queries exact bin indices you specify.
+ *
+ * @param publicClient - Viem public client
+ * @param stateViewAddress - StateView contract address
+ * @param poolAddress - Pool address
+ * @param owner - Position owner address
+ * @param salt - Position salt
+ * @param bins - Array of specific bin indices to query (e.g., [-3, 1, 2])
+ * @returns Array of { binIdx, shares } for bins with non-zero shares
+ */
+export async function getPositionBinSharesForBins(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+  owner: Address,
+  salt: bigint,
+  bins: number[],
+): Promise<PositionBinSharesResult[]> {
+  const positionBinKeys = bins.map((bin) => toPositionBinKey(owner, salt, bin));
+
+  const results = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "positionBinSharesBatch",
+    args: [poolAddress, positionBinKeys],
+  })) as bigint[];
+
+  const positionShares: PositionBinSharesResult[] = [];
+  for (let i = 0; i < bins.length; i++) {
+    const shares = results[i];
+    if (shares > 0n) {
+      positionShares.push({
+        binIdx: bins[i],
+        shares,
+      });
+    }
+  }
+
+  return positionShares;
+}
+
+/**
+ * Get fee configuration
+ */
+export async function getFeeConfig(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+): Promise<FeeConfig> {
+  const result = (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "feeConfig",
+    args: [poolAddress],
+  })) as any[];
+
+  return {
+    adminAddr: result[0],
+    protocolFee: result[1],
+    adminFee: result[2],
+    adminFeeDest: result[3],
+  };
+}
+
+/**
+ * Get price provider address
+ */
+export async function getPriceProvider(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+): Promise<Address> {
+  return (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "priceProvider",
+    args: [poolAddress],
+  })) as Address;
+}
+
+/**
+ * Get last trade timestamp
+ */
+export async function getLastTradeTimestamp(
+  publicClient: PublicClient,
+  stateViewAddress: Address,
+  poolAddress: Address,
+): Promise<number> {
+  return (await publicClient.readContract({
+    address: stateViewAddress,
+    abi: STATE_VIEW_ABI,
+    functionName: "lastTradeTimestamp",
+    args: [poolAddress],
+  })) as number;
+}

package/src/types.ts

@@ -0,0 +1,162 @@
+/**
+ * MetricAMM SDK Types
+ * All interfaces and type definitions
+ */
+
+import type { Address } from "viem";
+
+// ============ Core Types ============
+
+export interface LiquidityDelta {
+  bin: number; // int24
+  deltaShares: bigint; // int104
+}
+
+/**
+ * v1 pool and LiquidityAdder payload: parallel arrays of bin indices and share magnitudes (add or remove).
+ */
+export interface PoolLiquidityDelta {
+  binIdxs: readonly bigint[];
+  shares: readonly bigint[];
+}
+
+/**
+ * Bin configuration for pool creation.
+ * All values are in E6 format (1e6 = 100%).
+ *
+ * @example
+ * // Bin with 1% length, 0.3% buy fee, 0.1% sell fee
+ * { lengthE6: 10000, addFeeBuyE6: 3000, addFeeSellE6: 1000 }
+ */
+export interface BinData {
+  /** Bin length in E6 format (10000 = 1%, 1000000 = 100%) */
+  lengthE6: number;
+  /** Additional buy fee in E6 format */
+  addFeeBuyE6: number;
+  /** Additional sell fee in E6 format */
+  addFeeSellE6: number;
+}
+
+// ============ Pool Types ============
+
+export interface PoolImmutables {
+  factory: Address;
+  token0: Address;
+  token1: Address;
+  token0ScaleMultiplier: bigint;
+  token1ScaleMultiplier: bigint;
+  initialScaledToken0PerShareE18: bigint;
+  initialScaledToken1PerShareE18: bigint;
+  minimalMintableLiquidity: bigint;
+  maxDriftE8: bigint;
+  maxDriftDecayPerSecondE8: bigint;
+  lowestBin: number;
+  highestBin: number;
+}
+
+export interface PoolState {
+  pauseLevel: number;
+  curBinIdx: number;
+  curPosInBin: bigint;
+  curBinDistFromProvidedPrice: number;
+  spreadFeeE6: number;
+  notionalFeeE8: number;
+  totalScaledToken0InBins: bigint;
+  totalScaledToken1InBins: bigint;
+}
+
+export interface BinState {
+  token0BalanceScaled: bigint;
+  token1BalanceScaled: bigint;
+  lengthE6: number;
+  addFeeBuyE6: number;
+  addFeeSellE6: number;
+}
+
+export interface BinStateExternal {
+  token0Balance: bigint; // Unscaled, in native token decimals
+  token1Balance: bigint; // Unscaled, in native token decimals
+  lengthE6: number;
+  addFeeBuyE6: number;
+  addFeeSellE6: number;
+}
+
+export interface BinStatesExternal {
+  token0Balances: bigint[];
+  token1Balances: bigint[];
+  lengthsInUnits: number[];
+  addFeeBuysE6: number[];
+  addFeeSellsE6: number[];
+  totalShares: bigint[];
+}
+
+export interface BinStatesScaled {
+  token0BalancesScaled: bigint[];
+  token1BalancesScaled: bigint[];
+  lengthsInUnits: number[];
+  addFeeBuysE6: number[];
+  addFeeSellsE6: number[];
+  totalShares: bigint[];
+}
+
+// ============ StateView Types ============
+
+export interface Slot0 {
+  pauseLevel: number;
+  curBinIdx: number;
+  curPosInBin: bigint;
+  curBinDistFromProvidedPrice: number;
+  spreadFeeE6: number;
+  notionalFeeE8: number;
+}
+
+export interface Slot1 {
+  totalScaledToken0InBins: bigint;
+  totalScaledToken1InBins: bigint;
+}
+
+export interface FeeConfig {
+  adminAddr: Address;
+  protocolFee: number;
+  adminFee: number;
+  adminFeeDest: Address;
+}
+
+// ============ Position Types ============
+
+/**
+ * Result type for getPositionBinSharesRange
+ */
+export interface PositionBinSharesResult {
+  binIdx: number;
+  shares: bigint;
+}
+
+// ============ Liquidity Types ============
+
+export interface CalculateUniformLiquidityParams {
+  valuePerBinInToken: bigint;
+  valueIsInToken0: boolean;
+  currentPrice: number;
+  lowerBin: number;
+  upperBin: number;
+}
+
+export interface LiquidityBinValueInput {
+  bin: number;
+  targetValueInToken: bigint;
+  targetValueInToken0: boolean;
+}
+
+export interface CalculateAnyLiquidityParams {
+  bins: LiquidityBinValueInput[];
+  currentPrice: number;
+}
+
+export interface PreparedLiquidityDistribution {
+  deltas: LiquidityDelta[];
+  specAmount0: bigint;
+  specAmount1: bigint;
+}
+
+export type CalculatedLiquidityDistribution = PreparedLiquidityDistribution;

package/src/utils/binData.ts

@@ -0,0 +1,127 @@
+/**
+ * MetricAMM SDK - Bin Data Utilities
+ * Functions for packing/unpacking bin data
+ */
+
+import type { BinData } from "../types.js";
+
+/**
+ * Pack bin data into 48-bit representation
+ * Layout: [lengthE6: 16 bits][addFeeBuyE6: 16 bits][addFeeSellE6: 16 bits]
+ */
+export function packBinData(binData: BinData): bigint {
+  const length = BigInt(binData.lengthE6) & 0xffffn;
+  const buyFee = BigInt(binData.addFeeBuyE6) & 0xffffn;
+  const sellFee = BigInt(binData.addFeeSellE6) & 0xffffn;
+
+  return length | (buyFee << 16n) | (sellFee << 32n);
+}
+
+/**
+ * Pack 5 bins into a single uint256
+ * Each bin takes 48 bits, total 240 bits used, 16 bits unused
+ */
+export function packBins5(bins: BinData[]): bigint {
+  if (bins.length !== 5) {
+    throw new Error("Must provide exactly 5 bins");
+  }
+
+  let packed = 0n;
+  for (let i = 0; i < 5; i++) {
+    const binPacked = packBinData(bins[i]);
+    packed |= binPacked << (BigInt(i) * 48n);
+  }
+
+  return packed;
+}
+
+/**
+ * Pack an array of bin data into uint256 array (5 bins per uint256)
+ * Pads with zero bins if length is not divisible by 5
+ */
+export function packBinDataArray(bins: BinData[]): bigint[] {
+  const zeroBin: BinData = { lengthE6: 0, addFeeBuyE6: 0, addFeeSellE6: 0 };
+  const result: bigint[] = [];
+
+  // Process in chunks of 5
+  for (let i = 0; i < bins.length; i += 5) {
+    const chunk: BinData[] = [];
+    for (let j = 0; j < 5; j++) {
+      chunk.push(bins[i + j] || zeroBin);
+    }
+    result.push(packBins5(chunk));
+  }
+
+  return result;
+}
+
+/**
+ * Unpack 48-bit bin data
+ */
+export function unpackBinData(packed: bigint): BinData {
+  const lengthE6 = Number(packed & 0xffffn);
+  const addFeeBuyE6 = Number((packed >> 16n) & 0xffffn);
+  const addFeeSellE6 = Number((packed >> 32n) & 0xffffn);
+
+  return {
+    lengthE6,
+    addFeeBuyE6,
+    addFeeSellE6,
+  };
+}
+
+/**
+ * Pack bin data array into uint256 array ready for contract calls.
+ *
+ * @param bins Array of bin configurations
+ * @returns Packed uint256 array ready for contract calls
+ *
+ * @example
+ * // Create 3 bins: 1% length with default fees
+ * const bins = createBins([
+ *   { lengthE6: 10000, addFeeBuyE6: 0, addFeeSellE6: 0 },
+ *   { lengthE6: 10000, addFeeBuyE6: 0, addFeeSellE6: 0 },
+ *   { lengthE6: 10000, addFeeBuyE6: 0, addFeeSellE6: 0 },
+ * ]);
+ *
+ * @example
+ * // Create bins with custom fees
+ * const bins = createBins([
+ *   { lengthE6: 10000, addFeeBuyE6: 500, addFeeSellE6: 200 },   // 1% length, +0.05% buy, +0.02% sell
+ *   { lengthE6: 20000, addFeeBuyE6: 0, addFeeSellE6: 0 },       // 2% length, no extra fees
+ * ]);
+ */
+export function createBins(bins: BinData[]): bigint[] {
+  return packBinDataArray(bins);
+}
+
+/**
+ * Create uniform bins with the same configuration.
+ *
+ * @param count Number of bins to create
+ * @param lengthE6 Bin length in E6 format (10000 = 1%)
+ * @param addFeeBuyE6 Additional buy fee in E6 format (default: 0)
+ * @param addFeeSellE6 Additional sell fee in E6 format (default: 0)
+ * @returns Packed uint256 array ready for contract calls
+ *
+ * @example
+ * // Create 20 uniform bins, each 1% length
+ * const bins = createUniformBins(20, 10000);
+ *
+ * @example
+ * // Create 10 bins with 0.5% length and +0.1% buy fee
+ * const bins = createUniformBins(10, 5000, 1000);
+ */
+export function createUniformBins(
+  count: number,
+  lengthE6: number,
+  addFeeBuyE6: number = 0,
+  addFeeSellE6: number = 0,
+): bigint[] {
+  const bins: BinData[] = Array(count).fill({
+    lengthE6,
+    addFeeBuyE6,
+    addFeeSellE6,
+  });
+  return packBinDataArray(bins);
+}

package/src/utils/index.ts

@@ -0,0 +1,26 @@
+/**
+ * MetricAMM SDK - Utility Functions
+ */
+
+// Bin data utilities
+export {
+  packBinData,
+  packBins5,
+  packBinDataArray,
+  unpackBinData,
+  createBins,
+  createUniformBins,
+} from "./binData.js";
+
+// Price utilities
+export { priceToQ64, q64ToPrice } from "./price.js";
+
+// Liquidity math utilities
+export {
+  ONE_E18,
+  ceilDiv,
+  toPriceE18 as toPriceX18,
+  convertToken0ToToken1,
+  convertToken1ToToken0,
+  scaledPositiveDeltaToExternal,
+} from "./liquidityMath.js";

package/src/utils/liquidityMath.ts

@@ -0,0 +1,47 @@
+/**
+ * MetricAMM SDK - Liquidity Math Utilities
+ */
+
+export const ONE_E18 = 1_000_000_000_000_000_000n;
+
+export function ceilDiv(numerator: bigint, denominator: bigint): bigint {
+  if (denominator <= 0n) throw new Error("denominator must be > 0");
+  if (numerator < 0n) throw new Error("numerator must be >= 0");
+  return numerator === 0n ? 0n : (numerator + denominator - 1n) / denominator;
+}
+
+export function toPriceE18(currentPrice: number): bigint {
+  if (!Number.isFinite(currentPrice) || currentPrice <= 0) {
+    throw new Error("currentPrice must be a positive finite number");
+  }
+  const priceE18 = BigInt(Math.round(currentPrice * 1e18));
+  if (priceE18 <= 0n) {
+    throw new Error("currentPrice is too small");
+  }
+  return priceE18;
+}
+
+export function convertToken0ToToken1(
+  amount0: bigint,
+  token0ScaleMultiplier: bigint,
+  token1ScaleMultiplier: bigint,
+  priceE18: bigint,
+): bigint {
+  return (amount0 * token0ScaleMultiplier * priceE18) / (token1ScaleMultiplier * ONE_E18);
+}
+
+export function convertToken1ToToken0(
+  amount1: bigint,
+  token0ScaleMultiplier: bigint,
+  token1ScaleMultiplier: bigint,
+  priceX18: bigint,
+): bigint {
+  return (amount1 * token1ScaleMultiplier * ONE_E18) / (token0ScaleMultiplier * priceX18);
+}
+
+export function scaledPositiveDeltaToExternal(
+  scaledAmount: bigint,
+  scaleMultiplier: bigint,
+): bigint {
+  return ceilDiv(scaledAmount, scaleMultiplier);
+}