liquid-sdk 1.7.2 → 1.7.4

package/AGENT_README.md

@@ -35,7 +35,7 @@ No API keys, no backend, no database. The SDK talks directly to Base mainnet con
 Liquid Protocol deploys ERC-20 tokens on Base with:
 - Uniswap V4 liquidity pools (automatic)
 - LP fee collection and reward distribution
-- MEV protection via block delay
+- MEV protection via sniper auction
 - Optional extensions: dev buy, vault lockup/vesting, airdrops
 
 Every token gets 100 billion supply (18 decimals), a Uniswap V4 pool, and locked liquidity with configurable reward splits.
@@ -161,7 +161,7 @@ const txHash = await sdk.collectRewardsWithoutUnlock(tokenAddress);
 await publicClient.waitForTransactionReceipt({ hash: txHash });
 ```
 
-**Important:** After deployment, the pool is locked for a MEV block delay. `collectRewardsWithoutUnlock` may revert with `ManagerLocked` if called too soon. Use `getPoolUnlockTime` to check.
+**Important:** After deployment, the sniper auction MEV module may block early reward collection. If `collectRewardsWithoutUnlock` reverts with `ManagerLocked`, wait for the auction period to end.
 
 #### `sdk.updateRewardRecipient(tokenAddress, rewardIndex, newRecipient)` — Change reward recipient
 
@@ -455,21 +455,23 @@ const result = await sdk.bidInAuction({
 
 ---
 
-### MEV Protection
+### MEV Descending Fees
 
-#### `sdk.getMevBlockDelay()` — Get configured block delay
+#### `sdk.getMevDescendingFeesBlockDelay()` — Configured block delay
 
 ```typescript
-const delay = await sdk.getMevBlockDelay();
-// delay: bigint — number of blocks
+const delay = await sdk.getMevDescendingFeesBlockDelay();
+// delay: bigint — number of blocks the MEV module fee window covers
 ```
 
-#### `sdk.getPoolUnlockTime(poolId)` — When does MEV lock expire
+`sdk.getMevBlockDelay()` is a deprecated alias for the same call.
+
+#### `sdk.getPoolUnlockTime(poolId)` — When MEV lock expires
 
 ```typescript
 const unlockTime = await sdk.getPoolUnlockTime(poolId);
