liquid-sdk 1.0.0 → 1.1.0

package/README.md

@@ -5,16 +5,18 @@ TypeScript SDK for the Liquid Protocol token launcher on Base. Deploy tokens, ma
 ## Installation
 
 ```bash
-npm install liquid-protocol-sdk viem
+npm install liquid-sdk viem
 ```
 
+> **Defaults**: Static 1% fee, 3-tranche liquidity (40%/50%/10% at $500K/$10M/$1B), Sniper Auction MEV (80%→40% over 32s), tick spacing 200, starting tick -230400 (~10 ETH market cap).
+
 ## Quick Start
 
 ```typescript
 import { createPublicClient, createWalletClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { base } from "viem/chains";
-import { LiquidSDK } from "liquid-protocol-sdk";
+import { LiquidSDK } from "liquid-sdk";
 
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 
@@ -47,33 +49,54 @@ console.log("Pool ID:", result.event.poolId);
 console.log("Tx:", result.txHash);
 ```
 
-### Deploy with Custom Configuration
+### Deploy with Custom Market Cap Positions
 
 ```typescript
-import { ADDRESSES, EXTERNAL } from "liquid-protocol-sdk";
+import { createDefaultPositions, createPositionsUSD } from "liquid-sdk";
+
+// Use default 3-tranche split ($500K / $10M / $1B) at current ETH price
+const positions = createDefaultPositions(20_000, 2070); // $20K start, $2070/ETH
 
 const result = await liquid.deployToken({
-  name: "Custom Token",
-  symbol: "CTK",
-
-  // Pool config
-  hook: ADDRESSES.HOOK_STATIC_FEE_V2, // use static fee hook
-  pairedToken: EXTERNAL.WETH,
-  tickSpacing: 60,
-  tickIfToken0IsLiquid: -198720,
-
-  // LP rewards: split 70/30 between creator and platform
-  rewardAdmins: [creatorAddress, platformAddress],
-  rewardRecipients: [creatorAddress, platformAddress],
-  rewardBps: [7000, 3000],
-
-  // Full-range single position
-  tickLower: [-887220],
-  tickUpper: [887220],
-  positionBps: [10000],
-
-  // MEV protection
-  mevModule: ADDRESSES.MEV_BLOCK_DELAY,
+  name: "My Token",
+  symbol: "MTK",
+  ...positions, // tickLower, tickUpper, positionBps, tickIfToken0IsLiquid
+});
+
+// Or define fully custom tranches
+const custom = createPositionsUSD(50_000, 2070, [
+  { upperMarketCapUSD: 1_000_000, supplyPct: 30 },
+  { upperMarketCapUSD: 50_000_000, supplyPct: 50 },
+  { upperMarketCapUSD: 500_000_000, supplyPct: 20 },
+]);
+```
+
+### Deploy with Custom Fees
+
+```typescript
+import { ADDRESSES, encodeStaticFeePoolData, encodeDynamicFeePoolData } from "liquid-sdk";
+
+// Static 2% fee
+const result = await liquid.deployToken({
+  name: "Custom Fee Token",
+  symbol: "CFT",
+  poolData: encodeStaticFeePoolData(200, 200), // 2% both directions
+});
+
+// Dynamic fee (1%-5% range)
+const result2 = await liquid.deployToken({
+  name: "Dynamic Token",
+  symbol: "DYN",
+  hook: ADDRESSES.HOOK_DYNAMIC_FEE_V2,
+  poolData: encodeDynamicFeePoolData({
+    baseFeeBps: 100,
+    maxFeeBps: 500,
+    referenceTickFilterPeriod: 30,
+    resetPeriod: 120,
+    resetTickFilter: 200,
+    feeControlNumerator: 500000000n,
+    decayFilterBps: 7500,
+  }),
 });
 ```
 
