Welcome

1
Client sends HTTP POST:
2
  {"jsonrpc":"2.0","method":"eth_getBalance","params":["0xAlice","latest"],"id":1}
3
       │
4
       ▼
5
Layer 1: Transport layer (HTTP / WebSocket / IPC)
6
  HTTP server receives request, reads JSON body
7
       │
8
       ▼
9
Layer 2: Server decoding
10
  codec.readBatch() → parse into jsonrpcMessage struct
11
  Create handler, call handleMsg()
12
       │
13
       ▼
14
Layer 3: Method dispatch
15
  handleCallMsg() → handleCall()
16
    │
17
    ├─ "eth_getBalance" split on "_" → service="eth", method="getBalance"
18
    ├─ serviceRegistry lookup → find BlockChainAPI.GetBalance callback
19
    ├─ parsePositionalArguments() → decode JSON params to Go types
20
    │     params[0] "0xAlice" → common.Address
21
    │     params[1] "latest"  → rpc.BlockNumberOrHash
22
    └─ callb.call() → invoke Go method via reflection
23
       │
24
       ▼
25
Layer 4: API struct execution
26
  BlockChainAPI.GetBalance(ctx, 0xAlice, "latest")
27
    │
28
    ├─ backend.StateAndHeaderByNumberOrHash("latest")
29
    │     → "latest" resolves to BlockNumber(-2)
30
    │     → blockchain.CurrentBlock() gets latest block header
31
    │     → state.New(header.Root) opens StateDB
32
    │
33
    └─ statedb.GetBalance(0xAlice)
34
       → reads alice's balance from state trie (Chapter 4)
35
       │
36
       ▼
37
Layer 5: Return
38
  Balance → hexutil.Big → JSON serialization
39
  {"jsonrpc":"2.0","id":1,"result":"0x1234..."}
40
  → HTTP response sent back to client

1
func (s *Server) serveSingleRequest(ctx context.Context, codec ServerCodec) {
2
    h := newHandler(ctx, codec, s.idgen, &s.services, ...)
3
    h.allowSubscribe = false   // HTTP can't push notifications
4
    defer h.close(io.EOF, nil)
5

6
    reqs, batch, err := codec.readBatch()
7
    if batch {
8
        h.handleBatch(reqs)
9
    } else {
10
        h.handleMsg(reqs[0])
11
    }
12
}

1
server.RegisterName("eth", blockChainAPI)   // eth namespace
2
server.RegisterName("eth", transactionAPI)  // same namespace, multiple structs
3
server.RegisterName("txpool", txPoolAPI)    // txpool namespace
4
server.RegisterName("debug", debugAPI)      // debug namespace

1
func suitableCallbacks(receiver reflect.Value) map[string]*callback {
2
    typ := receiver.Type()
3
    for m := 0; m < typ.NumMethod(); m++ {
4
        method := typ.Method(m)
5
        if method.PkgPath != "" {
6
            continue  // unexported method, skip
7
        }
8
        cb := newCallback(receiver, method.Func)
9
        name := formatName(method.Name)  // GetBalance → getBalance
10
        callbacks[name] = cb
11
    }
12
}

1
Methods under "eth" namespace come from multiple structs:
2
  EthereumAPI    → eth_gasPrice, eth_syncing
3
  BlockChainAPI  → eth_getBalance, eth_call, eth_blockNumber
4
  TransactionAPI → eth_sendRawTransaction, eth_getTransactionByHash

1
func (h *handler) handleCall(cp *callProc, msg *jsonrpcMessage) *jsonrpcMessage {
2
    // 1. Subscription request?
3
    if msg.isSubscribe() {
4
        return h.handleSubscribe(cp, msg)
5
    }
6

7
    // 2. Unsubscribe?
8
    if msg.isUnsubscribe() {
9
        callb = h.unsubscribeCb
10
    } else {
11
        // 3. Normal call: look up callback
12
        callb = h.reg.callback(msg.Method)
13
        //   "eth_getBalance" → split on "_"
14
        //   → service "eth", method "getBalance"
15
        //   → look up in registry
16
    }
17

18
    // 4. Parse arguments
19
    args, err := parsePositionalArguments(msg.Params, callb.argTypes)
20
    //   JSON params array → Go type list
21

22
    // 5. Invoke via reflection
23
    answer := h.runMethod(cp.ctx, msg, callb, args)
24
    //   build arg list (receiver + context + args)
25
    //   reflect.Value.Call()
26
}

1
"earliest"  → BlockNumber(-5)  → earliest available block
2
"safe"      → BlockNumber(-4)  → safe block (CL confirmed)
3
"finalized" → BlockNumber(-3)  → finalized block (CL finalized)
4
"latest"    → BlockNumber(-2)  → latest block
5
"pending"   → BlockNumber(-1)  → pending state

1
func (b *EthAPIBackend) HeaderByNumber(ctx context.Context, number rpc.BlockNumber) (*types.Header, error) {
2
    switch number {
3
    case rpc.PendingBlockNumber:   return b.eth.miner.Pending()
4
    case rpc.LatestBlockNumber:    return b.eth.blockchain.CurrentBlock()
5
    case rpc.FinalizedBlockNumber: return b.eth.blockchain.CurrentFinalBlock()
6
    case rpc.SafeBlockNumber:      return b.eth.blockchain.CurrentSafeBlock()
7
    case rpc.EarliestBlockNumber:  return b.eth.blockchain.GetHeaderByNumber(cutoff)
8
    default:                       return b.eth.blockchain.GetHeaderByNumber(uint64(number))
9
    }
10
}

