@coinbase/onchaintestkit/dist/src/node/LocalNodeManager.d.ts

End-to-end testing toolkit for blockchain applications, powered by Playwright

import { NodeConfig } from "./types";
/**
 * LocalNodeManager provides a comprehensive interface for managing a local Anvil Ethereum node.
 * It handles node lifecycle, state management, and provides methods for manipulating blockchain state.
 *
 * Features:
 * - Node lifecycle management (start/stop)
 * - Chain state manipulation (snapshots, revert, reset)
 * - Time control (time travel, block mining)
 * - Account management (balance setting, impersonation)
 * - Network configuration (gas prices, chain ID)
 * - Automatic port allocation for parallel test execution
 *
 * @example
 * ```typescript
 * const node = new LocalNodeManager({
 *   chainId: 1337,
 *   forkUrl: process.env.MAINNET_RPC_URL
 * });
 *
 * await node.start();
 * const snapshot = await node.snapshot();
 * // Run tests...
 * await node.revert(snapshot);
 * await node.stop();
 * ```
 */
export declare class LocalNodeManager {
    private process;
    private provider;
    private config;
    private allocatedPort;
    private static DEFAULT_PORT_RANGE;
    private static MAX_PORT_ALLOCATION_RETRIES;
    /**
     * Creates a new LocalNodeManager instance with the specified configuration
     * @param config - Node configuration options
     */
    constructor(config?: NodeConfig);
    /**
     * Checks if a port is available for use
     * @param port - The port to check
     * @returns Promise that resolves to true if port is available, false otherwise
     * @private
     */
    private isPortAvailable;
    /**
     * Finds an available port within the configured range
     * @returns Promise that resolves to an available port number
     * @private
     */
    private findAvailablePort;
    /**
     * Starts the Anvil node with the configured options
     * @throws Error if node is already running or no available ports
     */
    start(): Promise<void>;
    /**
     * Stops the running Anvil node and cleans up resources
     */
    stop(): Promise<void>;
    /**
     * Internal cleanup method to ensure proper resource cleanup
     * @private
     */
    private cleanup;
    /**
     * Get the allocated port for this node instance
     * @returns Port number or null if node is not started
     */
    getPort(): number | null;
    /**
     * Port getter for easier access
     * @returns The allocated port number or -1 if not started
     */
    get port(): number;
    get rpcUrl(): string;
    /**
     * Takes a snapshot of the current chain state
     * @returns Snapshot ID that can be used with revert()
     */
    snapshot(): Promise<string>;
    /**
     * Reverts the chain state to a previous snapshot
     * @param snapshotId - ID returned from snapshot()
     */
    revert(snapshotId: string): Promise<void>;
    /**
     * Resets the chain state to initial state or specified fork block
     * @param forkBlock - Optional block number to reset to when in fork mode
     */
    reset(forkBlock?: bigint): Promise<void>;
    /**
     * Mines a specified number of blocks
     * @param blocks - Number of blocks to mine (default: 1)
     */
    mine(blocks?: number): Promise<void>;
    /**
     * Enables or disables automatic block mining
     * @param enabled - Whether to enable auto-mining
     */
    setAutomine(enabled: boolean): Promise<void>;
    /**
     * Sets the timestamp for the next block
     * @param timestamp - Unix timestamp in seconds
     */
    setNextBlockTimestamp(timestamp: number): Promise<void>;
    /**
     * Increases chain time by specified seconds
     * @param seconds - Number of seconds to move forward
     */
    increaseTime(seconds: number): Promise<void>;
    /**
     * Sets absolute chain time
     * @param timestamp - Unix timestamp in seconds
     */
    setTime(timestamp: number): Promise<void>;
    /**
     * Gets list of available accounts
     * @returns Array of account addresses
     */
    getAccounts(): Promise<string[]>;
    /**
     * Sets balance for specified address
     * @param address - Account address
     * @param balance - New balance in wei
     */
    setBalance(address: string, balance: bigint): Promise<void>;
    /**
     * Sets nonce for specified address
     * @param address - Account address
     * @param nonce - New nonce value
     */
    setNonce(address: string, nonce: number): Promise<void>;
    /**
     * Sets contract code at specified address
     * @param address - Contract address
     * @param code - Contract bytecode
     */
    setCode(address: string, code: string): Promise<void>;
    /**
     * Sets storage value at specified slot
     * @param address - Contract address
     * @param slot - Storage slot
     * @param value - New value
     */
    setStorageAt(address: string, slot: string, value: string): Promise<void>;
    /**
     * Sets base fee for next block (EIP-1559)
     * @param fee - Base fee in wei
     */
    setNextBlockBaseFeePerGas(fee: bigint): Promise<void>;
    /**
     * Sets minimum gas price
     * @param price - Min gas price in wei
     */
    setMinGasPrice(price: bigint): Promise<void>;
    /**
     * Sets chain ID
     * @param chainId - New chain ID
     */
    setChainId(chainId: number): Promise<void>;
    /**
     * Enables impersonation of specified account
     * @param address - Address to impersonate
     */
    impersonateAccount(address: string): Promise<void>;
    /**
     * Disables impersonation of specified account
     * @param address - Address to stop impersonating
     */
    stopImpersonatingAccount(address: string): Promise<void>;
    /**
     * Builds command line arguments for Anvil based on configuration
     * @returns Array of command line arguments
     * @private
     */
    private buildAnvilArgs;
    /**
     * Waits for Anvil node to be ready to accept connections
     * @returns Promise that resolves when node is ready
     * @private
     */
    private waitForNodeReady;
    /**
     * Sends JSON-RPC request to Anvil node
     * @param method - RPC method name
     * @param params - RPC method parameters
     * @returns Promise that resolves with RPC response
     * @private
     */
    private send;
}