-// unlockTime: bigint — unix timestamp
-// If Date.now()/1000 < unlockTime, pool is still locked
+// If Date.now()/1000 < unlockTime, the pool is still inside the MEV window
+// and writes that go through the MevDescendingFees hook may revert with ManagerLocked.
 ```
 
 ---
@@ -516,9 +518,9 @@ When calling `deployToken`, all fields except `name` and `symbol` are optional.
 | `rewardAdmins` | `[walletAddress]` | Deployer is admin |
 | `rewardRecipients` | `[walletAddress]` | Deployer gets rewards |
 | `rewardBps` | `[10000]` | 100% to deployer |
-| `tickLower` | `[-230400, -198600, -168600]` | 3-tranche Liquid default |
-| `tickUpper` | `[-198600, -168600, -122600]` | 3-tranche Liquid default |
-| `positionBps` | `[4000, 5000, 1000]` | 40% / 50% / 10% |
+| `tickLower` | `[-230400, -216000, -202000, -155000, -141000]` | 5-position Liquid layout |
+| `tickUpper` | `[-216000, -155000, -155000, -120000, -120000]` | 5-position Liquid layout |
+| `positionBps` | `[1000, 5000, 1500, 2000, 500]` | 10% / 50% / 15% / 20% / 5% |
 | `mevModule` | `ADDRESSES.SNIPER_AUCTION_V2` | 80%→40% over 20s |
 | `extensions` | `[]` | No extensions |
 
@@ -587,7 +589,8 @@ import {
   LiquidSniperUtilV2Abi,
   LiquidAirdropV2Abi,
   LiquidPoolExtensionAllowlistAbi,
-  LiquidMevBlockDelayAbi,
+  LiquidMevDescendingFeesAbi,
+  LiquidMevBlockDelayAbi, // deprecated alias — prefer LiquidMevDescendingFeesAbi
   LiquidLpLockerAbi,
   ERC20Abi,
 } from "liquid-sdk";

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `liquid-sdk` will be documented in this file.
 
+## [1.7.4] - 2026-04-23
+
+### Added
+- `EXTERNAL.DIEM` — the DIEM token address on Base, for DIEM-paired token launches.
+- `shiftPositions(positions, shiftBy)` — re-anchor a fixed-shape position layout to a different starting tick, preserving `positionBps`.
+- `createLiquidPositionsUSD(startingMarketCapUSD, pairedTokenPriceUSD, tickSpacing?)` — the canonical 5-position "Liquid" layout re-anchored to a starting market cap, denominated in the *paired token's* USD price. Works for any pair token (WETH or DIEM); unlike `createDefaultPositions` (3-tranche), it preserves the exact `POOL_POSITIONS.Liquid` curve `deployToken()` uses by default.
+
+### Fixed
+- `deployToken` gas estimation no longer silently swallows on-chain revert errors. Previously a failing `eth_estimateGas` (e.g., insufficient msg.value, paused factory, pre-flight check revert) would be caught and replaced with a 6M fallback, causing the tx to be broadcast and burn real gas for nothing. Now a revert-shaped error bubbles to the caller; only transport-level failures fall back. Non-revert fallbacks log a warning via `console.warn`.
+
+## [1.7.3] - 2026-04-22
+
+### Added
+- `buildAirdropExtension({ admin, merkleRoot, allocationBps, lockupDuration, vestingDuration })` — creates a `LiquidAirdropV2` extension config for use in `deployToken({ extensions: [...] })`. Double-hashed leaf format compatible with OpenZeppelin `MerkleProof`. Contract minimums enforced (1-day lockup, ≤90% allocation).
+
+### Fixed
+- `deployToken` no longer uses a hard-coded `gas: 5_000_000n` — real mainnet deploys currently require ~5.04M gas. Now uses `estimateContractGas * 1.2` with a 6M fallback so the SDK auto-adjusts as the factory evolves. Previous versions could OOG on mainnet.
+
+### Verified
+- End-to-end airdrop flow fork-tested against Base mainnet (real `LiquidAirdropV2` at `0x1423974d48f525462f1c087cBFdCC20BDBc33CdD`): deploy → state register → claim with single-leaf proof all confirmed.
+- Mainnet dry-run deploy confirmed on-chain state encoding: [basescan tx](https://basescan.org/tx/0x1807c1e3eb92ccb0c32779855cd35d5581e6143d4232f4ab66d39517ee86e3d0).
+
 ## [1.2.0] - 2025-03-10
 
 ### Added

package/dist/index.d.mts

@@ -63,6 +63,21 @@ interface VaultExtensionParams {
     /** Vesting duration in seconds after lockup ends (0 = no vesting, tokens unlock all at once) */
     vestingDuration?: number;
 }
+interface AirdropExtensionParams {
+    /** Address allowed to `updateAdmin`, `updateMerkleRoot` (under conditions),
+     *  and `adminClaim` the remainder after claim expiration. */
+    admin: Address;
+    /** Merkle root over leaves `keccak256(bytes.concat(keccak256(abi.encode(
+     *  recipient, allocatedAmount))))`. Double-hashed per OZ convention. */
+    merkleRoot: Hex;
+    /** Percentage of supply to reserve for the airdrop, in BPS (1–9000). */
+    allocationBps: number;
+    /** Lockup in seconds before any recipient can claim. Min 86400 (1 day). */
+    lockupDuration: number;
+    /** Linear vesting after lockup. 0 = instant claim of full entitlement at
+     *  lockup end. */
+    vestingDuration?: number;
+}
 interface DeployTokenParams {
     name: string;
     symbol: string;
@@ -270,6 +285,29 @@ declare class LiquidSDK {
      * ```
      */
     buildVaultExtension(vault: VaultExtensionParams): ExtensionConfig;
