@whetstone-research/doppler-sdk 0.0.1-alpha.8 → 0.0.1

package/dist/{chunk-FVTIDXYK.mjs → chunk-AKSEBAR7.mjs}

@@ -1,8 +1,11 @@
-import { getAddresses } from './chunk-RIMM47JL.mjs';
-import { uniswapV3PoolAbi, airlockAbi } from './chunk-DCFHANLR.mjs';
-import { getAddress } from 'viem';
+import { uniswapV3PoolAbi, airlockAbi } from './chunk-OTG75GVH.mjs';
+import { getAddresses } from './chunk-AW3WR2D3.mjs';
+import { zeroAddress } from 'viem';
 
 var StaticAuction = class {
+  get rpc() {
+    return this.client;
+  }
   constructor(client, poolAddress) {
     this.client = client;
     this.poolAddress = poolAddress;
@@ -18,41 +21,47 @@ var StaticAuction = class {
    */
   async getPoolInfo() {
     const [slot0, liquidity, token0, token1, fee] = await Promise.all([
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "slot0"
       }),
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "liquidity"
       }),
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "token0"
       }),
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "token1"
       }),
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "fee"
       })
     ]);
-    const chainId = await this.client.getChainId();
+    const chainId = await this.rpc.getChainId();
     const addresses = getAddresses(chainId);
