liquid-sdk 1.5.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liquid-sdk",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "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",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "AGENT_README.md",
     "CHANGELOG.md",
@@ -66,6 +67,8 @@
     "web3",
     "smart-contract",
     "liquidity",
-    "mev-protection"
+    "mev-protection",
+    "ai-agent",
+    "llm-skills"
   ]
 }

package/skills/README.md

@@ -0,0 +1,51 @@
+# Liquid SDK — Agent Skills
+
+Drop these files into your AI agent's context to give it the ability to interact with Liquid Protocol on Base.
+
+## Available Skills
+
+| Skill | File | Description |
+|-------|------|-------------|
+| **Deploy Token** | [`deploy-token.md`](./deploy-token.md) | Deploy ERC-20 tokens with Uniswap V4 liquidity, custom fees, dev buys, and reward splits |
+| **Bid in Auction** | [`bid-in-auction.md`](./bid-in-auction.md) | Participate in sniper auctions for early access to newly launched tokens |
+| **Index Tokens** | [`index-tokens.md`](./index-tokens.md) | Discover, index, and monitor all Liquid Protocol token deployments |
+
+## How to Use
+
+These are standalone markdown files designed to be loaded into an AI agent's system prompt or context window. Each skill contains:
+
+- Complete setup instructions
+- Step-by-step workflows with code examples
+- Type definitions and parameter references
+- Full working examples
+- Error handling and edge cases
+
+### With Claude Code
+
+Place a skill file in your project and reference it in your `CLAUDE.md`:
+
+```markdown
+For token deployment, follow the instructions in skills/deploy-token.md
+```
+
+### With Other AI Agents
+
+Load the skill file contents into your agent's system prompt or tool description:
+
+```python
+with open("skills/deploy-token.md") as f:
+    skill = f.read()
+
+agent.system_prompt += f"\n\n{skill}"
+```
+
+### With MCP Servers
+
+Serve skill files as resources through an MCP server for on-demand agent access.
+
+## Requirements
+
+All skills require:
+- `liquid-sdk` and `viem` npm packages
+- An RPC endpoint for Base mainnet (chain ID 8453)
+- For write operations: a private key with ETH on Base

package/skills/bid-in-auction.md

