> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Architecture

## Purpose and Scope

This document provides an overview of StableNet’s core blockchain components and their interaction model. It explains the overall architecture of StableNet by focusing on the roles of each component and the relationships between them.

For detailed information on specific subsystems, refer to the following:

* Node startup and service registration: [Node Initialization and Lifecycle](/en/core-architecture/3.1-node-initialization-and-lifecycle)
* Block insertion and chain reorganization: [Blockchain Management](/en/core-architecture/3.2-blockchain-management)
* State trie and account management: [State Management](/en/core-architecture/3.3-state-management)
* Transaction validation and queues: [Transaction Pool](/en/core-architecture/3.4-transaction-pool)
* Transaction data structures: [Transaction Types and Encoding](/en/core-architecture/3.5-transaction-types-and-encoding)
* Block data structures: [Block Structure and Encoding](/en/core-architecture/3.6-block-structure-and-encoding)
* Consensus mechanisms: [Consensus and Block Production](/en/consensus-and-block-production/index)
* P2P networking: [Networking](/en/networking/index)
* RPC interfaces: [RPC and APIs](/en/rpc-and-apis/index)

## Architecture Overview

A StableNet node is composed of a layered architecture. At the top sits the node container (`node.Node`), within which the Ethereum protocol implementation (`eth.Ethereum`) coordinates core components such as the blockchain, transaction pool, and consensus engine.

```
  node.Node (service container)
  ├─ P2P server, RPC/IPC/WS servers, account manager
  │
  └─ eth.Ethereum (protocol implementation)
     ├─ BlockChain   ← canonical chain, block insertion/validation
     ├─ StateDB      ← account/storage state management
     ├─ TxPool       ← pending transaction management
     ├─ Miner/Worker ← block assembly and sealing
     ├─ Engine       ← consensus (WBFT/Clique/Ethash)
     └─ Handler      ← P2P synchronization, block/tx propagation
```

## Core Components

### node.Node — Service Container

The top-level container that manages the lifecycle of all services. It initializes the P2P server, RPC/IPC/WebSocket servers, and databases, and starts and stops registered services in order. It does not contain blockchain logic; instead, it provides the infrastructure layer required to run a node.

### eth.Ethereum — Ethereum Protocol Implementation

The main service that coordinates core blockchain components. During initialization, it creates and connects the database, blockchain, transaction pool, miner/worker, and consensus engine. It also registers RPC APIs and P2P protocols with the node, enabling external interaction.

### BlockChain — Canonical Chain Management

The core component responsible for managing the canonical chain. It coordinates block validation, insertion, state execution, and chain reorganization (reorg). Block validity is verified through the consensus engine, while account and storage state are managed via StateDB. Frequently accessed blocks and receipts are cached using LRU caches to optimize query performance. For details, see [Blockchain Management](/en/core-architecture/3.2-blockchain-management).

### StateDB — State Management

Provides a caching layer on top of the Merkle Patricia Trie to manage account balances, nonces, contract code, and storage. State changes during transaction execution are journaled to support rollback on failure, and snapshots are used to enable fast state queries. For details, see [State Management](/en/core-architecture/3.3-state-management).

### TxPool — Transaction Pool

Manages pending transactions that have not yet been included in a block. Transactions are received via RPC and P2P, validated for signature, nonce, balance, and gas conditions, and then classified as executable (pending) or future (queued). The pool consists of a `legacypool` for standard transactions and a `blobpool` for blob transactions (EIP-4844). For details, see [Transaction Pool](/en/core-architecture/3.4-transaction-pool).

### Miner/Worker — Block Production

The block proposer assembles a block candidate by including pending transactions and finalizes it through validator consensus via the consensus engine. The Worker runs four goroutines—`mainLoop`, `newWorkLoop`, `taskLoop`, and `resultLoop`—to perform transaction selection, block assembly, sealing requests, and result handling in parallel.

### consensus.Engine — Consensus Engine

