Local Devnet

The Docker Compose devnet bundled with base/base spins up a complete local Base network for integration testing, debugging, and flashblocks experiments without touching a public testnet. Its configuration lives in etc/docker/docker-compose.yml.

Prerequisites

Before starting the devnet, make sure you have:

Docker and Docker Compose installed and running.
The repository cloned and all prerequisites in place.

Pre-Pulling Images

The devnet uses several Docker images. To avoid long waits on the first start, pull them ahead of time:

just system-tests-pull-images

Starting the Devnet

The devnet recipe handles the full lifecycle: it stops any existing devnet, builds fresh images, and starts the stack:

just devnet

This is the recommended way to start or restart the devnet. It ensures you are running the latest code and that there is no stale state from a previous run.

Stopping the Devnet

To stop all containers and clean up resources:

just devnet-down

This removes the containers and associated volumes, giving you a clean slate for the next start.

Monitoring

Block Status

Check the current block numbers and sync status of the devnet nodes:

just devnet-status

This prints block heights and indicates whether nodes are in sync.

Funded Test Accounts

View the pre-funded accounts available for testing:

just devnet-accounts

These accounts come with a balance of test ETH and are ready to use for sending transactions.

Container Logs

Stream logs from one or more containers:

# All containers
just devnet-logs

# Specific containers
just devnet-logs sequencer proposer

Logs are streamed in real time. Press Ctrl+C to stop.

Testing on the Devnet

Smoke Tests

Run a basic set of test transactions to verify the devnet is functioning correctly:

just devnet-smoke

This sends a few transactions and verifies they are included in blocks.

Combined Status and Smoke

Run both status checks and smoke tests together:

just devnet-checks

This is a convenient single command that first prints the devnet status and then runs the smoke tests.

Load Testing

Start the Contender load generator to stress-test the devnet:

just devnet-load

This generates a sustained stream of transactions, which is useful for benchmarking block production, measuring throughput, and testing behavior under pressure.

Flashblocks Streaming

The devnet supports flashblocks — sub-block-time transaction confirmations streamed over WebSocket. To connect and watch flashblocks:

just devnet-flashblocks

This opens a WebSocket connection to the devnet and prints flashblock messages as they arrive (typically every 200ms). It is a quick way to verify that the flashblocks pipeline is working end-to-end.

Typical Workflow

A common development loop with the devnet looks like this:

Make code changes.
Start a fresh devnet:
Terminal window
```
just devnet
```
Verify it is running:
Terminal window
```
just devnet-status
```
Run smoke tests:
Terminal window
```
just devnet-smoke
```
Stream flashblocks to test your changes:
Terminal window
```
just devnet-flashblocks
```
Check logs for issues:
Terminal window
```
just devnet-logs
```
When finished, tear it down:
Terminal window
```
just devnet-down
```

Troubleshooting

Containers fail to start — Make sure Docker is running and your user is in the docker group. Run docker compose version to verify the Compose plugin is installed.

Port conflicts — If another service is using the ports the devnet needs, stop that service first or edit etc/docker/docker-compose.yml to remap ports.

Stale state — If the devnet behaves unexpectedly after code changes, run just devnet-down followed by just devnet to start from a clean state.

Slow first start — The first run pulls several Docker images and may build containers from scratch. Run just system-tests-pull-images ahead of time to pre-pull base images.