Moto: Marketable metrics. Engineer approved chaos.

Gasper = MGas/s + throughput

A k6 extension for load testing Ethereum RPC nodes. Gasper allows you to simulate multiple wallets sending transactions concurrently to measure node performance and reliability.

Table of Contents

• Features
• Prerequisites
• Nix Development Environment
• Quick Start
• Development Environment
• Metrics
• Known Issues

Docs

• QUERIES.md
• TESTS.md

Features

• Fire-and-forget transaction sending
• Transaction confirmation tracking
• Multiple node testing simultaneously
• Metrics collection (InfluxDB + Grafana dashboards)
• Configurable wallet management
• Support for both new and existing wallets

Prerequisites

• Go 1.24+
• xk6 (k6 extension builder)
• jq
• solc
• forge
• Docker and Docker Compose (for metrics infrastructure)
• Running Ethereum node(s) for testing

Nix Development Environment

If you're not using NixOS, start by installing the nix package manager.

Once that's set up:

• If you have direnv installed, it will automatically load the required development packages for you.
• If not, you can manually run nix develop in the project directory to achieve the same effect.

ISSUES:

• Ensure that gvm is not preselecting a Go version, as this may cause build to fail

Quick Start

1. Start the metrics infrastructure:

docker-compose up -d

2. Add this environment variable to your shell:

export K6_INFLUXDB_ORGANIZATION=gasper-org
export K6_INFLUXDB_BUCKET=gasper
export K6_INFLUXDB_TOKEN=my-token

3a. Download the latest binary from the releases page and extract it to a directory of your choice.

3b. Use Docker to run the binary:

docker pull ghcr.io/mysteryforge/gasper:latest

4. Run a Hello World test:

Binary:

./{pth_to_binary}/gasper run --out influxdb=http://localhost:8086/gasper examples/integrity/hello.js

Docker:

docker run --network host -v $(pwd)/examples:/examples ghcr.io/mysteryforge/gasper:latest run --out xk6-influxdb=http://localhost:80
86/gasper /examples/integrity/hello.js

Development Environment

To view metrics in grafana follow the Quick Start section, first two steps.

1. Download xk6ea from https://github.com/grafana/xk6/releases and add it to your PATH.

xk6ea --version

Output:
xk6ea version 0.19.1

2. Install submodules:

make init-submodule

Manually

git submodule add https://github.com/OpenZeppelin/openzeppelin-contracts contracts/lib/openzeppelin-contracts
git submodule add https://github.com/foundry-rs/forge-std contracts/lib/forge-std

3. Manually install solc(not necessary if you are using nix) v0.8.28 from https://github.com/ethereum/solidity/releases

solc --version

Output:
solc, the solidity compiler commandline interface
Version: 0.8.28+commit.7893614a.Linux.g++

4. Build the binary:

make build

5. Run a Hello World test:

make hello

Metrics

Access Grafana at http://localhost:3000 and navigate to Dashboards > Blockspeed to view test results.

Metrics are stored in InfluxDB and can be visualized in Grafana:

• Transaction throughput
• Response times
• Success/failure rates
• Gas usage

See QUERIES.md for useful queries.

Known Issues

• Prometheus remote write is experimental in k6, using InfluxDB for now
• xk6 needs a stable nix package

Technical Report: Network Configuration for ETH node in Docker

When running ETH nodes in Docker, using the --network host flag is essential for optimal performance and functionality for the following reasons:

• High Connection Volume: ETH node handles a large number of concurrent connections during load testing. Docker's default bridge networking introduces NAT overhead that becomes a bottleneck under high connection rates.
• Network Performance: Host networking eliminates the additional network layer between the container and host, reducing latency by 15-20% and increasing throughput for transaction processing.
• Port Range Limitations: Under high load, ETH node may establish thousands of ephemeral connections. Bridge networking has limitations with port mapping that can exhaust the available port range.
• P2P Connectivity: For blockchain node operation, direct access to the host network stack is required for optimal peer discovery and connection establishment.
• UDP Protocol Support: Some blockchain P2P protocols rely on UDP for discovery, which works more reliably with host networking than with bridge networking.

Using --network host ensures ETH node can handle high transaction volumes without network-related performance degradation or connection failures.

Resources

• https://github.com/grafana/k6
• https://github.com/distribworks/xk6-ethereum
• https://github.com/0xPolygon/polygon-cli

License

All other files within this repository are licensed under the GNU AFFERO GENERAL PUBLIC LICENSE unless stated otherwise.

Redistribution Permission: GatewayFM has kindly granted permission to anyone to redistribute the binaries and source of this project, on condition that this attribution is preserved. This permission does not obligate any contributor to maintain, update, or provide support for the project.

Support

This project is supported by CuteTarantula.

We are a UK-based consultancy specializing in Ethereum and blockchain solutions. Whether you have an exciting project idea or need expert guidance on any of our supported tools, we’re here to help. Don’t hesitate to reach out, we’d love to collaborate with you!