Maru configuration reference

Advanced options

Some configuration keys are operational or environment-specific and are included for completeness. Their presence does not indicate that changing them is recommended or supported for every deployment. Verify their applicability against the relevant release and deployment guidance.

Defaults

Defaults are values defined in the Maru Kotlin config data classes (@ConfigDoc(default = ...)). They are not recommended production settings and may be overridden by deployment configuration. Sample *.toml files are never used as the source of defaults.

This reference lists Maru TOML configuration keys, grouped by section. Descriptions come from @ConfigDoc/@ConfigSection annotations on the config data classes; defaults are shown in the Default column.

Generated from LFDT-Lineth/lineth-monorepo@4e6baea.

Keys may differ in other Maru releases.

maru

Main Maru configuration.

Key	Type	Required	Default	Status	Description
allow-empty-blocks	Boolean	no	false	active	Whether empty blocks are allowed when proposing and when validating blocks (needed in multi-validator networks).
follower-engine-apis	Map<String, ApiEndpointDto>?	no	-	active	Named map of follower execution-layer endpoints. Each entry maps a follower name to its engine API endpoint settings.

api

Maru JSON-RPC API settings.

Key	Type	Required	Default	Status	Description
api.port	UInt	no	5060	active	Port serving the Maru JSON-RPC API.

defaults

Shared defaults reused by linea and fork-transition; currently provides the L2 endpoint.

Key	Type	Required	Default	Status	Description
defaults.l2-eth-endpoint.endpoint	URL	yes	-	active	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.
defaults.l2-eth-endpoint.jwt-secret-path	String?	no	-	active	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.
defaults.l2-eth-endpoint.timeout	Duration	no	PT1M	active	Overall timeout for a single request to this endpoint.

fork-transition

Protocol fork transition monitoring settings. Has defaults so the section may be omitted.

Key	Type	Required	Default	Status	Description
fork-transition.l2-eth-api-endpoint.endpoint	URL	yes	-	active	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.
fork-transition.l2-eth-api-endpoint.jwt-secret-path	String?	no	-	active	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.
fork-transition.l2-eth-api-endpoint.timeout	Duration	no	PT1M	active	Overall timeout for a single request to this endpoint.
fork-transition.protocol-transition-polling-interval	Duration	no	PT1S	active	Interval between polls for the protocol fork transition.

linea

Linea-specific settings (L1/L2 endpoints, contract address). Omit on non-Linea networks. l1-eth-api is a deprecated alias of l1-eth-api-endpoint; set one of the two. l2-eth-api-endpoint falls back to defaults.l2-eth-endpoint when omitted.

Key	Type	Required	Default	Status	Description
linea.contract-address	ByteArray	yes	-	active	Address of the Linea rollup contract on L1 (20-byte hex). Example: 0x0000000000000000000000000000000000000000.
linea.l1-eth-api-endpoint.endpoint	URL	yes	-	active	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.
linea.l1-eth-api-endpoint.jwt-secret-path	String?	no	-	active	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.
linea.l1-eth-api-endpoint.timeout	Duration	no	PT1M	active	Overall timeout for a single request to this endpoint.
linea.l1-eth-api.endpoint	URL	yes	-	deprecated	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.
linea.l1-eth-api.jwt-secret-path	String?	no	-	deprecated	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.
linea.l1-eth-api.timeout	Duration	no	PT1M	deprecated	Overall timeout for a single request to this endpoint.
linea.l1-highest-block-tag	String	no	finalized	active	L1 block tag treated as the highest finalized block (e.g. finalized, safe, latest).
linea.l1-polling-interval	Duration	no	PT6S	active	Interval between L1 polls for rollup contract events.
linea.l2-eth-api-endpoint.endpoint	URL	yes	-	active	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.
linea.l2-eth-api-endpoint.jwt-secret-path	String?	no	-	active	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.
linea.l2-eth-api-endpoint.timeout	Duration	no	PT1M	active	Overall timeout for a single request to this endpoint.

observability

Observability (metrics, health) settings.

Key	Type	Required	Default	Status	Description
observability.jvm-metrics-enabled	Boolean	no	true	active	Whether JVM-level metrics are exposed in addition to application metrics.
observability.port	UInt	no	9545	active	Port serving observability endpoints (metrics, health).
observability.prometheus-metrics-enabled	Boolean	no	true	active	Whether Prometheus metrics are exposed on the observability port.

