Linea nodes need compatible Maru and execution clients to follow network upgrades

Maru and Execution Responsibilities

Maru handles consensus and block propagation, while the execution client runs transactions and maintains the local execution state. The consensus layer drives its configured execution clients through the Engine API. Standard Ethereum JSON-RPC requests go to the execution layer, which answers queries about its own stored blocks and state. That division explains why an execution process can remain responsive while its connection to Maru fails. The application endpoint and the inter-client connection perform different jobs.

On Linea Mainnet, Beta v4 replaced Clique with Maru in October 2025. Older deployment recipes that launch only an execution client belong to the earlier architecture. The migration also moved sequencer signatures out of execution block extraData and into Maru's consensus APIs. Software that reads those signatures therefore needs an interface change alongside the client upgrade.

Engine API Connectivity

The Engine API is the connection through which Maru coordinates execution, and its endpoint must match the running execution service. A normal application RPC endpoint does not substitute for that connection. Address routing and authentication form separate parts of the configuration.

Endpoint Routing

Maru's execution endpoint must resolve to the selected client inside the deployment network. With Docker's default container networking, localhost refers to that container, so an execution client in another container needs a reachable service address. Port mappings also have two sides: the host-facing port and the service's internal listener. Copying only a host port into Maru's configuration can leave the actual listener unreachable.

Authentication Settings

Shared JWT Secrets

JWT-authenticated Engine API connections require both clients to read matching secret contents. JWT means JSON Web Token. Geth exposes its authenticated listener through authrpc settings, including the secret file. Maru has a corresponding JWT secret path. A correct address cannot compensate for a missing file, an unreadable mount, or different secrets.

Unauthenticated Configurations

Linea Besu configurations can explicitly disable Engine API JWT authentication, while Maru supports endpoints without a JWT secret path. Those settings must agree with the chosen execution client. Engine access belongs on a restricted network; disabling authentication does not make the endpoint suitable for public application traffic. Public RPC exposure needs separate access controls and resource limits.

Network Selection and Fork Activation

Network configuration identifies the chain and the execution rules that apply at each fork boundary. Maru supports named networks such as linea-mainnet and linea-sepolia. Its --network flag must not accompany --maru-genesis-file. Linea Besu profiles embed their network configuration, whereas the Geth deployment path supplies a genesis file. Mainnet and testnet have separate activation schedules. Fusaka activated on Linea Sepolia on 1 December 2025 and mainnet on 3 December 2025. Nodes needed compatible clients at activation to avoid fork-related interruptions.

Release Packages and Version Pins

Versioned deployment files identify a compatible software combination, including the Maru image and the execution client image. An old compose file can keep selecting old artifacts even after newer files exist elsewhere.

Linea Besu uses upstream Besu with a suite of Linea-specific plugins. The historical Linea-specific Besu fork is archived and unmaintained. Its repository name does not make its old binaries suitable replacements for the packaged distribution. Package builds coordinate Besu dependencies with the relevant plugin builds. Updating the base client alone can leave the deployed plugin set unchanged, so the artifact identity and selected profile both matter.

CPU architecture also constrains which image or binary can replace an existing deployment.

View image file

Upgrade Stages With Retained State

A controlled node upgrade keeps the client pair compatible while preserving usable local state. Docker Compose keeps client data separate from container images when the data directories use persistent volumes or bind mounts. A migration that explicitly requires rebuilding a database has a different recovery requirement from an ordinary software replacement.

Upgrade Stages With Retained State

A controlled node upgrade keeps the client pair compatible while preserving usable local state. Docker Compose keeps client data separate from container images when the data directories use persistent volumes or bind mounts. A migration that explicitly requires rebuilding a database has a different recovery requirement from an ordinary software replacement.

• Client Change (Maintenance Stage) Resolve the release pair: Match Maru, execution software, and the intended network's fork configuration. Stop and preserve storage: Shut down the affected clients gracefully and wait for them to exit before copying their stored data. Install compatible artifacts: Replace images or binaries and apply required configuration changes. Restart the connected services: Reconnect Maru to the selected execution client's Engine API. Confirm network progress: Examine fork settings, both client logs, and the execution head.
• State Preservation or Recovery Limit (Maintenance Stage) Resolve the release pair: Retain the previous configuration and artifact identities. Stop and preserve storage: Preserve data volumes, configuration, and any separate credentials. Install compatible artifacts: Retain database mounts unless the migration requires rebuilding their contents. Restart the connected services: Reusing stored state requires a database format that the client accepts. Confirm network progress: Resolve configuration failures before treating the database as unusable.

Maintenance Stage: Upgrade acceptance; Client Change: The compatible clients follow the intended network.; State Preservation or Recovery Limit: Preserved files alone do not establish successful synchronization.

View image file

Upgrade Stages With Retained State

Maintenance Stage	Client Change	State Preservation or Recovery Limit
Resolve the release pair	Match Maru, execution software, and the intended network's fork configuration.	Retain the previous configuration and artifact identities.
Stop and preserve storage	Shut down the affected clients gracefully and wait for them to exit before copying their stored data.	Preserve data volumes, configuration, and any separate credentials.
Install compatible artifacts	Replace images or binaries and apply required configuration changes.	Retain database mounts unless the migration requires rebuilding their contents.
Restart the connected services	Reconnect Maru to the selected execution client's Engine API.	Reusing stored state requires a database format that the client accepts.
Confirm network progress	Examine fork settings, both client logs, and the execution head.	Resolve configuration failures before treating the database as unusable.
Upgrade acceptance	The compatible clients follow the intended network.	Preserved files alone do not establish successful synchronization.

