> ## 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.

# Block Production and Mining

## Purpose and Scope

This page describes the full flow by which a StableNet node produces and mines blocks.\
It covers the role of the worker, block candidate assembly, transaction selection and execution, and the process of submitting the generated block to the consensus engine (WBFT) for finalization.\
For details on the WBFT consensus protocol itself, including voting, BLS signature aggregation, and epoch management, see [Anzeon WBFT Consensus Protocol](/en/consensus-and-block-production/4.1-anzeon-wbft-consensus-protocol).

## Worker Architecture

The `worker` is the core component responsible for block production in StableNet.\
It selects and executes transactions from the transaction pool, assembles blocks, and submits completed block candidates to the consensus engine for sealing.

### Worker Structure

The worker maintains multiple goroutines to process each stage of block production in parallel.

| Component     | Goroutine | Purpose                                                            |
| ------------- | --------- | ------------------------------------------------------------------ |
| `mainLoop`    | Yes       | Handles work requests and events, coordinates block assembly       |
| `newWorkLoop` | Yes       | Triggers block creation based on chain events or consensus signals |
| `taskLoop`    | Yes       | Submits assembled blocks to the consensus engine                   |
| `resultLoop`  | Yes       | Receives sealed blocks and writes them to the chain                |

**Key Fields**

* `current *environment` : Execution environment of the block currently being assembled
* `coinbase common.Address` : Block producer address (validator address)
* `tip *uint256.Int` : Minimum gas tip required for transaction inclusion
* `pendingTasks map[common.Hash]*task` : Block tasks awaiting sealing
* `txsCh`, `chainHeadCh`, `readyToCommitCh` : Channels for transactions, chain head updates, and consensus signals

### Worker Initialization

When Anzeon mode is enabled, the worker initializes by reading the network-wide gas tip from the GovValidator contract.\
Afterward, each time a new block is added to the chain, a callback is triggered to re-read the latest gas tip and update internal state and transaction pool filtering criteria.

## Block Production Flow

### WBFT vs Origin Work Loop

StableNet uses different block production strategies depending on whether the consensus engine is WBFT.

* **Origin (Ethereum default)**: Attempts new blocks periodically based on a timer
* **WBFT**: Starts block production only when the consensus engine emits a `readyToCommitCh` signal

In WBFT mode, blocks are created only at the exact moment when the node is selected as the proposer, preventing unnecessary re-assembly.

### WBFT Ready-to-Commit Mechanism

The WBFT engine requests block production via the `readyToCommit(round)` callback.\
The `round` value indicates the current consensus round, where `round = 0` is the initial attempt and `round > 0` represents retries after previous failures.

## Block Assembly Process

### Main Loop and Commit Work

`mainLoop()` receives consensus signals or chain events and then invokes `commitWork()`, which performs the actual block assembly.\
This function sequentially creates the block header, prepares the execution environment, and executes transactions.

### prepareWork – Block Header Setup

`prepareWork()` prepares the header and execution environment for a new block.

**Steps**

1. **Select parent block**: Choose the latest chain head or a specified parent
2. **Timestamp validation**: Adjust to ensure the timestamp is later than the parent block
3. **Header creation**: Initialize base header fields via `makeHeader()`
4. **Environment setup**: Create state snapshot and gas pool via `makeEnv()`
5. **Engine preparation**: Call `engine.Prepare()` to set consensus-specific fields, including proposer and coinbase for WBFT

### Transaction Selection and Execution

`fillTransactions()` selects transactions from the transaction pool that are eligible for inclusion in the current block.\
Selection is based on gas tip, nonce ordering, and per-account validity checks.

### commitTransactions – Execution Loop

`commitTransactions()` executes the selected transactions sequentially.

* On `ErrNonceTooLow`, the transaction is skipped and the next nonce transaction for the same account is attempted
* On successful execution, a receipt is recorded and execution proceeds to the next transaction
* On fatal errors, all subsequent transactions from the same account are excluded

### applyTransaction – State Transition

Each transaction is applied to the state via `applyTransaction()`.

1. Create a pre-execution state snapshot
2. Execute EVM logic and apply state changes via `core.ApplyTransaction()`
3. Revert to the snapshot on failure
4. On success, add the transaction and receipt to the block

Nonce validation, balance checks, gas accounting, and EVM execution are all handled internally by `core.ApplyTransaction()`.

### Block Finalization

Once all transactions are executed, the block enters the finalization phase.\
In a WBFT environment, since there are no block rewards, `Finalize()` performs minimal work, mainly computing the state root and receipt root.

## Sealing and Result Handling

### Task Submission Loop

`taskLoop()` submits completed blocks to the consensus engine.

* **WBFT**: The block is passed to the consensus engine, initiating PREPARE and COMMIT voting
* **Other engines**: Engine-specific sealing logic is executed

Results are delivered back to the worker through `resultCh`.

### Result Handling Loop

`resultLoop()` receives sealed blocks and writes them to the chain.

* Set block hash, block number, and transaction index in receipts
* Persist the block and state root to the database
* In Anzeon mode, re-query the GovValidator contract after block insertion to refresh the gas tip

## Transaction Filtering and Gas Tip Handling

### Gas Tip Handling in Anzeon

In the Anzeon network, gas tips are not individually configured by validators but are globally managed by governance (GovValidator).\
`updateGasTipFromContract()` reads the contract state and updates the minimum gas tip requirement for both the worker and the transaction pool.

This ensures:

1. Only transactions paying sufficient gas tips are included in block candidates
2. Gas tip changes take effect immediately from the next block
3. The transaction pool proactively filters out transactions below the required threshold

### Transaction Prioritization

Transactions are ordered using the `transactionsByPriceAndNonce` structure.

**Priority Rules**

1. **Local transactions first**
2. **Effective gas price**: `min(gasTipCap + baseFee, gasFeeCap)`
3. **Nonce ordering**: Sequential processing within each account
4. **Cross-account price comparison**: Higher effective gas price first

Blob transactions and regular transactions are managed separately internally, but final selection follows the same pricing rules.

## Environment and State Management

### Execution Environment

The `environment` structure holds all execution state required during block assembly.

| Field                       | Purpose                             |
| --------------------------- | ----------------------------------- |
| `signer types.Signer`       | Transaction signature verification  |
| `state *state.StateDB`      | State trie                          |
| `tcount int`                | Number of transactions in the block |
| `gasPool *core.GasPool`     | Remaining gas limit                 |
| `header *types.Header`      | Header of the block being built     |
| `txs []*types.Transaction`  | Included transactions               |
| `receipts []*types.Receipt` | Execution receipts                  |

The environment is created in `makeEnv()`, which prepares a state copy based on the parent block and initializes the gas pool.

### State Changes and Commit

State changes are managed in the following order.

1. Modify StateDB through transaction execution
2. Roll back using snapshots when necessary
3. Commit state to the trie after successful block sealing
4. Persist the block and state root to the database

`updateSnapshot()` maintains the pending block state to support RPC calls such as `eth_getBlockByNumber("pending")`.

## Integration with Miner Wrapper

The `Miner` type wraps the `worker` and controls block production based on node synchronization status.\
Block production is paused during chain synchronization and automatically resumed once synchronization completes.

## Summary Flow

The block production process can be summarized as follows.

1. Consensus engine or chain event triggers block production
2. Worker prepares the block header and execution environment
3. Transactions are selected and executed
4. The block is finalized and submitted to the consensus engine
5. After sealing, the block is written to the chain and gas tips are synchronized

Through this structure, StableNet maintains a stable block production pipeline tightly integrated with WBFT consensus.