+    /**
+     * Build an ExtensionConfig that reserves a percentage of supply into
+     * the LiquidAirdropV2 contract for merkle-tree-based distribution.
+     *
+     * The airdrop contract expects `AirdropV2ExtensionData`:
+     *   { address admin, bytes32 merkleRoot, uint256 lockupDuration, uint256 vestingDuration }
+     *
+     * Leaf encoding used by LiquidAirdropV2.claim (note: **double hashed**
+     * — OZ's standard 2nd-preimage-resistant pattern):
+     *   leaf = keccak256(bytes.concat(keccak256(abi.encode(recipient, allocatedAmount))))
+     *
+     * @example
+     * ```typescript
+     * const airdropExt = sdk.buildAirdropExtension({
+     *   admin: account.address,
+     *   merkleRoot: "0x…",
+     *   allocationBps: 2000,          // 20%
+     *   lockupDuration: 86400,        // 1 day (minimum)
+     *   vestingDuration: 0,           // instant claim after lockup
+     * });
+     * ```
+     */
+    buildAirdropExtension(airdrop: AirdropExtensionParams): ExtensionConfig;
     /**
      * Validate a DeploymentConfig before sending to the contract.
      * Catches common mistakes client-side with clear error messages.
@@ -433,6 +471,9 @@ declare const ADDRESSES: {
 declare const EXTERNAL: {
     readonly POOL_MANAGER: Address;
     readonly WETH: Address;
+    /** DIEM — Liquid's intelligence-economy token. Also a pair token for
+     *  agent-token launches (see `createLiquidPositionsUSD`). */
+    readonly DIEM: Address;
     readonly UNIVERSAL_ROUTER: Address;
     readonly PERMIT2: Address;
 };