How Can a Node Be Running Without Being Caught Up?

A running node can answer RPC requests from its local database while its clients lag behind the network head. The eth_syncing response reports synchronization activity, including block progress when the client returns that information. A false response means the client reports no active synchronization; it does not independently establish that the endpoint has reached the live network head. Local block height needs the context of the same network's current progress.

Fork configuration supplies another diagnostic signal. During the December 2025 Fusaka migration, the expected mainnet fork ID was 0x335bb88e, and Sepolia's was 0x24ef0ae2. The eth_config response placed that identifier under result.next.forkId in Besu and result.last.forkId in Geth. Those identifiers concern that particular activation. Later upgrades can require different expectations, and a correct configured fork does not demonstrate that the local database has caught up.

Maru's consensus height and execution import logs describe different parts of the same node. Monitoring both helps locate a stalled connection or a lagging execution process. A container health check that merely detects a running process cannot answer either question.

View image file

Peer Discovery Across Both Layers

Peer discovery connects a node to other network participants, and Maru and the execution client have distinct peering settings. Execution bootnodes help an initializing client discover peers; they do not replace the Engine API connection. Maru also has its own discovery configuration. A deployment can therefore reach execution peers while failing to import consensus blocks. Advertised addresses, listener bindings, and firewall rules must fit the deployment topology. TCP peer traffic and UDP discovery need the relevant network access, while application RPC and Engine API access require their own restrictions.

Data Volumes and Recovery Limits

Persistent volumes keep node databases separate from the container lifecycle, allowing replacement containers to reuse the same stored data. A normal docker compose down removes service containers and networks without deleting named volumes. Adding --volumes deletes the named volumes declared in the Compose file and anonymous volumes attached to its containers. External volumes remain untouched. Changing a volume name or mount can also point a new container at different storage. The previous database may still exist even though the restarted client sees an empty directory.

Recovery also distinguishes reproducible chain data from private credentials. Geth can reconstruct blockchain data through synchronization, but account keystores and their passwords require separate secure backups when the installation contains accounts. Peer synchronization cannot recreate a lost private key. Database backups have their own compatibility limits: a software release may change its storage format, and a network fork changes the rules needed to follow new blocks. Restoring earlier files cannot make an obsolete client accept a later fork.

RPC Profiles and Application Compatibility

RPC compatibility depends on the execution distribution and enabled plugins, even when clients follow the same chain. Besu, Geth, and the patched Erigon deployment can serve standard Ethereum JSON-RPC. The linea_ namespace belongs to Linea Besu plugins. A replacement client can therefore preserve ordinary block queries while removing methods that an application uses to estimate gas fees. Network synchronization and application method support need separate acceptance checks.

Basic Linea Besu profiles omit the extra plugins, while advanced profiles provide linea_estimateGas and previously used a plugin to support the finalized block parameter tag. The Maru mainnet configuration example defines an optional Linea section for this tag, with an Ethereum L1 RPC endpoint and a Linea L2 RPC endpoint. The example leaves this section commented out. Older plugin-based advanced configurations required an appropriate Ethereum RPC connection to query L1 finalization. In those configurations, an unavailable or incorrectly selected L1 endpoint could affect finalization tracking even while the node continued importing L2 blocks. This dependency concerns the relevant finalization feature, rather than every standard RPC query.

The advanced profile also has a platform restriction: it does not support macOS on ARM. An artifact that starts on a host is not automatically compatible with every plugin configuration. The selected profile and supported platform remain part of the deployment requirements.

Erigon's Linea-Specific Sync Requirements

Erigon's supported deployment path uses a locally built patched image. Stock v3.5.0 stalled at block 0 during fresh-sync testing with --externalcl and Maru. The supported example builds on v3.3.0 and addresses execution block-download behavior plus empty-code system calls associated with EIP-7002 and EIP-7251 at the Fusaka fork. Maru drives the execution client through the Engine API, while the patched client also bootstraps its execution stage from genesis. An Ethereum fork-support claim alone does not establish that a particular Erigon build can bootstrap Linea successfully.

Follower Maintenance and Validator Quorum

Follower nodes import network blocks without voting, so updating a public-network follower does not grant permission to produce blocks. Maru also supports validator operation in Lineth (formerly the Linea Stack) deployments with an explicitly configured QBFT validator set. QBFT means Quorum Byzantine Fault Tolerance. Each validator needs a dedicated Linea Besu execution client with sequencer plugins. These deployment capabilities describe the underlying stack; installing them locally does not add a node to the public network's block-producing set.

Validator maintenance has an additional availability constraint. A QBFT set with 3f+1 validators tolerates up to f faulty validators, and rolling upgrades must preserve that quorum. Existing failures count against the same allowance. Validator keys and membership also require coordinated genesis changes when they change. A healthy replacement process cannot compensate for missing quorum or inconsistent validator configuration.