liquid-sdk 1.5.9 → 1.6.1

package/README.md

@@ -8,9 +8,10 @@ The SDK ships with **agent skill files** — self-contained markdown guides that
 
 | 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 |
+| **SDK Overview** | `skills/sdk-overview.md` | Full capabilities, data schemas (metadata, context, rewards, vault, airdrop), default config — load this first |
+| **Deploy Token** | `skills/deploy-token.md` | Deployment workflows — minimal deploy, dev buy, custom fees, custom positions, reward splits |
 | **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 |
+| **Index Tokens** | `skills/index-tokens.md` | Token discovery — bulk queries, single lookup, pagination, real-time monitoring |
 
 ### Using Skills with Your Agent
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "liquid-sdk",
-  "version": "1.5.9",
+  "version": "1.6.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",
+  "homepage": "https://github.com/Liquid-Protocol-Ops/SDK#readme",
   "bugs": {
-    "url": "https://github.com/craigbots/liquid-sdk/issues"
+    "url": "https://github.com/Liquid-Protocol-Ops/SDK/issues"
   },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -49,7 +49,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/craigbots/liquid-sdk"
+    "url": "https://github.com/Liquid-Protocol-Ops/SDK"
   },
   "keywords": [
     "liquid",

package/skills/bid-in-auction.md

@@ -2,6 +2,33 @@
 
 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.
 
+## IMPORTANT: Risk Disclosure
+
+**Before executing any auction bid, you MUST inform the user of the following risks and obtain explicit confirmation to proceed.**
+
+Sniper auction participation involves significant financial risk:
+
+1. **High fees (up to 80%)**: During the auction window, swap fees start at 80% and decay to 40%. This means up to 80% of your swap input is taken as fees — you receive far fewer tokens than the input amount suggests.
+
+2. **Bid amount is non-refundable**: The ETH bid (`msg.value`) is paid to the protocol/LP holders regardless of whether the swap is profitable. If the token price drops, you lose both the bid and the trade.
+
+3. **Failed transactions still cost gas**: If your bid loses (outbid by higher gas price, wrong round, missed block), the transaction reverts but you still pay gas fees. On Base, gas is cheap, but repeated failures add up.
+
+4. **Tokens may have no liquidity or value**: Newly launched tokens are unaudited, may have no community, and can go to zero. The auction gives you early access — it does not guarantee the token has any value.
+
+5. **MEV competition**: Other bots and agents are competing in the same auction. You may be consistently outbid by more sophisticated actors with faster infrastructure.
+
+6. **Timing is critical and unreliable**: The auction is valid for exactly one block (~2 seconds on Base). Network latency, RPC delays, or block reorgs can cause your transaction to land in the wrong block and revert.
+
+7. **Smart contract risk**: The auction contracts are unaudited for this specific deployment. Bugs or misconfigurations could result in loss of funds.
+
+**As an agent, you MUST:**
+- Clearly present these risks to the user before their first auction bid
+- Ask for explicit confirmation (e.g., "I understand the risks of auction sniping and want to proceed")
+- Never execute auction bids autonomously without user approval for each bid, unless the user has explicitly granted standing permission
+- Display the fee percentage and total cost (bid + swap + fees) before execution
+- Recommend small amounts for initial bids until the user understands the mechanics
+
 ## 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:

package/skills/sdk-overview.md

@@ -0,0 +1,332 @@
+# Skill: Liquid SDK Overview
+
+You are an AI agent working with the `liquid-sdk` package. This file gives you a complete picture of what the SDK can do, the data schemas it uses, and how all the pieces fit together. Load a specific skill file (`deploy-token.md`, `bid-in-auction.md`, `index-tokens.md`) when you need step-by-step instructions for a task.
+
+## What Liquid Protocol Does
+
+Liquid Protocol deploys ERC-20 tokens on Base (chain ID 8453) with:
+- **Uniswap V4 pools** created and funded automatically
+- **Permanently locked LP** — liquidity cannot be rugged
+- **Configurable fee splits** — reward recipients earn LP fees in ETH
+- **MEV protection** — sniper auction prices early trading activity
+- **Extensions** — dev buy, vault lockup/vesting, merkle airdrops
+
+Every token gets 100 billion supply (18 decimals), a Uniswap V4 pool paired with WETH, and locked liquidity.
+
+## Install
+
+```bash
+npm install liquid-sdk viem
+```
+
+## SDK Capabilities at a Glance
+
+| Category | What you can do |
+|----------|----------------|
+| **Deploy** | Launch tokens with custom fees, positions, reward splits, dev buys |
+| **Snipe** | Bid in MEV auctions for early access to new tokens |
+| **Index** | Discover all tokens, query by deployer, paginate by block range |
+| **Fees** | Check and claim accumulated LP fees (converted to ETH) |
+| **Rewards** | Collect LP rewards, update reward recipients |
+| **Vault** | Check vesting schedules, claim unlocked tokens |
+| **Airdrop** | Check allocations, claim with merkle proofs |
+| **Pool reads** | Fee config, fee state, creation time, token sort order |
+| **MEV reads** | Auction state, fee decay, gas peg, block delay |
+| **Metadata** | Update token image and metadata on-chain (admin only) |
+
+## Data Schemas
+
+### Token Identity (set at deployment)
+
+These fields define how the token appears in wallets, aggregators, and explorers:
+
+```typescript
+const result = await sdk.deployToken({
+  name: "My Project Token",                    // Token name (required)
+  symbol: "MPT",                               // Token symbol (required)
+  image: "https://example.com/logo.png",       // Logo URL (shown in wallets)
+  metadata: buildMetadata({                    // Rich metadata (JSON, on-chain)
+    description: "A community token for builders on Base",
+    socialMediaUrls: [
+      { platform: "Website", url: "https://myproject.xyz" },
+      { platform: "Twitter", url: "https://x.com/myproject" },
+      { platform: "Discord", url: "https://discord.gg/myproject" },
+      { platform: "Telegram", url: "https://t.me/myproject" },
+      { platform: "GitHub", url: "https://github.com/myproject" },
+    ],
+    auditUrls: [
+      "https://audits.example.com/myproject-audit.pdf",
+    ],
+  }),
+  context: buildContext({                      // Deployment provenance
+    interface: "My App",
+    platform: "Farcaster",
+  }),
+});
+```
+
+**After deployment, you can update image and metadata (admin only):**
+```typescript
+await sdk.updateImage(tokenAddress, "https://new-logo.example.com/v2.png");
+await sdk.updateMetadata(tokenAddress, buildMetadata({
+  description: "Updated description",
+  socialMediaUrls: [
+    { platform: "Website", url: "https://myproject.xyz" },
+    { platform: "Twitter", url: "https://x.com/myproject_new" },
+  ],
+}));
+```
+
+### Token Metadata Schema
+
+Stored in the `tokenMetadata` field of the `TokenCreated` event. Wallets (Rainbow, Coinbase Wallet) and aggregators (Matcha, 0x) read this.
+
+```typescript
+import { buildMetadata, parseMetadata } from "liquid-sdk";
+
+// Build
+const metadata = buildMetadata({
+  description: "A community token for builders on Base",
+  socialMediaUrls: [
+    { platform: "Twitter", url: "https://x.com/myproject" },
+    { platform: "Discord", url: "https://discord.gg/myproject" },
+    { platform: "Telegram", url: "https://t.me/myproject" },
+    { platform: "Website", url: "https://myproject.xyz" },
+  ],
+  auditUrls: [
+    "https://audits.example.com/myproject-audit.pdf",
+  ],
+});
+
+// Parse (from on-chain event data)
+const parsed = parseMetadata(tokenEvent.tokenMetadata);
+// parsed.description     — string
+// parsed.socialMediaUrls — { platform: string, url: string }[]
+// parsed.auditUrls       — string[]
+```
+
+**Schema:**
+```typescript
+interface LiquidMetadata {
+  description?: string;              // Token/project description
+  socialMediaUrls?: SocialMediaUrl[];// Links shown by wallets & aggregators
+  auditUrls?: string[];              // Audit report URLs
+}
+
+interface SocialMediaUrl {
+  platform: string;  // "Website", "Twitter", "Discord", "Telegram", "GitHub", etc.
+  url: string;       // Full URL
+}
+```
+
+**Common platform values:** `"Website"`, `"Twitter"`, `"Discord"`, `"Telegram"`, `"GitHub"`, `"Farcaster"`, `"Instagram"`, `"YouTube"`
+
+### Token Context (deployment provenance)
+
+Stored in the `tokenContext` field. Tracks where/how the token was launched.
+
+```typescript
+import { buildContext, parseContext } from "liquid-sdk";
+
+// Build
+const context = buildContext({
+  interface: "My Agent",        // what system deployed it
+  platform: "Farcaster",        // social platform (optional)
+  messageId: "0xabc123",        // cast/post ID (optional)
+  id: "user-12345",             // user ID on platform (optional)
+});
+
+// Parse
+const parsed = parseContext(tokenEvent.tokenContext);
+// parsed.interface  — "My Agent"
+// parsed.platform   — "Farcaster"
+// parsed.messageId  — "0xabc123"
+```
+
+**Schema:**
+```typescript
+interface LiquidContext {
+  interface: string;    // Required. System that deployed ("SDK", "Rainbow Wallet", etc.)
+  platform?: string;    // Social platform origin
+  messageId?: string;   // Social post/message ID
+  id?: string;          // User ID on platform
+}
+```
+
+### Reward Configuration
+
+Set at deployment. Controls who receives LP fees and in what proportion.
+
+```typescript
+// Deploy with custom reward splits
+const result = await sdk.deployToken({
+  name: "Split Token",
+  symbol: "SPLIT",
+  rewardAdmins: [walletA, walletB, treasury],
+  rewardRecipients: [walletA, walletB, treasury],
+  rewardBps: [5000, 3000, 2000],  // 50% / 30% / 20%
+});
+
+// Read reward config for any token
+const rewards = await sdk.getTokenRewards(tokenAddress);
+rewards.rewardRecipients  // Address[] — who gets paid
+rewards.rewardBps         // number[]  — basis points per recipient (sum = 10000)
+rewards.rewardAdmins      // Address[] — who can update each recipient
+rewards.poolKey           // PoolKey   — the Uniswap V4 pool
+rewards.positionId        // bigint    — LP position NFT ID
+rewards.numPositions      // bigint    — number of LP positions
+
+// Update a recipient (only the admin at that index can do this)
+await sdk.updateRewardRecipient(tokenAddress, 0n, newWalletAddress);
+
+// Collect rewards (distributes to all recipients per their bps)
+await sdk.collectRewards(tokenAddress);
+```
+
+**Rules:**
+- `rewardRecipients`, `rewardAdmins`, and `rewardBps` arrays must be the same length
+- `rewardBps` must sum to 10000 (100%)
+- BPS splits are **immutable** after deployment — only recipient addresses can change
+- Each admin can only update the recipient at their own index
+- All fees are converted to ETH before distribution (default `FeePreference.Paired`)
+
+### Dev Buy (buy tokens at launch)
+
+Buys tokens with ETH in the same transaction as deployment. The ETH is swapped through the Uniswap V4 pool atomically.
+
+```typescript
+const result = await sdk.deployToken({
+  name: "My Token",
+  symbol: "MTK",
+  devBuy: {
+    ethAmount: parseEther("0.01"),  // ETH to spend buying tokens
+    recipient: account.address,      // who receives the purchased tokens
+  },
+});
+```
+
+**Schema:**
+```typescript
+interface DevBuyParams {
+  ethAmount: bigint;    // ETH to swap for tokens (sent as msg.value)
+  recipient: Address;   // Address that receives the purchased tokens
+}
+```
+
+### Vault (token lockup + vesting)
+
+Lock tokens with a lockup period followed by linear vesting.
+
+```typescript
+// Read vault state
+const vault = await sdk.getVaultAllocation(tokenAddress);
+vault.amountTotal     // bigint — total tokens locked
+vault.amountClaimed   // bigint — already claimed
+vault.lockupEndTime   // bigint — unix timestamp when lockup ends
+vault.vestingEndTime  // bigint — unix timestamp when fully vested
+vault.admin           // Address — who can claim
+vault.token           // Address — the token
+
+// Check claimable now
+const claimable = await sdk.getVaultClaimable(tokenAddress);
+
+// Claim
+if (claimable > 0n) {
+  await sdk.claimVault(tokenAddress);
+}
+```
+
+### Airdrop (merkle distribution)
+
+Distribute tokens to a list of recipients via merkle proof claims.
+
+```typescript
+// Read airdrop state
+const info = await sdk.getAirdropInfo(tokenAddress);
+info.merkleRoot     // Hex — merkle root
+info.totalSupply    // bigint — total airdrop supply
+info.totalClaimed   // bigint — already claimed
+info.lockupEndTime  // bigint — when claims begin
+info.vestingEndTime // bigint — when vesting completes
+info.admin          // Address — airdrop admin
+
+// Check claimable for a recipient
+const claimable = await sdk.getAirdropClaimable(tokenAddress, recipientAddress, allocatedAmount);
+
+// Claim (proof must be generated off-chain from the merkle tree)
+await sdk.claimAirdrop(tokenAddress, recipientAddress, allocatedAmount, merkleProof);
+```
+
+### Fee Claims
+
+LP fees accrue from trading activity. The LP Locker Fee Conversion contract converts all fees to ETH before distributing.
+
+```typescript
+// Check fees
+const available = await sdk.getAvailableFees(ownerAddress, tokenAddress);  // total unlocked
+const claimable = await sdk.getFeesToClaim(ownerAddress, tokenAddress);    // ready to claim
+
+// Claim
+if (claimable > 0n) {
+  await sdk.claimFees(ownerAddress, tokenAddress);
+}
+```
+
+### Token Metadata Updates (post-deploy)
+
+Only the token admin can update image and metadata after deployment.
+
+```typescript
+// Update image
+await sdk.updateImage(tokenAddress, "https://new-image.example.com/logo.png");
+
+// Update metadata
+await sdk.updateMetadata(tokenAddress, buildMetadata({
+  description: "Updated description",
+  socialMediaUrls: [
+    { platform: "Twitter", url: "https://twitter.com/updated" },
+  ],
+}));
+```
+
+## Default Configuration
+
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| Fee | 1% buy + 1% sell | Static, hook-controlled via `0x800000` flag |
+| Fee conversion | All → ETH | `FeePreference.Paired` per recipient |
+| Positions | 5-position Liquid layout | 10%/50%/15%/20%/5% from ~$20K to ~$1.2B |
+| MEV module | Sniper Auction V2 | 80%→40% over 20s, 5 rounds, 2-block interval |
+| Tick spacing | 200 | |
+| Starting tick | -230400 | ~10 ETH / ~$20K market cap |
+| Token supply | 100 billion (18 decimals) | Fixed for all tokens |
+| Reward split | 100% to deployer | Customizable at deploy |
+| Context | `{"interface":"SDK"}` | Auto-set, customizable |
+
+## Skill Files
+
+For step-by-step instructions, load the relevant skill:
+
+| Task | Skill file |
+|------|-----------|
+| Deploy a token | `skills/deploy-token.md` |
+| Bid in a sniper auction | `skills/bid-in-auction.md` |
+| Index/discover tokens | `skills/index-tokens.md` |
+
+## Exported Constants
+
+```typescript
+import { ADDRESSES, EXTERNAL, FEE, TOKEN, DEFAULTS, POOL_POSITIONS } from "liquid-sdk";
+
+// Key addresses
+ADDRESSES.FACTORY                    // Token factory
+ADDRESSES.HOOK_STATIC_FEE_V2        // Default hook (1% both ways)
+ADDRESSES.LP_LOCKER_FEE_CONVERSION  // Default locker (fees → ETH)
+ADDRESSES.SNIPER_AUCTION_V2         // Default MEV module
+
+// Fee constants
+FEE.DENOMINATOR    // 1,000,000
+FEE.BPS            // 10,000
+TOKEN.SUPPLY       // 100B * 10^18
+TOKEN.DECIMALS     // 18
+```