liquid-sdk 1.4.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liquid-sdk",
-  "version": "1.4.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
+```