Node Configuration

Purpose and Scope

This document explains how to configure a StableNet node using command-line flags, configuration files, and deployment patterns.

For information on building the node binary, see Installation and Building.
For genesis block setup and network initialization, see Genesis Setup and Network Initialization.

Configuration System Overview

StableNet node configuration uses a hierarchical system that converts command-line flags into structured configuration objects, which are then used to initialize each component.

Configuration precedence: Command-line flags > TOML configuration file > Defaults

Command-Line Flags

All configuration flags are defined in cmd/utils/flags.go and are grouped by category.

Core Flag Categories

Category	Purpose	Key Flags
Chain / Sync	Chain and synchronization settings	--datadir, --networkid, --syncmode, --mainnet, --testnet
Accounts	Key management	--keystore, --unlock, --password
Mining	Block production	--mine, --miner.etherbase, --miner.gaslimit
Networking	P2P configuration	--port, --maxpeers, --bootnodes, --nat
API	RPC endpoints	--http, --http.port, --ws, --http.api
Transaction Pool	Transaction pool tuning	--txpool.pricelimit, --txpool.globalslots
Performance	Performance tuning	--cache, --cache.database, --cache.trie
State	State management	--state.scheme, --gcmode

Network Selection Flags

StableNet provides flags for selecting predefined networks:

• --mainnet: Connect to StableNet mainnet (ChainID 8282)
• --testnet: Connect to StableNet testnet (ChainID 8283)
• --networkid: Override the automatic network ID (defaults to ChainID)
• Bootstrap nodes are automatically selected based on the network flag

Data Directory

The --datadir flag specifies the root directory where the node stores blockchain data and state.
Some sub-paths, such as the keystore, can be overridden with separate flags. If not specified, internal defaults are used.

Flag	Purpose	Default
--datadir	Root directory for all data	Linux: ~/.stablenet, macOS: ~/Library/StableNet
--datadir.ancient	Separate location for ancient/freezer data	<datadir>/gstable/ancient
--keystore	Override keystore location	<datadir>/keystore
--datadir.minfreedisk	Auto-shutdown disk threshold (MB)	0 (disabled)

Database Configuration

This setting controls the type of database engine used by the node.
It determines how state and chain data are stored and accessed internally, affecting performance and resource usage.

Flag	Description	Default
--db.engine	Select state and chain database engine	pebble

Synchronization Mode

The --syncmode flag controls how the blockchain is synchronized:

Mode	Value	Description	Use Case
Full	full	Download all blocks and execute all transactions and state transitions locally	Validator nodes, standard full nodes
Snap	snap	Download state snapshots first, then sync blocks to quickly build full state	Fast initial sync
Light	light	Keep only block headers; request state/data on demand from peers	Low-resource environments

State Scheme

The --state.scheme flag selects the state storage layout:

• hash: Legacy hash-based scheme (default, stable)
• path: Path-based scheme with Verkle trie support (experimental)

If not specified, the node automatically selects the scheme matching the existing database.

Mining and Validator Configuration

Flags controlling block production for StableNet validators (Anzeon-enabled networks).

Mining Flags

Flag	Purpose	Default	Notes
--mine	Enable mining/validation	false	Required for validators
--miner.etherbase	Block reward address	Node key address	Auto-set in Anzeon
--miner.gaslimit	Block gas ceiling	105,000,000	Target block gas limit
--miner.extradata	Extra block data	Client version	Custom identifier

Anzeon Network Design Characteristics

• etherbase is automatically derived from --nodekey and cannot be manually overridden
• GasTip (priority fee) is enforced as a network-wide value via GovValidator governance (except for authorized accounts)
• BaseFee uses a StableNet-customized calculation logic, with increase/decrease rates and min/max bounds controlled by chain parameters
• BaseFee is not burned; it is distributed to validators

For detailed gas fee policy, see Gas Fee Policy.
For governance-based gas tip management, see Validator Governance.

P2P Network Configuration

P2P networking flags control peer discovery and connection management.

P2P Configuration Flags

Flag	Purpose	Default
--port	P2P listening port	30303
--maxpeers	Maximum peer connections	50
--nat	NAT port mapping method	any
--bootnodes	Bootstrap node enode URLs (comma-separated)	Auto-selected per network
--nodiscover	Disable peer discovery	false
--nodekey	P2P node key file path	Auto-generated
--netrestrict	Allowed network CIDR mask	None (allow all)

Bootstrap Node Selection

Bootstrap nodes are selected in the following order:

1. Use --bootnodes if explicitly specified
2. Use bootstrap nodes defined in the config file
3. If --mainnet, use StableNet mainnet bootstrap nodes
4. If --testnet, use StableNet testnet bootstrap nodes

Static and Trusted Peers

Static and trusted peers can be configured in the [Node.P2P] section of a TOML configuration file:

[Node.P2P]
StaticNodes = [
  "enode://pubkey1@ip1:port1",
  "enode://pubkey2@ip2:port2"
]
TrustedNodes = [
  "enode://pubkey3@ip3:port3"
]

• StaticNodes: Peers the node always tries to maintain connections with
• TrustedNodes: Peers exempt from peer count limits

RPC API Configuration

RPC APIs expose node functionality to external clients. StableNet supports HTTP, WebSocket, and IPC transports.

HTTP Configuration

Flag	Purpose	Default
--http	Enable HTTP-RPC server	Disabled
--http.addr	Listening interface	localhost
--http.port	Listening port	8545
--http.api	Exposed API modules	eth,net,web3
--http.corsdomain	Allowed CORS domains	None
--http.vhosts	Allowed virtual hosts	localhost

WebSocket Configuration

