liquid-sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `liquid-sdk` will be documented in this file.
+
+## [1.2.0] - 2025-03-10
+
+### Added
+- `getDeployedTokens(deployer, fromBlock?, toBlock?)` — query all tokens deployed by an address via on-chain events
+- `buildContext()` / `buildMetadata()` helpers for structured on-chain context and metadata
+- `parseContext()` / `parseMetadata()` for reading context/metadata back from on-chain strings
+- `LiquidContext` and `LiquidMetadata` type exports
+- Auto-default `context` field to `{"interface":"SDK"}` when no context is provided to `deployToken()`
+- `AGENT_README.md` — 700+ line reference optimized for AI agents and LLM-assisted development
+- `llms.txt` — structured summary following the llms-txt.org specification
+- `.cursor/skills/use-liquid-sdk/SKILL.md` — Cursor IDE auto-discovery skill
+- 8 runnable examples in `examples/` directory
+
+### Changed
+- Expanded NPM keywords for better discoverability (erc20, deploy, defi, web3, etc.)
+- Updated package description to highlight zero-API-key, single-dependency value prop
+- `files` array now includes README.md, AGENT_README.md, CHANGELOG.md, and llms.txt
+
+## [1.1.0] - 2025-02-28
+
+### Added
+- Custom position builders: `createPositions()`, `createPositionsUSD()`, `createDefaultPositions()`
+- `describePositions()` for human-readable market cap range descriptions
+- Tick ↔ market cap conversion utilities: `getTickFromMarketCapETH`, `getTickFromMarketCapUSD`, `marketCapFromTickETH`, `marketCapFromTickUSD`
+- Dynamic fee pool data encoding: `encodeDynamicFeePoolData()`
+- Sniper auction data encoding: `encodeSniperAuctionData()`
+- `DEFAULT_TRANCHES_USD` preset (40% @ $500K, 50% @ $10M, 10% @ $1B)
+- Pool reads: `getPoolConfig()`, `getPoolFeeState()`, `getPoolCreationTimestamp()`, `isLiquidToken0()`
+- Sniper auction reads: `getAuctionState()`, `getAuctionFeeConfig()`, `getAuctionDecayStartTime()`, `getAuctionMaxRounds()`, `getAuctionGasPriceForBid()`
+- MEV protection reads: `getMevBlockDelay()`, `getPoolUnlockTime()`
+- Comprehensive client-side validation in `deployToken()` with clear error messages
+
+### Changed
+- Default hook switched to `HOOK_STATIC_FEE_V2` with proper two-layer pool data encoding
+- Default positions changed from single full-range to 3-tranche Liquid preset
+- Default MEV module switched to `SNIPER_AUCTION_V2` with 80%→40% decay over 32s
+
+## [1.0.0] - 2025-02-15
+
+### Added
+- Initial release of `liquid-sdk`
+- `LiquidSDK` class with full token lifecycle support
+- `deployToken()` — deploy ERC-20 tokens with Uniswap V4 liquidity on Base
+- Dev buy support — buy tokens with ETH in the same deployment transaction
+- Fee management: `getAvailableFees()`, `getFeesToClaim()`, `claimFees()`
+- LP reward management: `getTokenRewards()`, `collectRewards()`, `collectRewardsWithoutUnlock()`, `updateRewardRecipient()`
+- Vault management: `getVaultAllocation()`, `getVaultClaimable()`, `claimVault()`
+- Airdrop support: `getAirdropInfo()`, `getAirdropClaimable()`, `claimAirdrop()`
+- Token info: `getTokenInfo()`, `getDeploymentInfo()`
+- Token metadata updates: `updateImage()`, `updateMetadata()`
+- Factory status checks: `isFactoryDeprecated()`, `isLockerEnabled()`, `isExtensionEnabled()`
+- Static fee pool data encoding: `encodeStaticFeePoolData()`
+- All 13 contract ABIs exported
+- All type definitions exported
+- Dual build output: CJS + ESM with TypeScript declarations
+- Single peer dependency: `viem ^2.0.0`

package/dist/index.d.mts

