Genesis Configuration and Network Initialization

Purpose and Scope

This document explains how to generate the genesis block, initialize the chain, and prepare validator keys for the StableNet network. It covers both automated generation using the genesis_generator tool and manual genesis file authoring. Related documents:

Node Configuration — runtime options and configuration for initialized nodes
System Contracts Overview — detailed structure and storage layout of system contracts
Network Deployment — production network deployment procedures
Validator Operations — validator node operation and key management

Genesis File Structure

The genesis file is a JSON file that defines the initial state of the blockchain, including chain configuration, initial account allocations, and consensus parameters.

Core Genesis Fields

Genesis structure:

Field	Type	Description
`Config`	`*params.ChainConfig`	Chain configuration including fork rules and consensus settings
`Timestamp`	`uint64`	Genesis block timestamp
`ExtraData`	`[]byte`	In Anzeon chains, WBFT validator information RLP-encoded
`GasLimit`	`uint64`	Initial block gas limit
`Difficulty`	`*big.Int`	Initial difficulty (1 in Anzeon)
`Alloc`	`types.GenesisAlloc`	Pre-allocated accounts and deployed contract code
`BaseFee`	`*big.Int`	EIP-1559 base fee

Anzeon Consensus Configuration

For Anzeon/WBFT chains, the ChainConfig includes an Anzeon field. This configuration defines two validator sets:

Init: Validators active from block 1 until the first epoch (hardcoded in the genesis block ExtraData)
SystemContracts.GovValidator: Validator set applied from the second epoch onward (modifiable via governance)

Unless there is a specific reason, these two sets should be identical.
For details on the epoch transition mechanism, see Anzeon WBFT Consensus Protocol.

System Contracts

StableNet deploys five system contracts at fixed addresses in the genesis block:

Contract	Address	Purpose
NativeCoinAdapter	`0x0000000000000000000000000000000000001000`	ERC20 wrapper for the native coin
GovValidator	`0x0000000000000000000000000000000000001001`	Validator set management and gas tip governance
GovMasterMinter	`0x0000000000000000000000000000000000001002`	Master minter registry
GovMinter	`0x0000000000000000000000000000000000001003`	Mint/burn governance
GovCouncil	`0x0000000000000000000000000000000000001004`	Blacklist and certified account governance

System contracts are deployed without owners and can only be upgraded via hard forks.
For detailed initialization parameters, storage slots, and dependencies of each contract, see System Contracts Overview.

Genesis Initialization Parameters

The following parameters must be configured at genesis. GovValidator:

Parameter	Description	Default
`members`	Governance member addresses (comma-separated)	Required
`validators`	Validator addresses (comma-separated)	Required
`blsPublicKeys`	BLS public keys (0x-prefixed, comma-separated)	Required
`quorum`	Minimum number of votes required to pass a proposal	Required
`expiry`	Proposal expiration time (seconds)	604800 (7 days)
`memberVersion`	Member set version	”1”
`maxProposals`	Maximum concurrent proposals (1–50)	3
`gasTip`	Mandatory gas tip (wei)	27600000000000 (27600 Gwei)

members, validators, and blsPublicKeys are parallel lists managed in the same order.
Values at the same index across lists define a single validator identity.

Operator address (members): EOA or multisig address used for governance voting and validator registration/removal
Validator address (validators): Address used for consensus message signing and coinbase (block fee recipient), derived from the node’s nodekey
BLS public key (blsPublicKeys): BLS public key derived from the validator key, used for WBFT PREPARE/COMMIT aggregate signatures

For detailed key roles, derivation, and operational guidance, see Validator Operations. NativeCoinAdapter:

Parameter	Description	Default
`name`	Token name	”WKRC”
`symbol`	Token symbol	”WKRC”
`decimals`	Decimal places	”18”
`currency`	Fiat currency label	”KRW”
`masterMinter`	GovMasterMinter contract address	`0x...1002`
`minters`	GovMinter contract address	`0x...1003`
`minterAllowed`	Maximum mintable amount per minter	10^28

Validator Key Preparation

Each validator’s keys must be generated before network initialization.

Node Key Generation

Use the bootnode utility to generate node keys:

# Generate node key
bootnode -genkey nodekey

# Inspect derived address and BLS keys
bootnode -nodekey nodekey -writeaddress

Values derived from the node key:

Derived Item	Function	Purpose
Validator address	`crypto.PubkeyToAddress(nodeKey.PublicKey)`	Block signing address (coinbase)
BLS private key	`bls.DeriveFromECDSA(nodeKey)`	Consensus message signing
BLS public key	`blsKey.PublicKey().Marshal()`	Registered in genesis (48 bytes, hex-encoded)

