Configuration

Complete configuration reference for Kaizen Core nodes.

Full Configuration Reference

[node]
mode = "write"  # "write" (sequencer) or "read"
data_dir = "/var/lib/kaizen"
 
[network]
rpc_addr = "0.0.0.0:8545"        # JSON-RPC + WebSocket at /ws
grpc_addr = "0.0.0.0:9000"
write_node_addr = ""             # For read nodes only
 
[block]
interval_ms = 100
max_txs_per_block = 1000
 
[oracle]
ring_buffer_size = 65536
max_stale_ms = 3000
service_url = "http://localhost:8550"
timeout_ms = 10
 
[storage]
rocksdb_path = "/var/lib/kaizen/db"
snapshot_interval = 10000
 
[limits]
default_user_max_oi = 100000000000  # 100k USDC
default_min_bet = 1000000           # 1 USDC
default_max_bet = 10000000000       # 10k USDC
 
[metrics]
enabled = true
path = "/metrics"
 
[sentry]
enabled = false
dsn = ""
environment = "development"
traces_sample_rate = 0.1
release = ""
 
[genesis]
admins = ["0x..."]
feeders = ["0x..."]
relayers = ["0x..."]
 
[[genesis.oracle_pairs]]
base = "0x0000000000000000000000000000000000000001"
quote = "0x0000000000000000000000000000000000000100"
symbol = "BTC/USDT"
feeder = "0x..."
max_staleness_ms = 3000
 
[[genesis.oracle_pairs]]
base = "0x0000000000000000000000000000000000000002"
quote = "0x0000000000000000000000000000000000000100"
symbol = "ETH/USDT"
feeder = "0x..."
max_staleness_ms = 3000

Configuration Sections

Node

Parameter	Type	Default	Description
`mode`	string	`"write"`	Node mode: `"write"` (sequencer) or `"read"`
`data_dir`	string	`"/var/lib/kaizen"`	Base directory for all data

Network

Parameter	Type	Default	Description
`rpc_addr`	string	`"0.0.0.0:8545"`	JSON-RPC endpoint (WebSocket at `/ws` on same port)
`grpc_addr`	string	`"0.0.0.0:9000"`	gRPC endpoint for node sync
`write_node_addr`	string	`""`	Write node address (for read nodes only)

