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@b75b5ca.

Keys may differ in other Maru releases.

maru

Main Maru configuration.

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

api

Maru JSON-RPC API settings.

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

defaults

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

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

fork-transition

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

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

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

observability

Observability (metrics, health) settings.

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

p2p

P2P networking settings. Omit to disable P2P.

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

payload-validator

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

Key	Description	Type	Required	Default	Status
payload-validator.engine-api-endpoint.endpoint	Engine API endpoint URL of the execution-layer node. Example: http://el-node:8551.	URL	yes	-	active
payload-validator.engine-api-endpoint.jwt-secret-path	Optional path to the JWT secret file used for authenticated Engine API calls. Omit to disable JWT authentication. Example: /jwt.hex.	String?	no	-	active
payload-validator.engine-api-endpoint.timeout	Overall timeout for a single request to this endpoint.	Duration	no	PT1M	active
payload-validator.payload-validation-enabled	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.	Boolean	no	true	active

persistence

Persistent on-disk state settings.

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

qbft

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

Key	Description	Type	Required	Default	Status
qbft.duplicate-message-limit	Maximum number of duplicate QBFT messages kept per round.	Int	no	100	active
qbft.fee-recipient	Fee recipient address for blocks proposed by this validator (20-byte hex). Example: 0x0000000000000000000000000000000000000000.	ByteArray	yes	-	active
qbft.future-message-max-distance	Maximum number of blocks a future-dated QBFT message may be ahead of the current height.	Long	no	10	active
qbft.future-messages-limit	Maximum number of future-dated QBFT messages queued.	Long	no	1000	active
qbft.message-queue-limit	Maximum number of QBFT messages queued per round.	Int	no	1000	active
qbft.min-block-build-time	Minimum time spent building a block before proposing it.	Duration	no	PT0.5S	active
qbft.round-expiry	Optional fixed expiry duration for a QBFT round. Omit to derive it from round-expiry-coefficient.	Duration?	no	-	active
qbft.round-expiry-coefficient	Multiplier used to derive each subsequent round's expiry from the previous one.	Double	no	2.0	active
qbft.signer-name	Logical signer name passed to the external signer factory when signer-type is 'custom'.	String?	no	-	active
qbft.signer-type	Validator signing backend. Use 'local' for the node private key or 'custom' for an external signer.	String	no	local	active
qbft.target-gas-limit	Target execution block gas limit. Required for block-producing nodes with Amsterdam scheduled.	ULong?	no	-	active

syncing

Sync settings used while catching up to the chain head.

Key	Description	Type	Required	Default	Status
syncing.desync-tolerance	How far the sync target may be ahead of this node's head before the node is considered desynced.	ULong	no	5	active
syncing.download.backoff-delay	Backoff delay between download retries.	Duration	no	PT1S	active
syncing.download.block-range-request-timeout	Timeout for a single block-range download request.	Duration	no	PT5S	active
syncing.download.blocks-batch-size	Number of blocks requested in a single download batch.	UInt	no	100	active
syncing.download.blocks-parallelism	Number of block-range download requests issued in parallel.	UInt	no	1	active
syncing.download.max-retries	Maximum number of retries for a failed download request.	UInt	no	5	active
syncing.download.use-unconditional-random-download-peer	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.	Boolean	no	false	active
syncing.el-sync-status-refresh-interval	Optional interval to refresh the execution-layer sync status. Omit to disable.	Duration?	no	-	active
syncing.peer-chain-height-polling-interval	Interval between polls for peer chain height updates.	Duration	yes	-	active
syncing.sync-target-selection	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.	SyncTargetSelection	yes	-	active

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.