liquid-sdk 1.5.4 → 1.5.6

package/AGENT_README.md

@@ -507,11 +507,11 @@ When calling `deployToken`, all fields except `name` and `symbol` are optional.
 | `image` | `""` | Empty string |
 | `metadata` | `""` | Empty string |
 | `context` | `'{"interface":"SDK"}'` | Auto-set via `buildContext()` |
-| `hook` | `ADDRESSES.HOOK_STATIC_FEE_V2` | Static 1% buy fee |
+| `hook` | `ADDRESSES.HOOK_STATIC_FEE_V2` | Static 1% buy + 1% sell |
 | `pairedToken` | `EXTERNAL.WETH` | Base WETH |
 | `tickIfToken0IsLiquid` | `-230400` | ≈10 ETH market cap |
 | `tickSpacing` | `200` | Uniswap V4 tick spacing |
-| `poolData` | `encodeStaticFeePoolData(0, 100)` | 0% sell, 1% buy |
+| `poolData` | `encodeStaticFeePoolData(100, 100)` | 1% sell, 1% buy |
 | `locker` | `ADDRESSES.LP_LOCKER_FEE_CONVERSION` | LP locker with fee conversion to ETH |
 | `rewardAdmins` | `[walletAddress]` | Deployer is admin |
 | `rewardRecipients` | `[walletAddress]` | Deployer gets rewards |

package/README.md

@@ -8,7 +8,17 @@ TypeScript SDK for the Liquid Protocol token launcher on Base. Deploy tokens, ma
 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).
+> **Defaults**: Static 1% fee (both buy and sell), 5-position Liquid layout, Sniper Auction MEV (80%→40% over 32s, 5 rounds), tick spacing 200, starting tick -230400 (~10 ETH market cap).
+
+### Default Liquidity Positions
+
+| # | Supply | Tick Range | Market Cap Range (@$2,000/ETH) |
+|---|--------|-----------|-------------------------------|
+| 1 | 10% | -230,400 → -216,000 | ~$20K → ~$83K |
+| 2 | 50% | -216,000 → -155,000 | ~$83K → ~$37M |
+| 3 | 15% | -202,000 → -155,000 | ~$338K → ~$37M |
+| 4 | 20% | -155,000 → -120,000 | ~$37M → ~$1.2B |
+| 5 | 5% | -141,000 → -120,000 | ~$151M → ~$1.2B |
 
 ## Quick Start
 
@@ -95,78 +105,113 @@ const result2 = await liquid.deployToken({
 });
 ```
 
-## Read Token Info
+## Sniper Auction (MEV Bidding)
 
-```typescript
-// Get ERC20 info + deployment details
-const info = await liquid.getTokenInfo(tokenAddress);
-console.log(info.name, info.symbol, info.decimals);
-console.log("Hook:", info.deployment.hook);
-console.log("Locker:", info.deployment.locker);
+Bid for early access to newly launched tokens. The SDK handles WETH wrapping, approvals, gas price encoding, and timing automatically.
 
-// Get deployment info only
-const deployment = await liquid.getDeploymentInfo(tokenAddress);
+```typescript
+import { LiquidSDK, EXTERNAL } from "liquid-sdk";
+
+// 1. Get auction state & pool key
+const auction = await liquid.getAuctionState(poolId);
+const rewards = await liquid.getTokenRewards(tokenAddress);
+const zeroForOne = rewards.poolKey.currency0.toLowerCase() === EXTERNAL.WETH.toLowerCase();
+
+// 2. Calculate gas price for your bid
+const gasPrice = await liquid.getAuctionGasPriceForBid(auction.gasPeg, parseEther("0.001"));
+
+// 3. Wait for auction block, then fire
+const result = await liquid.bidInAuction({
+  poolKey: rewards.poolKey,
+  zeroForOne,
+  amountIn: parseEther("0.001"),     // WETH to swap (auto-wrapped)
+  amountOutMinimum: 0n,
+  round: auction.round,
+  bidAmount: parseEther("0.0005"),   // ETH bid (msg.value)
+}, gasPrice);
 ```
 
