Configuration reference

A summary of each component’s configuration options. For the complete list, refer to --help or the example configurations in the repositories.

leafage-evm

Common parameters of the standalone subcommand:

Basics

Parameter	Default	Description
`--db-path`	required	State database directory
`--db-type`	`rocksdb`	`rocksdb` or `mdbx`
`--db-cache`	`2048`	Database cache (MB)
`--listen-addr`	`0.0.0.0:8545`	JSON-RPC listen address
`--chain-cfg`	`1`	Chain ID
`--evm-type`	`mainnet`	Executor type
`--archive`	`false`	Enable archive mode
`--node-type`	`auto`	Node type declared when registering with etcd

State updates

Parameter	Default	Description
`--kafka-s3-config`	-	File path or inline JSON of the Kafka + S3 configuration
`--rpc-addr`	-	Write node RPC address; enables HTTP polling when Kafka is not configured
`--update-interval`	`100`	Polling interval in HTTP mode (milliseconds)
`--diff-depth-limit`	`64`	Number of block diff layers kept in memory; also the reorg depth that can be handled
`--catchup-safe-depth`	`0`	Depth from the chain head to backfill along parent-hash during S3 catch-up; should be greater than the chain’s maximum reorg depth
`--init-task-queue-size`	`256`	Batch size for S3 catch-up
`--genesis-number`	`0`	Genesis block height

Performance and concurrency

Parameter	Default	Description
`--max-connections`	`5000`	Maximum concurrent RPC connections
`--listen-backlog`	`4096`	TCP accept queue; must not exceed `net.core.somaxconn`
`--rpc-timeout`	`10000`	Request timeout (milliseconds)
`--evm-exec-concurrency`	`0` (unlimited)	Upper bound on concurrently executing EVM requests; 2–4 times the core count is recommended
`--state-read-concurrency`	`0` (unlimited)	Upper bound on concurrent state reads; determine by load testing
`--account-cache-size`	`200000`	Account cache entries
`--storage-cache-size`	`2000000`	Storage cache entries
`--code-cache-size`	`200000`	Code cache entries
`--warmup-blocks`	`0`	Number of blocks to warm up at startup

Archive mode

Parameter	Default	Description
`--iterator-timeout-secs`	`0` (disabled)	Iterator timeout; prevents long-held iterators from blocking compaction
`--archive-code-cache-mb`	`256`	Code cache size (MB); can also be set with the `ARCHIVE_CODE_CACHE_MB` environment variable
`--archive-zstd-compression`	`false`	Enable zstd compression
`--inverted-block-encoding`	`false`	Use inverted height encoding; must match the encoding used at write time
`--disable-auto-compactions`	`false`	Disable automatic compaction (use for bulk imports)

Historical forwarding and observability

Parameter	Default	Description
`--historical-rpc`	-	External RPC for ranges without block diffs
`--historical-height`	-	Forwarding threshold height
`--prometheus-addr`	empty (disabled)	Metrics listen address
`--readiness-addr`	empty (disabled)	Readiness probe address
`--pprof-addr`	empty (disabled)	pprof address
`--stop-wait-timeout`	`5`	Seconds to wait for graceful shutdown

Kafka + S3 configuration

Passed to --kafka-s3-config; can be an absolute path or inline JSON:

{
  "topic": "nodex_pipeline_1",
  "brokers": "kafka1:9092,kafka2:9092",
  "partition": 0,
  "bucket_name": "nodex-internal",
  "outer_bucket_name": "chaintable-pipeline",
  "offset_dir": "/nodex-eth/offset",
  "s3_chain_id": "1",
  "version": ""
}

Field	Description
`topic` / `brokers` / `partition`	Internal Kafka topic and partition
`bucket_name`	Internal bucket: Header and StateDiff
`outer_bucket_name`	External bucket: BlockFile, used for indexing by height and warmup
`offset_dir`	Offset persistence directory; leave empty to use the default path
`s3_chain_id`	Chain ID segment in S3 keys
`version`	Version namespace; leave empty to disable

etcd registration

--etcd-config accepts JSON:

{
  "endpoints": ["http://etcd:2379"],
  "keep_alive_interval_ms": 5000,
  "lease_ttl_s": 15,
  "meta": "10.0.90.11:8659"
}

meta is the ip:port registered with etcd; it can also be specified separately with --meta.

pipeline

Passed in through the execution client’s tracer configuration (geth’s --vmtrace.jsonconfig):

Field	Default	Description
`region`	-	AWS region
`node_x_bucket`	-	Internal bucket name
`chain_table_bucket`	-	External bucket name
`brokers`	-	Kafka broker list
`topic`	`nodex_pipeline_{chainID}[_{version}]`	Internal topic
`version`	empty	Version namespace
`s3_temp_dir`	empty	Local upload cache directory
`enable_prestate_tracer`	`false`	Collect state diffs with the prestate tracer instead
`is_backup`	`nil`	`nil` = etcd election; `true`/`false` = manual mode
`etcd_endpoints`	-	etcd endpoints; mutually exclusive with `is_backup`
`election_key`	`{chainID}[/{version}]/writers/leader`	Election key
`node_id`	hostname	Node identifier
`grace_period`	`10`	Seconds to wait before becoming Leader
`writer_registry_ttl`	`10`	Write node registration lease in seconds

Exactly one of is_backup and etcd_endpoints must be set. Setting both or neither causes an immediate exit at startup.

