​
Configuration Overview

The LocalNodeManager constructor accepts a NodeConfig object that allows you to customize the behavior of your local Anvil node. All configuration options are optional, with sensible defaults provided.

​
Basic Configuration

import { LocalNodeManager } from '@coinbase/onchaintestkit'

const node = new LocalNodeManager({
    chainId: 84532,
    port: 8545,
    blockTime: 1,
})

​
NodeConfig Type

interface NodeConfig {
    port?: number;
    portRange?: [number, number];
    chainId?: number;
    mnemonic?: string;
    forkUrl?: string;
    forkBlockNumber?: bigint;
    forkRetryInterval?: number;
    defaultBalance?: bigint;
    totalAccounts?: number;
    blockTime?: number;
    blockGasLimit?: bigint;
    noMining?: boolean;
    hardfork?: "london" | "berlin" | "cancun";
}

​
Configuration Options

​
Network Settings

​
chainId
number
default:"84532"
The chain ID for the network. Common values:
  • 1 - Ethereum Mainnet
  • 8453 - Base Mainnet
  • 84532 - Base Sepolia
  • 31337 - Default Hardhat/Anvil
​
hardfork
string
Specific hardfork to use. Options: "london", "berlin", "cancun"

​
Port Configuration

​
port
number
Fixed port number for the RPC server. If not specified, a port will be dynamically allocated.
​
portRange
[number, number]
default:"[10000, 20000]"
Port range for automatic port selection when port is not specified.

​
Fork Mode

​
forkUrl
string
URL to fork from (e.g., mainnet or testnet RPC endpoint). Enables fork mode.
forkUrl: "https://mainnet.base.org"
​
forkBlockNumber
bigint
Specific block number to fork from. Must be used with forkUrl.
forkBlockNumber: 18000000n
​
forkRetryInterval
number
Retry interval for fork requests in milliseconds.

​
Account Configuration

​
mnemonic
string
Mnemonic phrase for generating test accounts.
mnemonic: "test test test test test test test test test test test junk"
​
defaultBalance
bigint
default:"10000 ETH"
Default balance for test accounts in wei.
defaultBalance: parseEther("100")
​
totalAccounts
number
default:"10"
Number of test accounts to generate.

​
Mining Configuration

​
blockTime
number
default:"0"
Time between blocks in seconds. Set to 0 for instant mining (default).
​
noMining
boolean
default:"false"
Disable automatic mining. Blocks must be manually mined with node.mine().
​
blockGasLimit
bigint
Gas limit per block.

​
Configuration Examples

​
Basic Local Testing

const node = new LocalNodeManager({
    chainId: 31337,
    defaultBalance: parseEther("1000"),
    totalAccounts: 5,
})

​
Fork Mainnet

const node = new LocalNodeManager({
    chainId: 1,
    forkUrl: process.env.ETH_MAINNET_RPC,
    forkBlockNumber: 18500000n,
    hardfork: "cancun",
})

​
Base Sepolia Fork

const node = new LocalNodeManager({
    chainId: baseSepolia.id,
    forkUrl: process.env.BASE_SEPOLIA_RPC,
    forkBlockNumber: BigInt(process.env.FORK_BLOCK || "0"),
    mnemonic: process.env.TEST_MNEMONIC,
})

​
Manual Mining Mode

const node = new LocalNodeManager({
    noMining: true,
    blockGasLimit: 30_000_000n,
})

await node.start()

// Manually mine blocks when needed
await node.mine(1)

​
Fixed Port Configuration

const node = new LocalNodeManager({
    port: 8545, // Always use port 8545
    chainId: 31337,
})

​
Custom Port Range

const node = new LocalNodeManager({
    portRange: [20000, 30000], // Use ports 20000-30000
    chainId: 31337,
})

​
Environment Variables

It’s recommended to use environment variables for sensitive or environment-specific configuration: 
# .env.test
E2E_TEST_FORK_URL=https://mainnet.base.org
E2E_TEST_FORK_BLOCK_NUMBER=18500000
E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk"

const node = new LocalNodeManager({
    chainId: baseSepolia.id,
    forkUrl: process.env.E2E_TEST_FORK_URL,
    forkBlockNumber: BigInt(process.env.E2E_TEST_FORK_BLOCK_NUMBER ?? "0"),
    mnemonic: process.env.E2E_TEST_SEED_PHRASE,
})

​
Default Values

When no configuration is provided, these defaults are used:
  • chainId: 84532 (Base Sepolia)
  • portRange: [10000, 20000]
  • defaultBalance: 10000 ETH per account
  • totalAccounts: 10
  • blockTime: 0 (instant mining)
  • noMining: false

​
Best Practices

1

Use Environment Variables

Store RPC URLs, mnemonics, and API keys in environment variables
2

Fork for Integration Tests

Use fork mode to test against real mainnet/testnet state
3

Dynamic Ports for Parallel Tests

Let the system allocate ports automatically for parallel test execution
4

Consistent Configuration

Share configuration between tests using a common config file

​
Next Steps