@@ -0,0 +1,296 @@
+# Skill: Bid in a Sniper Auction (MEV)
+
+You are an AI agent that participates in Liquid Protocol's sniper auction system. This skill teaches you how to bid for early access to newly launched tokens through the MEV auction mechanism on Base.
+
+## How the Sniper Auction Works
+
+When a new token is deployed on Liquid Protocol, a **sniper auction** activates to price early trading activity and capture MEV. Here's the mechanism:
+
+1. **Fee decay**: The auction starts with an **80% fee** on swaps and decays linearly to **40% over 32 seconds**
+2. **Gas price bidding**: Bidders compete by setting their transaction gas price **above the pool's gas peg**. The difference between your gas price and the gas peg determines your bid amount
+3. **Rounds**: The auction runs in discrete rounds, each lasting a configurable number of blocks. Each round has its own auction window
+4. **Winner takes the swap**: The highest gas-price transaction in each block wins the right to swap at the current fee rate
+5. **Revenue distribution**: Auction revenue (bid amounts) flows to the protocol and LP holders
+
+The auction is **not** a separate step from trading — it's a modified swap where your gas price encodes your bid.
+
+## Prerequisites
+
+```bash
+npm install liquid-sdk viem
+```
+
+You need:
+- A **private key** with ETH on Base
+- The **token address** or **pool ID** of a recently launched token
+- An **RPC endpoint** for Base mainnet
+
+## Setup
+
+```typescript
+import { createPublicClient, createWalletClient, http, parseEther } from "viem";
+import { base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { LiquidSDK } from "liquid-sdk";
+
+const account = privateKeyToAccount(PRIVATE_KEY);
+const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+const walletClient = createWalletClient({ account, chain: base, transport: http(RPC_URL) });
+const sdk = new LiquidSDK({ publicClient, walletClient });
+```
+
+## Step-by-Step: Bidding in an Auction
+
+### Step 1: Get the Auction State
+
+```typescript
+// You need the pool ID — get it from deployment or token lookup
+const tokenEvent = await sdk.getTokenEvent(tokenAddress);
+const poolId = tokenEvent.poolId;
+
+// Query current auction state
+const auction = await sdk.getAuctionState(poolId);
+
+console.log("Next auction block:", auction.nextAuctionBlock);
+console.log("Current round:", auction.round);
+console.log("Gas peg:", auction.gasPeg);
+console.log("Current fee:", auction.currentFee); // in uniBps (800000 = 80%)
+```
+
+**Key fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `nextAuctionBlock` | `bigint` | Block number when next auction round starts |
+| `round` | `bigint` | Current round number (must match when bidding) |
+| `gasPeg` | `bigint` | Base gas price reference — you bid by exceeding this |
+| `currentFee` | `number` | Current MEV fee in uniBps (decays from 800000→400000) |
+
+### Step 2: Check Auction Fee Config
+
+```typescript
+const feeConfig = await sdk.getAuctionFeeConfig(poolId);
+
+console.log("Starting fee:", feeConfig.startingFee);     // 800000 (80%)
+console.log("Ending fee:", feeConfig.endingFee);          // 400000 (40%)
+console.log("Seconds to decay:", feeConfig.secondsToDecay); // 32n
+```
+
+### Step 3: Check Timing
+
+```typescript
+// When did fee decay start?
+const decayStart = await sdk.getAuctionDecayStartTime(poolId);
+const now = BigInt(Math.floor(Date.now() / 1000));
+const elapsed = now - decayStart;
+
+console.log("Seconds since decay started:", elapsed);
+// If elapsed > secondsToDecay, fee is at the floor (endingFee)
+
+// How many rounds total?
+const maxRounds = await sdk.getAuctionMaxRounds();
+console.log("Max auction rounds:", maxRounds);
+
+// Is this round still active?
+const currentBlock = await publicClient.getBlockNumber();
+console.log("Current block:", currentBlock);
+console.log("Next auction block:", auction.nextAuctionBlock);
+// If currentBlock < nextAuctionBlock, the current round is still active
+```
+
+### Step 4: Calculate Gas Price for Your Bid
+
+```typescript
+const desiredBidAmount = parseEther("0.01"); // How much ETH you want to bid
+
+// SDK calculates the exact gas price needed
+const requiredGasPrice = await sdk.getAuctionGasPriceForBid(
+  auction.gasPeg,
+  desiredBidAmount,
+);
+
+console.log("Required gas price:", requiredGasPrice);
+// This is the maxFeePerGas you must set on your transaction
+```
+
+**The formula:** `bidAmount = (txGasPrice - gasPeg) * paymentPerGasUnit`. The utility contract solves for `txGasPrice` given your desired `bidAmount`.
+
+### Step 5: Get the Pool Key
+
+```typescript
+// The pool key identifies the Uniswap V4 pool for the swap
+const rewards = await sdk.getTokenRewards(tokenAddress);
+const poolKey = rewards.poolKey;
+
+// poolKey contains:
+// .currency0  — lower-sorted token (WETH or the Liquid token)
+// .currency1  — higher-sorted token
+// .fee        — fee tier
+// .tickSpacing — tick spacing (200)
+// .hooks      — hook contract address
+```
+
+### Step 6: Execute the Bid
+
+```typescript
+const result = await sdk.bidInAuction(
+  {
+    poolKey: rewards.poolKey,
+    zeroForOne: true,               // true = buying tokens with ETH
+    amountIn: parseEther("0.1"),    // amount of ETH to swap
+    amountOutMinimum: 0n,           // set slippage protection (0 = no minimum)
+    round: auction.round,           // must match current on-chain round
+    bidAmount: desiredBidAmount,    // ETH bid (sent as msg.value)
+  },
+  requiredGasPrice,                 // calculated gas price from step 4
+);
+
+console.log("Bid tx:", result.txHash);
+
+// Wait for confirmation
+const receipt = await publicClient.waitForTransactionReceipt({ hash: result.txHash });
+console.log("Status:", receipt.status); // "success" or "reverted"
+```
+
+## Complete Example: Automated Auction Sniper
+
+```typescript
+import { createPublicClient, createWalletClient, http, parseEther, formatEther } from "viem";
+import { base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { LiquidSDK } from "liquid-sdk";
+
+async function snipeToken(tokenAddress: `0x${string}`, bidETH: string, swapETH: string) {
+  const account = privateKeyToAccount(PRIVATE_KEY);
+  const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+  const walletClient = createWalletClient({ account, chain: base, transport: http(RPC_URL) });
+  const sdk = new LiquidSDK({ publicClient, walletClient });
+
+  // 1. Look up the token
+  const tokenEvent = await sdk.getTokenEvent(tokenAddress);
+  if (!tokenEvent) throw new Error("Token not found");
+
+  console.log(`Sniping ${tokenEvent.tokenName} (${tokenEvent.tokenSymbol})`);
+  console.log(`Pool ID: ${tokenEvent.poolId}`);
+
+  // 2. Check auction state
+  const auction = await sdk.getAuctionState(tokenEvent.poolId);
+  console.log(`Auction round: ${auction.round}, Fee: ${Number(auction.currentFee) / 10000}%`);
+
+  // 3. Check if auction is still active
+  const maxRounds = await sdk.getAuctionMaxRounds();
+  if (auction.round >= maxRounds) {
+    console.log("Auction ended — trading at normal fees now");
+    return;
+  }
+
+  // 4. Get pool key for the swap
+  const rewards = await sdk.getTokenRewards(tokenAddress);
+
+  // 5. Calculate gas price for desired bid
+  const bidAmount = parseEther(bidETH);
+  const gasPrice = await sdk.getAuctionGasPriceForBid(auction.gasPeg, bidAmount);
+
+  console.log(`Bid amount: ${formatEther(bidAmount)} ETH`);
+  console.log(`Required gas price: ${gasPrice}`);
+
+  // 6. Execute the bid
+  const result = await sdk.bidInAuction(
+    {
+      poolKey: rewards.poolKey,
+      zeroForOne: true,
+      amountIn: parseEther(swapETH),
+      amountOutMinimum: 0n,       // In production, calculate proper slippage!
+      round: auction.round,
+      bidAmount,
+    },
+    gasPrice,
+  );
+
+  const receipt = await publicClient.waitForTransactionReceipt({ hash: result.txHash });
+  console.log(`Bid ${receipt.status === "success" ? "WON" : "FAILED"}: ${result.txHash}`);
+}
+
+// Usage
+await snipeToken("0x...", "0.005", "0.1"); // bid 0.005 ETH, swap 0.1 ETH
+```
+
+## BidInAuctionParams Reference
+
+```typescript
+interface BidInAuctionParams {
+  poolKey: PoolKey;        // The Uniswap V4 pool key (get from getTokenRewards)
+  zeroForOne: boolean;     // true = ETH→token, false = token→ETH
+  amountIn: bigint;        // Amount of input token to swap (in wei)
+  amountOutMinimum: bigint;// Minimum output (slippage protection)
+  round: bigint;           // Must match current on-chain auction round
+  bidAmount: bigint;       // ETH bid amount (sent as msg.value)
+}
+
+interface BidInAuctionResult {
+  txHash: Hash;
+}
+```
+
+## Auction Parameters (Defaults)
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| Starting fee | 800,000 (80%) | Fee at auction start |
+| Ending fee | 400,000 (40%) | Fee after decay completes |
+| Decay period | 32 seconds | Time for fee to decay from start to end |
+| Gas peg | Dynamic | Base gas price, updated per round |
+| Max rounds | Contract-defined | Total auction rounds per token |
+
+## Timing Strategy
+
+The auction fee **decays over time**, so there's a tradeoff:
+
+- **Bid early** (high fee): You pay up to 80% of the swap as a fee, but you get the tokens before others. Useful if you expect rapid price appreciation.
+- **Bid late** (lower fee): The fee decays to 40% over 32 seconds. You pay less in fees but risk being outbid or missing the auction window.
+- **Wait for auction to end**: After all rounds complete, trading is at normal pool fees (typically 1%). No auction mechanics apply.
+
+```typescript
+// Check current fee percentage
+const feePercent = auction.currentFee / 10000; // e.g., 80.0, 60.5, 40.0
+console.log(`Current fee: ${feePercent}%`);
+
+// Check fee decay progress
+const feeConfig = await sdk.getAuctionFeeConfig(poolId);
+const decayStart = await sdk.getAuctionDecayStartTime(poolId);
+const now = BigInt(Math.floor(Date.now() / 1000));
+const decayProgress = Number(now - decayStart) / Number(feeConfig.secondsToDecay);
+console.log(`Decay progress: ${Math.min(decayProgress * 100, 100).toFixed(1)}%`);
+```
+
+## Important Notes
+
+1. **`round` must be current**: If you submit a bid with a stale round number, the transaction will revert. Always fetch `getAuctionState()` right before bidding.
+
+2. **Gas price is the bid**: The auction uses `tx.gasprice` as the bidding mechanism. The SDK's `bidInAuction()` sets `maxFeePerGas` to the calculated value. On Base (L2), gas prices are low, so even small bids produce manageable gas costs.
+
+3. **Slippage protection**: Set `amountOutMinimum` to a non-zero value in production. Calculate it based on the current pool price and your acceptable slippage tolerance.
+
+4. **The bid amount is sent as `msg.value`**: This ETH goes to the auction contract, not to the swap. The `amountIn` is the separate ETH amount for the actual token swap.
+
+5. **`zeroForOne` direction**: Almost always `true` for sniping (buying tokens with ETH). Only set to `false` if selling tokens back through the auction.
+
+## Read-Only Auction Queries (No Wallet Needed)
+
+```typescript
+const sdk = new LiquidSDK({ publicClient }); // read-only
+
+const auction = await sdk.getAuctionState(poolId);
+const feeConfig = await sdk.getAuctionFeeConfig(poolId);
+const decayStart = await sdk.getAuctionDecayStartTime(poolId);
+const maxRounds = await sdk.getAuctionMaxRounds();
+const gasPrice = await sdk.getAuctionGasPriceForBid(auction.gasPeg, parseEther("0.01"));
+```
+
+## Contract Addresses
+
+```typescript
+import { ADDRESSES } from "liquid-sdk";
+
+ADDRESSES.SNIPER_AUCTION_V2  // Auction state contract
+ADDRESSES.SNIPER_UTIL_V2     // Bid execution contract (called by bidInAuction)
+```