:::info WebSocket Endpoint WebSocket is served at the /ws path on the RPC port (e.g., ws://localhost:8545/ws), not on a separate port. :::

Block

Parameter	Type	Default	Description
`interval_ms`	u64	`100`	Checkpoint interval in milliseconds
`max_txs_per_block`	usize	`1000`	Maximum transactions per block

Oracle

Parameter	Type	Default	Description
`ring_buffer_size`	u64	`65536`	Number of price slots per market (~1.8 hours)
`max_stale_ms`	u64	`3000`	Maximum oracle staleness before rejecting orders
`service_url`	string	`"http://localhost:8550"`	Oracle service URL for price pulling
`timeout_ms`	u64	`10`	Oracle HTTP request timeout (milliseconds)

Storage

Parameter	Type	Default	Description
`rocksdb_path`	string	`"/var/lib/kaizen/db"`	RocksDB database path
`snapshot_interval`	u64	`10000`	Blocks between state snapshots

Storage Pruning

Configure data retention strategy:

[storage.pruning]
mode = "aggressive"  # or "archive"
keep_blocks = 10000
snapshot_interval = 1000
keep_snapshots = 10

Parameter	Type	Default	Description
`mode`	string	`"archive"`	Pruning mode: `"aggressive"` or `"archive"`
`keep_blocks`	u64	`10000`	Number of recent blocks to keep (aggressive mode)
`snapshot_interval`	u64	`1000`	Blocks between snapshots (aggressive mode)
`keep_snapshots`	u64	`10`	Number of snapshots to retain (aggressive mode)

Pruning Modes:

archive: No pruning. Keeps all blocks, snapshots, and JMT values. Use for historical queries.
aggressive: Minimal storage. Prunes old blocks, snapshots, and JMT values. Use for low-latency queries.

Limits

Parameter	Type	Default	Description
`default_user_max_oi`	u64	`100000000000`	Default max OI per user (100k USDC)
`default_min_bet`	u64	`1000000`	Minimum bet amount (1 USDC)
`default_max_bet`	u64	`10000000000`	Maximum bet amount (10k USDC)

Metrics

Parameter	Type	Default	Description
`enabled`	bool	`true`	Enable Prometheus metrics export
`path`	string	`"/metrics"`	Metrics endpoint path

See Monitoring for detailed metrics documentation.

Sentry

Parameter	Type	Default	Description
`enabled`	bool	`false`	Enable Sentry error tracking
`dsn`	string	`""`	Sentry DSN (Data Source Name)
`environment`	string	`"development"`	Environment tag (production/staging/dev)
`traces_sample_rate`	f32	`0.1`	Transaction sample rate (0.0 to 1.0)
`release`	string	`""`	Optional release/version tag

Genesis Configuration

Genesis configuration initializes the chain state on first startup. This section is only applied once when the database is empty.

Roles

Parameter	Type	Description
`admins`	string[]	Addresses with admin permission
`feeders`	string[]	Addresses allowed to submit oracle prices
`relayers`	string[]	Addresses allowed to process deposits/withdrawals

[genesis]
admins = ["0x742d35Cc6634C0532925a3b844Bc9e7595f0E123"]
feeders = ["0x8Ba1f109551bD432803012645Ac136ddd64DBA72"]
relayers = ["0x71C7656EC7ab88b098defB751B7401B5f6d8976F"]

Oracle Pairs

Configure trading pairs at genesis:

[[genesis.oracle_pairs]]
base = "0x0000000000000000000000000000000000000001"   # BTC token address
quote = "0x0000000000000000000000000000000000000100"  # USDT token address
symbol = "BTC/USDT"
feeder = "0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
max_staleness_ms = 3000
 
[[genesis.oracle_pairs]]
base = "0x0000000000000000000000000000000000000002"   # ETH token address
quote = "0x0000000000000000000000000000000000000100"  # USDT token address
symbol = "ETH/USDT"
feeder = "0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
max_staleness_ms = 3000

Field	Type	Description
`base`	string	Base token address (hex with 0x prefix)
`quote`	string	Quote token address (hex with 0x prefix)
`symbol`	string	Trading symbol for display
`feeder`	string	Authorized feeder address for this pair
`max_staleness_ms`	u64	Maximum price age in milliseconds (default: 3000)

Environment Variables

Configuration can also be set via environment variables with the KAIZEN_ prefix:

# Node settings
KAIZEN_NODE_MODE=write
KAIZEN_NODE_DATA_DIR=/var/lib/kaizen
 
# Network settings
KAIZEN_NETWORK_RPC_ADDR=0.0.0.0:8545
KAIZEN_NETWORK_WS_ADDR=0.0.0.0:8546
KAIZEN_NETWORK_GRPC_ADDR=0.0.0.0:9000
KAIZEN_NETWORK_WRITE_NODE_ADDR=write-node:9000
 
# Block settings
KAIZEN_BLOCK_INTERVAL_MS=100
KAIZEN_BLOCK_MAX_TXS_PER_BLOCK=1000
 
# Oracle settings
KAIZEN_ORACLE_SERVICE_URL=http://oracle:8550
KAIZEN_ORACLE_TIMEOUT_MS=10
KAIZEN_ORACLE_MAX_STALE_MS=3000
 
# Storage settings
KAIZEN_STORAGE_ROCKSDB_PATH=/var/lib/kaizen/db
 
# Metrics
KAIZEN_METRICS_ENABLED=true
 
# Sentry
KAIZEN_SENTRY_DSN=https://key@sentry.io/project
KAIZEN_SENTRY_ENVIRONMENT=production

Environment variables take precedence over config file values.

Example Configurations

Write Node (Production)

[node]
mode = "write"
data_dir = "/data/kaizen"
 
[network]
rpc_addr = "0.0.0.0:8545"
grpc_addr = "0.0.0.0:9000"
 
[block]
interval_ms = 100
max_txs_per_block = 5000
 
[oracle]
ring_buffer_size = 65536
max_stale_ms = 3000
service_url = "http://oracle:8550"
timeout_ms = 10
 
[storage]
rocksdb_path = "/data/kaizen/db"
snapshot_interval = 10000
 
[limits]
default_user_max_oi = 1000000000000    # 1M USDC
default_min_bet = 1000000               # 1 USDC
default_max_bet = 100000000000          # 100k USDC
 
[metrics]
enabled = true
path = "/metrics"
 
[sentry]
enabled = true
dsn = "https://key@sentry.io/project"
environment = "production"
traces_sample_rate = 0.05

Read Node (Aggressive - Low Latency)

[node]
mode = "read"
data_dir = "/data/kaizen"
 
[network]
rpc_addr = "0.0.0.0:8545"
grpc_addr = "0.0.0.0:9000"
write_node_addr = "write-node:9000"
 
[block]
interval_ms = 100
max_txs_per_block = 1000
 
[storage]
rocksdb_path = "/data/kaizen/db"
 
[storage.pruning]
mode = "aggressive"
keep_blocks = 10000        # ~16 minutes at 100ms blocks
snapshot_interval = 1000
keep_snapshots = 10
 
[metrics]
enabled = true
path = "/metrics"

Read Node (Archive - Full History)

[node]
mode = "read"
data_dir = "/data/kaizen"
 
[network]
rpc_addr = "0.0.0.0:8545"
grpc_addr = "0.0.0.0:9000"
write_node_addr = "write-node:9000"
 
[block]
interval_ms = 100
max_txs_per_block = 1000
 
[storage]
rocksdb_path = "/data/kaizen/db"
 
[storage.pruning]
mode = "archive"  # Keep all data
 
[metrics]
enabled = true
path = "/metrics"

Development

[node]
mode = "write"
data_dir = "./data"
 
[network]
rpc_addr = "127.0.0.1:8545"
grpc_addr = "127.0.0.1:9000"
 
[block]
interval_ms = 100
max_txs_per_block = 1000
 
[oracle]
ring_buffer_size = 65536
max_stale_ms = 30000  # 30 seconds for testing
service_url = "http://localhost:8550"
timeout_ms = 100
 
[storage]
rocksdb_path = "./data/db"
snapshot_interval = 1000
 
[limits]
default_user_max_oi = 1000000000000
default_min_bet = 100000      # 0.1 USDC
default_max_bet = 1000000000  # 1k USDC
 
[metrics]
enabled = true
path = "/metrics"
 
[genesis]
admins = ["0x0000000000000000000000000000000000000001"]
feeders = ["0x0000000000000000000000000000000000000002"]
relayers = ["0x0000000000000000000000000000000000000003"]