Configuration

This guide covers all configuration options for Ashen nodes, including environment variables, CLI arguments, and genesis configuration.

Quick Start

# Initialize a single node with funded account
node init --data-dir ./node-data --alloc "0xYOUR_ADDRESS=1000000000000"

# Run with defaults
node run --data-dir ./node-data

# Run with custom settings
NODE_BLOCK_TIME_MS=500 NODE_LISTEN=0.0.0.0:3030 node run

Environment Variables

All CLI arguments can be set via environment variables. The variable name is the argument name in SCREAMING_SNAKE_CASE with NODE_ prefix.

Core Settings

Variable	Default	Description
NODE_DATA_DIR	./node-data	Directory for chain data, genesis, and state
NODE_LISTEN	127.0.0.1:3030	RPC server listen address
NODE_BLOCK_TIME_MS	1000	Target block time in milliseconds
NODE_PRODUCE_EMPTY	true	Produce blocks even when mempool is empty
NODE_AUTH_TOKEN	none	Optional authentication token for RPC

Logging

Variable	Default	Description
NODE_LOG_FILE	stdout	Path to log file (enables rotation when set)
NODE_LOG_ROTATION	daily	Rotation policy: daily, hourly, or never
NODE_LOG_MAX_FILES	7	Maximum rotated log files to retain
NODE_LOG_PREFIX	node	Log file prefix (e.g., node.2026-01-22.log)

Rate Limiting

Variable	Default	Description
NODE_RATE_LIMIT_PER_S	1000	RPC requests per second limit
NODE_RATE_LIMIT_BURST	2000	RPC burst allowance
NODE_NO_RATE_LIMIT	false	Disable rate limiting (development only)
NODE_UTILITY_RATE_LIMIT_PER_S	100	Rate limit for /metrics and /health
NODE_UTILITY_RATE_LIMIT_BURST	200	Burst for utility endpoints
NODE_MAX_BODY_BYTES	20971520	Maximum request body size (20 MB)

State Management

Variable	Default	Description
NODE_ARCHIVE_MODE	false	Preserve all historical state (no pruning)
NODE_PRUNE_KEEP_EPOCHS	10	Epochs of state to retain (ignored in archive mode)
NODE_CHECKPOINT_INTERVAL	epoch boundary	Blocks between state checkpoints

Transaction Forwarding

Variable	Default	Description
NODE_TX_FORWARD_URL	none	Forward tx_submit to this URL (gateway mode)

---

CLI Commands

node init

Initialize a new node data directory with genesis configuration.

node init \
  --data-dir ./node-data \
  --alloc "0xADDRESS1=1000000000000" \
  --alloc "0xADDRESS2=500000000000" \
  --seed 42 \
  --seed-count 10 \
  --seed-balance 1000000000

Option	Description
--data-dir	Directory to initialize
--alloc ADDRESS=BALANCE	Pre-fund accounts (repeatable)
--seed	Seed for deterministic address generation
--seed-count	Number of seeded accounts to create
--seed-balance	Balance for each seeded account

node run

Run a node (single-node or validator mode).

# Single-node mode (development)
node run --data-dir ./node-data

# Validator mode (production)
node run \
  --data-dir ./node-data \
  --validator \
  --validator-network-key "keystore:my-validator" \
  --peers ./peers.yaml \
  --p2p-port 4040 \
  --bls-share "0x..." \
  --bls-polynomial "0x..."

node rpc

Run RPC server only, sharing data directory with another node.

node rpc \
  --data-dir ./validator-data \
  --listen 127.0.0.1:3031 \
  --refresh-interval-s 1

Useful for offloading RPC traffic from validators.

node follower

Run as P2P follower (non-validator), syncing via gossip.

node follower \
  --data-dir ./follower-data \
  --peers peers.yaml \
  --bootstrapper 0xPUBKEY... \
  --sync-batch-size 64 \
  --sync-poll-ms 500

Option	Default	Description
--sync-batch-size	32	Headers per sync request
--sync-poll-ms	1000	Poll interval when caught up

---

Consensus Configuration

Timeouts

Control consensus timing behavior. Defaults scale with block time.

Variable	Default	Description
NODE_LEADER_TIMEOUT_MS	2 × block_time	Wait for leader proposal
NODE_NOTARIZATION_TIMEOUT_MS	4 × block_time	Wait for notarization
NODE_NULLIFY_RETRY_MS	1000	Retry interval for nullification
NODE_FETCH_TIMEOUT_MS	10 × block_time	Timeout for block fetches
NODE_ACTIVITY_TIMEOUT	10 (view deltas)	Activity timeout before view change
NODE_SKIP_TIMEOUT	5 (view deltas)	When to skip to higher view

DKG (Distributed Key Generation)

Configure threshold BLS key generation for each epoch.

