linea-monorepo/linea-besu-package

Linea Besu Distribution

This project uses Gradle to manage dependencies, build tasks, and create distributions for linea-besu with all the necessary plugins to run a node for operators. The build process will also create a Docker image that can be used to run a node with a specific profile.

Run with Docker

Step 1. Download configuration files

You can start with the Docker Compose files located in the docker directory.

Step 2. Update the Docker Compose file

In the docker-compose.yaml file, update the --p2p-host command to include your public IP address. For example:

--p2p-host=103.10.10.10

Update plugin-linea-l1-rpc-endpoint config with your L1 RPC endpoint. You should replace YOUR_L1_RPC_ENDPOINT with your endpoint, like:

--plugin-linea-l1-rpc-endpoint=https://mainnet.infura.io/v3/PROJECT_ID

This is required to enable RPC queries using "FINALIZED" block tag. Linea Finalization status is based on L1 RPC endpoint's response

Step 2. Start the Besu node

docker compose -f ./linea-besu-package/docker/docker-compose-basic-mainnet.yaml up

Alternatively, to run a node with a specific profile, set the BESU_PROFILE environment variable to the desired profile name:

docker run -e BESU_PROFILE=basic-mainnet consensys/linea-besu-package:latest

Or use a specific release image tag

docker run -e BESU_PROFILE=basic-mainnet consensys/linea-besu-package:2.1.0-20250507100634-6dc9db9

Run with a binary distribution

Step 1. Install Linea Besu from packaged binaries

• Download the linea-besu-package-<release>.tar.gz from the assets.
• Unpack the downloaded files and change directory into the linea-besu/besu directory.

Display Besu command line help to confirm installation:

bin/besu --help

Step 2. Start the Besu client

Note the YOUR_L1_RPC_ENDPOINT. You should replace this with your L1 RPC endpoint.

This is required to enable RPC queries using "FINALIZED" tag. Linea Finalization status is based on L1 RPC endpoint's response

bin/besu --profile=advanced-mainnet --plugin-linea-l1-rpc-endpoint=YOUR_L1_RPC_ENDPOINT

Build from source locally

1. Make changes to linea-besu-package/versions.env as needed

2. Cd into linea-besu-package

3. Run make clean && make build (check the Makefile for build options)

4. The docker image (i.e. default as consensys/linea-besu-package:local) should be created locally

Note:

To build with specific platform (e.g. linux/amd64) and image tag (e.g. xxx), do the following:

make clean && PLATFORM=linux/amd64 TAG=xxx make build

To run the e2e test locally with the locally-built linea-besu-package image (e.g. tagged as xxx), do the following:

TAG=xxx make run-e2e-test

How-To Release

1. Make a branch with changes to linea-besu-package/versions.env as needed

2. Go to the actions tab and click on the workflow linea-besu-package-release and select the target branch for making a release with besu and plugin versions based on linea-besu-package/versions.env

3. If release prefix is not given, LINEA_TRACER_PLUGIN_VERSION in the target versions.env file will be used, and the resultant release tag would be linea-besu-package-[releasePrefix]-[YYYYMMDDHHMMSS]-[shortenCommitHash] and the docker image tag would be [releasePrefix]-[YYYYMMDDHHMMSS]-[shortenCommitHash]

4. Once the workflow is done successfully, go to the releases page and you should find the corresponding release info along with the docker image tag

Additionally, the latest tag will be updated to match this release

Profiles

This project leverages Besu Profiles to enable multiple startup configurations for different node types.

During the build process, all TOML files located in the linea-besu-package/linea-besu/profiles directory will be incorporated into the package. These profiles are crucial for configuring the node, as each one specifies the necessary plugins and CLI options to ensure Besu operates correctly.

Each profile is a TOML file that outlines the plugins and CLI options to be used when starting the node. For example:

# required plugins to run a sequencer node
plugins=["LineaExtraDataPlugin","LineaEndpointServicePlugin","LineaTransactionPoolValidatorPlugin","LineaTransactionSelectorPlugin"]

# required options to configure the plugins above
plugin-linea-module-limit-file-path="config/trace-limits.mainnet.toml"
# Other required plugin options
# ...

# Other Besu options
# ...

Currently, the following profiles are available:

Profile Name	Description	Network
basic-mainnet	Creates a basic Linea Node.	Mainnet
advanced-mainnet	Creates a Linea Node with linea_estimateGas and finalized tag updater plugin.	Mainnet
basic-sepolia	Creates a basic Linea Node.	Sepolia
advanced-sepolia	Creates a Linea Node with linea_estimateGas and finalized tag updater plugin.	Sepolia