Ethereum Source Code Analysis: Understanding the State Module

Introduction

In any blockchain project, storing account information is crucial. In Ethereum, this functionality is implemented by the state module.

Unlike Bitcoin's UTXO (Unspent Transaction Output) model, Ethereum adopts an account balance model. This article explores how the state module enables this model and its underlying architecture.

What Is State?

State refers to Ethereum's account model—a system tracking user balances and transaction histories.

Two Primary Blockchain Account Models

1. UTXO Model:

   • Tracks unspent transaction outputs rather than account balances.
   • Used by Bitcoin.

2. Account Balance Model:

   • Mimics traditional banking by storing direct balance values.
   • Adopted by Ethereum via the state module.

The state module functions like a state machine, updating account balances whenever transactions occur.

Core Object: StateDB

The StateDB object stores account details, including:

• Balance: Ether holdings.
• Nonce: Transaction counter (prevents replay attacks).
• CodeHash: Smart contract bytecode hash (for contract accounts).

Key methods:

func (self *StateDB) GetBalance(addr common.Address) *big.Int  
func (self *StateDB) SetNonce(addr common.Address, nonce uint64)  
func (self *StateDB) GetCode(addr common.Address) []byte  

Implementation Architecture

The state module relies on trie structures (Merkle Patricia Tries) for efficient data storage.

Key Components

1. StateDB Fields:

   • stateObjects: Caches account data (modified or unmodified).
   • stateObjectsDirty: Tracks modified accounts.
   • journal: Logs operations for rollback support.
   • trie: Interface for the account storage trie.

2. Database Interaction:

   • Uses cachingDB to cache frequently accessed trie nodes.
   • cachedTrie optimizes commits by syncing with cachingDB.

👉 Learn more about trie structures

Core Features

1. Storing Account Information

• Key: Account address (common.Address).

• Value: Account struct:

  type Account struct {
      Nonce    uint64
      Balance  *big.Int
      Root     common.Hash  // Storage trie root
      CodeHash []byte       // Contract code hash
  }

• Transactions update balances, and the trie root hash is saved in the block header for validation.

2. Preventing Replay Attacks

Each transaction includes a nonce (AccountNonce):

1. Validation:

   • The transaction’s AccountNonce must equal the sender’s Account.Nonce + 1.

2. Execution:

   • After processing, the sender’s nonce increments by 1.

This ensures old transactions can’t be reused.

3. Snapshots and Rollbacks

• Snapshot: Saves the current journal length.

  func (self *StateDB) Snapshot() int

• Rollback: Reverts changes using logged operations.

  func (self *StateDB) RevertToSnapshot(revid int)

• Mechanism:

  • Each operation logs a reversal action (e.g., balanceChange).
  • Rollbacks apply these actions in reverse order.

👉 Explore Ethereum’s rollback design

FAQ

Q1: Why does Ethereum use an account model instead of UTXO?

• A1: The account model simplifies balance tracking and aligns with smart contract requirements, where persistent storage is essential.

Q2: How does the nonce prevent replay attacks?

• A2: By requiring each transaction to use a unique sequential nonce, old transactions become invalid after execution.

Q3: Can snapshots revert committed database changes?

• A3: No. Snapshots only revert uncommitted changes in StateDB. Once saved to the trie, rollbacks are irreversible.

Conclusion

The state module is Ethereum’s backbone for account management, combining:

• Balance Tracking: Via the Account struct.
• Security: Through nonces and replay attack prevention.
• Efficiency: Using trie structures and caching.

Understanding StateDB and its trie-based design is key to grasping Ethereum’s account system.

For further reading, refer to the official Go-Ethereum repository.