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

# Transaction Lifecycle

## Purpose and Scope

This document describes the complete lifecycle of a transaction in StableNet, from the moment it is submitted to the system until it is **finally included (finalized)** on the blockchain.\
It covers the entire process, including submission via RPC or P2P, transaction pool validation and acceptance, mining candidate selection, state transition (EVM execution), block sealing, and consensus-based finalization.

For details on transaction types and encoding, see [Transaction Types and Encoding](/en/core-architecture/3.5-transaction-types-and-encoding).\
For transaction pool management policies, see [Transaction Pool](/en/core-architecture/3.4-transaction-pool).\
For internal EVM execution behavior, see [EVM Execution](/en/transaction-processing/6.3-evm-execution).\
For gas fees and tip policies, see [Gas Fee Policy](/en/transaction-processing/6.4-gas-fee-policy).

## Transaction Lifecycle Overview

Transactions in StableNet go through the following **7-stage lifecycle** in sequence.

**Transaction Lifecycle Stages**

1. Transaction submission
2. Pool-level validation and acceptance
3. Mining candidate selection
4. Transaction execution (state transition)
5. Block sealing and propagation
6. Block verification and chain insertion
7. Consensus-based finality

## Stage 1: Transaction Submission

Transactions enter a StableNet node through two main paths.

### Entry Points

| Path            | Entry Point                                 | Description                                                                                                                                                                                                   |
| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **RPC API**     | `internal/ethapi/api.go` (`TransactionAPI`) | Transactions are submitted via JSON-RPC calls such as `eth_sendTransaction` or `eth_sendRawTransaction`. Internally, they pass through `SubmitTransaction` → backend `SendTx` and are forwarded to the txpool |
| **P2P Network** | `eth/handler.go` (`txFetcher`)              | Transactions broadcast by peers are received and added to the pool via `txpool.Add(tx, remote)`                                                                                                               |

On the RPC path, `TransactionArgs.setDefaults` fills in fields such as nonce, gas limit, and fee parameters.\
After wallet- or keystore-based signing (`SignTx`), a **fully signed transaction** is delivered to the txpool.

## Stage 2: Pool-Level Validation and Acceptance

The txpool does not execute submitted transactions immediately. Instead, it applies a **pool-level validation pipeline** to filter them.

Key validation checks include:

* Transaction type validity (including fork activation checks)
* Gas limit and minimum gas price requirements
* Consistency of EIP-1559 fee fields (`maxFeePerGas`, `maxPriorityFeePerGas`)
* Nonce ordering and detection of per-account nonce gaps
* Replacement rules (price bump requirements for resubmission with the same nonce)
* Per-account queue / pending slot limits
* Whether fee-delegated transaction types are allowed

Only transactions that pass validation are stored in the `pending` or `queued` sub-pools.\
Transactions that fail validation are either rejected immediately or retained in the queue until conditions are met.

## Stage 3: Mining Candidate Selection

The mining worker (`miner/worker.go`) selects transactions as block candidates at the following times:

* Upon receiving a `NewTxsEvent`
* When starting a new block-building work loop

The selection process follows this flow:

* A `txpool.PendingFilter` is constructed based on the current block’s `baseFee`, the **governance-defined gas tip** retrieved from `GovValidator`, and blob fees (EIP-4844).
* `TxPool().Pending(filter)` is called to retrieve transactions that satisfy the conditions.
* **Local transactions are prioritized**, followed by remote transactions.
* Transactions are ordered via `newTransactionsByPriceAndNonce` using the following criteria:
  * Effective gas tip and fee level
  * Per-account nonce continuity
  * Authorized account status in the Anzeon environment
* `commitTransactions` greedily selects transactions until the block gas limit is reached.

At this stage, only **pre-execution filtering** is performed; no state changes occur yet.

## Stage 4: Transaction Execution (State Transition)

Each selected transaction is executed sequentially via `core.StateTransition`.

The execution flow is as follows:

* Create `NewStateTransition(evm, msg, gasPool)`
* Call `TransitionDb()` to start the state transition
* Perform pre-execution checks in `preCheck()`:
  * Nonce correctness (TooLow / TooHigh / Max)
  * Whether the sender is an EOA (contract accounts are rejected, except for EIP-7702 delegated code)
  * Relationship between `gasFeeCap`, `gasTipCap`, and the block `baseFee`
  * Validation of blob fees (EIP-4844) and authorization formats (EIP-7702)
* Perform upfront gas deduction in `buyGas()`:
  * Deduct from the sender’s balance if no fee delegation is used
  * Deduct from the FeePayer’s balance if fee delegation is applied
* Execute contract calls or creations via the EVM
* Compute gas usage, gas refunds, execution results, and logs

EVM errors (such as revert or out-of-gas) are **recorded as transaction failures but do not invalidate the block**.\
Consensus-level errors (such as preCheck failures) cause the transaction to be excluded from the block.

## Stage 5: Block Sealing and Propagation

After all selected transactions have been executed, the worker performs the following steps:

* Finalizes the block header by computing the state root, receipt root, and log bloom
* Seals the block according to WBFT consensus rules (including BLS signature aggregation)
* Writes the sealed block to the local chain and broadcasts it to the network via\
  `eth/handler` and P2P subprotocols

At this point, the block is propagated to the network in a **proposed** state.

## Stage 6: Block Verification and Chain Insertion

Other nodes that receive the block perform the following validations:

* Header validation (parent hash, timestamp, gas limit, extra data)
* Verification of the transaction Merkle root and receipt root
* Re-execution of transactions to verify the state root
* Validation of WBFT consensus signatures

If all checks pass, the block is inserted into the chain, and the canonical chain may be updated.

## Stage 7: Finality and Confirmation

When the conditions required by WBFT consensus (signatures from at least 2/3 of validators) are met, the block is marked as **finalized**.

* Finalized blocks cannot be reverted.
* Clients and applications treat transactions in finalized blocks as **confirmed**.
* Safe and Final header concepts can be used in UIs and APIs to distinguish trust levels.

With this, a transaction completes its full lifecycle on StableNet.