@elizaos/plugin-wallet 2.0.0-beta.1 → 2.0.3-beta.5

package/dist/sdk/policy/SpendingPolicy.d.ts

@@ -0,0 +1,105 @@
+/**
+ * SpendingPolicy — Programmable spending guardrails for AI agents.
+ *
+ * Beats PolicyLayer.com to market with:
+ *   - MerchantAllowlist  — allowlist-only merchant enforcement
+ *   - RollingSpendCap    — time-windowed spend limits
+ *   - DraftThenApprove   — human-in-the-loop for large transactions
+ *   - AuditTrail         — immutable local log of every payment attempt
+ *   - FailClosed         — policy errors always reject, never approve
+ *
+ * @module policy/SpendingPolicy
+ */
+/** A payment the agent wants to make. */
+export interface PaymentIntent {
+    /** Merchant contract address or domain (e.g. "0xABC..." or "api.example.com") */
+    merchant: string;
+    /** Amount in the smallest token unit (e.g. USDC micro-cents = 6 decimals). Use number for JS safety in tests; real on-chain code passes BigInt via adapter. */
+    amount: number;
+    /** ISO-8601 timestamp string. Defaults to now if omitted. */
+    timestamp?: string;
+    /** Optional human-readable label */
+    description?: string;
+}
+export type PolicyStatus = "approved" | "rejected" | "draft";
+/** Result returned by SpendingPolicy.check(). */
+export interface PolicyResult {
+    status: PolicyStatus;
+    reason?: string;
+    draftId?: string;
+}
+/** A queued draft transaction awaiting approval. */
+export interface DraftEntry {
+    draftId: string;
+    payment: PaymentIntent;
+    queuedAt: string;
+    approved: boolean;
+    rejected: boolean;
+}
+/** Immutable record written to the audit log. */
+export interface AuditEntry {
+    id: string;
+    timestamp: string;
+    merchant: string;
+    amount: number;
+    status: PolicyStatus;
+    reason?: string;
+    draftId?: string;
+}
+/** Configuration passed to SpendingPolicy constructor. */
+export interface SpendingPolicyConfig {
+    /**
+     * MerchantAllowlist: list of allowed contract addresses or domains.
+     * If provided and non-empty, only these merchants are allowed.
+     * Pass an empty array [] to disable allowlist enforcement (allow all).
+     */
+    merchantAllowlist?: string[];
+    /**
+     * RollingSpendCap: maximum cumulative spend in a rolling time window.
+     * Set to undefined to disable.
+     */
+    rollingCap?: {
+        /** Max amount (same units as PaymentIntent.amount) */
+        maxAmount: number;
+        /** Window size in milliseconds (e.g. 86_400_000 for 24 h) */
+        windowMs: number;
+    };
+    /**
+     * DraftThenApprove: payments above this threshold are placed in draft status
+     * for human (or another agent) approval rather than executed immediately.
+     * Set to undefined to disable.
+     */
+    draftThreshold?: number;
+}
+export declare class SpendingPolicy {
+    private config;
+    private allowlist;
+    private spendWindow;
+    private auditLog;
+    private drafts;
+    constructor(config: SpendingPolicyConfig);
+    /**
+     * FailClosed: wraps the actual check logic so that ANY unhandled error
+     * produces a rejection rather than inadvertently approving a payment.
+     */
+    check(payment: PaymentIntent): Promise<PolicyResult>;
+    /**
+     * Write a payment attempt to the immutable audit log.
+     */
+    log(payment: PaymentIntent, result: PolicyResult): Promise<void>;
+    /** Return a copy of the current merchant allowlist. */
+    getMerchantAllowlist(): string[];
+    /** Add a merchant address/domain to the allowlist at runtime. */
+    addMerchant(address: string): void;
+    /** Return the full, immutable audit log (copy). */
+    getAuditLog(): AuditEntry[];
+    /** Approve a queued draft by its draftId. Returns false if not found. */
+    approveDraft(draftId: string): boolean;
+    /** Reject a queued draft by its draftId. Returns false if not found. */
+    rejectDraft(draftId: string): boolean;
+    /** Return all pending drafts awaiting approval or rejection. */
+    getPendingDrafts(): DraftEntry[];
+    /** Return all drafts. */
+    getAllDrafts(): DraftEntry[];
+    private _check;
+}