@@ -151,6 +151,17 @@ interface TokenCreatedEvent {
     mevModule: Address;
     extensionsSupply: bigint;
     extensions: Address[];
+    /** Block number where the token was created (populated by discovery methods) */
+    blockNumber?: bigint;
+}
+/** Options for querying deployed tokens. */
+interface GetTokensOptions {
+    /** Filter by deployer address (msgSender). If omitted, returns all tokens. */
+    deployer?: Address;
+    /** Starting block to search from (defaults to factory deployment block) */
+    fromBlock?: bigint;
+    /** Ending block to search to (defaults to 'latest') */
+    toBlock?: bigint | "latest";
 }
 interface AirdropInfo {
     admin: Address;
@@ -243,6 +254,50 @@ declare class LiquidSDK {
     isExtensionEnabled(extensionAddress: Address): Promise<boolean>;
     getMevBlockDelay(): Promise<bigint>;
     getPoolUnlockTime(poolId: Hex): Promise<bigint>;
+    /**
+     * Update a token's image. Must be called by the token admin.
+     */
+    updateImage(tokenAddress: Address, newImage: string): Promise<Hash>;
+    /**
+     * Update a token's metadata. Must be called by the token admin.
+     */
+    updateMetadata(tokenAddress: Address, newMetadata: string): Promise<Hash>;
+    /**
+     * Get all tokens deployed by a specific address by querying TokenCreated events.
+     * @param deployer - The address that deployed the tokens (msgSender)
+     * @param fromBlock - Starting block to search from (defaults to 0n)
+     * @param toBlock - Ending block to search to (defaults to 'latest')
+     */
+    getDeployedTokens(deployer: Address, fromBlock?: bigint, toBlock?: bigint | "latest"): Promise<TokenCreatedEvent[]>;
+    /**
+     * Query TokenCreated events with optional filtering.
+     *
+     * Use this for token discovery, indexing, or building token lists.
+     * Returns events in chronological order with block numbers for pagination.
+     *
+     * @example
+     * // 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, toBlock: 20200000n });
+     */
+    getTokens(options?: GetTokensOptions): Promise<TokenCreatedEvent[]>;
+    /**
+     * Look up a single token's on-chain event data by contract address.
+     *
+     * Returns the full TokenCreated event including metadata, context, poolId,
+     * hook, locker, extensions — everything a wallet or aggregator needs to
+     * display the token. Returns `null` if not found.
+     *
+     * This is indexed on-chain (tokenAddress is indexed in the event), so it's
+     * a single RPC call regardless of how many tokens exist.
+     */
+    getTokenEvent(tokenAddress: Address): Promise<TokenCreatedEvent | null>;
 }
 
 declare const ADDRESSES: {
@@ -320,6 +375,8 @@ declare const POOL_POSITIONS: {
  */
 declare const DEFAULTS: {
     readonly HOOK: `0x${string}`;
+    /** LP Locker with fee conversion (converts fees to ETH before distributing) */
+    readonly LOCKER: `0x${string}`;
     readonly TICK_SPACING: 200;
     readonly TICK_IF_TOKEN0_IS_LIQUID: -230400;
     /** Static fee on buys (ETH → token): 1% (100 bps). Fees collected in ETH. */
@@ -1592,6 +1649,312 @@ declare const LiquidLpLockerAbi: readonly [{
     readonly stateMutability: "view";
 }];
 
+declare const LiquidTokenAbi: readonly [{
+    readonly type: "function";
+    readonly name: "updateImage";
+    readonly inputs: readonly [{
+        readonly name: "image_";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "updateMetadata";
+    readonly inputs: readonly [{
+        readonly name: "metadata_";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "updateAdmin";
+    readonly inputs: readonly [{
+        readonly name: "admin_";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "event";
+    readonly name: "UpdateImage";
+    readonly inputs: readonly [{
+        readonly name: "image";
+        readonly type: "string";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "UpdateMetadata";
+    readonly inputs: readonly [{
+        readonly name: "metadata";
+        readonly type: "string";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "UpdateAdmin";
+    readonly inputs: readonly [{
+        readonly name: "oldAdmin";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "newAdmin";
+        readonly type: "address";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}];
+
+declare const LiquidUniv4EthDevBuyAbi: readonly [{
+    readonly type: "constructor";
+    readonly inputs: readonly [{
+        readonly name: "factory_";
+        readonly type: "address";
+    }, {
+        readonly name: "weth_";
+        readonly type: "address";
+    }, {
+        readonly name: "universalRouter_";
+        readonly type: "address";
+    }, {
+        readonly name: "permit2_";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "factory";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "weth";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "universalRouter";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "permit2";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "receiveTokens";
+    readonly inputs: readonly [{
+        readonly name: "deploymentConfig";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenConfig";
+            readonly type: "tuple";
+            readonly components: readonly [{
+                readonly name: "tokenAdmin";
+                readonly type: "address";
+            }, {
+                readonly name: "name";
+                readonly type: "string";
+            }, {
+                readonly name: "symbol";
+                readonly type: "string";
+            }, {
+                readonly name: "salt";
+                readonly type: "bytes32";
+            }, {
+                readonly name: "image";
+                readonly type: "string";
+            }, {
+                readonly name: "metadata";
+                readonly type: "string";
+            }, {
+                readonly name: "context";
+                readonly type: "string";
+            }, {
+                readonly name: "originatingChainId";
+                readonly type: "uint256";
+            }];
+        }, {
+            readonly name: "poolConfig";
+            readonly type: "tuple";
+            readonly components: readonly [{
+                readonly name: "hook";
+                readonly type: "address";
+            }, {
+                readonly name: "pairedToken";
+                readonly type: "address";
+            }, {
+                readonly name: "tickIfToken0IsLiquid";
+                readonly type: "int24";
+            }, {
+                readonly name: "tickSpacing";
+                readonly type: "int24";
+            }, {
+                readonly name: "poolData";
+                readonly type: "bytes";
+            }];
+        }, {
+            readonly name: "lockerConfig";
+            readonly type: "tuple";
+            readonly components: readonly [{
+                readonly name: "locker";
+                readonly type: "address";
+            }, {
+                readonly name: "rewardAdmins";
+                readonly type: "address[]";
+            }, {
+                readonly name: "rewardRecipients";
+                readonly type: "address[]";
+            }, {
+                readonly name: "rewardBps";
+                readonly type: "uint16[]";
+            }, {
+                readonly name: "tickLower";
+                readonly type: "int24[]";
+            }, {
+                readonly name: "tickUpper";
+                readonly type: "int24[]";
+            }, {
+                readonly name: "positionBps";
+                readonly type: "uint16[]";
+            }, {
+                readonly name: "lockerData";
+                readonly type: "bytes";
+            }];
+        }, {
+            readonly name: "mevModuleConfig";
+            readonly type: "tuple";
+            readonly components: readonly [{
+                readonly name: "mevModule";
+                readonly type: "address";
+            }, {
+                readonly name: "mevModuleData";
+                readonly type: "bytes";
+            }];
+        }, {
+            readonly name: "extensionConfigs";
+            readonly type: "tuple[]";
+            readonly components: readonly [{
+                readonly name: "extension";
+                readonly type: "address";
+            }, {
+                readonly name: "msgValue";
+                readonly type: "uint256";
+            }, {
+                readonly name: "extensionBps";
+                readonly type: "uint16";
+            }, {
+                readonly name: "extensionData";
+                readonly type: "bytes";
+            }];
+        }];
+    }, {
+        readonly name: "tokenPoolKey";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "currency0";
+            readonly type: "address";
+        }, {
+            readonly name: "currency1";
+            readonly type: "address";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint24";
+        }, {
+            readonly name: "tickSpacing";
+            readonly type: "int24";
+        }, {
+            readonly name: "hooks";
+            readonly type: "address";
+        }];
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "extensionSupply";
+        readonly type: "uint256";
+    }, {
+        readonly name: "extensionIndex";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "function";
+    readonly name: "supportsInterface";
+    readonly inputs: readonly [{
+        readonly name: "interfaceId";
+        readonly type: "bytes4";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "pure";
+}, {
+    readonly type: "event";
+    readonly name: "EthDevBuy";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "user";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "ethAmount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "tokenAmount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "error";
+    readonly name: "InvalidEthDevBuyPercentage";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidMsgValue";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidPairedTokenPoolKey";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "ReentrancyGuardReentrantCall";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "Unauthorized";
+    readonly inputs: readonly [];
+}];
+
 declare const ERC20Abi: readonly [{
     readonly type: "function";
     readonly name: "name";
@@ -1949,4 +2312,56 @@ interface SniperAuctionConfig {
  */
 declare function encodeSniperAuctionData(config: SniperAuctionConfig): Hex;
 
-export { ADDRESSES, type AirdropInfo, DEFAULTS, DEFAULT_CHAIN, DEFAULT_CHAIN_ID, DEFAULT_RPC_URL, DEFAULT_TRANCHES_USD, type DeployTokenParams, type DeployTokenResult, type DeploymentConfig, type DeploymentInfo, type DevBuyParams, type DynamicFeeConfig, ERC20Abi, EXTERNAL, type ExtensionConfig, FEE, LiquidAirdropV2Abi, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, LiquidMevBlockDelayAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidVaultAbi, type LockerConfig, type MarketCapTranche, type MarketCapTrancheUSD, type MevModuleConfig, POOL_POSITIONS, type PoolConfig, type PoolDynamicConfigVars, type PoolDynamicFeeVars, type PoolKey, type PoolPosition, type PositionArrays, type PositionConfig, type SniperAuctionConfig, type SniperAuctionFeeConfig, type SniperAuctionState, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, createDefaultPositions, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD };
+/** Provenance — who launched the token and from where. */
+interface LiquidContext {
+    /** System that deployed the token (e.g. "SDK", "Rainbow Wallet", "Liquid CLI") */
+    interface: string;
+    /** Social platform origin (e.g. "Farcaster", "Twitter") */
+    platform?: string;
+    /** Social post/message ID that triggered the deploy */
+    messageId?: string;
+    /** User ID on the originating platform */
+    id?: string;
+}
+/** Social media link for token metadata. */
+interface SocialMediaUrl {
+    platform: string;
+    url: string;
+}
+/** Token info for aggregators and explorers. */
+interface LiquidMetadata {
+    /** Token/project description */
+    description?: string;
+    /** Social media links */
+    socialMediaUrls?: SocialMediaUrl[];
+    /** Audit report URLs */
+    auditUrls?: string[];
+}
+/**
+ * Build a JSON string for the on-chain `context` field.
+ *
+ * @example
+ * buildContext({ interface: "My App", platform: "Farcaster" })
+ * // '{"interface":"My App","platform":"Farcaster"}'
+ */
+declare function buildContext(input?: Partial<LiquidContext>): string;
+/**
+ * Build a JSON string for the on-chain `metadata` field.
+ *
+ * @example
+ * buildMetadata({ description: "A cool token" })
+ * // '{"description":"A cool token"}'
+ */
+declare function buildMetadata(input?: Partial<LiquidMetadata>): string;
+/**
+ * Parse a context JSON string back into a typed object.
+ * Returns `null` if the string is empty or not valid JSON.
+ */
+declare function parseContext(contextString: string): LiquidContext | null;
+/**
+ * Parse a metadata JSON string back into a typed object.
+ * Returns `null` if the string is empty or not valid JSON.
+ */
+declare function parseMetadata(metadataString: string): LiquidMetadata | null;
+
+export { ADDRESSES, type AirdropInfo, DEFAULTS, DEFAULT_CHAIN, DEFAULT_CHAIN_ID, DEFAULT_RPC_URL, DEFAULT_TRANCHES_USD, type DeployTokenParams, type DeployTokenResult, type DeploymentConfig, type DeploymentInfo, type DevBuyParams, type DynamicFeeConfig, ERC20Abi, EXTERNAL, type ExtensionConfig, FEE, type GetTokensOptions, LiquidAirdropV2Abi, type LiquidContext, LiquidFactoryAbi, LiquidFeeLockerAbi, LiquidHookDynamicFeeV2Abi, LiquidLpLockerAbi, type LiquidMetadata, LiquidMevBlockDelayAbi, LiquidPoolExtensionAllowlistAbi, LiquidSDK, type LiquidSDKConfig, LiquidSniperAuctionV2Abi, LiquidSniperUtilV2Abi, LiquidTokenAbi, LiquidUniv4EthDevBuyAbi, LiquidVaultAbi, type LockerConfig, type MarketCapTranche, type MarketCapTrancheUSD, type MevModuleConfig, POOL_POSITIONS, type PoolConfig, type PoolDynamicConfigVars, type PoolDynamicFeeVars, type PoolKey, type PoolPosition, type PositionArrays, type PositionConfig, type SniperAuctionConfig, type SniperAuctionFeeConfig, type SniperAuctionState, type SocialMediaUrl, TOKEN, type TokenConfig, type TokenCreatedEvent, type TokenRewardInfo, type VaultAllocation, buildContext, buildMetadata, createDefaultPositions, createPositions, createPositionsUSD, describePositions, encodeDynamicFeePoolData, encodeSniperAuctionData, encodeStaticFeePoolData, getTickFromMarketCapETH, getTickFromMarketCapStable, getTickFromMarketCapUSD, marketCapFromTickETH, marketCapFromTickUSD, parseContext, parseMetadata };