liquid-sdk 1.2.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;
@@ -258,6 +269,35 @@ declare class LiquidSDK {
      * @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: {
@@ -335,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. */
@@ -2270,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, 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, 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 };

package/dist/index.d.ts

@@ -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;
@@ -258,6 +269,35 @@ declare class LiquidSDK {
      * @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: {
@@ -335,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. */
@@ -2270,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, 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, 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 };

package/dist/index.js

@@ -44,6 +44,8 @@ __export(index_exports, {
   LiquidVaultAbi: () => LiquidVaultAbi,
   POOL_POSITIONS: () => POOL_POSITIONS,
   TOKEN: () => TOKEN,
+  buildContext: () => buildContext,
+  buildMetadata: () => buildMetadata,
   createDefaultPositions: () => createDefaultPositions,
   createPositions: () => createPositions,
   createPositionsUSD: () => createPositionsUSD,
@@ -55,7 +57,9 @@ __export(index_exports, {
   getTickFromMarketCapStable: () => getTickFromMarketCapStable,
   getTickFromMarketCapUSD: () => getTickFromMarketCapUSD,
   marketCapFromTickETH: () => marketCapFromTickETH,
-  marketCapFromTickUSD: () => marketCapFromTickUSD
+  marketCapFromTickUSD: () => marketCapFromTickUSD,
+  parseContext: () => parseContext,
+  parseMetadata: () => parseMetadata
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -147,6 +151,8 @@ var POOL_POSITIONS = {
 };
 var DEFAULTS = {
   HOOK: ADDRESSES.HOOK_STATIC_FEE_V2,
+  /** LP Locker with fee conversion (converts fees to ETH before distributing) */
+  LOCKER: ADDRESSES.LP_LOCKER_FEE_CONVERSION,
   TICK_SPACING: 200,
   TICK_IF_TOKEN0_IS_LIQUID: -230400,
   /** Static fee on buys (ETH → token): 1% (100 bps). Fees collected in ETH. */
@@ -255,6 +261,68 @@ function encodeSniperAuctionData(config) {
   ]);
 }
 
+// src/utils/context.ts
+function buildContext(input) {
+  const ctx = {
+    interface: input?.interface ?? "SDK"
+  };
+  if (input?.platform !== void 0) ctx.platform = input.platform;
+  if (input?.messageId !== void 0) ctx.messageId = input.messageId;
+  if (input?.id !== void 0) ctx.id = input.id;
+  return JSON.stringify(ctx);
+}
+function buildMetadata(input) {
+  if (!input) return "{}";
+  const meta = {};
+  if (input.description !== void 0) meta.description = input.description;
+  if (input.socialMediaUrls !== void 0 && input.socialMediaUrls.length > 0) {
+    meta.socialMediaUrls = input.socialMediaUrls;
+  }
+  if (input.auditUrls !== void 0 && input.auditUrls.length > 0) {
+    meta.auditUrls = input.auditUrls;
+  }
+  return JSON.stringify(meta);
+}
+function parseContext(contextString) {
+  if (!contextString || contextString === "") return null;
+  try {
+    const parsed = JSON.parse(contextString);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return {
+      interface: typeof parsed.interface === "string" ? parsed.interface : "unknown",
+      ...typeof parsed.platform === "string" && { platform: parsed.platform },
+      ...typeof parsed.messageId === "string" && { messageId: parsed.messageId },
+      ...typeof parsed.id === "string" && { id: parsed.id }
+    };
+  } catch {
+    return null;
+  }
+}
+function parseMetadata(metadataString) {
+  if (!metadataString || metadataString === "") return null;
+  try {
+    const parsed = JSON.parse(metadataString);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const result = {};
+    if (typeof parsed.description === "string") {
+      result.description = parsed.description;
+    }
+    if (Array.isArray(parsed.socialMediaUrls)) {
+      result.socialMediaUrls = parsed.socialMediaUrls.filter(
+        (item) => typeof item === "object" && item !== null && typeof item.platform === "string" && typeof item.url === "string"
+      );
+    }
+    if (Array.isArray(parsed.auditUrls)) {
+      result.auditUrls = parsed.auditUrls.filter(
+        (item) => typeof item === "string"
+      );
+    }
+    return result;
+  } catch {
+    return null;
+  }
+}
+
 // src/abis/LiquidFactory.ts
 var LiquidFactoryAbi = [
   {
@@ -1154,7 +1222,7 @@ var LiquidSDK = class {
         ),
         image: params.image ?? "",
         metadata: params.metadata ?? "",
-        context: params.context ?? "",
+        context: params.context ?? buildContext(),
         originatingChainId: BigInt(DEFAULT_CHAIN_ID)
       },
       poolConfig: {
@@ -1168,7 +1236,7 @@ var LiquidSDK = class {
         )
       },
       lockerConfig: {
-        locker: params.locker ?? ADDRESSES.LP_LOCKER,
+        locker: params.locker ?? DEFAULTS.LOCKER,
         rewardAdmins: params.rewardAdmins ?? [account],
         rewardRecipients: params.rewardRecipients ?? [account],
         rewardBps: params.rewardBps ?? [1e4],
@@ -1558,7 +1626,7 @@ var LiquidSDK = class {
   }
   // ── LP Locker ───────────────────────────────────────────────────────
   async getTokenRewards(tokenAddress, lockerAddress) {
-    const locker = lockerAddress ?? ADDRESSES.LP_LOCKER;
+    const locker = lockerAddress ?? DEFAULTS.LOCKER;
     const result = await this.publicClient.readContract({
       address: locker,
       abi: LiquidLpLockerAbi,
@@ -1580,7 +1648,7 @@ var LiquidSDK = class {
     if (!this.walletClient?.account) {
       throw new Error("walletClient with account required for collectRewards");
     }
-    const locker = lockerAddress ?? ADDRESSES.LP_LOCKER;
+    const locker = lockerAddress ?? DEFAULTS.LOCKER;
     return await this.walletClient.writeContract({
       address: locker,
       abi: LiquidLpLockerAbi,
@@ -1596,7 +1664,7 @@ var LiquidSDK = class {
         "walletClient with account required for collectRewardsWithoutUnlock"
       );
     }
-    const locker = lockerAddress ?? ADDRESSES.LP_LOCKER;
+    const locker = lockerAddress ?? DEFAULTS.LOCKER;
     return await this.walletClient.writeContract({
       address: locker,
       abi: LiquidLpLockerAbi,
@@ -1612,7 +1680,7 @@ var LiquidSDK = class {
         "walletClient with account required for updateRewardRecipient"
       );
     }
-    const locker = lockerAddress ?? ADDRESSES.LP_LOCKER;
+    const locker = lockerAddress ?? DEFAULTS.LOCKER;
     return await this.walletClient.writeContract({
       address: locker,
       abi: LiquidLpLockerAbi,
@@ -1688,15 +1756,37 @@ var LiquidSDK = class {
    * @param toBlock - Ending block to search to (defaults to 'latest')
    */
   async getDeployedTokens(deployer, fromBlock, toBlock) {
+    return this.getTokens({ deployer, fromBlock, toBlock });
+  }
+  /**
+   * 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 });
+   */
+  async getTokens(options) {
     const logs = await this.publicClient.getLogs({
       address: ADDRESSES.FACTORY,
       event: (0, import_viem2.parseAbiItem)(
         "event TokenCreated(address msgSender, address indexed tokenAddress, address indexed tokenAdmin, string tokenImage, string tokenName, string tokenSymbol, string tokenMetadata, string tokenContext, int24 startingTick, address poolHook, bytes32 poolId, address pairedToken, address locker, address mevModule, uint256 extensionsSupply, address[] extensions)"
       ),
-      fromBlock: fromBlock ?? 0n,
-      toBlock: toBlock ?? "latest"
+      fromBlock: options?.fromBlock ?? 0n,
+      toBlock: options?.toBlock ?? "latest"
     });
+    const deployer = options?.deployer;
     return logs.filter((log) => {
+      if (!deployer) return true;
       const sender = log.args.msgSender;
       return sender && (0, import_viem2.getAddress)(sender) === (0, import_viem2.getAddress)(deployer);
     }).map((log) => {
@@ -1717,10 +1807,54 @@ var LiquidSDK = class {
         locker: args.locker,
         mevModule: args.mevModule,
         extensionsSupply: args.extensionsSupply,
-        extensions: args.extensions
+        extensions: args.extensions,
+        blockNumber: log.blockNumber
       };
     });
   }
+  /**
+   * 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.
+   */
+  async getTokenEvent(tokenAddress) {
+    const logs = await this.publicClient.getLogs({
+      address: ADDRESSES.FACTORY,
+      event: (0, import_viem2.parseAbiItem)(
+        "event TokenCreated(address msgSender, address indexed tokenAddress, address indexed tokenAdmin, string tokenImage, string tokenName, string tokenSymbol, string tokenMetadata, string tokenContext, int24 startingTick, address poolHook, bytes32 poolId, address pairedToken, address locker, address mevModule, uint256 extensionsSupply, address[] extensions)"
+      ),
+      args: { tokenAddress },
+      fromBlock: 0n,
+      toBlock: "latest"
+    });
+    if (logs.length === 0) return null;
+    const log = logs[0];
+    const args = log.args;
+    return {
+      msgSender: args.msgSender,
+      tokenAddress: args.tokenAddress,
+      tokenAdmin: args.tokenAdmin,
+      tokenImage: args.tokenImage,
+      tokenName: args.tokenName,
+      tokenSymbol: args.tokenSymbol,
+      tokenMetadata: args.tokenMetadata,
+      tokenContext: args.tokenContext,
+      startingTick: args.startingTick,
+      poolHook: args.poolHook,
+      poolId: args.poolId,
+      pairedToken: args.pairedToken,
+      locker: args.locker,
+      mevModule: args.mevModule,
+      extensionsSupply: args.extensionsSupply,
+      extensions: args.extensions,
+      blockNumber: log.blockNumber
+    };
+  }
 };
 
 // src/abis/LiquidUniv4EthDevBuy.ts
@@ -2006,6 +2140,8 @@ function describePositions(positions, ethPriceUSD) {
   LiquidVaultAbi,
   POOL_POSITIONS,
   TOKEN,
+  buildContext,
+  buildMetadata,
   createDefaultPositions,
   createPositions,
   createPositionsUSD,
@@ -2017,6 +2153,8 @@ function describePositions(positions, ethPriceUSD) {
   getTickFromMarketCapStable,
   getTickFromMarketCapUSD,
   marketCapFromTickETH,
-  marketCapFromTickUSD
+  marketCapFromTickUSD,
+  parseContext,
+  parseMetadata
 });
 //# sourceMappingURL=index.js.map