LocalNodeManager Class

Manages the lifecycle and state of a local Anvil Ethereum node for testing. Handles dynamic port allocation, process management, and exposes a rich set of methods for manipulating the blockchain state.

Constructor

new LocalNodeManager(config?: NodeConfig)
Creates a new instance with the specified configuration.
config
NodeConfig
Optional node configuration options. See Configuration for details.

Properties

port
number
The allocated port number, or -1 if not started.
rpcUrl
string
The RPC URL for the running node (e.g., http://localhost:12345).

Lifecycle Methods

start()

async start(): Promise<void>
Starts the Anvil node with the configured options. Allocates a port, spawns the process, and waits for readiness.
const node = new LocalNodeManager()
await node.start()
console.log(`Node running at ${node.rpcUrl}`)

stop()

async stop(): Promise<void>
Stops the running Anvil node and cleans up resources.
await node.stop()

getPort()

getPort(): number | null
Returns the allocated port number for this node instance, or null if not started.
const port = node.getPort()
// Use port for configuration

State Management Methods

snapshot()

async snapshot(): Promise<string>
Takes a snapshot of the current chain state. Returns a snapshot ID for later use with revert().
const snapshotId = await node.snapshot()
// Make changes...
await node.revert(snapshotId)

revert()

async revert(snapshotId: string): Promise<void>
Reverts the chain state to a previous snapshot.
snapshotId
string
required
The ID returned from snapshot()

reset()

async reset(forkBlock?: bigint): Promise<void>
Resets the chain state to the initial state or a specified fork block.
forkBlock
bigint
Optional block number to reset to (when in fork mode)

Mining Methods

mine()

async mine(blocks = 1): Promise<void>
Mines a specified number of blocks.
blocks
number
default:"1"
Number of blocks to mine
// Mine 10 blocks
await node.mine(10)

setAutomine()

async setAutomine(enabled: boolean): Promise<void>
Enables or disables automatic block mining.
enabled
boolean
required
Whether to enable automatic mining
// Disable automine for manual control
await node.setAutomine(false)

Time Manipulation Methods

setNextBlockTimestamp()

async setNextBlockTimestamp(timestamp: number): Promise<void>
Sets the timestamp for the next block.
timestamp
number
required
Unix timestamp in seconds

increaseTime()

async increaseTime(seconds: number): Promise<void>
Increases chain time by the specified number of seconds.
seconds
number
required
Number of seconds to advance
// Advance time by 1 day
await node.increaseTime(86400)

setTime()

async setTime(timestamp: number): Promise<void>
Sets absolute chain time.
timestamp
number
required
Unix timestamp in seconds

Account Management Methods

getAccounts()

async getAccounts(): Promise<string[]>
Returns an array of available account addresses.
const accounts = await node.getAccounts()
console.log(`Available accounts: ${accounts.length}`)

setBalance()

async setBalance(address: string, balance: bigint): Promise<void>
Sets the balance for the specified address.
address
string
required
The address to modify
balance
bigint
required
The new balance in wei
await node.setBalance(
  "0x742d35Cc6634C0532925a3b844Bc9e7595f8fA65",
  parseEther("100")
)

setNonce()

async setNonce(address: string, nonce: number): Promise<void>
Sets the nonce for the specified address.
address
string
required
The address to modify
nonce
number
required
The new nonce value

impersonateAccount()

async impersonateAccount(address: string): Promise<void>
Enables impersonation of the specified account.
address
string
required
The address to impersonate
// Impersonate a whale address
await node.impersonateAccount("0xWhaleAddress")

stopImpersonatingAccount()

async stopImpersonatingAccount(address: string): Promise<void>
Disables impersonation of the specified account.
address
string
required
The address to stop impersonating

Contract Methods

setCode()

async setCode(address: string, code: string): Promise<void>
Sets the contract code at the specified address.
address
string
required
The contract address
code
string
required
The contract bytecode (hex string)

setStorageAt()

async setStorageAt(
  address: string, 
  slot: string, 
  value: string
): Promise<void>
Sets the storage value at the specified slot for a contract.
address
string
required
The contract address
slot
string
required
The storage slot (hex string)
value
string
required
The value to store (hex string)

Gas Configuration Methods

setNextBlockBaseFeePerGas()

async setNextBlockBaseFeePerGas(fee: bigint): Promise<void>
Sets the base fee for the next block (EIP-1559).
fee
bigint
required
The base fee in wei

setMinGasPrice()

async setMinGasPrice(price: bigint): Promise<void>
Sets the minimum gas price.
price
bigint
required
The minimum gas price in wei

Network Methods

setChainId()

async setChainId(chainId: number): Promise<void>
Sets the chain ID.
chainId
number
required
The new chain ID

Next Steps