> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leafage.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration reference
> Startup parameters and configuration file fields for the five components
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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`.
```yaml theme={null}
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`
```yaml theme={null}
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`
```yaml theme={null}
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`](https://github.com/Chaintable/nodex-proxy/blob/main/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`.