Skip to main content

​
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

CategoryPurposeKey Flags
Chain / SyncChain and synchronization settings--datadir, --networkid, --syncmode, --mainnet, --testnet
AccountsKey management--keystore, --unlock, --password
MiningBlock production--mine, --miner.etherbase, --miner.gaslimit
NetworkingP2P configuration--port, --maxpeers, --bootnodes, --nat
APIRPC endpoints--http, --http.port, --ws, --http.api
Transaction PoolTransaction pool tuning--txpool.pricelimit, --txpool.globalslots
PerformancePerformance tuning--cache, --cache.database, --cache.trie
StateState 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.
FlagPurposeDefault
--datadirRoot directory for all dataLinux: ~/.stablenet, macOS: ~/Library/StableNet
--datadir.ancientSeparate location for ancient/freezer data<datadir>/gstable/ancient
--keystoreOverride keystore location<datadir>/keystore
--datadir.minfreediskAuto-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.
FlagDescriptionDefault
--db.engineSelect state and chain database enginepebble

​
Synchronization Mode

The --syncmode flag controls how the blockchain is synchronized:
ModeValueDescriptionUse Case
FullfullDownload all blocks and execute all transactions and state transitions locallyValidator nodes, standard full nodes
SnapsnapDownload state snapshots first, then sync blocks to quickly build full stateFast initial sync
LightlightKeep only block headers; request state/data on demand from peersLow-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

FlagPurposeDefaultNotes
--mineEnable mining/validationfalseRequired for validators
--miner.etherbaseBlock reward addressNode key addressAuto-set in Anzeon
--miner.gaslimitBlock gas ceiling105,000,000Target block gas limit
--miner.extradataExtra block dataClient versionCustom 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

FlagPurposeDefault
--portP2P listening port30303
--maxpeersMaximum peer connections50
--natNAT port mapping methodany
--bootnodesBootstrap node enode URLs (comma-separated)Auto-selected per network
--nodiscoverDisable peer discoveryfalse
--nodekeyP2P node key file pathAuto-generated
--netrestrictAllowed network CIDR maskNone (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

FlagPurposeDefault
--httpEnable HTTP-RPC serverDisabled
--http.addrListening interfacelocalhost
--http.portListening port8545
--http.apiExposed API moduleseth,net,web3
--http.corsdomainAllowed CORS domainsNone
--http.vhostsAllowed virtual hostslocalhost

​
WebSocket Configuration

FlagPurposeDefault
--wsEnable WebSocket serverDisabled
--ws.addrListening interfacelocalhost
--ws.portListening port8546
--ws.apiExposed API moduleseth,net,web3
--ws.originsAllowed originsNone

​
IPC Configuration

IPC is enabled by default, creating a socket at <datadir>/gstable.ipc.
FlagPurposeDefault
--ipcdisableDisable IPCfalse
--ipcpathIPC socket pathgstable.ipc

​
API Namespace Security

Do not expose all API namespaces publicly. Recommended configurations:
Deployment TypeHTTP APIsWebSocket APIsNotes
Public RPC nodeeth,net,web3eth,net,web3Read-only, safe for public use
Validator nodeNone or localhost onlyNoneMinimize attack surface
Development nodeeth,net,web3,personal,debug,adminSameFull access for testing
Archive nodeeth,net,web3,txpool,debugSameDebug APIs for analysis
Warning: personal, admin, and debug namespaces provide privileged operations. Never expose them on public interfaces without authentication.

​
RPC Limiting Flags

FlagPurposeDefault
--rpc.gascapMax gas for eth_call / eth_estimateGas50,000,000
--rpc.evmtimeoutTimeout for eth_call5 seconds
--rpc.txfeecapMax fee for eth_sendTransaction0 (unlimited)
--rpc.batch-request-limitMax requests per batch1000
--rpc.batch-response-max-sizeMax batch response size25MB
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--gcmodeNotes
Validator (synced)4096+fullFast state access
Validator (initial sync)8192+fullFaster initial sync
Full node2048fullBalanced performance
Archive node8192+archiveNo 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.