@exagent/agent 0.1.32 → 0.1.33

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Address, Hash, WalletClient } from 'viem';
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
 import { ExagentClient } from '@exagent/sdk';
 
 /** Risk state persisted across restarts */
@@ -339,9 +339,9 @@ declare const AgentConfigSchema: z.ZodObject<{
     }>>;
     allowedTokens: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
+    agentId: string | number;
     name: string;
     network: "mainnet";
-    agentId: string | number;
     llm: {
         provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
         temperature: number;
@@ -388,8 +388,8 @@ declare const AgentConfigSchema: z.ZodObject<{
     } | undefined;
     allowedTokens?: string[] | undefined;
 }, {
-    name: string;
     agentId: string | number;
+    name: string;
     llm: {
         provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
         model?: string | undefined;
@@ -1426,30 +1426,101 @@ declare class RiskManager {
     private calculateLiquidationProximity;
 }
 
+/**
+ * TokenResolver — bulletproof token metadata resolution with 3-tier fallback.
+ *
+ * Resolution chain:
+ *   1. Hardcoded map (39 whitelisted tokens — instant)
+ *   2. Multicall3 batch on-chain (decimals + symbol in 1 RPC call)
+ *   3. Blockscout API (free, near-universal coverage for Base tokens)
+ *
+ * If ALL tiers fail, the token is marked "unresolvable" and skipped from
+ * portfolio calculations. This is better than silently defaulting to 18
+ * decimals, which causes 10^9–10^12 errors for tokens with 6/8/9 decimals.
+ *
+ * Resolved metadata is persisted to FileStore and never re-fetched (ERC-20
+ * decimals are immutable by convention).
+ */
+declare class TokenResolver {
+    private client;
+    private store;
+    private cache;
+    private unresolvable;
+    constructor(client: PublicClient, store?: StrategyStore);
+    /**
+     * Get decimals for a token (synchronous).
+     * Returns undefined if the token has never been resolved and is not hardcoded.
+     * Call resolve() first for unknown tokens.
+     */
+    getDecimals(address: string): number | undefined;
+    /**
+     * Get symbol for a token (synchronous).
+     */
+    getSymbol(address: string): string | undefined;
+    /**
+     * Set symbol for a token (used when DexScreener returns symbol data).
+     */
+    setSymbol(address: string, symbol: string): void;
+    /**
+     * Check if a token has been marked as unresolvable by all tiers.
+     */
+    isUnresolvable(address: string): boolean;
+    /**
+     * Batch-resolve metadata for a list of token addresses.
+     *
+     * Skips already-resolved tokens. For unknown tokens:
+     * 1. Multicall3 on-chain batch (decimals + symbol)
+     * 2. Blockscout API for any multicall failures
+     * 3. Mark remaining as unresolvable
+     */
+    resolve(addresses: string[]): Promise<void>;
+    /**
+     * Tier 2: Batch-fetch decimals + symbol via Multicall3.
+     * Returns addresses that failed (for next tier).
+     */
+    private resolveViaMulticall;
+    /**
+     * Tier 3: Fetch token metadata from Blockscout (Base's block explorer API).
+     * Free, no API key, near-universal coverage for any token indexed by the explorer.
+     * Returns addresses that failed (truly unresolvable).
+     */
+    private resolveViaBlockscout;
+    /**
+     * Persist resolved metadata to FileStore.
+     */
+    private persist;
+    /**
+     * Persist unresolvable token list to FileStore.
+     */
+    private persistUnresolvable;
+}
+
 /**
  * Market Data Service
  * Fetches real prices from CoinGecko and on-chain balances for strategy analysis.
  *
- * Queries real on-chain balances for:
- * - Native ETH (via eth_getBalance)
- * - ERC-20 tokens (via balanceOf)
+ * Uses TokenResolver for bulletproof token metadata resolution:
+ *   1. Hardcoded map (39 whitelisted tokens)
+ *   2. Multicall3 batch on-chain (1 RPC call for N tokens)
+ *   3. Blockscout API (free, near-universal coverage)
  *
- * Fetches real prices from CoinGecko free API.
- * Refuses to return data if prices are stale (>60s old) to prevent
- * agents from making decisions with outdated price information.
+ * Uses Multicall3 for batched balance fetching (1 RPC call for N balanceOf).
  */
 declare class MarketDataService {
     private rpcUrl;
     private client;
+    private resolver;
     /** Cached prices from last fetch */
     private cachedPrices;
     /** Timestamp of last successful price fetch */
     private lastPriceFetchAt;
-    constructor(rpcUrl: string);
     /** Cached volume data */
     private cachedVolume24h;
     /** Cached price change data */
     private cachedPriceChange24h;
+    constructor(rpcUrl: string, store?: StrategyStore);
+    /** Get the underlying TokenResolver for direct access */
+    getResolver(): TokenResolver;
     /**
      * Fetch current market data for the agent
      */
@@ -1464,11 +1535,17 @@ declare class MarketDataService {
      */
     private fetchPrices;
     /**
-     * Fetch real on-chain balances: native ETH + ERC-20 tokens
+     * Fetch real on-chain balances: native ETH + ERC-20 tokens.
+     * Uses Multicall3 to batch all balanceOf calls into a single RPC request.
      */
     private fetchBalances;
     /**
-     * Calculate total portfolio value in USD
+     * Fallback: fetch ERC-20 balances individually (if multicall fails).
+     */
+    private fetchBalancesIndividual;
+    /**
+     * Calculate total portfolio value in USD.
+     * Skips tokens with unresolvable decimals to avoid corrupted calculations.
      */
     private calculatePortfolioValue;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Address, Hash, WalletClient } from 'viem';
+import { Address, Hash, PublicClient, WalletClient } from 'viem';
 import { ExagentClient } from '@exagent/sdk';
 
 /** Risk state persisted across restarts */
@@ -339,9 +339,9 @@ declare const AgentConfigSchema: z.ZodObject<{
     }>>;
     allowedTokens: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
+    agentId: string | number;
     name: string;
     network: "mainnet";
-    agentId: string | number;
     llm: {
         provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
         temperature: number;
@@ -388,8 +388,8 @@ declare const AgentConfigSchema: z.ZodObject<{
     } | undefined;
     allowedTokens?: string[] | undefined;
 }, {
-    name: string;
     agentId: string | number;
+    name: string;
     llm: {
         provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
         model?: string | undefined;
@@ -1426,30 +1426,101 @@ declare class RiskManager {
     private calculateLiquidationProximity;
 }
 
+/**
+ * TokenResolver — bulletproof token metadata resolution with 3-tier fallback.
+ *
+ * Resolution chain:
+ *   1. Hardcoded map (39 whitelisted tokens — instant)
+ *   2. Multicall3 batch on-chain (decimals + symbol in 1 RPC call)
+ *   3. Blockscout API (free, near-universal coverage for Base tokens)
+ *
+ * If ALL tiers fail, the token is marked "unresolvable" and skipped from
+ * portfolio calculations. This is better than silently defaulting to 18
+ * decimals, which causes 10^9–10^12 errors for tokens with 6/8/9 decimals.
+ *
+ * Resolved metadata is persisted to FileStore and never re-fetched (ERC-20
+ * decimals are immutable by convention).
+ */
+declare class TokenResolver {
+    private client;
+    private store;
+    private cache;
+    private unresolvable;
+    constructor(client: PublicClient, store?: StrategyStore);
+    /**
+     * Get decimals for a token (synchronous).
+     * Returns undefined if the token has never been resolved and is not hardcoded.
+     * Call resolve() first for unknown tokens.
+     */
+    getDecimals(address: string): number | undefined;
+    /**
+     * Get symbol for a token (synchronous).
+     */
+    getSymbol(address: string): string | undefined;
+    /**
+     * Set symbol for a token (used when DexScreener returns symbol data).
+     */
+    setSymbol(address: string, symbol: string): void;
+    /**
+     * Check if a token has been marked as unresolvable by all tiers.
+     */
+    isUnresolvable(address: string): boolean;
+    /**
+     * Batch-resolve metadata for a list of token addresses.
+     *
+     * Skips already-resolved tokens. For unknown tokens:
+     * 1. Multicall3 on-chain batch (decimals + symbol)
+     * 2. Blockscout API for any multicall failures
+     * 3. Mark remaining as unresolvable
+     */
+    resolve(addresses: string[]): Promise<void>;
+    /**
+     * Tier 2: Batch-fetch decimals + symbol via Multicall3.
+     * Returns addresses that failed (for next tier).
+     */
+    private resolveViaMulticall;
+    /**
+     * Tier 3: Fetch token metadata from Blockscout (Base's block explorer API).
+     * Free, no API key, near-universal coverage for any token indexed by the explorer.
+     * Returns addresses that failed (truly unresolvable).
+     */
+    private resolveViaBlockscout;
+    /**
+     * Persist resolved metadata to FileStore.
+     */
+    private persist;
+    /**
+     * Persist unresolvable token list to FileStore.
+     */
+    private persistUnresolvable;
+}
+
 /**
  * Market Data Service
  * Fetches real prices from CoinGecko and on-chain balances for strategy analysis.
  *
- * Queries real on-chain balances for:
- * - Native ETH (via eth_getBalance)
- * - ERC-20 tokens (via balanceOf)
+ * Uses TokenResolver for bulletproof token metadata resolution:
+ *   1. Hardcoded map (39 whitelisted tokens)
+ *   2. Multicall3 batch on-chain (1 RPC call for N tokens)
+ *   3. Blockscout API (free, near-universal coverage)
  *
- * Fetches real prices from CoinGecko free API.
- * Refuses to return data if prices are stale (>60s old) to prevent
- * agents from making decisions with outdated price information.
+ * Uses Multicall3 for batched balance fetching (1 RPC call for N balanceOf).
  */
 declare class MarketDataService {
     private rpcUrl;
     private client;
+    private resolver;
     /** Cached prices from last fetch */
     private cachedPrices;
     /** Timestamp of last successful price fetch */
     private lastPriceFetchAt;
-    constructor(rpcUrl: string);
     /** Cached volume data */
     private cachedVolume24h;
     /** Cached price change data */
     private cachedPriceChange24h;
+    constructor(rpcUrl: string, store?: StrategyStore);
+    /** Get the underlying TokenResolver for direct access */
+    getResolver(): TokenResolver;
     /**
      * Fetch current market data for the agent
      */
@@ -1464,11 +1535,17 @@ declare class MarketDataService {
      */
     private fetchPrices;
     /**
-     * Fetch real on-chain balances: native ETH + ERC-20 tokens
+     * Fetch real on-chain balances: native ETH + ERC-20 tokens.
+     * Uses Multicall3 to batch all balanceOf calls into a single RPC request.
      */
     private fetchBalances;
     /**
-     * Calculate total portfolio value in USD
+     * Fallback: fetch ERC-20 balances individually (if multicall fails).
+     */
+    private fetchBalancesIndividual;
+    /**
+     * Calculate total portfolio value in USD.
+     * Skips tokens with unresolvable decimals to avoid corrupted calculations.
      */
     private calculatePortfolioValue;
 }