State Transition and Gas

Purpose and Scope

This page documents the state transition process in StableNet, which defines how a transaction modifies the blockchain state.
It covers gas mechanics, transaction validation, execution flow, fee delegation, and StableNet-specific features, including the gas policy of the Anzeon network.

For details on internal EVM execution, see EVM Execution.
For gas fee policy and pricing, see Gas Fee Policy.
For transaction types and encoding, see Transaction Types and Encoding.

Overview

A state transition refers to the process of applying a single transaction to the current chain state (StateDB).
The StateTransition type in core/state_transition.go orchestrates this process, handling nonce validation, gas purchase, value transfer, EVM execution, and gas refunds.
This process is tightly integrated with the EVM to execute contract code and update account balances and storage.

Core Data Structures

Message

The Message structure represents transaction data prepared for state processing.
It is derived from a signed transaction and includes execution-time computed fields such as the effective gas price.

Message Structure (core/state_transition.go):
- To: recipient address (nil for contract creation)
- From: sender address
- Nonce: transaction nonce
- Value: wei amount to transfer
- GasLimit: maximum gas available
- GasPrice: effective gas price paid (result after baseFee and tip)
- GasFeeCap: max fee per gas (EIP-1559)
- GasTipCap: priority fee per gas (EIP-1559)
- Data: call data or init code
- AccessList: EIP-2930 access list
- SetCodeAuthorizations: EIP-7702 code delegation list
- FeePayer: optional fee payer address (StableNet fee delegation)
- BlobGasFeeCap, BlobHashes: EIP-4844 blob fields
- SkipAccountChecks: bypass validation (for eth_call)

StateTransition

The StateTransition structure manages the lifecycle of a single transaction and tracks gas consumption.

Field	Type	Purpose
gp	*GasPool	Block-level gas limit tracker
msg	*Message	Transaction message being processed
gasRemaining	uint64	Unspent gas during execution
initialGas	uint64	Starting gas limit
state	vm.StateDB	State database interface
evm	*vm.EVM	EVM instance for execution

State Transition Flow

Diagram: Complete State Transition Flow

Converting a Transaction to a Message

Before execution, a transaction is converted into a Message via TransactionToMessage().
At this stage, the effective gas price is calculated, and the governance-based gas tip policy of the Anzeon network is applied.

Gas Tip Override (Anzeon)

In the Anzeon network, a network-enforced gas tip included in the block header is applied to unauthorized accounts, while only authorized accounts may use the tip specified in the transaction itself.

if headerGasTip != nil:
    if !statedb.IsAuthorized(sender):
        gasTipCap = headerGasTip // Override with mandatory tip
    else:
        gasTipCap = tx.GasTipCap() // Use transaction's tip

For EIP-1559 transactions, the effective gas price is calculated as
min(gasTipCap + baseFee, gasFeeCap).

Pre-Execution Validation

preCheck() Method

The preCheck() method validates whether a transaction satisfies consensus rules before any state changes occur.

Check	Error	Description
Nonce correctness	ErrNonceTooLow / ErrNonceTooHigh	Nonce must exactly match the state nonce
Nonce overflow	ErrNonceMax	Nonce cannot be uint64 max value
Sender is EOA	ErrSenderNoEOA	Sender must not have contract code
Gas fee cap	ErrFeeCapTooLow	Fee cap must exceed the base fee
Tip sanity	ErrTipVeryHigh	Tip cannot exceed 256 bits
Fee cap sanity	ErrFeeCapVeryHigh	Fee cap cannot exceed 256 bits
Tip vs cap	ErrTipAboveFeeCap	Tip cannot exceed the fee cap
Blob validity	ErrBlobTxCreate	Blob transactions cannot create contracts
Blob fee cap	ErrBlobFeeCapTooLow	Blob fee cap must meet the minimum

Gas Purchase (buyGas)

After validation, buyGas() deducts gas costs upfront.
The paying account depends on whether fee delegation is used.

Diagram: Gas Purchase Flow with Fee Delegation

• Without delegation: The sender pays both gas costs and value transfer
• With delegation: The FeePayer pays for gas, while the sender pays only for value transfer

Intrinsic Gas Calculation

Intrinsic gas is the minimum gas required for a transaction to be executed.