Variable	Default	Description
NODE_DKG_COMMIT_TIMEOUT_S	30	Commitment phase timeout
NODE_DKG_SHARE_TIMEOUT_S	30	Share distribution timeout
NODE_DKG_COMPLAINT_TIMEOUT_S	30	Complaint/justification timeout
NODE_DKG_FINALIZE_TIMEOUT_S	30	Finalization timeout
NODE_DKG_LEAD_BLOCKS	10	Blocks before epoch to start DKG
NODE_DKG_MAX_RETRIES	3	Retry attempts for failed DKG
NODE_TLE_SHARE_TIMEOUT_MS	500	TLE decryption share collection

Epochs

Epochs control key rotation and validator set changes.

EPOCH_LENGTH = 16 blocks (hardcoded)

• New threshold BLS keys are generated via DKG at epoch boundaries
• State checkpoints default to epoch boundaries
• Pruning is configured in epochs

---

P2P Configuration

For multi-validator deployments.

Variable	Default	Description
NODE_P2P_PORT	4040	P2P listen port (separate from RPC)
NODE_PEERS_FILE	none	Path to peers.yaml
NODE_BOOTSTRAPPERS	none	Bootstrapper public keys (hex)
NODE_LOCAL_P2P	false	Skip external IP discovery (testing)
NODE_P2P_MAILBOX_SIZE	16384	P2P message buffer size
NODE_P2P_MESSAGE_BACKLOG	16384	Message backlog size

peers.yaml Format

peers:
  - pubkey: "0x1234...abcd"
    address: "192.168.1.10:4040"
  - pubkey: "0x5678...efgh"
    address: "192.168.1.11:4040"
  - pubkey: "0x9abc...ijkl"
    address: "192.168.1.12:4040"

---

Keystore Configuration

Ashen uses an encrypted keystore for validator keys.

Variable	Description
NODE_KEYSTORE_PATH	Keystore file location (default: ~/.local/share/ashen/keystore/keystore.json)
NODE_VALIDATOR_NETWORK_KEY	Key reference: keystore:<handle> or ks:<label>

Key Formats

# Reference key by handle
--validator-network-key "keystore:my-validator-key"
--validator-network-key "ks:validator-1"

# Password input
--keystore-password-stdin     # Read from stdin
--keystore-password-file /path/to/password

BLS Keys (Production)

For production validators with pre-distributed BLS shares:

--bls-share "0x..."        # Your BLS share (hex)
--bls-polynomial "0x..."   # Public commitment polynomial (hex)

BLS Keys (Testnet)

For testing with deterministic keys:

--bls-seed 42              # Same seed across all validators
--validator-index 0        # Your index (0-based)

---

Genesis Configuration

The genesis.json file defines the initial chain state.

{
  "allocations": [
    {
      "address": "493615aa1e16a24f618d3ab6dd93a9250ca76e19996e46493a372c5994862e8c",
      "balance": 13370000000000
    },
    {
      "address": "deadbeef...",
      "balance": 1000000000000
    }
  ]
}

Field	Description
allocations	Initial account balances
allocations[].address	Account address (hex, no 0x prefix)
allocations[].balance	Initial balance in base units

---

Example Configurations

Local Development

# Single node, fast blocks, no rate limits
node run \
  --data-dir ./dev-data \
  --block-time-ms 500 \
  --no-rate-limit \
  --produce-empty-blocks

Production Validator

node run \
  --data-dir /var/lib/ashen \
  --validator \
  --validator-network-key "keystore:prod-validator" \
  --peers /etc/ashen/peers.yaml \
  --p2p-port 4040 \
  --listen 127.0.0.1:3030 \
  --bls-share "$BLS_SHARE" \
  --bls-polynomial "$BLS_POLY" \
  --archive-mode \
  --log-file /var/log/ashen/ \
  --log-rotation daily \
  --log-max-files 30

RPC Gateway

# Offload RPC from validator
node rpc \
  --data-dir /var/lib/ashen \
  --listen 0.0.0.0:3030 \
  --rate-limit-per-s 5000 \
  --rate-limit-burst 10000 \
  --refresh-interval-s 1

Archive Node (Follower)

node follower \
  --data-dir /var/lib/ashen-archive \
  --peers /etc/ashen/peers.yaml \
  --bootstrapper 0x... \
  --listen 0.0.0.0:3030 \
  --sync-batch-size 64

---

Debugging

Trace Output

Enable execution tracing for debugging:

ASHEN_TRACE_OUTPUT=1 node run --data-dir ./node-data
ASHEN_TRACE_OUTPUT_DIR=./traces node run --data-dir ./node-data

Skip Preflight

Skip startup validation (testing only):

node run --skip-preflight --data-dir ./node-data

---

Related

• Feature Flags — Compile-time configuration
• Gas Schedule — Execution costs
• RPC API — API endpoints