@naculus/connect-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3884 @@
+/**
+ * Error types for Account Abstraction (ERC-4337) operations.
+ *
+ * Independent error class — core package does not depend on wallet-engine.
+ */
+type AAErrorCode = "aa_unsupported_chain" | "aa_no_bundler" | "aa_no_paymaster" | "aa_no_entry_point" | "aa_no_factory" | "aa_account_not_deployed" | "aa_account_already_deployed" | "aa_invalid_owner" | "aa_user_op_failed" | "aa_user_op_rejected" | "aa_estimation_failed" | "aa_signature_failed" | "aa_rpc_error" | "aa_invalid_input" | "aa_unknown_account_type" | "aa_no_calls" | "aa_encode_error" | "aa_paymaster_rejected" | "aa_receipt_timeout" | "aa_unknown_error";
+/** Human-readable messages for each error code */
+declare const AA_ERROR_MESSAGES: Record<AAErrorCode, string>;
+declare class AccountAbstractionError extends Error {
+    readonly code: AAErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: AAErrorCode, message?: string, cause?: unknown | undefined);
+    hasCode(code: AAErrorCode): boolean;
+}
+/** Type guard */
+declare function isAAError(e: unknown): e is AccountAbstractionError;
+
+/**
+ * ERC-4337 Account Abstraction Types
+ *
+ * Defines the type hierarchy for Smart Contract Wallet management,
+ * UserOperation construction, Paymaster integration, and batch transactions.
+ *
+ * @see docs/features/account-abstraction.md
+ */
+type Address = `0x${string}`;
+type Hex = `0x${string}`;
+/**
+ * ERC-4337 UserOperation structure.
+ * Follows the v0.7 spec: accountGasLimits replaces separate callGasLimit/verificationGasLimit,
+ * and paymasterPostOpGasLimit is bundled into paymasterData.
+ */
+interface UserOperation {
+    sender: Address;
+    nonce: bigint;
+    initCode: Hex;
+    callData: Hex;
+    /** ABI-encoded callGasLimit + verificationGasLimit (v0.7) */
+    accountGasLimits: Hex;
+    preVerificationGas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    /** ABI-encoded paymaster + paymasterVerificationGasLimit + paymasterPostOpGasLimit + paymasterData */
+    paymasterAndData: Hex;
+    signature: Hex;
+}
+interface Call {
+    /** Target contract address */
+    to: Address;
+    /** Value in wei (0n for pure function calls) */
+    value: bigint;
+    /** Encoded calldata */
+    data: Hex;
+}
+type AccountType = "simple" | "light" | "kernel" | "safe";
+interface SmartAccountConfig {
+    /** Owner address (typically an EOA) */
+    owner: Address;
+    /** Optional salt for CREATE2 deterministic address */
+    salt?: bigint;
+    /** Account implementation type */
+    accountType: AccountType;
+    /** ERC-4337 EntryPoint contract address */
+    entryPoint: Address;
+    /** Chain ID (CAIP-2 format, e.g. "eip155:1") */
+    chainId: string;
+}
+interface SmartAccountInfo {
+    /** Deterministic counterfactual address */
+    address: Address;
+    /** Whether the contract is deployed on-chain */
+    isDeployed: boolean;
+    /** Account type */
+    accountType: AccountType;
+    /** Owner address */
+    owner: Address;
+}
+interface BundlerClient {
+    /** RPC endpoint URL */
+    url: string;
+    /** Optional API key for authenticated bundler services */
+    apiKey?: string;
+}
+interface UserOperationResponse {
+    /** UserOp hash (returned by eth_sendUserOperation) */
+    userOpHash: Hex;
+    /** Smart account sender address */
+    sender: Address;
+    /** UserOp nonce */
+    nonce: bigint;
+}
+interface UserOperationReceipt {
+    userOpHash: Hex;
+    entryPoint: Address;
+    sender: Address;
+    nonce: bigint;
+    paymaster?: Address;
+    actualGasUsed: bigint;
+    actualGasCost: bigint;
+    success: boolean;
+    /** Transaction receipt of the HandleOps bundle */
+    transactionHash: Hex;
+    /** Array of logs emitted during execution */
+    logs: Log[];
+}
+interface Log {
+    address: Address;
+    topics: Hex[];
+    data: Hex;
+}
+interface UserOperationGasEstimate {
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+    /** v0.7 bundlers may return accountGasLimits */
+    accountGasLimits?: Hex;
+}
+type PaymasterType = "verifying" | "token" | "sponsor" | "custom";
+interface PaymasterConfig {
+    type: PaymasterType;
+    /** Paymaster RPC URL */
+    url: string;
+    /** Optional policy configuration */
+    policy?: {
+        /** Whitelisted dApp origins */
+        allowedDapps?: string[];
+        /** ERC-20 token address for token paymaster */
+        token?: Address;
+        /** Maximum gas per UserOperation */
+        maxGasPerUserOp?: bigint;
+    };
+}
+interface PaymasterData {
+    /** The paymasterAndData hex to inject into UserOperation */
+    paymasterAndData: Hex;
+    /** Human-readable sponsorship info */
+    sponsorInfo?: string;
+}
+interface Paymaster {
+    /** Get paymaster data for a UserOperation */
+    getPaymasterData(userOp: Partial<UserOperation>): Promise<PaymasterData>;
+    /** Verify if a UserOperation is eligible for sponsorship */
+    isSponsored(userOp: Partial<UserOperation>): Promise<boolean>;
+}
+interface SendUserOpOptions {
+    /** Optional gas overrides */
+    gasOverrides?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    /** Optional paymaster configuration */
+    paymaster?: PaymasterConfig;
+    /** Whether to skip deploy (for already deployed accounts) */
+    skipDeploy?: boolean;
+}
+/**
+ * ERC-4337 EntryPoint v0.6 contract addresses.
+ * https://github.com/eth-infinitism/account-abstraction
+ */
+declare const ENTRY_POINT_V0_6: Address;
+/**
+ * ERC-4337 EntryPoint v0.7 contract address (same on all chains).
+ */
+declare const ENTRY_POINT_V0_7: Address;
+/**
+ * Default EntryPoint address (v0.7).
+ */
+declare const DEFAULT_ENTRY_POINT: `0x${string}`;
+/**
+ * SimpleAccount Factory address (eth-infinitism).
+ * Deployed at the same address on all supported chains via CREATE2.
+ */
+declare const SIMPLE_ACCOUNT_FACTORY: Address;
+/** Default call gas limit for UserOperations */
+declare const DEFAULT_CALL_GAS_LIMIT = 100000n;
+/** Default verification gas limit for UserOperations */
+declare const DEFAULT_VERIFICATION_GAS_LIMIT = 100000n;
+/** Default pre-verification gas for UserOperations */
+declare const DEFAULT_PRE_VERIFICATION_GAS = 50000n;
+/**
+ * Chains known to support ERC-4337 AA (EntryPoint deployed).
+ * Keyed by CAIP-2 chain ID.
+ */
+declare const AA_SUPPORTED_CHAINS: Record<string, {
+    entryPoint: Address;
+    factory: Address;
+}>;
+
+/**
+ * Paymaster Integration for ERC-4337
+ *
+ * Provides Paymaster abstractions for gas sponsorship:
+ * - Paymaster interface (pluggable)
+ * - VerifyingPaymaster: API-based sponsorship via paymaster RPC
+ * - PaymasterService: orchestrator for paymaster data injection
+ *
+ * @see docs/features/account-abstraction.md
+ */
+
+interface PaymasterServiceConfig {
+    /** Paymaster RPC URL */
+    url: string;
+    /** Paymaster type */
+    type: PaymasterType;
+    /** Optional policy configuration */
+    policy?: {
+        allowedDapps?: string[];
+        token?: Address;
+        maxGasPerUserOp?: bigint;
+    };
+    /** Optional API key for authenticated paymaster */
+    apiKey?: string;
+}
+/**
+ * PaymasterService manages Paymaster interactions for ERC-4337 UserOperations.
+ *
+ * Supports:
+ * - Verifying paymaster (API-based sponsorship approval)
+ * - Sponsor paymaster (free gas for whitelisted dApps)
+ * - Custom paymaster implementations
+ */
+declare class PaymasterService implements Paymaster {
+    private config;
+    private _sponsorInfo;
+    constructor(config: PaymasterServiceConfig);
+    /**
+     * Get paymaster data for a UserOperation.
+     *
+     * For verifying paymasters, this calls the paymaster RPC's
+     * pm_sponsorUserOperation method.
+     *
+     * @param userOp - The UserOperation to sponsor
+     * @returns Paymaster data including paymasterAndData hex
+     */
+    getPaymasterData(userOp: Partial<UserOperation>): Promise<PaymasterData>;
+    /**
+     * Check if a UserOperation is eligible for sponsorship.
+     *
+     * @param userOp - The UserOperation to check
+     * @returns true if the paymaster would sponsor this operation
+     */
+    isSponsored(userOp: Partial<UserOperation>): Promise<boolean>;
+    /**
+     * Get human-readable sponsorship info.
+     */
+    get sponsorInfo(): string | null;
+    /**
+     * Get paymaster data using a verifying paymaster.
+     * Calls the paymaster RPC's pm_sponsorUserOperation method.
+     */
+    private getVerifyingPaymasterData;
+    /**
+     * Get paymaster data for a simple sponsor paymaster.
+     * Uses a static or policy-based sponsorship.
+     */
+    private getSponsorPaymasterData;
+    /**
+     * Get paymaster data for a token paymaster.
+     * Requires an ERC-20 token for gas payment.
+     */
+    private getTokenPaymasterData;
+    /**
+     * Get paymaster data using a custom paymaster implementation.
+     * Delegates to the configured URL which should implement the paymaster RPC.
+     */
+    private getCustomPaymasterData;
+    /**
+     * Serialize a partial UserOperation for paymaster RPC calls.
+     * Converts bigint fields to hex strings.
+     */
+    private serializeForPaymaster;
+}
+/**
+ * Create a PaymasterService from a PaymasterConfig.
+ *
+ * @param config - Paymaster configuration
+ * @returns PaymasterService instance
+ */
+declare function createPaymasterService(config: PaymasterConfig): PaymasterService;
+
+/**
+ * Smart Account Manager
+ *
+ * Manages ERC-4337 Smart Contract Wallet lifecycle:
+ * - Counterfactual address computation (CREATE2)
+ * - Account deployment via factory contract
+ * - Deploy-and-execute (merge deploy into first UserOperation)
+ *
+ * Supports SimpleAccount (eth-infinitism) with EntryPoint v0.7.
+ *
+ * @see docs/features/account-abstraction.md
+ */
+
+interface SmartAccountManagerConfig {
+    /** RPC URL for the target chain */
+    rpcUrl: string;
+    /** Bundler client configuration */
+    bundlerClient: BundlerClient;
+    /** Optional paymaster service */
+    paymaster?: PaymasterService;
+    /** Default paymaster configuration (used if no paymaster instance provided) */
+    defaultPaymasterConfig?: PaymasterConfig;
+    /** Chain ID in CAIP-2 format */
+    chainId: string;
+}
+declare class SmartAccountManager {
+    private config;
+    constructor(config: SmartAccountManagerConfig);
+    /**
+     * Check if ERC-4337 is supported on the configured chain.
+     */
+    isAASupported(chainId?: string): boolean;
+    /**
+     * Compute the counterfactual address for a smart account.
+     * The account does not need to be deployed yet.
+     *
+     * Uses the factory's createAccount to compute the address via eth_call.
+     *
+     * @param config - Smart account configuration
+     * @returns The deterministic smart account address
+     */
+    getAccountAddress(config: SmartAccountConfig): Promise<Address>;
+    /**
+     * Create a SmartAccountManager instance for a given smart account.
+     * Computes the address but does not deploy.
+     *
+     * @param config - Smart account configuration
+     * @returns Smart account info
+     */
+    createAccount(config: SmartAccountConfig): Promise<SmartAccountInfo>;
+    /**
+     * Deploy a smart account to the blockchain.
+     *
+     * Sends a raw transaction to the factory contract with the createAccount call.
+     *
+     * @param config - Smart account configuration
+     * @returns Transaction hash
+     */
+    deployAccount(config: SmartAccountConfig): Promise<Hex>;
+    /**
+     * Deploy using a minimal deployment transaction.
+     * For self-custodial setups, the deploy is a simple eth_call via the factory.
+     */
+    getDeployCallData(config: SmartAccountConfig): Promise<{
+        to: Address;
+        data: Hex;
+        value: bigint;
+    }>;
+    /**
+     * Send a UserOperation to the bundler.
+     *
+     * @param config - Smart account config
+     * @param calls - Array of calls to execute
+     * @param options - Optional overrides (gas, paymaster)
+     * @returns UserOperation response
+     */
+    sendUserOperation(config: SmartAccountConfig, calls: Call[], options?: SendUserOpOptions): Promise<UserOperationResponse>;
+    /**
+     * Get the nonce for a smart account from the EntryPoint.
+     */
+    getNonce(entryPoint: Address, sender: Address): Promise<bigint>;
+    /**
+     * Estimate gas for a UserOperation via the bundler's eth_estimateUserOperationGas.
+     */
+    estimateUserOperationGas(entryPoint: Address, partialUserOp: Partial<UserOperation>): Promise<UserOperationGasEstimate>;
+    /**
+     * Send a signed UserOperation to the bundler.
+     * Returns the userOpHash which can be used to track the operation.
+     */
+    sendUserOpToBundler(userOp: UserOperation): Promise<Hex>;
+    /**
+     * Poll for a UserOperation receipt.
+     */
+    getUserOperationReceipt(userOpHash: Hex, maxRetries?: number, intervalMs?: number): Promise<UserOperationReceipt | null>;
+    /**
+     * Send a batch of calls in a single UserOperation.
+     *
+     * @param config - Smart account config
+     * @param calls - Array of calls to batch
+     * @param options - Optional overrides
+     * @returns UserOperation response
+     */
+    sendBatch(config: SmartAccountConfig, calls: Call[], options?: SendUserOpOptions): Promise<UserOperationResponse>;
+    /**
+     * Get the latest base fee per gas.
+     */
+    getBaseFee(): Promise<bigint>;
+    /**
+     * Get the recommended priority fee.
+     */
+    getPriorityFee(): Promise<bigint>;
+    private getEntryPoint;
+    private getFactory;
+}
+/**
+ * Encode account gas limits as a packed 32-byte value (v0.7).
+ * High 16 bytes = verificationGasLimit
+ * Low 16 bytes = callGasLimit
+ */
+declare function encodeGasLimits(verificationGasLimit: bigint, callGasLimit: bigint): Hex;
+/**
+ * Decode account gas limits from packed 32-byte value (v0.7).
+ */
+declare function decodeGasLimits(accountGasLimits: Hex): {
+    verificationGasLimit: bigint;
+    callGasLimit: bigint;
+};
+
+/**
+ * UserOperation Builder & Signer
+ *
+ * Provides utilities for constructing, signing, and sending ERC-4337
+ * UserOperations without depending on @account-abstraction/sdk.
+ *
+ * @see docs/features/account-abstraction.md
+ */
+
+/**
+ * Build a partial UserOperation from the given fields.
+ *
+ * @param params - UserOperation fields
+ * @returns UserOperation with defaults applied for any missing fields
+ */
+declare function buildUserOperation(params: Partial<UserOperation>): UserOperation;
+/**
+ * Build the callData for a UserOperation from one or more calls.
+ *
+ * For a single call, encodes as execute(to, value, data).
+ * For multiple calls, encodes as executeBatch(to[], value[], data[]).
+ *
+ * @param calls - Array of calls to include
+ * @returns Encoded calldata
+ */
+declare function buildCallData(calls: Call[]): Hex;
+declare function hashUserOperation(userOp: UserOperation, entryPoint: Address, chainId: number): Hex;
+/**
+ * Sign a UserOperation using EIP-191 or EIP-712.
+ *
+ * For SimpleAccount, the signature is a standard ECDSA signature.
+ *
+ * @param userOp - The UserOperation to sign (without signature)
+ * @param signer - A function that signs arbitrary data (e.g. personal_sign)
+ * @param entryPoint - EntryPoint contract address
+ * @param chainId - EVM chain ID
+ * @returns The UserOperation with signature field filled
+ */
+declare function signUserOperation(userOp: UserOperation, signer: (hash: Hex) => Promise<Hex> | Hex, entryPoint: Address, chainId: number): Promise<UserOperation>;
+/**
+ * Send a UserOperation to a bundler RPC endpoint.
+ *
+ * @param userOp - The signed UserOperation
+ * @param bundlerUrl - Bundler RPC URL
+ * @param entryPoint - EntryPoint contract address
+ * @returns UserOperation response with userOpHash
+ */
+declare function sendUserOperation(userOp: UserOperation, bundlerUrl: string, entryPoint: Address): Promise<UserOperationResponse>;
+/**
+ * Estimate gas for a UserOperation via the bundler's eth_estimateUserOperationGas.
+ *
+ * @param userOp - Partial UserOperation (signature not required)
+ * @param entryPoint - EntryPoint contract address
+ * @param bundlerUrl - Bundler RPC URL
+ * @returns Gas estimates (callGasLimit, verificationGasLimit, preVerificationGas)
+ */
+declare function estimateUserOperationGas(userOp: Partial<UserOperation>, entryPoint: Address, bundlerUrl: string): Promise<UserOperationGasEstimate>;
+
+/**
+ * Address validation helpers.
+ *
+ * Minimal set — enough to prevent blackhole transfers.
+ */
+/** True for `0x0000…0000` (zero/burn address on all EVM chains) */
+declare function isZeroAddress(address: string): boolean;
+/** True if the address contains known burn-indicating hex prefixes */
+declare function isBurnAddress(address: string): boolean;
+/**
+ * Returns true if the string is a valid address for the given chain namespace.
+ * For EVM chains: 0x + 40 hex chars (checksum optional).
+ * Solana / XRPL: basic format check (length & prefix).
+ */
+declare function isValidAddress(address: string, chainNamespace?: string): boolean;
+
+type Namespace = "eip155" | "solana" | string;
+interface NamespaceCapabilities {
+    atomicBatch?: {
+        supported: boolean;
+        maxBatchSize?: number;
+    };
+    paymasterService?: {
+        supported: boolean;
+    };
+    permissions?: boolean;
+    serverSigning?: boolean;
+    [key: string]: unknown;
+}
+interface SessionNamespace {
+    chains: string[];
+    accounts: string[];
+    methods: string[];
+    events: string[];
+    capabilities?: NamespaceCapabilities;
+}
+interface UniversalWalletSession {
+    id: string;
+    topic?: string;
+    walletId: string;
+    walletType: "walletconnect" | "eip6963" | "xrpl" | string;
+    namespaces: Record<Namespace, SessionNamespace>;
+    platform: "desktop-web" | "mobile-web" | "in-app-browser";
+    auth?: {
+        method: "siwe" | "siws" | "none";
+        issuedAt?: string;
+        expiresAt?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** Connector-specific identifier, set during session creation */
+    connectorId?: string;
+    /** Expiry datetime set by session-key manager */
+    expiry?: string | number;
+}
+interface SessionStorage {
+    load(): Promise<UniversalWalletSession | null>;
+    save(session: UniversalWalletSession): Promise<void>;
+    clear(): Promise<void>;
+}
+interface CreateEmptySessionInput {
+    id: string;
+    walletId: string;
+    walletType: UniversalWalletSession["walletType"];
+    namespaces: Record<Namespace, SessionNamespace>;
+    platform: UniversalWalletSession["platform"];
+    topic?: string;
+    auth?: UniversalWalletSession["auth"];
+    createdAt?: string;
+    updatedAt?: string;
+}
+declare function createEmptySession(input: CreateEmptySessionInput): UniversalWalletSession;
+declare function updateSession(session: UniversalWalletSession, patch: Partial<UniversalWalletSession>): UniversalWalletSession;
+declare function isSessionExpired(session: UniversalWalletSession, now: Date): boolean;
+/**
+ * Session storage backed by localStorage via the unified StorageAdapter.
+ *
+ * Resolves the "dual storage system" tech debt: instead of directly
+ * calling localStorage.getItem/setItem, this delegates to
+ * LocalStorageAdapter which provides prefix support, availability
+ * detection, quota error handling, and typed parse-error reporting.
+ */
+declare class LocalStorageSessionStorage implements SessionStorage {
+    private readonly adapter;
+    private readonly innerKey;
+    /**
+     * @param key - localStorage key used to store the session blob.
+     *             Defaults to "naculus_web3_session".
+     */
+    constructor(key?: string);
+    /**
+     * Return whether localStorage is available in the current environment.
+     * Useful for consumers that want to check before calling load/save.
+     */
+    isAvailable(): boolean;
+    load(): Promise<UniversalWalletSession | null>;
+    save(session: UniversalWalletSession): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Auto-Reconnect Manager
+ *
+ * Handles automatic reconnection to previously connected wallets
+ * with configurable retry strategies.
+ */
+
+interface AutoReconnectConfig {
+    enabled: boolean;
+    maxRetries: number;
+    retryDelay: number;
+    onReconnecting?: () => void;
+    onReconnected?: () => void;
+    onFailed?: (error: Error) => void;
+}
+interface ReconnectState<T = UniversalWalletSession> {
+    lastSession: T | null;
+    retryCount: number;
+    isReconnecting: boolean;
+}
+declare class AutoReconnectManager<T = UniversalWalletSession> {
+    private config;
+    private state;
+    private retryTimeout;
+    constructor(config?: Partial<AutoReconnectConfig>);
+    setLastSession(session: T): void;
+    getState(): ReconnectState<T>;
+    needsReconnect(): boolean;
+    reconnect(reconnectFn: (session: T) => Promise<unknown>): Promise<boolean>;
+    private handleReconnectError;
+    cancel(): void;
+    clearSession(): void;
+    updateConfig(config: Partial<AutoReconnectConfig>): void;
+    reset(): void;
+}
+declare function createAutoReconnectManager<T = UniversalWalletSession>(config?: Partial<AutoReconnectConfig>): AutoReconnectManager<T>;
+
+/**
+ * Chain Abstraction Types
+ *
+ * Core type definitions for cross-chain intent routing (Chain Abstraction).
+ * Defines Quote, RouteExecution, CostComparison, and supporting types
+ * for the Route Engine and Bridge Providers.
+ *
+ * @see docs/features/chain-abstraction.md
+ */
+/** Bridge provider identifier */
+type BridgeProviderId = "lifi" | "axelar" | "socket" | "across";
+/**
+ * Route step within a cross-chain route.
+ * Cross-chain routes typically decompose into:
+ *   1. Approve (optional) on source chain
+ *   2. Swap on source chain (optional)
+ *   3. Cross-chain bridge transfer
+ *   4. Swap on destination chain (optional)
+ */
+interface RouteStep {
+    type: "approve" | "swap" | "cross-chain";
+    chain: string;
+    token: string;
+    contractAddress: string;
+    data?: string;
+    /** EIP-1559 formatted gas estimate (bigint serialized as string) */
+    estimatedGas: string;
+}
+/** Gas cost estimate for a single chain in a cross-chain route */
+interface GasEstimate {
+    /** Max fee per gas in wei (serialized bigint) */
+    maxFeePerGas: string;
+    /** Max priority fee in wei (serialized bigint) */
+    maxPriorityFeePerGas: string;
+    /** Estimated gas units */
+    gasLimit: string;
+    /** Total estimated gas cost in wei */
+    totalCostWei: string;
+    /** Total estimated gas cost in USD string */
+    totalCostUsd: string;
+}
+/**
+ * A discovered cross-chain route returned by a bridge provider.
+ */
+interface Route {
+    /** Unique route identifier */
+    id: string;
+    /** The bridge provider that discovered this route */
+    provider: BridgeProviderId;
+    /** Source chain CAIP-2 identifier */
+    fromChain: string;
+    /** Destination chain CAIP-2 identifier */
+    toChain: string;
+    /** Source token contract address (or native token symbol for ETH/MATIC/SOL) */
+    fromToken: string;
+    /** Destination token contract address */
+    toToken: string;
+    /** Input amount in raw form (smallest unit, e.g. wei) */
+    fromAmount: string;
+    /** Expected output amount in raw form */
+    toAmount: string;
+    /** Minimum guaranteed output amount (accounting for slippage) */
+    toAmountMin: string;
+    /** Gas cost breakdown for each chain involved */
+    gasCosts: {
+        fromChain: GasEstimate;
+        toChain: GasEstimate;
+        totalUsd: string;
+    };
+    /** Estimated time in seconds */
+    estimatedTime: number;
+    /** Decomposition of this route into individual steps */
+    steps: RouteStep[];
+    /** Fee breakdown */
+    fee: {
+        protocolFee: string;
+        integrationFee?: string;
+    };
+    /** Human-readable summary of the route */
+    summary: string;
+}
+/** Sorting options for quote aggregation */
+type QuoteSortBy = "netReceive" | "fastest" | "cheapest";
+interface QuoteOptions {
+    /** Slippage tolerance in percent (default 0.5) */
+    slippage?: number;
+    /** Preferred bridge providers */
+    preferredBridges?: BridgeProviderId[];
+    /** Bridge providers to exclude */
+    excludeBridges?: BridgeProviderId[];
+    /** Sort order for returned quotes */
+    sortBy?: QuoteSortBy;
+}
+/**
+ * A unified cross-chain quote ready for display and execution.
+ * Aggregates data from a Route with formatting and cost metadata.
+ */
+interface Quote {
+    /** Reference to the originating route ID */
+    routeId: string;
+    /** Bridge provider */
+    provider: BridgeProviderId;
+    /** Source chain CAIP-2 */
+    fromChain: string;
+    /** Destination chain CAIP-2 */
+    toChain: string;
+    /** Source token symbol (e.g. "USDC") */
+    fromTokenSymbol: string;
+    /** Destination token symbol */
+    toTokenSymbol: string;
+    /** Source amount, formatted for display (e.g. "100.00") */
+    fromAmountFormatted: string;
+    /** Destination amount, formatted for display */
+    toAmountFormatted: string;
+    /** Minimum guaranteed output, formatted */
+    toAmountMinFormatted: string;
+    /** Effective exchange rate (1 fromToken = ? toToken) */
+    exchangeRate: string;
+    /** Price impact percentage */
+    priceImpact: string;
+    /** Total gas cost in USD */
+    totalGasCostUsd: string;
+    /** Total protocol and integration fees in USD */
+    totalFeeUsd: string;
+    /** Net receive amount after gas + fees, formatted */
+    netReceiveFormatted: string;
+    /** Estimated arrival time as human-readable string */
+    estimatedArrival: string;
+    /** Estimated arrival in seconds */
+    estimatedArrivalSeconds: number;
+    /** Human-readable step summary */
+    summary: string;
+    /** Whether this quote requires an approve transaction before execution */
+    needsApprove: boolean;
+    /** Approve target address (token contract to approve) */
+    approveTarget?: string;
+    /** Approve spender address (bridge contract) */
+    approveSpender?: string;
+    /** Approve amount in raw form */
+    approveAmount?: string;
+    /** Timestamp when this quote expires (ms) */
+    expiresAt: number;
+}
+type RouteStatusValue = "pending" | "bridging" | "completed" | "failed";
+interface RouteStatus {
+    status: RouteStatusValue;
+    fromTxHash?: string;
+    toTxHash?: string;
+    currentStep?: string;
+    /** Progress percentage 0-100 */
+    progress?: number;
+    /** Estimated completion timestamp (epoch ms) */
+    estimatedCompletionAt?: number;
+    /** Error message if status === "failed" */
+    error?: string;
+}
+interface ExecuteOptions {
+    /** Recipient address on the destination chain */
+    recipient?: string;
+    /** Whether to automatically handle approve transactions */
+    autoApprove?: boolean;
+    /** Custom approve amount in raw form (overrides default) */
+    approveAmount?: string;
+}
+interface ExecuteRouteResult {
+    /** Source chain transaction hash */
+    fromTxHash: string;
+    /** Source chain CAIP-2 */
+    fromChain: string;
+    /** Destination chain transaction hash (populated once bridging completes) */
+    toTxHash?: string;
+    /** Destination chain CAIP-2 */
+    toChain: string;
+    /** Current execution status */
+    status: RouteStatusValue;
+    /** Bridge provider reference ID (for status polling) */
+    bridgeReference?: string;
+    /** Estimated completion timestamp (epoch ms) */
+    estimatedCompletionAt?: number;
+    /** Error message if status === "failed" */
+    error?: string;
+}
+type CostComparisonOperation = "send_native" | "send_erc20" | "swap" | "cross_chain_transfer";
+interface CostComparisonOptions {
+    /** Token contract address relevant to the operation */
+    token?: string;
+    /** Amount in raw form */
+    amount?: string;
+    /** Include cross-chain fees in comparison */
+    includeCrossChain?: boolean;
+}
+interface CostComparison {
+    /** Chain CAIP-2 identifier */
+    chain: string;
+    /** Human-readable chain name */
+    chainName: string;
+    /** Gas cost in USD */
+    gasCost: string;
+    /** Protocol/bridge fees in USD */
+    fee: string;
+    /** Total cost (gas + fees) in USD */
+    totalCost: string;
+    /** Estimated time in seconds */
+    time: number;
+    /** Congestion level (optional) */
+    congestionLevel?: "low" | "medium" | "high";
+}
+interface ChainAbstractionConfig {
+    /** Senderpay backend URL (for proxy-based route discovery) */
+    backendUrl?: string;
+    /** Quote cache TTL in ms (default 30000) */
+    quoteCacheTtl?: number;
+    /** Status polling interval in ms (default 2000) */
+    statusPollInterval?: number;
+    /** Default slippage in percent (default 0.5) */
+    defaultSlippage?: number;
+    /** LiFi SDK API key (optional, for direct SDK usage) */
+    lifiApiKey?: string;
+    /** Axelar API key / config (optional, for direct SDK usage) */
+    axelarConfig?: {
+        apiUrl?: string;
+    };
+}
+/**
+ * Abstract interface for a cross-chain bridge provider.
+ * Each provider (LiFi, Axelar, Socket, Across) implements this
+ * to be registered with the RouteEngine.
+ */
+interface BridgeProvider {
+    /** Unique provider identifier */
+    readonly id: BridgeProviderId;
+    /** Human-readable provider name */
+    readonly name: string;
+    /**
+     * Discover available routes for a cross-chain transfer.
+     *
+     * @param fromChain - Source chain CAIP-2
+     * @param toChain - Destination chain CAIP-2
+     * @param fromToken - Source token address/symbol
+     * @param toToken - Destination token address/symbol
+     * @param amount - Amount in raw form (smallest unit)
+     * @returns Array of discovered routes (empty if no routes found)
+     */
+    getRoutes(fromChain: string, toChain: string, fromToken: string, toToken: string, amount: string): Promise<Route[]>;
+    /**
+     * Build transaction parameters to execute a given route.
+     *
+     * @param route - The selected route to execute
+     * @param sender - Sender address
+     * @param recipient - Recipient address on destination chain
+     * @returns Transaction parameters for the execution
+     */
+    getTransactionParams(route: Route, sender: string, recipient: string): Promise<ProviderTransaction[]>;
+    /**
+     * Query the current execution status of a cross-chain transfer.
+     *
+     * @param bridgeReference - Reference ID from the provider
+     * @returns Current route status
+     */
+    getRouteStatus(bridgeReference: string): Promise<RouteStatus>;
+    /**
+     * Check whether this provider supports a given chain pair.
+     *
+     * @param fromChain - Source chain CAIP-2
+     * @param toChain - Destination chain CAIP-2
+     * @returns true if the chain pair is supported
+     */
+    supportsChainPair(fromChain: string, toChain: string): boolean;
+    /**
+     * Check whether this provider supports a given token on a chain.
+     *
+     * @param chain - Chain CAIP-2
+     * @param token - Token contract address or symbol
+     * @returns true if the token is supported
+     */
+    supportsToken(chain: string, token: string): boolean;
+}
+interface ProviderTransaction {
+    type: "approve" | "cross-chain";
+    chainId: string;
+    to: string;
+    data: string;
+    value: string;
+}
+type ChainAbstractionErrorCode = "chain_pair_not_supported" | "token_not_supported" | "route_expired" | "insufficient_balance" | "approve_needed" | "approve_rejected" | "transaction_failed" | "backend_unavailable" | "invalid_config" | "no_routes_available" | "provider_unavailable" | "execution_failed";
+declare class ChainAbstractionError extends Error {
+    code: ChainAbstractionErrorCode;
+    details?: Record<string, unknown>;
+    constructor(code: ChainAbstractionErrorCode, message?: string, details?: Record<string, unknown>);
+}
+declare function isChainAbstractionError(e: unknown, code?: ChainAbstractionErrorCode): e is ChainAbstractionError;
+
+/**
+ * AxelarProvider — Axelar GMP integration for cross-chain transfers.
+ *
+ * Integrates with the Axelar network for General Message Passing (GMP),
+ * enabling cross-chain token transfers and arbitrary contract calls.
+ *
+ * When configured with a backend URL, proxies through senderpay backend.
+ * Otherwise attempts direct Axelar API interaction.
+ *
+ * @see https://docs.axelar.dev/dev/general-message-passing
+ */
+
+interface AxelarProviderConfig {
+    /** Axelar API base URL */
+    apiUrl?: string;
+    /** Backend proxy URL (alternative to direct API) */
+    backendUrl?: string;
+}
+declare class AxelarProvider implements BridgeProvider {
+    readonly id: BridgeProviderId;
+    readonly name = "Axelar";
+    private config;
+    constructor(config?: AxelarProviderConfig);
+    getRoutes(fromChain: string, toChain: string, fromToken: string, toToken: string, amount: string): Promise<Route[]>;
+    private getRoutesViaBackend;
+    private getRoutesViaDirectAPI;
+    getTransactionParams(_route: Route, _sender: string, _recipient: string): Promise<ProviderTransaction[]>;
+    getRouteStatus(bridgeReference: string): Promise<RouteStatus>;
+    supportsChainPair(fromChain: string, toChain: string): boolean;
+    supportsToken(chain: string, token: string): boolean;
+    private getAxelarGateway;
+    private buildGMPData;
+    private mapAxelarStatus;
+}
+
+/**
+ * LiFiProvider — LI.FI SDK integration for cross-chain swaps.
+ *
+ * Integrates with the LI.FI API to discover routes and build
+ * transaction data for hop-based cross-chain transfers.
+ *
+ * When a LI.FI API key is configured, queries the LI.FI API directly.
+ * Otherwise falls back to a senderpay backend proxy if configured.
+ *
+ * @see https://apidocs.li.fi/reference
+ */
+
+interface LiFiProviderConfig {
+    /** LI.FI API key (optional) */
+    apiKey?: string;
+    /** LI.FI API base URL */
+    apiUrl?: string;
+    /** Backend proxy URL (alternative to direct API) */
+    backendUrl?: string;
+}
+declare class LiFiProvider implements BridgeProvider {
+    readonly id: BridgeProviderId;
+    readonly name = "LI.FI";
+    private config;
+    constructor(config?: LiFiProviderConfig);
+    getRoutes(fromChain: string, toChain: string, fromToken: string, toToken: string, amount: string): Promise<Route[]>;
+    private getRoutesViaBackend;
+    private getRoutesViaDirectAPI;
+    getTransactionParams(route: Route, sender: string, recipient: string): Promise<ProviderTransaction[]>;
+    getRouteStatus(bridgeReference: string): Promise<RouteStatus>;
+    supportsChainPair(fromChain: string, toChain: string): boolean;
+    supportsToken(chain: string, token: string): boolean;
+    private mapLiFiStatus;
+}
+
+/**
+ * Chain Route Engine
+ *
+ * Core engine for cross-chain intent routing. Discovers routes across
+ * multiple bridge providers, aggregates quotes, and handles execution.
+ *
+ * Supports a pluggable provider registration mechanism so new bridges
+ * (Socket, Across, etc.) can be added without modifying this engine.
+ *
+ * @see docs/features/chain-abstraction.md §3
+ */
+
+declare class RouteEngine {
+    private providers;
+    private config;
+    /** Simple in-memory quote cache (route-level, before formatting) */
+    private quoteCache;
+    /** Route store: maps routeId → Route for execution lookup */
+    private routeStore;
+    constructor(config?: ChainAbstractionConfig);
+    /**
+     * Register a bridge provider with the route engine.
+     * Providers can be added at any time; they are discovered
+     * on each getQuote() call.
+     */
+    registerProvider(provider: BridgeProvider): void;
+    /**
+     * Unregister a previously registered provider.
+     */
+    unregisterProvider(providerId: BridgeProviderId): void;
+    /**
+     * Get a registered provider by ID.
+     */
+    getProvider(providerId: BridgeProviderId): BridgeProvider | undefined;
+    /**
+     * List all registered providers.
+     */
+    listProviders(): BridgeProvider[];
+    /**
+     * Get cross-chain quotes for a given transfer.
+     *
+     * Discovers routes from all registered providers that support the
+     * requested chain pair and token, then formats them into unified
+     * Quote objects sorted by the specified strategy.
+     *
+     * @param fromChain - Source chain CAIP-2 (e.g. "eip155:1" for Ethereum)
+     * @param toChain - Destination chain CAIP-2
+     * @param token - Token to transfer (symbol or contract address)
+     * @param amount - Amount in raw form (smallest unit)
+     * @param options - Optional quote options (slippage, sort, provider filters)
+     * @returns Sorted array of Quote objects
+     *
+     * @throws {ChainAbstractionError} if no routes are found or providers
+     *         are unavailable
+     */
+    getQuote(fromChain: string, toChain: string, token: string, amount: string, options?: QuoteOptions): Promise<Quote[]>;
+    /**
+     * Execute a cross-chain route from a selected quote.
+     *
+     * Returns transaction hashes and a bridge reference for status tracking.
+     * Actual transaction sending is handled by the caller (e.g., ConnectorManager).
+     *
+     * @param quote - The selected Quote to execute
+     * @param recipient - Recipient address on the destination chain
+     * @param options - Execution options (autoApprove, recipient)
+     * @returns ExecuteRouteResult with transaction tracking info
+     *
+     * @throws {ChainAbstractionError} if the route is expired, provider
+     *         is unavailable, or execution fails
+     */
+    executeRoute(quote: Quote, recipient: string, options?: ExecuteOptions): Promise<ExecuteRouteResult>;
+    /**
+     * Compare costs of performing an operation across multiple chains.
+     *
+     * Useful for helping users decide which chain is cheapest for
+     * a given operation (send, swap, cross-chain transfer).
+     *
+     * @param operation - The operation type to compare
+     * @param chains - Array of CAIP-2 chain IDs to compare
+     * @param options - Optional comparison parameters
+     * @returns Array of CostComparison sorted by total cost ascending
+     */
+    compareCosts(operation: CostComparisonOperation, chains: string[], options?: CostComparisonOptions): Promise<CostComparison[]>;
+    /**
+     * Poll the current status of a cross-chain route execution.
+     *
+     * @param bridgeReference - The reference ID returned from executeRoute
+     * @returns Current RouteStatus
+     */
+    getRouteStatus(bridgeReference: string): Promise<RouteStatus>;
+    /**
+     * Get the subset of providers that support the given chain pair and token.
+     * Filters by preferred/excluded bridges if configured.
+     */
+    private getActiveProviders;
+    /**
+     * Format raw routes into display-ready Quote objects and sort them.
+     */
+    private formatAndSortQuotes;
+    /**
+     * Sort quotes by the specified strategy.
+     */
+    private sortQuotes;
+    /**
+     * Resolve a token symbol from a chain and token address.
+     */
+    private resolveTokenSymbol;
+    /**
+     * Format the total fee (protocol + integration) as a USD string.
+     */
+    private formatFeeUsd;
+    /**
+     * Format estimated time as human-readable string.
+     */
+    private formatEstimatedTime;
+    /**
+     * Build a cache key from quote parameters.
+     */
+    private buildCacheKey;
+    /**
+     * Get cached routes by route ID.
+     */
+    /**
+     * Clean stale cache entries.
+     */
+    private cleanCache;
+    /**
+     * Evaluate the cost of an operation on a single chain.
+     */
+    private evaluateChainCost;
+    /**
+     * Get estimated gas units for a given operation type.
+     */
+    private getEstimatedGasUnits;
+    /**
+     * Get estimated time in seconds for an operation on a chain.
+     */
+    private getEstimatedTime;
+    /**
+     * Get a human-readable chain name.
+     */
+    private getChainName;
+    /**
+     * Get native token price in USD (simplified).
+     */
+    private getNativeTokenPriceUsd;
+    /**
+     * Get congestion level for a chain.
+     */
+    private getCongestionLevel;
+}
+declare function createRouteEngine(config?: ChainAbstractionConfig): RouteEngine;
+
+/**
+ * Chain Registry
+ *
+ * Single source of truth for chain names, token addresses, and provider IDs.
+ * Do NOT create new mapping tables elsewhere — use `CHAINS` and `getChainInfo()`.
+ */
+interface ChainInfo$1 {
+    name: string;
+    caip2Id: string;
+    nativeCurrency: {
+        symbol: string;
+        decimals: number;
+    };
+    axelarName?: string;
+    usdcAddress?: string;
+    usdcDecimals?: number;
+    usdtAddress?: string;
+    usdtDecimals?: number;
+    entryPoint?: string;
+    factoryAddress?: string;
+    explorerUrl?: string;
+    chainlinkEthUsdFeed?: string;
+}
+declare const CHAINS: Record<number, ChainInfo$1>;
+
+interface ConnectorSupport {
+    desktop: boolean;
+    mobile: boolean;
+    deepLink: boolean;
+    qr: boolean;
+    trustedReconnect: boolean;
+}
+interface BatchCall {
+    to: `0x${string}`;
+    value?: string;
+    data?: `0x${string}`;
+}
+interface WalletCapabilities {
+    atomicBatch: {
+        supported: boolean;
+        maxBatchSize?: number;
+    };
+    paymasterService?: {
+        supported: boolean;
+    };
+    [key: string]: unknown;
+}
+/** EIP-5792: getCallsStatus response */
+interface CallsStatus {
+    status: "PENDING" | "CONFIRMED";
+    receipts?: Array<{
+        logs: Array<{
+            address: string;
+            data: string;
+            topics: string[];
+        }>;
+        status: "0x1" | "0x0";
+        blockHash: string;
+        blockNumber: string;
+        gasUsed: string;
+        transactionHash: string;
+    }>;
+}
+interface UniversalConnector {
+    id: string;
+    name: string;
+    kind: string;
+    namespaces: string[];
+    supports: ConnectorSupport;
+    connect(input?: unknown): Promise<UniversalWalletSession>;
+    reconnect?(session: UniversalWalletSession): Promise<UniversalWalletSession>;
+    disconnect(session: UniversalWalletSession): Promise<void>;
+    getAccounts(session: UniversalWalletSession): Promise<string[]>;
+    signMessage?(session: UniversalWalletSession, input: unknown): Promise<unknown>;
+    signTransaction?(session: UniversalWalletSession, input: unknown): Promise<unknown>;
+    sendTransaction?(session: UniversalWalletSession, input: unknown): Promise<unknown>;
+    switchChain?(session: UniversalWalletSession, chainId: string): Promise<void>;
+    deepLink?(target: string): Promise<void>;
+    sendCalls?(session: UniversalWalletSession, calls: BatchCall[], chainId?: string): Promise<string>;
+    getCapabilities?(session: UniversalWalletSession): Promise<Record<string, WalletCapabilities>>;
+    getCallsStatus?(session: UniversalWalletSession, bundleHash: string): Promise<CallsStatus>;
+    request?(request: {
+        method: string;
+        params: unknown[];
+    }): Promise<unknown>;
+    getBalance?(chainId?: string): Promise<string>;
+}
+declare function extractAccounts(namespaces: Record<Namespace, SessionNamespace>): string[];
+declare function getChainsFromNamespaces(namespaces: Record<Namespace, SessionNamespace>): string[];
+declare function getMethodsFromNamespaces(namespaces: Record<Namespace, SessionNamespace>): string[];
+declare function getEventsFromNamespaces(namespaces: Record<Namespace, SessionNamespace>): string[];
+
+/**
+ * Connector Manager
+ *
+ * Manages multiple wallet connectors and provides a unified interface
+ * for connecting, disconnecting, and managing wallet connections.
+ */
+
+type ConnectorId = string;
+interface ConnectorEntry {
+    id: ConnectorId;
+    connector: UniversalConnector;
+    priority: number;
+}
+interface ConnectorManagerConfig {
+    autoSelect?: boolean;
+    preferOrder?: ConnectorId[];
+}
+declare class ConnectorManager {
+    private connectors;
+    private entries;
+    private activeConnectorId;
+    private activeSession;
+    private config;
+    /** Prevent concurrent connect() calls from overwriting sessions */
+    private _connecting;
+    constructor(config?: ConnectorManagerConfig);
+    register(id: ConnectorId, connector: UniversalConnector, priority?: number): void;
+    unregister(id: ConnectorId): void;
+    get(id: ConnectorId): UniversalConnector | undefined;
+    getActive(): UniversalConnector | undefined;
+    getActiveSession(): UniversalWalletSession | null;
+    list(): ConnectorEntry[];
+    listBySupport(support: keyof ConnectorSupport): UniversalConnector[];
+    connect(id?: ConnectorId, input?: unknown): Promise<UniversalWalletSession>;
+    reconnect(session: UniversalWalletSession): Promise<UniversalWalletSession>;
+    disconnect(): Promise<void>;
+    getAccounts(): Promise<string[]>;
+    signMessage(input: {
+        message: string;
+        account?: string;
+    }): Promise<unknown>;
+    sendTransaction(input: unknown): Promise<unknown>;
+    switchChain(chainId: string): Promise<void>;
+    request(request: {
+        method: string;
+        params: unknown[];
+    }): Promise<unknown>;
+    getBalance(chainId?: string): Promise<string>;
+    sendCalls(session: UniversalWalletSession, calls: BatchCall[], chainId?: string): Promise<string>;
+    getCapabilities(session: UniversalWalletSession): Promise<Record<string, WalletCapabilities>>;
+    clear(): void;
+    private selectBestConnector;
+}
+declare function createConnectorManager(config?: ConnectorManagerConfig): ConnectorManager;
+
+/**
+ * CAIP-2 Chain Namespace Identifiers
+ *
+ * References:
+ *   - CAIP-2: https://namespaces.chainagnostic.org/CAIP-2
+ */
+declare const NAMESPACE_EIP155: "eip155";
+declare const NAMESPACE_SOLANA: "solana";
+declare const NAMESPACE_XRPL: "xrpl";
+declare const SUPPORTED_NAMESPACES: readonly ["eip155", "solana", "xrpl"];
+/**
+ * Common EVM Chain IDs (CAIP-2 format)
+ */
+declare const EIP155_MAINNET = "eip155:1";
+declare const EIP155_GOERLI = "eip155:5";
+declare const EIP155_SEPOLIA = "eip155:11155111";
+declare const EIP155_POLYGON = "eip155:137";
+declare const EIP155_MUMBAI = "eip155:80001";
+declare const EIP155_ARBITRUM = "eip155:42161";
+declare const EIP155_ARBITRUM_GOERLI = "eip155:421613";
+declare const EIP155_OPTIMISM = "eip155:10";
+declare const EIP155_OPTIMISM_GOERLI = "eip155:420";
+declare const EIP155_BASE = "eip155:8453";
+/**
+ * Common Solana Cluster IDs (CAIP-2 format)
+ */
+declare const SOLANA_MAINNET = "solana:0";
+declare const SOLANA_DEVNET = "solana:1";
+declare const SOLANA_TESTNET = "solana:2";
+/**
+ * Common XRPL Network IDs (CAIP-2 format)
+ */
+declare const XRPL_MAINNET = "xrpl:0";
+declare const XRPL_TESTNET = "xrpl:1";
+declare const XRPL_DEVNET = "xrpl:2";
+/**
+ * Default EVM chain (Ethereum Mainnet)
+ */
+declare const DEFAULT_EVM_CHAIN = "eip155:1";
+/**
+ * Default Solana cluster (Mainnet)
+ */
+declare const DEFAULT_SOLANA_CLUSTER = "solana:0";
+/**
+ * Default XRPL network (Mainnet)
+ */
+declare const DEFAULT_XRPL_NETWORK = "xrpl:0";
+/**
+ * WalletConnect v2 Disconnect Reason Codes
+ *
+ * Reference: WalletConnect v2 Protocol Specification
+ */
+declare const WC_DISCONNECT_USER = 6000;
+declare const WC_DISCONNECT_TIMEOUT = 6001;
+declare const WC_DISCONNECT_SESSION_EXPIRED = 6002;
+/**
+ * Storage keys used across connectors
+ */
+declare const STORAGE_KEYS: {
+    readonly SESSION: "naculus_web3_session";
+    readonly POCKET: "naculus_pocket";
+    readonly PASSKEYS_CREDENTIAL: "naculus_passkeys_credential";
+};
+/**
+ * Nonce configuration
+ */
+declare const DEFAULT_NONCE_LENGTH = 16;
+/**
+ * Session timeout values (in milliseconds)
+ */
+declare const SESSION_TIMEOUT_MS: number;
+declare const AUTO_RECONNECT_TIMEOUT_MS: number;
+
+declare const CONNECTOR_ERROR_MESSAGES: {
+    readonly SESSION_EXPIRED: "Session expired. Please reconnect your wallet.";
+    readonly NO_ACCOUNT_SIGNING: "No account found for signing. Please reconnect your wallet.";
+    readonly NO_ACCOUNT_TX: "No account found for transaction. Please reconnect your wallet.";
+    readonly NO_ACCOUNTS: "No accounts available. Please reconnect your wallet.";
+    readonly INVALID_INPUT: "Invalid input.";
+    readonly MISSING_TX: "Missing transaction.";
+    readonly MISSING_MESSAGE: "Missing message parameter.";
+    readonly USER_REJECTED: "Operation rejected by user.";
+    readonly TX_FAILED: "Transaction failed.";
+    readonly CHAIN_UNSUPPORTED: "Chain not supported.";
+    readonly METHOD_NOT_ALLOWED: "Method not allowed.";
+    readonly WALLET_UNAVAILABLE: "Wallet not available.";
+};
+type WalletErrorCode = "wallet_unavailable" | "user_rejected" | "deeplink_timeout" | "session_expired" | "intent_expired" | "namespace_mismatch" | "chain_unsupported" | "method_not_allowed" | "method_unsupported" | "signature_rejected" | "tx_failed" | "invalid_proposal" | "invalid_input" | "siwx_error" | "no_active_session" | "chain_switch_rejected" | "invalid_chain" | "no_solana_session" | "unsupported_chain" | "fee_rpc_error";
+declare class WalletError extends Error {
+    code: WalletErrorCode;
+    details?: unknown;
+    constructor(code: WalletErrorCode, message?: string, details?: unknown);
+}
+declare function isWalletError(e: unknown, code?: WalletErrorCode): e is WalletError;
+
+/**
+ * BigInt ↔ String Conversion Utilities
+ *
+ * Provides safe conversion between bigint and string representations
+ * for fee values, integrating with wallet-engine and UI layers.
+ *
+ * @see SRS-001 §6.3
+ */
+/**
+ * Convert a bigint fee value to its decimal string representation.
+ *
+ * @param value - Fee value in wei as bigint
+ * @returns Decimal string (e.g., "15000000000" for 15 gwei)
+ *
+ * @example
+ * ```ts
+ * toDecString(15000000000n) // "15000000000"
+ * toDecString(0n)           // "0"
+ * ```
+ */
+declare function toDecString(value: bigint): string;
+/**
+ * Parse a decimal string into a bigint.
+ *
+ * @param value - Decimal string (e.g., "15000000000")
+ * @returns bigint representation
+ *
+ * @example
+ * ```ts
+ * parseBigInt("15000000000") // 15000000000n
+ * parseBigInt("0")           // 0n
+ * ```
+ */
+declare function parseBigInt(value: string): bigint;
+/**
+ * Convert a bigint to a human-readable string with a label (e.g., "25 gwei").
+ *
+ * @param wei - Value in wei as bigint
+ * @param decimals - Number of decimals for the display unit (default: 9 for gwei)
+ * @param unit - Unit label (default: "gwei")
+ * @returns Human-readable string
+ *
+ * @example
+ * ```ts
+ * toHumanReadable(25000000000n)     // "25 gwei"
+ * toHumanReadable(15000000000n, 9, "gwei") // "15 gwei"
+ * toHumanReadable(1000000000000000000n, 18, "ETH") // "1 ETH"
+ * ```
+ */
+declare function toHumanReadable(wei: bigint, decimals?: number, unit?: string): string;
+
+/**
+ * Fee Estimation Error
+ *
+ * Thrown when all fee estimation strategies have failed.
+ */
+type FeeEstimationErrorCode = "fee_estimation_failed" | "fee_chain_not_supported" | "fee_rpc_error";
+declare class FeeEstimationError extends Error {
+    code: FeeEstimationErrorCode;
+    details?: unknown;
+    constructor(code: FeeEstimationErrorCode, message?: string, details?: unknown);
+}
+declare function isFeeEstimationError(e: unknown, code?: FeeEstimationErrorCode): e is FeeEstimationError;
+/** Error message constants */
+declare const FEE_ERROR_MESSAGES: {
+    readonly ESTIMATION_FAILED: "Fee estimation failed after all strategies exhausted.";
+    readonly CHAIN_NOT_SUPPORTED: "Chain not supported for fee estimation.";
+    readonly RPC_ERROR: "RPC call failed during fee estimation.";
+};
+
+/**
+ * EIP-1559 Fee Estimation Types
+ *
+ * Defines the type hierarchy for gas fee estimation following the
+ * viem-style union return type pattern.
+ *
+ * @see SRS-001 §5.1
+ */
+/** EIP-1559 (type 2) fee values */
+interface FeeValuesEIP1559 {
+    type: "eip1559";
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}
+/** Legacy (type 0) fee values */
+interface FeeValuesLegacy {
+    type: "legacy";
+    gasPrice: bigint;
+}
+/** Union type for fee estimation return values */
+type FeeValues = FeeValuesEIP1559 | FeeValuesLegacy;
+/** Force a specific fee type strategy */
+type FeeTypeStrategy = "auto" | "eip1559" | "legacy";
+/** Configuration for the fee estimation */
+interface FeeEstimationConfig {
+    /** Chain ID in CAIP-2 format (e.g., "eip155:1" for Ethereum mainnet) */
+    chainId?: string;
+    /** Force a specific transaction type strategy */
+    type?: FeeTypeStrategy;
+    /** Override maxPriorityFeePerGas (only used for eip1559) */
+    maxPriorityFeePerGas?: bigint;
+    /** Multiplier applied to base fee for maxFeePerGas (default: 2n) */
+    baseFeeMultiplier?: bigint;
+    /** RPC endpoint URL */
+    rpcUrl: string;
+}
+/** Result of checking a chain's EIP-1559 support */
+interface ChainFeeSupport {
+    /** Whether the chain supports EIP-1559 */
+    eip1559: boolean;
+    /** Latest block's base fee per gas (available when eip1559 is true) */
+    latestBaseFee?: bigint;
+    /** Recommended priority fee (available when eip1559 is true) */
+    recommendedPriorityFee?: bigint;
+}
+/** Chain-specific fee estimator override for L2s with custom fee models */
+interface ChainFeeEstimator {
+    /** CAIP-2 chain identifier (e.g., "eip155:10" for Optimism) */
+    chainId: string;
+    /**
+     * Estimate fees for the chain.
+     * Called before the built-in heuristic logic.
+     */
+    estimateFees(rpcUrl: string, config?: Partial<FeeEstimationConfig>): Promise<FeeValues>;
+}
+
+/**
+ * EIP-1559 Fee Estimation Module
+ *
+ * Provides fee estimation for EVM chains with automatic support detection,
+ * fallback to legacy gas price, and chain-specific estimator registration.
+ *
+ * @see SRS-001 §6.1
+ */
+
+/**
+ * Register a chain-specific fee estimator.
+ * Registered estimators take priority over the built-in heuristic logic.
+ */
+declare function registerChainFeeEstimator(estimator: ChainFeeEstimator): void;
+/**
+ * Remove a previously registered chain-specific estimator.
+ */
+declare function unregisterChainFeeEstimator(chainId: string): void;
+/**
+ * Clear all registered chain-specific estimators.
+ */
+declare function clearChainFeeEstimators(): void;
+/**
+ * Fetch the suggested max priority fee via eth_maxPriorityFeePerGas.
+ *
+ * @param rpcUrl - RPC endpoint
+ * @returns The suggested priority fee (in wei), or throws if the method is not supported
+ */
+declare function estimateMaxPriorityFeePerGas(rpcUrl: string): Promise<bigint>;
+/**
+ * Fetch the base fee per gas from the latest block.
+ *
+ * @param rpcUrl - RPC endpoint
+ * @returns Base fee per gas in wei, or null if not available (pre-London fork)
+ */
+declare function getLatestBaseFee(rpcUrl: string): Promise<bigint | null>;
+/**
+ * Fetch legacy gas price via eth_gasPrice.
+ *
+ * @param rpcUrl - RPC endpoint
+ * @returns Current gas price in wei
+ */
+declare function getGasPrice(rpcUrl: string): Promise<bigint>;
+/**
+ * Fetch chain ID via eth_chainId.
+ *
+ * @param rpcUrl - RPC endpoint
+ * @returns Chain ID as a bigint (supports values beyond Number.MAX_SAFE_INTEGER)
+ */
+declare function getChainId(rpcUrl: string): Promise<bigint>;
+/**
+ * Query the chain's EIP-1559 support status and recent base fee.
+ *
+ * Strategy:
+ * 1. Fetch the latest block to check for baseFeePerGas
+ * 2. If present, the chain supports EIP-1559
+ * 3. If absent, the chain uses legacy gas model
+ *
+ * @param rpcUrl - RPC endpoint
+ * @returns ChainFeeSupport with EIP-1559 support status and data
+ */
+declare function getFeeData(rpcUrl: string): Promise<ChainFeeSupport>;
+/**
+ * Estimate fees for a transaction on the given chain.
+ *
+ * The function follows this fallback strategy:
+ * 1. If a chain-specific estimator is registered, use it
+ * 2. Try EIP-1559 flow (eth_maxPriorityFeePerGas + base fee)
+ * 3. Fall back to legacy gas price
+ * 4. All strategies fail → throw FeeEstimationError
+ *
+ * @param config - Fee estimation configuration
+ * @returns FeeValues (eip1559 | legacy)
+ *
+ * @example
+ * ```ts
+ * const fees = await estimateFees({
+ *   rpcUrl: "https://eth.llamarpc.com",
+ *   chainId: "eip155:1",
+ * });
+ * // => { type: "eip1559", maxFeePerGas: 15000000000n, maxPriorityFeePerGas: 1000000000n }
+ * ```
+ */
+declare function estimateFees(config: FeeEstimationConfig): Promise<FeeValues>;
+
+/**
+ * Configurable Logger
+ *
+ * Replaces raw `console.*` calls across the SDK with a logger that can
+ * be silenced, namespaced, or have custom sinks injected.
+ *
+ * Usage:
+ *   import { logger } from "@naculus/connect-core";
+ *   logger.warn("core/session", "Failed to save", err);
+ *
+ * At app level:
+ *   import { setLogLevel, setLogSink } from "@naculus/connect-core";
+ *   setLogLevel("error");          // suppress debug/info/warn
+ *   setLogSink((level, ns, args) => myLogger(level, ns, args));
+ */
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+/** Set the minimum log level. Messages below this threshold are suppressed. */
+declare function setLogLevel(level: LogLevel): void;
+/** Replace the default console-based sink with a custom handler. */
+declare function setLogSink(sink: ((level: LogLevel, ns: string, ...args: unknown[]) => void) | null): void;
+/** Namespace-bound convenience wrapper returned by `logger.for(ns)`. */
+interface LoggerNamespace {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+declare function createNamespace(ns: string): LoggerNamespace;
+/**
+ * Global logger object.
+ *   logger.warn("my-ns", "message", err);
+ *   const l = logger.for("my-ns"); l.warn("message", err);
+ */
+declare const logger: {
+    debug: (ns: string, ...args: unknown[]) => void;
+    info: (ns: string, ...args: unknown[]) => void;
+    warn: (ns: string, ...args: unknown[]) => void;
+    error: (ns: string, ...args: unknown[]) => void;
+    for: typeof createNamespace;
+    setLogLevel: typeof setLogLevel;
+    setLogSink: typeof setLogSink;
+    /** Current effective level (for tests / introspection). */
+    getLogLevel: () => LogLevel;
+};
+
+/**
+ * Notification type definitions for Push Notification system.
+ *
+ * @see docs/features/push-notification.md
+ */
+/**
+ * Transaction lifecycle status.
+ * Mirrors TxMonitor (SRS-008) status values.
+ */
+type TxStatus = "pending" | "confirmed" | "failed" | "reorg" | "speedup" | "cancel";
+/**
+ * How often to fire notifications for a transaction.
+ *
+ * - `per-tx`: every status change is notified
+ * - `per-confirm`: every N confirmations
+ * - `final-only`: only confirmed or failed (default)
+ * - `muted`: never notify for this tx
+ */
+type NotificationFrequency = "per-tx" | "per-confirm" | "final-only" | "muted";
+/**
+ * The payload delivered to every channel when a notification fires.
+ */
+interface NotificationPayload {
+    /** Unique notification id (uuid) */
+    id: string;
+    /** Target user identifier */
+    userId: string;
+    /** Related transaction hash */
+    txHash: string;
+    /** Chain ID (CAIP-2, e.g. "eip155:1") */
+    chainId: string;
+    /** Human-readable chain name (e.g. "Ethereum Mainnet") */
+    chainName: string;
+    /** Current transaction status */
+    status: TxStatus;
+    /** Short notification title */
+    title: string;
+    /** Notification body text */
+    body: string;
+    /** Transaction value as raw bigint */
+    value?: bigint;
+    /** Formatted value string (e.g. "100 USDC") */
+    valueFormatted?: string;
+    /** USD-equivalent value */
+    valueUsd?: number;
+    /** Actual gas used */
+    gasUsed?: bigint;
+    /** Gas cost in USD */
+    gasCostUsd?: number;
+    /** Block explorer link */
+    explorerUrl?: string;
+    /** Final confirmation count */
+    confirmations?: number;
+    /** Notification creation timestamp (unix ms) */
+    timestamp: number;
+    /** Recipient type (for SenderPay) */
+    recipientType?: "sender" | "merchant";
+}
+/**
+ * Registration for a single transaction's notification lifecycle.
+ * Remains active until the tx reaches a terminal state (confirmed/failed).
+ */
+interface NotificationWatch {
+    /** Transaction hash being watched */
+    txHash: string;
+    /** Target user */
+    userId: string;
+    /** Channel ids that should receive this notification */
+    channels: string[];
+    /** Notification frequency for this watch */
+    frequency: NotificationFrequency;
+    /** Per-confirm interval (only meaningful when frequency is "per-confirm") */
+    confirmInterval?: number;
+    /** Transaction metadata for filtering / mute evaluation */
+    txMetadata: TxMetadata;
+    /** When this watch was created (unix ms) */
+    createdAt: number;
+    /** When the transaction resolved (unix ms, set when terminal status reached) */
+    resolvedAt?: number;
+}
+interface TxMetadata {
+    chainId: string;
+    value?: bigint;
+    to?: string;
+    /** Detected tx type (transfer, swap, approve, custom) */
+    txType: "transfer" | "swap" | "approve" | "custom";
+}
+interface ChannelCapability {
+    supportsRichText: boolean;
+    supportsActionButtons: boolean;
+    supportsMedia: boolean;
+    maxLength: number;
+    isBackground: boolean;
+}
+interface NotificationChannel {
+    readonly id: string;
+    readonly name: string;
+    send(payload: NotificationPayload): Promise<void>;
+    isAvailable(): boolean;
+    getCapabilities(): ChannelCapability;
+    healthCheck(): Promise<boolean>;
+}
+interface UserNotificationPreferences {
+    /** Active channel ids */
+    channels: string[];
+    /** Default notification frequency */
+    frequency: NotificationFrequency;
+    /** Per-confirm interval (default 6) */
+    confirmInterval?: number;
+    /** Pending alert timeout in seconds (default 300 = 5 min) */
+    pendingTimeout?: number;
+    /** Quiet hours configuration */
+    quietHours?: {
+        start: string;
+        end: string;
+        timezone: string;
+    };
+}
+interface MuteRule {
+    id: string;
+    /** Mute all transactions on this chain */
+    chainId?: string;
+    /** Mute specific tx type */
+    txType?: "transfer" | "swap" | "approve" | "custom";
+    /** Suppress notifications below this USD value */
+    minValueUsd?: number;
+    /** Mute a specific contract address */
+    contractAddress?: string;
+    /** Optional expiry timestamp (unix ms). Omit = permanent */
+    until?: number;
+    /** When this rule was created (unix ms) */
+    createdAt: number;
+}
+/**
+ * A notification item displayed in the in-app notification center (React).
+ */
+interface NotificationItem {
+    id: string;
+    title: string;
+    body: string;
+    status: TxStatus;
+    txHash: string;
+    chainName: string;
+    valueFormatted?: string;
+    explorerUrl?: string;
+    timestamp: number;
+    read: boolean;
+}
+interface NotificationSettings {
+    telegram: boolean;
+    webpush: boolean;
+    inapp: boolean;
+    frequency: NotificationFrequency;
+    mutedChains: string[];
+    mutedTypes: string[];
+}
+interface NotifierOptions {
+    /** Default user notification preferences (applied when a userId has no explicit prefs) */
+    defaultPreferences?: Partial<UserNotificationPreferences>;
+    /** Storage adapter for persisting notification history and prefs */
+    storage?: {
+        getItem: <T>(key: string) => Promise<T | null>;
+        setItem: <T>(key: string, value: T) => Promise<void>;
+        removeItem: (key: string) => Promise<void>;
+    };
+    /** Maximum number of in-app history entries to retain (default 200) */
+    maxHistory?: number;
+}
+type TxStatusCallback = (status: TxStatus, payload?: Partial<NotificationPayload>) => void;
+
+/**
+ * Notification Channel Adapters.
+ *
+ * Provides the `NotificationChannel` interface plus built-in adapters:
+ * - `InAppChannel` — in-memory / localStorage-backed notification list
+ * - `TelegramChannel` — adapter stub (actual bot token provided externally)
+ *
+ * @see docs/features/push-notification.md §4.4
+ */
+
+interface InAppChannelOptions {
+    /** Maximum number of history entries kept in storage (default 200) */
+    maxHistory?: number;
+    /** Optional storage for persisting notification history */
+    storage?: {
+        getItem: <T>(key: string) => Promise<T | null>;
+        setItem: <T>(key: string, value: T) => Promise<void>;
+        removeItem: (key: string) => Promise<void>;
+    };
+    /** Callback fired when a new notification arrives (used by React hook) */
+    onNotification?: (item: NotificationItem) => void;
+}
+/**
+ * In-app notification channel.
+ *
+ * Stores notifications in a history buffer and fires a callback for each
+ * new notification so React hooks can stay in sync.
+ */
+declare class InAppChannel implements NotificationChannel {
+    readonly id = "inapp";
+    readonly name = "In-App Toast";
+    private history;
+    private maxHistory;
+    private storage?;
+    onNotification?: (item: NotificationItem) => void;
+    constructor(options?: InAppChannelOptions);
+    getCapabilities(): ChannelCapability;
+    isAvailable(): boolean;
+    healthCheck(): Promise<boolean>;
+    send(payload: NotificationPayload): Promise<void>;
+    /** Returns all in-app notifications (newest last). */
+    getHistory(): NotificationItem[];
+    /** Mark a single notification as read. */
+    markAsRead(id: string): void;
+    /** Mark all notifications as read. */
+    markAllAsRead(): void;
+    /** Clear all in-app notifications. */
+    clear(): void;
+    /** Number of unread notifications. */
+    get unreadCount(): number;
+    private persist;
+    /** Restore persisted history (call on initialization). */
+    restore(): Promise<void>;
+}
+/**
+ * Telegram notification channel.
+ *
+ * This is an adapter stub. The actual bot token is provided at runtime via
+ * the constructor. The `send` method formats the payload into a Telegram
+ * message and sends it through the Telegram Bot API.
+ *
+ * @remarks
+ * Token is accepted but the HTTP call to Telegram's API is left to the
+ * integrator's Telegram infrastructure (e.g., OpenClaw delivery channel).
+ * The `send` implementation here is a placeholder that logs the formatted
+ * message — the real transport should be injected or overridden.
+ */
+declare class TelegramChannel implements NotificationChannel {
+    readonly id = "telegram";
+    readonly name = "Telegram";
+    private botToken;
+    private chatId;
+    private transport?;
+    constructor(config: {
+        botToken: string;
+        chatId: string;
+        /** Optional transport override. Defaults to console.log. */
+        transport?: (payload: NotificationPayload, formatted: string) => Promise<void>;
+    });
+    getCapabilities(): ChannelCapability;
+    isAvailable(): boolean;
+    healthCheck(): Promise<boolean>;
+    send(payload: NotificationPayload): Promise<void>;
+    private formatMessage;
+    private shortenHash;
+    private statusEmoji;
+}
+/**
+ * No-op channel for testing or disabling notifications entirely.
+ */
+declare class NoopChannel implements NotificationChannel {
+    readonly id = "noop";
+    readonly name = "No-op";
+    getCapabilities(): ChannelCapability;
+    isAvailable(): boolean;
+    healthCheck(): Promise<boolean>;
+    send(_payload: NotificationPayload): Promise<void>;
+}
+
+/**
+ * Notifier — Push Notification Core.
+ *
+ * Central orchestrator for transaction lifecycle push notifications.
+ * Manages watch registrations, channel adapters, user preferences,
+ * mute rules, and event-driven status dispatch.
+ *
+ * @see docs/features/push-notification.md
+ */
+
+declare class Notifier {
+    private channels;
+    private watches;
+    private preferences;
+    private muteRules;
+    private statusCallbacks;
+    private defaultPreferences;
+    private storage?;
+    constructor(options?: NotifierOptions);
+    registerChannel(channel: NotificationChannel): void;
+    unregisterChannel(channelId: string): void;
+    getChannel(channelId: string): NotificationChannel | undefined;
+    getActiveChannels(): string[];
+    /**
+     * Start watching a transaction for notifications.
+     *
+     * When the tx status changes, notifications will be dispatched
+     * to all registered channels based on the watch configuration
+     * and the user's preferences + mute rules.
+     */
+    watchTx(hash: string, chainId: string, options?: {
+        userId?: string;
+        channels?: string[];
+        frequency?: NotificationFrequency;
+        txMetadata?: Partial<TxMetadata>;
+    }): void;
+    /**
+     * Stop watching a transaction.
+     */
+    unregisterTxWatch(hash: string): void;
+    getWatch(hash: string): NotificationWatch | undefined;
+    getAllWatches(): NotificationWatch[];
+    /**
+     * Subscribe to status changes for a specific transaction.
+     *
+     * Returns an unsubscribe function.
+     */
+    onTxStatus(hash: string, callback: TxStatusCallback): () => void;
+    /**
+     * Called when a transaction's status changes.
+     *
+     * This is the main entry point from TxMonitor integration.
+     * It evaluates mute rules, determines whether to fire based on
+     * the frequency preference, and dispatches to all channels.
+     */
+    handleTxStatus(hash: string, status: TxStatus, receipt?: {
+        confirmations?: number;
+        value?: bigint;
+        gasUsed?: bigint;
+        gasCostUsd?: number;
+    }): Promise<void>;
+    /**
+     * Send a notification directly (bypasses watch and frequency checks).
+     */
+    notify(payload: Omit<NotificationPayload, "id" | "timestamp">, channels?: string[]): Promise<void>;
+    setPreferences(userId: string, prefs: Partial<UserNotificationPreferences>): void;
+    getPreferences(userId: string): UserNotificationPreferences;
+    getDefaultPreferences(): UserNotificationPreferences;
+    addMuteRule(userId: string, rule: MuteRule): void;
+    removeMuteRule(userId: string, ruleId: string): void;
+    getMuteRules(userId: string): MuteRule[];
+    /**
+     * Evaluate whether a transaction should be muted based on active rules.
+     */
+    isMuted(metadata: TxMetadata, rules: MuteRule[]): boolean;
+    /** Restore persisted state (call on initialization). */
+    restore(): Promise<void>;
+    private persistPreferences;
+    private persistWatches;
+    private persistMuteRules;
+    private shouldNotify;
+    private buildPayload;
+    private dispatchToChannels;
+}
+
+interface WalletPermission {
+    parentCapability: string;
+    invoker: string;
+    date?: number;
+    caveats?: {
+        type: string;
+        value: unknown;
+    }[];
+}
+interface PermissionsRequest {
+    eth_accounts: Record<string, never>;
+}
+declare function getPermissions(provider: {
+    request: (args: {
+        method: string;
+        params?: unknown[];
+    }) => Promise<unknown>;
+}): Promise<WalletPermission[] | null>;
+declare function requestPermissions(provider: {
+    request: (args: {
+        method: string;
+        params?: unknown[];
+    }) => Promise<unknown>;
+}): Promise<WalletPermission[]>;
+declare function extractAccountsFromPermissions(permissions: WalletPermission[]): string[];
+declare function hasPermission(permissions: WalletPermission[] | null, capability: string): boolean;
+
+type Platform = "desktop-web" | "mobile-web" | "in-app-browser";
+declare function detectPlatform(): Platform;
+declare function isMobileBrowser(): boolean;
+
+/**
+ * Result of a forward name resolution (name → address).
+ */
+interface AddressResult {
+    /** Resolved address (without CAIP-10 prefix). */
+    address: string;
+    /** Chain type that this address belongs to. */
+    chainType: "eip155" | "solana" | "xrpl";
+    /** The original name that was resolved. */
+    name: string;
+    /** Optional chain ID (CAIP-2 format) that the name was resolved on. */
+    chainId?: string;
+}
+/**
+ * Result of a reverse lookup (address → name).
+ */
+interface NameResult {
+    /** Resolved name (e.g. "vitalik.eth", "vitalik.sol"). */
+    name: string;
+    /** Chain type that this name belongs to. */
+    chainType: "eip155" | "solana" | "xrpl";
+    /** Whether the result is a primary / canonical name. */
+    isPrimary: boolean;
+}
+/**
+ * Provider interface for a specific name service (ENS, SNS, etc.).
+ */
+interface ResolverProvider {
+    /** The chain type this provider handles. */
+    chainType: "eip155" | "solana" | "xrpl";
+    /** Resolve a name to an address. Returns null if name is not found. */
+    resolveName(name: string): Promise<AddressResult | null>;
+    /** Reverse-lookup an address to a name. Returns null if no name is found. */
+    lookupAddress(address: string): Promise<NameResult | null>;
+    /** Check if this provider can handle a given name (by suffix or format). */
+    supportsName(name: string): boolean;
+}
+/**
+ * Error codes for name resolution failures.
+ */
+type ResolutionErrorCode = "NAME_NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "UNSUPPORTED_NAME_SERVICE" | "RESOLUTION_TIMEOUT" | "INVALID_NAME" | "INVALID_ADDRESS";
+/**
+ * Error class for name resolution failures.
+ */
+declare class ResolutionError extends Error {
+    readonly code: ResolutionErrorCode;
+    constructor(code: ResolutionErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Configuration for the name resolver.
+ */
+interface NameResolverConfig {
+    providers?: {
+        ens?: {
+            rpcUrl: string;
+        };
+        sns?: {
+            rpcUrl: string;
+        };
+    };
+    cache?: {
+        /** TTL in milliseconds (default: 5 minutes). */
+        ttlMs: number;
+    };
+    /** Default timeout for resolution requests in ms. */
+    timeoutMs?: number;
+}
+/**
+ * Simple in-memory cache with TTL.
+ */
+declare class ResolverCache {
+    private cache;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    clear(): void;
+    /** Remove stale entries. */
+    prune(): void;
+}
+
+/**
+ * Unified name resolution service for ENS / SNS / future name systems.
+ *
+ * Features:
+ * - Auto-detection of name service by suffix (.eth → ENS, .sol → SNS)
+ * - Forward resolution: name → address
+ * - Reverse lookup: address → name
+ * - In-memory caching with configurable TTL
+ * - Timeout support
+ * - Minimal dependencies (plain fetch, no ethers/web3)
+ */
+declare class NameResolver {
+    private readonly providers;
+    private readonly cache;
+    private readonly timeoutMs;
+    constructor(config?: NameResolverConfig);
+    /**
+     * Register a custom name resolution provider.
+     */
+    registerProvider(provider: ResolverProvider): void;
+    /**
+     * Resolve a human-readable name to a blockchain address.
+     *
+     * @param name - The name to resolve (e.g. "vitalik.eth", "jupiter.sol").
+     * @returns AddressResult with the resolved address, or null if not found.
+     * @throws ResolutionError on provider errors, timeout, or unsupported names.
+     */
+    resolveName(name: string): Promise<AddressResult | null>;
+    /**
+     * Reverse-lookup a blockchain address to find its human-readable name.
+     *
+     * @param address - The blockchain address to look up.
+     * @param chainId - Optional CAIP-2 chain ID to hint which provider to use.
+     * @returns NameResult with the resolved name, or null if not found.
+     */
+    lookupAddress(address: string, chainId?: string): Promise<NameResult | null>;
+    /**
+     * Resolve multiple names in a single batch call.
+     * Merges requests by provider to minimize RPC calls.
+     *
+     * @param names - Array of names to resolve.
+     * @returns Map of name to AddressResult (or null if not found).
+     */
+    resolveNames(names: string[]): Promise<Map<string, AddressResult | null>>;
+    /**
+     * Clear the resolution cache.
+     */
+    clearCache(): void;
+    private findProviderForName;
+    private detectChainType;
+    private withTimeout;
+}
+
+/**
+ * ENS name resolution provider.
+ *
+ * Resolves `.eth` names via direct eth_call to ENS contracts.
+ * Does NOT depend on ethers.js or web3.js — uses plain fetch + minimal
+ * ABI encoding.
+ */
+declare class ENSProvider implements ResolverProvider {
+    readonly chainType: "eip155";
+    private readonly rpcUrl;
+    constructor(rpcUrl: string);
+    supportsName(name: string): boolean;
+    resolveName(name: string): Promise<AddressResult | null>;
+    lookupAddress(address: string): Promise<NameResult | null>;
+    private getResolver;
+}
+
+/**
+ * SNS (Solana Name Service) provider.
+ *
+ * Resolves `.sol` names via Solana RPC, querying the Bonfida SNS program.
+ * Uses plain fetch + @noble/hashes — no @solana/web3.js dependency.
+ */
+declare class SNSProvider implements ResolverProvider {
+    readonly chainType: "solana";
+    private readonly rpcUrl;
+    constructor(rpcUrl: string);
+    supportsName(name: string): boolean;
+    resolveName(name: string): Promise<AddressResult | null>;
+    lookupAddress(address: string): Promise<NameResult | null>;
+    /**
+     * Convert a hex string to a Base58 Solana address.
+     */
+    private hexToBase58;
+}
+
+/**
+ * RouteEngine Types
+ *
+ * Core type definitions for the cross-chain routing engine with
+ * provider-agnostic swap and bridge providers.
+ *
+ * @see docs/features/routes.md
+ */
+interface Token {
+    chainId: number;
+    address: string;
+    decimals: number;
+    symbol: string;
+}
+interface ChainInfo {
+    chainId: number;
+    name: string;
+}
+
+declare const DEFAULT_RPC_URLS: Record<string, string>;
+/**
+ * Get the default RPC URL for a given CAIP-2 chainId.
+ * Returns undefined if no default is configured.
+ */
+declare function getRpcUrl(chainId: string, fallback?: string): string | undefined;
+
+/**
+ * Session Key Error Codes
+ */
+
+type SessionKeyErrorCode = "session_key_not_found" | "session_key_expired" | "session_key_revoked" | "session_key_scope_exceeded" | "session_key_method_forbidden" | "session_key_contract_not_allowed" | "session_key_chain_not_allowed" | "session_key_storage_unavailable" | "session_key_encryption_failed" | "session_key_required_fields_missing" | "session_key_max_tx_count_exceeded" | "session_key_value_limit_exceeded" | "session_key_gas_limit_exceeded";
+declare const SESSION_KEY_ERROR_MESSAGES: Record<SessionKeyErrorCode, string>;
+/**
+ * Create a WalletError with a session-key-specific error code.
+ */
+declare function createSessionKeyError(code: SessionKeyErrorCode, details?: unknown): WalletError;
+
+/**
+ * Storage Adapter Interface
+ *
+ * Defines the contract for session storage implementations.
+ * Allows custom storage backends (localStorage, sessionStorage, IndexedDB, etc.)
+ */
+declare class StorageError extends Error {
+    code: "quota_exceeded" | "not_available" | "parse_error" | "unknown";
+    constructor(message: string, code?: "quota_exceeded" | "not_available" | "parse_error" | "unknown", cause?: unknown);
+}
+interface StorageAdapter {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    isAvailable(): boolean;
+}
+declare class LocalStorageAdapter implements StorageAdapter {
+    private prefix;
+    private _available;
+    constructor(prefix?: string);
+    private getKey;
+    private getStorage;
+    isAvailable(): boolean;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+declare class SessionStorageAdapter implements StorageAdapter {
+    private prefix;
+    private _available;
+    constructor(prefix?: string);
+    private getKey;
+    isAvailable(): boolean;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+declare class MemoryStorageAdapter implements StorageAdapter {
+    private store;
+    isAvailable(): boolean;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+declare class NoopStorageAdapter implements StorageAdapter {
+    isAvailable(): boolean;
+    get<T>(_key: string): Promise<T | null>;
+    set<T>(_key: string, _value: T): Promise<void>;
+    remove(_key: string): Promise<void>;
+    clear(): Promise<void>;
+    has(_key: string): Promise<boolean>;
+}
+declare function createStorageAdapter(type: "local" | "session" | "memory" | "none", prefix?: string): StorageAdapter;
+
+/**
+ * Session Keys / Ephemeral Keys — Type Definitions
+ *
+ * Defines the core types for session key creation, storage,
+ * authorization, and scope-based transaction control.
+ *
+ * @see docs/features/session-keys.md
+ */
+/**
+ * Defines the permitted scope for a session key.
+ *
+ * All numeric limits are best-effort enforced client-side.
+ * For on-chain enforcement, use EIP-7702 or AA module delegation.
+ */
+interface SessionKeyScope {
+    /** Unix timestamp (seconds) after which the key expires */
+    expiry: number;
+    /** Maximum total gas across all transactions (wei) */
+    maxTotalGas?: bigint;
+    /** Maximum gas per single transaction (wei) */
+    maxGasPerTx?: bigint;
+    /** Maximum total value of assets transferred (wei / token base units) */
+    maxTotalValue?: bigint;
+    /** Maximum value per single transaction */
+    maxValuePerTx?: bigint;
+    /** Maximum number of transactions this key can sign */
+    maxTxCount?: number;
+    /** Allowed target contract addresses (empty = any contract) */
+    allowedContracts?: `0x${string}`[];
+    /** Allowed method selectors (4-byte hex, empty = any method) */
+    allowedMethods?: string[];
+    /** Per-token allowances: token address → max amount in token base units */
+    tokenAllowances?: Record<`0x${string}`, bigint>;
+    /** Chain IDs this key is valid for (empty = any chain) */
+    allowedChainIds?: number[];
+    /** Session type: off-chain agreement, EIP-7702 delegation, or AA module */
+    mode: "offchain" | "eip7702" | "aa_module";
+}
+/** A secp256k1 key pair (private key NEVER persisted unencrypted) */
+interface SessionKeyPair {
+    publicKey: `0x${string}`;
+    privateKey: `0x${string}`;
+}
+/** Encrypted session key data for local storage */
+interface EncryptedKeyPair {
+    publicKey: `0x${string}`;
+    encryptedPrivateKey: string;
+    iv: string;
+    salt: string;
+}
+/** Authorization signature from the main wallet */
+interface SignedAuthorization {
+    /** EIP-7702 authorization bytes (if mode === "eip7702") */
+    authorization?: `0x${string}`;
+    /** Off-chain signature of scope hash (if mode === "offchain") */
+    rawSignature?: `0x${string}`;
+    /** Main wallet address that signed this authorization */
+    signerAddress: `0x${string}`;
+    /** Authorization type */
+    type: "eip7702" | "offchain" | "aa_module";
+}
+/** Full session key record stored locally (private key encrypted) */
+interface StoredSessionKey {
+    /** Unique session key ID (UUID v4) */
+    id: string;
+    /** Encrypted key pair for secure persistence */
+    keyPair: EncryptedKeyPair;
+    /** Authorized scope */
+    scope: SessionKeyScope;
+    /** Main wallet's authorization signature */
+    authorization: SignedAuthorization;
+    /** Current status */
+    status: SessionKeyStatus;
+    /** Creation timestamp (Unix ms) */
+    createdAt: number;
+    /** Last usage timestamp (Unix ms) */
+    lastUsedAt: number;
+    /** Number of transactions signed with this key */
+    useCount: number;
+}
+/** Session key public info — safe to expose to UI */
+interface SessionKeyInfo {
+    id: string;
+    publicKey: `0x${string}`;
+    scope: SessionKeyScope;
+    status: SessionKeyStatus;
+    createdAt: number;
+    expiresAt: number;
+    useCount: number;
+    signerAddress: `0x${string}`;
+}
+type SessionKeyStatus = "active" | "revoked" | "expired";
+/** Decrypted session key ready for signing (memory only) */
+interface SessionKeyBundle {
+    id: string;
+    privateKey: `0x${string}`;
+    scope: SessionKeyScope;
+    authorization: SignedAuthorization;
+    /** The main wallet address that authorized this session */
+    signerAddress: `0x${string}`;
+}
+interface ScopeCheckResult {
+    valid: boolean;
+    reason?: string;
+    remainingGas?: bigint;
+    remainingValue?: bigint;
+    remainingTxCount?: number;
+}
+interface SessionKeyManagerConfig {
+    /** Storage key prefix (default: "naculus_session_keys") */
+    storagePrefix?: string;
+    /** Default max total value for new session keys (wei, default: 0.1 ETH) */
+    defaultMaxTotalValue?: bigint;
+    /** Default max transactions per key (default: 50) */
+    defaultMaxTxCount?: number;
+    /** Default max session duration in ms (default: 24h) */
+    defaultExpiryMs?: number;
+    /** Whether to require allowedContracts (default: true) */
+    requireAllowedContracts?: boolean;
+    /** Forbidden method selectors (default: approve, permit) */
+    forbiddenMethods?: string[];
+    /** Key derivation salt for encryption (auto-generated if not provided) */
+    encryptionSalt?: string;
+    /** Password-derived encryption key (hex string). If not provided, a random one is generated on first use. */
+    encryptionKey?: string;
+    /**
+     * PBKDF2 iteration count for key derivation.
+     * Default: 600_000 (OWASP recommended for AES-256 in 2025).
+     * Set lower (e.g. 1000) for testing to avoid timeout.
+     */
+    pbkdf2Iterations?: number;
+}
+declare const DEFAULT_SESSION_KEY_CONFIG: Required<SessionKeyManagerConfig>;
+
+/**
+ * SessionKeyManager
+ *
+ * Manages ephemeral session keys for automated transaction signing
+ * without wallet popups. Session keys are:
+ *
+ * - Short-lived (configurable expiry, default 24h)
+ * - Scoped (limits on value, gas, contracts, methods, chain)
+ * - Revocable (local revoke instantly invalidates)
+ * - Encrypted at rest (AES-256-CTR-HMAC via @noble/hashes)
+ *
+ * Uses standard secp256k1 key pairs generated client-side.
+ * Private keys are encrypted before storage and decrypted only in memory.
+ *
+ * @see docs/features/session-keys.md
+ */
+
+declare class SessionKeyManager {
+    private config;
+    private storage;
+    private encryptionPassword;
+    private activeBundle;
+    private cache;
+    constructor(config?: SessionKeyManagerConfig, storageAdapter?: StorageAdapter);
+    /**
+     * Check whether the storage backend is available.
+     */
+    isStorageAvailable(): boolean;
+    /**
+     * Create a new session key (secp256k1 keypair).
+     *
+     * Generates a fresh key pair, encrypts the private key,
+     * persists to storage, and returns public session info.
+     *
+     * @param scope - Optional scope overrides. Missing fields use defaults.
+     * @param signerAddress - The main wallet address that authorizes this session
+     * @returns Public session key info (no private key exposed)
+     */
+    createSessionKey(scope?: Partial<SessionKeyScope>, signerAddress?: `0x${string}`): Promise<SessionKeyInfo>;
+    /**
+     * List all session keys (active, revoked, or expired).
+     * Automatically marks expired keys.
+     */
+    listSessions(): Promise<SessionKeyInfo[]>;
+    /**
+     * List only active session keys.
+     */
+    listActiveSessions(): Promise<SessionKeyInfo[]>;
+    /**
+     * Revoke a session key by ID.
+     * Sets status to "revoked" and invalidates the cached bundle.
+     */
+    revokeSession(sessionId: string): Promise<void>;
+    /**
+     * Get a decrypted session key bundle for transaction signing.
+     * Validates expiry and status before returning.
+     *
+     * @param sessionId - The session key ID
+     * @returns Decrypted SessionKeyBundle or throws
+     */
+    getSessionBundle(sessionId: string): Promise<SessionKeyBundle>;
+    /**
+     * Sign a raw message hash using a session key.
+     * Validates scope, increments usage counter, and returns the signature.
+     *
+     * @param sessionId - The session key ID
+     * @param messageHash - The 32-byte message hash to sign (0x-prefixed hex)
+     * @returns secp256k1 signature as hex
+     */
+    signWithSessionKey(sessionId: string, messageHash: `0x${string}`): Promise<`0x${string}`>;
+    /**
+     * Check whether a session key's scope allows a given transaction.
+     * Updates usage tracking before returning.
+     */
+    checkSessionScope(sessionId: string, tx: {
+        to?: string;
+        value?: string;
+        data?: string;
+        chainId?: number;
+        gas?: string;
+    }): Promise<ScopeCheckResult>;
+    /**
+     * Attach a signed authorization (e.g., EIP-7702 or off-chain signature)
+     * to an existing session key.
+     */
+    setAuthorization(sessionId: string, authorization: SignedAuthorization): Promise<void>;
+    /**
+     * Remove all session keys from storage.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Resolve the final scope by merging user-provided overrides with defaults.
+     */
+    private resolveScope;
+    /**
+     * Validate that a session key is active and not expired.
+     */
+    private validateSessionStatus;
+    /**
+     * Check whether a transaction falls within the session key's scope.
+     */
+    private checkScopeAgainstTx;
+    /**
+     * Reload the cache from storage, auto-marking expired keys.
+     */
+    private refreshCache;
+    /**
+     * Convert a StoredSessionKey to a public SessionKeyInfo.
+     */
+    private toSessionKeyInfo;
+}
+
+/**
+ * Session Key Secure Storage
+ *
+ * Provides AES-256-GCM encryption for session key private keys
+ * using a password-derived key (PBKDF2) for storage.
+ *
+ * Supports:
+ * - LocalStorageAdapter (from core/storage.ts)
+ * - MemoryStorageAdapter (for testing / SSR)
+ * - IndexedDB-backed storage (browser-native, non-blocking)
+ *
+ * Private keys are NEVER stored in plaintext — always encrypted
+ * before persisting, and decrypted only in memory during signing.
+ *
+ * @see docs/features/session-keys.md §6
+ */
+
+/**
+ * Encrypt a private key hex string for secure storage.
+ *
+ * @param privateKeyHex - The raw private key as a 0x-prefixed hex string
+ * @param password - Derivation password (e.g. wallet seed hash or user-provided)
+ * @param salt - Optional salt override (provided for decryption consistency)
+ * @returns EncryptedKeyPair with ciphertext, IV, and salt
+ */
+declare function encryptPrivateKey(privateKeyHex: `0x${string}`, password: string, salt?: Uint8Array, iterations?: number, publicKeyHex?: `0x${string}`): EncryptedKeyPair;
+/**
+ * Decrypt an encrypted private key for in-memory signing.
+ *
+ * @param encrypted - EncryptedKeyPair from storage
+ * @param password - The same password used during encryption
+ * @param iterations - Must match the value used during encryption
+ * @returns The raw private key as a 0x-prefixed hex string
+ */
+declare function decryptPrivateKey(encrypted: EncryptedKeyPair, password: string, iterations?: number): `0x${string}`;
+/**
+ * Manages persistence of StoredSessionKey records to a StorageAdapter.
+ * All private keys are already encrypted before reaching this layer.
+ */
+declare class SessionKeyStorage {
+    private adapter;
+    constructor(adapter?: StorageAdapter);
+    /**
+     * Check if the storage backend is available.
+     */
+    isAvailable(): boolean;
+    /**
+     * Load all stored session keys with BigInt revival.
+     */
+    loadAll(): Promise<StoredSessionKey[]>;
+    /**
+     * Persist an array of session keys with BigInt serialization.
+     */
+    private persistAll;
+    /**
+     * Save a single session key (adds or updates).
+     */
+    save(key: StoredSessionKey): Promise<void>;
+    /**
+     * Retrieve a single session key by ID.
+     */
+    get(id: string): Promise<StoredSessionKey | null>;
+    /**
+     * Remove a single session key by ID.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Update the status of a session key (active → revoked / expired).
+     */
+    updateStatus(id: string, status: StoredSessionKey["status"]): Promise<void>;
+    /**
+     * Increment the usage counter for a session key.
+     */
+    incrementUsage(id: string): Promise<void>;
+    /**
+     * Remove all session keys.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Session-Manager-Specific Error Codes
+ *
+ * Extends WalletError with session-specific error codes.
+ *
+ * @see SRS-009 §8
+ */
+
+type SessionErrorCode = "no_active_session" | "chain_switch_rejected" | "chain_unsupported" | "fee_rpc_error" | "method_unsupported" | "invalid_chain";
+declare const SESSION_ERROR_MESSAGES: Record<SessionErrorCode, string>;
+/**
+ * Create a WalletError with session-manager-specific error code.
+ */
+declare function createSessionError(code: SessionErrorCode, details?: unknown): WalletError;
+
+/**
+ * Chain Session Model for Multi-Chain Session Management
+ *
+ * @see SRS-009 §3
+ */
+
+/**
+ * Chain-specific session data.
+ *
+ * Defines the state of a session on one specific chain.
+ * A single UniversalWalletSession can contain multiple ChainSessions
+ * across different namespaces (e.g., EVM + Solana).
+ */
+interface ChainSession {
+    /** Chain ID in CAIP-2 format (e.g., "eip155:1", "solana:0") */
+    chainId: string;
+    /** The connector instance ID that manages this chain */
+    connectorId: string;
+    /** RPC endpoint for this chain */
+    rpcUrl: string;
+    /** Native currency metadata */
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    /** Block explorer URL (optional) */
+    blockExplorer?: string;
+    /** Last known fee values (cached) */
+    lastKnownFees?: FeeValues;
+    /** Timestamp of last successful fee estimation */
+    lastFeeUpdatedAt?: string;
+}
+/**
+ * Active session bundle: wraps a UniversalWalletSession with
+ * its constituent ChainSessions for multi-chain visibility.
+ */
+interface ActiveSessionBundle {
+    /** The persistent UniversalWalletSession */
+    walletSession: UniversalWalletSession;
+    /** Chain-specific sessions derived from namespaces */
+    chainSessions: Map<string, ChainSession>;
+    /** The currently "active" chain ID (the chain being transacted on) */
+    activeChainId: string;
+    /** When this session was last used */
+    lastActiveAt: string;
+}
+/**
+ * Serialized format for session persistence.
+ * Map is serialized as Record for JSON compatibility.
+ */
+interface PersistedSessionData {
+    walletSession: UniversalWalletSession;
+    lastActiveChainId: string;
+    chainSessions: Record<string, ChainSession>;
+    lastConnectedAt: string;
+}
+/**
+ * User-configured fee overrides, preserved across chain switches.
+ * Keyed by CAIP-2 chainId.
+ */
+interface UserFeeOverrides {
+    [chainId: string]: {
+        type?: "eip1559" | "legacy";
+        maxPriorityFeePerGas?: bigint;
+        baseFeeMultiplier?: bigint;
+    };
+}
+interface SessionManagerConfig {
+    /** Default RPC URLs keyed by chainId */
+    defaultRpcUrls?: Record<string, string>;
+    /** Default native currency metadata keyed by chainId */
+    defaultCurrencies?: Record<string, {
+        name: string;
+        symbol: string;
+        decimals: number;
+    }>;
+    /** Default block explorers keyed by chainId */
+    defaultExplorers?: Record<string, string>;
+    /** Whether to auto-refresh fee estimation on chain switch (default: true) */
+    autoRefreshFeeOnSwitch?: boolean;
+    /** Maximum active session bundles (default: 10) */
+    maxActiveSessions?: number;
+    /** Optional AES-GCM encryption key for session persistence */
+    encryptionKey?: string;
+}
+interface RefreshFeesOptions {
+    force?: boolean;
+    userOverrides?: Partial<FeeEstimationConfig>;
+}
+/**
+ * Parse a CAIP-2 chain ID into namespace and reference parts.
+ * e.g., "eip155:1" → { namespace: "eip155", reference: "1" }
+ * e.g., "solana:0" → { namespace: "solana", reference: "0" }
+ */
+declare function parseChainId(chainId: string): {
+    namespace: string;
+    reference: string;
+};
+/**
+ * Validate a CAIP-2 chain ID format.
+ * Supported namespaces: eip155, solana, xrpl
+ */
+declare function validateChainId(chainId: string): void;
+
+/**
+ * Event system for SessionManager
+ *
+ * Provides a typed event emitter that dispatches session lifecycle events
+ * for consumption by React hooks and UI layers.
+ *
+ * @see SRS-009 §7
+ */
+
+type SessionEvent = "sessionConnected" | "sessionDisconnected" | "chainChanged" | "chainSessionAdded" | "chainSessionRemoved" | "feesUpdated" | "accountsChanged";
+interface SessionEventPayloads {
+    sessionConnected: {
+        bundle: ActiveSessionBundle;
+    };
+    sessionDisconnected: {
+        connectorId: string;
+        topic?: string;
+    };
+    chainChanged: {
+        bundle: ActiveSessionBundle;
+        previousChainId: string;
+        newChainId: string;
+    };
+    chainSessionAdded: {
+        bundle: ActiveSessionBundle;
+        chainSession: ChainSession;
+    };
+    chainSessionRemoved: {
+        bundle: ActiveSessionBundle;
+        chainId: string;
+    };
+    feesUpdated: {
+        chainId: string;
+        fees: FeeValues;
+    };
+    accountsChanged: {
+        bundle: ActiveSessionBundle;
+        accounts: string[];
+    };
+}
+type SessionEventHandler<E extends SessionEvent = SessionEvent> = (payload: SessionEventPayloads[E]) => void;
+declare class SessionEventEmitter {
+    private listeners;
+    /**
+     * Register an event handler.
+     */
+    on<E extends SessionEvent>(event: E, handler: SessionEventHandler<E>): void;
+    /**
+     * Remove a previously registered event handler.
+     */
+    off<E extends SessionEvent>(event: E, handler: SessionEventHandler<E>): void;
+    /**
+     * Remove all handlers for a specific event.
+     */
+    removeAllListeners(event?: SessionEvent): void;
+    /**
+     * Emit an event to all registered handlers.
+     * Errors in handlers are caught and logged to prevent cascading failures.
+     */
+    protected emit<E extends SessionEvent>(event: E, payload: SessionEventPayloads[E]): void;
+}
+
+/**
+ * Session Persistence
+ *
+ * Extends LocalStorageSessionStorage to persist ChainSession data
+ * alongside the wallet session, enabling multi-chain state recovery
+ * across page reloads.
+ *
+ * @see SRS-009 §9
+ */
+
+declare class SessionPersistence {
+    private adapter;
+    private key;
+    /**
+     * @param key - Storage key for the persisted data.
+     * @param adapter - Optional custom storage adapter. Defaults to LocalStorageAdapter.
+     */
+    constructor(key?: string, adapter?: StorageAdapter);
+    /**
+     * Return whether the backing storage is available.
+     */
+    isAvailable(): boolean;
+    /**
+     * Load the persisted session data.
+     * Returns null if no data is found or parsing fails.
+     */
+    load(): Promise<PersistedSessionData | null>;
+    /**
+     * Save session data to persistent storage.
+     */
+    save(data: PersistedSessionData): Promise<void>;
+    /**
+     * Clear persisted session data.
+     */
+    clear(): Promise<void>;
+    /**
+     * Serialize an ActiveSessionBundle to PersistedSessionData.
+     * Converts the Map to a Record for JSON compatibility.
+     */
+    serializeBundle(bundle: ActiveSessionBundle): PersistedSessionData;
+    /**
+     * Deserialize PersistedSessionData back to a bundle structure.
+     * Returns null if the wallet session has expired.
+     */
+    deserializeToBundle(data: PersistedSessionData): ActiveSessionBundle | null;
+}
+/**
+ * Create a SessionPersistence instance.
+ */
+declare function createSessionPersistence(key?: string, adapter?: StorageAdapter): SessionPersistence;
+
+/**
+ * SessionManager
+ *
+ * Unified multi-chain session management system.
+ * Wraps ConnectorManager to add chain-aware session lifecycle,
+ * fee estimation sync, event emission, and persistence.
+ *
+ * @see SRS-009 §3-6
+ */
+
+declare class SessionManager extends SessionEventEmitter {
+    private connectorManager;
+    private bundles;
+    private activeBundleId;
+    private userFeeOverrides;
+    private config;
+    private persistence;
+    constructor(connectorManager: ConnectorManager, config?: SessionManagerConfig);
+    /**
+     * Connect to a wallet on a specific chain.
+     * Delegates to the connector's connect method and wraps the result
+     * in an ActiveSessionBundle.
+     */
+    connect(walletType: string, chainId: string, input?: unknown): Promise<ActiveSessionBundle>;
+    /**
+     * Switch the active chain for the current session.
+     * Delegates to the appropriate connector's switchChain method.
+     * After successful switch, auto-refreshes fee estimation.
+     */
+    switchChain(chainId: string): Promise<void>;
+    /**
+     * Disconnect the active session.
+     * Cleans up all chain sessions and clears storage.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Disconnect a specific chain session within the active bundle.
+     * Does not disconnect the entire wallet.
+     */
+    disconnectChain(chainId: string): Promise<void>;
+    /**
+     * Get the active chain session.
+     */
+    getActiveChainSession(): ChainSession | undefined;
+    /**
+     * Get all active chain sessions across all connected bundles.
+     */
+    getAllChainSessions(): ChainSession[];
+    /**
+     * Get all active session bundles.
+     */
+    getAllActiveSessions(): ActiveSessionBundle[];
+    /**
+     * Get the currently active session bundle.
+     */
+    getActiveBundle(): ActiveSessionBundle | null;
+    /**
+     * Refresh fee estimation for a specific chain.
+     * Called automatically on switchChain if autoRefreshFeeOnSwitch is enabled.
+     */
+    refreshFees(chainId?: string, options?: RefreshFeesOptions): Promise<FeeValues | null>;
+    /**
+     * Set user fee overrides for a specific chain.
+     * Overrides are preserved across chain switches.
+     */
+    setUserFeeOverrides(chainId: string, overrides: Partial<UserFeeOverrides[string]>): void;
+    /**
+     * Get the current user fee overrides for a specific chain.
+     */
+    getUserFeeOverrides(chainId: string): UserFeeOverrides[string] | undefined;
+    /**
+     * Clear user fee overrides for a specific chain.
+     */
+    clearUserFeeOverrides(chainId?: string): void;
+    /**
+     * Attempt to restore a session from persistence.
+     * Returns true if a session was restored, false otherwise.
+     */
+    restoreFromPersistence(): Promise<boolean>;
+    on<E extends SessionEvent>(event: E, handler: SessionEventHandler<E>): void;
+    off<E extends SessionEvent>(event: E, handler: SessionEventHandler<E>): void;
+    /**
+     * Build a bundle from a wallet session, marking the given chain as active.
+     */
+    private buildBundle;
+    /**
+     * Create a ChainSession for the given chain ID.
+     * Resolves RPC URL, native currency, and block explorer from config
+     * or defaults.
+     */
+    private createChainSession;
+    /**
+     * Update the UniversalWalletSession namespaces to reflect
+     * the current active chain.
+     */
+    private updateSessionNamespace;
+    /**
+     * Resolve the appropriate connector for a given wallet session.
+     */
+    private resolveConnector;
+    /**
+     * Get a unique bundle ID from a wallet session.
+     */
+    private getBundleId;
+    /**
+     * Persist the active bundle to storage.
+     */
+    private persistBundle;
+}
+/**
+ * Create a SessionManager instance.
+ */
+declare function createSessionManager(connectorManager: ConnectorManager, config?: SessionManagerConfig): SessionManager;
+
+/**
+ * Transaction Simulation — Core Type Definitions
+ *
+ * Defines the shapes for:
+ * - SimulationResult: what a simulation yields
+ * - BalanceChange / ApprovalChange: predicted state changes
+ * - RiskAssessment / RiskWarning: security scoring
+ * - GasInfo: fee estimation from simulation
+ * - TransactionRequest: minimal tx descriptor for simulation
+ *
+ * @see /docs/features/transaction-simulation.md
+ */
+type SimulationProviderName = "eth_call" | "blowfish" | "tenderly" | "auto";
+type SimulationStatus = "success" | "reverted" | "unavailable";
+interface SimulationResult {
+    /** Whether the simulation completed, reverted, or was unavailable */
+    status: SimulationStatus;
+    /** Revert reason (when status === "reverted") */
+    revertReason?: string;
+    /** Predicted balance changes from the simulation */
+    balanceChanges: BalanceChange[];
+    /** Predicted approval changes from the simulation */
+    approvalChanges: ApprovalChange[];
+    /** Risk assessment of the simulated transaction */
+    riskAssessment: RiskAssessment;
+    /** Gas estimation details */
+    gasInfo?: GasInfo;
+    /** Which provider produced this result */
+    provider: SimulationProviderName;
+    /** Human-readable summary of the simulation */
+    summary?: string;
+    /** Whether the simulation detected any state changes */
+    changesDetected: boolean;
+    /** Raw provider response (for debugging / transparency) */
+    raw?: unknown;
+}
+interface BalanceChange {
+    /** Token contract address (zero address for native gas token) */
+    tokenAddress: `0x${string}`;
+    /** Token symbol (e.g. "USDC", "ETH") */
+    tokenSymbol: string;
+    /** Number of decimals for display */
+    tokenDecimals: number;
+    /** Raw change amount in smallest unit (stringified bigint) */
+    amount: string;
+    /** Direction of the balance change */
+    direction: "in" | "out";
+    /** Source address */
+    from: `0x${string}`;
+    /** Destination address */
+    to: `0x${string}`;
+    /** Human-readable representation (e.g. "-1.5 USDC") */
+    humanReadable: string;
+}
+interface ApprovalChange {
+    /** Token contract address */
+    tokenAddress: `0x${string}`;
+    /** Token symbol */
+    tokenSymbol: string;
+    /** Owner (usually the user address) */
+    owner: `0x${string}`;
+    /** Spender (contract being approved) */
+    spender: `0x${string}`;
+    /** Approval amount in smallest unit (stringified bigint) */
+    amount: string;
+    /** Whether this is an unlimited approval (type(uint256).max) */
+    isUnlimited: boolean;
+    /** Human-readable description */
+    humanReadable: string;
+}
+type RiskLevel = "safe" | "warning" | "malicious" | "unknown";
+type RiskWarningCategory = "phishing" | "unlimited_approval" | "high_value" | "unknown_contract" | "malicious_domain" | "simulation_failed" | "other";
+type RiskWarningSeverity = "low" | "medium" | "high" | "critical";
+interface RiskAssessment {
+    /** Aggregated risk level */
+    level: RiskLevel;
+    /** Numeric score 0–100 (higher = more dangerous) */
+    score: number;
+    /** Individual warnings that contributed to the score */
+    warnings: RiskWarning[];
+}
+interface RiskWarning {
+    /** Classification category */
+    category: RiskWarningCategory;
+    /** Severity level */
+    severity: RiskWarningSeverity;
+    /** Human-readable warning message */
+    message: string;
+}
+interface GasInfo {
+    /** Estimated gas limit */
+    gasLimit: bigint;
+    /** Estimated gas price in wei */
+    gasPrice?: bigint;
+    /** Predicted total gas fee in ETH (stringified) */
+    estimatedFeeEth?: string;
+    /** Predicted total gas fee in USD */
+    estimatedFeeUsd?: string;
+}
+interface TransactionDescriptor {
+    /** Target contract / recipient address */
+    to: `0x${string}`;
+    /** Call data (ABI-encoded function call) */
+    data: `0x${string}`;
+    /** Value in wei (stringified hex with 0x prefix) */
+    value: string;
+    /** Sender address */
+    from?: `0x${string}`;
+    /** Gas limit override (optional) */
+    gas?: string;
+}
+interface SimulationConfig {
+    /** Blowfish API key (optional; enables Blowfish provider) */
+    blowfishApiKey?: string;
+    /** Default provider to use (default: "auto") */
+    defaultProvider?: SimulationProviderName;
+    /** Whether simulation is enabled globally (default: true) */
+    enabled?: boolean;
+    /** Custom RPC URL for eth_call provider */
+    rpcUrl?: string;
+}
+
+/**
+ * SimulationProvider — Abstract interface for simulation backends.
+ *
+ * All simulation providers (eth_call, Blowfish, Tenderly) implement
+ * this interface so they can be swapped transparently by SimulationManager.
+ *
+ * @see /docs/features/transaction-simulation.md §6.4
+ */
+
+interface SimulationProvider {
+    /** Human-readable provider name */
+    readonly name: SimulationProviderName;
+    /** Chain IDs this provider supports (empty = all EVM) */
+    readonly supportedChains: number[];
+    /**
+     * Simulate a transaction and return the result.
+     *
+     * @param tx - The transaction to simulate
+     * @param from - The sender address
+     * @param options - Optional.origin (dApp URL for phishing detection)
+     *                  and optional.rpcUrl (override for eth_call provider)
+     */
+    simulate(tx: TransactionDescriptor, from: `0x${string}`, options?: {
+        origin?: string;
+        rpcUrl?: string;
+    }): Promise<SimulationResult>;
+    /**
+     * Check whether this provider is available for the given chain.
+     */
+    isAvailable(chainId: number): boolean;
+}
+
+/**
+ * BlowfishProvider — Blowfish API integration for transaction simulation
+ *                    and security scanning.
+ *
+ * This is an **adapter stub** (Layer 2 / P1). When configured with an
+ * API key, it provides:
+ * - Full balance change detection
+ * - Human-readable simulation summaries
+ * - Risk scoring (suggestedAction: NONE / WARN / BLOCK)
+ * - Phishing detection
+ *
+ * Implementation notes:
+ * - API key is provided by the wallet host (not end-user)
+ * - Falls back to basic simulation on rate-limit / 500
+ * - Sensitive transaction data is sent to Blowfish servers
+ *
+ * @see https://docs.blowfish.xyz
+ * @see /docs/features/transaction-simulation.md §5.2
+ */
+
+declare class BlowfishProvider implements SimulationProvider {
+    readonly name: SimulationProviderName;
+    readonly supportedChains: number[];
+    private apiKey;
+    constructor(apiKey: string);
+    simulate(tx: TransactionDescriptor, from: `0x${string}`, options?: {
+        origin?: string;
+        rpcUrl?: string;
+    }): Promise<SimulationResult>;
+    isAvailable(chainId: number): boolean;
+    /**
+     * Best-effort infer chain ID from origin or other context.
+     * Defaults to 1 (Ethereum mainnet).
+     */
+    private _inferChainId;
+}
+
+/**
+ * EthCallProvider — Basic simulation using the eth_call RPC method.
+ *
+ * Provides Layer 1 (P0) simulation: checks for revert, returns revert
+ * reason if the transaction would fail. Cannot resolve balance changes,
+ * approval changes, or risk scores since eth_call only returns the
+ * function output, not state diffs.
+ *
+ * Uses raw fetch to call JSON-RPC (no ethers/viem dependency).
+ *
+ * @see /docs/features/transaction-simulation.md §5.1
+ */
+
+declare class EthCallProvider implements SimulationProvider {
+    readonly name: SimulationProviderName;
+    readonly supportedChains: number[];
+    private defaultRpcUrl?;
+    constructor(defaultRpcUrl?: string);
+    /**
+     * Simulate a transaction via eth_call.
+     *
+     * eth_call returns only the function return data — it does not expose
+     * state diffs. Therefore this provider can only determine:
+     * - Is the transaction going to revert?
+     * - What is the revert reason?
+     *
+     * It CANNOT resolve balance changes or approval changes.
+     */
+    simulate(tx: TransactionDescriptor, from: `0x${string}`, options?: {
+        origin?: string;
+        rpcUrl?: string;
+    }): Promise<SimulationResult>;
+    isAvailable(_chainId: number): boolean;
+    /**
+     * Attempt to infer chain ID from the RPC URL (best-effort).
+     * Returns 0 if unknown.
+     */
+    private _extractChainId;
+}
+
+/**
+ * Token Configuration — uniquely identifies an ERC-20 token on a specific chain.
+ */
+interface TokenConfig {
+    /** ERC-20 token contract address */
+    address: `0x${string}`;
+    /** Chain ID (decimal, e.g. 1 for Ethereum) */
+    chainId: number;
+    /** Optional cached decimals (skip RPC call when provided) */
+    decimals?: number;
+}
+/**
+ * Token Metadata — fetched on-chain via name(), symbol(), decimals(), totalSupply().
+ */
+interface TokenInfo {
+    name: string;
+    symbol: string;
+    decimals: number;
+    totalSupply: bigint;
+}
+/**
+ * Parameters for building an ERC-20 transfer transaction.
+ */
+interface ERC20TransferTxParams {
+    token: TokenConfig;
+    from: `0x${string}`;
+    to: `0x${string}`;
+    /** Amount in human-readable units (e.g. "1.50" for 1.5 USDC) */
+    amount: string | bigint;
+}
+/**
+ * Parameters for building an ERC-20 approve transaction.
+ */
+interface ERC20ApproveTxParams {
+    token: TokenConfig;
+    owner: `0x${string}`;
+    spender: `0x${string}`;
+    amount: string | bigint;
+}
+/**
+ * Parameters for building an ERC-20 transferFrom transaction.
+ */
+interface ERC20TransferFromTxParams {
+    token: TokenConfig;
+    from: `0x${string}`;
+    to: `0x${string}`;
+    amount: string | bigint;
+}
+/**
+ * RPC call options — useful for overriding the default RPC URL.
+ */
+interface ERC20CallOptions {
+    /** Override RPC URL (default: derived from chainId via config) */
+    rpcUrl?: string;
+}
+
+/**
+ * SimulationManager — Central orchestrator for transaction simulation.
+ *
+ * Dispatches simulation requests to the appropriate provider based on
+ * configuration and chain support. Handles:
+ * - Provider selection (auto / eth_call / blowfish)
+ * - Graceful fallback when a provider is unavailable
+ * - Convenience methods like simulateERC20Transfer
+ *
+ * Integration points:
+ * - wallet-engine: PocketWallet.simulateTransaction()
+ * - Token helper (SRS-007): Builds calldata for ERC-20 transfers
+ * - TxMonitor (SRS-008): Compares simulation vs actual results
+ *
+ * @see /docs/features/transaction-simulation.md §6.3
+ */
+
+declare class SimulationManager {
+    private providers;
+    private _defaultProvider;
+    private _enabled;
+    private blowfishApiKey?;
+    constructor(config?: SimulationConfig);
+    /**
+     * Main simulation entry point.
+     *
+     * Routes to the best available provider based on config and chain support.
+     * Falls back to eth_call if Blowfish is unavailable for the chain.
+     *
+     * @param tx - Transaction to simulate
+     * @param from - Sender address
+     * @param options - Optional chainId, rpcUrl, origin
+     */
+    simulate(tx: TransactionDescriptor, from: `0x${string}`, options?: {
+        chainId?: number;
+        origin?: string;
+        rpcUrl?: string;
+    }): Promise<SimulationResult>;
+    /**
+     * Convenience: simulate an ERC-20 token transfer.
+     *
+     * Builds the transfer calldata using ERC20TokenHelper (SRS-007),
+     * then runs the simulation.
+     *
+     * @param token - Token to transfer
+     * @param from - Sender address
+     * @param to - Recipient address
+     * @param amount - Amount in human-readable units (e.g. "1.50")
+     * @param chainId - Chain ID
+     */
+    simulateERC20Transfer(token: TokenConfig, from: `0x${string}`, to: `0x${string}`, amount: string, chainId: number): Promise<SimulationResult>;
+    /**
+     * Check whether simulation is available for a given chain.
+     */
+    isAvailable(chainId: number): boolean;
+    /**
+     * Enable or disable simulation globally.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Get whether simulation is currently enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Register a custom provider.
+     * Useful for testing or third-party providers.
+     */
+    registerProvider(name: SimulationProviderName, provider: SimulationProvider): void;
+    /**
+     * Add or update a Blowfish API key at runtime.
+     */
+    setBlowfishApiKey(apiKey: string): void;
+    /**
+     * Remove a registered provider.
+     */
+    unregisterProvider(name: SimulationProviderName): void;
+    /**
+     * Select the best provider for the given chain.
+     *
+     * Selection rules:
+     * - "auto": Try blowfish first (if registered + chain supported),
+     *           fall back to eth_call
+     * - "blowfish": Use blowfish if available
+     * - "eth_call": Always available on EVM
+     */
+    private _selectProvider;
+    /**
+     * Estimate chain ID from the from address or config.
+     * Best-effort; returns 0 if unknown.
+     */
+    private _estimateChainId;
+    /**
+     * Resolve an RPC URL for the eth_call fallback provider.
+     */
+    private _resolveRpcUrl;
+}
+/**
+ * Compare simulation results with actual transaction receipt.
+ *
+ * Used by TxMonitor to detect discrepancies between simulated and
+ * actual transaction outcomes.
+ *
+ * @param simulation - The simulation result
+ * @param actualStatus - Actual tx receipt status ("success" | "reverted")
+ * @returns Match result
+ */
+declare function compareSimulationVsActual(simulation: SimulationResult, actualStatus: "success" | "reverted"): {
+    match: boolean;
+    discrepancies?: string[];
+};
+
+/** Full minimal ABI as const for viem compatibility */
+declare const ERC20_MIN_ABI: readonly [{
+    readonly name: "transfer";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "success";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "approve";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "success";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "transferFrom";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "success";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "remaining";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "balance";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "decimals";
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "symbol";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "symbol";
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "name";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "name";
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "totalSupply";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "totalSupply";
+        readonly type: "uint256";
+    }];
+}];
+/**
+ * Canonical function signatures (for manual keccak256-based encoding).
+ */
+declare const ERC20_FUNCTION_SIGNATURES: {
+    readonly transfer: "transfer(address,uint256)";
+    readonly approve: "approve(address,uint256)";
+    readonly transferFrom: "transferFrom(address,address,uint256)";
+    readonly allowance: "allowance(address,address)";
+    readonly balanceOf: "balanceOf(address)";
+    readonly decimals: "decimals()";
+    readonly symbol: "symbol()";
+    readonly name: "name()";
+    readonly totalSupply: "totalSupply()";
+};
+/**
+ * Type helper — extract the ABI items for a given function name.
+ */
+type AbiItem<TName extends (typeof ERC20_MIN_ABI)[number]["name"]> = (typeof ERC20_MIN_ABI)[number] & {
+    name: TName;
+};
+
+/**
+ * ERC20TokenHelper — ABI encoding, RPC queries, and transaction building
+ * for ERC-20 tokens.
+ *
+ * Design:
+ * - Zero dependency on viem/ethers for ABI encoding
+ * - Uses @noble/hashes/keccak_256 (already in monorepo) for selector computation
+ * - All methods are static (composition over inheritance)
+ * - Transaction builder methods return raw TransactionRequest objects
+ *
+ * @see SRS-007
+ */
+
+/**
+ * ABI-encode an address: left-pad to 32 bytes.
+ * "0xabc" → "0x0000...000abc"
+ */
+declare function abiEncodeAddress(addr: `0x${string}`): `0x${string}`;
+/**
+ * ABI-encode a uint256: left-pad to 32 bytes.
+ */
+declare function abiEncodeUint256(value: bigint): `0x${string}`;
+/**
+ * Compute a 4-byte function selector from a canonical function signature.
+ *
+ * @example
+ * abiFunctionSelector("transfer(address,uint256)")
+ *   // → "0xa9059cbb"
+ */
+declare function abiFunctionSelector(signature: string): Promise<`0x${string}`>;
+/**
+ * Full ABI function call encoding: 4-byte selector + packed args.
+ *
+ * @example
+ * const data = await abiEncodeFunctionCall(
+ *   "transfer(address,uint256)",
+ *   "0xRecipientAddress...",
+ *   "0x0000...0001e240"  // already-encoded uint256
+ * );
+ */
+declare function abiEncodeFunctionCall(signature: string, ...encodedArgs: string[]): Promise<`0x${string}`>;
+declare class ERC20TokenHelper {
+    /**
+     * Build a raw ERC-20 transfer TransactionRequest.
+     *
+     * The returned object can be fed into PocketWallet.sendTransaction()
+     * or signed offline.
+     */
+    static buildTransferTx(params: ERC20TransferTxParams, decimals: number): Promise<{
+        to: `0x${string}`;
+        from: `0x${string}`;
+        data: `0x${string}`;
+        value: "0x0";
+    }>;
+    /**
+     * Build a raw ERC-20 approve TransactionRequest.
+     */
+    static buildApproveTx(params: ERC20ApproveTxParams, decimals: number): Promise<{
+        to: `0x${string}`;
+        from: `0x${string}`;
+        data: `0x${string}`;
+        value: "0x0";
+    }>;
+    /**
+     * Build a raw ERC-20 transferFrom TransactionRequest.
+     * Requires the caller to have been approved first.
+     */
+    static buildTransferFromTx(params: ERC20TransferFromTxParams, decimals: number): Promise<{
+        to: `0x${string}`;
+        from: `0x${string}`;
+        data: `0x${string}`;
+        value: "0x0";
+    }>;
+    /**
+     * Call allowance(address,address) on-chain.
+     * Returns remaining allowance in smallest unit (bigint).
+     */
+    static getAllowance(token: TokenConfig, owner: `0x${string}`, spender: `0x${string}`, options?: ERC20CallOptions): Promise<bigint>;
+    /**
+     * Fetch token metadata (name, symbol, decimals, totalSupply) from chain.
+     * Makes 4 parallel RPC calls.
+     */
+    static getTokenInfo(token: TokenConfig, options?: ERC20CallOptions): Promise<TokenInfo>;
+    /**
+     * Check if a token is deployed on the target chain.
+     * Returns true if the contract has code (extcodesize > 0).
+     */
+    static isTokenDeployed(token: TokenConfig, options?: ERC20CallOptions): Promise<boolean>;
+    /**
+     * Fetch token decimals from chain (or return cached value).
+     */
+    static getDecimals(token: TokenConfig, options?: ERC20CallOptions): Promise<number>;
+    /**
+     * Convenience: parse a human-readable amount to raw units using the token's decimals.
+     */
+    static parseToRawAmount(token: TokenConfig, amount: string | number, options?: ERC20CallOptions): Promise<bigint>;
+    /**
+     * Convenience: format a raw bigint amount to a human-readable string using the token's decimals.
+     */
+    static formatRawAmount(token: TokenConfig, rawAmount: bigint, options?: ERC20CallOptions): Promise<string>;
+}
+
+/**
+ * Unified error handling for ERC-20 token operations.
+ *
+ * ERC20TokenError is independent of WalletError — the core package
+ * shouldn't depend on wallet-engine. Wallet-engine integration wraps
+ * these into WalletError when needed.
+ */
+type ERC20TokenErrorCode = "token_not_deployed" | "invalid_address" | "invalid_amount" | "insufficient_allowance" | "insufficient_balance" | "decimals_fetch_failed" | "token_info_fetch_failed" | "rpc_error" | "encoding_error" | "unknown_error";
+declare class ERC20TokenError extends Error {
+    readonly code: ERC20TokenErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: ERC20TokenErrorCode, message?: string, cause?: unknown | undefined);
+    /** Check if this error has a specific code */
+    hasCode(code: ERC20TokenErrorCode): boolean;
+}
+/** Type guard */
+declare function isERC20TokenError(e: unknown): e is ERC20TokenError;
+
+/**
+ * Amount formatting utilities for ERC-20 tokens.
+ *
+ * Provides parseUnits (human-readable → raw bigint) and
+ * formatUnits (raw bigint → human-readable string).
+ *
+ * Handles any decimal count (0–255 as per ERC-20 spec).
+ */
+/**
+ * Convert a human-readable amount (string, number, or bigint) to the smallest unit.
+ *
+ * @example
+ * parseUnits("1.5", 6)   → 1500000n    (USDC: 1.5 → 1,500,000)
+ * parseUnits("0.01", 18) → 10000000000000000n
+ * parseUnits("100", 0)   → 100n
+ *
+ * @throws {ERC20TokenError} on invalid input
+ */
+declare function parseUnits(amount: string | number | bigint, decimals: number): bigint;
+/**
+ * Convert a raw bigint amount to a human-readable decimal string.
+ *
+ * @example
+ * formatUnits(1500000n, 6)       → "1.5"
+ * formatUnits(10000000000000000n, 18) → "0.01"
+ * formatUnits(0n, 18)            → "0"
+ */
+declare function formatUnits(amount: bigint, decimals: number): string;
+
+/**
+ * Token List Types — compliant with Uniswap Token List spec
+ *
+ * @see https://github.com/Uniswap/token-lists
+ */
+/**
+ * Metadata for a single token.
+ */
+interface TokenListEntry {
+    /** EVM contract address or token identifier */
+    readonly address: string;
+    /** Numeric chain ID (e.g. 1 for Ethereum) */
+    readonly chainId: number;
+    /** Human-readable name (e.g. "USD Coin") */
+    readonly name: string;
+    /** Ticker symbol (e.g. "USDC") */
+    readonly symbol: string;
+    /** Token decimals (e.g. 6 for USDC, 18 for ETH) */
+    readonly decimals: number;
+    /** Optional logo URL */
+    readonly logoURI?: string;
+    /** Optional semantic tags (e.g. ["stablecoin"]) */
+    readonly tags?: string[];
+    /** Optional extensions for custom metadata */
+    readonly extensions?: Record<string, unknown>;
+    /** Source identifier (set internally by the manager) */
+    readonly source?: string;
+}
+/**
+ * A token list conforming to the Uniswap Token List JSON schema.
+ */
+interface TokenList {
+    readonly name: string;
+    readonly timestamp: string;
+    readonly version: {
+        major: number;
+        minor: number;
+        patch: number;
+    };
+    readonly tokens: TokenListEntry[];
+    readonly logoURI?: string;
+    readonly keywords?: string[];
+    readonly tags?: Record<string, TokenListTag>;
+}
+interface TokenListTag {
+    readonly name: string;
+    readonly description: string;
+}
+/**
+ * Configuration for a single token list source.
+ */
+interface TokenListSource {
+    /** Unique source identifier */
+    name: string;
+    /** Remote URL to fetch the list from */
+    url?: string;
+    /** Inline token array (used for built-in lists or custom tokens) */
+    tokens?: TokenListEntry[];
+    /** Refresh interval in ms (default 24h) */
+    refreshInterval?: number;
+    /** Whether this source is enabled by default */
+    enabled: boolean;
+    /** Optional chain filter – only tokens matching these chain IDs are kept */
+    chainFilter?: number[];
+}
+/**
+ * Configuration for TokenListManager.
+ */
+interface TokenListManagerConfig {
+    /** Ordered list of token list sources */
+    sources: TokenListSource[];
+    /** localStorage key for caching merged results */
+    cacheKey?: string;
+    /** Cache TTL in ms (default 24h) */
+    cacheTtl?: number;
+    /** Source priority for deduplication – earlier = higher priority */
+    sourcePriority?: string[];
+    /** Fetch timeout per source (ms, default 10000) */
+    fetchTimeout?: number;
+}
+/**
+ * Status snapshot of a single source.
+ */
+interface TokenListSourceStatus {
+    name: string;
+    enabled: boolean;
+    state: "loading" | "loaded" | "error";
+    tokenCount: number;
+    lastUpdated: number | null;
+    error?: string;
+}
+/**
+ * Search query parameters.
+ */
+interface TokenSearchQuery {
+    query: string;
+    chainId?: number;
+    limit?: number;
+}
+/**
+ * Result of a token search.
+ */
+interface TokenSearchResult {
+    exact: TokenMatch[];
+    fuzzy: TokenMatch[];
+    hasMore: boolean;
+}
+/**
+ * A single search match with relevance score.
+ */
+interface TokenMatch {
+    token: TokenListEntry;
+    score: number;
+    matchField: "symbol" | "name" | "address";
+    hasBalance?: boolean;
+    balance?: string;
+}
+
+/**
+ * Auto-detect — fetch token metadata from chain and cache to localStorage.
+ *
+ * Uses ERC20TokenHelper.getTokenInfo() to retrieve name, symbol, decimals.
+ * Results are cached in localStorage to avoid repeated RPC calls.
+ */
+
+/**
+ * A minimal on-chain token fetcher compatible with Node and browser.
+ *
+ * Makes eth_call RPC requests to invoke standard ERC-20 functions:
+ *   name(), symbol(), decimals()
+ */
+declare function detectTokenInfo(address: string, chainId: number, rpcUrl: string, options?: {
+    skipCache?: boolean;
+}): Promise<TokenListEntry>;
+/**
+ * Clear the auto-detect cache.
+ */
+declare function clearAutoDetectCache(): Promise<void>;
+
+/**
+ * Built-in default token lists.
+ *
+ * Only includes the most common tokens to keep the bundle small.
+ * Full lists (Uniswap, Coinbase, Jupiter) are loaded from remote sources.
+ */
+
+/**
+ * Popular Ethereum mainnet tokens (chainId = 1).
+ */
+declare const ETHEREUM_MAINNET_TOKENS: TokenListEntry[];
+/**
+ * Popular Polygon (chainId 137) tokens.
+ */
+declare const POLYGON_TOKENS: TokenListEntry[];
+/**
+ * Optimism (chainId 10) tokens.
+ */
+declare const OPTIMISM_TOKENS: TokenListEntry[];
+/**
+ * Arbitrum (chainId 42161) tokens.
+ */
+declare const ARBITRUM_TOKENS: TokenListEntry[];
+/**
+ * Base (chainId 8453) tokens.
+ */
+declare const BASE_TOKENS: TokenListEntry[];
+/**
+ * All built-in tokens aggregated by chain ID.
+ */
+declare const DEFAULT_BUILTIN_TOKENS: Record<number, TokenListEntry[]>;
+/**
+ * All built-in tokens as a flat array.
+ */
+declare function getAllBuiltinTokens(): TokenListEntry[];
+/**
+ * Default sources for TokenListManager.
+ *
+ * - Built-in (inline): always available, no network fetch needed
+ * - Uniswap Default: loaded from remote URL on first use
+ * - Coinbase: loaded from remote URL on first use
+ */
+declare const DEFAULT_SOURCES: TokenListSource[];
+
+/**
+ * TokenListManager — load, merge, cache, and search token lists.
+ *
+ * Supports multiple sources (built-in, Uniswap, Coinbase, custom).
+ * Deduplicates by (chainId, address) with configurable source priority.
+ * Caches merged results to localStorage.
+ */
+
+declare class TokenListManager {
+    private config;
+    private tokens;
+    private sourceStatus;
+    private storage;
+    constructor(config?: Partial<TokenListManagerConfig>);
+    /**
+     * Load all enabled sources.
+     * Checks cache first, falls back to in-memory or failed-source stale data.
+     */
+    load(): Promise<TokenListEntry[]>;
+    /**
+     * Force-refresh all sources, bypassing cache.
+     */
+    refresh(): Promise<TokenListEntry[]>;
+    /**
+     * Get all loaded tokens, optionally filtered.
+     */
+    getTokens(options?: {
+        chainId?: number;
+        source?: string;
+    }): TokenListEntry[];
+    /**
+     * Search tokens by symbol, name, or address.
+     */
+    search(query: string, options?: {
+        chainId?: number;
+        limit?: number;
+    }): TokenSearchResult;
+    /**
+     * Get a single token by address and chain ID.
+     */
+    getToken(address: string, chainId: number): TokenListEntry | undefined;
+    /**
+     * Clear all caches.
+     */
+    clearCache(): void;
+    /**
+     * Get status of all registered sources.
+     */
+    getSourcesStatus(): TokenListSourceStatus[];
+    private fetchSource;
+    /**
+     * Deduplicate tokens by (chainId, address).
+     * Source priority controls which record wins for colliding tokens.
+     */
+    private deduplicate;
+    private loadFromCache;
+    private saveToCache;
+    private isCacheExpired;
+    private updateSourceStatuses;
+}
+
+/**
+ * Get the USD price of a native token (e.g. ETH, MATIC) by chain ID.
+ *
+ * This function was missing from the source but exists in the dist build.
+ * It was added to the Ladle Vite bridge to unblock storybook-based testing.
+ *
+ * @param chain - EIP-155 chain ID (e.g. "eip155:1")
+ * @param rpcUrl - Optional RPC URL for on-chain price lookup
+ * @returns USD price as a number, or null if unavailable
+ */
+declare function getNativeTokenPriceUsd(chain: string, _rpcUrl?: string): Promise<number | null>;
+
+export { type AAErrorCode, AA_ERROR_MESSAGES, AA_SUPPORTED_CHAINS, ARBITRUM_TOKENS, AUTO_RECONNECT_TIMEOUT_MS, type AbiItem, AccountAbstractionError, type AccountType, type ActiveSessionBundle, type Address, type AddressResult, type ApprovalChange, type AutoReconnectConfig, AutoReconnectManager, AxelarProvider, type AxelarProviderConfig, BASE_TOKENS, type BalanceChange, type BatchCall, BlowfishProvider, type BridgeProvider, type BridgeProviderId, type BundlerClient, CHAINS, CONNECTOR_ERROR_MESSAGES, type Call, type CallsStatus, type ChainAbstractionConfig, ChainAbstractionError, type ChainAbstractionErrorCode, type ChainFeeEstimator, type ChainFeeSupport, type ChainInfo, type ChainSession, type ChannelCapability, type ConnectorEntry, type ConnectorId, ConnectorManager, type ConnectorManagerConfig, type ConnectorSupport, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, type CreateEmptySessionInput, DEFAULT_BUILTIN_TOKENS, DEFAULT_CALL_GAS_LIMIT, DEFAULT_ENTRY_POINT, DEFAULT_EVM_CHAIN, DEFAULT_NONCE_LENGTH, DEFAULT_PRE_VERIFICATION_GAS, DEFAULT_RPC_URLS, DEFAULT_SESSION_KEY_CONFIG, DEFAULT_SOLANA_CLUSTER, DEFAULT_SOURCES, DEFAULT_VERIFICATION_GAS_LIMIT, DEFAULT_XRPL_NETWORK, EIP155_ARBITRUM, EIP155_ARBITRUM_GOERLI, EIP155_BASE, EIP155_GOERLI, EIP155_MAINNET, EIP155_MUMBAI, EIP155_OPTIMISM, EIP155_OPTIMISM_GOERLI, EIP155_POLYGON, EIP155_SEPOLIA, ENSProvider, ENTRY_POINT_V0_6, ENTRY_POINT_V0_7, type ERC20ApproveTxParams, type ERC20CallOptions, ERC20TokenError, type ERC20TokenErrorCode, ERC20TokenHelper, type ERC20TransferFromTxParams, type ERC20TransferTxParams, ERC20_FUNCTION_SIGNATURES, ERC20_MIN_ABI, ETHEREUM_MAINNET_TOKENS, type EncryptedKeyPair, EthCallProvider, type ExecuteOptions, type ExecuteRouteResult, FEE_ERROR_MESSAGES, type FeeEstimationConfig, FeeEstimationError, type FeeEstimationErrorCode, type FeeTypeStrategy, type FeeValues, type FeeValuesEIP1559, type FeeValuesLegacy, type GasEstimate, type GasInfo, type Hex, InAppChannel, type InAppChannelOptions, LiFiProvider, type LiFiProviderConfig, LocalStorageAdapter, LocalStorageSessionStorage, type LogLevel, type LoggerNamespace, MemoryStorageAdapter, type MuteRule, NAMESPACE_EIP155, NAMESPACE_SOLANA, NAMESPACE_XRPL, NameResolver, type NameResolverConfig, type NameResult, type Namespace, type NamespaceCapabilities, NoopChannel, NoopStorageAdapter, type NotificationChannel, type NotificationFrequency, type NotificationItem, type NotificationPayload, type NotificationSettings, type NotificationWatch, Notifier, type NotifierOptions, OPTIMISM_TOKENS, POLYGON_TOKENS, type Paymaster, type PaymasterConfig, type PaymasterData, PaymasterService, type PaymasterServiceConfig, type PaymasterType, type PermissionsRequest, type PersistedSessionData, type Platform, type ProviderTransaction, type Quote, type QuoteOptions, type QuoteSortBy, type RefreshFeesOptions, ResolutionError, type ResolutionErrorCode, ResolverCache, type ResolverProvider, type RiskAssessment, type RiskLevel, type RiskWarning, type RiskWarningCategory, type RiskWarningSeverity, type Route, RouteEngine, type RouteStatus, type RouteStatusValue, type RouteStep, SESSION_ERROR_MESSAGES, SESSION_KEY_ERROR_MESSAGES, SESSION_TIMEOUT_MS, SIMPLE_ACCOUNT_FACTORY, SNSProvider, SOLANA_DEVNET, SOLANA_MAINNET, SOLANA_TESTNET, STORAGE_KEYS, SUPPORTED_NAMESPACES, type ScopeCheckResult, type SendUserOpOptions, type SessionErrorCode, type SessionEvent, SessionEventEmitter, type SessionEventHandler, type SessionEventPayloads, type SessionKeyBundle, type SessionKeyErrorCode, type SessionKeyInfo, SessionKeyManager, type SessionKeyManagerConfig, type SessionKeyPair, type SessionKeyScope, type SessionKeyStatus, SessionKeyStorage, SessionManager, type SessionManagerConfig, type SessionNamespace, SessionPersistence, type SessionStorage, SessionStorageAdapter, type SignedAuthorization, type SimulationConfig, SimulationManager, type SimulationProvider, type SimulationProviderName, type SimulationResult, type SimulationStatus, type SmartAccountConfig, type SmartAccountInfo, SmartAccountManager, type SmartAccountManagerConfig, type StorageAdapter, StorageError, type StoredSessionKey, TelegramChannel, type Token, type TokenConfig, type TokenInfo, type TokenList, type TokenListEntry, TokenListManager, type TokenListManagerConfig, type TokenListSource, type TokenListSourceStatus, type TokenMatch, type TokenSearchQuery, type TokenSearchResult, type TransactionDescriptor, type TxMetadata, type TxStatus, type TxStatusCallback, type UniversalConnector, type UniversalWalletSession, type UserFeeOverrides, type UserNotificationPreferences, type UserOperation, type UserOperationGasEstimate, type UserOperationReceipt, type UserOperationResponse, WC_DISCONNECT_SESSION_EXPIRED, WC_DISCONNECT_TIMEOUT, WC_DISCONNECT_USER, type WalletCapabilities, WalletError, type WalletErrorCode, type WalletPermission, XRPL_DEVNET, XRPL_MAINNET, XRPL_TESTNET, abiEncodeAddress, abiEncodeFunctionCall, abiEncodeUint256, abiFunctionSelector, buildCallData, buildUserOperation, clearAutoDetectCache, clearChainFeeEstimators, compareSimulationVsActual, createAutoReconnectManager, createConnectorManager, createEmptySession, createPaymasterService, createRouteEngine, createSessionError, createSessionKeyError, createSessionManager, createSessionPersistence, createStorageAdapter, decodeGasLimits, decryptPrivateKey, detectPlatform, detectTokenInfo, encodeGasLimits, encryptPrivateKey, estimateFees, estimateMaxPriorityFeePerGas, estimateUserOperationGas, extractAccounts, extractAccountsFromPermissions, formatUnits, getAllBuiltinTokens, getChainId, getChainsFromNamespaces, getEventsFromNamespaces, getFeeData, getGasPrice, getLatestBaseFee, getMethodsFromNamespaces, getNativeTokenPriceUsd, getPermissions, getRpcUrl, hasPermission, hashUserOperation, isAAError, isBurnAddress, isChainAbstractionError, isERC20TokenError, isFeeEstimationError, isMobileBrowser, isSessionExpired, isValidAddress, isWalletError, isZeroAddress, logger, parseBigInt, parseChainId, parseUnits, registerChainFeeEstimator, requestPermissions, sendUserOperation, setLogLevel, setLogSink, signUserOperation, toDecString, toHumanReadable, unregisterChainFeeEstimator, updateSession, validateChainId };