@@ -489,7 +530,7 @@ declare const POOL_POSITIONS: {
  */
 declare const DEFAULTS: {
     readonly HOOK: `0x${string}`;
-    /** LP Locker with fee conversion (converts fees to ETH before distributing) */
+    /** LP Locker with fee conversion (converts fees to WETH before distributing) */
     readonly LOCKER: `0x${string}`;
     readonly TICK_SPACING: 200;
     readonly TICK_IF_TOKEN0_IS_LIQUID: -230400;
@@ -583,31 +624,7 @@ declare const DEFAULT_CHAIN: {
     formatters: {
         readonly block: {
             exclude: [] | undefined;
-            format: (args: viem_chains.OpStackRpcBlock, action
-            /**
-             * 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%).
-             */
-            ? /**
-             * 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%).
-             */: string | undefined) => {
+            format: (args: viem_chains.OpStackRpcBlock, action?: string | undefined) => {
                 baseFeePerGas: bigint | null;
                 blobGasUsed: bigint;
                 difficulty: bigint;
@@ -2285,6 +2302,7 @@ declare function getTickFromMarketCapStable(marketCap: number, stableDecimals: n
  * 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;
@@ -2380,6 +2398,55 @@ declare function createPositionsUSD(startingMarketCapUSD: number, ethPriceUSD: n
 declare function createDefaultPositions(startingMarketCapUSD: number, ethPriceUSD: number, tickSpacing?: number): PositionArrays & {
     tickIfToken0IsLiquid: number;
 };
+/**
+ * Shift every tick in a position layout by a fixed amount, preserving the
+ * positionBps splits. The primitive behind `createLiquidPositionsUSD` — it
+ * re-anchors a fixed-shape layout (e.g. `POOL_POSITIONS.Liquid`) to a
+ * different starting tick.
+ *
+ * `shiftBy` should be a multiple of the pool's tick spacing so the shifted
+ * ticks stay aligned. A difference of two aligned ticks is always aligned,
+ * so deriving it as `targetTick - sourceBottomTick` is safe.
+ *
+ * @param positions - Source positions (e.g. `POOL_POSITIONS.Liquid`)
+ * @param shiftBy - Ticks to add to every tickLower/tickUpper (may be negative)
+ * @returns A fresh array — the source is not mutated
+ */
+declare function shiftPositions(positions: readonly PoolPosition[], shiftBy: number): PoolPosition[];
+/**
+ * Build the canonical 5-position "Liquid" layout (10/50/15/20/5) re-anchored
+ * to a starting market cap, denominated in the *paired token's* USD price.
+ *
+ * Works for any pair token — pass the price of whatever the pool is paired
+ * against:
+ *   - WETH-paired: `createLiquidPositionsUSD(20_000, ethPriceUSD)`
+ *   - DIEM-paired: `createLiquidPositionsUSD(20_000, diemPriceUSD)`
+ *
+ * Unlike `createDefaultPositions` (a 3-tranche layout), this preserves the
+ * exact shape of `POOL_POSITIONS.Liquid` — the same curve `deployToken()`
+ * uses by default — just shifted so its bottom sits at the requested start.
+ *
+ * @param startingMarketCapUSD - Initial market cap in USD
+ * @param pairedTokenPriceUSD - USD price of the token the pool is paired against
+ * @param tickSpacing - Tick spacing (default 200)
+ * @returns Position arrays + `tickIfToken0IsLiquid`, ready to spread into `deployToken()`
+ *
+ * @example
+ * ```ts
+ * import { LiquidSDK, EXTERNAL, createLiquidPositionsUSD } from "liquid-sdk";
+ *
+ * const positions = createLiquidPositionsUSD(20_000, diemPriceUSD);
+ * await sdk.deployToken({
+ *   name: "Agent Token",
+ *   symbol: "AGENT",
+ *   pairedToken: EXTERNAL.DIEM,
+ *   ...positions,
+ * });
+ * ```
+ */
+declare function createLiquidPositionsUSD(startingMarketCapUSD: number, pairedTokenPriceUSD: number, tickSpacing?: number): PositionArrays & {
+    tickIfToken0IsLiquid: number;
+};
 /**
  * Describe positions as human-readable market cap ranges.
  * Useful for displaying position info in UIs.
@@ -2496,7 +2563,7 @@ declare enum FeePreference {
  *
  * @example
  * ```ts
- * // Single recipient, fees converted to ETH
+ * // Single recipient, fees converted to WETH
  * const lockerData = encodeFeeConversionLockerData([FeePreference.Paired]);
  *
  * // Two recipients: first gets ETH, second gets the token
@@ -2557,4 +2624,4 @@ declare function parseContext(contextString: string): LiquidContext | null;
  */
 declare function parseMetadata(metadataString: string): LiquidMetadata | null;
 
-export { ADDRESSES, type AirdropInfo, type BidInAuctionParams, type BidInAuctionResult, 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, FeePreference, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidMevDescendingFeesAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, 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, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, type VaultExtensionParams, buildContext, buildMetadata, createDefaultPositions, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeFeeConversionLockerData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata };
+export { ADDRESSES, type AirdropExtensionParams, type AirdropInfo, type BidInAuctionParams, type BidInAuctionResult, 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, FeePreference, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidMevDescendingFeesAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, 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, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, type VaultExtensionParams, buildContext, buildMetadata, createDefaultPositions, createLiquidPositionsUSD, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeFeeConversionLockerData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata, shiftPositions };

package/dist/index.d.ts

@@ -63,6 +63,21 @@ interface VaultExtensionParams {
     /** Vesting duration in seconds after lockup ends (0 = no vesting, tokens unlock all at once) */
     vestingDuration?: number;
 }
+interface AirdropExtensionParams {
+    /** Address allowed to `updateAdmin`, `updateMerkleRoot` (under conditions),
+     *  and `adminClaim` the remainder after claim expiration. */
+    admin: Address;
+    /** Merkle root over leaves `keccak256(bytes.concat(keccak256(abi.encode(
+     *  recipient, allocatedAmount))))`. Double-hashed per OZ convention. */
+    merkleRoot: Hex;
+    /** Percentage of supply to reserve for the airdrop, in BPS (1–9000). */
+    allocationBps: number;
+    /** Lockup in seconds before any recipient can claim. Min 86400 (1 day). */
+    lockupDuration: number;
+    /** Linear vesting after lockup. 0 = instant claim of full entitlement at
+     *  lockup end. */
+    vestingDuration?: number;
+}
 interface DeployTokenParams {
     name: string;
     symbol: string;
@@ -270,6 +285,29 @@ declare class LiquidSDK {
      * ```
      */
     buildVaultExtension(vault: VaultExtensionParams): ExtensionConfig;
+    /**
+     * Build an ExtensionConfig that reserves a percentage of supply into
+     * the LiquidAirdropV2 contract for merkle-tree-based distribution.
+     *
+     * The airdrop contract expects `AirdropV2ExtensionData`:
+     *   { address admin, bytes32 merkleRoot, uint256 lockupDuration, uint256 vestingDuration }
+     *
+     * Leaf encoding used by LiquidAirdropV2.claim (note: **double hashed**
+     * — OZ's standard 2nd-preimage-resistant pattern):
+     *   leaf = keccak256(bytes.concat(keccak256(abi.encode(recipient, allocatedAmount))))
+     *
+     * @example
+     * ```typescript
+     * const airdropExt = sdk.buildAirdropExtension({
+     *   admin: account.address,
+     *   merkleRoot: "0x…",
+     *   allocationBps: 2000,          // 20%
+     *   lockupDuration: 86400,        // 1 day (minimum)
+     *   vestingDuration: 0,           // instant claim after lockup
+     * });
+     * ```
+     */
+    buildAirdropExtension(airdrop: AirdropExtensionParams): ExtensionConfig;
     /**
      * Validate a DeploymentConfig before sending to the contract.
      * Catches common mistakes client-side with clear error messages.
@@ -433,6 +471,9 @@ declare const ADDRESSES: {
 declare const EXTERNAL: {
     readonly POOL_MANAGER: Address;
     readonly WETH: Address;
+    /** DIEM — Liquid's intelligence-economy token. Also a pair token for
+     *  agent-token launches (see `createLiquidPositionsUSD`). */
+    readonly DIEM: Address;
     readonly UNIVERSAL_ROUTER: Address;
     readonly PERMIT2: Address;
 };
@@ -489,7 +530,7 @@ declare const POOL_POSITIONS: {
  */
 declare const DEFAULTS: {
     readonly HOOK: `0x${string}`;
-    /** LP Locker with fee conversion (converts fees to ETH before distributing) */
+    /** LP Locker with fee conversion (converts fees to WETH before distributing) */
     readonly LOCKER: `0x${string}`;
     readonly TICK_SPACING: 200;
     readonly TICK_IF_TOKEN0_IS_LIQUID: -230400;
@@ -583,31 +624,7 @@ declare const DEFAULT_CHAIN: {
     formatters: {
         readonly block: {
             exclude: [] | undefined;
-            format: (args: viem_chains.OpStackRpcBlock, action
-            /**
-             * 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%).
-             */
-            ? /**
-             * 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%).
-             */: string | undefined) => {
+            format: (args: viem_chains.OpStackRpcBlock, action?: string | undefined) => {
                 baseFeePerGas: bigint | null;
                 blobGasUsed: bigint;
                 difficulty: bigint;
@@ -2285,6 +2302,7 @@ declare function getTickFromMarketCapStable(marketCap: number, stableDecimals: n
  * 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;
@@ -2380,6 +2398,55 @@ declare function createPositionsUSD(startingMarketCapUSD: number, ethPriceUSD: n
 declare function createDefaultPositions(startingMarketCapUSD: number, ethPriceUSD: number, tickSpacing?: number): PositionArrays & {
     tickIfToken0IsLiquid: number;
 };
+/**
+ * Shift every tick in a position layout by a fixed amount, preserving the
+ * positionBps splits. The primitive behind `createLiquidPositionsUSD` — it
+ * re-anchors a fixed-shape layout (e.g. `POOL_POSITIONS.Liquid`) to a
+ * different starting tick.
+ *
+ * `shiftBy` should be a multiple of the pool's tick spacing so the shifted
+ * ticks stay aligned. A difference of two aligned ticks is always aligned,
+ * so deriving it as `targetTick - sourceBottomTick` is safe.
+ *
+ * @param positions - Source positions (e.g. `POOL_POSITIONS.Liquid`)
+ * @param shiftBy - Ticks to add to every tickLower/tickUpper (may be negative)
+ * @returns A fresh array — the source is not mutated
+ */
+declare function shiftPositions(positions: readonly PoolPosition[], shiftBy: number): PoolPosition[];
+/**
+ * Build the canonical 5-position "Liquid" layout (10/50/15/20/5) re-anchored
+ * to a starting market cap, denominated in the *paired token's* USD price.
+ *
+ * Works for any pair token — pass the price of whatever the pool is paired
+ * against:
+ *   - WETH-paired: `createLiquidPositionsUSD(20_000, ethPriceUSD)`
+ *   - DIEM-paired: `createLiquidPositionsUSD(20_000, diemPriceUSD)`
+ *
+ * Unlike `createDefaultPositions` (a 3-tranche layout), this preserves the
+ * exact shape of `POOL_POSITIONS.Liquid` — the same curve `deployToken()`
+ * uses by default — just shifted so its bottom sits at the requested start.
+ *
+ * @param startingMarketCapUSD - Initial market cap in USD
+ * @param pairedTokenPriceUSD - USD price of the token the pool is paired against
+ * @param tickSpacing - Tick spacing (default 200)
+ * @returns Position arrays + `tickIfToken0IsLiquid`, ready to spread into `deployToken()`
+ *
+ * @example
+ * ```ts
+ * import { LiquidSDK, EXTERNAL, createLiquidPositionsUSD } from "liquid-sdk";
+ *
+ * const positions = createLiquidPositionsUSD(20_000, diemPriceUSD);
+ * await sdk.deployToken({
+ *   name: "Agent Token",
+ *   symbol: "AGENT",
+ *   pairedToken: EXTERNAL.DIEM,
+ *   ...positions,
+ * });
+ * ```
+ */
+declare function createLiquidPositionsUSD(startingMarketCapUSD: number, pairedTokenPriceUSD: number, tickSpacing?: number): PositionArrays & {
+    tickIfToken0IsLiquid: number;
+};
 /**
  * Describe positions as human-readable market cap ranges.
  * Useful for displaying position info in UIs.
@@ -2496,7 +2563,7 @@ declare enum FeePreference {
  *
  * @example
  * ```ts
- * // Single recipient, fees converted to ETH
+ * // Single recipient, fees converted to WETH
  * const lockerData = encodeFeeConversionLockerData([FeePreference.Paired]);
  *
  * // Two recipients: first gets ETH, second gets the token
@@ -2557,4 +2624,4 @@ declare function parseContext(contextString: string): LiquidContext | null;
  */
 declare function parseMetadata(metadataString: string): LiquidMetadata | null;
 
-export { ADDRESSES, type AirdropInfo, type BidInAuctionParams, type BidInAuctionResult, 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, FeePreference, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidMevDescendingFeesAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, 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, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, type VaultExtensionParams, buildContext, buildMetadata, createDefaultPositions, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeFeeConversionLockerData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata };
+export { ADDRESSES, type AirdropExtensionParams, type AirdropInfo, type BidInAuctionParams, type BidInAuctionResult, 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, FeePreference, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidMevDescendingFeesAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, 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, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, type VaultExtensionParams, buildContext, buildMetadata, createDefaultPositions, createLiquidPositionsUSD, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeFeeConversionLockerData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata, shiftPositions };

package/dist/index.js

@@ -49,6 +49,7 @@ __export(index_exports, {
   buildContext: () => buildContext,
   buildMetadata: () => buildMetadata,
   createDefaultPositions: () => createDefaultPositions,
+  createLiquidPositionsUSD: () => createLiquidPositionsUSD,
   createPositions: () => createPositions,
   createPositionsUSD: () => createPositionsUSD,
   describePositions: () => describePositions,
@@ -62,7 +63,8 @@ __export(index_exports, {
   marketCapFromTickETH: () => marketCapFromTickETH,
   marketCapFromTickUSD: () => marketCapFromTickUSD,
   parseContext: () => parseContext,
-  parseMetadata: () => parseMetadata
+  parseMetadata: () => parseMetadata,
+  shiftPositions: () => shiftPositions
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -92,6 +94,9 @@ var ADDRESSES = {
 var EXTERNAL = {
   POOL_MANAGER: "0x498581fF718922c3f8e6A244956aF099B2652b2b",
   WETH: "0x4200000000000000000000000000000000000006",
+  /** DIEM — Liquid's intelligence-economy token. Also a pair token for
+   *  agent-token launches (see `createLiquidPositionsUSD`). */
+  DIEM: "0xF4d97F2da56e8c3098f3a8D538DB630A2606a024",
   UNIVERSAL_ROUTER: "0x6fF5693b99212Da76ad316178A184AB56D299b43",
   PERMIT2: "0x000000000022D473030F116dDEE9F6B43aC78BA3"
 };
@@ -161,7 +166,7 @@ var POOL_POSITIONS = {
 };
 var DEFAULTS = {
   HOOK: ADDRESSES.HOOK_STATIC_FEE_V2,
-  /** LP Locker with fee conversion (converts fees to ETH before distributing) */
+  /** LP Locker with fee conversion (converts fees to WETH before distributing) */
   LOCKER: ADDRESSES.LP_LOCKER_FEE_CONVERSION,
   TICK_SPACING: 200,
   TICK_IF_TOKEN0_IS_LIQUID: -230400,
@@ -1201,6 +1206,73 @@ var LiquidSDK = class {
       extensionData
     };
   }
+  // ── Airdrop Extension ──────────────────────────────────────────
+  /**
+   * Build an ExtensionConfig that reserves a percentage of supply into
+   * the LiquidAirdropV2 contract for merkle-tree-based distribution.
+   *
+   * The airdrop contract expects `AirdropV2ExtensionData`:
+   *   { address admin, bytes32 merkleRoot, uint256 lockupDuration, uint256 vestingDuration }
+   *
+   * Leaf encoding used by LiquidAirdropV2.claim (note: **double hashed**
+   * — OZ's standard 2nd-preimage-resistant pattern):
+   *   leaf = keccak256(bytes.concat(keccak256(abi.encode(recipient, allocatedAmount))))
+   *
+   * @example
+   * ```typescript
+   * const airdropExt = sdk.buildAirdropExtension({
+   *   admin: account.address,
+   *   merkleRoot: "0x…",
+   *   allocationBps: 2000,          // 20%
+   *   lockupDuration: 86400,        // 1 day (minimum)
+   *   vestingDuration: 0,           // instant claim after lockup
+   * });
+   * ```
+   */
+  buildAirdropExtension(airdrop) {
+    const MIN_LOCKUP = 86400;
+    const MAX_BPS = 9e3;
+    if (airdrop.allocationBps < 1 || airdrop.allocationBps > MAX_BPS) {
+      throw new Error(
+        `Airdrop allocationBps must be 1\u2013${MAX_BPS} (0.01%\u201390%). Got ${airdrop.allocationBps}.`
+      );
+    }
+    if (airdrop.lockupDuration < MIN_LOCKUP) {
+      throw new Error(
+        `Airdrop lockupDuration must be \u2265 ${MIN_LOCKUP} seconds (1 day). Got ${airdrop.lockupDuration}.`
+      );
+    }
+    if (airdrop.vestingDuration !== void 0 && airdrop.vestingDuration < 0) {
+      throw new Error("Airdrop vestingDuration cannot be negative.");
+    }
+    const extensionData = (0, import_viem2.encodeAbiParameters)(
+      [
+        {
+          type: "tuple",
+          components: [
+            { type: "address", name: "admin" },
+            { type: "bytes32", name: "merkleRoot" },
+            { type: "uint256", name: "lockupDuration" },
+            { type: "uint256", name: "vestingDuration" }
+          ]
+        }
+      ],
+      [
+        {
+          admin: airdrop.admin,
+          merkleRoot: airdrop.merkleRoot,
+          lockupDuration: BigInt(airdrop.lockupDuration),
+          vestingDuration: BigInt(airdrop.vestingDuration ?? 0)
+        }
+      ]
+    );
+    return {
+      extension: ADDRESSES.AIRDROP_V2,
+      msgValue: 0n,
+      extensionBps: airdrop.allocationBps,
+      extensionData
+    };
+  }
   // ── Validation ─────────────────────────────────────────────────
   /**
    * Validate a DeploymentConfig before sending to the contract.
@@ -1365,13 +1437,36 @@ var LiquidSDK = class {
       (sum, ext) => sum + ext.msgValue,
       0n
     );
+    let gas;
+    try {
+      const estimated = await this.publicClient.estimateContractGas({
+        address: ADDRESSES.FACTORY,
+        abi: LiquidFactoryAbi,
+        functionName: "deployToken",
+        args: [deploymentConfig],
+        value: msgValue,
+        account: this.walletClient.account
+      });
+      gas = estimated * 120n / 100n;
+    } catch (err) {
+      const e = err;
+      const looksLikeRevert = e?.name === "ContractFunctionExecutionError" || e?.name === "CallExecutionError" || typeof e?.shortMessage === "string" && /reverted|revert reason|execution reverted/i.test(e.shortMessage);
+      if (looksLikeRevert) throw err;
+      if (typeof console !== "undefined" && console.warn) {
+        console.warn(
+          "[liquid-sdk] deployToken gas estimation failed; falling back to 6M gas limit:",
+          e?.shortMessage ?? err
+        );
+      }
+      gas = 6000000n;
+    }
     const txHash = await this.walletClient.writeContract({
       address: ADDRESSES.FACTORY,
       abi: LiquidFactoryAbi,
       functionName: "deployToken",
       args: [deploymentConfig],
       value: msgValue,
-      gas: 5000000n,
+      gas,
       chain: import_chains2.base,
       account: this.walletClient.account
     });
@@ -2356,6 +2451,33 @@ function createDefaultPositions(startingMarketCapUSD, ethPriceUSD, tickSpacing =
     tickIfToken0IsLiquid: positions.tickLower[0]
   };
 }
+function shiftPositions(positions, shiftBy) {
+  return positions.map((p) => ({
+    tickLower: p.tickLower + shiftBy,
+    tickUpper: p.tickUpper + shiftBy,
+    positionBps: p.positionBps
+  }));
+}
+function createLiquidPositionsUSD(startingMarketCapUSD, pairedTokenPriceUSD, tickSpacing = 200) {
+  if (pairedTokenPriceUSD <= 0) {
+    throw new Error("pairedTokenPriceUSD must be positive");
+  }
+  const startingTick = getTickFromMarketCapUSD(
+    startingMarketCapUSD,
+    pairedTokenPriceUSD,
+    tickSpacing
+  );
+  const shifted = shiftPositions(
+    POOL_POSITIONS.Liquid,
+    startingTick - DEFAULTS.TICK_IF_TOKEN0_IS_LIQUID
+  );
+  return {
+    tickLower: shifted.map((p) => p.tickLower),
+    tickUpper: shifted.map((p) => p.tickUpper),
+    positionBps: shifted.map((p) => p.positionBps),
+    tickIfToken0IsLiquid: startingTick
+  };
+}
 function describePositions(positions, ethPriceUSD) {
   return positions.tickLower.map((_, i) => {
     const lowerETH = Math.pow(1.0001, positions.tickLower[i]) * 1e11;
@@ -2405,6 +2527,7 @@ function describePositions(positions, ethPriceUSD) {
   buildContext,
   buildMetadata,
   createDefaultPositions,
+  createLiquidPositionsUSD,
   createPositions,
   createPositionsUSD,
   describePositions,
@@ -2418,6 +2541,7 @@ function describePositions(positions, ethPriceUSD) {
   marketCapFromTickETH,
   marketCapFromTickUSD,
   parseContext,
-  parseMetadata
+  parseMetadata,
+  shiftPositions
 });
 //# sourceMappingURL=index.js.map