# liquid-sdk

> TypeScript SDK to deploy ERC-20 tokens with Uniswap V4 liquidity on Base — zero API keys, one dependency (viem)

## Install

```
npm install liquid-sdk viem
```

## Quick Start

```typescript
import { createPublicClient, createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { LiquidSDK } from "liquid-sdk";

const publicClient = createPublicClient({ chain: base, transport: http() });
const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({ account, chain: base, transport: http() });
const sdk = new LiquidSDK({ publicClient, walletClient });

const result = await sdk.deployToken({ name: "My Token", symbol: "MTK" });
console.log(result.tokenAddress);
```

## What It Does

Liquid Protocol deploys ERC-20 tokens on Base (chain 8453) with:
- Uniswap V4 liquidity pools (created automatically)
- Locked LP with configurable reward splits
- MEV protection (sniper auction with descending fees)
- Optional extensions: dev buy, vault lockup/vesting, merkle airdrops

Every token gets 100 billion supply (18 decimals), a Uniswap V4 pool, and locked liquidity.

## API Methods

### Token Deployment
- `sdk.deployToken(params)` — Deploy ERC-20 + Uniswap V4 pool. Params: name (required), symbol (required), image, metadata, context, devBuy, hook, tickSpacing, poolData, rewardRecipients, rewardBps, extensions
- `sdk.buildDevBuyExtension(devBuy)` — Build extension config for buying tokens at launch

### Fee Management
- `sdk.getAvailableFees(feeOwner, tokenAddress)` — Total unlocked fees (bigint)
- `sdk.getFeesToClaim(feeOwner, tokenAddress)` — Claimable fees right now (bigint)
- `sdk.claimFees(feeOwner, tokenAddress)` — Claim fees (returns txHash)

### LP Reward Management
- `sdk.getTokenRewards(tokenAddress)` — Reward config (recipients, bps, admins, poolKey)
- `sdk.collectRewards(tokenAddress)` — Collect + unlock LP (returns txHash)
- `sdk.collectRewardsWithoutUnlock(tokenAddress)` — Collect fees only (returns txHash)
- `sdk.updateRewardRecipient(tokenAddress, index, newRecipient)` — Change recipient (returns txHash)

### Vault (Token Lockup & Vesting)
- `sdk.getVaultAllocation(tokenAddress)` — Vault state (total, claimed, lockup/vesting times, admin)
- `sdk.getVaultClaimable(tokenAddress)` — Tokens available to claim now (bigint)
- `sdk.claimVault(tokenAddress)` — Claim vested tokens (returns txHash)

### Airdrop
- `sdk.getAirdropInfo(tokenAddress)` — Airdrop state (merkle root, supply, claimed, times)
- `sdk.getAirdropClaimable(tokenAddress, recipient, amount)` — Claimable for recipient (bigint)
- `sdk.claimAirdrop(tokenAddress, recipient, amount, proof)` — Claim airdrop (returns txHash)

### Token Info & Discovery
- `sdk.getTokenInfo(tokenAddress)` — Name, symbol, decimals, totalSupply, deployment addresses
- `sdk.getDeploymentInfo(tokenAddress)` — Token, hook, locker, extensions addresses
- `sdk.getTokens(options?)` — Query all deployed tokens with optional deployer filter and block range pagination. Returns full event data + blockNumber
- `sdk.getTokenEvent(tokenAddress)` — Look up single token's on-chain event data by address (indexed, single RPC call). Returns metadata, context, poolId, hook, extensions
- `sdk.getDeployedTokens(deployer, fromBlock?, toBlock?)` — Convenience wrapper for getTokens({ deployer })

### Token Metadata Updates
- `sdk.updateImage(tokenAddress, newImageUrl)` — Update token image (admin only)
- `sdk.updateMetadata(tokenAddress, newMetadata)` — Update token metadata (admin only)

### Pool Reads
- `sdk.getPoolConfig(poolId)` — Dynamic fee configuration
- `sdk.getPoolFeeState(poolId)` — Current fee state
- `sdk.getPoolCreationTimestamp(poolId)` — Pool creation time
- `sdk.isLiquidToken0(poolId)` — Token sort order in pool

### Sniper Auction (MEV)
- `sdk.getAuctionState(poolId)` — Current auction state (block, round, gasPeg, fee)
- `sdk.getAuctionFeeConfig(poolId)` — Fee parameters (starting, ending, decay)
- `sdk.getAuctionDecayStartTime(poolId)` — When fee decay started
- `sdk.getAuctionMaxRounds()` — Max auction rounds
- `sdk.getAuctionGasPriceForBid(gasPeg, bidAmount)` — Calculate gas price for bid

