Skip to content

Configuration fields

This inventory is generated from config/schema-v1.json. “Required here” means required by the immediate containing object; optional objects can still contain required members when present.

config_version

FieldType / valuesRequired hereConstraints
config_version1yes—

network

FieldType / valuesRequired hereConstraints
networkstringA built-in chain entry or its alias, such as `ethereum-mainnet`, `base`, `op`, `arbitrum-one`, or `robinhood`.yes{"minLength":1}

data_dir

FieldType / valuesRequired hereConstraints
data_dirstringWritable node state. A relative path is relative to the directory of this configuration file.yes{"default":"./data","minLength":1}

finality

FieldType / valuesRequired hereConstraints
finalitystarterFinalityyes—
finality.checkpointstringyes{"pattern":"^0x[0-9a-fA-F]{64}$"}
finality.checkpoint_slotpositiveIntegeryes{"minimum":1}
finality.endpointsarray<string>yes{"minItems":1}
finality.kindbeacon_api | consensus_p2p | json_rpc | op_gossip | sequencer_feed | disabledyes—
finality.minimum_agreementpositiveIntegerno{"minimum":1}
finality.bootnodesarray<string>no—
finality.minimum_peersnonNegativeIntegerno{"minimum":0}
finality.discovery_portintegerno{"minimum":0,"maximum":65535}
finality.listen_portintegerop_gossip only: TCP port for gossip connections, advertised in the discovery record; 0 picks one, and peers cannot dial in.no{"minimum":0,"maximum":65535}
finality.settle_blockspositiveIntegerop_gossip only: recent frames are pruned this many blocks below the tip while blocks wait for finalized; omitted, about one hour of blocks.no{"minimum":1}
finality.sequencer_signeraddressop_gossip only: the key the sequencer signs blocks with, in place of the chain entry's and any new one the L1 anchor reads.no{"pattern":"^0x[0-9a-fA-F]{40}$"}
finality.finalized_bybatches | json_rpc | settlementRollups only: what makes a block finalized, its batch in a finalized Ethereum block. batches (the default under an l1_anchor) has the anchor read the batches from finalized Ethereum blocks (op-stack blobs from l1_anchor.finality's Beacon APIs, Nitro SequencerInbox calls); json_rpc takes the finalized block the chain's JSON-RPC endpoints agree on, trusting them, and needs no l1_anchor; settlement finalizes blocks only as they settle. Omitted without an l1_anchor, nothing is finalized.no—

confirmation

FieldType / valuesRequired hereConstraints
confirmationconfirmationEthereum only: consensus nodes with Fast Confirmation enabled whose fast_confirmation events mark blocks this node verified as attested confirmed. They serve no chain data.no—
confirmation.endpointsarray<string>Beacon API base URLs streaming fast_confirmation events. Empty disables confirmed.no{"default":[]}
confirmation.minimum_agreementpositiveIntegerEndpoints whose votes must agree; within 1..=the number of endpoints.no{"minimum":1,"default":1}

blocks

FieldType / valuesRequired hereConstraints
blocksstarterBlocksno—

uniswap

FieldType / valuesRequired hereConstraints
uniswapstarterUniswapno—
uniswap.marketsarray<ETH/USDC | ETH/USDT | WBTC/ETH>yes{"minItems":1}

api

FieldType / valuesRequired hereConstraints
apistarterApiyes—
api.bindsocketAddressIPv4 or bracketed IPv6 socket address with portyes{"default":"127.0.0.1:18080"}
api.allow_wasm_buildsallowWasmBuildsCompile processor source sent to POST /admin/v1/wasm/build, as the playground's editor does. A development feature, not for production: rustc can read the host's files while it compiles, so Rust builds only for requests from the node's own machine, TypeScript for any client the API admits. Build modules where you write them and configure the module file instead.no{"default":false}
api.allow_processor_changesallowProcessorChangesAdd and remove processors through POST /admin/v1/processors and DELETE /admin/v1/processors/{instance}. The node keeps them in its data directory's processors.toml and loads them after this file, which wins for an instance it configures too. Each change restarts the network or JSON-RPC lanes in-process: a live pause for every processor.no{"default":false}
api.bearer_token_envstringno{"minLength":1}
api.allow_unauthenticated_remotebooleanServe the API on a non-loopback bind without bearer_token_env. Only behind an authenticating proxy.no{"default":false}
api.allowed_hostsarray<string>Host names, besides localhost, that requests may address. Any other Host name gets HTTP 421; IP addresses always pass.no{"default":[]}
api.allowed_originsallowedOriginsBrowser origins, besides loopback ones on any port, that may call the API. Any other Origin gets HTTP 403.no{"default":[]}
api.deliveryobjectno—
api.delivery.history_batchesdeliveryBatchno—
api.delivery.history_batches.target_encoded_byteshumanBytesyes—
api.delivery.history_batches.maximum_encoded_byteshumanBytesyes—
api.delivery.history_batches.maximum_eventspositiveIntegeryes{"minimum":1}
api.delivery.history_batches.maximum_processed_blockspositiveIntegeryes{"minimum":1}
api.delivery.history_batches.maximum_delayhumanMillisecondsyes—
api.delivery.history_batches.maximum_buffered_batchespositiveIntegeryes{"minimum":1}
api.delivery.history_batches.maximum_buffered_byteshumanBytesyes—
api.delivery.history_batches.compressionnone | gzipno—
api.delivery.live_batchesdeliveryBatchno—
api.delivery.live_batches.target_encoded_byteshumanBytesyes—
api.delivery.live_batches.maximum_encoded_byteshumanBytesyes—
api.delivery.live_batches.maximum_eventspositiveIntegeryes{"minimum":1}
api.delivery.live_batches.maximum_processed_blockspositiveIntegeryes{"minimum":1}
api.delivery.live_batches.maximum_delayhumanMillisecondsyes—
api.delivery.live_batches.maximum_buffered_batchespositiveIntegeryes{"minimum":1}
api.delivery.live_batches.maximum_buffered_byteshumanBytesyes—
api.delivery.live_batches.compressionnone | gzipno—

chain

FieldType / valuesRequired hereConstraints
chainchainyes—
chain.namestringA built-in chain entry or its alias.yes{"minLength":1}
chain.chain_idpositiveIntegerThe entry's EIP-155 chain id when omitted; a given one must match it.no{"minimum":1}
chain.merge_blocknonNegativeIntegerno{"minimum":0}

raw_history

FieldType / valuesRequired hereConstraints
raw_historyrawHistoryno—
raw_history.enabledbooleanno—
raw_history.maximum_logical_byteshumanBytesno—
raw_history.maximum_physical_byteshumanBytesno—
raw_history.maximum_frame_logical_byteshumanBytesno—
raw_history.maximum_segment_logical_byteshumanBytesno—
raw_history.maximum_segment_physical_byteshumanBytesno—
raw_history.reader_connectionspositiveIntegerno{"minimum":1}
raw_history.maximum_source_framespositiveIntegerno{"minimum":1}
raw_history.maximum_buffered_framespositiveIntegerno{"minimum":1}

artifact_storage

FieldType / valuesRequired hereConstraints
artifact_storageartifactStorageno—
artifact_storage.backendsqlite | tiered_segmentsno—
artifact_storage.segment_target_blockspositiveIntegerno{"minimum":1}
artifact_storage.compressionnone | snappy | deflateno—
artifact_storage.maximum_artifact_logical_byteshumanBytesno—
artifact_storage.maximum_segment_logical_byteshumanBytesno—
artifact_storage.maximum_segment_physical_byteshumanBytesno—
artifact_storage.compaction_intervalhumanMillisecondsno—
artifact_storage.maximum_segments_per_cyclepositiveIntegerno{"minimum":1}

budgets

FieldType / valuesRequired hereConstraints
budgetsbudgetsyes—
budgets.memory_bytespositiveIntegeryes{"minimum":1}
budgets.temporary_disk_bytespositiveIntegeryes{"minimum":1}
budgets.pending_delta_bytespositiveIntegeryes{"minimum":1}
budgets.recent_raw_soft_bytespositiveIntegeryes{"minimum":1}
budgets.recent_raw_hard_bytespositiveIntegeryes{"minimum":1}
budgets.source_concurrencypositiveIntegeryes{"minimum":1}
budgets.mapper_concurrencypositiveIntegeryes{"minimum":1}
budgets.history_materialhistoryMaterialBudgetno—
budgets.history_material.modedisabled | observe | enabledno—
budgets.history_material.memory_byteshumanBytesno—
budgets.history_material.maximum_buffered_frames_per_acquisitionpositiveIntegerno{"minimum":1}
budgets.history_material.minimum_physical_chunk_blockspositiveIntegerno{"minimum":1}
budgets.history_material.maximum_overfetch_rationumberno{"minimum":1}
budgets.history_pipelinehistoryPipelineBudgetno—
budgets.history_pipeline.maximum_active_chunkspositiveIntegerno{"minimum":1}
budgets.history_pipeline.maximum_mapped_byteshumanBytesno—
budgets.history_pipeline.commithistoryCommitBudgetno—
budgets.history_pipeline.commit.maximum_blockspositiveIntegerno{"minimum":1}
budgets.history_pipeline.commit.maximum_changespositiveIntegerno{"minimum":1}
budgets.history_pipeline.commit.maximum_encoded_byteshumanBytesno—
budgets.history_pipeline.commit.maximum_delayhumanMillisecondsno—
budgets.history_pipeline.commit.target_writer_holdhumanMillisecondsno—
budgets.storestoreBudgetno—
budgets.store.maximum_physical_byteshumanBytesno—
budgets.artifactsartifactBudgetno—
budgets.artifacts.maximum_retained_byteshumanBytesno—
budgets.artifacts.maximum_pending_byteshumanBytesno—
budgets.deliverydeliveryBudgetno—
budgets.delivery.maximum_retained_byteshumanBytesno—
budgets.delivery.maximum_history_retained_byteshumanBytesno—

sources

FieldType / valuesRequired hereConstraints
sourcessourcesyes—
sources.historyarray<historySource>no—
sources.history[].idstringyes{"minLength":1}
sources.history[].kindxatu | era_e | archive | json_rpc | aws_publicyes—
sources.history[].priorityintegeryes{"minimum":0,"maximum":65535}
sources.history[].trusttrusted_dataset | verified_materialyes—
sources.history[].chunk_blockspositiveIntegerXatu: blocks per acquisition chunk for headers, transactions, and logs, a multiple of Xatu's 1,000-block partitions (default 1,000). aws_public: most blocks of one day per chunk (default the whole day); each chunk reads its day again.no{"minimum":1}
sources.history[].blobs_chunk_blockspositiveIntegerXatu only: blocks per acquisition chunk for the blobs projection, a multiple of 1,000.no{"minimum":1,"default":8000,"multipleOf":1000}
sources.history[].batch_rowspositiveIntegerXatu and aws_public: Parquet rows decoded per bounded Arrow batch.no{"minimum":1,"default":8192}
sources.history[].manifeststringArchive only: the archive manifest. A relative path is relative to the directory of this configuration file.no—
sources.history[].endpointstringera_e: a mirror of the eraE files. aws_public: an https mirror of the AWS public blockchain bucket with the same layout.no{"format":"uri"}
sources.history[].allow_insecure_httpbooleanno—
sources.liveliveSourceyes—
sources.live.kindliveSourceKind | array<liveSourceKind>One kind, or ["p2p", "json_rpc"] on an op-stack chain with op_gossip finality: execution P2P first, JSON-RPC while no execution peer serves.yes—
sources.live.minimum_peersnonNegativeIntegeryes{"minimum":0}
sources.live.body_serving_peer_targetnonNegativeIntegerno{"minimum":0}
sources.live.preferred_peersnonNegativeIntegerno{"minimum":0}
sources.live.max_outbound_peersnonNegativeIntegerno{"minimum":0}
sources.live.max_concurrent_dialsnonNegativeIntegerno{"minimum":0}
sources.live.listener_portintegerno{"minimum":0,"maximum":65535}
sources.live.discovery_portintegerno{"minimum":0,"maximum":65535}
sources.live.discv5_portintegerno{"minimum":0,"maximum":65535}
sources.live.enable_discv5booleanno—
sources.live.natstringno—
sources.live.trusted_peersarray<string>no—
sources.live.bootstrap_dns_treestringOptional authenticated EIP-1459 execution peer-hint tree. It affects discovery only; execution material remains protocol-verified locally.no{"pattern":"^enrtree://"}
sources.live.peer_refill_interval_mspositiveIntegerno{"minimum":1}
sources.live.peer_recovery_timeout_secondspositiveIntegerno{"minimum":1}
sources.live.stall_timeout_secondsintegerExit the node, so that its process supervisor restarts it, after the live lane stays not ready this long while verified finality is ready.no{"default":600,"minimum":360,"maximum":2592000}
sources.live.material_request_concurrencypositiveIntegerno{"minimum":1}
sources.live.material_request_blocksintegerno{"minimum":1,"maximum":16}
sources.live.request_timeout_secondspositiveIntegerno{"minimum":1}
sources.live.request_retriespositiveIntegerno{"minimum":1}
sources.live.request_retry_backoff_mspositiveIntegerno{"minimum":1}
sources.live.history_header_request_concurrencypositiveIntegerno{"minimum":1}
sources.live.history_header_request_blockspositiveIntegerno{"minimum":1}
sources.live.persistent_retriesbooleanno—
sources.live.retry_backoff_max_secondspositiveIntegerno{"minimum":1}
sources.live.peer_store_flush_secondspositiveIntegerno{"minimum":1}
sources.live.peer_store_max_entriespositiveIntegerno{"minimum":1}
sources.live.archive_reconciliation_blockspositiveIntegerno{"minimum":1}
sources.live.archive_reconciliation_interval_secondspositiveIntegerno{"minimum":1}
sources.live.history_fallback_blockspositiveIntegerOptional maximum finalized suffix eligible for execution-P2P history fallback. When omitted, every gap at or after the processor start block is eligible.no{"minimum":1}
sources.live.handoff_overlap_blockspositiveIntegerno{"minimum":1}
sources.live.trusttrusted_dataset | verified_materialtrusted_dataset lets the JSON-RPC lane under a Nitro sequencer feed take the blocks it makes from the feed's messages without the header that checks each, for processors that take filtered material and need nothing but transactions' bodies, calldata, and senders (default verified_material).no—
sources.json_rpcobjectno—
sources.json_rpc.endpointsarray<string>no—
sources.json_rpc.public_endpointschainlist | bundled | noneno—
sources.json_rpc.quorumpositiveIntegerno{"minimum":1}
sources.json_rpc.poll_interval_mspositiveIntegerno{"minimum":1}
sources.json_rpc.finality_poll_interval_mspositiveIntegerno{"minimum":1}
sources.json_rpc.calls_per_secondpositiveIntegerno{"minimum":1}

l1_anchor

FieldType / valuesRequired hereConstraints
l1_anchorl1AnchorOpt-in: finalize a rollup's blocks from the settlement contracts its chain entry names, read in finalized Ethereum blocks over execution P2P.no—
l1_anchor.finalityfinalityEthereum mainnet's verified finality: beacon_api or consensus_p2p.yes—
l1_anchor.finality.kindbeacon_api | consensus_p2p | json_rpc | op_gossip | sequencer_feed | disabledyes—
l1_anchor.finality.checkpointstringno—
l1_anchor.finality.checkpoint_slotnonNegativeIntegerno{"minimum":0}
l1_anchor.finality.endpointsarray<string>no—
l1_anchor.finality.minimum_agreementpositiveIntegerno{"minimum":1}
l1_anchor.finality.bootnodesarray<string>no—
l1_anchor.finality.minimum_peersnonNegativeIntegerno{"minimum":0}
l1_anchor.finality.discovery_portintegerno{"minimum":0,"maximum":65535}
l1_anchor.finality.listen_portintegerop_gossip only: TCP port for gossip connections, advertised in the discovery record; 0 picks one, and peers cannot dial in.no{"minimum":0,"maximum":65535}
l1_anchor.finality.settle_blockspositiveIntegerop_gossip only: recent frames are pruned this many blocks below the tip while blocks wait for finalized; omitted, about one hour of blocks.no{"minimum":1}
l1_anchor.finality.sequencer_signeraddressop_gossip only: the key the sequencer signs blocks with, in place of the chain entry's and any new one the L1 anchor reads.no{"pattern":"^0x[0-9a-fA-F]{40}$"}
l1_anchor.finality.finalized_bybatches | json_rpc | settlementRollups only: what makes a block finalized, its batch in a finalized Ethereum block. batches (the default under an l1_anchor) has the anchor read the batches from finalized Ethereum blocks (op-stack blobs from l1_anchor.finality's Beacon APIs, Nitro SequencerInbox calls); json_rpc takes the finalized block the chain's JSON-RPC endpoints agree on, trusting them, and needs no l1_anchor; settlement finalizes blocks only as they settle. Omitted without an l1_anchor, nothing is finalized.no—
l1_anchor.listener_portintegerno{"minimum":0,"maximum":65535}
l1_anchor.discovery_portintegerno{"minimum":0,"maximum":65535}
l1_anchor.discv5_portintegerno{"minimum":0,"maximum":65535}
l1_anchor.natstringno—
l1_anchor.lookback_blocksintegerFinalized Ethereum blocks read below the first finalized block on a cold start.no{"minimum":1,"maximum":50400}
l1_anchor.factoryaddressAn op-stack chain's dispute game factory in place of the chain entry's; with registry and game_type, the contracts of a chain whose entry names none.no{"pattern":"^0x[0-9a-fA-F]{40}$"}
l1_anchor.registryaddressThe anchor state registry in place of the chain entry's.no{"pattern":"^0x[0-9a-fA-F]{40}$"}
l1_anchor.game_typeintegerThe game type the anchor reads, kept even when the registry comes to respect another.no{"minimum":0,"maximum":4294967295}
l1_anchor.claimsoutput_roots | super_rootsWhat the games claim: output_roots, or super_roots whose preimage holds the chain's output root.no—

processors

FieldType / valuesRequired hereConstraints
processorsarray<processor>yes{"minItems":1}
processors[].idstringyes{"minLength":1}
processors[].instancestringyes{"minLength":1}
processors[].versionstringyes{"minLength":1}
processors[].history_controlnode_owned | application_subscriptionsno—
processors[].history_modeautomatic | on_demandno—
processors[].require_retained_inputbooleanno—
processors[].start_blocknonNegativeIntegeryes{"minimum":0}
processors[].publishunattested | attested | confirmed | finalized | settledFirst chain-confidence level the processor's consumers see. confirmed needs active [confirmation]; settled needs a rollup's l1_anchor.no{"default":"unattested"}
processors[].statestatePolicyyes—
processors[].state.modedurable | checkpointedyes—
processors[].artifactsartifactPolicyno—
processors[].artifacts.modenone | window | fullRetention of immutable finalized map results, independent of queryable output and delivery.no{"default":"none"}
processors[].artifacts.windowartifactWindowRequired in window mode, and only valid there.no—
processors[].artifacts.window.max_blockspositiveIntegerno{"minimum":1}
processors[].artifacts.window.max_agehumanDurationno—
processors[].artifacts.window.max_byteshumanBytesno—
processors[].outputoutputPolicyyes—
processors[].output.modenone | latest | window | fullyes—
processors[].output.windowoutputWindowno—
processors[].output.window.max_blockspositiveIntegerno{"minimum":1}
processors[].output.window.max_agehumanDurationno—
processors[].output.window.max_rowspositiveIntegerno{"minimum":1}
processors[].output.window.max_byteshumanBytesno—
processors[].deliverydeliveryPolicyyes—
processors[].delivery.modenone | best_effort | window | until_acknowledgedyes—
processors[].delivery.emitchanges | job_resultno{"default":"changes"}
processors[].delivery.max_byteshumanBytesno—
processors[].delivery.max_agehumanDurationno—
processors[].delivery.on_limitpause | fail | expire_and_resetno—
processors[].delivery.pruningdeliveryPruningno—
processors[].delivery.pruning.intervalhumanDurationyes—
processors[].delivery.pruning.minimum_batch_blockspositiveIntegeryes{"minimum":1}
processors[].delivery.pruning.minimum_batch_changespositiveIntegeryes{"minimum":1}
processors[].delivery.pruning.maximum_delete_changespositiveIntegeryes{"minimum":1}
processors[].delivery.pruning.retain_finalized_blockspositiveIntegeryes{"minimum":1}
processors[].delivery.pruning.retain_acknowledged_agehumanDurationyes—
processors[].delivery.consumersarray<consumer>no—
processors[].delivery.consumers[].idstringyes{"minLength":1,"maxLength":128}
processors[].delivery.consumers[].requiredbooleanyes—
processors[].delivery.consumers[].lease_ttlhumanDurationFrom one second to 100 years.yes—
processors[].checkpointcheckpointPolicyyes—
processors[].checkpoint.modenone | automaticyes—
processors[].checkpoint.keepnonNegativeIntegeryes{"minimum":0}
processors[].undoundoPolicyyes—
processors[].undo.modenone | unfinalizedyes—
processors[].undo.safety_blocksnonNegativeIntegeryes{"minimum":0}
processors[].coverageprocessorCoverageno—
processors[].coverage.verification_segment_blockspositiveIntegerno{"minimum":1}
processors[].live_gap_fillprocessorLiveGapFillFill the blocks a block-local live lane skips, such as after a restart at a later finalized anchor, from history before it applies the next block, instead of only announcing them. Requires history_mode = "on_demand" and delivery.on_limit = "pause". Every live lane waits while a fill runs.no—
processors[].live_gap_fill.max_blocksintegerLargest skipped range the lane fills; it announces a longer one, and the rest of a fill that fails or runs longer than five minutes.yes{"minimum":1,"maximum":7200}
processors[].settingsobjectStrictly decoded by the selected processor factoryno—

rpc

FieldType / valuesRequired hereConstraints
rpcrpcyes—
rpc.http_bindsocketAddressIPv4 or bracketed IPv6 socket address with portyes—
rpc.ws_bindsocketAddressIPv4 or bracketed IPv6 socket address with portyes—
rpc.historical_modeon_demand | disabledyes—
rpc.minimum_recent_blockspositiveIntegeryes{"minimum":1}
rpc.allow_unauthenticated_remotebooleanServe JSON-RPC, which has no authentication, on a non-loopback http_bind or ws_bind. Only behind a trusted network or authenticating proxy.no{"default":false}
rpc.allowed_originsallowedOriginsBrowser origins, besides loopback ones on any port, that may call JSON-RPC over HTTP or WebSocket. Any other Origin gets HTTP 403.no{"default":[]}
rpc.max_batch_requestspositiveIntegerMost calls in one batch; a longer batch is refused whole with -32600.no{"minimum":1,"default":100}
rpc.max_response_byteshumanBytesMost encoded bytes of one response or batch response; each call past it is answered with -32005.no{"default":"16MiB"}
rpc.max_log_resultspositiveIntegerMost logs one eth_getLogs call returns; more fail with -32005 and a smaller block range to retry.no{"minimum":1,"default":10000}
rpc.max_log_addressespositiveIntegerMost addresses in one log filter; more fail with -32602.no{"minimum":1,"default":1000}
rpc.max_log_topic_alternativespositiveIntegerMost alternatives at one topic position of a log filter; more fail with -32602.no{"minimum":1,"default":1000}
rpc.max_subscriptions_per_connectionpositiveIntegerMost live subscriptions on one WebSocket connection; more fail with -32005.no{"minimum":1,"default":128}
rpc.max_websocket_connectionspositiveIntegerMost open WebSocket connections; a further upgrade gets HTTP 503.no{"minimum":1,"default":256}
rpc.max_outbound_byteshumanBytesQueued subscription notification bytes shared across WebSocket connections and listeners; at least max_subscription_event_bytes.no{"default":"64MiB"}
rpc.max_subscription_event_byteshumanBytesMost encoded bytes of subscription notifications one chain event may produce for one WebSocket connection, and that a connection may leave unread. A connection past the first is closed with 1008, past the second with 1013.no{"default":"16MiB"}