-## Pool Information
+## Token Discovery
 
 ```typescript
-// Get pool fee configuration (dynamic fee hook)
-const config = await liquid.getPoolConfig(poolId);
-console.log("Base fee:", config.baseFee);
-console.log("Max LP fee:", config.maxLpFee);
+// Get all tokens
+const allTokens = await liquid.getTokens();
 
-// Get current fee state
-const feeState = await liquid.getPoolFeeState(poolId);
-console.log("Reference tick:", feeState.referenceTick);
-console.log("Last swap:", feeState.lastSwapTimestamp);
+// Get tokens by deployer
+const myTokens = await liquid.getTokens({ deployer: myAddress });
 
-// Check pool creation time
-const created = await liquid.getPoolCreationTimestamp(poolId);
+// Look up a single token (fast, indexed)
+const token = await liquid.getTokenEvent(tokenAddress);
 
-// Check token ordering
-const isToken0 = await liquid.isLiquidToken0(poolId);
+// Paginate with block ranges
+const page = await liquid.getTokens({ fromBlock: 20000000n, toBlock: 20100000n });
 ```
 
-## Claim Fees
+## Read Token Info
 
 ```typescript
-// Check available fees
-const available = await liquid.getAvailableFees(ownerAddress, tokenAddress);
-const claimable = await liquid.getFeesToClaim(ownerAddress, tokenAddress);
+const info = await liquid.getTokenInfo(tokenAddress);
+console.log(info.name, info.symbol, info.decimals);
+console.log("Hook:", info.deployment.hook);
+console.log("Locker:", info.deployment.locker);
+```
+
+## Claim Fees & Rewards
 
-console.log("Available:", available);
-console.log("Claimable:", claimable);
+```typescript
+// LP Rewards
+const rewards = await liquid.getTokenRewards(tokenAddress);
+await liquid.collectRewards(tokenAddress);
 
-// Claim fees
-const txHash = await liquid.claimFees(ownerAddress, tokenAddress);
+// Fee claims
+const claimable = await liquid.getFeesToClaim(ownerAddress, tokenAddress);
+await liquid.claimFees(ownerAddress, tokenAddress);
 ```
 
 ## Vault (Token Vesting)
 
 ```typescript
-// Check vault allocation
 const allocation = await liquid.getVaultAllocation(tokenAddress);
-console.log("Total:", allocation.amountTotal);
-console.log("Claimed:", allocation.amountClaimed);
-console.log("Lockup ends:", new Date(Number(allocation.lockupEndTime) * 1000));
-
-// Check claimable amount
 const claimable = await liquid.getVaultClaimable(tokenAddress);
-
-// Claim vested tokens
-const txHash = await liquid.claimVault(tokenAddress);
+await liquid.claimVault(tokenAddress);
 ```
 
-## Factory Status
+## Agent Skills
+
+The SDK ships with **agent skill files** — self-contained markdown guides that AI agents can load into their context to autonomously use the SDK. Find them in `node_modules/liquid-sdk/skills/` after install.
+
+| Skill | File | What it teaches |
+|-------|------|-----------------|
+| **Deploy Token** | `skills/deploy-token.md` | Full deployment workflows — minimal deploy, dev buy, custom fees, custom positions, reward splits, validation rules |
+| **Bid in Auction** | `skills/bid-in-auction.md` | MEV sniper auction — WETH handling, gas price encoding, block timing, automated sniper example |
+| **Index Tokens** | `skills/index-tokens.md` | Token discovery — bulk queries, single lookup, pagination, real-time monitoring, data enrichment |
+
+### Using Skills with Your Agent
+
+```python
+# Python — load a skill into your agent's context
+with open("node_modules/liquid-sdk/skills/deploy-token.md") as f:
+    agent.system_prompt += f.read()
+```
 
 ```typescript
-// Check if factory is accepting new deployments
-const deprecated = await liquid.isFactoryDeprecated();
+// TypeScript — read skill for an MCP server or agent framework
+import { readFileSync } from "fs";
+const skill = readFileSync("node_modules/liquid-sdk/skills/bid-in-auction.md", "utf-8");
+```
 
-// Check if a locker/hook pair is enabled
-const enabled = await liquid.isLockerEnabled(lockerAddress, hookAddress);
+For Claude Code, reference skills in your `CLAUDE.md`:
 ```
+For token deployment, follow the instructions in node_modules/liquid-sdk/skills/deploy-token.md
+```
+
+### Additional Agent Docs
+
+| File | Purpose |
+|------|---------|
+| `AGENT_README.md` | Complete API reference with every method, type, and default (700+ lines) |
+| `llms.txt` | Compact summary for LLM context windows |
+| `CLAUDE.md` | Agent guide with architecture, defaults, and invariants |
 
 ## Constants & ABIs
 