For validator key security, rotation, and multisig operator keys, see Validator Operations.

genesis_generator Tool

genesis_generator is a CLI tool that generates a genesis file with correctly configured system contracts.

Build

cd go-stablenet
make genesis_generator

# Binary location: build/bin/genesis_generator

Interactive Mode

Running without arguments starts interactive mode:

./build/bin/genesis_generator

You will be prompted for:

Consensus engine selection: choose Anzeon (WBFT)
Number of nodes: single-node or multi-node
Node key paths: path to each validator’s node key file (default: ./nodekey)
Quorum configuration: governance quorum for multi-node setups (min 2, max = validator count)
Chain ID: unique network identifier (random if omitted)

The tool automatically derives validator addresses and BLS keys from node keys.

Command-Line Flags

Non-interactive usage is also supported (cmd/genesis_generator/genesis_generator.go 50–100):

Flag	Type	Description	Default
`--chainId`	`int`	Network chain ID	Random
`--validators`	`string`	Validator addresses (comma-separated)	-
`--blsKeys`	`string`	BLS public keys (comma-separated)	-
`--members`	`string`	Governance member addresses (comma-separated)	-
`--quorum`	`int`	Governance quorum	-
`--epochLength`	`int`	Blocks per epoch	10
`--blockPeriod`	`int`	Target block time (seconds)	1
`--gasLimit`	`uint64`	Genesis block gas limit	-
`--output`	`string`	Output file path	genesis.json

Generation Examples

Single-validator network:

./build/bin/genesis_generator \
  --chainId 9999 \
  --validators 0xaa5f...1234 \
  --blsKeys 0xaec4...5678 \
  --members 0xaa5f...1234 \
  --quorum 1 \
  --output genesis.json

Multi-validator network:

./build/bin/genesis_generator \
  --chainId 9999 \
  --validators 0xaa5f...1234,0x294f...5678 \
  --blsKeys 0xaec4...abcd,0x91b2...efgh \
  --members 0xaa5f...1234,0x294f...5678 \
  --quorum 2 \
  --epochLength 10 \
  --blockPeriod 1 \
  --output genesis.json

Genesis Validation

During generation, genesis_generator automatically validates:

Matching lengths of Init.Validators and Init.BLSPublicKeys arrays
Correct hex encoding and length (96 bytes) of each BLS public key
Valid Ethereum address format for all validator and member addresses
Valid ranges for epoch length, block period, and timeout values
Correct system contract addresses

Chain Initialization

Running gstable init

Initialize the chain database with the genesis file:

# Initialize with default data directory
gstable init genesis.json

# Specify a custom data directory
gstable init genesis.json --datadir /data/gstable

Initialization steps:

Load genesis file and validate Anzeon configuration
Generate WBFT ExtraData from the initial validator set
Deploy system contracts via InjectContracts()
Commit the genesis block to the database

If an existing database is found, the provided genesis is checked against the stored genesis.
A mismatch results in a GenesisMismatchError.

Starting Nodes After Initialization

# Start a validator node
gstable --datadir /data/gstable \
  --networkid 9999 \
  --mine \
  --nodekey /path/to/nodekey \
  --syncmode full \
  --port 30303

# With explicit bootnodes
gstable --datadir /data/gstable \
  --networkid 9999 \
  --bootnodes "enode://pubkey@ip:port"

For full runtime options, see Node Configuration.

Two-Phase Validator Initialization

StableNet manages validator sets in two phases: Phase 1: First Epoch (Block 1 ~ epochLength)

Defined in Anzeon.Init.Validators
Hardcoded in the genesis block ExtraData
Not modifiable via governance

Phase 2: From Second Epoch Onward

Defined in SystemContracts.GovValidator.Params
Validator set updated at epoch blocks by reading GovValidator contract state
Modifiable via governance voting

This design allows the chain to bootstrap with a minimal validator set and then transition to governance-controlled validator management.
For details, see Validator Governance.

Network-Specific Configuration

Mainnet

Chain ID: 8282
Network flag: --mainnet
Bootnodes: automatically configured (params.StableNetMainnetBootnodes)
Genesis: embedded in the binary (no init required)

# Start a Mainnet node (genesis auto-loaded)
gstable --mainnet --syncmode full --datadir /data/gstable

Testnet

Chain ID: 8283
Network flag: --testnet
Bootnodes: automatically configured (params.StableNetTestnetBootnodes)
Genesis: embedded in the binary (no init required)

