Skip to main content

​
Purpose and Scope

This document describes the initialization sequence and lifecycle management of a StableNet node.
It covers the process from command-line invocation to full shutdown, including configuration loading, genesis setup, component initialization, service coordination, and graceful termination. Related documents:

​
Overall Initialization Sequence

Node initialization follows the sequence below, from CLI flag parsing to a fully running node: 
CLI flag parsing → configuration loading → node.Node creation
→ eth.Ethereum backend initialization (DB, chain, pool, miner)
→ API/protocol registration → service startup → runtime monitoring

​
Configuration Phase

​
Flag Parsing and Data Directory Setup

At startup, the node initializes internal defaults and then applies configuration in the following order: network presets, configuration files, and command-line flags, to determine the final runtime configuration.
Settings applied later override values set in earlier stages.
OrderConfiguration SourceDescription
4Command-line flagsFinal overrides specified at runtime
3TOML configuration fileUser-defined persistent settings
2Network presetsNetwork-specific defaults such as Mainnet / Testnet
1Hardcoded defaultsInitial defaults defined in code
If the data directory is not explicitly specified, an internal default directory is used.

​
Genesis Block Initialization

The genesis block defines the initial state of the blockchain. The node loads an existing genesis from the database, or initializes a new one if none exists. For Anzeon/WBFT networks, genesis initialization includes the following additional steps:
  1. Constructing the initial validator set including BLS public keys
  2. Deploying system contracts (GovValidator, NativeCoinAdapter, etc.)
  3. Encoding WBFT-specific Extra data
  4. Setting initial gas tip parameters

​
Node and Backend Creation

​
Node Container

node.Node acts as the service orchestrator. It manages the P2P server, RPC endpoints, and registered services, and receives sub-services via RegisterLifecycle() and RegisterAPIs().

​
Ethereum Backend Initialization

eth.Ethereum is the main service implementing the full protocol. The eth.New() constructor performs initialization in the following order:
  1. Database setup: Open the chaindata database including ancient/freezer storage
  2. State scheme selection: Configure hash-based or path-based state storage
  3. Consensus engine creation: Select WBFT, Clique, or Ethash based on chain configuration
  4. Etherbase setup: Automatically derived from the node key for Anzeon networks
  5. BlockChain creation: Load genesis and configure caches and snapshots
  6. Transaction pool setup: Initialize legacypool and blobpool
  7. Protocol handler creation: Configure P2P synchronization and propagation logic
  8. Miner creation: Initialize the block assembly worker
  9. API and lifecycle registration: Register RPC APIs, P2P protocols, and service lifecycles

​
Transaction Pool Initialization

The transaction pool consists of two sub-pools:
  • legacypool: Handles standard transactions and StableNet-specific transaction types
  • blobpool: Handles EIP-4844 blob transactions
In Anzeon networks, the minimum gas tip is initialized from the GovValidator contract and applied to both the miner and the transaction pool.

​
Miner and Consensus Integration

The Worker runs the following four main goroutines:
  • mainLoop: Handles work requests and transaction events
  • newWorkLoop: Triggers new block creation (WBFT: driven by consensus round events)
  • taskLoop: Manages sealing tasks by calling engine.Seal()
  • resultLoop: Processes sealed blocks and inserts them into the chain

​
Service Registration and Lifecycle Management

​
API Registration

The backend exposes the following RPC API namespaces:
  • eth: Core Ethereum RPC methods
  • miner: Block production control
  • admin: Node and peer management
  • debug: Tracing and diagnostic utilities
  • net: Network information
  • Consensus-engine-specific APIs (e.g., WBFT management functions)

​
Protocol Registration

P2P protocols handle peer-to-peer communication:
  • eth: Block and transaction propagation
  • snap: State snapshot synchronization (if enabled)
  • wbft: WBFT consensus message exchange

​
Node Startup and Runtime

When StartNode() is called, services are started in registration order via stack.Start(), and runtime monitoring is enabled.

​
Disk Space Monitoring

The node periodically monitors disk space to prevent data corruption due to low disk conditions.
  • If --datadir.minfreedisk is set, that threshold is used
  • Otherwise, an internal default threshold is applied
  • A value of 0 disables monitoring

​
Graceful Shutdown Sequence

When a shutdown signal is received or low disk space is detected, the node performs an orderly shutdown. Shutdown characteristics:
  • Services are stopped in reverse startup order
  • Repeated signals can force termination
  • The shutdown process is traced and logged
  • All pending state changes are flushed to disk

​
Shutdown Tracker

The shutdown tracker (shutdowncheck) detects abnormal terminations:
  • Writes a shutdown marker at startup
  • Removes the marker on graceful shutdown
  • If a marker remains, the previous run is considered abnormal and a warning is logged
This mechanism enables early detection of potential database corruption.

​
Consensus-Specific Initialization

​
WBFT Consensus Startup

For Anzeon/WBFT networks, the following additional initialization steps are performed:
  1. Automatic etherbase setup: Forced to the address derived from the node key
  2. Gas tip initialization: Load the network-wide value from the GovValidator contract
  3. WBFT engine startup: Start the engine with consensus round callbacks registered
  4. Worker WBFT mode activation: Use an event-driven block production loop based on consensus signals

​
Component Summary

ComponentInitialization FunctionPrimary Responsibility
Nodenode.New()Service coordination, P2P server, RPC endpoints
Ethereum Backendeth.New()Full protocol implementation and component wiring
Blockchaincore.NewBlockChain()Canonical chain management and validation
Transaction Pooltxpool.New()Pending transaction management
Minerminer.New()Block production coordination
WorkernewWorker()Transaction selection and block assembly
Consensus Engineethconfig.CreateConsensusEngine()Block validation and sealing
Protocol HandlernewHandler()Block and transaction propagation
Downloaderdownloader.New()Chain synchronization
P2P Serverp2p.ServerPeer connections and protocol multiplexing