base/base: the components behind an Ethereum rollup

A monorepo of crates, not a single application

Base is a rollup built on Ethereum, and this repository holds the components that run it. The repository description is simply that it contains all components used to run Base.

The Cargo workspace file shows the shape. There are crate groups for the batcher, the builder, common code, consensus, execution, infrastructure, proof and prover services, and utilities, plus bin/ entries that split alphabetically into ranges, with separate members for the proposer and for prover binaries. The default members are the bin groups and the proposer, which means a plain cargo build gives you the operator binaries rather than the whole workspace including the proof system.

Some members are excluded from the workspace entirely, actions/fixtures and crates/proof/zk/programs, presumably because they are standalone or need their own dependency resolution. The resolver is version 2 and the edition is 2024 with a rust-version floor of 1.96, which sets the minimum toolchain for anyone building from source.

The lint configuration is unusually strict for a rollup repository. missing-docs, unreachable-pub, unnameable-types and missing-debug-implementations are all warnings, rust-2018-idioms and unused-must-use are denies, and the clippy set enables essentially all default lints at warn priority with performance and cloning lints turned on individually, including redundant-clone, cloned-instead-of-copied and unnecessary-to-owned.

That lint surface tells you something about how the code is expected to be written and reviewed.

Two containers: the execution engine and the consensus node

Running a node is a Docker Compose operation, and the compose file defines two services built from the same Dockerfile with a shared target.

services:
  execution:
    image: ghcr.io/base/node:${NODE_TAG:-latest}
    build:
      context: .
      dockerfile: etc/docker/Dockerfile.rust-services
      target: base
      args:
        PROFILE: ${PROFILE:-release}
    restart: unless-stopped
    ports:
      - "8545:8545" # RPC
      - "8546:8546" # websocket
      - "7301:6060" # metrics
      - "30303:30303" # P2P TCP
      - "30303:30303/udp" # P2P UDP
    command: ["bash", "./execution-entrypoint"]
    volumes:
      - ${HOST_DATA_DIR:-./reth-data}:/data
    env_file:
      - ${NETWORK_ENV:-.env.mainnet} # Use .env.mainnet by default, override with .env.sepolia for testnet

The execution service exposes the RPC port and a websocket port, maps a metrics port, and publishes the P2P ports for both TCP and UDP. The consensus service depends on execution, maps its RPC and P2P ports separately, and adds a pprof port. Both read their environment from a file chosen by the NETWORK_ENV variable, defaulting to .env.mainnet and overridable with .env.sepolia for the testnet.

The data directory is a bind mount with a default of ./reth-data, and the image tag defaults to latest but can be pinned with NODE_TAG.

# Mainnet (default):
docker compose up --build

# Testnet:
NETWORK_ENV=.env.sepolia docker compose up --build

# Pin a published image (no compile):
NODE_TAG=v1.3.0 docker compose up

Those three commands cover the practical cases: build and run locally, run the testnet configuration, or pull a pinned published image without compiling anything.

The node moved into this repository

A change worth noting happened here. The repository now hosts the public Base node that was previously published from a separate base/node repository, and the root docker-compose.yml pulls the ghcr.io/base/node image. Passing --build compiles the tree instead, and the local development path is documented separately under the devnet section.

For operators this means one place to look. The public node image and the source that produces it now live in the same repository, and the documentation page for node operators covers hardware requirements, snapshots, Flashblocks and historical proofs.

Two environment variables are mandatory before you start. You have to set BASE_NODE_L1_ETH_RPC and BASE_NODE_L1_BEACON in .env.mainnet or .env.sepolia, and those point the rollup at its Ethereum layer one, both for the execution RPC and for the beacon chain. A rollup node without an L1 connection cannot derive or settle, so this is the first thing to configure and the most common reason a first run does not progress.

The repository also carries SECURITY.md, a CONTRIBUTING.md, an AGENTS.md and a CLAUDE.md alongside a rust-toolchain.toml, a rustfmt.toml, a clippy.toml, a deny.toml for dependency licence checking, and a lychee.toml for link checking in CI.

Two devnets, one real state and one synthetic

There are two local development environments, and they solve different problems.

The Docker devnet gives you a fresh L1 and L2 stack. Its listed use is sequencing, derivation, batching and hardfork activation, and it is started with just devnet up-single. In other words, you get the entire stack as a controlled system where you can trigger a hardfork or watch a batch being derived.

The snapshot devnet gives you real Base mainnet state and contracts, so you can act as any account, with 200ms blocks and no L1. It is a two step process: download the snapshot into a directory, then run it from that directory.

The two steps are `just devnet snapshot download --dir <dir>` and then `just devnet snapshot run --dir <dir>`.

The distinction matters for what you are testing. If you want to exercise the rollup machinery itself, the Docker devnet is the one, because it has an L1 to derive against. If you want realistic state, real contracts and real balances, the snapshot devnet is faster and simpler, and the 200ms block time makes it usable as an interactive environment.

The docs guide at docs/guides/DEVNET.md covers every local environment in the repository, and the Justfile is the entry point for the commands.

Patched anvil and forge published on every push

One of the more unusual pieces of the repository is a private toolchain distribution. Every push to main publishes patched anvil and forge binaries to GHCR as ghcr.io/base/base-anvil.

Those are the standard Foundry development tools, anvil for a local EVM and forge for testing and scripting, built with Base specific patches. That matters for anyone writing tests against a Base local chain, because the upstream tools may not know about the rollup's specific behaviour.

The tagging convention is spelled out. Use immutable sha-<commit> tags for pinned downstream tests, or main for the latest successful main build. The distinction is a good one: a CI pipeline that pins to a commit hash gets a reproducible toolchain, while main tracks whatever the last green build produced.

The repository also carries an acceptance/ directory and an audits/ directory alongside crates/, etc/ and bin/, which suggests the test suite spans more than unit tests inside the crates.

The wider Base story, and where this repository fits in it

It helps to separate Base the network from Base this repository.

Base the network is described as a cheap, fast and open platform providing one second and sub-cent transactions to anyone in the world. The other stated reasons are that Base commits to helping developers grow their user base by distributing their apps through official Base channels, that it has delivered grants to more than a thousand builders with plans to continue, and that builders get access to tooling for onchain experiences in AI, social, media and entertainment.

This repository is the infrastructure half. The docs site covers three things for application developers: connecting a wallet, running a node, and deploying an app. The specs site holds the protocol overview including past and upcoming upgrades.

So if you are building on Base, you probably want the docs and the specs, and you only need this repository if you are running infrastructure or want to read and modify the node implementation itself.

The binaries themselves are installed with baseup, the installer in the baseup directory of this repository, which fetches the GitHub release binaries for the repository.

curl -fsSL https://raw.githubusercontent.com/base/base/main/baseup/install | bash

The licence is MIT, recorded in the LICENSE file and in the Cargo workspace metadata.

Editorial conclusion

Adopt base/base if you need to run Base infrastructure yourself, either a public node against mainnet or a local devnet for testing, since the repository now contains the whole stack rather than only the node. Do not adopt it if you just want to talk to Base from an application, since for that the documented path is connecting a wallet or using the hosted RPC. Verify first that your machine meets the hardware requirements in the node operator docs, that you set BASE_NODE_L1_ETH_RPC and BASE_NODE_L1_BEACON in the environment file for the network you intend to run, that you pin NODE_TAG when you want a reproducible deployment rather than tracking latest, and that the Rust toolchain matches the 1.96 minimum the workspace declares.

Frequently asked questions

Official sources

1. base/base on GitHub
2. License: MIT
3. Project website
4. README
5. Releases