# Start a Testnet node
gstable --testnet --syncmode full --datadir /data/gstable

Private Network

Private networks require a custom genesis file. Setup procedure:

Generate node keys for each validator (bootnode -genkey)
Generate the genesis file using genesis_generator
Run gstable init genesis.json on all nodes
Start nodes with --networkid and --bootnodes specified

Recommended parameters for private networks:

Parameter	Development	Production
`chainId`	Unique value not colliding with public networks	Same
`epochLength`	5–10 (fast validator changes)	100+
`blockPeriod`	1 second	1–3 seconds
`quorum`	1 (single node)	≥ 2/3 of validators
`gasLimit`	Default	Adjust to network needs

Private network startup example:

# 1. Generate node keys
bootnode -genkey nodekey1
bootnode -genkey nodekey2

# 2. Generate genesis (interactive mode recommended)
./build/bin/genesis_generator

# 3. Initialize each node
gstable init genesis.json --datadir /data/node1
gstable init genesis.json --datadir /data/node2

# 4. Start the first node
gstable --datadir /data/node1 \
  --networkid 9999 \
  --mine \
  --nodekey nodekey1 \
  --syncmode full \
  --port 30303

# 5. Start the second node (using the first as bootnode)
gstable --datadir /data/node2 \
  --networkid 9999 \
  --mine \
  --nodekey nodekey2 \
  --syncmode full \
  --port 30304 \
  --bootnodes "enode://<node1-pubkey>@<node1-ip>:30303"

For production deployment checklists, Docker deployment, and Debian packages, see Network Deployment.

Post-Initialization Verification

After initialization, verify the following:

# Attach to the node
gstable attach /data/gstable/gstable.ipc

# Check chain ID
> eth.chainId()

# Check genesis block
> eth.getBlock(0)

# Check validator set (system contract call)
> eth.call({to: "0x0000000000000000000000000000000000001001", data: "0x..."})

# Check peer connections
> admin.peers.length

# Check mining status (validator node)
> eth.mining

# Check block production
> eth.blockNumber

Common Initialization Issues and Resolutions

Genesis Mismatch Error

Error: GenesisMismatchError: database contains incompatible genesis Cause: Attempting to initialize with a genesis file that does not match the existing database. Resolution:

# Option 1: Remove existing chain data and reinitialize
rm -rf /data/gstable/gstable/chaindata
gstable init genesis.json --datadir /data/gstable

# Option 2: Use the correct genesis.json matching the existing chain

Validator Count Mismatch

Error: Invalid genesis config: validator count mismatch Cause: Length mismatch between Init.Validators and Init.BLSPublicKeys. Resolution: Ensure members, validators, and blsPublicKeys all have the same number of entries.

System Contract Deployment Failure

Error: Failed to inject system contracts Cause: Invalid initialization parameters or missing contract bytecode. Resolution: Verify system contract parameters, especially address format (0x prefix, 40 hex chars) and comma-separated list syntax.

BLS Key Format Error

Error: Invalid BLS public key format Cause: Incorrect hex encoding or length of the BLS key. Resolution: BLS public keys must include a 0x prefix and be exactly 98 characters long
(0x + 96-byte hex encoding = 0x + 192 hex characters).
Verify using bootnode -nodekey.

Init vs GovValidator Validator Mismatch Warning

If Init.Validators and SystemContracts.GovValidator.Params.validators differ, the validator set will change at the transition from the first to the second epoch.
Unless intentional, keep both sets identical.

StableNet Overview

Getting Started

Core Architecture

Consensus and Block Production

Governance System

Transaction Processing

Networking

RPC and APIs

Storage Architecture

Development Tools

Operations Guide

​Purpose and Scope

​Genesis File Structure

​Core Genesis Fields

​Anzeon Consensus Configuration

​System Contracts

​Genesis Initialization Parameters

​Validator Key Preparation

​Node Key Generation

​genesis_generator Tool

​Build

​Interactive Mode

​Command-Line Flags

​Generation Examples

​Genesis Validation

​Chain Initialization

​Running gstable init

​Starting Nodes After Initialization

​Two-Phase Validator Initialization

​Network-Specific Configuration

​Mainnet

​Testnet

​Private Network

​Post-Initialization Verification

​Common Initialization Issues and Resolutions

​Genesis Mismatch Error

​Validator Count Mismatch

​System Contract Deployment Failure

​BLS Key Format Error

​Init vs GovValidator Validator Mismatch Warning