Skip to main content

Beta v4.0 migration guide

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)