Skip to main content

​
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.
FieldTypePurpose
gp*GasPoolBlock-level gas limit tracker
msg*MessageTransaction message being processed
gasRemaininguint64Unspent gas during execution
initialGasuint64Starting gas limit
statevm.StateDBState database interface
evm*vm.EVMEVM 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.
CheckErrorDescription
Nonce correctnessErrNonceTooLow / ErrNonceTooHighNonce must exactly match the state nonce
Nonce overflowErrNonceMaxNonce cannot be uint64 max value
Sender is EOAErrSenderNoEOASender must not have contract code
Gas fee capErrFeeCapTooLowFee cap must exceed the base fee
Tip sanityErrTipVeryHighTip cannot exceed 256 bits
Fee cap sanityErrFeeCapVeryHighFee cap cannot exceed 256 bits
Tip vs capErrTipAboveFeeCapTip cannot exceed the fee cap
Blob validityErrBlobTxCreateBlob transactions cannot create contracts
Blob fee capErrBlobFeeCapTooLowBlob 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.
ComponentCostCondition
Base transaction21,000 gasAll transactions
Contract creation+32,000 gasto == nil and Homestead+
Zero byte data4 gas/byteEach zero byte
Non-zero byte data16 gas/byte (Istanbul+)Each non-zero byte
68 gas/byte (Frontier–Byzantium)
Access list2,400 gas/addressPer address
1,900 gas/keyPer storage key
Init code size2 gas/wordContract 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

ForkRefund CapConstant
Pre-LondongasUsed / 2params.RefundQuotient
London+gasUsed / 5params.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.
FieldTypeDescription
UsedGasuint64Gas consumed excluding refunds
RefundedGasuint64Refunded gas
ErrerrorEVM execution error
ReturnData[]byteEVM 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

ErrorCode LocationMeaning
ErrNonceTooLowstate_transition.goAlready executed
ErrNonceTooHighstate_transition.goNonce gap
ErrInsufficientFundsstate_transition.goCannot afford cost
ErrIntrinsicGasstate_transition.goGas limit too low
ErrGasLimitReachedgas_pool.goBlock gas exhausted
ErrBlacklistedAccountstate_transition.goBlacklisted
ErrTxTypeNotSupportedtypes/transaction.goFork 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.