liquid-sdk 1.5.4 → 1.5.5

package/README.md

@@ -8,7 +8,7 @@ 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% buy fee / 0% sell fee, 5-position Liquid layout (10%/50%/15%/20%/5%), Sniper Auction MEV (80%→40% over 32s, 5 rounds), tick spacing 200, starting tick -230400 (~10 ETH market cap).
 
 ## Quick Start
 
@@ -95,78 +95,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);
+```
 
-console.log("Available:", available);
-console.log("Claimable:", claimable);
+## Claim Fees & Rewards
 
-// Claim fees
-const txHash = await liquid.claimFees(ownerAddress, tokenAddress);
+```typescript
+// LP Rewards
+const rewards = await liquid.getTokenRewards(tokenAddress);
+await liquid.collectRewards(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 +237,15 @@ import {
   LiquidFactoryAbi,
   LiquidFeeLockerAbi,
   LiquidHookDynamicFeeV2Abi,
+  LiquidLpLockerAbi,
   LiquidVaultAbi,
+  LiquidSniperAuctionV2Abi,
+  LiquidSniperUtilV2Abi,
+  LiquidAirdropV2Abi,
+  LiquidTokenAbi,
+  LiquidUniv4EthDevBuyAbi,
+  LiquidPoolExtensionAllowlistAbi,
+  LiquidMevBlockDelayAbi,
   ERC20Abi,
 } from "liquid-sdk";
 ```
@@ -222,23 +265,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/llms.txt

@@ -120,7 +120,7 @@ Every token gets 100 billion supply (18 decimals), a Uniswap V4 pool, and locked
 | hook | Static fee V2 (1% buy fee) |
 | tickSpacing | 200 |
 | tickIfToken0IsLiquid | -230400 (~10 ETH market cap) |
-| positions | 3-tranche: 40% to $500K, 50% to $10M, 10% to $1B |
+| positions | 5-position Liquid layout: 10%/50%/15%/20%/5% |
 | mevModule | Sniper Auction V2 (80%→40% over 32s) |
 | rewardRecipients | [deployer] at 100% |
 | context | {"interface":"SDK"} |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liquid-sdk",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "TypeScript SDK to deploy ERC-20 tokens with Uniswap V4 liquidity on Base — zero API keys, one dependency (viem)",
   "author": "Liquid Protocol",
   "homepage": "https://github.com/craigbots/liquid-sdk#readme",