@@ -202,7 +247,15 @@ import {
   LiquidFactoryAbi,
   LiquidFeeLockerAbi,
   LiquidHookDynamicFeeV2Abi,
+  LiquidLpLockerAbi,
   LiquidVaultAbi,
+  LiquidSniperAuctionV2Abi,
+  LiquidSniperUtilV2Abi,
+  LiquidAirdropV2Abi,
+  LiquidTokenAbi,
+  LiquidUniv4EthDevBuyAbi,
+  LiquidPoolExtensionAllowlistAbi,
+  LiquidMevBlockDelayAbi,
   ERC20Abi,
 } from "liquid-sdk";
 ```
@@ -222,23 +275,57 @@ new LiquidSDK({ walletClient, publicClient? })
 
 #### Methods
 
-| Method | Description | Requires Wallet |
-|--------|-------------|:-:|
-| `deployToken(params)` | Deploy a new token + pool | Yes |
-| `getDeploymentInfo(token)` | Get deployment info (hook, locker, extensions) | No |
-| `getTokenInfo(token)` | Get ERC20 info + deployment details | No |
-| `getPoolConfig(poolId, hook?)` | Get dynamic fee pool configuration | No |
-| `getPoolFeeState(poolId, hook?)` | Get current fee state variables | No |
-| `getPoolCreationTimestamp(poolId, hook?)` | Get pool creation timestamp | No |
-| `isLiquidToken0(poolId, hook?)` | Check if Liquid token is currency0 | No |
-| `getAvailableFees(owner, token)` | Get available fee balance | No |
-| `getFeesToClaim(owner, token)` | Get claimable fee balance | No |
+| Method | Description | Wallet |
+|--------|-------------|:------:|
+| **Deployment** | | |
+| `deployToken(params)` | Deploy token + Uniswap V4 pool | Yes |
+| `buildDevBuyExtension(devBuy)` | Build dev buy extension config | No |
+| **Token Discovery** | | |
+| `getTokens(options?)` | Query deployed tokens with filters | No |
+| `getTokenEvent(token)` | Look up single token (indexed, fast) | No |
+| `getDeployedTokens(deployer)` | Get tokens by deployer | No |
+| **Token Info** | | |
+| `getDeploymentInfo(token)` | Hook, locker, extensions | No |
+| `getTokenInfo(token)` | ERC20 info + deployment details | No |
+| **Token Updates** | | |
+| `updateImage(token, url)` | Update token image (admin) | Yes |
+| `updateMetadata(token, json)` | Update token metadata (admin) | Yes |
+| **Pool State** | | |
+| `getPoolConfig(poolId)` | Dynamic fee pool configuration | No |
+| `getPoolFeeState(poolId)` | Current fee state variables | No |
+| `getPoolCreationTimestamp(poolId)` | Pool creation timestamp | No |
+| `isLiquidToken0(poolId)` | Token sort order in pool | No |
+| **Fee Claims** | | |
+| `getAvailableFees(owner, token)` | Total unlocked fees | No |
+| `getFeesToClaim(owner, token)` | Claimable fee balance | No |
 | `claimFees(owner, token)` | Claim accumulated fees | Yes |
-| `getVaultAllocation(token)` | Get vault vesting allocation | No |
-| `getVaultClaimable(token)` | Get vested amount available to claim | No |
-| `claimVault(token)` | Claim vested tokens from vault | Yes |
-| `isFactoryDeprecated()` | Check if factory is deprecated | No |
-| `isLockerEnabled(locker, hook)` | Check if locker/hook pair is enabled | No |
+| **LP Rewards** | | |
+| `getTokenRewards(token)` | Reward config (recipients, bps, poolKey) | No |
+| `collectRewards(token)` | Collect + unlock LP fees | Yes |
+| `collectRewardsWithoutUnlock(token)` | Collect fees only | Yes |
+| `updateRewardRecipient(token, idx, addr)` | Change reward recipient | Yes |
+| **Vault** | | |
+| `getVaultAllocation(token)` | Vault vesting state | No |
+| `getVaultClaimable(token)` | Vested amount available | No |
+| `claimVault(token)` | Claim vested tokens | Yes |
+| **Airdrop** | | |
+| `getAirdropInfo(token)` | Airdrop state | No |
+| `getAirdropClaimable(token, recipient, amount)` | Claimable for recipient | No |
+| `claimAirdrop(token, recipient, amount, proof)` | Claim airdrop | Yes |
+| **Sniper Auction** | | |
+| `getAuctionState(poolId)` | Round, gasPeg, fee, nextBlock | No |
+| `getAuctionFeeConfig(poolId)` | Fee decay parameters | No |
+| `getAuctionDecayStartTime(poolId)` | When fee decay started | No |
+| `getAuctionMaxRounds()` | Max auction rounds | No |
+| `getAuctionGasPriceForBid(gasPeg, bid)` | Calculate gas price for bid | No |
+| `bidInAuction(params, gasPrice)` | Bid + swap (auto-wraps WETH) | Yes |
+| **MEV Protection** | | |
+| `getMevBlockDelay()` | Configured block delay | No |
+| `getPoolUnlockTime(poolId)` | When MEV lock expires | No |
+| **Factory** | | |
+| `isFactoryDeprecated()` | Factory still active? | No |
+| `isLockerEnabled(locker, hook)` | Locker/hook pair enabled? | No |
+| `isExtensionEnabled(extension)` | Extension on allowlist? | No |
 
 ## Production Addresses
 

package/dist/index.d.mts

@@ -429,7 +429,7 @@ declare const POOL_POSITIONS: {
 /**
  * Liquid protocol defaults.
  *
- * - Hook: Static fee V2, 1% on buys only (fees in ETH), 0% on sells
+ * - Hook: Static fee V2, 1% on both buys and sells
  * - MEV: Sniper Auction V2 — 80% → 40% decaying over 32 seconds
  * - Tick spacing: 200
  * - Starting tick: -230400 (≈10 ETH market cap)
@@ -441,10 +441,10 @@ declare const DEFAULTS: {
     readonly LOCKER: `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. */
