@terkoizmy/intent-sdk 1.0.0

package/dist/parser/validators/schema.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/**
+ * Zod schemas for validation
+ */
+const IntentParametersSchema = z
+    .object({
+    inputToken: z.string().optional(),
+    inputTokenAddress: z.string().optional(),
+    inputAmount: z.string().optional(),
+    outputToken: z.string().optional(),
+    outputTokenAddress: z.string().optional(),
+    minOutputAmount: z.string().optional(),
+    recipient: z.string().optional(),
+    riskLevel: z.enum(["low", "medium", "high"]).optional(),
+    diversificationRequired: z.boolean().optional(),
+    preferredProtocols: z.array(z.string()).optional(),
+    targetAPY: z.string().optional(),
+    collection: z.string().optional(),
+    collectionAddress: z.string().optional(),
+    traits: z.record(z.string(), z.string()).optional(),
+    maxPrice: z.string().optional(),
+})
+    .passthrough();
+const IntentConstraintsSchema = z
+    .object({
+    deadline: z.number(),
+    maxSlippage: z.number().optional(),
+    maxGasCost: z.string().optional(),
+    minProtocols: z.number().optional(),
+    maxExposurePerProtocol: z.number().optional(),
+    preferredDEXs: z.array(z.string()).optional(),
+    preferredMarketplaces: z.array(z.string()).optional(),
+})
+    .passthrough();
+const StructuredIntentSchema = z.object({
+    intentType: z.enum([
+        "swap",
+        "yield_strategy",
+        "nft_purchase",
+        "send",
+        "bridge",
+        "claim",
+        "unknown",
+    ]),
+    parameters: IntentParametersSchema,
+    constraints: IntentConstraintsSchema,
+    metadata: z.object({
+        originalText: z.string(),
+        confidence: z.number().min(0).max(1),
+        parsedAt: z.number(),
+        warnings: z.array(z.string()).optional(),
+    }),
+});
+/**
+ * Validate structured intent
+ *
+ * INPUT: StructuredIntent
+ * OUTPUT: { success: boolean, error?: string }
+ *
+ * TODO: Implement validation logic
+ */
+export function validateIntent(intent) {
+    try {
+        StructuredIntentSchema.parse(intent);
+        return { success: true };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            return {
+                success: false,
+                // @ts-ignore
+                error: error.errors.map((e) => e.message).join(", "),
+            };
+        }
+        return {
+            success: false,
+            error: "Unknown validation error",
+        };
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/parser/validators/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/parser/validators/schema.ts"],"names":[],"mappings":"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"}

package/dist/sdk-factory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * SDK Factory — Convenience function to create Parser + Solver
+ *
+ * Usage:
+ *   import { createIntentSDK } from "@terkoizmy/intent-sdk";
+ *
+ *   const { parser, solver } = createIntentSDK({
+ *       agent: {
+ *           privateKey: "0x...",
+ *           mode: "simulate",
+ *           supportedChains: [1, 42161],
+ *           supportedTokens: ["USDC"],
+ *       },
+ *       contractAddress: "0x...",
+ *   });
+ */
+import { IntentParser } from "./parser";
+import { IntentSolver } from "./solver";
+import type { LiquidityAgentConfig } from "./solver/agent/agent-config";
+import type { ParserConfig } from "./parser";
+export interface SDKConfig {
+    /** Parser configuration (optional — sensible defaults used) */
+    parser?: ParserConfig;
+    /** Solver configuration (required for solver functionality) */
+    solver: LiquidityAgentConfig;
+}
+/**
+ * Create a fully configured Intent SDK with both parser and solver.
+ *
+ * @param config - SDK configuration
+ * @returns Object containing `parser` and `solver` instances
+ *
+ * @example
+ * ```typescript
+ * const { parser, solver } = createIntentSDK({
+ *     solver: {
+ *         agent: {
+ *             privateKey: process.env.SOLVER_PRIVATE_KEY!,
+ *             mode: "live",
+ *             supportedChains: [1, 42161],
+ *             supportedTokens: ["USDC"],
+ *         },
+ *         contractAddress: process.env.SETTLEMENT_CONTRACT!,
+ *     },
+ * });
+ *
+ * await solver.initialize();
+ * const parsed = parser.parse("Bridge 100 USDC from Ethereum to Arbitrum");
+ * ```
+ */
+export declare function createIntentSDK(config: SDKConfig): {
+    parser: IntentParser;
+    solver: IntentSolver;
+};
+//# sourceMappingURL=sdk-factory.d.ts.map

package/dist/sdk-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-factory.d.ts","sourceRoot":"","sources":["../src/sdk-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,SAAS;IACtB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB,+DAA+D;IAC/D,MAAM,EAAE,oBAAoB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS;;;EAKhD"}

package/dist/sdk-factory.js

@@ -0,0 +1,49 @@
+/**
+ * SDK Factory — Convenience function to create Parser + Solver
+ *
+ * Usage:
+ *   import { createIntentSDK } from "@terkoizmy/intent-sdk";
+ *
+ *   const { parser, solver } = createIntentSDK({
+ *       agent: {
+ *           privateKey: "0x...",
+ *           mode: "simulate",
+ *           supportedChains: [1, 42161],
+ *           supportedTokens: ["USDC"],
+ *       },
+ *       contractAddress: "0x...",
+ *   });
+ */
+import { IntentParser } from "./parser";
+import { IntentSolver } from "./solver";
+/**
+ * Create a fully configured Intent SDK with both parser and solver.
+ *
+ * @param config - SDK configuration
+ * @returns Object containing `parser` and `solver` instances
+ *
+ * @example
+ * ```typescript
+ * const { parser, solver } = createIntentSDK({
+ *     solver: {
+ *         agent: {
+ *             privateKey: process.env.SOLVER_PRIVATE_KEY!,
+ *             mode: "live",
+ *             supportedChains: [1, 42161],
+ *             supportedTokens: ["USDC"],
+ *         },
+ *         contractAddress: process.env.SETTLEMENT_CONTRACT!,
+ *     },
+ * });
+ *
+ * await solver.initialize();
+ * const parsed = parser.parse("Bridge 100 USDC from Ethereum to Arbitrum");
+ * ```
+ */
+export function createIntentSDK(config) {
+    return {
+        parser: new IntentParser(config.parser),
+        solver: new IntentSolver(config.solver),
+    };
+}
+//# sourceMappingURL=sdk-factory.js.map

package/dist/sdk-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-factory.js","sourceRoot":"","sources":["../src/sdk-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAYxC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC7C,OAAO;QACH,MAAM,EAAE,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC;QACvC,MAAM,EAAE,IAAI,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC;KAC1C,CAAC;AACN,CAAC"}

package/dist/services/token-resolver.d.ts

@@ -0,0 +1,142 @@
+import type { ResolvedToken, TokenResolverConfig } from "../types/token";
+/**
+ * Token Resolver Service
+ *
+ * Resolve token symbol + chain → contract address menggunakan Swing.xyz API.
+ * Includes built-in caching untuk menghindari API call berulang.
+ *
+ * API ENDPOINT: https://platform.swing.xyz/api/v1/tokens?chain={chain}&symbol={symbol}
+ * - Public API, tidak perlu API key
+ * - Support EVM chains (Ethereum, Polygon, Arbitrum, etc.) + Solana
+ * - Response: { symbol, name, address, decimals, price, chain, logo }
+ *
+ * CONTOH PENGGUNAAN:
+ *   const resolver = new TokenResolver({ enabled: true, cacheTTL: 300_000, timeout: 5000 });
+ *   const token = await resolver.resolve("USDC", "polygon");
+ *   // → { symbol: "USDC", address: "0x3c499c...", decimals: 6, chain: "polygon" }
+ *
+ * CACHING:
+ *   - Cache key: "${SYMBOL}:${chain}" (e.g., "USDC:polygon")
+ *   - TTL: configurable, default 5 menit
+ *   - Jika cache hit dan belum expired → return cached, skip API call
+ *
+ * ERROR HANDLING:
+ *   - Jika API down / timeout → return null (parser tetap berfungsi tanpa address)
+ *   - Jika token tidak ditemukan → return null
+ *   - Tidak throw error — selalu graceful
+ */
+export declare class TokenResolver {
+    private config;
+    private cache;
+    private static readonly BASE_URL;
+    /**
+     * Constructor
+     *
+     * INPUT: TokenResolverConfig
+     *   - enabled: boolean (default: true)
+     *   - cacheTTL: number in ms (default: 300_000 = 5 min)
+     *   - timeout: number in ms (default: 5000)
+     *   - customResolver?: (symbol, chain) => Promise<ResolvedToken | null>
+     */
+    constructor(config?: Partial<TokenResolverConfig>);
+    /**
+     * Resolve a token symbol on a specific chain to its contract address
+     *
+     * INPUT:
+     *   - symbol: Token symbol, e.g., "USDC", "ETH", "WBTC"
+     *   - chain: Chain name, e.g., "ethereum", "polygon", "solana"
+     *
+     * OUTPUT:
+     *   - Promise<ResolvedToken | null>
+     *   - Returns null jika: disabled, token not found, API error, timeout
+     *
+     * FLOW:
+     *   1. Jika disabled → return null
+     *   2. Jika customResolver disediakan → gunakan itu
+     *   3. Check cache → jika hit dan belum expired → return cached
+     *   4. Call Swing.xyz API
+     *   5. Parse response → map ke ResolvedToken
+     *   6. Simpan ke cache
+     *   7. Return ResolvedToken
+     *
+     * ERROR: Tidak throw. Jika terjadi error apapun → return null
+     */
+    resolve(symbol: string, chain: string): Promise<ResolvedToken | null>;
+    /**
+     * Resolve multiple tokens in parallel
+     *
+     * INPUT:
+     *   - tokens: Array of { symbol, chain } objects
+     *
+     * OUTPUT:
+     *   - Promise<Map<string, ResolvedToken | null>>
+     *   - Map key = "SYMBOL:chain" (e.g., "USDC:polygon")
+     *
+     * CONTOH:
+     *   const results = await resolver.resolveMany([
+     *     { symbol: "USDC", chain: "ethereum" },
+     *     { symbol: "ETH", chain: "polygon" },
+     *   ]);
+     *   // results.get("USDC:ethereum") → { address: "0xA0b8..." }
+     */
+    resolveMany(tokens: Array<{
+        symbol: string;
+        chain: string;
+    }>): Promise<Map<string, ResolvedToken | null>>;
+    /**
+     * Fetch token data from Swing.xyz API
+     *
+     * INPUT:
+     *   - symbol: Token symbol (e.g., "USDC")
+     *   - chain: Chain name (e.g., "polygon")
+     *
+     * OUTPUT:
+     *   - Promise<ResolvedToken | null>
+     *
+     * API CALL:
+     *   GET https://platform.swing.xyz/api/v1/tokens?chain={chain}&symbol={symbol}
+     *   Headers: { "x-swing-environment": "" }
+     *
+     * RESPONSE SHAPE (array):
+     *   [{ symbol, name, address, decimals, logo, chain, price, ... }]
+     *
+     * MAPPING:
+     *   SwingTokenResponse → ResolvedToken:
+     *   - symbol → symbol
+     *   - address → address
+     *   - decimals → decimals
+     *   - chain → chain
+     *   - name → name
+     *   - price → price
+     *   - logo → logoUrl
+     *
+     * ERROR HANDLING:
+     *   - Wrap in try/catch
+     *   - Use AbortController for timeout
+     *   - Return null on any error
+     */
+    private fetchFromSwing;
+    /**
+     * Generate cache key dari symbol dan chain
+     *
+     * INPUT: symbol ("USDC"), chain ("polygon")
+     * OUTPUT: "USDC:polygon" (symbol uppercase, chain lowercase)
+     */
+    private getCacheKey;
+    /**
+     * Get dari cache jika ada dan belum expired
+     *
+     * INPUT: Cache key (e.g., "USDC:polygon")
+     * OUTPUT: ResolvedToken | null
+     *
+     * LOGIC:
+     *   1. Check apakah key ada di Map
+     *   2. Check apakah (now - cachedAt) < cacheTTL
+     *   3. Jika expired → delete entry, return null
+     *   4. Jika valid → return token
+     */
+    private getFromCache;
+    private setCache;
+    clearCache(): void;
+}
+//# sourceMappingURL=token-resolver.d.ts.map

package/dist/services/token-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-resolver.d.ts","sourceRoot":"","sources":["../../src/services/token-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,aAAa,EACb,mBAAmB,EAGtB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,KAAK,CAA+B;IAE5C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CACe;IAE/C;;;;;;;;OAQG;gBACS,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM;IAYrD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA0B3E;;;;;;;;;;;;;;;;OAgBG;IACG,WAAW,CACb,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GACjD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC,CAAC;IAqB7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;YACW,cAAc;IAoD5B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,QAAQ;IAahB,UAAU,IAAI,IAAI;CAGrB"}

package/dist/services/token-resolver.js

@@ -0,0 +1,254 @@
+/**
+ * Token Resolver Service
+ *
+ * Resolve token symbol + chain → contract address menggunakan Swing.xyz API.
+ * Includes built-in caching untuk menghindari API call berulang.
+ *
+ * API ENDPOINT: https://platform.swing.xyz/api/v1/tokens?chain={chain}&symbol={symbol}
+ * - Public API, tidak perlu API key
+ * - Support EVM chains (Ethereum, Polygon, Arbitrum, etc.) + Solana
+ * - Response: { symbol, name, address, decimals, price, chain, logo }
+ *
+ * CONTOH PENGGUNAAN:
+ *   const resolver = new TokenResolver({ enabled: true, cacheTTL: 300_000, timeout: 5000 });
+ *   const token = await resolver.resolve("USDC", "polygon");
+ *   // → { symbol: "USDC", address: "0x3c499c...", decimals: 6, chain: "polygon" }
+ *
+ * CACHING:
+ *   - Cache key: "${SYMBOL}:${chain}" (e.g., "USDC:polygon")
+ *   - TTL: configurable, default 5 menit
+ *   - Jika cache hit dan belum expired → return cached, skip API call
+ *
+ * ERROR HANDLING:
+ *   - Jika API down / timeout → return null (parser tetap berfungsi tanpa address)
+ *   - Jika token tidak ditemukan → return null
+ *   - Tidak throw error — selalu graceful
+ */
+export class TokenResolver {
+    config;
+    cache;
+    static BASE_URL = "https://platform.swing.xyz/api/v1/tokens";
+    /**
+     * Constructor
+     *
+     * INPUT: TokenResolverConfig
+     *   - enabled: boolean (default: true)
+     *   - cacheTTL: number in ms (default: 300_000 = 5 min)
+     *   - timeout: number in ms (default: 5000)
+     *   - customResolver?: (symbol, chain) => Promise<ResolvedToken | null>
+     */
+    constructor(config = {}) {
+        this.config = {
+            enabled: config.enabled ?? true,
+            cacheTTL: config.cacheTTL ?? 300_000,
+            timeout: config.timeout ?? 5000,
+            maxCacheSize: config.maxCacheSize ?? 1000,
+            customResolver: config.customResolver,
+        };
+        this.cache = new Map();
+    }
+    /**
+     * Resolve a token symbol on a specific chain to its contract address
+     *
+     * INPUT:
+     *   - symbol: Token symbol, e.g., "USDC", "ETH", "WBTC"
+     *   - chain: Chain name, e.g., "ethereum", "polygon", "solana"
+     *
+     * OUTPUT:
+     *   - Promise<ResolvedToken | null>
+     *   - Returns null jika: disabled, token not found, API error, timeout
+     *
+     * FLOW:
+     *   1. Jika disabled → return null
+     *   2. Jika customResolver disediakan → gunakan itu
+     *   3. Check cache → jika hit dan belum expired → return cached
+     *   4. Call Swing.xyz API
+     *   5. Parse response → map ke ResolvedToken
+     *   6. Simpan ke cache
+     *   7. Return ResolvedToken
+     *
+     * ERROR: Tidak throw. Jika terjadi error apapun → return null
+     */
+    async resolve(symbol, chain) {
+        // Step 1: Early return jika disabled
+        if (!this.config.enabled)
+            return null;
+        // Step 2: Jika customResolver disediakan, gunakan itu
+        if (this.config.customResolver) {
+            return this.config.customResolver(symbol, chain);
+        }
+        // Step 3: Check cache
+        const cacheKey = this.getCacheKey(symbol, chain);
+        const cached = this.getFromCache(cacheKey);
+        if (cached)
+            return cached;
+        // Step 4: Call Swing.xyz API via fetchFromSwing()
+        const resolved = await this.fetchFromSwing(symbol, chain);
+        // Step 5: Cache result jika berhasil
+        if (resolved) {
+            this.setCache(cacheKey, resolved);
+        }
+        // Step 6: Return result
+        return resolved;
+    }
+    /**
+     * Resolve multiple tokens in parallel
+     *
+     * INPUT:
+     *   - tokens: Array of { symbol, chain } objects
+     *
+     * OUTPUT:
+     *   - Promise<Map<string, ResolvedToken | null>>
+     *   - Map key = "SYMBOL:chain" (e.g., "USDC:polygon")
+     *
+     * CONTOH:
+     *   const results = await resolver.resolveMany([
+     *     { symbol: "USDC", chain: "ethereum" },
+     *     { symbol: "ETH", chain: "polygon" },
+     *   ]);
+     *   // results.get("USDC:ethereum") → { address: "0xA0b8..." }
+     */
+    async resolveMany(tokens) {
+        // Step 1: Map each token ke Promise<[key, ResolvedToken | null]>
+        const promises = tokens.map(async ({ symbol, chain }) => {
+            const key = this.getCacheKey(symbol, chain);
+            const resolved = await this.resolve(symbol, chain);
+            return [key, resolved];
+        });
+        // Step 2: Promise.allSettled() untuk parallel execution
+        const results = await Promise.allSettled(promises);
+        // Step 3: Build result map
+        const resultMap = new Map();
+        for (const result of results) {
+            if (result.status === "fulfilled") {
+                resultMap.set(result.value[0], result.value[1]);
+            }
+        }
+        return resultMap;
+    }
+    /**
+     * Fetch token data from Swing.xyz API
+     *
+     * INPUT:
+     *   - symbol: Token symbol (e.g., "USDC")
+     *   - chain: Chain name (e.g., "polygon")
+     *
+     * OUTPUT:
+     *   - Promise<ResolvedToken | null>
+     *
+     * API CALL:
+     *   GET https://platform.swing.xyz/api/v1/tokens?chain={chain}&symbol={symbol}
+     *   Headers: { "x-swing-environment": "" }
+     *
+     * RESPONSE SHAPE (array):
+     *   [{ symbol, name, address, decimals, logo, chain, price, ... }]
+     *
+     * MAPPING:
+     *   SwingTokenResponse → ResolvedToken:
+     *   - symbol → symbol
+     *   - address → address
+     *   - decimals → decimals
+     *   - chain → chain
+     *   - name → name
+     *   - price → price
+     *   - logo → logoUrl
+     *
+     * ERROR HANDLING:
+     *   - Wrap in try/catch
+     *   - Use AbortController for timeout
+     *   - Return null on any error
+     */
+    async fetchFromSwing(symbol, chain) {
+        // Step 1: Build URL
+        const url = `${TokenResolver.BASE_URL}?chain=${encodeURIComponent(chain)}&symbol=${encodeURIComponent(symbol)}`;
+        // Step 2: Setup AbortController for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            // Step 3: Fetch
+            const response = await fetch(url, {
+                headers: { "x-swing-environment": "" },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            // Step 4: Parse response
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            // Handle Swing API response format wrapped in "value" if present (some APIs wrap list in value object)
+            // Based on user provided curl output: {"value": [...], "Count": 1} is possible?
+            // Wait, previous curl output showed:
+            // { "value": [ ... ] }
+            // So we need to access data.value if it exists.
+            const tokens = Array.isArray(data) ? data : (data.value || []);
+            // Step 5: Validasi — API return array, ambil pertama
+            if (!tokens || tokens.length === 0)
+                return null;
+            const token = tokens[0];
+            // Step 6: Map ke ResolvedToken
+            return {
+                symbol: token.symbol,
+                address: token.address,
+                decimals: token.decimals,
+                chain: token.chain,
+                name: token.name,
+                price: token.price,
+                logoUrl: token.logo,
+            };
+        }
+        catch (error) {
+            return null;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Generate cache key dari symbol dan chain
+     *
+     * INPUT: symbol ("USDC"), chain ("polygon")
+     * OUTPUT: "USDC:polygon" (symbol uppercase, chain lowercase)
+     */
+    getCacheKey(symbol, chain) {
+        return `${symbol.toUpperCase()}:${chain.toLowerCase()}`;
+    }
+    /**
+     * Get dari cache jika ada dan belum expired
+     *
+     * INPUT: Cache key (e.g., "USDC:polygon")
+     * OUTPUT: ResolvedToken | null
+     *
+     * LOGIC:
+     *   1. Check apakah key ada di Map
+     *   2. Check apakah (now - cachedAt) < cacheTTL
+     *   3. Jika expired → delete entry, return null
+     *   4. Jika valid → return token
+     */
+    getFromCache(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        const isExpired = Date.now() - entry.cachedAt > this.config.cacheTTL;
+        if (isExpired) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.token;
+    }
+    setCache(key, token) {
+        // Evict oldest entry if cache is full
+        if (this.cache.size >= this.config.maxCacheSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey)
+                this.cache.delete(oldestKey);
+        }
+        this.cache.set(key, {
+            token,
+            cachedAt: Date.now(),
+        });
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=token-resolver.js.map

package/dist/services/token-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-resolver.js","sourceRoot":"","sources":["../../src/services/token-resolver.ts"],"names":[],"mappings":"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"}

package/dist/shared/chain-registry/chain-names.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Chain Names — Human-Readable Display Names
+ *
+ * Static lookup map for well-known EVM chain IDs.
+ * Zero external dependencies — used across error messages and logging.
+ *
+ * Stage 3 — Phase G (Production Hardening)
+ */
+/**
+ * Well-known EVM chain ID → human-readable name.
+ */
+export declare const CHAIN_NAMES: Record<number, string>;
+/**
+ * Get a human-readable display name for a chain ID.
+ *
+ * Returns `"Ethereum (1)"` for known chains or `"Unknown Chain (99999)"` for unknown.
+ *
+ * @param chainId - Numeric EVM chain ID
+ * @returns Display string like `"Arbitrum One (42161)"`
+ */
+export declare function getChainDisplayName(chainId: number): string;
+//# sourceMappingURL=chain-names.d.ts.map

package/dist/shared/chain-registry/chain-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-names.d.ts","sourceRoot":"","sources":["../../../src/shared/chain-registry/chain-names.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsB9C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM3D"}