@yodlpay/tokenlists 1.1.4 → 1.1.6

package/dist/tokens.d.ts

@@ -0,0 +1,118 @@
+import { Address } from 'viem';
+
+/**
+ * Uniswap Token List types
+ * Based on https://github.com/Uniswap/token-lists
+ */
+/**
+ * Supported fiat currencies for stablecoin pegs.
+ */
+type FiatCurrency = 'USD' | 'EUR' | 'CHF' | 'BRL' | 'IDR' | 'GBP' | 'JPY' | 'KRW' | 'SGD' | 'AUD' | 'MXN' | 'CNY' | 'TRY';
+interface UniswapVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/**
+ * Base Uniswap token extensions - allows arbitrary key-value pairs.
+ */
+interface UniswapTokenExtensions {
+    [key: string]: string | number | boolean | null | undefined;
+}
+/**
+ * Yodl-specific token extensions with typed fields.
+ */
+interface TokenExtensions extends UniswapTokenExtensions {
+    coinGeckoId?: string;
+    relayVerified?: boolean;
+    peggedTo?: FiatCurrency;
+    marketCapRank?: number;
+}
+/**
+ * Base Uniswap token info interface.
+ */
+interface UniswapTokenInfo<TExtensions extends UniswapTokenExtensions = UniswapTokenExtensions> {
+    readonly chainId: number;
+    readonly address: string;
+    readonly decimals: number;
+    readonly name: string;
+    readonly symbol: string;
+    readonly logoURI?: string;
+    readonly tags?: string[];
+    readonly extensions?: TExtensions;
+}
+interface UniswapTagDefinition {
+    name: string;
+    description: string;
+}
+/**
+ * Uniswap token list structure.
+ */
+interface UniswapTokenList<TExtensions extends UniswapTokenExtensions = UniswapTokenExtensions> {
+    name: string;
+    timestamp: string;
+    version: UniswapVersion;
+    tokens: UniswapTokenInfo<TExtensions>[];
+    keywords?: string[];
+    tags?: Record<string, UniswapTagDefinition>;
+    logoURI?: string;
+}
+/**
+ * Yodl token list with typed extensions.
+ */
+type YodlTokenList = UniswapTokenList<TokenExtensions>;
+
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validate a token list against the Uniswap token list schema.
+ * @param list - The token list to validate
+ * @returns ValidationResult with valid boolean and array of errors
+ */
+declare function validateTokenList(list: unknown): ValidationResult;
+/**
+ * Validate a token list and throw an error if invalid.
+ * @param list - The token list to validate
+ * @param listName - Name of the list for error messages
+ * @throws Error if validation fails
+ */
+declare function assertValidTokenList(list: unknown, listName?: string): asserts list is UniswapTokenList;
+
+/**
+ * Token info type used throughout the application.
+ * Extends UniswapTokenInfo with:
+ * - viem's Address type for type-safe address handling
+ * - Typed TokenExtensions for Yodl-specific fields
+ */
+interface TokenInfo extends Omit<UniswapTokenInfo<TokenExtensions>, 'address'> {
+    readonly address: Address;
+}
+/**
+ * Featured token overrides - tokens that are manually curated and should not be
+ * updated from on-chain data. These allow intentional duplicates (e.g., native
+ * USDC + bridged USDC on the same chain) in the featured list.
+ *
+ * The `primary` address is returned by default when querying by symbol.
+ * Use `getTokenByAddress` to get a specific token variant.
+ */
+declare const FEATURED_TOKEN_OVERRIDES: Array<{
+    symbol: string;
+    chainId: number;
+    primary: string;
+    addresses: string[];
+}>;
+declare const tokenlist: TokenInfo[];
+declare function getTokenByAddress(tokenAddress: Address, chainId?: number): TokenInfo;
+declare function getFeaturedTokenBySymbol(tokenSymbol: string, chainId?: number): TokenInfo;
+declare function getTokenBySymbol(tokenSymbol: string, chainId?: number): TokenInfo;
+declare function getTokens(chainId?: number): TokenInfo[];
+declare function getNativeWrappedToken(chainId: number): TokenInfo;
+
+export { FEATURED_TOKEN_OVERRIDES, assertValidTokenList, getFeaturedTokenBySymbol, getNativeWrappedToken, getTokenByAddress, getTokenBySymbol, getTokens, tokenlist, validateTokenList };
+export type { FiatCurrency, TokenExtensions, TokenInfo, UniswapTagDefinition, UniswapTokenExtensions, UniswapTokenInfo, UniswapTokenList, UniswapVersion, ValidationError, ValidationResult, YodlTokenList };