p2p

P2P networking settings. Omit to disable P2P.

Key	Type	Required	Default	Status	Description
p2p.discovery.advertised-ip	String?	no	-	active	IP address advertised to peers for discovery. Omit to use the listen IP address.
p2p.discovery.bootnodes	List<String>	no	-	active	Bootnode addresses (enodes) used to bootstrap discovery.
p2p.discovery.port	UInt	no	9000	active	UDP port used for discovery.
p2p.discovery.refresh-interval	Duration	yes	-	active	Interval between discovery table refresh cycles.
p2p.discovery.retry-timeout	Duration	no	PT10S	active	Timeout before retrying a failed discovery request.
p2p.discovery.search-interval	Duration	no	PT1S	active	Interval between discovery search runs.
p2p.discovery.search-timeout	Duration	no	PT30S	active	Timeout for a single discovery search run.
p2p.gossiping.consider-peers-as-direct	Boolean	no	false	active	Whether all peers are scored as direct peers (same as static peers) in gossip peer scoring (libp2p GossipPeerScoreParams.isDirect).
p2p.gossiping.d	Int	no	8	active	Target mesh degree (number of peers each topic is gossiped to).
p2p.gossiping.d-high	Int	no	16	active	Upper bound on the mesh degree; peers are pruned when the mesh exceeds this. Defaults to 2 * d.
p2p.gossiping.d-lazy	Int	no	6	active	Degree of lazy (non-mesh) peers used for gossip amplification.
p2p.gossiping.d-low	Int	no	6	active	Lower bound on the mesh degree; peers are added when the mesh drops below this.
p2p.gossiping.fanout-ttl	Duration	no	PT1M	active	Time-to-live for gossip fanout messages sent to peers outside the mesh.
p2p.gossiping.flood-publish-max-message-size-threshold	Int	no	16384	active	Maximum message size above which flood publishing is skipped. Defaults to 16KiB.
p2p.gossiping.gossip-factor	Double	no	0.25	active	Fraction of non-mesh peers that receive gossip messages (libp2p gossipFactor).
p2p.gossiping.gossip-size	Int	no	3	active	Number of history windows advertised via IHAVE messages (libp2p gossipSize).
p2p.gossiping.heartbeat-interval	Duration	no	PT0.7S	active	Interval between gossipsub heartbeat rounds.
p2p.gossiping.history	Int	no	6	active	Number of gossip history windows retained in the message cache (libp2p gossipHistoryLength).
p2p.gossiping.seen-ttl	Duration	no	PT780.5S	active	Time-to-live for the seen-message cache. Defaults to 700ms * 1115.
p2p.ip-address	String	no	127.0.0.1	active	IP address the node listens on for P2P traffic. Defaults to localhost for security.
p2p.max-peers	Int	no	25	active	Maximum number of peers the node maintains.
p2p.peering-fork-mismatch-leeway-time	Duration	no	PT20S	active	Leeway time during which a peer is tolerated despite a fork mismatch before being penalized.
p2p.port	UInt	no	9000	active	TCP port the node listens on for P2P traffic. UDP discovery uses p2p.discovery.port.
p2p.reconnect-delay	Duration	no	PT5S	active	Delay before reconnecting to a dropped peer.
p2p.reputation.ban-period	Duration	no	PT1H	active	Duration a peer is banned after dropping below the disconnect threshold.
p2p.reputation.capacity	Int	no	1024	active	Maximum number of peers tracked in the reputation table.
p2p.reputation.cooldown-period	Duration	no	PT2M	active	Duration a peer's reputation is held before decaying after a change.
p2p.reputation.disconnect-score-threshold	Int	no	-10	active	Reputation score below which a peer is disconnected. Defaults to -large-change.
p2p.reputation.large-change	Int	no	10	active	Reputation score delta applied for a large positive/negative event.
p2p.reputation.max-reputation	Int	no	20	active	Maximum reputation score a peer can reach. Defaults to 2 * large-change.
p2p.reputation.small-change	Int	no	3	active	Reputation score delta applied for a small positive/negative event.
p2p.static-peers	List<String>	no	-	active	Static peer addresses (enodes) the node stays connected to.
p2p.status-update.refresh-interval	Duration	no	PT30S	active	Interval between peer status refreshes.
p2p.status-update.refresh-interval-leeway	Duration	no	PT5S	active	Leeway applied to the peer status refresh interval.
p2p.status-update.timeout	Duration	no	PT10S	active	Timeout for a single peer status update request.