package/dist/sdk/policy/UptoBillingPolicy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * UptoBillingPolicy
+ *
+ * Local accounting for x402 "upto" flows where a buyer authorizes a maximum
+ * amount up front and the seller later settles only actual usage.
+ *
+ * The policy tracks three things:
+ * - the max amount authorized
+ * - the amount actually settled
+ * - ledger deltas for reservation, settlement, and release of unused capacity
+ */
+export type UptoAuthorizationStatus = "authorized" | "partially_settled" | "settled" | "released";
+export interface UptoAuthorizationRequest {
+    authorizationId?: string;
+    service: string;
+    resource?: string;
+    network: string;
+    asset: string;
+    payTo: string;
+    maxAmount: bigint;
+    metadata?: Record<string, unknown>;
+    authorizedAt?: string;
+}
+export interface UptoSettlementOptions {
+    settledAt?: string;
+    finalize?: boolean;
+    txHash?: string;
+    reference?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface UptoSettlementRecord {
+    settlementId: string;
+    authorizationId: string;
+    amount: bigint;
+    settledAt: string;
+    txHash?: string;
+    reference?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface UptoAuthorizationRecord {
+    authorizationId: string;
+    service: string;
+    resource?: string;
+    network: string;
+    asset: string;
+    payTo: string;
+    maxAmount: bigint;
+    settledAmount: bigint;
+    releasedAmount: bigint;
+    remainingAmount: bigint;
+    authorizedAt: string;
+    finalizedAt?: string;
+    status: UptoAuthorizationStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface WalletLedgerDelta {
+    deltaId: string;
+    authorizationId: string;
+    type: "authorization" | "settlement" | "release";
+    timestamp: string;
+    reservedDelta: bigint;
+    settledDelta: bigint;
+    netWalletDelta: bigint;
+    txHash?: string;
+    reference?: string;
+}
+export interface UptoBillingSnapshot {
+    authorization: UptoAuthorizationRecord;
+    settlements: UptoSettlementRecord[];
+    ledgerDeltas: WalletLedgerDelta[];
+}
+export declare class UptoBillingPolicy {
+    private authorizations;
+    private settlements;
+    private ledger;
+    authorize(request: UptoAuthorizationRequest): UptoAuthorizationRecord;
+    recordSettlement(authorizationId: string, amount: bigint, options?: UptoSettlementOptions): UptoBillingSnapshot;
+    finalizeAuthorization(authorizationId: string, finalizedAt?: string, reference?: string): UptoAuthorizationRecord;
+    getAuthorization(authorizationId: string): UptoAuthorizationRecord | null;
+    listAuthorizations(): UptoAuthorizationRecord[];
+    getSettlements(authorizationId: string): UptoSettlementRecord[];
+    getWalletLedgerDeltas(authorizationId: string): WalletLedgerDelta[];
+    getSnapshot(authorizationId: string): UptoBillingSnapshot;
+    getNetWalletDelta(authorizationId: string): bigint;
+    getReservedAmount(authorizationId: string): bigint;
+    private requireAuthorization;
+}

package/dist/sdk/router/PaymentRouter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * PaymentRouter — Three-rail payment architecture.
+ *
+ * Routes payments across three rails:
+ *   1. **x402** (crypto-native) — on-chain USDC payments via the x402 protocol. Optimal for
+ *      micropayments, autonomous agents, and scenarios requiring on-chain audit trails.
+ *   2. **MPP** (Managed Payment Protocol / Stripe) — fiat-based payments with dispute resolution.
+ *      Optimal for larger amounts, supervised agents, and high-frequency session batching.
+ *   3. **Google AP2** (Agent Payment Protocol) — reserved rail for Google's managed agent
+ *      payment flow. Settlement on Base when explicitly marked live by configuration.
+ *
+ * Routing criteria:
+ *   - Transaction amount (micropayments → x402, high-frequency → MPP)
+ *   - Session context (ongoing session → MPP for batching efficiency)
+ *   - Agent autonomy level (autonomous → x402, supervised → MPP)
+ *   - Chain/ecosystem preference (Google ecosystem → AP2, Solana → x402-solana)
+ *   - Rail availability
+ *
+ * @module router/PaymentRouter
+ */
+export type PaymentRail = "x402" | "mpp" | "x402-solana" | "google-ap2";
+export type RailStatus = "live" | "planned" | "disabled";
+export interface RailConfig {
+    rail: PaymentRail;
+    status: RailStatus;
+    /** Maximum per-transaction amount in USDC micro-units (6 decimals) */
+    maxAmount?: number;
+    /** Minimum per-transaction amount in USDC micro-units */
+    minAmount?: number;
+}
+export interface PaymentContext {
+    /** Amount in USDC micro-units (6 decimals). e.g. 1_000_000 = $1.00 */
+    amount: number;
+    /** Recipient address or merchant domain */
+    recipient: string;
+    /** Whether this payment is part of an active session with repeated transactions */
+    isSessionContext?: boolean;
+    /** Number of transactions in the current session (if applicable) */
+    sessionTxCount?: number;
+    /** Whether the agent is operating autonomously (no human in loop) */
+    autonomous?: boolean;
+    /** Preferred chain, if any */
+    preferredChain?: "base" | "solana" | "google-ap2";
+}
+export interface RoutingDecision {
+    rail: PaymentRail;
+    reason: string;
+    /** Estimated cost overhead (basis points) */
+    estimatedOverheadBps: number;
+    /** Whether this rail is currently live */
+    isLive: boolean;
+}
+export declare class PaymentRouter {
+    private rails;
+    /** Amount threshold (micro-units) below which x402 is preferred. Default: $1.00 */
+    private microPaymentThreshold;
+    /** Session tx count above which MPP is preferred for batching. Default: 5 */
+    private highFrequencyThreshold;
+    constructor(options?: {
+        rails?: RailConfig[];
+        microPaymentThreshold?: number;
+        highFrequencyThreshold?: number;
+    });
+    /**
+     * Select the optimal payment rail for a given context.
+     */
+    route(context: PaymentContext): RoutingDecision;
+    /**
+     * Get all available (live) rails.
+     */
+    getLiveRails(): RailConfig[];
+    /**
+     * Check if a specific rail is available.
+     */
+    isRailLive(rail: PaymentRail): boolean;
+    private getRail;
+}

package/dist/sdk/router/index.d.ts

@@ -0,0 +1,2 @@
+export type { PaymentContext, PaymentRail, RailConfig, RailStatus, RoutingDecision, } from "./PaymentRouter.js";
+export { PaymentRouter } from "./PaymentRouter.js";

package/dist/sdk/swap/SwapModule.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module swap/SwapModule
+ * SwapModule — multi-chain Uniswap V3 token swap aggregator with 0.875% protocol fee.
+ *
+ * Supports Base, Arbitrum, Optimism, and Polygon. Automatically selects the best
+ * Uniswap V3 fee tier (0.01%, 0.05%, 0.3%, 1%) by quoting all tiers and choosing
+ * the highest output. Applies slippage protection and an optional protocol fee.
+ *
+ * Usage: construct with `chain` param or use `attachSwap(wallet, { chain: 'arbitrum' })`.
+ */
+import { type Address, type Hash, type PublicClient, type WalletClient } from "viem";
+import { type SwapChain, type SwapModuleConfig, type SwapOptions, type SwapQuote, type SwapResult } from "./types.js";
+/** Calculate protocol fee: floor(amount * feeBps / 100_000) */
+export declare function calcProtocolFee(amount: bigint, feeBps: number): bigint;
+/** Apply slippage: floor(amount * (10_000 - slippageBps) / 10_000) */
+export declare function applySlippage(amount: bigint, slippageBps: number): bigint;
+/** Encode deadline: block.timestamp + deadlineSecs */
+export declare function calcDeadline(deadlineSecs: number): bigint;
+export declare class SwapModule {
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly accountAddress;
+    private readonly config;
+    constructor(publicClient: PublicClient, walletClient: WalletClient, accountAddress: Address, config?: Partial<SwapModuleConfig> & {
+        chain?: SwapChain;
+    });
+    getQuote(tokenIn: Address, tokenOut: Address, amountIn: bigint, options?: Pick<SwapOptions, "slippageBps" | "feeTiers">): Promise<SwapQuote>;
+    ensureApproval(token: Address, spender: Address, amount: bigint): Promise<Hash | undefined>;
+    private transferFee;
+    swap(tokenIn: Address, tokenOut: Address, amountIn: bigint, options?: SwapOptions): Promise<SwapResult>;
+    getConfig(): SwapModuleConfig;
+    setFeeWallet(address: Address): void;
+}
+export declare function attachSwap(wallet: {
+    address: Address;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+}, config?: Partial<SwapModuleConfig> & {
+    chain?: SwapChain;
+}): {
+    swapModule: SwapModule;
+    swap: (tokenIn: Address, tokenOut: Address, amountIn: bigint, options?: SwapOptions) => Promise<SwapResult>;
+    getQuote: (tokenIn: Address, tokenOut: Address, amountIn: bigint, options?: Pick<SwapOptions, "slippageBps" | "feeTiers">) => Promise<SwapQuote>;
+    address: Address;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+};

package/dist/sdk/swap/abi.d.ts

@@ -0,0 +1,50 @@
+/** Uniswap V3 SwapRouter02 ABI — exactInputSingle */
+export declare const UniswapV3RouterAbi: {
+    name: string;
+    type: string;
+    stateMutability: string;
+    inputs: {
+        name: string;
+        type: string;
+        components: {
+            name: string;
+            type: string;
+        }[];
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+}[];
+/** Uniswap V3 QuoterV2 ABI — quoteExactInputSingle */
+export declare const UniswapV3QuoterV2Abi: {
+    name: string;
+    type: string;
+    stateMutability: string;
+    inputs: {
+        name: string;
+        type: string;
+        components: {
+            name: string;
+            type: string;
+        }[];
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+}[];
+/** Minimal ERC-20 ABI for allowance, approve, transferFrom */
+export declare const ERC20Abi: {
+    name: string;
+    type: string;
+    stateMutability: string;
+    inputs: {
+        name: string;
+        type: string;
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+    }[];
+}[];

package/dist/sdk/swap/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module swap
+ * Re-exports for the SwapModule: multi-chain Uniswap V3 swaps.
+ *
+ * Supported chains: base, arbitrum, optimism, polygon.
+ * Use SwapModule directly or attachSwap(wallet, { chain }) for a wallet-bound instance.
+ */
+export { ERC20Abi, UniswapV3QuoterV2Abi, UniswapV3RouterAbi } from "./abi.js";
+export { applySlippage, attachSwap, calcDeadline, calcProtocolFee, SwapModule, } from "./SwapModule.js";
+export type { SwapChain, SwapModuleConfig, SwapOptions, SwapQuote, SwapResult, UniswapFeeTier, } from "./types.js";
+export { ARBITRUM_TOKENS, BASE_TOKENS, DEFAULT_SLIPPAGE_BPS, OPTIMISM_TOKENS, POLYGON_TOKENS, PROTOCOL_FEE_BPS, PROTOCOL_FEE_COLLECTOR, UNISWAP_V3_ADDRESSES, } from "./types.js";

package/dist/sdk/swap/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module swap/types
+ * Type definitions and constants for the multi-chain Uniswap V3 SwapModule.
+ *
+ * Supported swap chains: Base, Arbitrum, Optimism, Polygon.
+ * All router/quoter addresses verified against official Uniswap V3 deployment docs:
+ * - Base: https://docs.uniswap.org/contracts/v3/reference/deployments/base-deployments
+ * - Arbitrum: https://docs.uniswap.org/contracts/v3/reference/deployments/arbitrum-deployments
+ * - Optimism: https://docs.uniswap.org/contracts/v3/reference/deployments/optimism-deployments
+ * - Polygon: https://docs.uniswap.org/contracts/v3/reference/deployments/polygon-deployments
+ *
+ * Note: Base uses a unique SwapRouter02 address; Arbitrum, Optimism, and Polygon
+ * share the same universal SwapRouter02 deployment address.
+ */
+import type { Address, Hash } from "viem";
+/** Uniswap V3 fee tier options */
+export type UniswapFeeTier = 100 | 500 | 3000 | 10000;
+/** Chains supported for Uniswap V3 swap */
+export type SwapChain = "base" | "arbitrum" | "optimism" | "polygon";
+export interface SwapQuote {
+    tokenIn: Address;
+    tokenOut: Address;
+    amountInRaw: bigint;
+    amountInNet: bigint;
+    feeAmount: bigint;
+    amountOut: bigint;
+    amountOutMinimum: bigint;
+    poolFeeTier: UniswapFeeTier;
+    effectiveRate: number;
+    gasEstimate: bigint;
+}
+export interface SwapOptions {
+    slippageBps?: number;
+    feeTiers?: UniswapFeeTier[];
+    deadlineSecs?: number;
+    feeWallet?: Address;
+}
+export interface SwapResult {
+    txHash: Hash;
+    feeTxHash?: Hash;
+    quote: SwapQuote;
+    approvalRequired: boolean;
+    approvalTxHash?: Hash;
+}
+export interface SwapModuleConfig {
+    routerAddress: Address;
+    quoterAddress: Address;
+    feeBps: number;
+    feeWallet: Address;
+    /** Chain this SwapModule is configured for */
+    chain: SwapChain;
+}
+/** Well-known Base Mainnet token addresses */
+export declare const BASE_TOKENS: {
+    USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+    WETH: "0x4200000000000000000000000000000000000006";
+    cbETH: "0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22";
+    WNATIVE: "0x4200000000000000000000000000000000000006";
+};
+/** Well-known Arbitrum token addresses */
+export declare const ARBITRUM_TOKENS: {
+    USDC: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
+    WETH: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1";
+    WNATIVE: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1";
+};
+/** Well-known Optimism token addresses */
+export declare const OPTIMISM_TOKENS: {
+    USDC: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85";
+    WETH: "0x4200000000000000000000000000000000000006";
+    OP: "0x4200000000000000000000000000000000000042";
+    WNATIVE: "0x4200000000000000000000000000000000000006";
+};
+/** Well-known Polygon token addresses */
+export declare const POLYGON_TOKENS: {
+    USDC: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359";
+    WETH: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619";
+    WMATIC: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270";
+    WNATIVE: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270";
+};
+/**
+ * Uniswap V3 router and quoter addresses.
+ *
+ * Base has a different router (SwapRouter02 deployed at a unique address due to BASE chain launch).
+ * Arbitrum, Optimism, and Polygon use the same universal SwapRouter02 address.
+ *
+ * Sources:
+ *   - Base: https://docs.uniswap.org/contracts/v3/reference/deployments/base-deployments
+ *   - Arbitrum: https://docs.uniswap.org/contracts/v3/reference/deployments/arbitrum-deployments
+ *   - Optimism: https://docs.uniswap.org/contracts/v3/reference/deployments/optimism-deployments
+ *   - Polygon: https://docs.uniswap.org/contracts/v3/reference/deployments/polygon-deployments
+ */
+export declare const UNISWAP_V3_ADDRESSES: Record<SwapChain, {
+    ROUTER: Address;
+    QUOTER_V2: Address;
+}>;
+/** Protocol fee in bps — 0.875% */
+export declare const PROTOCOL_FEE_BPS = 875;
+/** Protocol fee collector address (all EVM chains) */
+export declare const PROTOCOL_FEE_COLLECTOR: "0xff86829393C6C26A4EC122bE0Cc3E466Ef876AdD";
+/** Default slippage in bps — 0.5% */
+export declare const DEFAULT_SLIPPAGE_BPS = 50;

package/dist/sdk/tokens/decimals.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module tokens/decimals
+ * Token decimal normalization utilities for multi-token agent wallets.
+ *
+ * Handles safe conversion between human-readable amounts ("1.5") and raw
+ * on-chain bigint amounts (1500000n for USDC with 6 decimals). All arithmetic
+ * is done in integer domain to avoid floating point precision errors.
+ */
+import type { Address } from "viem";
+/** Minimal token info required for formatting */
+export interface TokenInfo {
+    symbol: string;
+    decimals: number;
+    address: Address;
+    name?: string;
+    chainId?: number;
+}
+/**
+ * Convert a human-readable amount string to raw bigint (on-chain units).
+ *
+ * @param amount - Human-readable amount, e.g. "1.5" or "1000"
+ * @param decimals - Token decimal places (e.g. 6 for USDC, 18 for WETH)
+ * @returns Raw on-chain amount as bigint
+ *
+ * @example
+ * toRaw("1.5", 6)   // → 1500000n  (1.5 USDC)
+ * toRaw("1.0", 18)  // → 1000000000000000000n  (1 WETH)
+ * toRaw("0.001", 8) // → 100000n  (0.001 WBTC)
+ */
+export declare function toRaw(amount: string | bigint, decimals: number): bigint;
+/**
+ * Convert a raw bigint on-chain amount to a human-readable string.
+ *
+ * @param amount - Raw on-chain amount
+ * @param decimals - Token decimal places
+ * @returns Human-readable string, trimmed trailing zeros
+ *
+ * @example
+ * toHuman(1500000n, 6)               // → "1.5"
+ * toHuman(1000000000000000000n, 18)  // → "1.0"
+ * toHuman(0n, 6)                     // → "0.0"
+ */
+export declare function toHuman(amount: bigint, decimals: number): string;
+/**
+ * Format a raw bigint amount with token symbol for display.
+ *
+ * @param amount - Raw on-chain amount
+ * @param token - Token info (symbol + decimals required)
+ * @param displayDecimals - Max decimal places to show (default: 4 for high-precision, 2 for stablecoins)
+ * @returns Formatted string e.g. "1.50 USDC" or "0.0023 WETH"
+ *
+ * @example
+ * formatBalance(1500000n, { symbol: 'USDC', decimals: 6, address: '0x...' })
+ * // → "1.50 USDC"
+ */
+export declare function formatBalance(amount: bigint, token: Pick<TokenInfo, "symbol" | "decimals">, displayDecimals?: number): string;
+/**
+ * Parse amount that may be either a string (human-readable) or bigint (raw).
+ * Returns raw bigint. Used in transfer functions to accept flexible input.
+ *
+ * @param amount - Either a human-readable string "1.5" or a raw bigint
+ * @param decimals - Required only when amount is a string
+ */
+export declare function parseAmount(amount: string | bigint, decimals: number): bigint;

package/dist/sdk/tokens/registry.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module tokens/registry
+ * TokenRegistry — multi-chain token address registry for AgentWallet v6.
+ *
+ * Ships pre-populated with top tokens for all 11 supported EVM chains.
+ * All addresses sourced from:
+ *   - EVM: CoinGecko official token lists + chain explorers
+ *   - USDC: https://developers.circle.com/stablecoins/usdc-contract-addresses
+ *   - WBTC: https://wbtc.network/dashboard/order
+ *   - WETH: official wrapped ETH contracts per chain
+ *   - L2 native tokens: official L2 documentation
+ *
+ * Chain IDs follow the CHAIN_IDS map in src/types.ts.
+ */
+import type { Address } from "viem";
+import type { TokenInfo } from "./decimals.js";
+export type { TokenInfo };
+/** Full token entry stored in the registry */
+export interface TokenEntry extends TokenInfo {
+    chainId: number;
+    name: string;
+    isNative?: boolean;
+}
+/** Params for adding a custom token */
+export interface AddTokenParams {
+    symbol: string;
+    address: Address;
+    decimals: number;
+    chainId: number;
+    name?: string;
+    isNative?: boolean;
+}
+export declare class TokenRegistry {
+    private readonly tokens;
+    constructor(initialTokens?: TokenEntry[]);
+    private _key;
+    private _store;
+    /**
+     * Add or overwrite a token in the registry.
+     */
+    addToken(params: AddTokenParams): void;
+    /**
+     * Look up a token by symbol and chainId.
+     * Returns undefined if not found.
+     */
+    getToken(symbol: string, chainId: number): TokenEntry | undefined;
+    /**
+     * List all tokens registered for a given chainId.
+     */
+    listTokens(chainId: number): TokenEntry[];
+    /**
+     * Find a token by its contract address on a given chain.
+     */
+    getTokenByAddress(address: Address, chainId: number): TokenEntry | undefined;
+    /**
+     * Returns all registered tokens (all chains).
+     */
+    getAllTokens(): TokenEntry[];
+    /**
+     * Returns number of registered tokens.
+     */
+    size(): number;
+}
+/** Global registry with all supported chains pre-populated. */
+export declare function getGlobalRegistry(): TokenRegistry;
+/** Create a fresh registry pre-populated for a single chain.
+ * @internal — reserved for per-chain filtering API
+ */
+export declare function createChainRegistry(_chainId: number): TokenRegistry;
+export declare const ETHEREUM_REGISTRY: TokenRegistry;
+export declare const BASE_REGISTRY: TokenRegistry;
+export declare const ARBITRUM_REGISTRY: TokenRegistry;
+export declare const OPTIMISM_REGISTRY: TokenRegistry;
+export declare const POLYGON_REGISTRY: TokenRegistry;
+export declare const AVALANCHE_REGISTRY: TokenRegistry;
+export declare const UNICHAIN_REGISTRY: TokenRegistry;
+export declare const LINEA_REGISTRY: TokenRegistry;
+export declare const SONIC_REGISTRY: TokenRegistry;
+export declare const WORLDCHAIN_REGISTRY: TokenRegistry;
+export declare const BASE_SEPOLIA_REGISTRY: TokenRegistry;
+export declare function getNativeToken(chainId: number): TokenEntry | undefined;