Skip to main content

Set up distributed sequencing

This page describes how to set up and operate MaruMaru Linea's consensus layer client. Maru runs on validator nodes to coordinate block production with the execution layer, manage validator sets and consensus participation, and provide peer-to-peer networking for block propagation, using the Quorum Byzantine Fault Tolerance (QBFT) consensus algorithm. in multi-validator mode with QBFTQuorum Byzantine Fault Tolerance (QBFT) The Byzantine-fault-tolerant consensus algorithm that Maru implements to let a validator set produce and finalize blocks, tolerating faulty validators in a 3f+1 validator set. consensus on a LinethLineth (Formerly the Linea Stack) The open-source ZK-rollup stack, codebase, and technical protocol that's the foundation of Linea Mainnet. Operators can deploy this stack to launch their own Ethereum-compatible L2 or L3 networks. chain.

Prerequisites​

Set up and configure validators​

Use direct, static peering between validators rather than P2P discovery. Indirect routing adds latency and reduces consensus performance.

Use Maru's key generation script (Maru PrivateKeyGenerator) to generate validator keys in advance, then populate the genesis file with the validator addresses.

For multi-party deployments where validators are run by independent operators: each operator generates their own key locally and shares only the public address. Private keys never leave the operator's environment. All public addresses are then collected into the genesis file.

Private keys are saved by the corresponding validator and mounted as files on the filesystem at runtime.

Key rotation

Validator keys are mounted as files on the filesystem. Key rotation is a heavyweight operation: it requires fork management and a coordinated network update across all validators. Plan key rotations carefully and avoid them when possible.

A reference K3S setup is available at lineth-monorepo/maru/chaos-testing. For genesis file structure, see the genesis-maru.json template.

Manage the validator set​

You can add or remove a validator on a running chain using a scheduled Maru genesis file update. The genesis file is keyed by timestamp (similar to Ethereum hard fork schedules: Shanghai, Cancun, Prague), so changes apply at a future point all validators agree on.

To manage the validator set:

  1. If the new validator does not yet have a key pair, generate one using the PrivateKeyGenerator tool. The new operator keeps the private key locally and shares only the public address.
  2. All existing validator operators agree on a future timestamp far enough ahead for everyone to update their genesis file in time.
  3. Each operator updates their genesis file with the new validator list, set to activate at the agreed timestamp.
  4. Block time must remain consistent across validators.

This is a coordinated operation, not a runtime config change. There is no onchain governance or RPC method to add or remove validators dynamically.

Monitor Maru​

Maru exposes Prometheus metrics on its metrics port (configurable, default 9545). Metrics are prefixed with maru_. Key metrics for operators:

  • maru_consensus_block_latency (histogram, ms): total consensus time per block. P95 is the value to alert on. Tagged by role (proposer / non-proposer).
  • maru_engine_api_request_latency (timer): Engine API request latency between Maru and its paired Besu. Tagged by method, status.
  • maru_metadata_cl_block_height (gauge): latest beacon chain block height. Useful for liveness checks.

For diagnosing consensus slowdowns, additional maru_consensus_phase_* histograms break latency down by QBFT phase.

Recommended alert threshold: trigger when the block-building window (configured block time minus P95 of maru_consensus_block_latency) drops below 500ms. This matches the minimum block-building window in Multi-validator consensus.

Restore lost quorum​

The following are potential failure modes:

  • Single validator down (3 of 4 still active): Consensus continues normally.
  • Quorum lost (for example, 2 of 4 validators offline): The chain halts. Restore quorum via one of the following:
    1. Bring at least one offline validator back online.
    2. The remaining operators coordinate a scheduled genesis update to add a new validator that is online.

If consensus cannot complete within the configured block time, the protocol automatically advances to a missed round and changes the proposer for that slot. The affected slot is skipped and the next proposer takes over.

Upgrade validators​

You can apply rolling upgrades: with 4 validators, you can take 1 offline at a time without halting consensus. Expect missed rounds during the upgrade window: the offline validator's turn to propose blocks will be skipped. For larger validator sets, more validators can be taken offline simultaneously, up to the f failure tolerance.

Resources​

Was this page helpful?