1
API structs  →  Backend interface  →  Core subsystems
2
                      │
3
                      ├─ HeaderByNumber()      → blockchain
4
                      ├─ StateAndHeaderBy...() → blockchain + state
5
                      ├─ SendTx()              → txpool
6
                      ├─ GetPoolTransaction()  → txpool
7
                      ├─ GetEVM()              → vm
8
                      └─ ChainConfig()         → params

1
Check token balance   → eth_call(balanceOf(address))
2
Get DEX quote         → eth_call(getAmountsOut(amount, path))
3
Simulate transaction  → eth_call(transfer(to, amount))
4
Check contract state  → eth_call(any view function)

1
eth_call(args, blockNrOrHash, stateOverride, blockOverrides)
2
       │
3
       ▼
4
Step 1: Resolve block, open StateDB
5
  blockNrOrHash = "latest" → current chain head
6
  backend.StateAndHeaderByNumberOrHash()
7
  → state.New(header.Root)  → StateDB at that block
8
       │
9
       ▼
10
Step 2: Apply block overrides (optional)
11
  Modify EVM block context: block number, timestamp, base fee, etc.
12
  → In-memory only, nothing written to disk
13
       │
14
       ▼
15
Step 3: Apply state overrides (optional)
16
  Modify account state: balance, nonce, code, storage
17
  → In-memory only, nothing written to disk
18
       │
19
       ▼
20
Step 4: Set up gas pool and timeout
21
  Gas pool = RPCGasCap (default 50 million) or unlimited
22
  Timeout = RPCEVMTimeout (default 5 seconds)
23
       │
24
       ▼
25
Step 5: Execute
26
  TransactionArgs → core.Message
27
  Create EVM instance
28
  core.ApplyMessage()  ← same execution path as real transactions (Chapter 6)
29
  A goroutine monitors timeout, cancels EVM if exceeded
30
       │
31
       ▼
32
Step 6: Return
33
  ├─ Success → return EVM output bytes (hex encoded)
34
  ├─ REVERT → return revert reason (decoded error message)
35
  └─ Other error → return error

1
type OverrideAccount struct {
2
    Nonce            *hexutil.Uint64
3
    Code             *hexutil.Bytes              // replace contract code
4
    Balance          *hexutil.Big                // replace balance
5
    State            map[common.Hash]common.Hash // completely replace storage
6
    StateDiff        map[common.Hash]common.Hash // incremental storage diff
7
    MovePrecompileTo *common.Address             // move precompile contract
8
}

1
// "If alice had 100 ETH, would this transaction succeed?"
2
{
3
  "0xAlice": {
4
    "balance": "0x56BC75E2D63100000"
5
  }
6
}
7

8
// "If this contract's code were the new version, what would happen?"
9
{
10
  "0xContract": {
11
    "code": "0x6080604052..."
12
  }
13
}
14

15
// "If this storage slot's value changed, what would happen?"
16
{
17
  "0xContract": {
18
    "stateDiff": {
19
      "0x0000...0001": "0x0000...00FF"
20
    }
21
  }
22
}

1
type BlockOverrides struct {
2
    Number        *hexutil.Big       // custom block number
3
    Time          *hexutil.Uint64    // custom timestamp
4
    GasLimit      *hexutil.Uint64    // custom gas limit
5
    BaseFeePerGas *hexutil.Big       // custom base fee
6
    // ...
7
}

1
// Gas limit
2
if globalGasCap == 0 {
3
    gp.AddGas(math.MaxUint64)    // unlimited gas
4
} else {
5
    gp.AddGas(globalGasCap)      // default 50,000,000
6
}
7

8
// Timeout control
9
if timeout > 0 {
10
    ctx, cancel = context.WithTimeout(ctx, timeout)  // default 5 seconds
11
}
12
// A goroutine cancels EVM execution on timeout

1
                   eth_call                    eth_sendRawTransaction
2
Purpose         Read/simulate                  Submit real transaction
3
Modifies chain  No                             Yes (tx enters txpool → gets mined)
4
Requires sig    No                             Yes (tx must be signed)
5
Costs gas       No (free)                      Yes (deducts real ETH)
6
Overrides       Supported                      Not supported
7
Execution       Synchronous, returns result    Async, returns tx hash

1
1. Client constructs call data:
2
   balanceOf(address) selector = 0x70a08231
3
   Argument = alice's address (left-padded to 32 bytes)
4
   data = 0x70a08231000000000000000000000000AliceAddress...
5

6
2. Send eth_call:
7
   {to: "0xUSDC", data: "0x70a08231..."}
8

9
3. Geth executes:
10
   Open "latest" block's StateDB
11
   → Create EVM
12
   → CALL to USDC contract address
13
   → EVM executes balanceOf bytecode
14
   → SLOAD reads alice's balance storage slot
15
   → RETURN returns balance value
16

17
4. Return result:
18
   "0x0000000000000000000000000000000000000000000000000000000005F5E100"
19
   = 100,000,000 (100 USDC, since USDC has 6 decimals)