### MEV Descending Fees
- `sdk.getMevDescendingFeesBlockDelay()` — Configured block delay (also: `getMevBlockDelay()` deprecated alias)
- `sdk.getPoolUnlockTime(poolId)` — When MEV lock expires (unix timestamp)

### Factory & Allowlist
- `sdk.isFactoryDeprecated()` — Is factory still active
- `sdk.isLockerEnabled(locker, hook)` — Is locker approved for hook
- `sdk.isExtensionEnabled(extension)` — Is extension on allowlist

### Context & Metadata Helpers
- `buildContext({ interface?, platform?, messageId?, id? })` — Build JSON context string
- `buildMetadata({ description?, socialMediaUrls?, auditUrls? })` — Build JSON metadata string
- `parseContext(contextString)` — Parse context JSON to typed object
- `parseMetadata(metadataString)` — Parse metadata JSON to typed object

## Utility Functions

- `encodeStaticFeePoolData(liquidFeeBps, pairedFeeBps)` — Encode static fee config
- `encodeDynamicFeePoolData(config)` — Encode dynamic fee config
- `encodeSniperAuctionData(config)` — Encode MEV auction config
- `createPositions(startingCapETH, tranches)` — Build position arrays from ETH market caps
- `createPositionsUSD(startingCapUSD, ethPrice, tranches)` — Build from USD market caps
- `createDefaultPositions(startingCapUSD, ethPrice)` — Default 3-tranche (40%@$500K, 50%@$10M, 10%@$1B)
- `describePositions(positions, ethPrice?)` — Human-readable position descriptions
- `getTickFromMarketCapETH(capETH)` / `getTickFromMarketCapUSD(capUSD, ethPrice)` — Market cap → tick
- `marketCapFromTickETH(tick)` / `marketCapFromTickUSD(tick, ethPrice)` — Tick → market cap

## Default Values

| Field | Default |
|-------|---------|
| hook | Static fee V2 (1% buy + 1% sell) |
| tickSpacing | 200 |
| tickIfToken0IsLiquid | -230400 (~10 ETH market cap) |
| positions | 5-position Liquid layout: 10%/50%/15%/20%/5% |
| mevModule | Sniper Auction V2 (80%→40% over 20s) |
| rewardRecipients | [deployer] at 100% |
| context | {"interface":"SDK"} |

## Contract Addresses (Base Mainnet)

- Factory: 0x04F1a284168743759BE6554f607a10CEBdB77760
- LP Locker Fee Conversion: 0x77247fCD1d5e34A3703AcA898A591Dc7422435f3 (default)
- Fee Locker: 0xF7d3BE3FC0de76fA5550C29A8F6fa53667B876FF
- Vault: 0xdFCCC93257c20519A9005A2281CFBdF84836d50E
- Hook (Dynamic Fee V2): 0x80E2F7dC8C2C880BbC4BDF80A5Fb0eB8B1DB68CC
- Hook (Static Fee V2): 0x9811f10Cd549c754Fa9E5785989c422A762c28cc
- Sniper Auction V2: 0x187e8627c02c58F31831953C1268e157d3BfCefd
- MEV Descending Fees: 0x8D6B080e48756A99F3893491D556B5d6907b6910
- Sniper Util V2: 0x2B6cd5Be183c388Dd0074d53c52317df1414cd9f
- Airdrop V2: 0x1423974d48f525462f1c087cBFdCC20BDBc33CdD
- Dev Buy Extension: 0x5934097864dC487D21A7B4e4EEe201A39ceF728D
- Pool Extension Allowlist: 0xb614167d79aDBaA9BA35d05fE1d5542d7316Ccaa
- WETH (Base): 0x4200000000000000000000000000000000000006
- Pool Manager (Uniswap V4): 0x498581fF718922c3f8e6A244956aF099B2652b2b

## Docs

- README.md: Usage guide with code examples
- AGENT_README.md: Complete API reference for AI agents and developers (700+ lines)
- CHANGELOG.md: Version history
- examples/: 8 runnable TypeScript examples

## Links

- NPM: https://www.npmjs.com/package/liquid-sdk
- GitHub: https://github.com/craigbots/liquid-sdk