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

## Purpose and Scope

This document provides a comprehensive overview of transaction execution in **go-stablenet**, covering the entire pipeline from RPC submission to validation, EVM execution, and finalization.\
It introduces the major components (StateProcessor, StateTransition, EVM) and their interactions, while delegating detailed explanations of specific aspects to subpages.

**Detailed Topics (See Subpages):**

* Transaction Lifecycle – End-to-end flow from RPC submission to block inclusion
* State Transitions and Gas – StateTransition process, pre-checks, gas purchase, intrinsic gas, refunds
* EVM Execution – EVM instantiation, bytecode interpretation, state mutation
* Gas Fee Policy – Governance-based gas tip application in StableNet
* Fee Delegation – Third-party gas payment mechanism

**Related Pages:**

* Transaction pool management and validation: [Transaction Pool](/en/core-architecture/3.4-transaction-pool)
* Transaction structure and serialization: [Transaction Types and Encoding](/en/core-architecture/3.5-transaction-types-and-encoding)
* Transaction selection during block production: [Block Production and Mining](/en/consensus-and-block-production/4.2-block-production-and-mining)
* StateDB architecture and journaling: [State Management](/en/core-architecture/3.3-state-management)

## Transaction Processing Overview

Transaction processing in go-stablenet follows a multi-stage pipeline that transforms messages into state changes and receipts.\
The process is orchestrated by the **StateProcessor** for block-level handling and **StateTransition** for individual transaction execution.

### High-Level Processing Flow

**Diagram: Transaction execution pipeline with code entities**

## Core Components

### StateProcessor

StateProcessor handles block-level transaction processing. It iterates over all transactions in a block, applies them sequentially, and coordinates with the consensus engine for finalization.

| Component | Type                  | Purpose                                       |
| --------- | --------------------- | --------------------------------------------- |
| `config`  | `*params.ChainConfig` | Chain configuration for fork rules            |
| `bc`      | `*BlockChain`         | Access to canonical chain state               |
| `engine`  | `consensus.Engine`    | Consensus engine for rewards and finalization |

**Key Method:** `Process(block, statedb, cfg) -> (receipts, logs, gasUsed, error)`

This method performs the following steps:

* Creates the EVM block context using header information
* Iterates over transactions and converts each to a Message
* Invokes `applyTransaction()` for each transaction
* Calls `engine.Finalize()` for consensus-specific logic

### StateTransition

The StateTransition structure encapsulates the logic for executing a single transaction against the current state.\
It manages gas accounting, pre-checks, EVM invocation, and error handling.

## Transaction Validation and Pre-Checks

Before execution, transactions undergo extensive validation in the `StateTransition.preCheck()` method.\
This ensures all consensus rules are satisfied before any state changes occur.

### Key Validation Checks

| Check              | Method                              | Purpose                        | Errors                                 |
| ------------------ | ----------------------------------- | ------------------------------ | -------------------------------------- |
| Nonce              | `state.GetNonce(msg.From)`          | Ensures transaction ordering   | `ErrNonceTooLow`, `ErrNonceTooHigh`    |
| Sender Account     | `state.GetCode(msg.From)`           | Verifies sender is an EOA      | `ErrSenderNoEOA`                       |
| Gas Pricing        | `GasFeeCap >= GasTipCap >= BaseFee` | Validates EIP-1559 constraints | `ErrFeeCapTooLow`, `ErrTipAboveFeeCap` |
| Authorization List | Validate EIP-7702                   | Verifies signatures            | `ErrAuthorizationInvalidSignature`     |
| Gas Purchase       | `buyGas()`                          | Reserves gas upfront           | `ErrInsufficientFunds`                 |

## Gas Management

Gas handling in StableNet consists of three phases: upfront purchase, intrinsic gas deduction, and post-execution refunds.

### Gas Purchase

`StateTransition.buyGas()` handles upfront gas payment, including optional fee delegation.

### Intrinsic Gas

`IntrinsicGas()` computes the minimum gas required before execution begins.

### Gas Refunds

`StateTransition.refundGas()` refunds unused gas after execution.

## EVM Execution

After validation and gas purchase, `StateTransition.TransitionDb()` invokes the EVM to execute the transaction.

### EVM Structure

| Field         | Type              | Purpose              |
| ------------- | ----------------- | -------------------- |
| `Context`     | `vm.BlockContext` | Block metadata       |
| `TxContext`   | `vm.TxContext`    | Transaction metadata |
| `StateDB`     | `vm.StateDB`      | State interface      |
| `interpreter` | `*EVMInterpreter` | Bytecode interpreter |

## StableNet-Specific Features

### Blacklist Enforcement

When Anzeon is active, blacklisted addresses are blocked before and during execution.

### Governance-Based Gas Tips

For non-authorized accounts, a governance-mandated minimum gas tip is enforced.

### Fee Delegation

A third-party account can pay gas fees, and refunds are issued to that account accordingly.

## Error Handling

Errors are categorized into pre-execution consensus errors and execution-time EVM errors.

## Performance Considerations

* Use of stack and memory pools
* Snapshot-based rollback in StateDB
* Optimized gas calculation paths

## Summary

Transaction processing in StableNet follows the flow:\
**validation → gas purchase → EVM execution → state application → refunds → receipt generation**, and incorporates governance-based gas policies, fee delegation, and extended features such as EIP-7702.