package/skills/deploy-token.md

@@ -0,0 +1,260 @@
+# Skill: Deploy a Token with Liquid Protocol
+
+You are an AI agent that deploys ERC-20 tokens on Base using the `liquid-sdk`. This skill gives you everything you need to deploy tokens autonomously — from minimal launches to fully customized deployments with dev buys, custom fee structures, and multi-tranche liquidity positions.
+
+## Prerequisites
+
+```bash
+npm install liquid-sdk viem
+```
+
+You need:
+- A **private key** with ETH on Base (for gas + optional dev buy)
+- An **RPC endpoint** for Base mainnet (chain ID 8453)
+
+## Setup
+
+```typescript
+import { createPublicClient, createWalletClient, http, parseEther } from "viem";
+import { base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { LiquidSDK } from "liquid-sdk";
+
+const account = privateKeyToAccount(PRIVATE_KEY);
+const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+const walletClient = createWalletClient({ account, chain: base, transport: http(RPC_URL) });
+const sdk = new LiquidSDK({ publicClient, walletClient });
+```
+
+## Deploying a Token
+
+### Minimal Deploy (2 required fields)
+
+```typescript
+const result = await sdk.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+});
+
+// result.tokenAddress  → 0x... (the deployed ERC-20)
+// result.txHash        → 0x... (the transaction hash)
+// result.event.poolId  → 0x... (the Uniswap V4 pool ID)
+```
+
+This creates a token with 100 billion supply, a Uniswap V4 pool, locked liquidity, 1% buy fee, and sniper auction MEV protection — all with sensible defaults.
+
+### Deploy with Dev Buy (buy tokens at launch)
+
+```typescript
+const result = await sdk.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+  image: "https://example.com/logo.png",
+  metadata: JSON.stringify({ description: "Launched by an AI agent" }),
+  devBuy: {
+    ethAmount: parseEther("0.01"), // ETH to spend buying tokens at launch
+    recipient: account.address,     // who receives the purchased tokens
+  },
+});
+```
+
+The dev buy happens atomically in the same transaction as deployment. The ETH is swapped through the Uniswap V4 pool. The `msg.value` of the transaction equals the `ethAmount`.
+
+### Deploy with Custom Fees
+
+```typescript
+import { encodeStaticFeePoolData, encodeDynamicFeePoolData, ADDRESSES } from "liquid-sdk";
+
+// Static fees: 0% sell fee, 2% buy fee
+const result = await sdk.deployToken({
+  name: "High Fee Token",
+  symbol: "HFT",
+  poolData: encodeStaticFeePoolData(0, 200), // (liquidFeeBps, pairedFeeBps)
+});
+
+// Dynamic fees (volatility-responsive)
+const result2 = await sdk.deployToken({
+  name: "Dynamic Fee Token",
+  symbol: "DFT",
+  hook: ADDRESSES.HOOK_DYNAMIC_FEE_V2,
+  poolData: encodeDynamicFeePoolData({
+    baseFeeBps: 30,              // 0.3% base
+    maxFeeBps: 500,              // 5% max
+    referenceTickFilterPeriod: 300,
+    resetPeriod: 86400,
+    resetTickFilter: 600,
+    feeControlNumerator: 50000n,
+    decayFilterBps: 500,
+  }),
+});
+```
+
+### Deploy with Custom Liquidity Positions
+
+```typescript
+import { createPositionsUSD, createDefaultPositions } from "liquid-sdk";
+
+// Option A: Default 3-tranche positions based on current ETH price
+const positions = createDefaultPositions(20_000, 2500); // $20K starting cap, ETH=$2500
+const result = await sdk.deployToken({
+  name: "Positioned Token",
+  symbol: "POS",
+  tickIfToken0IsLiquid: positions.tickIfToken0IsLiquid,
+  tickLower: positions.tickLower,
+  tickUpper: positions.tickUpper,
+  positionBps: positions.positionBps,
+});
+
+// Option B: Custom tranches
+const custom = createPositionsUSD(20_000, 2500, [
+  { upperMarketCapUSD: 100_000, supplyPct: 30 },
+  { upperMarketCapUSD: 1_000_000, supplyPct: 40 },
+  { upperMarketCapUSD: 100_000_000, supplyPct: 30 },
+]);
+```
+
+### Deploy with Custom Reward Splits
+
+```typescript
+const result = await sdk.deployToken({
+  name: "Split Token",
+  symbol: "SPLIT",
+  rewardAdmins: [walletA, walletB],
+  rewardRecipients: [walletA, walletB],
+  rewardBps: [7000, 3000], // 70% / 30% split
+});
+```
+
+### Deploy with Context (attribution/tracking)
+
+```typescript
+import { buildContext, buildMetadata } from "liquid-sdk";
+
+const result = await sdk.deployToken({
+  name: "Social Token",
+  symbol: "SOC",
+  context: buildContext({
+    interface: "My Agent",
+    platform: "Farcaster",
+    messageId: "0x123abc",
+  }),
+  metadata: buildMetadata({
+    description: "A token launched from a Farcaster cast",
+    socialMediaUrls: [
+      { platform: "Twitter", url: "https://twitter.com/example" },
+    ],
+  }),
+});
+```
+
+## Complete DeployTokenParams Reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | **required** | Token name |
+| `symbol` | `string` | **required** | Token symbol |
+| `image` | `string` | `""` | Image URL |
+| `metadata` | `string` | `""` | JSON metadata string |
+| `context` | `string` | `'{"interface":"SDK"}'` | JSON context for attribution |
+| `tokenAdmin` | `Address` | wallet address | Can update image/metadata |
+| `salt` | `Hex` | auto-generated | CREATE2 salt (unique per deploy) |
+| `hook` | `Address` | Static Fee V2 | Fee logic hook contract |
+| `pairedToken` | `Address` | WETH | Quote token |
+| `tickIfToken0IsLiquid` | `number` | `-230400` | Starting tick (~10 ETH market cap) |
+| `tickSpacing` | `number` | `200` | Uniswap V4 tick spacing |
+| `poolData` | `Hex` | 0% sell / 1% buy | Encoded fee configuration |
+| `locker` | `Address` | LP Locker Fee Conversion | LP locker contract |
+| `rewardAdmins` | `Address[]` | `[wallet]` | Reward admin per recipient |
+| `rewardRecipients` | `Address[]` | `[wallet]` | Fee recipients |
+| `rewardBps` | `number[]` | `[10000]` | BPS per recipient (sum = 10000) |
+| `tickLower` | `number[]` | 5-tranche Liquid default | Position lower bounds |
+| `tickUpper` | `number[]` | 5-tranche Liquid default | Position upper bounds |
+| `positionBps` | `number[]` | 5-tranche Liquid default | Supply % per position (sum = 10000) |
+| `lockerData` | `Hex` | auto-encoded | Locker init data |
+| `mevModule` | `Address` | Sniper Auction V2 | MEV protection module |
+| `mevModuleData` | `Hex` | 80%→40% over 32s | Encoded auction config |
+| `extensions` | `ExtensionConfig[]` | `[]` | Additional extensions |
+| `devBuy` | `DevBuyParams` | none | Buy tokens at launch |
+
+## DeployTokenResult
+
+```typescript
+interface DeployTokenResult {
+  tokenAddress: Address;      // The deployed ERC-20 contract
+  txHash: Hash;               // Transaction hash
+  event: TokenCreatedEvent;   // Full on-chain event data
+}
+
+// event contains:
+// .poolId        — Uniswap V4 pool ID (bytes32)
+// .poolHook      — Hook contract used
+// .locker        — LP locker address
+// .mevModule     — MEV module address
+// .extensions    — Extension addresses
+// .tokenAdmin    — Admin address
+// .startingTick  — Initial tick
+// .pairedToken   — Quote token (WETH)
+```
+
+## What Happens On-Chain
+
+When `deployToken()` executes, a single transaction:
+
+1. **Creates the ERC-20 token** with 100 billion supply (18 decimals)
+2. **Initializes a Uniswap V4 pool** paired with WETH
+3. **Locks all LP** in the LP Locker (non-ruggable)
+4. **Configures reward splits** for fee distribution
+5. **Activates MEV protection** (sniper auction: 80%→40% fee decay over 32 seconds)
+6. **Executes dev buy** if specified (swaps ETH→tokens in same tx)
+7. **Emits `TokenCreated` event** with all deployment data
+
+## Validation Rules
+
+The SDK validates before sending the transaction:
+- 1–7 positions allowed, BPS must sum to 10000
+- All ticks must be aligned to `tickSpacing`
+- All `tickLower` must be `≥ tickIfToken0IsLiquid`
+- At least one position must have `tickLower == tickIfToken0IsLiquid`
+- 1+ reward recipients, BPS must sum to 10000
+- Max 10 extensions, max 90% of supply to extensions total
+
+## Post-Deploy Operations
+
+After deployment, you can:
+
+```typescript
+// Update token image or metadata (admin only)
+await sdk.updateImage(result.tokenAddress, "https://new-image.png");
+await sdk.updateMetadata(result.tokenAddress, '{"description":"Updated"}');
+
+// Check deployment info
+const info = await sdk.getDeploymentInfo(result.tokenAddress);
+const tokenInfo = await sdk.getTokenInfo(result.tokenAddress);
+
+// Check MEV lock status
+const unlockTime = await sdk.getPoolUnlockTime(result.event.poolId);
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `TickRangeLowerThanStartingTick` | `tickLower < tickIfToken0IsLiquid` | Ensure all position ticks ≥ starting tick |
+| Insufficient funds | Not enough ETH for gas + devBuy | Check balance covers gas + `devBuy.ethAmount` |
+| `rewardBps must sum to 10000` | BPS array doesn't total 10000 | Fix the array values |
+| `positions and bps arrays must be same length` | Mismatched arrays | Ensure tickLower, tickUpper, positionBps are same length |
+
+## Contract Addresses (Base Mainnet)
+
+```typescript
+import { ADDRESSES, EXTERNAL } from "liquid-sdk";
+
+ADDRESSES.FACTORY                    // Token factory
+ADDRESSES.HOOK_STATIC_FEE_V2        // Default hook (1% buy fee)
+ADDRESSES.HOOK_DYNAMIC_FEE_V2       // Dynamic fee hook
+ADDRESSES.LP_LOCKER_FEE_CONVERSION  // Default locker (converts fees to ETH)
+ADDRESSES.SNIPER_AUCTION_V2         // Default MEV module
+ADDRESSES.UNIV4_ETH_DEV_BUY         // Dev buy extension
+EXTERNAL.WETH                       // Base WETH
+EXTERNAL.POOL_MANAGER               // Uniswap V4 Pool Manager
+```

package/skills/index-tokens.md

@@ -0,0 +1,501 @@
+# Skill: Index Liquid Protocol Tokens
+
+You are an AI agent that indexes and tracks token deployments on Liquid Protocol. This skill teaches you how to discover tokens, build an index, track new launches in real-time, and query the full on-chain state of any Liquid token on Base.
+
+## What You Can Index
+
+Every token deployed through Liquid Protocol emits a `TokenCreated` event with rich on-chain data:
+
+- Token address, name, symbol, image URL
+- Deployer address and admin address
+- Metadata (description, social links, audit URLs)
+- Context (originating interface, platform, social post ID)
+- Uniswap V4 pool ID, hook contract, paired token
+- LP locker address and MEV module
+- Extensions (dev buy, vault, airdrop, etc.)
+- Block number (for pagination/ordering)
+
+All of this is queryable directly from Base mainnet — no backend, no API keys, no database required.
+
+## Prerequisites
+
+```bash
+npm install liquid-sdk viem
+```
+
+## Setup
+
+```typescript
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { LiquidSDK } from "liquid-sdk";
+
+// Read-only — no wallet needed for indexing
+const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+const sdk = new LiquidSDK({ publicClient });
+```
+
+## Core Indexing Methods
+
+### 1. Get All Tokens
+
+```typescript
+const allTokens = await sdk.getTokens();
+
+console.log(`Total tokens: ${allTokens.length}`);
+for (const token of allTokens) {
+  console.log(`${token.tokenName} (${token.tokenSymbol}) — ${token.tokenAddress}`);
+  console.log(`  Deployed by: ${token.msgSender}`);
+  console.log(`  Pool ID: ${token.poolId}`);
+  console.log(`  Block: ${token.blockNumber}`);
+}
+```
+
+### 2. Get Tokens by Deployer
+
+```typescript
+// All tokens launched by a specific wallet
+const myTokens = await sdk.getTokens({ deployer: "0x1234..." });
+
+// Or use the convenience wrapper
+const myTokens2 = await sdk.getDeployedTokens("0x1234...");
+```
+
+Note: `msgSender` (deployer) is **not indexed** on-chain, so the SDK fetches all events and filters client-side. For large ranges, use block pagination to keep RPC calls manageable.
+
+### 3. Look Up a Single Token
+
+```typescript
+// Fast O(1) lookup — tokenAddress IS indexed on-chain
+const token = await sdk.getTokenEvent("0xTokenAddress...");
+
+if (token) {
+  console.log(`${token.tokenName} (${token.tokenSymbol})`);
+  console.log(`Pool: ${token.poolId}`);
+  console.log(`Hook: ${token.poolHook}`);
+  console.log(`Locker: ${token.locker}`);
+  console.log(`MEV Module: ${token.mevModule}`);
+  console.log(`Extensions: ${token.extensions}`);
+  console.log(`Image: ${token.tokenImage}`);
+} else {
+  console.log("Not a Liquid Protocol token");
+}
+```
+
+### 4. Paginate with Block Ranges
+
+```typescript
+// Page through tokens using block numbers
+const BLOCK_SIZE = 100_000n;
+let fromBlock = 20_000_000n; // start from factory deployment block
+let allTokens: TokenCreatedEvent[] = [];
+
+while (true) {
+  const toBlock = fromBlock + BLOCK_SIZE;
+  const page = await sdk.getTokens({ fromBlock, toBlock });
+
+  allTokens.push(...page);
+  console.log(`Fetched ${page.length} tokens from blocks ${fromBlock}–${toBlock}`);
+
+  if (page.length === 0) break; // no more tokens
+  fromBlock = toBlock + 1n;
+}
+
+console.log(`Total indexed: ${allTokens.length} tokens`);
+```
+
+### 5. Cursor-Based Pagination
+
+```typescript
+// Use the last token's blockNumber as cursor for next page
+let cursor = 0n;
+const PAGE_SIZE = 50;
+
+async function getNextPage() {
+  const tokens = await sdk.getTokens({ fromBlock: cursor + 1n });
+
+  if (tokens.length > 0) {
+    cursor = tokens[tokens.length - 1].blockNumber!;
+  }
+
+  return tokens;
+}
+```
+
+## TokenCreatedEvent Schema
+
+```typescript
+interface TokenCreatedEvent {
+  // Addresses
+  msgSender: Address;         // Wallet that called deployToken()
+  tokenAddress: Address;      // The deployed ERC-20 (indexed on-chain)
+  tokenAdmin: Address;        // Can update image/metadata (indexed on-chain)
+
+  // Token Metadata
+  tokenName: string;          // e.g., "My Token"
+  tokenSymbol: string;        // e.g., "MTK"
+  tokenImage: string;         // Image URL or empty string
+  tokenMetadata: string;      // JSON string — parse with parseMetadata()
+  tokenContext: string;       // JSON string — parse with parseContext()
+
+  // Pool Configuration
+  startingTick: number;       // Initial Uniswap V4 tick (int24)
+  poolHook: Address;          // Hook contract (static or dynamic fee)
+  poolId: Hex;                // Uniswap V4 pool identifier (bytes32)
+  pairedToken: Address;       // Quote token (usually WETH)
+
+  // Infrastructure
+  locker: Address;            // LP locker contract
+  mevModule: Address;         // MEV module (usually Sniper Auction V2)
+  extensionsSupply: bigint;   // Total supply allocated to extensions (wei)
+  extensions: Address[];      // Active extension contracts
+
+  // Block Info
+  blockNumber?: bigint;       // Block where event was emitted
+}
+```
+
+## Parsing Metadata and Context
+
+The `tokenMetadata` and `tokenContext` fields are JSON strings. Use the SDK's parsers:
+
+```typescript
+import { parseMetadata, parseContext } from "liquid-sdk";
+
+const token = await sdk.getTokenEvent(tokenAddress);
+
+// Parse metadata
+const meta = parseMetadata(token.tokenMetadata);
+if (meta) {
+  console.log("Description:", meta.description);
+  console.log("Social links:", meta.socialMediaUrls); // [{ platform, url }]
+  console.log("Audit URLs:", meta.auditUrls);
+}
+
+// Parse context (deployment provenance)
+const ctx = parseContext(token.tokenContext);
+if (ctx) {
+  console.log("Interface:", ctx.interface);   // "SDK", "Rainbow Wallet", etc.
+  console.log("Platform:", ctx.platform);     // "Farcaster", "Twitter", etc.
+  console.log("Message ID:", ctx.messageId);  // Social post ID
+  console.log("User ID:", ctx.id);
+}
+```
+
+**Context types:**
+```typescript
+interface LiquidContext {
+  interface: string;    // System that deployed (e.g., "SDK", "My App")
+  platform?: string;    // Social platform
+  messageId?: string;   // Social post/cast ID
+  id?: string;          // User ID on platform
+}
+
+interface LiquidMetadata {
+  description?: string;
+  socialMediaUrls?: { platform: string; url: string }[];
+  auditUrls?: string[];
+}
+```
+
+## Enriching Token Data
+
+Once you have the token event, you can query additional on-chain state:
+
+### Full Token Info
+
+```typescript
+const info = await sdk.getTokenInfo(tokenAddress);
+console.log(`${info.name} (${info.symbol})`);
+console.log(`Decimals: ${info.decimals}`);       // always 18
+console.log(`Supply: ${info.totalSupply}`);       // 100 billion * 10^18
+console.log(`Hook: ${info.deployment.hook}`);
+console.log(`Locker: ${info.deployment.locker}`);
+console.log(`Extensions: ${info.deployment.extensions}`);
+```
+
+### Reward Configuration
+
+```typescript
+const rewards = await sdk.getTokenRewards(tokenAddress);
+console.log("Recipients:", rewards.rewardRecipients);
+console.log("Splits (bps):", rewards.rewardBps);   // e.g., [7000, 3000]
+console.log("Admins:", rewards.rewardAdmins);
+console.log("Pool key:", rewards.poolKey);
+console.log("Position ID:", rewards.positionId);
+console.log("Num positions:", rewards.numPositions);
+```
+
+### Pool State
+
+```typescript
+const poolConfig = await sdk.getPoolConfig(poolId);
+console.log("Base fee:", poolConfig.baseFee);
+console.log("Max LP fee:", poolConfig.maxLpFee);
+
+const feeState = await sdk.getPoolFeeState(poolId);
+console.log("Reference tick:", feeState.referenceTick);
+console.log("Last swap:", feeState.lastSwapTimestamp);
+
+const createdAt = await sdk.getPoolCreationTimestamp(poolId);
+console.log("Pool created:", new Date(Number(createdAt) * 1000));
+
+const isToken0 = await sdk.isLiquidToken0(poolId);
+console.log("Liquid is token0:", isToken0);
+```
+
+### MEV / Auction State
+
+```typescript
+const auction = await sdk.getAuctionState(poolId);
+console.log("Auction round:", auction.round);
+console.log("Current fee:", auction.currentFee);
+console.log("Gas peg:", auction.gasPeg);
+
+const unlockTime = await sdk.getPoolUnlockTime(poolId);
+const now = BigInt(Math.floor(Date.now() / 1000));
+console.log("Pool locked:", now < unlockTime);
+```
+
+### Fee & Reward Balances
+
+```typescript
+// Check accrued fees
+const fees = await sdk.getAvailableFees(feeOwner, tokenAddress);
+const claimable = await sdk.getFeesToClaim(feeOwner, tokenAddress);
+console.log("Total fees:", fees);
+console.log("Claimable now:", claimable);
+```
+
+### Vault State (if token has vault extension)
+
+```typescript
+const vault = await sdk.getVaultAllocation(tokenAddress);
+console.log("Total locked:", vault.amountTotal);
+console.log("Claimed:", vault.amountClaimed);
+console.log("Lockup ends:", new Date(Number(vault.lockupEndTime) * 1000));
+console.log("Vesting ends:", new Date(Number(vault.vestingEndTime) * 1000));
+```
+
+### Airdrop State (if token has airdrop extension)
+
+```typescript
+const airdrop = await sdk.getAirdropInfo(tokenAddress);
+console.log("Merkle root:", airdrop.merkleRoot);
+console.log("Total supply:", airdrop.totalSupply);
+console.log("Claimed:", airdrop.totalClaimed);
+```
+
+## Complete Example: Build a Token Index
+
+```typescript
+import { createPublicClient, http, formatEther } from "viem";
+import { base } from "viem/chains";
+import { LiquidSDK, parseMetadata, parseContext, ADDRESSES } from "liquid-sdk";
+
+async function buildIndex() {
+  const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+  const sdk = new LiquidSDK({ publicClient });
+
+  // Fetch all tokens
+  const tokens = await sdk.getTokens();
+  console.log(`Indexing ${tokens.length} tokens...\n`);
+
+  const index = [];
+
+  for (const token of tokens) {
+    const meta = parseMetadata(token.tokenMetadata);
+    const ctx = parseContext(token.tokenContext);
+
+    const entry = {
+      address: token.tokenAddress,
+      name: token.tokenName,
+      symbol: token.tokenSymbol,
+      image: token.tokenImage,
+      description: meta?.description ?? null,
+      socialLinks: meta?.socialMediaUrls ?? [],
+      deployer: token.msgSender,
+      deployedAt: token.blockNumber,
+      poolId: token.poolId,
+      pairedToken: token.pairedToken,
+      hook: token.poolHook,
+      locker: token.locker,
+      mevModule: token.mevModule,
+      extensions: token.extensions,
+      launchedVia: ctx?.interface ?? "unknown",
+      platform: ctx?.platform ?? null,
+      castId: ctx?.messageId ?? null,
+    };
+
+    index.push(entry);
+  }
+
+  return index;
+}
+
+// Usage
+const index = await buildIndex();
+console.log(JSON.stringify(index, null, 2));
+```
+
+## Complete Example: Real-Time Token Monitor
+
+```typescript
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { LiquidSDK, parseContext, ADDRESSES } from "liquid-sdk";
+
+async function monitorNewTokens(callback: (token: any) => void) {
+  const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+  const sdk = new LiquidSDK({ publicClient });
+
+  let lastBlock = await publicClient.getBlockNumber();
+
+  console.log(`Monitoring from block ${lastBlock}...`);
+
+  setInterval(async () => {
+    try {
+      const currentBlock = await publicClient.getBlockNumber();
+      if (currentBlock <= lastBlock) return;
+
+      const newTokens = await sdk.getTokens({
+        fromBlock: lastBlock + 1n,
+        toBlock: currentBlock,
+      });
+
+      for (const token of newTokens) {
+        const ctx = parseContext(token.tokenContext);
+        console.log(`\nNew token: ${token.tokenName} (${token.tokenSymbol})`);
+        console.log(`  Address: ${token.tokenAddress}`);
+        console.log(`  Deployer: ${token.msgSender}`);
+        console.log(`  Pool ID: ${token.poolId}`);
+        console.log(`  Launched via: ${ctx?.interface ?? "unknown"}`);
+        callback(token);
+      }
+
+      lastBlock = currentBlock;
+    } catch (err) {
+      console.error("Poll error:", err);
+    }
+  }, 2000); // poll every 2 seconds (Base block time)
+}
+
+// Usage
+monitorNewTokens((token) => {
+  // Process new token — save to DB, send alert, etc.
+});
+```
+
+## Complete Example: Enrich a Token for Display
+
+```typescript
+async function enrichToken(tokenAddress: `0x${string}`) {
+  const publicClient = createPublicClient({ chain: base, transport: http(RPC_URL) });
+  const sdk = new LiquidSDK({ publicClient });
+
+  // Parallel queries for speed
+  const [event, info, rewards] = await Promise.all([
+    sdk.getTokenEvent(tokenAddress),
+    sdk.getTokenInfo(tokenAddress),
+    sdk.getTokenRewards(tokenAddress),
+  ]);
+
+  if (!event) return null;
+
+  const meta = parseMetadata(event.tokenMetadata);
+
+  // Pool state (parallel)
+  const [poolConfig, feeState, createdAt, auctionState] = await Promise.all([
+    sdk.getPoolConfig(event.poolId),
+    sdk.getPoolFeeState(event.poolId),
+    sdk.getPoolCreationTimestamp(event.poolId),
+    sdk.getAuctionState(event.poolId),
+  ]);
+
+  return {
+    token: {
+      address: tokenAddress,
+      name: info.name,
+      symbol: info.symbol,
+      decimals: info.decimals,
+      totalSupply: info.totalSupply.toString(),
+      image: event.tokenImage,
+      description: meta?.description,
+      socialLinks: meta?.socialMediaUrls,
+    },
+    deployment: {
+      deployer: event.msgSender,
+      admin: event.tokenAdmin,
+      block: event.blockNumber,
+      hook: event.poolHook,
+      locker: event.locker,
+      extensions: event.extensions,
+    },
+    pool: {
+      id: event.poolId,
+      pairedToken: event.pairedToken,
+      baseFee: poolConfig.baseFee,
+      maxLpFee: poolConfig.maxLpFee,
+      createdAt: Number(createdAt),
+      referenceTick: feeState.referenceTick,
+    },
+    rewards: {
+      recipients: rewards.rewardRecipients,
+      splits: rewards.rewardBps,
+      numPositions: Number(rewards.numPositions),
+    },
+    auction: {
+      round: Number(auctionState.round),
+      currentFee: auctionState.currentFee,
+      gasPeg: auctionState.gasPeg.toString(),
+    },
+  };
+}
+```
+
+## On-Chain Event Signature
+
+The `TokenCreated` event emitted by the Liquid Factory:
+
+```solidity
+event TokenCreated(
+  address msgSender,             // NOT indexed — filtered client-side
+  address indexed tokenAddress,  // indexed — efficient single lookup
+  address indexed tokenAdmin,    // indexed — filter by admin
+  string tokenImage,
+  string tokenName,
+  string tokenSymbol,
+  string tokenMetadata,
+  string tokenContext,
+  int24 startingTick,
+  address poolHook,
+  bytes32 poolId,
+  address pairedToken,
+  address locker,
+  address mevModule,
+  uint256 extensionsSupply,
+  address[] extensions
+);
+```
+
+**Indexing implications:**
+- `getTokenEvent(address)` is a single RPC call (uses indexed `tokenAddress`)
+- `getTokens({ deployer })` requires fetching all events then filtering (msgSender not indexed)
+- Block-range pagination is the primary scaling mechanism for large datasets
+
+## Performance Tips
+
+1. **Use `getTokenEvent()` for single lookups** — it's O(1) via the indexed field
+2. **Paginate with block ranges** for bulk indexing — avoid fetching the entire history in one call
+3. **Parallelize enrichment queries** with `Promise.all()` — pool config, rewards, auction state are all independent reads
+4. **Cache block numbers** to avoid re-indexing already-seen tokens
+5. **Base block time is ~2s** — poll at this interval for near-real-time monitoring
+
+## Contract Address
+
+```typescript
+import { ADDRESSES } from "liquid-sdk";
+
+ADDRESSES.FACTORY  // 0x0000003482fe299E72d4908368044A8A173BE576
+// All TokenCreated events are emitted from this address
+```