+    /** Static fee on buys (ETH → token): 1% (100 bps) */
     readonly PAIRED_FEE_BPS: 100;
-    /** Static fee on sells (token → ETH): 0%. No fees in liquid token. */
-    readonly LIQUID_FEE_BPS: 0;
+    /** Static fee on sells (token → ETH): 1% (100 bps) */
+    readonly LIQUID_FEE_BPS: 100;
     /** MEV module: Sniper Auction V2 */
     readonly MEV_MODULE: `0x${string}`;
     /** Sniper auction starting fee: 80% (800,000 uniBps) */

package/dist/index.d.ts

@@ -429,7 +429,7 @@ declare const POOL_POSITIONS: {
 /**
  * Liquid protocol defaults.
  *
- * - Hook: Static fee V2, 1% on buys only (fees in ETH), 0% on sells
+ * - Hook: Static fee V2, 1% on both buys and sells
  * - MEV: Sniper Auction V2 — 80% → 40% decaying over 32 seconds
  * - Tick spacing: 200
  * - Starting tick: -230400 (≈10 ETH market cap)
@@ -441,10 +441,10 @@ declare const DEFAULTS: {
     readonly LOCKER: `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. */
+    /** Static fee on buys (ETH → token): 1% (100 bps) */
     readonly PAIRED_FEE_BPS: 100;
-    /** Static fee on sells (token → ETH): 0%. No fees in liquid token. */
-    readonly LIQUID_FEE_BPS: 0;
+    /** Static fee on sells (token → ETH): 1% (100 bps) */
+    readonly LIQUID_FEE_BPS: 100;
     /** MEV module: Sniper Auction V2 */
     readonly MEV_MODULE: `0x${string}`;
     /** Sniper auction starting fee: 80% (800,000 uniBps) */

package/dist/index.js

@@ -164,10 +164,10 @@ var DEFAULTS = {
   LOCKER: ADDRESSES.LP_LOCKER_FEE_CONVERSION,
   TICK_SPACING: 200,
   TICK_IF_TOKEN0_IS_LIQUID: -230400,
-  /** Static fee on buys (ETH → token): 1% (100 bps). Fees collected in ETH. */
+  /** Static fee on buys (ETH → token): 1% (100 bps) */
   PAIRED_FEE_BPS: 100,
-  /** Static fee on sells (token → ETH): 0%. No fees in liquid token. */
-  LIQUID_FEE_BPS: 0,
+  /** Static fee on sells (token → ETH): 1% (100 bps) */
+  LIQUID_FEE_BPS: 100,
   /** MEV module: Sniper Auction V2 */
   MEV_MODULE: ADDRESSES.SNIPER_AUCTION_V2,
   /** Sniper auction starting fee: 80% (800,000 uniBps) */