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
- Transaction pool management and validation: Transaction Pool
- Transaction structure and serialization: Transaction Types and Encoding
- Transaction selection during block production: Block Production and Mining
- StateDB architecture and journaling: 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 entitiesCore 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 |
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 theStateTransition.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.