payload-validator

Validator execution-layer node settings. Required when qbft is set.

Key	Type	Required	Default	Status	Description
payload-validator.engine-api-endpoint.endpoint	URL	yes	-	active	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.
payload-validator.engine-api-endpoint.jwt-secret-path	String?	no	-	active	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.
payload-validator.engine-api-endpoint.timeout	Duration	no	PT1M	active	Overall timeout for a single request to this endpoint.
payload-validator.payload-validation-enabled	Boolean	no	true	active	Whether to validate execution payloads received via the Engine API. Must stay true when the qbft section is set: a validator fails to start with payload validation disabled. Only followers may set it to false.

persistence

Persistent on-disk state settings.

Key	Type	Required	Default	Status	Description
persistence.data-path	Path	yes	-	active	Directory where Maru stores its persistent on-disk state (database, keystore). Example: /data/maru.
persistence.private-key-path	Path	no	data-path/private-key	active	Path to the node private key file. Defaults to a 'private-key' file under data-path.

qbft

QBFT consensus settings. Omit on follower (non-validator) nodes.

Key	Type	Required	Default	Status	Description
qbft.duplicate-message-limit	Int	no	100	active	Maximum number of duplicate QBFT messages kept per round.
qbft.fee-recipient	ByteArray	yes	-	active	Fee recipient address for blocks proposed by this validator (20-byte hex). Example: 0x0000000000000000000000000000000000000000.
qbft.future-message-max-distance	Long	no	10	active	Maximum number of blocks a future-dated QBFT message may be ahead of the current height.
qbft.future-messages-limit	Long	no	1000	active	Maximum number of future-dated QBFT messages queued.
qbft.message-queue-limit	Int	no	1000	active	Maximum number of QBFT messages queued per round.
qbft.min-block-build-time	Duration	no	PT0.5S	active	Minimum time spent building a block before proposing it.
qbft.round-expiry	Duration?	no	-	active	Optional fixed expiry duration for a QBFT round. Omit to derive it from round-expiry-coefficient.
qbft.round-expiry-coefficient	Double	no	2.0	active	Multiplier used to derive each subsequent round's expiry from the previous one.

syncing

Sync settings used while catching up to the chain head.

Key	Type	Required	Default	Status	Description
syncing.desync-tolerance	ULong	no	5	active	How far the sync target may be ahead of this node's head before the node is considered desynced.
syncing.download.backoff-delay	Duration	no	PT1S	active	Backoff delay between download retries.
syncing.download.block-range-request-timeout	Duration	no	PT5S	active	Timeout for a single block-range download request.
syncing.download.blocks-batch-size	UInt	no	100	active	Number of blocks requested in a single download batch.
syncing.download.blocks-parallelism	UInt	no	1	active	Number of block-range download requests issued in parallel.
syncing.download.max-retries	UInt	no	5	active	Maximum number of retries for a failed download request.
syncing.download.use-unconditional-random-download-peer	Boolean	no	false	active	When false (default), pick a random peer among those whose latest reported block is at least the download range end. When true, skip that end-block filter and pick any peer at random.
syncing.el-sync-status-refresh-interval	Duration?	no	-	active	Optional interval to refresh the execution-layer sync status. Omit to disable.
syncing.peer-chain-height-polling-interval	Duration	yes	-	active	Interval between polls for peer chain height updates.
syncing.sync-target-selection	SyncTargetSelection	yes	-	active	Sync target selection strategy. Use a bare string 'Highest' to sync to the highest peer head, or an inline table { _type = 'MostFrequent', peer-chain-height-granularity = <n> } to sync to the most frequent peer chain height. Sealed-type dispatch is enabled by the loader.

Deprecated Keys

File	Key	Replacement	Description
maru	linea.l1-eth-api	linea.l1-eth-api-endpoint	Legacy L1 endpoint; alias for l1-eth-api-endpoint kept for backwards compatibility. Deprecated, use l1-eth-api-endpoint.
maru	linea.l1-eth-api.endpoint	linea.l1-eth-api-endpoint	Engine API endpoint URL of the execution-layer node.
maru	linea.l1-eth-api.jwt-secret-path	linea.l1-eth-api-endpoint	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication.
maru	linea.l1-eth-api.timeout	linea.l1-eth-api-endpoint	Overall timeout for a single request to this endpoint.