Skip to main content

Besu

Besu is an open-source Ethereum client developed under the Apache 2.0 license and written in Java.

important

Install and run a Besu node if you want to follow the Linea network by maintaining a local copy of the blockchain. However, if you want to interact with the network and use Linea-specific methods and features, you should install Linea Besu instead.

You can run Besu from a binary distribution or using Docker.

Run using the binary distribution​

Step 1. Install Besu​

Download and install Besu using the instructions in the official documentation.

Step 2. Download the genesis file and Besu configuration file​

Download the genesis file and Besu configuration file.

Mainnet genesis-mainnet.json file and Besu config-mainnet.toml file.

bootnodes

You can choose from a range of bootnodes for Linea Mainnet. The above configuration file uses all bootnodes by default.

The bootnodes page contains a full list of available bootnodes.

Step 3. Define disk space volume (optional)​

Define a volume size appropriate to your expected usage. Besu nodes use:

  • Full node: Total size 239.14 GB; increasing by 1.58 GB daily
  • Archive node: Total size 3.03 TB; increasing by 3.87 GB daily

Last updated: Dec 16, 2024

Use these figures as a basis to determine the extent to which you want to future-proof your node.

To limit disk space required, we recommend you configure Besu to use the Bonsai data storage format, which prunes orphaned nodes and old branches.

Ensure you mount the Besu data-path to the custom volume when you start the node.

note

Blockchain clients can take up a lot of disk space. By defining the amount of disk space you're willing to dedicate to your client (and the block data that it will be syncing), you can ensure that you still have enough room on your disk for whatever else you need.

Select the relevant operating system for the steps on how to create a custom volume.

Ubuntu
  • Open Terminal
  • Use the df -h command to check the available disk space
  • Choose a maximum size for the volume. We'll use 100GB for this example.
  • Use fallocate to create a file of the desired size, e.g. fallocate -l 100G myfile.img
  • Use mkfs.ext4 to format the file as an ext4 filesystem. e.g. mkfs.ext4 myfile.img
  • Mount the file using mount, e.g. mount -o loop myfile.img /mnt/myvolume
  • The contents will now be available in /mnt/myvolume, up to a maximum of 100GB
MacOS
  • Open Terminal
  • Use the df -h command to check the available disk space
  • Choose a maximum size for the volume. We'll use 100GB for this example.
  • Use hdiutil to create a sparse image of the desired size, e.g. hdiutil create -size 100g -type SPARSE -fs HFS+X myfile.dmg
  • Mount the image using hdiutil, e.g. hdiutil attach myfile.dmg
  • The contents will now be available mounted under /Volumes, up to a maximum of 100GB
Windows
Without Windows Subsystem Linux
  • Open Command Prompt as Administrator
  • Use the dir command to check available disk space on the volume you want to create the disk image
  • Choose a maximum size for the volume. We'll use 100GB for this example.
  • Use the fsutil command to create a sparse file of the desired size, e.g. fsutil file createnew myfile.img 107374182400 (for a 100GB file)
  • Initialize the disk image using diskpart:
    • diskpart
    • select vdisk file="myfile.img"
    • create vdisk maximum=100000
    • attach vdisk
    • exit
  • Format the volume using format, e.g. format F: /FS:NTFS /A:64K /Q
  • The new volume will now be available as drive letter F:, up to the maximum 100GB size

To mount an existing disk image:

  • Open Command Prompt as Administrator
  • Use diskpart
    • select vdisk file="myfile.img"
    • attach vdisk
  • The disk image will be mounted and accessible under the assigned drive letter
With Windows Subsystem Linux
  • Open WSL
  • Use the df -h command to check the available disk space
  • Choose a maximum size for the volume. We'll use 100GB for this example.
  • Use fallocate to create a file of the desired size, e.g. fallocate -l 100G myfile.img
  • Use mkfs.ext4 to format the file as an ext4 filesystem. e.g. mkfs.ext4 myfile.img
  • Mount the file using mount, e.g. mount -o loop myfile.img /mnt/myvolume
  • The contents will now be available in /mnt/myvolume, up to a maximum of 100GB

Step 4. Configure the Besu configuration file​

In your Besu configuration file (config-mainnet.toml or config-sepolia.toml), configure the following options:

  • Set data-path to the location you want to store your data.
  • Set genesis-file to the path of your downloaded genesis file.

Step 5. Start the Besu client​

Run the Besu client with the location of your configuration file. For example:

besu --config-file=/Users/myuser/mainnet/config-mainnet.toml

The Besu node will attempt to find peers to begin synchronizing and to download the world state.

Run using Docker​

Important

The Besu Docker image doesn't run on Windows.

Prerequisites​

Download and install Docker and ensure it is running.

Step 1. Download configuration files​

Download the configuration files for the relevant network (in ZIP format) and extract them. The configuration files include the network genesis file, Docker Compose file and Besu configuration file.

Download the mainnet besu-mainnet ZIP file.

bootnodes

You can choose from a range of bootnodes for Linea Mainnet. The Besu .zip includes a config file named config-snap-mainnet.toml where bootnodes are specified. The file uses all bootnodes by default.

The bootnodes page contains a full list of available bootnodes.

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
tip

You can use this page to find your public IP address.

Step 3. Start the Besu node​

Open a terminal, in the directory containing the docker-compose.yml file, run docker-compose up.

It can take up to 20 minutes for the node to find peers. If it takes any longer than that, try restarting the node.

Troubleshoot peering issues

Refer to the Besu troubleshooting information for help if you experience peering issues.

Confirm the node is running​

You can call the JSON-RPC API methods to confirm the node is running. For example, call eth_syncing to return the synchronization status. For example the starting, current, and highest block, or false if not synchronizing (or if the head of the chain has been reached).


curl localhost:8545 \
        -X POST \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

You should get a result similar to:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "startingBlock": "0x0",
    "currentBlock": "0x5d228",
    "highestBlock": "0x3cedec"
  }
}