-    const assetData = await this.client.readContract({
+    const assetData = await this.rpc.readContract({
       address: addresses.airlock,
       abi: airlockAbi,
       functionName: "getAssetData",
       args: [token0]
     });
-    const isToken0AuctionToken = assetData[5] !== getAddress("0x0000000000000000000000000000000000000000");
+    let poolOrHook0;
+    if (Array.isArray(assetData)) {
+      poolOrHook0 = assetData[5];
+    } else if (assetData && typeof assetData === "object") {
+      poolOrHook0 = assetData.poolOrHook ?? assetData.pool;
+    }
+    const isToken0AuctionToken = poolOrHook0 && poolOrHook0 !== zeroAddress;
     return {
       address: this.poolAddress,
       tokenAddress: isToken0AuctionToken ? token0 : token1,
@@ -75,15 +84,16 @@ var StaticAuction = class {
    */
   async hasGraduated() {
     const tokenAddress = await this.getTokenAddress();
-    const chainId = await this.client.getChainId();
+    const chainId = await this.rpc.getChainId();
     const addresses = getAddresses(chainId);
-    const assetData = await this.client.readContract({
+    const assetData = await this.rpc.readContract({
       address: addresses.airlock,
       abi: airlockAbi,
       functionName: "getAssetData",
       args: [tokenAddress]
     });
-    return assetData[3] === getAddress("0x0000000000000000000000000000000000000000");
+    const liquidityMigrator = Array.isArray(assetData) ? assetData[3] : assetData?.liquidityMigrator;
+    return liquidityMigrator === zeroAddress;
   }
   /**
    * Get the current price in the pool
@@ -92,12 +102,12 @@ var StaticAuction = class {
   async getCurrentPrice() {
     const poolInfo = await this.getPoolInfo();
     const [token0, token1] = await Promise.all([
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "token0"
       }),
-      this.client.readContract({
+      this.rpc.readContract({
         address: this.poolAddress,
         abi: uniswapV3PoolAbi,
         functionName: "token1"
@@ -118,7 +128,7 @@ var StaticAuction = class {
    * Get total liquidity in the pool
    */
   async getTotalLiquidity() {
-    return await this.client.readContract({
+    return await this.rpc.readContract({
       address: this.poolAddress,
       abi: uniswapV3PoolAbi,
       functionName: "liquidity"
@@ -127,5 +137,5 @@ var StaticAuction = class {
 };
 
 export { StaticAuction };
-//# sourceMappingURL=chunk-FVTIDXYK.mjs.map
-//# sourceMappingURL=chunk-FVTIDXYK.mjs.map
+//# sourceMappingURL=chunk-AKSEBAR7.mjs.map
+//# sourceMappingURL=chunk-AKSEBAR7.mjs.map

package/dist/chunk-AKSEBAR7.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entities/auction/StaticAuction.ts"],"names":[],"mappings":"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","file":"chunk-AKSEBAR7.mjs","sourcesContent":["import { type Address, getAddress, zeroAddress, type PublicClient } from 'viem'\nimport type { PoolInfo, SupportedPublicClient } from '../../types'\nimport { uniswapV3PoolAbi, airlockAbi } from '../../abis'\nimport { getAddresses } from '../../addresses'\n\n/**\n * StaticAuction class for interacting with static auctions (Uniswap V3 based)\n * \n * Static auctions use a fixed price range on Uniswap V3 for initial liquidity bootstrapping.\n * This is ideal for simple, predictable price discovery events.\n */\nexport class StaticAuction {\n  private client: SupportedPublicClient\n  private poolAddress: Address\n  private get rpc(): PublicClient {\n    return this.client as PublicClient\n  }\n  \n  constructor(client: SupportedPublicClient, poolAddress: Address) {\n    this.client = client\n    this.poolAddress = poolAddress\n  }\n  \n  /**\n   * Get the pool address\n   */\n  getAddress(): Address {\n    return this.poolAddress\n  }\n  \n  /**\n   * Get current pool information\n   */\n  async getPoolInfo(): Promise<PoolInfo> {\n    // Fetch all pool data in parallel\n    const [slot0, liquidity, token0, token1, fee] = await Promise.all([\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'slot0',\n      }),\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'liquidity',\n      }),\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'token0',\n      }),\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'token1',\n      }),\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'fee',\n      }),\n    ])\n    \n    // Determine which token is the auction token and which is numeraire\n    // This requires checking with the Airlock contract\n    const chainId = await this.rpc.getChainId()\n    const addresses = getAddresses(chainId)\n    \n    const assetData = await this.rpc.readContract({\n      address: addresses.airlock,\n      abi: airlockAbi,\n      functionName: 'getAssetData',\n      args: [token0],\n    })\n    // Determine whether token0 is the auction token.\n    // Handle both tuple and object return shapes from getAssetData.\n    // Tuple (legacy): [numeraire, timelock, governance, liquidityMigrator, poolInitializer, pool, ...]\n    // Object (unified): { poolOrHook, liquidityMigrator, numeraire, ... }\n    let poolOrHook0: any\n    if (Array.isArray(assetData)) {\n      poolOrHook0 = assetData[5]\n    } else if (assetData && typeof assetData === 'object') {\n      poolOrHook0 = (assetData as any).poolOrHook ?? (assetData as any).pool\n    }\n    const isToken0AuctionToken = poolOrHook0 && poolOrHook0 !== zeroAddress\n    \n    return {\n      address: this.poolAddress,\n      tokenAddress: isToken0AuctionToken ? token0 : token1,\n      numeraireAddress: isToken0AuctionToken ? token1 : token0,\n      fee,\n      liquidity,\n      sqrtPriceX96: slot0[0], // First element is sqrtPriceX96\n    }\n  }\n  \n  /**\n   * Get the token address for this auction\n   */\n  async getTokenAddress(): Promise<Address> {\n    const poolInfo = await this.getPoolInfo()\n    return poolInfo.tokenAddress\n  }\n  \n  /**\n   * Check if the auction has graduated (ready for migration)\n   */\n  async hasGraduated(): Promise<boolean> {\n    const tokenAddress = await this.getTokenAddress()\n    const chainId = await this.rpc.getChainId()\n    const addresses = getAddresses(chainId)\n    \n    const assetData = await this.rpc.readContract({\n      address: addresses.airlock,\n      abi: airlockAbi,\n      functionName: 'getAssetData',\n      args: [tokenAddress],\n    })\n    // Check if the asset is graduated (liquidityMigrator is zero)\n    const liquidityMigrator = Array.isArray(assetData)\n      ? (assetData as any)[3]\n      : (assetData as any)?.liquidityMigrator\n    return liquidityMigrator === zeroAddress\n  }\n  \n  /**\n   * Get the current price in the pool\n   * Returns the price of token in terms of numeraire (token/numeraire)\n   */\n  async getCurrentPrice(): Promise<bigint> {\n    const poolInfo = await this.getPoolInfo()\n    \n    // Get token ordering\n    const [token0, token1] = await Promise.all([\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'token0',\n      }),\n      this.rpc.readContract({\n        address: this.poolAddress,\n        abi: uniswapV3PoolAbi,\n        functionName: 'token1',\n      }),\n    ])\n    \n    // Calculate price from sqrtPriceX96\n    // sqrtPriceX96 = sqrt(price) * 2^96\n    // price = (sqrtPriceX96 / 2^96)^2\n    const sqrtPriceX96 = poolInfo.sqrtPriceX96\n    const Q96 = BigInt(2) ** BigInt(96)\n    \n    // price0 = amount of token1 per token0\n    const sqrtPriceX96Squared = sqrtPriceX96 * sqrtPriceX96\n    const Q96Squared = Q96 * Q96\n    const price0 = sqrtPriceX96Squared / Q96Squared\n    \n    // Return price based on which token is the auction token\n    if (poolInfo.tokenAddress === token0) {\n      // Auction token is token0, return price in terms of token1 (numeraire)\n      return price0\n    } else {\n      // Auction token is token1, return reciprocal price\n      // price1 = 1 / price0 (with precision handling)\n      return Q96Squared / price0\n    }\n  }\n  \n  /**\n   * Get total liquidity in the pool\n   */\n  async getTotalLiquidity(): Promise<bigint> {\n    return await this.rpc.readContract({\n      address: this.poolAddress,\n      abi: uniswapV3PoolAbi,\n      functionName: 'liquidity',\n    })\n  }\n}\n"]}

package/dist/chunk-AS64GWBX.js

@@ -0,0 +1,204 @@
+'use strict';
+
+var chunkHM25ZMO3_js = require('./chunk-HM25ZMO3.js');
+var chunkP7KLEPVI_js = require('./chunk-P7KLEPVI.js');
+
+// src/utils/marketCapHelpers.ts
+function marketCapToTokenPrice(marketCapUSD, tokenSupply, tokenDecimals = 18) {
+  if (marketCapUSD <= 0) {
+    throw new Error("Market cap must be positive");
+  }
+  if (tokenSupply <= 0n) {
+    throw new Error("Token supply must be positive");
+  }
+  const supplyNum = Number(tokenSupply) / 10 ** tokenDecimals;
+  return marketCapUSD / supplyNum;
+}
+function tokenPriceToRatio(tokenPriceUSD, numerairePriceUSD, tokenDecimals = 18, numeraireDecimals = 18) {
+  if (tokenPriceUSD <= 0) {
+    throw new Error("Token price must be positive");
+  }
+  if (numerairePriceUSD <= 0) {
+    throw new Error("Numeraire price must be positive");
+  }
+  const ratio = numerairePriceUSD / tokenPriceUSD;
+  const decimalAdjustment = 10 ** (tokenDecimals - numeraireDecimals);
+  return ratio * decimalAdjustment;
+}
+function ratioToTick(ratio) {
+  if (ratio <= 0) {
+    throw new Error("Ratio must be positive");
+  }
+  return Math.log(ratio) / Math.log(1.0001);
+}
+function isToken1(tokenAddress, numeraireAddress) {
+  return tokenAddress.toLowerCase() > numeraireAddress.toLowerCase();
+}
+function marketCapToTick(marketCapUSD, tokenSupply, numerairePriceUSD, tokenDecimals = 18, numeraireDecimals = 18, tickSpacing, numeraire) {
+  const tokenIsToken1 = !chunkHM25ZMO3_js.isToken0Expected(numeraire);
+  const tokenPrice = marketCapToTokenPrice(marketCapUSD, tokenSupply, tokenDecimals);
+  const ratio = tokenPriceToRatio(
+    tokenPrice,
+    numerairePriceUSD,
+    tokenDecimals,
+    numeraireDecimals
+  );
+  const rawTick = ratioToTick(ratio);
+  let tick = Math.floor(rawTick / tickSpacing) * tickSpacing;
+  if (tokenIsToken1) {
+    tick = -tick;
+  }
+  if (tick === 0) tick = 0;
+  if (tick < chunkP7KLEPVI_js.MIN_TICK || tick > chunkP7KLEPVI_js.MAX_TICK) {
+    throw new Error(
+      `Calculated tick ${tick} is out of bounds [${chunkP7KLEPVI_js.MIN_TICK}, ${chunkP7KLEPVI_js.MAX_TICK}]. Market cap ${marketCapUSD.toLocaleString()} may be too extreme for the given parameters.`
+    );
+  }
+  return tick;
+}
+function marketCapRangeToTicks(marketCapRange, tokenSupply, numerairePriceUSD, tokenDecimals = 18, numeraireDecimals = 18, tickSpacing, numeraire) {
+  if (marketCapRange.start <= 0 || marketCapRange.end <= 0) {
+    throw new Error("Market cap values must be positive");
+  }
+  if (marketCapRange.start >= marketCapRange.end) {
+    throw new Error("Start market cap must be less than end market cap");
+  }
+  const tickStart = marketCapToTick(
+    marketCapRange.start,
+    tokenSupply,
+    numerairePriceUSD,
+    tokenDecimals,
+    numeraireDecimals,
+    tickSpacing,
+    numeraire
+  );
+  const tickEnd = marketCapToTick(
+    marketCapRange.end,
+    tokenSupply,
+    numerairePriceUSD,
+    tokenDecimals,
+    numeraireDecimals,
+    tickSpacing,
+    numeraire
+  );
+  const startTick = Math.min(tickStart, tickEnd);
+  const endTick = Math.max(tickStart, tickEnd);
+  if (startTick === endTick) {
+    throw new Error(
+      `Market cap range ${marketCapRange.start.toLocaleString()} - ${marketCapRange.end.toLocaleString()} resulted in same tick (${startTick}). Try a wider range or smaller tick spacing.`
+    );
+  }
+  return { startTick, endTick };
+}
+function transformTicksForAuction(rawStartTick, rawEndTick, numeraire) {
+  const tokenIsToken1 = !chunkHM25ZMO3_js.isToken0Expected(numeraire);
+  if (tokenIsToken1) {
+    return {
+      startTick: -rawEndTick,
+      endTick: -rawStartTick
+    };
+  }
+  return { startTick: rawStartTick, endTick: rawEndTick };
+}
+function applyTickOffsets(pegTick, offsetLower, offsetUpper, numeraire) {
+  const tokenIsToken1 = !chunkHM25ZMO3_js.isToken0Expected(numeraire);
+  if (tokenIsToken1) {
+    return {
+      tickLower: pegTick + offsetLower,
+      tickUpper: pegTick + offsetUpper
+    };
+  } else {
+    return {
+      tickLower: pegTick - offsetUpper,
+      tickUpper: pegTick - offsetLower
+    };
+  }
+}
+function marketCapRangeToTicksForCurve(marketCapLower, marketCapUpper, tokenSupply, numerairePriceUSD, tokenDecimals = 18, numeraireDecimals = 18, tickSpacing, numeraire) {
+  if (marketCapLower <= 0 || marketCapUpper <= 0) {
+    throw new Error("Market cap values must be positive");
+  }
+  if (marketCapLower >= marketCapUpper) {
+    throw new Error("Lower market cap must be less than upper market cap");
+  }
+  const tickAtLower = marketCapToTick(
+    marketCapLower,
+    tokenSupply,
+    numerairePriceUSD,
+    tokenDecimals,
+    numeraireDecimals,
+    tickSpacing,
+    numeraire
+  );
+  const tickAtUpper = marketCapToTick(
+    marketCapUpper,
+    tokenSupply,
+    numerairePriceUSD,
+    tokenDecimals,
+    numeraireDecimals,
+    tickSpacing,
+    numeraire
+  );
+  const tickLower = Math.min(tickAtLower, tickAtUpper);
+  const tickUpper = Math.max(tickAtLower, tickAtUpper);
+  if (tickLower === tickUpper) {
+    throw new Error(
+      `Market cap range $${marketCapLower.toLocaleString()} - $${marketCapUpper.toLocaleString()} resulted in same tick (${tickLower}). Try a wider range or smaller tick spacing.`
+    );
+  }
+  return { tickLower, tickUpper };
+}
+function validateMarketCapParameters(marketCap, tokenSupply, tokenDecimals = 18) {
+  const warnings = [];
+  if (marketCap < 1e3) {
+    warnings.push(
+      `Market cap $${marketCap.toLocaleString()} is very small. Consider if this is intentional.`
+    );
+  }
+  if (marketCap > 1e12) {
+    warnings.push(
+      `Market cap $${marketCap.toLocaleString()} is very large (> $1T). Verify this is correct.`
+    );
+  }
+  const tokenPrice = marketCapToTokenPrice(marketCap, tokenSupply, tokenDecimals);
+  if (tokenPrice < 1e-6) {
+    warnings.push(
+      `Implied token price $${tokenPrice.toExponential(2)} is very small. This may cause precision issues.`
+    );
+  }
+  if (tokenPrice > 1e6) {
+    warnings.push(
+      `Implied token price $${tokenPrice.toLocaleString()} is very large. Verify your token supply and market cap values.`
+    );
+  }
+  return {
+    valid: warnings.length === 0,
+    warnings
+  };
+}
+function tickToMarketCap(tick, tokenSupply, numerairePriceUSD, tokenDecimals = 18, numeraireDecimals = 18, numeraire) {
+  const tokenIsToken1 = !chunkHM25ZMO3_js.isToken0Expected(numeraire);
+  let adjustedTick = tick;
+  if (tokenIsToken1) {
+    adjustedTick = -tick;
+  }
+  const ratio = Math.pow(1.0001, adjustedTick);
+  const decimalAdjustment = 10 ** (tokenDecimals - numeraireDecimals);
+  const tokenPriceUSD = numerairePriceUSD / (ratio / decimalAdjustment);
+  const supplyNum = Number(tokenSupply) / 10 ** tokenDecimals;
+  return tokenPriceUSD * supplyNum;
+}
+
+exports.applyTickOffsets = applyTickOffsets;
+exports.isToken1 = isToken1;
+exports.marketCapRangeToTicks = marketCapRangeToTicks;
+exports.marketCapRangeToTicksForCurve = marketCapRangeToTicksForCurve;
+exports.marketCapToTick = marketCapToTick;
+exports.marketCapToTokenPrice = marketCapToTokenPrice;
+exports.ratioToTick = ratioToTick;
+exports.tickToMarketCap = tickToMarketCap;
+exports.tokenPriceToRatio = tokenPriceToRatio;
+exports.transformTicksForAuction = transformTicksForAuction;
+exports.validateMarketCapParameters = validateMarketCapParameters;
+//# sourceMappingURL=chunk-AS64GWBX.js.map
+//# sourceMappingURL=chunk-AS64GWBX.js.map

package/dist/chunk-AS64GWBX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/marketCapHelpers.ts"],"names":["isToken0Expected","MIN_TICK","MAX_TICK"],"mappings":"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","file":"chunk-AS64GWBX.js","sourcesContent":["/**\n * Market cap conversion utilities for token launches\n *\n * These utilities convert between market cap (USD) and Uniswap ticks\n * following the mathematical relationship:\n *\n *   Market Cap (USD) → Token Price (USD) → Ratio (numeraire/token) → Tick\n *\n * Based on reference implementation: plan/priceMultiCurve.py\n */\n\nimport type { Address } from 'viem'\nimport type { MarketCapRange, MarketCapValidationResult } from '../types'\nimport { MIN_TICK, MAX_TICK } from './tickMath'\nimport { isToken0Expected } from './isToken0Expected'\n\n// Re-export types from types.ts for convenience\nexport type { MarketCapRange, MarketCapValidationResult } from '../types'\n\n/**\n * Convert market cap to token price\n *\n * @param marketCapUSD - Market capitalization in USD\n * @param tokenSupply - Total token supply (as bigint with decimals, e.g., parseEther('1000000000'))\n * @param tokenDecimals - Token decimals (default: 18)\n * @returns Price of one token in USD\n *\n * @example\n * ```ts\n * // $1M market cap with 1B tokens (18 decimals)\n * const price = marketCapToTokenPrice(1_000_000, parseEther('1000000000'))\n * // Returns: 0.001 (each token is worth $0.001)\n * ```\n */\nexport function marketCapToTokenPrice(\n  marketCapUSD: number,\n  tokenSupply: bigint,\n  tokenDecimals: number = 18\n): number {\n  if (marketCapUSD <= 0) {\n    throw new Error('Market cap must be positive')\n  }\n  if (tokenSupply <= 0n) {\n    throw new Error('Token supply must be positive')\n  }\n\n  // Convert supply from bigint with decimals to human-readable number\n  const supplyNum = Number(tokenSupply) / 10 ** tokenDecimals\n  return marketCapUSD / supplyNum\n}\n\n/**\n * Convert token price to price ratio (numeraire per token)\n *\n * @param tokenPriceUSD - Price of one token in USD\n * @param numerairePriceUSD - Price of numeraire (e.g., ETH) in USD\n * @param tokenDecimals - Token decimals (default: 18)\n * @param numeraireDecimals - Numeraire decimals (default: 18)\n * @returns Price ratio adjusted for decimals\n *\n * @example\n * ```ts\n * // Token at $0.001, ETH at $3000, both 18 decimals\n * const ratio = tokenPriceToRatio(0.001, 3000, 18, 18)\n * // Returns: 3,000,000 (3M ETH wei per token wei at this ratio)\n * ```\n */\nexport function tokenPriceToRatio(\n  tokenPriceUSD: number,\n  numerairePriceUSD: number,\n  tokenDecimals: number = 18,\n  numeraireDecimals: number = 18\n): number {\n  if (tokenPriceUSD <= 0) {\n    throw new Error('Token price must be positive')\n  }\n  if (numerairePriceUSD <= 0) {\n    throw new Error('Numeraire price must be positive')\n  }\n\n  // How much numeraire per token (in USD terms first)\n  // tokenPriceUSD / numerairePriceUSD = numeraire per token\n  const ratio = numerairePriceUSD / tokenPriceUSD\n\n  // Adjust for decimal differences\n  // Formula: (numeraire / tokenPrice) * (10 ** (assetDecimals - numeraireDecimals))\n  const decimalAdjustment = 10 ** (tokenDecimals - numeraireDecimals)\n\n  return ratio * decimalAdjustment\n}\n\n/**\n * Convert ratio to tick using Uniswap's formula: tick = log(ratio) / log(1.0001)\n *\n * @param ratio - Price ratio (must be positive)\n * @returns Raw tick value (before spacing adjustment)\n *\n * @example\n * ```ts\n * ratioToTick(1)       // Returns: 0\n * ratioToTick(1.0001)  // Returns: ~1\n * ratioToTick(Math.pow(1.0001, 1000)) // Returns: ~1000\n * ```\n */\nexport function ratioToTick(ratio: number): number {\n  if (ratio <= 0) {\n    throw new Error('Ratio must be positive')\n  }\n\n  // Uniswap tick formula: tick = log(price) / log(1.0001)\n  return Math.log(ratio) / Math.log(1.0001)\n}\n\n/**\n * Determine if the new token will be token1 in the Uniswap pair\n *\n * Uniswap orders tokens by address (token0 < token1 in hex comparison).\n * This affects how ticks are interpreted for price calculations.\n *\n * @param tokenAddress - Address of the new token\n * @param numeraireAddress - Address of the numeraire (e.g., WETH)\n * @returns true if token will be token1, false if token0\n *\n * @example\n * ```ts\n * isToken1('0xB000...', '0xA000...') // true (B > A)\n * isToken1('0xA000...', '0xB000...') // false (A < B)\n * ```\n */\nexport function isToken1(\n  tokenAddress: string,\n  numeraireAddress: string\n): boolean {\n  return tokenAddress.toLowerCase() > numeraireAddress.toLowerCase()\n}\n\n/**\n * Complete conversion from market cap to usable tick\n *\n * This is the main entry point combining all conversion steps:\n * 1. Market cap → Token price\n * 2. Token price → Ratio\n * 3. Ratio → Raw tick\n * 4. Raw tick → Nearest usable tick (aligned to spacing)\n * 5. Handle token ordering (negate if token is token1)\n *\n * **Important**: The returned tick includes token ordering adjustment.\n * When the token is token1 (determined from numeraire address), the tick is NEGATED:\n * - Higher market cap → smaller (more negative) tick\n * - Lower market cap → larger (less negative) tick\n *\n * Builders apply additional transformations based on auction type.\n * See builder implementations for auction-specific tick conventions.\n *\n * @param marketCapUSD - Target market cap in USD\n * @param tokenSupply - Total token supply (with decimals, as bigint)\n * @param numerairePriceUSD - Price of numeraire in USD (e.g., ETH = 3000)\n * @param tokenDecimals - Token decimals (default: 18)\n * @param numeraireDecimals - Numeraire decimals (default: 18)\n * @param tickSpacing - Tick spacing of the pool (e.g., 60, 100)\n * @param numeraire - Address of the numeraire token (e.g., WETH). Used to determine token ordering.\n * @returns Nearest usable tick (negated when token is token1)\n *\n * @throws Error if calculated tick is out of bounds [-887272, 887272]\n *\n * @example\n * ```ts\n * // With WETH numeraire on Base:\n * const tick = marketCapToTick(\n *   1_000_000,             // $1M market cap\n *   parseEther('1000000000'), // 1B tokens\n *   3000,                  // ETH = $3000\n *   18, 18,                // both 18 decimals\n *   60,                    // tick spacing\n *   '0x4200000000000000000000000000000000000006' // WETH address\n * )\n * // Returns negative tick (e.g., -149100) because token will be token1\n * ```\n */\nexport function marketCapToTick(\n  marketCapUSD: number,\n  tokenSupply: bigint,\n  numerairePriceUSD: number,\n  tokenDecimals: number = 18,\n  numeraireDecimals: number = 18,\n  tickSpacing: number,\n  numeraire: Address\n): number {\n  // Determine token ordering from numeraire address\n  const tokenIsToken1 = !isToken0Expected(numeraire)\n\n  // Step 1: Market cap → token price\n  const tokenPrice = marketCapToTokenPrice(marketCapUSD, tokenSupply, tokenDecimals)\n\n  // Step 2: Token price → ratio\n  const ratio = tokenPriceToRatio(\n    tokenPrice,\n    numerairePriceUSD,\n    tokenDecimals,\n    numeraireDecimals\n  )\n\n  // Step 3: Ratio → raw tick\n  const rawTick = ratioToTick(ratio)\n\n  // Step 4: Round to tick spacing using floor division\n  let tick = Math.floor(rawTick / tickSpacing) * tickSpacing\n\n  // Step 5: Handle token ordering\n  // When token is token1: negate tick (V4 multicurve convention)\n  // When token is token0: keep tick as-is\n  // Note: V3 static auctions handle this differently and negate at the builder level\n  if (tokenIsToken1) {\n    tick = -tick\n  }\n\n  // Normalize -0 to 0 (JavaScript quirk: -0 !== 0 in Object.is)\n  if (tick === 0) tick = 0\n\n  // Step 6: Validate bounds\n  if (tick < MIN_TICK || tick > MAX_TICK) {\n    throw new Error(\n      `Calculated tick ${tick} is out of bounds [${MIN_TICK}, ${MAX_TICK}]. ` +\n        `Market cap ${marketCapUSD.toLocaleString()} may be too extreme for the given parameters.`\n    )\n  }\n\n  return tick\n}\n\n/**\n * Convert a market cap range to tick range\n *\n * Used for V3 Static Auctions and V4 Dynamic Auctions where you need\n * a start and end tick for the bonding curve.\n *\n * **Important**: This function applies token ordering via marketCapToTick\n * (negates ticks when token is token1), then normalizes so startTick < endTick.\n *\n * Due to the negation + normalization:\n * - When token is token1: both ticks are NEGATIVE\n *   - startTick = more negative (corresponds to LOWER market cap)\n *   - endTick = less negative (corresponds to HIGHER market cap)\n * - When token is token0: both ticks are POSITIVE\n *   - startTick = smaller positive (corresponds to LOWER market cap)\n *   - endTick = larger positive (corresponds to HIGHER market cap)\n *\n * Builders apply additional transformations based on auction type semantics.\n * See builder implementations for auction-specific tick handling.\n *\n * @param marketCapRange - Start and end market caps in USD (start < end required)\n * @param tokenSupply - Total token supply (with decimals)\n * @param numerairePriceUSD - Price of numeraire in USD\n * @param tokenDecimals - Token decimals (default: 18)\n * @param numeraireDecimals - Numeraire decimals (default: 18)\n * @param tickSpacing - Tick spacing\n * @param numeraire - Address of the numeraire token. Used to determine token ordering.\n * @returns Object with startTick and endTick (startTick < endTick numerically)\n *\n * @throws Error if start >= end market cap or if ticks are out of bounds\n *\n * @example\n * ```ts\n * // With WETH numeraire on Base:\n * const { startTick, endTick } = marketCapRangeToTicks(\n *   { start: 500_000, end: 50_000_000 },  // $500k → $50M\n *   parseEther('1000000000'),\n *   3000,\n *   18, 18,\n *   60,\n *   '0x4200000000000000000000000000000000000006' // WETH address\n * )\n * // Returns: startTick=-156080 (500k), endTick=-110020 (50M)\n * // Note: startTick < endTick, but startTick corresponds to LOWER market cap\n * ```\n */\nexport function marketCapRangeToTicks(\n  marketCapRange: MarketCapRange,\n  tokenSupply: bigint,\n  numerairePriceUSD: number,\n  tokenDecimals: number = 18,\n  numeraireDecimals: number = 18,\n  tickSpacing: number,\n  numeraire: Address\n): { startTick: number; endTick: number } {\n  if (marketCapRange.start <= 0 || marketCapRange.end <= 0) {\n    throw new Error('Market cap values must be positive')\n  }\n\n  if (marketCapRange.start >= marketCapRange.end) {\n    throw new Error('Start market cap must be less than end market cap')\n  }\n\n  const tickStart = marketCapToTick(\n    marketCapRange.start,\n    tokenSupply,\n    numerairePriceUSD,\n    tokenDecimals,\n    numeraireDecimals,\n    tickSpacing,\n    numeraire\n  )\n\n  const tickEnd = marketCapToTick(\n    marketCapRange.end,\n    tokenSupply,\n    numerairePriceUSD,\n    tokenDecimals,\n    numeraireDecimals,\n    tickSpacing,\n    numeraire\n  )\n\n  // Ensure startTick < endTick (Uniswap requirement)\n  const startTick = Math.min(tickStart, tickEnd)\n  const endTick = Math.max(tickStart, tickEnd)\n\n  if (startTick === endTick) {\n    throw new Error(\n      `Market cap range ${marketCapRange.start.toLocaleString()} - ${marketCapRange.end.toLocaleString()} ` +\n        `resulted in same tick (${startTick}). Try a wider range or smaller tick spacing.`\n    )\n  }\n\n  return { startTick, endTick }\n}\n\n/**\n * Transform ticks from marketCapRangeToTicks format to auction contract format.\n *\n * For range-based auctions (Static V3, Dynamic V4), the contracts expect ticks\n * in a specific format based on token ordering. This function handles the\n * negation and swapping required when the token is token1.\n *\n * @param rawStartTick - Start tick from marketCapRangeToTicks (lower market cap)\n * @param rawEndTick - End tick from marketCapRangeToTicks (higher market cap)\n * @param numeraire - Address of the numeraire token. Used to determine token ordering.\n * @returns Transformed ticks ready for auction contract\n *\n * @example\n * ```ts\n * const { startTick: raw1, endTick: raw2 } = marketCapRangeToTicks(...)\n * const { startTick, endTick } = transformTicksForAuction(raw1, raw2, WETH_ADDRESS)\n * ```\n */\nexport function transformTicksForAuction(\n  rawStartTick: number,\n  rawEndTick: number,\n  numeraire: Address\n): { startTick: number; endTick: number } {\n  const tokenIsToken1 = !isToken0Expected(numeraire)\n\n  if (tokenIsToken1) {\n    // For token1: negate and swap to satisfy contract requirements\n    // Raw ticks are negative, negating makes them positive, swapping maintains startTick < endTick\n    return {\n      startTick: -rawEndTick,\n      endTick: -rawStartTick,\n    }\n  }\n\n  // For token0: use raw ticks as-is\n  return { startTick: rawStartTick, endTick: rawEndTick }\n}\n\n/**\n * Apply curvature offsets to a peg tick for Multicurve positions\n *\n * Multicurve positions are defined relative to a \"peg\" tick (starting market cap).\n * Offsets define how far above/below the peg each curve extends.\n *\n * Token ordering (determined from numeraire address) affects how offsets are applied:\n * - token1: tickLower = pegTick + offsetLower, tickUpper = pegTick + offsetUpper\n * - token0: tickLower = pegTick - offsetUpper, tickUpper = pegTick - offsetLower\n *\n * @param pegTick - Base tick calculated from starting market cap\n * @param offsetLower - Lower offset in ticks (distance from peg)\n * @param offsetUpper - Upper offset in ticks (distance from peg)\n * @param numeraire - Address of the numeraire token. Used to determine token ordering.\n * @returns Tick range with offsets applied\n *\n * @example\n * ```ts\n * // Peg at -200000, curve from peg to 10000 ticks above (WETH numeraire)\n * const { tickLower, tickUpper } = applyTickOffsets(\n *   -200000, 0, 10000,\n *   '0x4200000000000000000000000000000000000006'\n * )\n * // Returns: { tickLower: -200000, tickUpper: -190000 }\n * ```\n */\nexport function applyTickOffsets(\n  pegTick: number,\n  offsetLower: number,\n  offsetUpper: number,\n  numeraire: Address\n): { tickLower: number; tickUpper: number } {\n  const tokenIsToken1 = !isToken0Expected(numeraire)\n\n  if (tokenIsToken1) {\n    // For token1, add offsets directly\n    return {\n      tickLower: pegTick + offsetLower,\n      tickUpper: pegTick + offsetUpper,\n    }\n  } else {\n    // For token0, subtract offsets in reverse order\n    return {\n      tickLower: pegTick - offsetUpper,\n      tickUpper: pegTick - offsetLower,\n    }\n  }\n}\n\n/**\n * Convert a market cap range to tick range for Multicurve curves.\n *\n * Unlike range-based auctions, Multicurve curves use ticks directly without\n * the negate-and-swap transformation. This function converts market cap\n * bounds to the appropriate tick bounds based on token ordering.\n *\n * @param marketCapLower - Lower market cap bound in USD\n * @param marketCapUpper - Upper market cap bound in USD\n * @param tokenSupply - Total token supply (with decimals)\n * @param numerairePriceUSD - Price of numeraire in USD\n * @param tokenDecimals - Token decimals (default: 18)\n * @param numeraireDecimals - Numeraire decimals (default: 18)\n * @param tickSpacing - Tick spacing\n * @param numeraire - Address of the numeraire token\n * @returns Tick range { tickLower, tickUpper } where tickLower < tickUpper\n *\n * @example\n * ```ts\n * const { tickLower, tickUpper } = marketCapRangeToTicksForCurve(\n *   500_000,    // $500k lower\n *   1_000_000,  // $1M upper\n *   parseEther('1000000000'),\n *   3000,\n *   18, 18,\n *   60,\n *   WETH_ADDRESS\n * )\n * ```\n */\nexport function marketCapRangeToTicksForCurve(\n  marketCapLower: number,\n  marketCapUpper: number,\n  tokenSupply: bigint,\n  numerairePriceUSD: number,\n  tokenDecimals: number = 18,\n  numeraireDecimals: number = 18,\n  tickSpacing: number,\n  numeraire: Address\n): { tickLower: number; tickUpper: number } {\n  if (marketCapLower <= 0 || marketCapUpper <= 0) {\n    throw new Error('Market cap values must be positive')\n  }\n\n  if (marketCapLower >= marketCapUpper) {\n    throw new Error('Lower market cap must be less than upper market cap')\n  }\n\n  // Get ticks for both bounds\n  const tickAtLower = marketCapToTick(\n    marketCapLower,\n    tokenSupply,\n    numerairePriceUSD,\n    tokenDecimals,\n    numeraireDecimals,\n    tickSpacing,\n    numeraire\n  )\n\n  const tickAtUpper = marketCapToTick(\n    marketCapUpper,\n    tokenSupply,\n    numerairePriceUSD,\n    tokenDecimals,\n    numeraireDecimals,\n    tickSpacing,\n    numeraire\n  )\n\n  // Ensure tickLower < tickUpper (may need to swap depending on token ordering)\n  const tickLower = Math.min(tickAtLower, tickAtUpper)\n  const tickUpper = Math.max(tickAtLower, tickAtUpper)\n\n  if (tickLower === tickUpper) {\n    throw new Error(\n      `Market cap range $${marketCapLower.toLocaleString()} - $${marketCapUpper.toLocaleString()} ` +\n        `resulted in same tick (${tickLower}). Try a wider range or smaller tick spacing.`\n    )\n  }\n\n  return { tickLower, tickUpper }\n}\n\n/**\n * Validate market cap parameters and return warnings for unusual values\n *\n * This doesn't prevent execution but helps catch potential mistakes:\n * - Very small market caps (< $1,000)\n * - Very large market caps (> $1 trillion)\n * - Extreme token prices (< $0.000001 or > $1M)\n *\n * @param marketCap - Market cap value to validate\n * @param tokenSupply - Token supply (with decimals)\n * @param tokenDecimals - Token decimals (default: 18)\n * @returns Validation result with warnings array\n *\n * @example\n * ```ts\n * const result = validateMarketCapParameters(500, parseEther('1000000'))\n * if (result.warnings.length > 0) {\n *   console.warn('Warnings:', result.warnings)\n * }\n * ```\n */\nexport function validateMarketCapParameters(\n  marketCap: number,\n  tokenSupply: bigint,\n  tokenDecimals: number = 18\n): MarketCapValidationResult {\n  const warnings: string[] = []\n\n  // Check for unreasonably small market caps\n  if (marketCap < 1000) {\n    warnings.push(\n      `Market cap $${marketCap.toLocaleString()} is very small. Consider if this is intentional.`\n    )\n  }\n\n  // Check for unreasonably large market caps\n  if (marketCap > 1_000_000_000_000) {\n    warnings.push(\n      `Market cap $${marketCap.toLocaleString()} is very large (> $1T). Verify this is correct.`\n    )\n  }\n\n  // Calculate implied token price\n  const tokenPrice = marketCapToTokenPrice(marketCap, tokenSupply, tokenDecimals)\n\n  // Check for extremely small token prices\n  if (tokenPrice < 0.000001) {\n    warnings.push(\n      `Implied token price $${tokenPrice.toExponential(2)} is very small. ` +\n        `This may cause precision issues.`\n    )\n  }\n\n  // Check for extremely large token prices\n  if (tokenPrice > 1_000_000) {\n    warnings.push(\n      `Implied token price $${tokenPrice.toLocaleString()} is very large. ` +\n        `Verify your token supply and market cap values.`\n    )\n  }\n\n  return {\n    valid: warnings.length === 0,\n    warnings,\n  }\n}\n\n/**\n * Calculate market cap from a tick (reverse conversion)\n *\n * Useful for displaying what market cap a given tick represents.\n *\n * @param tick - Uniswap tick value\n * @param tokenSupply - Total token supply (with decimals)\n * @param numerairePriceUSD - Price of numeraire in USD\n * @param tokenDecimals - Token decimals (default: 18)\n * @param numeraireDecimals - Numeraire decimals (default: 18)\n * @param numeraire - Address of the numeraire token. Used to determine token ordering.\n * @returns Market cap in USD\n *\n * @example\n * ```ts\n * const marketCap = tickToMarketCap(\n *   -192100,\n *   parseEther('1000000000'),\n *   3000,\n *   18, 18,\n *   '0x4200000000000000000000000000000000000006' // WETH address\n * )\n * ```\n */\nexport function tickToMarketCap(\n  tick: number,\n  tokenSupply: bigint,\n  numerairePriceUSD: number,\n  tokenDecimals: number = 18,\n  numeraireDecimals: number = 18,\n  numeraire: Address\n): number {\n  const tokenIsToken1 = !isToken0Expected(numeraire)\n\n  // Reverse the token ordering adjustment\n  // When token IS token1, the tick was negated, so negate again to reverse\n  let adjustedTick = tick\n  if (tokenIsToken1) {\n    adjustedTick = -tick\n  }\n\n  // Tick → ratio (reverse of ratioToTick)\n  const ratio = Math.pow(1.0001, adjustedTick)\n\n  // Ratio → token price (reverse of tokenPriceToRatio)\n  // ratio = (numerairePriceUSD / tokenPriceUSD) * 10^(tokenDecimals - numeraireDecimals)\n  // tokenPriceUSD = numerairePriceUSD / (ratio / decimalAdjustment)\n  const decimalAdjustment = 10 ** (tokenDecimals - numeraireDecimals)\n  const tokenPriceUSD = numerairePriceUSD / (ratio / decimalAdjustment)\n\n  // Token price → market cap (reverse of marketCapToTokenPrice)\n  const supplyNum = Number(tokenSupply) / 10 ** tokenDecimals\n  return tokenPriceUSD * supplyNum\n}\n\n"]}