Component	Cost	Condition
Base transaction	21,000 gas	All transactions
Contract creation	+32,000 gas	to == nil and Homestead+
Zero byte data	4 gas/byte	Each zero byte
Non-zero byte data	16 gas/byte (Istanbul+)	Each non-zero byte
	68 gas/byte (Frontier–Byzantium)
Access list	2,400 gas/address	Per address
	1,900 gas/key	Per storage key
Init code size	2 gas/word	Contract creation (Shanghai+)

If gasRemaining < intrinsicGas, the transaction is immediately rejected with ErrIntrinsicGas.

EVM Execution Integration

After intrinsic gas is deducted, the remaining gas is used for EVM execution.

Contract Calls

state.SetNonce(sender, nonce + 1)
ret, gasRemaining, err = evm.Call(
    sender,
    *msg.To,
    msg.Data,
    gasRemaining,
    value
)

For call transactions, the nonce is incremented before execution.

Blacklist Validation (Anzeon)

In the Anzeon network, a blacklist managed by GovValidator is checked before execution.

if rules.IsAnzeon:
    if state.IsBlacklisted(msg.From):
        return ErrBlacklistedAccount{msg.From}
    if msg.To != nil && state.IsBlacklisted(*msg.To):
        return ErrBlacklistedAccount{*msg.To}

When fee delegation is enabled, the FeePayer is also subject to blacklist checks.

if msg.FeePayer != nil && rules.IsAnzeon:
    if state.IsBlacklisted(*msg.FeePayer):
        return ErrBlacklistedAccount{*msg.FeePayer}

Gas Refunds and Fee Distribution

Gas Refund Calculation

Fork	Refund Cap	Constant
Pre-London	gasUsed / 2	params.RefundQuotient
London+	gasUsed / 5	params.RefundQuotientEIP3529

Refunds are returned to the account that actually paid for gas (either the FeePayer or the sender).

Fee Distribution

In StableNet’s Anzeon network, validators receive the full fee corresponding to the effective gas price.

effectivePrice := msg.GasPrice
fee := gasUsed * effectivePrice
state.AddBalance(coinbase, fee)

• msg.GasPrice is the final effective gas price computed during TransactionToMessage
• Unlike Ethereum London, there is no baseFee burn
• This design preserves the 1:1 fiat backing principle of the stablecoin

Fee Delegation Details

Balance Validation

With fee delegation, balance checks are clearly separated between sender and FeePayer.

Gas Cost Calculation

feeCheck = gasLimit * gasFeeCap
actualDebit = gasLimit * gasPrice
if Anzeon && isFeeDelegation:
    feeCheck = gasLimit * gasPrice

Transfer Log Generation

In Anzeon, explicit Transfer logs are generated for native coin movements.

func (evm *EVM) AddTransferLog(sender, recipient common.Address, amount *uint256.Int) {
    if !evm.chainConfig.AnzeonEnabled() {
        return
    }
    // Record Transfer log
}

Execution Result

ExecutionResult represents the outcome of a state transition.

Field	Type	Description
UsedGas	uint64	Gas consumed excluding refunds
RefundedGas	uint64	Refunded gas
Err	error	EVM execution error
ReturnData	[]byte	EVM return data

• Consensus errors: The transaction itself is rejected
• EVM errors: The transaction is included but recorded as failed

Integration with Block Processing

State transitions are invoked sequentially by the StateProcessor during block processing.

Diagram: Block Processing Loop

applyTransaction() coordinates EVM context creation, execution, and receipt generation.

Error Handling

Error	Code Location	Meaning
ErrNonceTooLow	state_transition.go	Already executed
ErrNonceTooHigh	state_transition.go	Nonce gap
ErrInsufficientFunds	state_transition.go	Cannot afford cost
ErrIntrinsicGas	state_transition.go	Gas limit too low
ErrGasLimitReached	gas_pool.go	Block gas exhausted
ErrBlacklistedAccount	state_transition.go	Blacklisted
ErrTxTypeNotSupported	types/transaction.go	Fork not active

These errors may cause a block to be considered invalid during block verification.

State Transition Testing

StableNet includes the t8n state transition testing tool.

evm t8n --input.alloc=alloc.json \
        --input.txs=txs.json \
        --input.env=env.json \
        --state.fork=Shanghai

This tool outputs the pre-state, post-state root, and receipts for deterministic verification of state transitions.