An interface that abstracts block validation and sealing. In StableNet, the Anzeon WBFT consensus engine is used, and it is responsible for block proposal, voting, and seal verification.

## StableNet-Specific Design

StableNet is based on go-ethereum, but it introduces the following extensions to support stablecoin operations and governance-centric consensus.

### Anzeon WBFT Consensus

* **Governance-based validators**: The validator set is determined by voting results from the GovValidator contract; staking is not used.
* **No block rewards**: There is no inflation from new issuance; validators are rewarded only through transaction fees.
* **BLS signature aggregation**: BLS aggregated signatures are used for PREPARE/COMMIT consensus messages to reduce verification costs.
* **Epoch-based validator updates**: Changes to the validator set are applied only at epoch blocks.

### Gas Fee Policy

* **Governance-controlled gas tip**: The minimum gas tip (priority fee) is managed as a network-wide value by the GovValidator contract.
* **Approved account exceptions**: Accounts approved by governance are allowed to specify custom gas tips.
* **Dynamic gas tip propagation**: The latest gas tip is synchronized to the worker and transaction pool each time a new block is added to the chain.

### Fee Delegation

Using the StableNet-specific transaction type (0x16), the sender and the fee payer can be separated. In this case, ECDSA signatures from both the sender and the fee payer are required.

### Automatic Etherbase Configuration

In the Anzeon network, the etherbase is automatically derived from the node’s operational key (nodekey) and cannot be manually configured by the user.

## Initialization Flow Summary

A StableNet node is initialized in the following order:

1. **CLI flag parsing** — Load network settings, data directory, and TOML configuration
2. **Node creation** — `node.Node` prepares P2P, RPC, and database infrastructure
3. **Database opening** — Initialize chaindata and ancient (freezer) stores
4. **Consensus engine creation** — Select WBFT/Clique/Ethash based on chain configuration
5. **Blockchain initialization** — Load genesis, create BlockChain, configure snapshots
6. **Transaction pool setup** — Create legacypool and blobpool
7. **Miner/worker creation** — Start goroutines related to block assembly
8. **API and protocol registration** — Register RPC handlers and P2P protocols
9. **Service startup** — Start registered services in order

For detailed initialization steps, see [Node Initialization and Lifecycle](/en/core-architecture/3.1-node-initialization-and-lifecycle).

## Data Flow Overview

### Transaction Processing Flow

```
User/DApp → RPC (eth_sendRawTransaction)
          → TxPool.Add() — signature, nonce, balance, gas validation
          → classified as pending transaction
          → propagated to the P2P network
          → Miner calls Pending() → block assembly
          → consensus.Engine.Seal() → block sealing
          → BlockChain.InsertChain() → chain insertion
          → state commit and event publication
```

### Block Synchronization Flow

```
Peer node → P2P protocol
          → Handler receives block
          → BlockChain.InsertChain() — header, body, and state validation
          → chain reorganization (reorg) if necessary
          → notify TxPool of new head → pool state update
```

## Database Structure

The storage layer is composed of the following hierarchy:

* **ChainDB**: A persistent store based on LevelDB or Pebble that stores blocks, receipts, and canonical mappings.
* **Ancient Store (Freezer)**: Separates old block data into an append-only store to manage ChainDB size.
* **TrieDB**: Manages Merkle Patricia Trie nodes and supports both hash-based and path-based schemes.
* **Snapshot**: Stores state in a flattened key-value structure to enable fast queries.

For details, see [Storage Architecture](/en/storage-architecture/index).

## Chain Configuration

Chain-specific parameters are defined in `params.ChainConfig` and control fork activation points, consensus rules, and network-specific settings.

| Item                   | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| `ChainID`              | Unique chain identifier                                     |
| Fork activation blocks | Block heights at which EIPs are activated                   |
| `Anzeon`               | WBFT consensus parameters and system contract configuration |

The Anzeon configuration includes consensus parameters such as block period (`BlockPeriod`), epoch size (`Epoch`), and request timeout (`RequestTimeout`), as well as system contract initialization information.