Flag	Purpose	Default
--ws	Enable WebSocket server	Disabled
--ws.addr	Listening interface	localhost
--ws.port	Listening port	8546
--ws.api	Exposed API modules	eth,net,web3
--ws.origins	Allowed origins	None

IPC Configuration

IPC is enabled by default, creating a socket at <datadir>/gstable.ipc.

Flag	Purpose	Default
--ipcdisable	Disable IPC	false
--ipcpath	IPC socket path	gstable.ipc

API Namespace Security

Do not expose all API namespaces publicly. Recommended configurations:

Deployment Type	HTTP APIs	WebSocket APIs	Notes
Public RPC node	eth,net,web3	eth,net,web3	Read-only, safe for public use
Validator node	None or localhost only	None	Minimize attack surface
Development node	eth,net,web3,personal,debug,admin	Same	Full access for testing
Archive node	eth,net,web3,txpool,debug	Same	Debug APIs for analysis

Warning: personal, admin, and debug namespaces provide privileged operations. Never expose them on public interfaces without authentication.

RPC Limiting Flags

Flag	Purpose	Default
--rpc.gascap	Max gas for eth_call / eth_estimateGas	50,000,000
--rpc.evmtimeout	Timeout for eth_call	5 seconds
--rpc.txfeecap	Max fee for eth_sendTransaction	0 (unlimited)
--rpc.batch-request-limit	Max requests per batch	1000
--rpc.batch-response-max-size	Max batch response size	25MB

These limits protect the node from resource exhaustion by malicious or misconfigured clients.

Performance Tuning

Cache and database settings have a major impact on node performance and resource usage.

Cache Configuration

The --cache flag sets total memory allocation, which is split across subsystems. Default allocation:

Total cache: 1024 MB
├─ Database: 512 MB (50%)
├─ Trie Clean: 154 MB (15%)
├─ Snapshot: 102 MB (10%)
└─ Trie Dirty (GC): 256 MB (25%)

For archive nodes (--gcmode archive), Trie Dirty cache is disabled and reallocated to Trie Clean and Snapshot.

Recommended settings by node type:

Node Type	--cache	--gcmode	Notes
Validator (synced)	4096+	full	Fast state access
Validator (initial sync)	8192+	full	Faster initial sync
Full node	2048	full	Balanced performance
Archive node	8192+	archive	No pruning, large disk required

Database Engine Selection

The --db.engine flag selects the underlying key-value store:

• pebble (default): Modern, fast, better compression
• leveldb: Legacy, stable, compatible with older databases

Pebble is recommended for new deployments.

Garbage Collection and Pruning

The --gcmode flag controls state pruning behavior:

• full (default): Prunes old state tries, keeps recent state only
• archive: Keeps all historical state without pruning (requires TBs of disk)

Common Configuration Patterns

Validator Node

gstable --mainnet \
  --mine \
  --nodekey /path/to/nodekey \
  --syncmode full \
  --datadir /data/gstable \
  --cache 4096 \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --port 30303 \
  --maxpeers 50

• --mine enables block production
• --nodekey specifies the validator’s operational key (also used as etherbase in Anzeon)
• RPC is bound to localhost for security
• Validators must use --syncmode full

Public RPC Node

gstable --mainnet \
  --syncmode snap \
  --datadir /data/gstable \
  --cache 2048 \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --http.corsdomain "*" \
  --http.vhosts "*" \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --ws.api eth,net,web3 \
  --maxpeers 100

• --syncmode snap allowed since this is not a validator
• Bound to 0.0.0.0 for public access
• Only safe APIs exposed (eth, net, web3)

Development Node

gstable --dev \
  --dev.period 1 \
  --datadir /tmp/gstable-dev \
  --http \
  --http.addr 127.0.0.1 \
  --http.api eth,net,web3,personal,debug,admin \
  --allow-insecure-unlock

• --dev creates a temporary development network with pre-funded accounts
• --dev.period 1 produces a block every second
• All APIs enabled for debugging
• --allow-insecure-unlock allows HTTP account unlocking (development only)

Archive Node

gstable --mainnet \
  --syncmode full \
  --gcmode archive \
  --datadir /data/gstable-archive \
  --cache 8192 \
  --http \
  --http.addr 127.0.0.1 \
  --http.api eth,net,web3,debug,trace \
  --maxpeers 50

• --gcmode archive disables state pruning
• debug and trace APIs are useful for analysis
• Requires significant disk space (multiple TBs)

Configuration Files

While command-line flags are the primary configuration method, TOML configuration files are useful for managing complex deployments.

TOML Configuration Files

To export the current node configuration to a TOML file:

gstable dumpconfig > config.toml

Edit the generated file and load it with the --config flag:

gstable --config config.toml

Example TOML sections:

[Eth]
NetworkId = 8282
SyncMode = "full"
NoPruning = false

[Eth.Miner]
GasCeil = 105000000

[Node]
DataDir = "/data/gstable"
HTTPHost = "0.0.0.0"
HTTPPort = 8545
HTTPModules = ["eth", "net", "web3"]
WSHost = "0.0.0.0"
WSPort = 8546
WSModules = ["eth", "net", "web3"]
IPCPath = "gstable.ipc"

[Node.P2P]
MaxPeers = 100
ListenAddr = ":30303"
StaticNodes = []
TrustedNodes = []

Configuration precedence: Command-line flags > TOML file settings > Defaults

Genesis Configuration

For custom networks, the genesis configuration is provided as JSON and loaded using the gstable init command:

gstable init /path/to/genesis.json --datadir /path/to/datadir

For detailed information on the genesis file structure, see Genesis Setup and Network Initialization.