Skip to main content

Upgrade guides

Fusaka upgrade guide​

Linea will be upgrading to Fusaka (Ethereum's latest EVM upgrade) on December 3-4, 2025 to maintain alignment with Ethereum mainnet. Node runners must update their clients before the upgrade activates (if no downtime is desired).

Upgrade both clients​

This upgrade requires updating BOTH your Execution Layer (EL) and Consensus Layer (Maru) clients: Besu: consensys/linea-besu-package:[VERSION_TBD] Maru: consensys/maru:[VERSION_TBD] Geth: 1.16.5 ? Other EL clients: Check for Fusaka-compatible versions

Verify your upgrade​

After upgrading, validate that your node is running the correct fork by checking the forkId:

curl --location http://localhost:8545/ \
--header 'Content-Type: application/json' \
--data '{
    "jsonrpc": "2.0",
    "method": "eth_config",
    "params":[],
    "id": 1
}' | jq .result.current.forkId

Expected output:

{
  "hash": "[EXPECTED_HASH_TBD]"
}

If your output doesn't match, your node is not properly upgraded.

Simplified configuration with named networks:​

Starting with these versions (TBD), Maru now supports the --network flag, eliminating the need for manually managing genesis files.

Old way:​

command:

  - "--maru-genesis-file"
  - "/opt/consensys/maru/configs/maru-genesis.json"

command:

  - "--network"
  - "linea-mainnet"

This simplifies node setup and ensures you're always using the correct network configuration. Lastly:

Help us monitor the network! (...it's optional, but greatly appreciated)​

We kindly ask node runners to enable Ethstats monitoring for your Sepolia or Mainnet nodes.

This helps us to:

  • Proactively spot upgrade issues
  • Monitor block propagation across the network
  • Track EL client versions and network health
  • Provide better support during the Fusaka upgrade and future upgrades

You can opt out at any time.

How to Enable Ethstats:​

Add the following flag to your Execution Layer client, replacing your-node-name with a unique identifier for your node (e.g., mycompany-node-1):

Linea Sepolia:​

--ethstats=your-node-name:2jus8pGcrJZbyC7E@ethstats.sepolia.linea.build

Linea Mainnet:​

--ethstats=your-node-name:2jus8pGcrJZbyC7E@ethstats.linea.build

Docker Compose example:​
besu-node:
  image: consensys/linea-besu-package:[VERSION_TBD]
  command:
    - --config-file=/var/lib/besu/linea-besu.config.toml
    - --ethstats=your-node-name:2jus8pGcrJZbyC7E@ethstats.linea.build
More details here:​

Besu Ethstats setup Geth Ethstats setup

Beta v4.0 migration guide​

Instructions for running Maru alongside an execution layer client

Linea Beta v4.0 is a mandatory hard fork introducing Maru, the new consensus layer (CL).

Maru replaces Clique and aligns Linea with Ethereum's dual-layer design (execution and consensus).

After the fork:

  • You must run both an execution layer (EL) client of your choice and Maru, a CL client. A standalone EL client will not work.
  • Sequencer signatures move from EL extraData to the Maru attestations API.
  • EL clients must be upgraded to Beta v4.0 compatible versions (any EL client that supports Prague should be compatible).

See the Beta v4.0 release notes for the scheduled hard fork dates.

This page is intended for those who have already successfully upgraded their nodes to the Shanghai hard fork.

Overview of changes​

Breaking change: sequencer signatures​

Sequencer signatures will no longer be in EL block extraData after the upgrade.

Before (pre-fork):

// on EL client
let signatures = block.extra_data;

After (post-fork):

// Must switch to Maru API
let signatures = maru_api.get("/eth/v2/beacon/blocks/{block_id}").data.message.body.attestations;

attestations returns a list containing the current block signature/attestation and the previous block signature/attestation.

Key architecture changes​

Current​

  • Single layer: EL client only (Besu with Clique)
  • Sequencer signatures: Stored in EL block extraData
  • Block production: Clique handles execution and consensus

After Beta v4.0​

  • Dual-layer architecture: Execution Layer (EL) client + Consensus Layer (CL) client (The CL is currently powered by Maru, a consensus client implementing a customized variation of the QBFT algorithm. While Maru is the only supported client today, the architecture is designed to support future client diversity and algorithm evolution).
  • Sequencer signatures: Moved to Maru's SealedBeaconBlock.commitSeals
  • Block production: Maru (QBFT) coordinates consensus, EL executes transactions
  • API: Signatures and consensus data available via Maru APIs

EL client compatibility​

By design, Linea with Maru will support any client compatible with L1; vanilla client compatible with Prague will work.

Supported EL clients include:

  • Besu: 25.8.0 or higher
  • Geth:
    • Pre-Shanghai: v1.13.15
    • Post-Shanghai: v1.16.x
  • Erigon: Latest release
  • Nethermind: Latest release
  • Linea-specific: A new linea-besu-package release is available via Docker: consensys/linea-besu-package:beta-v4.0-rc17-20251024131506-d32162b

Upgrade to Cancun and Prague​

After the Paris and Shanghai hard forks on October 22 and 23 respectively, the next step is to update your genesis files for both Maru and your EL client and then reinitialize your node.

Geth version

Ensure your Geth client is using v1.16.x or higher. Older versions will not be compatible after the Cancun hard fork.

Step 1: New genesis files​

First, find the files here:

Step 2: Update docker-compose.yml​

Retrieve the updated docker-compose.yml file from the Linea monorepo.

Alternatively, update your existing docker-compose.yml file manually with the new linea-besu-package image (rc17):

  besu-node:
      hostname: el-client
      container_name: linea-besu
      image: consensys/linea-besu-package:beta-v4.0-rc17-20251024131506-d32162b

Step 3: Reinitialize your node​

First, stop your existing nodes:

docker compose down

Then reinitialize your node:

docker compose up maru-node besu-node

Step 4: Verify​

After a successful reinitialization, you should see the following in your logs:

Maru​

LenientForkPeeringManager | forks: [{ts=1761646200 time=2025-10-28T10:10:00Z fork=QBFT_PHASE0/Prague forkDigest=0xae00a891},{ts=1761645600 time=2025-10-28T10:00:00Z fork=QBFT_PHASE0/Cancun forkDigest=0x3aa8d9a0},{ts=1761213600 time=2025-10-23T10:00:00Z fork=QBFT_PHASE0/Shanghai forkDigest=0xfcb4d7c8},{ts=0 time=1970-01-01T00:00:00Z ttd=49575263 fork=QBFT_PHASE0/Paris forkDigest=0x285982f0}]

Besu​

ProtocolScheduleBuilder | Protocol schedule created with milestones: [Paris:0, Shanghai:1761213600, Cancun:1761645600, Prague:1761646200]

Geth​

Post-Merge hard forks (timestamp based):
 - Shanghai:                    @1761213600
 - Cancun:                      @1761645600 blob: (target: 0, max: 0, fraction: 3338477)
 - Prague:                      @1761646200 blob: (target: 0, max: 0, fraction: 5007716)