@@ -156,20 +179,37 @@ All production addresses, fee parameters, and contract ABIs are exported:
 
 ```typescript
 import {
-  ADDRESSES,     // Liquid Protocol contract addresses
-  EXTERNAL,      // External protocol addresses (PoolManager, WETH, etc.)
-  FEE,           // Fee constants (denominator, protocol fee, max fees)
-  TOKEN,         // Token constants (supply, decimals, max extensions)
-  DEFAULT_CHAIN, // base chain object
+  ADDRESSES,        // Liquid Protocol contract addresses
+  EXTERNAL,         // External protocol addresses (PoolManager, WETH, etc.)
+  FEE,              // Fee constants (denominator, protocol fee, max fees)
+  TOKEN,            // Token constants (supply, decimals, max extensions)
+  DEFAULTS,         // Default deploy config (hook, fees, MEV, ticks)
+  POOL_POSITIONS,   // Position presets (Standard, Liquid)
+  DEFAULT_CHAIN,    // base chain object
   DEFAULT_CHAIN_ID, // 8453
 
+  // Tick math & positions
+  getTickFromMarketCapETH,
+  getTickFromMarketCapUSD,
+  marketCapFromTickETH,
+  marketCapFromTickUSD,
+  createPositions,
+  createPositionsUSD,
+  createDefaultPositions,
+  describePositions,
+
+  // Encoding helpers
+  encodeStaticFeePoolData,
+  encodeDynamicFeePoolData,
+  encodeSniperAuctionData,
+
   // ABIs for direct contract interaction
   LiquidFactoryAbi,
   LiquidFeeLockerAbi,
   LiquidHookDynamicFeeV2Abi,
   LiquidVaultAbi,
   ERC20Abi,
-} from "liquid-protocol-sdk";
+} from "liquid-sdk";
 ```
 
 ## API Reference

package/dist/index.d.mts

