liquid-sdk 1.7.3 → 1.7.5

package/AGENT_README.md

@@ -35,7 +35,7 @@ No API keys, no backend, no database. The SDK talks directly to Base mainnet con
 Liquid Protocol deploys ERC-20 tokens on Base with:
 - Uniswap V4 liquidity pools (automatic)
 - LP fee collection and reward distribution
-- MEV protection via block delay
+- MEV protection via sniper auction
 - Optional extensions: dev buy, vault lockup/vesting, airdrops
 
 Every token gets 100 billion supply (18 decimals), a Uniswap V4 pool, and locked liquidity with configurable reward splits.
@@ -54,7 +54,7 @@ Requires wallet. Creates the token, pool, locks LP, and optionally buys tokens a
 const result = await sdk.deployToken({
   name: "My Token",
   symbol: "MTK",
-  image: "https://example.com/logo.png",     // optional
+  image: "ipfs://QmYourImageCID",              // optional, IPFS recommended
   metadata: '{"description":"A cool token"}', // optional, JSON string
   context: '{"platform":"my-app"}',           // optional, tracking/attribution
 
@@ -100,27 +100,27 @@ const ext = sdk.buildDevBuyExtension({
 
 Tokens generate LP fees from Uniswap V4 trading. These accrue in the Fee Locker and can be claimed by the fee owner.
 
-#### `sdk.getAvailableFees(feeOwner, feeToken?)` — Check total unlocked fees
+#### `sdk.getAvailableFees(feeOwner, tokenAddress)` — Check total unlocked fees
 
 ```typescript
-const fees = await sdk.getAvailableFees(ownerAddress);
-// fees: bigint — total fees available, defaulting to WETH-denominated claims
+const fees = await sdk.getAvailableFees(ownerAddress, tokenAddress);
+// fees: bigint — total fees available (in token's paired asset, usually WETH)
 ```
 
-#### `sdk.getFeesToClaim(feeOwner, feeToken?)` — Check claimable fees
+#### `sdk.getFeesToClaim(feeOwner, tokenAddress)` — Check claimable fees
 
 ```typescript
-const claimable = await sdk.getFeesToClaim(ownerAddress);
-// claimable: bigint — fees ready to claim right now (WETH by default)
+const claimable = await sdk.getFeesToClaim(ownerAddress, tokenAddress);
+// claimable: bigint — fees ready to claim right now
 ```
 
-#### `sdk.claimFees(feeOwner, feeToken?)` — Claim fees
+#### `sdk.claimFees(feeOwner, tokenAddress)` — Claim fees
 
 Requires wallet.
 
 ```typescript
 if (claimable > 0n) {
-  const txHash = await sdk.claimFees(ownerAddress);
+  const txHash = await sdk.claimFees(ownerAddress, tokenAddress);
   await publicClient.waitForTransactionReceipt({ hash: txHash });
 }
 ```
@@ -161,7 +161,7 @@ const txHash = await sdk.collectRewardsWithoutUnlock(tokenAddress);
 await publicClient.waitForTransactionReceipt({ hash: txHash });
 ```
 
-**Important:** After deployment, the pool is locked for a MEV block delay. `collectRewardsWithoutUnlock` may revert with `ManagerLocked` if called too soon. Use `getPoolUnlockTime` to check.
+**Important:** After deployment, the sniper auction MEV module may block early reward collection. If `collectRewardsWithoutUnlock` reverts with `ManagerLocked`, wait for the auction period to end.
 
 #### `sdk.updateRewardRecipient(tokenAddress, rewardIndex, newRecipient)` — Change reward recipient
 
@@ -284,6 +284,49 @@ const deploy = await sdk.getDeploymentInfo(tokenAddress);
 
 ---
 
+### Token Discovery
+
+#### `sdk.getTokens(options?)` — Query all deployed tokens
+
+Query TokenCreated events with optional filtering. For wallet integrations, token listings, and indexing.
+
+```typescript
+// Get all tokens
+const allTokens = await sdk.getTokens();
+
+// Get tokens by deployer
+const myTokens = await sdk.getTokens({ deployer: myAddress });
+
+// Paginate with block ranges
+const page1 = await sdk.getTokens({ fromBlock: 20000000n, toBlock: 20100000n });
+const page2 = await sdk.getTokens({ fromBlock: 20100001n });
+```
+
+Each result includes full on-chain event data: name, symbol, image, metadata, context, poolId, hook, locker, extensions, and `blockNumber` for cursor-based pagination.
+
+#### `sdk.getTokenEvent(tokenAddress)` — Look up a single token's event data
+
+Fast lookup by contract address (tokenAddress is indexed on-chain = single RPC call).
+
+```typescript
+const event = await sdk.getTokenEvent(tokenAddress);
+// event.tokenName, event.tokenSymbol, event.tokenImage
+// event.tokenMetadata — parse with parseMetadata()
+// event.tokenContext  — parse with parseContext()
+// event.poolId, event.poolHook, event.locker, event.extensions
+// event.blockNumber
+```
+
+#### `sdk.getDeployedTokens(deployer, fromBlock?, toBlock?)` — Get tokens by deployer
+
+Convenience wrapper around `getTokens({ deployer })`.
+
+```typescript
+const tokens = await sdk.getDeployedTokens(deployerAddress);
+```
+
+---
+
 ### Token Metadata Updates
 
 #### `sdk.updateImage(tokenAddress, newImageUrl)` — Update token image
@@ -385,27 +428,50 @@ const maxRounds = await sdk.getAuctionMaxRounds();
 ```typescript
 const gasPrice = await sdk.getAuctionGasPriceForBid(
   auction.gasPeg,
-  parseEther("1"),  // desired bid
+  parseEther("0.001"),  // desired bid
 );
 ```
 
+#### `sdk.bidInAuction(params, gasPrice)` — Bid in auction and swap tokens
+
+Requires wallet. Auto-wraps ETH → WETH and approves SniperUtilV2 if needed. Sets gas manually (800K) and both `maxFeePerGas`/`maxPriorityFeePerGas` to the auction gas price.
+
+```typescript
+const rewards = await sdk.getTokenRewards(tokenAddress);
+const zeroForOne = rewards.poolKey.currency0.toLowerCase() === EXTERNAL.WETH.toLowerCase();
+
+const result = await sdk.bidInAuction({
+  poolKey: rewards.poolKey,
+  zeroForOne,                        // depends on token sort order vs WETH
+  amountIn: parseEther("0.001"),     // WETH to swap (auto-wrapped from ETH)
+  amountOutMinimum: 0n,              // set slippage in production
+  round: auction.round,              // must match current on-chain round
+  bidAmount: parseEther("0.0005"),   // ETH bid (sent as msg.value)
+}, gasPrice);
+// result.txHash — transaction hash
+```
+
+**Important:** The bid is valid only at `nextAuctionBlock`. Submit when `currentBlock === nextAuctionBlock - 1`. The `amountIn` is pulled from your WETH balance (separate from the bid's `msg.value`). Auction runs 5 rounds, every 2 blocks, starting 2 blocks after deployment.
+
 ---
 
-### MEV Protection
+### MEV Descending Fees
 
-#### `sdk.getMevBlockDelay()` — Get configured block delay
+#### `sdk.getMevDescendingFeesBlockDelay()` — Configured block delay
 
 ```typescript
-const delay = await sdk.getMevBlockDelay();
-// delay: bigint — number of blocks
+const delay = await sdk.getMevDescendingFeesBlockDelay();
+// delay: bigint — number of blocks the MEV module fee window covers
 ```
 
-#### `sdk.getPoolUnlockTime(poolId)` — When does MEV lock expire
+`sdk.getMevBlockDelay()` is a deprecated alias for the same call.
+
+#### `sdk.getPoolUnlockTime(poolId)` — When MEV lock expires
 
 ```typescript
 const unlockTime = await sdk.getPoolUnlockTime(poolId);
-// unlockTime: bigint — unix timestamp
-// If Date.now()/1000 < unlockTime, pool is still locked
+// If Date.now()/1000 < unlockTime, the pool is still inside the MEV window
+// and writes that go through the MevDescendingFees hook may revert with ManagerLocked.
 ```
 
 ---
@@ -442,20 +508,20 @@ When calling `deployToken`, all fields except `name` and `symbol` are optional.
 | `salt` | `keccak256(name + symbol + timestamp)` | Unique per deploy |
 | `image` | `""` | Empty string |
 | `metadata` | `""` | Empty string |
-| `context` | `""` | Empty string |
-| `hook` | `ADDRESSES.HOOK_DYNAMIC_FEE_V2` | Dynamic fee model |
+| `context` | `'{"interface":"SDK"}'` | Auto-set via `buildContext()` |
+| `hook` | `ADDRESSES.HOOK_STATIC_FEE_V2` | Static 1% buy + 1% sell |
 | `pairedToken` | `EXTERNAL.WETH` | Base WETH |
-| `tickIfToken0IsLiquid` | `-198720` | Starting price tick |
-| `tickSpacing` | `60` | Uniswap V4 tick spacing |
-| `poolData` | `"0x"` | Hook uses its default fee config |
-| `locker` | `ADDRESSES.LP_LOCKER` | Standard LP locker |
+| `tickIfToken0IsLiquid` | `-230400` | ≈10 ETH market cap |
+| `tickSpacing` | `200` | Uniswap V4 tick spacing |
+| `poolData` | `encodeStaticFeePoolData(100, 100)` | 1% sell, 1% buy |
+| `locker` | `ADDRESSES.LP_LOCKER_FEE_CONVERSION` | LP locker with fee conversion to ETH |
 | `rewardAdmins` | `[walletAddress]` | Deployer is admin |
 | `rewardRecipients` | `[walletAddress]` | Deployer gets rewards |
 | `rewardBps` | `[10000]` | 100% to deployer |
-| `tickLower` | `[-887220]` | Full-range lower |
-| `tickUpper` | `[887220]` | Full-range upper |
-| `positionBps` | `[10000]` | Single position, 100% |
-| `mevModule` | `ADDRESSES.MEV_BLOCK_DELAY` | MEV protection on |
+| `tickLower` | `[-230400, -216000, -202000, -155000, -141000]` | 5-position Liquid layout |
+| `tickUpper` | `[-216000, -155000, -155000, -120000, -120000]` | 5-position Liquid layout |
+| `positionBps` | `[1000, 5000, 1500, 2000, 500]` | 10% / 50% / 15% / 20% / 5% |
+| `mevModule` | `ADDRESSES.SNIPER_AUCTION_V2` | 80%→40% over 20s |
 | `extensions` | `[]` | No extensions |
 
 ---
@@ -468,19 +534,18 @@ All addresses are exported as `ADDRESSES` and `EXTERNAL`:
 import { ADDRESSES, EXTERNAL } from "liquid-sdk";
 
 // Liquid Protocol contracts
-ADDRESSES.FACTORY                  // 0x0000003482fe299E72d4908368044A8A173BE576
-ADDRESSES.LP_LOCKER                // 0x00000548732DfA56Be1257cE44D0CFc3B46dDb2A
-ADDRESSES.FEE_LOCKER               // 0x000008B9242b7e4432f6c4b1EeAD93562f9Cc94d
-ADDRESSES.VAULT                    // 0x000001c5263F4d64CdC343cDA9C8bF961CF8376c
-ADDRESSES.HOOK_DYNAMIC_FEE_V2      // 0x2A2F73CDDa098d639bd8Bbcd7dF2bf24E06728cC
-ADDRESSES.HOOK_STATIC_FEE_V2       // 0xb2401c5369AaCF62F8d615623C7F68F84da428Cc
-ADDRESSES.AIRDROP_V2               // 0x00000C222442512b08446D33dd9754a7F260BE79
-ADDRESSES.SNIPER_AUCTION_V2        // 0x000007b64003ee07a69576F98859a0a36b854260
-ADDRESSES.SNIPER_UTIL_V2           // 0x000003Ee0cb9B0C82C6C7FCB7b81a9883F285270
-ADDRESSES.MEV_BLOCK_DELAY          // 0x0000035D83588954F3c581c3A66251b3F06AD5e4
-ADDRESSES.UNIV4_ETH_DEV_BUY        // 0x00000d7DE1f0A3FA7957F5d8A2b97B0E24e5783D
-ADDRESSES.POOL_EXTENSION_ALLOWLIST  // 0x000003Afb1b070F037D2871eE0A6b8c8f53F7B77
-ADDRESSES.LIQUID_DEPLOYER_LIB      // 0x00000f88b2d37A2006F2F0C8552d22E0b8945202
+ADDRESSES.FACTORY                  // 0x04F1a284168743759BE6554f607a10CEBdB77760
+ADDRESSES.LP_LOCKER_FEE_CONVERSION // 0x77247fCD1d5e34A3703AcA898A591Dc7422435f3
+ADDRESSES.FEE_LOCKER               // 0xF7d3BE3FC0de76fA5550C29A8F6fa53667B876FF
+ADDRESSES.VAULT                    // 0xdFCCC93257c20519A9005A2281CFBdF84836d50E
+ADDRESSES.HOOK_DYNAMIC_FEE_V2      // 0x80E2F7dC8C2C880BbC4BDF80A5Fb0eB8B1DB68CC
+ADDRESSES.HOOK_STATIC_FEE_V2       // 0x9811f10Cd549c754Fa9E5785989c422A762c28cc
+ADDRESSES.AIRDROP_V2               // 0x1423974d48f525462f1c087cBFdCC20BDBc33CdD
+ADDRESSES.SNIPER_AUCTION_V2        // 0x187e8627c02c58F31831953C1268e157d3BfCefd
+ADDRESSES.SNIPER_UTIL_V2           // 0x2B6cd5Be183c388Dd0074d53c52317df1414cd9f
+ADDRESSES.MEV_DESCENDING_FEES      // 0x8D6B080e48756A99F3893491D556B5d6907b6910
+ADDRESSES.UNIV4_ETH_DEV_BUY        // 0x5934097864dC487D21A7B4e4EEe201A39ceF728D
+ADDRESSES.POOL_EXTENSION_ALLOWLIST  // 0xb614167d79aDBaA9BA35d05fE1d5542d7316Ccaa
 
 // External (Uniswap V4 / Base)
 EXTERNAL.POOL_MANAGER              // 0x498581fF718922c3f8e6A244956aF099B2652b2b
@@ -524,7 +589,8 @@ import {
   LiquidSniperUtilV2Abi,
   LiquidAirdropV2Abi,
   LiquidPoolExtensionAllowlistAbi,
-  LiquidMevBlockDelayAbi,
+  LiquidMevDescendingFeesAbi,
+  LiquidMevBlockDelayAbi, // deprecated alias — prefer LiquidMevDescendingFeesAbi
   LiquidLpLockerAbi,
   ERC20Abi,
 } from "liquid-sdk";
@@ -579,7 +645,7 @@ const sdk = new LiquidSDK({ publicClient, walletClient });
 const result = await sdk.deployToken({
   name: "Agent Token",
   symbol: "AGENT",
-  image: "https://example.com/logo.png",
+  image: "ipfs://QmYourImageCID",
   metadata: JSON.stringify({ description: "Deployed by an AI agent" }),
   devBuy: {
     ethAmount: parseEther("0.01"),
@@ -618,11 +684,11 @@ if (now < unlockTime) {
 ### 3. Check and claim fees
 
 ```typescript
-const fees = await sdk.getFeesToClaim(ownerAddress);
+const fees = await sdk.getFeesToClaim(ownerAddress, tokenAddress);
 console.log("Claimable fees:", fees);
 
 if (fees > 0n) {
-  const txHash = await sdk.claimFees(ownerAddress);
+  const txHash = await sdk.claimFees(ownerAddress, tokenAddress);
   const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
   console.log("Fees claimed in tx:", receipt.transactionHash);
 }

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `liquid-sdk` will be documented in this file.
 
+## [1.7.5] - 2026-06-09
+
+### Security
+- `bidInAuction` now approves WETH to `SniperUtilV2` for **exactly `amountIn`** (previously `amountIn * 10n`). Each bid's `transferFrom` consumes the full allowance, so **no standing WETH allowance survives** — removing the "drain via standing approval" surface that hit a sibling Clanker fork in 2026-05. Complements the protocol-level `paymentPerGasUnit == 0` mitigation already live on the auction contract. (#18)
+  - **Action for existing users:** if you bid through an older SDK that approved a multiplier, **revoke your residual WETH allowance to `SniperUtilV2` (`0x2B6cd5Be183c388Dd0074d53c52317df1414cd9f`)**.
+  - **Trade-off:** prior versions pre-approved 10× so 9 subsequent bids skipped the approve. Bots relying on that should either `WETH.approve(SNIPER_UTIL_V2, amountIn)` ahead of the auction window or start `bidInAuction` ~1 block earlier so the approve confirms in time.
+
+## [1.7.4] - 2026-04-23
+
+### Added
+- `EXTERNAL.DIEM` — the DIEM token address on Base, for DIEM-paired token launches.
+- `shiftPositions(positions, shiftBy)` — re-anchor a fixed-shape position layout to a different starting tick, preserving `positionBps`.
+- `createLiquidPositionsUSD(startingMarketCapUSD, pairedTokenPriceUSD, tickSpacing?)` — the canonical 5-position "Liquid" layout re-anchored to a starting market cap, denominated in the *paired token's* USD price. Works for any pair token (WETH or DIEM); unlike `createDefaultPositions` (3-tranche), it preserves the exact `POOL_POSITIONS.Liquid` curve `deployToken()` uses by default.
+
+### Fixed
+- `deployToken` gas estimation no longer silently swallows on-chain revert errors. Previously a failing `eth_estimateGas` (e.g., insufficient msg.value, paused factory, pre-flight check revert) would be caught and replaced with a 6M fallback, causing the tx to be broadcast and burn real gas for nothing. Now a revert-shaped error bubbles to the caller; only transport-level failures fall back. Non-revert fallbacks log a warning via `console.warn`.
+
 ## [1.7.3] - 2026-04-22
 
 ### Added