Chainbench provides flexible options for running blockchain infrastructure benchmarks. This guide covers the basics of executing tests and common patterns.
Basic Test Execution
To start a load test, use the chainbench start command with your desired configuration:
chainbench start --profile ethereum.general --users 50 --workers 2 --test-time 1h --target https://your-node-url
If you installed Chainbench using Poetry, prefix all commands with poetry run:poetry run chainbench start --profile ethereum.general --users 50 --workers 2 --test-time 1h --target https://your-node-url
Testing Individual Methods
You can test a specific RPC method instead of a full profile:
chainbench start eth_blockNumber --users 50 --workers 2 --test-time 12h --target https://node-url --headless --autoquit
eth_blockNumber method calls using the default test data size (S).
List available methods
To see which methods are supported: Choose your method
Select a method from the list and use it as the argument to chainbench start
Run the test
Execute your test with the desired parameters for users, workers, and test duration
Using Profiles
Profiles allow you to test multiple methods with realistic traffic distributions:
chainbench start --profile bsc.general --users 50 --workers 2 --test-time 12h --target https://node-url --headless --autoquit
Built-in Profiles
Chainbench includes profiles for:
- Ethereum (
ethereum.general)
- Binance Smart Chain (
bsc.general)
- Polygon (
polygon.general)
- Solana (
solana.general)
- Avalanche, Arbitrum, Base, Fantom, Gnosis, Optimism, Ronin, and more
- Generic EVM profiles:
evm.light and evm.heavy
List all available profiles with: Common Parameters
Essential Options
--users or -u: Number of simulated users (default: 100)--workers or -w: Number of worker threads (default: 8)--test-time or -t: Duration of the test (e.g., 1h, 30m, 12h)--target: The blockchain node URL to test--spawn-rate or -r: Users spawned per second (default: 10)
Test Data Configuration
chainbench start --profile evm.light --users 50 --workers 2 --test-time 1h --target https://node-url --size L --headless --autoquit
| Size | Blocks |
|---|
| XS | 10 |
| S | 100 |
| M | 1,000 |
| L | 10,000 |
| XL | 100,000 |
Larger data sizes result in longer test data generation time before the test starts. Start with smaller sizes (XS or S) for initial testing.
Load Pattern Shapes
Control how load is distributed over time using the --shape flag:
chainbench start --profile ethereum.general --users 100 --workers 2 --test-time 1h --target https://node-url --shape spike --headless --autoquit
Available Shapes
- ramp-up (default): Linear increase at spawn-rate until target users reached
- step: Load increases in steps based on spawn-rate
- spike: Ramps to 10% users for 40% of test duration, spikes to 100% for 20%, then drops back to 10%
List all available shapes: Custom Profile Directories
Use custom profiles from a specific directory:
chainbench start --profile-dir /path/to/profiles --profile my-profile --users 50 --workers 2 --test-time 12h --target https://node-url --headless --autoquit
chainbench start --profile-dir /path/to/profiles --profile bsc.my-profile --users 50 --workers 2 --test-time 12h --target https://node-url --headless --autoquit
Chainbench supports one level of nesting for profile organization.
Reference Node for Test Data
Generate test data from a different node than the one being tested:
chainbench start --profile ethereum.general --users 50 --workers 2 --test-time 1h --target https://node-to-test --ref-url https://reference-node --headless --autoquit
Excluding Specific Methods
Exclude methods with specific tags from your test:
chainbench start --profile evm.heavy --users 50 --workers 2 --test-time 1h --target https://node-url -E slow -E expensive --headless --autoquit
You can specify the --exclude-tags (or -E) flag multiple times to exclude multiple tag categories.
Debug and Trace Methods
By default, debug and trace methods are excluded. Enable them with:
chainbench start --profile evm.heavy --users 50 --workers 2 --test-time 1h --target https://node-url --debug-trace-methods --headless --autoquit
Debug and trace methods can be resource-intensive. Use with caution and monitor your node’s performance.