@@ -61,15 +61,15 @@ interface DeployTokenParams {
     context?: string;
     tokenAdmin?: Address;
     salt?: Hex;
-    /** Hook address. Defaults to HOOK_DYNAMIC_FEE_V2 */
+    /** Hook address. Defaults to HOOK_STATIC_FEE_V2 (1% fee) */
     hook?: Address;
     /** Quote token. Defaults to WETH */
     pairedToken?: Address;
-    /** Starting tick. Defaults to -198720 (approx $0.001 WETH per token) */
+    /** Starting tick. Defaults to -230400 (≈10 ETH market cap) */
     tickIfToken0IsLiquid?: number;
-    /** Tick spacing. Defaults to 60 */
+    /** Tick spacing. Defaults to 200 */
     tickSpacing?: number;
-    /** Pool-specific hook data */
+    /** Pool-specific hook data. Defaults to static 1% fee encoded for V2 hook */
     poolData?: Hex;
     /** LP locker address. Defaults to LP_LOCKER */
     locker?: Address;
@@ -87,9 +87,9 @@ interface DeployTokenParams {
     positionBps?: number[];
     /** Locker-specific data */
     lockerData?: Hex;
-    /** MEV module address. Defaults to MEV_BLOCK_DELAY */
+    /** MEV module address. Defaults to SNIPER_AUCTION_V2 */
     mevModule?: Address;
-    /** MEV module initialization data */
+    /** MEV module data. Defaults to 80%→40% decay over 32s */
     mevModuleData?: Hex;
     /** Extension configs (vault, airdrop, etc.) */
     extensions?: ExtensionConfig[];
@@ -201,6 +201,11 @@ declare class LiquidSDK {
      * The paired token must be WETH for simple dev buys.
      */
     buildDevBuyExtension(devBuy: DevBuyParams): ExtensionConfig;
+    /**
+     * Validate a DeploymentConfig before sending to the contract.
+     * Catches common mistakes client-side with clear error messages.
+     */
+    private validateDeploymentConfig;
     deployToken(params: DeployTokenParams): Promise<DeployTokenResult>;
     getDeploymentInfo(tokenAddress: Address): Promise<DeploymentInfo>;
     getTokenInfo(tokenAddress: Address): Promise<{
@@ -281,6 +286,55 @@ declare const TOKEN: {
     readonly MAX_EXTENSIONS: 10;
     readonly MAX_EXTENSION_BPS: 9000;
 };
+interface PoolPosition {
+    tickLower: number;
+    tickUpper: number;
+    positionBps: number;
+}
+/**
+ * Pre-built position configurations.
+ *
+ * - **Standard**: Single position covering full range (~$20K → $1.5B).
+ *   Default starting tick -230400 (≈10 ETH market cap).
+ *
+ * - **Liquid**: 3-tranche default for Liquid Protocol.
+ *   Hardcoded for ≈10 ETH start at ~$2070/ETH.
+ *   For dynamic market cap targets, use `createPositionsUSD()` instead.
+ *
+ * Note: positionBps must sum to 10,000 (100%).
+ */
+declare const POOL_POSITIONS: {
+    /** Single position, 100% of liquidity in one range */
+    readonly Standard: PoolPosition[];
+    /** 3-tranche Liquid default (hardcoded for ~10 ETH start, ~$2070/ETH) */
+    readonly Liquid: PoolPosition[];
+};
+/**
+ * Liquid protocol defaults.
+ *
+ * - Hook: Static fee V2, 1% on buys only (fees in ETH), 0% on sells
+ * - MEV: Sniper Auction V2 — 80% → 40% decaying over 32 seconds
+ * - Tick spacing: 200
+ * - Starting tick: -230400 (≈10 ETH market cap)
+ * - Positions: 3-tranche Liquid default (40/50/10)
+ */
+declare const DEFAULTS: {
+    readonly HOOK: `0x${string}`;
+    readonly TICK_SPACING: 200;
+    readonly TICK_IF_TOKEN0_IS_LIQUID: -230400;
+    /** Static fee on buys (ETH → token): 1% (100 bps). Fees collected in ETH. */
+    readonly PAIRED_FEE_BPS: 100;
+    /** Static fee on sells (token → ETH): 0%. No fees in liquid token. */
+    readonly LIQUID_FEE_BPS: 0;
+    /** MEV module: Sniper Auction V2 */
+    readonly MEV_MODULE: `0x${string}`;
+    /** Sniper auction starting fee: 80% (800,000 uniBps) */
+    readonly SNIPER_STARTING_FEE: 800000;
+    /** Sniper auction ending fee: 40% (400,000 uniBps) */
+    readonly SNIPER_ENDING_FEE: 400000;
+    /** Sniper auction decay period: 32 seconds */
+    readonly SNIPER_SECONDS_TO_DECAY: 32;
+};
 declare const DEFAULT_CHAIN: {
     blockExplorers: {
         readonly default: {
@@ -600,6 +654,7 @@ declare const DEFAULT_CHAIN: {
     verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
 };
 declare const DEFAULT_CHAIN_ID = 8453;
+declare const DEFAULT_RPC_URL = "https://base.drpc.org";
 
 declare const LiquidFactoryAbi: readonly [{
     readonly type: "function";
@@ -1632,4 +1687,266 @@ declare const ERC20Abi: readonly [{
     readonly stateMutability: "nonpayable";
 }];
 
-export { ADDRESSES, type AirdropInfo, DEFAULT_CHAIN, DEFAULT_CHAIN_ID, type DeployTokenParams, type DeployTokenResult, type DeploymentConfig, type DeploymentInfo, type DevBuyParams, ERC20Abi, EXTERNAL, type ExtensionConfig, FEE, LiquidAirdropV2Abi, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, LiquidMevBlockDelayAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidVaultAbi, type LockerConfig, type MevModuleConfig, type PoolConfig, type PoolDynamicConfigVars, type PoolDynamicFeeVars, type PoolKey, type SniperAuctionFeeConfig, type SniperAuctionState, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation };
+/**
+ * Tick ↔ market cap conversion utilities for Uniswap V4 concentrated liquidity.
+ *
+ * All tokens have 100B supply (10^11) with 18 decimals.
+ * Price per token = marketCap / totalSupply.
+ * Tick = log(price) / log(1.0001), aligned to tickSpacing.
+ */
+/**
+ * Convert an ETH-denominated market cap to a Uniswap V4 tick.
+ *
+ * @param marketCapETH - Market cap in ETH (e.g. 10 for a 10 ETH starting cap)
+ * @param tickSpacing - Tick spacing to align to (default 200)
+ * @returns Tick value (int24) aligned to tickSpacing
+ *
+ * @example
+ * ```ts
+ * getTickFromMarketCapETH(10)   // → -230400  (≈10 ETH market cap)
+ * getTickFromMarketCapETH(200)  // → -200200  (≈200 ETH)
+ * ```
+ */
+declare function getTickFromMarketCapETH(marketCapETH: number, tickSpacing?: number): number;
+/**
+ * Convert a USD-denominated market cap to a Uniswap V4 tick.
+ *
+ * @param marketCapUSD - Market cap in USD (e.g. 500_000 for $500K)
+ * @param ethPriceUSD - Current ETH price in USD (e.g. 2070)
+ * @param tickSpacing - Tick spacing to align to (default 200)
+ * @returns Tick value (int24) aligned to tickSpacing
+ *
+ * @example
+ * ```ts
+ * getTickFromMarketCapUSD(500_000, 2070)    // tick for $500K market cap
+ * getTickFromMarketCapUSD(10_000_000, 2070) // tick for $10M market cap
+ * ```
+ */
+declare function getTickFromMarketCapUSD(marketCapUSD: number, ethPriceUSD: number, tickSpacing?: number): number;
+/**
+ * Convert a tick back to an ETH-denominated market cap.
+ *
+ * @param tick - Uniswap V4 tick value
+ * @returns Market cap in ETH
+ *
+ * @example
+ * ```ts
+ * marketCapFromTickETH(-230400)  // ≈ 10 ETH
+ * ```
+ */
+declare function marketCapFromTickETH(tick: number): number;
+/**
+ * Convert a tick to a USD-denominated market cap.
+ *
+ * @param tick - Uniswap V4 tick value
+ * @param ethPriceUSD - Current ETH price in USD
+ * @returns Market cap in USD
+ */
+declare function marketCapFromTickUSD(tick: number, ethPriceUSD: number): number;
+/**
+ * Convert a market cap in a stablecoin to a tick.
+ * Supports any stablecoin decimal count (6 for USDC, 18 for DAI, etc.)
+ *
+ * @param marketCap - Market cap in stablecoin units
+ * @param stableDecimals - Decimals of the stablecoin (e.g. 6 for USDC)
+ * @param tickSpacing - Tick spacing (default 200)
+ * @returns Tick value aligned to tickSpacing
+ */
+declare function getTickFromMarketCapStable(marketCap: number, stableDecimals: number, tickSpacing?: number): number;
+
+/**
+ * Multi-tranche liquidity position builder.
+ *
+ * Creates position arrays (tickLower[], tickUpper[], positionBps[]) from
+ * market cap milestones. Percentages represent share of the *pool supply*
+ * (i.e. after dev buy, airdrop, and vault allocations are deducted).
+ */
+interface MarketCapTranche {
+    /** Upper bound market cap in ETH for this tranche */
+    upperMarketCapETH: number;
+    /** Percentage of pool supply allocated to this tranche (1-100) */
+    supplyPct: number;
+}
+interface MarketCapTrancheUSD {
+    /** Upper bound market cap in USD for this tranche */
+    upperMarketCapUSD: number;
+    /** Percentage of pool supply allocated to this tranche (1-100) */
+    supplyPct: number;
+}
+interface PositionConfig {
+    tickLower: number;
+    tickUpper: number;
+    positionBps: number;
+}
+interface PositionArrays {
+    tickLower: number[];
+    tickUpper: number[];
+    positionBps: number[];
+}
+/**
+ * Default Liquid tranches (USD-denominated).
+ *
+ * - Starting → $500K market cap: 40% of pool supply
+ * - $500K → $10M market cap:     50% of pool supply
+ * - $10M → $1B market cap:       10% of pool supply
+ */
+declare const DEFAULT_TRANCHES_USD: MarketCapTrancheUSD[];
+/**
+ * Build position arrays from ETH-denominated market cap tranches.
+ *
+ * @param startingMarketCapETH - Initial market cap in ETH (determines the starting tick)
+ * @param tranches - Array of tranches with upper market cap bounds and supply percentages
+ * @param tickSpacing - Tick spacing (default 200)
+ * @returns Position arrays ready to pass to `deployToken()`
+ *
+ * @example
+ * ```ts
+ * const positions = createPositions(10, [
+ *   { upperMarketCapETH: 241.5, supplyPct: 40 },  // ~$500K at $2070/ETH
+ *   { upperMarketCapETH: 4830,  supplyPct: 50 },   // ~$10M
+ *   { upperMarketCapETH: 483050, supplyPct: 10 },   // ~$1B
+ * ]);
+ * // → { tickLower: [-230400, -198600, -168600],
+ * //     tickUpper: [-198600, -168600, -122400],
+ * //     positionBps: [4000, 5000, 1000] }
+ * ```
+ */
+declare function createPositions(startingMarketCapETH: number, tranches: MarketCapTranche[], tickSpacing?: number): PositionArrays;
+/**
+ * Build position arrays from USD-denominated market cap tranches.
+ * Convenience wrapper that converts USD → ETH using the provided ETH price.
+ *
+ * @param startingMarketCapUSD - Initial market cap in USD
+ * @param ethPriceUSD - Current ETH price in USD
+ * @param tranches - Array of tranches with upper USD market cap bounds
+ * @param tickSpacing - Tick spacing (default 200)
+ * @returns Position arrays ready to pass to `deployToken()`
+ *
+ * @example
+ * ```ts
+ * const positions = createPositionsUSD(20_000, 2070, [
+ *   { upperMarketCapUSD: 500_000,       supplyPct: 40 },
+ *   { upperMarketCapUSD: 10_000_000,    supplyPct: 50 },
+ *   { upperMarketCapUSD: 1_000_000_000, supplyPct: 10 },
+ * ]);
+ * ```
+ */
+declare function createPositionsUSD(startingMarketCapUSD: number, ethPriceUSD: number, tranches: MarketCapTrancheUSD[], tickSpacing?: number): PositionArrays;
+/**
+ * Build default Liquid positions using the standard 3-tranche split.
+ *
+ * - Starting → $500K:  40% of pool supply
+ * - $500K → $10M:      50% of pool supply
+ * - $10M → $1B:        10% of pool supply
+ *
+ * @param startingMarketCapUSD - Initial market cap in USD (e.g. 20_000 for ~10 ETH)
+ * @param ethPriceUSD - Current ETH price in USD
+ * @param tickSpacing - Tick spacing (default 200)
+ *
+ * @example
+ * ```ts
+ * const positions = createDefaultPositions(20_000, 2070);
+ * const tx = await sdk.deployToken({
+ *   name: "MyToken",
+ *   symbol: "MTK",
+ *   ...positions,
+ * });
+ * ```
+ */
+declare function createDefaultPositions(startingMarketCapUSD: number, ethPriceUSD: number, tickSpacing?: number): PositionArrays & {
+    tickIfToken0IsLiquid: number;
+};
+/**
+ * Describe positions as human-readable market cap ranges.
+ * Useful for displaying position info in UIs.
+ *
+ * @param positions - Position arrays
+ * @param ethPriceUSD - Optional ETH price for USD display
+ */
+declare function describePositions(positions: PositionArrays, ethPriceUSD?: number): Array<{
+    index: number;
+    tickLower: number;
+    tickUpper: number;
+    supplyPct: number;
+    marketCapLowerETH: number;
+    marketCapUpperETH: number;
+    marketCapLowerUSD?: number;
+    marketCapUpperUSD?: number;
+}>;
+
+/**
+ * ABI encoding helpers for pool data, fee configs, and MEV module data.
+ */
+
+/**
+ * Encode pool data for the static fee V2 hook.
+ *
+ * Uses two-layer encoding:
+ * 1. Inner: static fee params [liquidFee, pairedFee] in uniBps
+ * 2. Outer: PoolInitializationData wrapper
+ *
+ * @param liquidFeeBps - Fee when swapping for the liquid token (in bps, e.g. 100 = 1%)
+ * @param pairedFeeBps - Fee when swapping for the paired token (in bps, e.g. 100 = 1%)
+ * @param extension - Optional pool extension address (defaults to zero)
+ * @param extensionData - Optional pool extension init data (defaults to "0x")
+ * @returns Encoded poolData hex string
+ *
+ * @example
+ * ```ts
+ * // 1% fee both directions (default)
+ * const poolData = encodeStaticFeePoolData(100, 100);
+ * ```
+ */
+declare function encodeStaticFeePoolData(liquidFeeBps: number, pairedFeeBps: number, extension?: `0x${string}`, extensionData?: Hex): Hex;
+interface DynamicFeeConfig {
+    /** Base LP fee in bps (e.g. 100 = 1%) */
+    baseFeeBps: number;
+    /** Max LP fee in bps (e.g. 500 = 5%) */
+    maxFeeBps: number;
+    /** Reference tick filter period in seconds */
+    referenceTickFilterPeriod: number;
+    /** Reset period in seconds */
+    resetPeriod: number;
+    /** Reset tick filter (tick units) */
+    resetTickFilter: number;
+    /** Fee control numerator (scaling constant) */
+    feeControlNumerator: bigint;
+    /** Decay filter in bps */
+    decayFilterBps: number;
+}
+/**
+ * Encode pool data for the dynamic fee V2 hook.
+ *
+ * @param config - Dynamic fee configuration
+ * @param extension - Optional pool extension address
+ * @param extensionData - Optional pool extension init data
+ * @returns Encoded poolData hex string
+ */
+declare function encodeDynamicFeePoolData(config: DynamicFeeConfig, extension?: `0x${string}`, extensionData?: Hex): Hex;
+interface SniperAuctionConfig {
+    /** Starting fee in uniBps (e.g. 800_000 = 80%) */
+    startingFee: number;
+    /** Ending fee in uniBps (e.g. 400_000 = 40%) */
+    endingFee: number;
+    /** Seconds for fee to decay from starting to ending */
+    secondsToDecay: number;
+}
+/**
+ * Encode MEV module data for the Sniper Auction V2.
+ *
+ * @param config - Sniper auction fee configuration
+ * @returns Encoded mevModuleData hex string
+ *
+ * @example
+ * ```ts
+ * // 80% → 40% over 32 seconds (default)
+ * const mevData = encodeSniperAuctionData({
+ *   startingFee: 800_000,
+ *   endingFee: 400_000,
+ *   secondsToDecay: 32,
+ * });
+ * ```
+ */
+declare function encodeSniperAuctionData(config: SniperAuctionConfig): Hex;
+
+export { ADDRESSES, type AirdropInfo, DEFAULTS, DEFAULT_CHAIN, DEFAULT_CHAIN_ID, DEFAULT_RPC_URL, DEFAULT_TRANCHES_USD, type DeployTokenParams, type DeployTokenResult, type DeploymentConfig, type DeploymentInfo, type DevBuyParams, type DynamicFeeConfig, ERC20Abi, EXTERNAL, type ExtensionConfig, FEE, LiquidAirdropV2Abi, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, LiquidMevBlockDelayAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidVaultAbi, type LockerConfig, type MarketCapTranche, type MarketCapTrancheUSD, type MevModuleConfig, POOL_POSITIONS, type PoolConfig, type PoolDynamicConfigVars, type PoolDynamicFeeVars, type PoolKey, type PoolPosition, type PositionArrays, type PositionConfig, type SniperAuctionConfig, type SniperAuctionFeeConfig, type SniperAuctionState, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, createDefaultPositions, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD };