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:

Use --bootnodes if explicitly specified
Use bootstrap nodes defined in the config file
If --mainnet, use StableNet mainnet bootstrap nodes
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.

StableNet Overview

Getting Started

Core Architecture

Consensus and Block Production

Governance System

Transaction Processing

Networking

RPC and APIs

Storage Architecture

Development Tools

Operations Guide

Documentation Index

​Purpose and Scope

​Configuration System Overview

​Command-Line Flags

​Core Flag Categories

​Network Selection Flags

​Data Directory

​Database Configuration

​Synchronization Mode

​State Scheme

​Mining and Validator Configuration

​Mining Flags

​Anzeon Network Design Characteristics

​P2P Network Configuration

​P2P Configuration Flags

​Bootstrap Node Selection

​Static and Trusted Peers

​RPC API Configuration

​HTTP Configuration

​WebSocket Configuration

​IPC Configuration

​API Namespace Security

​RPC Limiting Flags

​Performance Tuning

​Cache Configuration

​Database Engine Selection

​Garbage Collection and Pruning

​Common Configuration Patterns

​Validator Node

​Public RPC Node

​Development Node

​Archive Node

​Configuration Files

​TOML Configuration Files

​Genesis Configuration