consistency-checker

YAML configuration; -config specifies the path, and -listen can override the listen address.

Field	Default	Description
`listen`	`:8663`	HTTP listen address
`chain_id`	required	Chain ID
`version`	-	Version identifier; together with `outer_version_new_block_topic`, enables version mode
`ready_ratio`	`0.8`	Replica ready ratio threshold
`check_interval_ms`	`20`	Replica polling interval
`check_timeout_ms`	`2000`	Upper bound on the total time to wait for replicas to catch up
`rpc_node_timeout_ms`	`5000`	Per-node RPC timeout
`msg_wait_timeout`	`5000`	Kafka fetch timeout
`consistency_db_path`	-	Pebble DB directory
`outer_s3_bucket` / `outer_s3_region`	-	External bucket
`inner_brokers` / `inner_new_block_topic` / `inner_new_block_group_id`	-	Internal Kafka
`outer_brokers` / `outer_new_block_topic`	-	External Kafka singleton topic
`outer_version_new_block_topic`	-	External version topic (enables version mode)
`etcd_endpoints`	-	etcd endpoints
`etcd_lock_ttl`	`20`	Distributed lock TTL (seconds)
`etcd_write_timeout_ms`	`5000`	etcd write timeout
`version_check_interval`	`5`	Leader version check interval (seconds)
`commit_interval`	-	Kafka commit interval (seconds)
`fork_scan_interval_sec`	`60`	Fork scan interval; `<=0` disables it
`fork_scan_lookback`	`64`	Number of heights the scan looks back

check_num is deprecated and no longer takes effect. Replica polling is time-limited by check_timeout_ms.

listen: "0.0.0.0:8663"
chain_id: 1
ready_ratio: 0.8
consistency_db_path: "/eth/consistency_db"
outer_s3_bucket: "chaintable-pipeline"
outer_s3_region: "ap-northeast-1"
inner_brokers: ["kafka-1:9092"]
inner_new_block_topic: "nodex_pipeline_1"
inner_new_block_group_id: "consistency-group-1"
outer_brokers: ["kafka-1:9092"]
outer_new_block_topic: "pipeline_1"
etcd_endpoints: ["http://etcd:2379"]

nodex-proxy

YAML configuration; -config specifies the path, and -listen overrides the RPC port.

Top level

Field	Description
`listen`	RPC and admin port
`metric_listen`	Prometheus port
`etcd_endpoints`	etcd endpoints
`log_level`	Log level
`usage`	Usage reporting; an empty list disables it

`proxy_config`

Field	Default	Description
`service_name`	-	Service name
`native_node_url`	-	Native node address
`default_rpc_timeout`	`5000`	Upstream timeout (milliseconds)
`connection_pool_size`	`2000`	Connection pool size
`node_select_strategy`	`random`	`random` or `round_robin`
`etcd_prefix`	empty	etcd key prefix
`node_health_check_timeout`	`5`	Timeout for a single health check (seconds)
`node_health_check_max_wait`	`300`	Maximum health check wait (seconds)

`proxy_config.processor`

processor:
  observability_log:
    enable: true
    enable_error_log: true
    slow_threshold:
      default: 500
      rpc_methods:
        eth_call: 1000
        eth_getLogs: 2000
  rate_limiter:
    rpc_methods:
      eth_call: 100
      eth_getLogs: 50
  block_range_query_limit:
    enable: false
    recent_blocks: 0
    rewrite_to_latest: false
  request_mirror:
    enable: false
  method_name_checker:
    enable: false
    regexp: "^[a-zA-Z_][a-zA-Z0-9_]*$"
  method_denied:
    - eth_newPendingTransactionFilter
    - txpool_content

`proxy_config.observability`

observability:
  trace:
    enable: false
    otlp_endpoint: ""
    sampling_ratio: 0.1
  log:
    sampling:
      enable: true
      initial: 100
      thereafter: 100
  static_resource:
    service.name: "nodex-proxy"
    service.version: "1.0.0"

See config/config.example.yaml in the repository for a complete example.

Write node

Using the go-ethereum fork as an example, the flags Leafage adds:

Flag	Description
`--vmtrace pipeline`	Enable the pipeline live tracer
`--vmtrace.jsonconfig`	Tracer configuration JSON; see the pipeline section above for the fields
`--ancient.prune`	Continuously prune historical block bodies and receipts; requires `--syncmode full`

The remaining flags match upstream geth. To enable trace_debankBlock, include trace in --http.api.

Getting started

Core concepts

Architecture

Components

Guides

Reference

leafage-evm

Basics

State updates

Performance and concurrency

Archive mode

Historical forwarding and observability

Kafka + S3 configuration

etcd registration

pipeline

consistency-checker

nodex-proxy

Top level

`proxy_config`

`proxy_config.processor`

`proxy_config.observability`

Write node

​leafage-evm

​Basics

​State updates

​Performance and concurrency

​Archive mode

​Historical forwarding and observability

​Kafka + S3 configuration

​etcd registration

​pipeline

​consistency-checker

​nodex-proxy

​Top level

​proxy_config

​proxy_config.processor

​proxy_config.observability

​Write node

leafage-evm

Basics

State updates

Performance and concurrency

Archive mode

Historical forwarding and observability

Kafka + S3 configuration

etcd registration

pipeline

consistency-checker

nodex-proxy

Top level

`proxy_config`

`proxy_config.processor`

`proxy_config.observability`

Write node