Geth(4) QA - Kehao Zheng's Website

Kehao Zheng

Click the avatar to see more info

1057 words

5 minutes

Geth(4) QA

2026-04-13

Inside Ethereum

BlockChain

/

Ethereum

/

Geth

Q1: What is stateObject and how does it relate to StateAccount?#

StateAccount is the disk format — a minimal 4-field struct representing an account on disk:

1
type StateAccount struct {
2
    Nonce    uint64
3
    Balance  *uint256.Int
4
    Root     common.Hash   // storage trie root hash
5
    CodeHash []byte
6
}

This is just a “snapshot on paper” — enough for storage, but not enough for the EVM to work with during execution.

stateObject (core/state/state_object.go) is the in-memory working copy that wraps StateAccount with everything needed at runtime:

1
type stateObject struct {
2
    db       *StateDB             // back-pointer to parent container
3
    address  common.Address       // account address
4
    addrHash common.Hash          // keccak256(address), the trie key
5

6
    origin   *types.StateAccount  // original data from disk (before any changes)
7
    data     types.StateAccount   // current data (with all modifications applied)
8

9
    trie Trie                     // this account's storage trie, lazily opened
10
    code []byte                   // contract bytecode, loaded on demand
11

12
    originStorage      Storage    // values read from disk
13
    dirtyStorage       Storage    // values modified in the current transaction
14
    pendingStorage     Storage    // modifications accumulated across transactions
15
    uncommittedStorage Storage    // changes since last commit
16

17
    dirtyCode      bool
18
    selfDestructed bool
19
    newContract    bool
20
}

Analogy: StateAccount is your bank passbook (just balance and serial number). stateObject is the teller’s working screen — it has the passbook data plus modification history, rollback capability, and caches.

Four-layer storage cache#

Storage is just map[common.Hash]common.Hash. The four maps form a layered cache:

Map	Lifetime	Purpose
`originStorage`	Block	”Clean” baseline values read from disk
`dirtyStorage`	Transaction	Values modified in the current transaction; cleared after `Finalise()`
`pendingStorage`	Block	Accumulated modifications across all transactions; written to trie
`uncommittedStorage`	Since last commit	All changes since last trie commit

The layers exist because rollback granularity differs:

REVERT within a transaction → only dirtyStorage needs to be undone; pendingStorage is unaffected
Between transactions → Finalise() merges dirtyStorage into pendingStorage, then clears dirtyStorage for a clean workspace

With a single map, a transaction rollback couldn’t distinguish “this transaction’s changes” from “previous transactions’ changes.”

origin vs data#

origin — the account data as loaded from disk. Never modified. Serves as the rollback reference.
data — the live, evolving state. Updated on every balance change, nonce increment, etc.

Q2: When is a stateObject created? Is it only created during transaction writes?#

No. A stateObject is created on any access to an account — reads included, not just writes.

The key function is getStateObject:

1
func (s *StateDB) getStateObject(addr common.Address) *stateObject {
2
    // 1. Already in memory cache? Return it.
3
    if obj := s.stateObjects[addr]; obj != nil {
4
        return obj
5
    }
6
    // 2. Destroyed in this block? Return nil.
7
    if _, ok := s.stateObjectsDestruct[addr]; ok {
8
        return nil
9
    }
10
    // 3. Load from disk, wrap as stateObject, cache it.
11
    acct, err := s.reader.Account(addr)
12
    // ...
13
    obj := newObject(s, addr, acct)
14
    s.setStateObject(obj)
15
    return obj
16
}

Both GetBalance() (read) and AddBalance() (write) call this function. So any query to an account triggers stateObject creation and caching.

Lifecycle#

Once created, a stateObject is reused for the entire block, not just one transaction:

1
Block #100 starts → StateDB created
2

3
  Tx 1: GetBalance(alice)  → load from disk, create stateObject, cache
4
  Tx 1: AddBalance(alice)  → cache hit, reuse same stateObject
5
  Tx 2: GetBalance(alice)  → cache hit, still the same stateObject
6
  Tx 2: GetBalance(bob)    → load from disk, create new stateObject
7

8
  Commit()
9

10
Block #100 ends → StateDB discarded, all stateObjects GC'd

The stateObjects map (map[Address]*stateObject) ensures each address is loaded from disk at most once per block.

Q3: What is StateDB and what does it do?#

StateDB (core/state/statedb.go) is the central hub for all state operations within a block. The EVM never touches tries or databases directly — it only talks to StateDB:

1
stateDB.GetBalance(addr)           // read balance
2
stateDB.AddBalance(addr, amount)   // add balance
3
stateDB.GetState(addr, slot)       // read storage
4
stateDB.SetState(addr, key, val)   // write storage
5
stateDB.Snapshot()                 // take snapshot
6
stateDB.RevertToSnapshot(id)       // rollback

Position in the architecture#

1
EVM executes transactions
2
    │
3
    ▼
4
 StateDB              ← all state reads/writes go through here
5
    │
6
    ├─ stateObject (alice)
7
    ├─ stateObject (bob)
8
    ├─ stateObject (contract)
9
    │
10
    ▼
11
 Trie + Reader        ← MPT from Chapter 03
12
    │
13
    ▼
14
 triedb → ethdb       ← disk storage

Key fields#

1
type StateDB struct {
2
    db         Database          // bridge to trie database and snapshot layer
3
    reader     Reader            // loads accounts/storage from disk
4
    trie       Trie              // account trie (lazily loaded)
5

6
    originalRoot common.Hash     // state root at block start
7

8
    stateObjects         map[common.Address]*stateObject  // cache of all accessed accounts
9
    stateObjectsDestruct map[common.Address]*stateObject  // accounts destroyed in this block
10
    mutations            map[common.Address]*mutation      // which accounts were modified
11

12
    journal *journal             // undo log for rollback support
13
}

stateObjects — core cache. Every account accessed during this block lives here.
journal — undo log. Records old values before each write; RevertToSnapshot() replays entries in reverse.
mutations — tracks which accounts are modified/deleted; only these are processed during Commit().
trie — account trie, opened lazily on first write, not at StateDB creation.

Lifecycle#

One StateDB per block, disposable:

1
1. New(parentRoot, db)       → bind to parent block's state root
2
2. Execute tx 1, 2, 3...     → GetBalance/SetState/AddBalance...
3
3. Finalise()                → per transaction: dirty → pending, clean up empty accounts
4
4. IntermediateRoot()        → flush to trie, compute new state root (for block header)
5
5. Commit()                  → write trie nodes + contract code + snapshot to database
6
6. Discard                   → GC reclaims; next block creates a fresh StateDB

Relationship with stateObject#

	StateDB	stateObject
Granularity	Entire world state	Single account
Count	1 per block	1 per accessed address
Role	Route requests, manage trie, coordinate commit	Cache account data, track dirty storage

StateDB is the manager; stateObject is the managed individual.

Q4: Is StateDB preserved across transactions?#

Yes across transactions, no across blocks.

Across transactions — preserved#

1
Block #100 → StateDB created (bound to block #99's state root)
2

3
  Tx 1: transfer(alice → bob, 1 ETH)
4
    GetBalance(alice)  → load from disk, create stateObject, cache
5
    AddBalance(bob)    → load from disk, create stateObject, cache
6
    Finalise()         → dirty → pending
7

8
  Tx 2: transfer(alice → charlie, 2 ETH)
9
    GetBalance(alice)  → cache hit, same stateObject from Tx 1
10
                          balance reflects Tx 1's deduction, not the stale disk value
11
    Finalise()         → dirty → pending
12

13
  Tx 3: call(bob.someMethod())
14
    GetBalance(bob)    → cache hit, balance reflects Tx 1's deposit

This is necessary for two reasons:

Correctness — transactions execute sequentially. Tx 2 must see Tx 1’s results. If each transaction reloaded from disk, Tx 1’s balance change would be lost.
Performance — a block may have hundreds of transactions touching the same hot contract (e.g., Uniswap). Cache once, reuse hundreds of times via in-memory map lookup instead of repeated disk reads.

Across blocks — discarded#

After Commit(), the entire StateDB is thrown away. Same disposable design as the Trie struct from Chapter 03 — once committed, internal state is no longer complete. A fresh StateDB must be created from the new root for the next block.

1
Block #100: StateDB created → execute txs → Commit() → discarded
2
Block #101: new StateDB created (from block #100's root) → all caches start empty

Geth(4) QA

https://kehaozheng.vercel.app/posts/chainethgeth/04_qa/

Author

Kehao Zheng

Published at

2026-04-13

License

CC BY-NC-SA 4.0

Some information may be outdated

Geth(4) Account and State

Geth(3) Merkle Patricia Trie

Welcome

Q1: What is stateObject and how does it relate to StateAccount?#

Four-layer storage cache#

origin vs data#

Q2: When is a stateObject created? Is it only created during transaction writes?#

Lifecycle#

Q3: What is StateDB and what does it do?#

Position in the architecture#

Key fields#

Lifecycle#

Relationship with stateObject#

Q4: Is StateDB preserved across transactions?#

Across transactions — preserved#

Across blocks — discarded#