@awarizon/web3 1.3.2 → 1.3.4

package/dist/index.d.mts

@@ -1,10 +1,333 @@
-import { PublicClient, Chain, WalletClient, Address, Abi, Hex, Transport } from 'viem';
+import { Chain, PublicClient, Transport, Address, WalletClient, Hex, Hash, TransactionReceipt, Abi, AbiFunction, AbiEvent } from 'viem';
 export { Abi, Address, Chain, Hash, TransactionReceipt, WalletClient } from 'viem';
-import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ConnectorInfo, ExternalWalletClient, EIP1193Provider, SignTypedDataParams, WalletChangeEvent, ChainChangeEvent } from '@awarizon/wallet-engine';
-export { ChainChangeEvent, ChainMismatchError, ChainSwitchError, ConnectorInfo, CreatedWallet, EIP1193Provider, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, InvalidMnemonicError, InvalidPrivateKeyError, SignTypedDataParams, WalletChangeEvent, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
-import { TransactionResult } from '@awarizon/tx-engine';
-export { ContractExecutionError, GasEstimationError, SimulationError, TransactionEngine, TransactionResult, TransactionTimeoutError } from '@awarizon/tx-engine';
-export { DuplicateFunctionError, InvalidABIError, UnsupportedABIItemError, generateAllMethodSignatures, generateMethodSignature, isPayableFunction, isWriteFunction, parseABI } from '@awarizon/abi-engine';
+import { AbiConstructor } from 'abitype';
+
+interface CreatedWallet {
+    /** The Ethereum address (first account at m/44'/60'/0'/0/0) */
+    address: Address;
+    /** BIP-39 seed phrase — 12 words. Back this up; it is the only way to recover the wallet. */
+    mnemonic: string;
+    /** BIP-44 derivation path used — matches MetaMask and Phantom */
+    derivationPath: string;
+}
+interface ImportedWalletFromMnemonic {
+    address: Address;
+    mnemonic: string;
+    /** BIP-44 derivation path used: m/44'/60'/0'/0/{addressIndex} */
+    derivationPath: string;
+}
+interface ImportedWalletFromPrivateKey {
+    address: Address;
+}
+interface WalletEngineConfig {
+    chain: Chain;
+    publicClient: PublicClient;
+    /** Custom RPC URL to use when creating the internal wallet client */
+    rpcUrl?: string;
+    /**
+     * Optional transport factory invoked when the engine needs to rebuild
+     * its internal clients (e.g. after switchChain). When omitted the engine
+     * falls back to `http(rpcUrl)`.
+     *
+     * Pass `getChainTransport` from `@awarizon/core` to get automatic fallback
+     * handling for chains with unreliable default public RPCs.
+     */
+    getTransport?: (chain: Chain) => Transport;
+}
+/**
+ * Any viem-compatible WalletClient, including those produced by wagmi,
+ * WalletConnect, or custom providers implementing EIP-1193.
+ */
+type ExternalWalletClient = WalletClient;
+interface EIP1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on?(event: string, handler: (...args: unknown[]) => void): void;
+    removeListener?(event: string, handler: (...args: unknown[]) => void): void;
+}
+interface ConnectorInfo {
+    /** How this wallet was connected */
+    type: 'internal' | 'external' | 'none';
+    /** Human-readable connector name, e.g. "MetaMask", "Coinbase Wallet" */
+    name?: string;
+    /** URL to the connector's icon image */
+    icon?: string;
+}
+interface WalletChangeEvent {
+    /** Active address after the change, or null if disconnected */
+    address: Address | null;
+    /** Source of the active wallet after the change */
+    type: 'internal' | 'external' | 'none';
+    /** Connector name if type is 'external' */
+    name?: string;
+}
+interface ChainChangeEvent {
+    /** The new chain ID */
+    chainId: number;
+    /** The full viem Chain object */
+    chain: Chain;
+}
+interface SignTypedDataParams {
+    domain?: {
+        name?: string;
+        version?: string;
+        chainId?: number | bigint;
+        verifyingContract?: Address;
+        salt?: Hex;
+    };
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+
+type WalletChangeCallback = (event: WalletChangeEvent) => void;
+type ChainChangeCallback = (event: ChainChangeEvent) => void;
+/**
+ * Manages both internally-generated wallets and externally-injected signers
+ * (wagmi, WalletConnect, EIP-1193 providers, raw viem WalletClients).
+ *
+ * Priority order when resolving the active signer:
+ *   1. External wallet client (highest priority)
+ *   2. Internal wallet client (private key / mnemonic import)
+ *
+ * Events:
+ *   onWalletChange — fires whenever the active wallet address changes
+ *   onChainChange  — fires whenever switchChain() is called
+ */
+declare class WalletEngine {
+    private config;
+    private internalClient;
+    private externalClient;
+    private _connectorInfo;
+    private _walletListeners;
+    private _chainListeners;
+    constructor(config: WalletEngineConfig);
+    create(): Promise<CreatedWallet>;
+    /**
+     * Import a wallet from a BIP-39 mnemonic phrase.
+     *
+     * `addressIndex` maps to MetaMask's account switcher:
+     *   0 → Account 1  (m/44'/60'/0'/0/0)
+     *   1 → Account 2  (m/44'/60'/0'/0/1)
+     *   N → Account N+1
+     */
+    importMnemonic(mnemonic: string, addressIndex?: number): Promise<ImportedWalletFromMnemonic>;
+    importPrivateKey(privateKey: Hex): Promise<ImportedWalletFromPrivateKey>;
+    /**
+     * Connect any viem WalletClient (wagmi, RainbowKit, custom).
+     * Optionally pass connector metadata to display in the UI.
+     *
+     * External wallets always take priority over internal wallets.
+     */
+    connectExternal(walletClient: ExternalWalletClient, info?: {
+        name?: string;
+        icon?: string;
+    }): void;
+    /**
+     * Connect directly from a raw EIP-1193 provider (window.ethereum, WalletConnect, etc.)
+     * without needing wagmi or any wrapper. Calls eth_requestAccounts internally.
+     *
+     * @param provider - Any object implementing the EIP-1193 interface
+     * @param info     - Optional connector metadata (name, icon)
+     */
+    connectEIP1193(provider: EIP1193Provider, info?: {
+        name?: string;
+        icon?: string;
+    }): Promise<void>;
+    /** Remove the external wallet. Falls back to internal wallet if one is loaded. */
+    disconnectExternal(): void;
+    /** Remove all wallet state — both internal and external. */
+    disconnect(): void;
+    switchChain(chain: Chain): Promise<void>;
+    /**
+     * Sign a plain text or raw-bytes message with the active wallet.
+     * Supports Sign-In with Ethereum (SIWE) and off-chain auth flows.
+     *
+     * @param message - A UTF-8 string or `{ raw: Hex | Uint8Array }` for raw bytes
+     */
+    signMessage(message: string | {
+        raw: Hex | Uint8Array;
+    }): Promise<Hex>;
+    /**
+     * Sign EIP-712 typed structured data (permit2, SIWE, Seaport, etc.).
+     *
+     * @param params - domain, types, primaryType, and message fields per EIP-712
+     */
+    signTypedData(params: SignTypedDataParams): Promise<Hex>;
+    /**
+     * Returns the chain ID the active wallet is currently on.
+     * For external wallets this queries the wallet directly (may differ from SDK config).
+     * For internal wallets this always returns the SDK-configured chain ID.
+     */
+    getChainId(): Promise<number>;
+    /**
+     * Returns true if the external wallet is on a different chain than the SDK.
+     * Always false for internal wallets (they follow the SDK chain automatically).
+     */
+    isChainMismatch(): Promise<boolean>;
+    /**
+     * Subscribe to wallet changes (connect, disconnect, account switch).
+     * Returns an unsubscribe function — call it to stop listening.
+     *
+     * @example
+     * const unsub = engine.onWalletChange(({ address, type }) => {
+     *   console.log('wallet changed:', address, type)
+     * })
+     * unsub() // stop listening
+     */
+    onWalletChange(cb: WalletChangeCallback): () => void;
+    /**
+     * Subscribe to chain changes (switchChain calls).
+     * Returns an unsubscribe function — call it to stop listening.
+     */
+    onChainChange(cb: ChainChangeCallback): () => void;
+    getWalletClient(): WalletClient;
+    getSigner(): WalletClient;
+    address(): Address;
+    getChain(): Chain;
+    getPublicClient(): PublicClient;
+    isConnected(): boolean;
+    hasExternalWallet(): boolean;
+    hasInternalWallet(): boolean;
+    /**
+     * Returns metadata about the currently active connector.
+     * Useful for displaying "Connected via MetaMask" in the UI.
+     */
+    getConnectorInfo(): ConnectorInfo;
+    private _resolveTransport;
+    private _buildInternalClient;
+    private _emitWalletChange;
+    private _emitChainChange;
+}
+
+declare class WalletNotConnectedError extends Error {
+    readonly code: "WALLET_NOT_CONNECTED";
+    constructor(message?: string);
+}
+declare class InvalidMnemonicError extends Error {
+    readonly code: "INVALID_MNEMONIC";
+    constructor(message?: string);
+}
+declare class InvalidPrivateKeyError extends Error {
+    readonly code: "INVALID_PRIVATE_KEY";
+    constructor(message?: string);
+}
+declare class ChainSwitchError extends Error {
+    readonly code: "CHAIN_SWITCH_ERROR";
+    constructor(message: string);
+}
+declare class ChainMismatchError extends Error {
+    readonly code: "CHAIN_MISMATCH";
+    readonly walletChainId: number;
+    readonly expectedChainId: number;
+    constructor(walletChainId: number, expectedChainId: number);
+}
+
+interface WriteContractParams {
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args: unknown[];
+    /** ETH value to send with payable calls (in wei) */
+    value?: bigint;
+    /** Gas limit override */
+    gas?: bigint;
+    /** Optional configuration overrides */
+    config?: TransactionConfig;
+}
+interface ReadContractParams {
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args: unknown[];
+}
+interface TransactionConfig {
+    /** Whether to simulate the transaction before sending (default: true) */
+    simulate?: boolean;
+    /** Multiplier applied to the estimated gas limit (default: 1.0 — no buffer) */
+    gasBuffer?: number;
+}
+interface TransactionResult {
+    /** Transaction hash */
+    hash: Hash;
+    /** On-chain receipt, available once the tx is confirmed */
+    receipt: TransactionReceipt;
+}
+interface GasEstimate {
+    gas: bigint;
+    /** gas * gasPrice, if gasPrice is available */
+    gasCost?: bigint;
+}
+
+/**
+ * Handles the complete transaction lifecycle:
+ *   read  → readContract via PublicClient
+ *   write → simulate → writeContract → waitForReceipt
+ *
+ * Automatically handles:
+ *   • ABI encoding / decoding (delegated to viem)
+ *   • Gas estimation (via simulation)
+ *   • Simulation before broadcast (catches reverts early)
+ *   • Receipt polling
+ */
+declare class TransactionEngine {
+    private readonly publicClient;
+    private readonly getWalletClient;
+    constructor(publicClient: PublicClient, getWalletClient: () => WalletClient);
+    /**
+     * Execute a read-only contract call (view / pure functions).
+     * Returns the decoded output — single values or tuples.
+     */
+    read(params: ReadContractParams): Promise<unknown>;
+    /**
+     * Execute a state-mutating contract call:
+     *   1. Simulate the transaction (surfaces revert reasons before spending gas)
+     *   2. Broadcast the signed transaction
+     *   3. Wait for on-chain confirmation
+     *
+     * @returns { hash, receipt } — the tx hash and on-chain receipt
+     */
+    write(params: WriteContractParams): Promise<TransactionResult>;
+    /**
+     * Estimate gas for a write transaction.
+     * Useful for displaying fee previews before the user confirms.
+     */
+    estimateGas(params: WriteContractParams): Promise<GasEstimate>;
+}
+
+declare class ContractExecutionError extends Error {
+    readonly code: "CONTRACT_EXECUTION_ERROR";
+    readonly functionName?: string;
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        functionName?: string;
+        cause?: Error;
+    });
+}
+declare class SimulationError extends Error {
+    readonly code: "SIMULATION_ERROR";
+    readonly functionName?: string;
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        functionName?: string;
+        cause?: Error;
+    });
+}
+declare class GasEstimationError extends Error {
+    readonly code: "GAS_ESTIMATION_ERROR";
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+declare class TransactionTimeoutError extends Error {
+    readonly code: "TRANSACTION_TIMEOUT";
+    readonly hash?: string;
+    constructor(hash?: string);
+}
 
 interface PriceResult {
     /** Uppercase token symbol (e.g. "ETH", "USDC") */
@@ -706,6 +1029,71 @@ interface Erc1155Contract {
     readonly _abi: Abi;
 }
 
+interface ParsedABI {
+    /** view / pure functions — safe to call without a signer */
+    readFunctions: AbiFunction[];
+    /** nonpayable / payable functions — require a signer */
+    writeFunctions: AbiFunction[];
+    /** payable subset of writeFunctions */
+    payableFunctions: AbiFunction[];
+    /** all events declared on the contract */
+    events: AbiEvent[];
+    /** the constructor, if present */
+    constructor?: AbiConstructor;
+}
+type FunctionKind = 'read' | 'write' | 'payable';
+interface GeneratedMethod {
+    name: string;
+    kind: FunctionKind;
+    /** Human-readable TypeScript signature */
+    signature: string;
+    /** Parameter names + types */
+    params: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+
+/**
+ * Parse a raw ABI array and classify every item into read functions,
+ * write functions, payable functions, events, and the constructor.
+ *
+ * Results are memoized by object identity — passing the same const ABI
+ * reference across multiple calls costs only a single WeakMap lookup.
+ *
+ * @throws {InvalidABIError} when the input is not a valid ABI array
+ */
+declare function parseABI(abi: Abi): ParsedABI;
+/** Check whether a function mutates state (requires a signer) */
+declare function isWriteFunction(fn: AbiFunction): boolean;
+/** Check whether a function can receive ETH */
+declare function isPayableFunction(fn: AbiFunction): boolean;
+/**
+ * Generate a human-readable TypeScript method signature from an ABI function.
+ * Useful for tooling, code generation, and documentation.
+ */
+declare function generateMethodSignature(fn: AbiFunction): GeneratedMethod;
+/**
+ * Generate TypeScript method signatures for all functions in a parsed ABI.
+ * Used by the CLI to produce fully typed contract client code.
+ */
+declare function generateAllMethodSignatures(parsed: ParsedABI): GeneratedMethod[];
+
+declare class InvalidABIError extends Error {
+    readonly code: "INVALID_ABI";
+    constructor(message: string);
+}
+declare class UnsupportedABIItemError extends Error {
+    readonly code: "UNSUPPORTED_ABI_ITEM";
+    readonly itemType: string;
+    constructor(itemType: string);
+}
+declare class DuplicateFunctionError extends Error {
+    readonly code: "DUPLICATE_FUNCTION";
+    readonly functionName: string;
+    constructor(name: string);
+}
+
 declare class NetworkMismatchError extends Error {
     readonly code: "NETWORK_MISMATCH";
     readonly expected: string;
@@ -744,7 +1132,7 @@ declare class WalletProxy {
     private readonly ensureReady;
     constructor(engine: WalletEngine, ensureReady: () => Promise<void>);
     create(): Promise<CreatedWallet>;
-    importMnemonic(mnemonic: string, accountIndex?: number): Promise<ImportedWalletFromMnemonic>;
+    importMnemonic(mnemonic: string, addressIndex?: number): Promise<ImportedWalletFromMnemonic>;
     importPrivateKey(privateKey: Hex): Promise<ImportedWalletFromPrivateKey>;
     address(): Address;
     getSigner(): WalletClient;
@@ -1183,4 +1571,4 @@ declare class TelemetryClient {
     private _flushBeacon;
 }
 
-export { ApiKeyRequiredError, type AwarizonConfig, AwarizonWeb3, CHAINLINK_FEEDS, CHAINS, COINGECKO_IDS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type ContractRegistryEntry, ERC1155_ABI, ERC20_ABI, ERC721_ABI, type Erc1155Contract, type Erc20Contract, type Erc721Contract, type EventUnsubscribe, InvalidApiKeyError, NetworkMismatchError, type PayableOptions, PriceEngine, type PriceResult, ProviderError, type SDKWalletInfo, TelemetryClient, type TelemetryEvent, type TelemetryEventType, UnsupportedChainError, getChainTransport, getSupportedChainIds, resolveChain };
+export { ApiKeyRequiredError, type AwarizonConfig, AwarizonWeb3, CHAINLINK_FEEDS, CHAINS, COINGECKO_IDS, type ChainChangeEvent, ChainMismatchError, ChainSwitchError, type ConnectorInfo, type ContractConfig, ContractExecutionError, type ContractInstance, ContractNotLoadedError, type ContractRegistryEntry, type CreatedWallet, DuplicateFunctionError, type EIP1193Provider, ERC1155_ABI, ERC20_ABI, ERC721_ABI, type Erc1155Contract, type Erc20Contract, type Erc721Contract, type EventUnsubscribe, GasEstimationError, type ImportedWalletFromMnemonic, type ImportedWalletFromPrivateKey, InvalidABIError, InvalidApiKeyError, InvalidMnemonicError, InvalidPrivateKeyError, NetworkMismatchError, type PayableOptions, PriceEngine, type PriceResult, ProviderError, type SDKWalletInfo, type SignTypedDataParams, SimulationError, TelemetryClient, type TelemetryEvent, type TelemetryEventType, TransactionEngine, type TransactionResult, TransactionTimeoutError, UnsupportedABIItemError, UnsupportedChainError, type WalletChangeEvent, WalletEngine, WalletNotConnectedError, generateAllMethodSignatures, generateMethodSignature, getChainTransport, getSupportedChainIds, isPayableFunction, isWriteFunction, parseABI, resolveChain };