Welcome

HTTP#

The HTTP transport handles each request independently — no persistent connection state:

1
func (s *Server) serveSingleRequest(ctx context.Context, codec ServerCodec) {
2
    if !s.run.Load() {
3
        return
4
    }
5
    h := newHandler(ctx, codec, s.idgen, &s.services, s.batchItemLimit, s.batchResponseLimit)
6
    h.allowSubscribe = false
7
    defer h.close(io.EOF, nil)
8

9
    reqs, batch, err := codec.readBatch()
10
    // ...
11
    if batch {
12
        h.handleBatch(reqs)
13
    } else {
14
        h.handleMsg(reqs[0])
15
    }
16
}

A new handler is created per HTTP request. Subscriptions are explicitly disabled (allowSubscribe = false) because HTTP has no way to push notifications back to the client. The request is read, dispatched, and the handler is closed.

Default limits protect against abuse: HTTP body size is capped at 5MB (defaultBodyLimit), and configurable batch limits control the number of items and total response size.

WebSocket#

WebSocket connections are long-lived, making them suitable for subscriptions:

1
const (
2
    wsPingInterval     = 30 * time.Second
3
    wsPongTimeout      = 30 * time.Second
4
    wsDefaultReadLimit = 32 * 1024 * 1024  // 32 MB
5
)

The server upgrades an HTTP connection to WebSocket using the Gorilla library, then calls ServeCodec() which creates a persistent handler. Because the connection stays open, the handler can push subscription notifications to the client. A ping/pong heartbeat every 30 seconds detects dead connections.

IPC#

IPC uses a Unix domain socket (or named pipe on Windows), providing the fastest transport for local access:

1
func (s *Server) ServeListener(l net.Listener) {
2
    for {
3
        conn, err := l.Accept()
4
        if err != nil {
5
            // ...
6
            return
7
        }
8
        go s.ServeCodec(NewCodec(conn), 0)
9
    }
10
}

Each accepted connection gets its own goroutine running ServeCodec. Like WebSocket, IPC supports subscriptions since the connection is persistent.

How Methods Are Registered#

When geth starts, each subsystem registers its API methods with the server:

1
func (s *Server) RegisterName(name string, receiver interface{}) error {
2
    return s.services.registerName(name, receiver)
3
}

For example, RegisterName("eth", blockChainAPI) registers all exported methods of blockChainAPI under the eth namespace. The registry uses reflection to discover methods:

1
type serviceRegistry struct {
2
    mu       sync.Mutex
3
    services map[string]service
4
}
5

6
type service struct {
7
    name          string
8
    callbacks     map[string]*callback
9
    subscriptions map[string]*callback
10
}
11

12
type callback struct {
13
    fn          reflect.Value
14
    rcvr        reflect.Value
15
    argTypes    []reflect.Type
16
    hasCtx      bool
17
    errPos      int
18
    isSubscribe bool
19
}

The registerName() function calls suitableCallbacks(), which iterates over the receiver’s exported methods and validates each one:

1
func suitableCallbacks(receiver reflect.Value) map[string]*callback {
2
    typ := receiver.Type()
3
    callbacks := make(map[string]*callback)
4
    for m := 0; m < typ.NumMethod(); m++ {
5
        method := typ.Method(m)
6
        if method.PkgPath != "" {
7
            continue // method not exported
8
        }
9
        cb := newCallback(receiver, method.Func)
10
        if cb == nil {
11
            continue // function invalid
12
        }
13
        name := formatName(method.Name)
14
        callbacks[name] = cb
15
    }
16
    return callbacks
17
}

A Go method qualifies as an RPC callback if it:

1. Is exported (uppercase first letter).
2. Optionally takes context.Context as its first argument (after the receiver).
3. Returns at most two values: an optional result and an optional error (error must be last).

The method name is transformed by formatName(), which lowercases the first character: GetBalance becomes getBalance. Combined with the namespace, this produces the JSON-RPC method name eth_getBalance.

Methods that return *rpc.Subscription are registered as subscriptions rather than regular callbacks. These handle eth_subscribe requests.

Single Request Flow#

For a non-batch request, handleMsg() starts a call proc and delegates:

1
func (h *handler) handleCallMsg(ctx *callProc, msg *jsonrpcMessage) *jsonrpcMessage {
2
    start := time.Now()
3
    switch {
4
    case msg.isNotification():
5
        h.handleCall(ctx, msg)
6
        h.log.Debug("Served "+msg.Method, "duration", time.Since(start))
7
        return nil
8

9
    case msg.isCall():
10
        resp := h.handleCall(ctx, msg)
11
        // ... log duration and errors ...
12
        return resp
13

14
    case msg.hasValidID():
15
        return msg.errorResponse(&invalidRequestError{"invalid request"})
16

17
    default:
18
        return errorMessage(&invalidRequestError{"invalid request"})
19
    }
20
}

The handleCall() function does the actual method lookup and invocation:

1
func (h *handler) handleCall(cp *callProc, msg *jsonrpcMessage) *jsonrpcMessage {
2
    if msg.isSubscribe() {
3
        return h.handleSubscribe(cp, msg)
4
    }
5
    var callb *callback
6
    if msg.isUnsubscribe() {
7
        callb = h.unsubscribeCb
8
    } else {
9
        callb = h.reg.callback(msg.Method)
10
    }
11
    if callb == nil {
12
        return msg.errorResponse(&methodNotFoundError{method: msg.Method})
13
    }
14

15
    args, err := parsePositionalArguments(msg.Params, callb.argTypes)
16
    if err != nil {
17
        return msg.errorResponse(&invalidParamsError{err.Error()})
18
    }
19
    start := time.Now()
20
    answer := h.runMethod(cp.ctx, msg, callb, args)
21
    // ... metrics ...
22
    return answer
23
}

The dispatch chain:

1. Subscription check — if the method ends with _subscribe, route to handleSubscribe().
2. Unsubscribe check — *_unsubscribe calls use the built-in unsubscribe callback.
3. Method lookup — h.reg.callback(msg.Method) splits the method string on _ (e.g., eth_getBalance → service eth, method getBalance) and looks up the corresponding callback.
4. Argument parsing — parsePositionalArguments() decodes the JSON params array into the Go types expected by the callback.
5. Invocation — callb.call() builds the full argument list (prepending the receiver and context), calls the Go method via reflection, and catches panics.

Subscriptions#

Subscription requests (e.g., eth_subscribe("newHeads")) are handled specially:

1
func (h *handler) handleSubscribe(cp *callProc, msg *jsonrpcMessage) *jsonrpcMessage {
2
    if !h.allowSubscribe {
3
        return msg.errorResponse(ErrNotificationsUnsupported)
4
    }
5
    name, err := parseSubscriptionName(msg.Params)
6
    // ...
7
    namespace := msg.namespace()
8
    callb := h.reg.subscription(namespace, name)
9
    // ...
10

11
    n := &Notifier{h: h, namespace: namespace}
12
    cp.notifiers = append(cp.notifiers, n)
13
    ctx := context.WithValue(cp.ctx, notifierKey{}, n)
14

15
    return h.runMethod(ctx, msg, callb, args)
16
}

A Notifier is injected into the context. The subscription handler retrieves it via NotifierFromContext(ctx), creates a Subscription, and starts pushing notifications:

1
type Notifier struct {
2
    h         *handler
3
    namespace string
4

5
    mu           sync.Mutex
6
    sub          *Subscription
7
    buffer       []any
8
    callReturned bool
9
    activated    bool
10
}
11

12
type Subscription struct {
13
    ID        ID
14
    namespace string
15
    err       chan error
16
}

Notifications sent before the subscription ID is delivered to the client are buffered. Once the handler sends the subscription ID response, activate() flushes the buffer and enables direct delivery.

Timeout Handling#

HTTP requests support server-side timeouts. The handleNonBatchCall() function creates a timer that cancels the context and sends an error response if the method doesn’t return in time:

1
// rpc/handler.go  (simplified)
2

3
func (h *handler) handleNonBatchCall(cp *callProc, msg *jsonrpcMessage) {
4
    var responded sync.Once
5
    cp.ctx, cancel = context.WithCancel(cp.ctx)
6
    defer cancel()
7

8
    if timeout, ok := ContextRequestTimeout(cp.ctx); ok {
9
        timer = time.AfterFunc(timeout, func() {
10
            cancel()
11
            responded.Do(func() {
12
                resp := msg.errorResponse(&internalServerError{errcodeTimeout, errMsgTimeout})
13
                h.conn.writeJSON(cp.ctx, resp, true)
14
            })
15
        })
16
    }
17

18
    answer := h.handleCallMsg(cp, msg)
19
    // ...
20
    if answer != nil {
21
        responded.Do(func() {
22
            h.conn.writeJSON(cp.ctx, answer, false)
23
        })
24
    }
25
}

The sync.Once ensures exactly one response is sent, whether it’s the normal result or the timeout error.

EthAPIBackend: The Implementation#

The EthAPIBackend struct bridges the API layer to the actual Ethereum service:

1
type EthAPIBackend struct {
2
    extRPCEnabled       bool
3
    allowUnprotectedTxs bool
4
    eth                 *Ethereum
5
    gpo                 *gasprice.Oracle
6
}

Most methods delegate directly to the underlying subsystem. For example, StateAndHeaderByNumberOrHash resolves the block identifier and opens a state database at that block’s root:

1
// eth/api_backend.go  (simplified)
2

3
func (b *EthAPIBackend) HeaderByNumber(ctx context.Context, number rpc.BlockNumber) (*types.Header, error) {
4
    if number == rpc.PendingBlockNumber {
5
        block, _, _ := b.eth.miner.Pending()
6
        return block.Header(), nil
7
    }
8
    if number == rpc.LatestBlockNumber {
9
        return b.eth.blockchain.CurrentBlock(), nil
10
    }
11
    if number == rpc.FinalizedBlockNumber {
12
        return b.eth.blockchain.CurrentFinalBlock(), nil
13
    }
14
    if number == rpc.SafeBlockNumber {
15
        return b.eth.blockchain.CurrentSafeBlock(), nil
16
    }
17
    if number == rpc.EarliestBlockNumber {
18
        return b.eth.blockchain.GetHeaderByNumber(b.HistoryPruningCutoff()), nil
19
    }
20
    return b.eth.blockchain.GetHeaderByNumber(uint64(number)), nil
21
}

This is where the BlockNumber sentinel values are resolved to actual headers from the blockchain (see Chapter 10 for the head pointers).

eth_getBalance#

The simplest read operation — look up an account’s balance at a given block:

1
func (api *BlockChainAPI) GetBalance(ctx context.Context, address common.Address,
2
    blockNrOrHash rpc.BlockNumberOrHash) (*hexutil.Big, error) {
3

4
    state, _, err := api.b.StateAndHeaderByNumberOrHash(ctx, blockNrOrHash)
5
    if state == nil || err != nil {
6
        return nil, err
7
    }
8
    b := state.GetBalance(address).ToBig()
9
    return (*hexutil.Big)(b), state.Error()
10
}

The pattern is: resolve the block → open a StateDB at that block’s state root → read from state (see Chapter 04 for StateDB.GetBalance).

eth_call#

eth_call executes a transaction against a given state without modifying the chain. It is the workhorse behind dApp read operations like token balances, DEX quotes, and contract simulations:

1
func (api *BlockChainAPI) Call(ctx context.Context, args TransactionArgs,
2
    blockNrOrHash *rpc.BlockNumberOrHash, overrides *override.StateOverride,
3
    blockOverrides *override.BlockOverrides) (hexutil.Bytes, error) {
4

5
    if blockNrOrHash == nil {
6
        latest := rpc.BlockNumberOrHashWithNumber(rpc.LatestBlockNumber)
7
        blockNrOrHash = &latest
8
    }
9
    result, err := DoCall(ctx, api.b, args, *blockNrOrHash, overrides, blockOverrides,
10
        api.b.RPCEVMTimeout(), api.b.RPCGasCap())
11
    if err != nil {
12
        return nil, err
13
    }
14
    if errors.Is(result.Err, vm.ErrExecutionReverted) {
15
        return nil, newRevertError(result.Revert())
16
    }
17
    return result.Return(), result.Err
18
}

The execution pipeline in doCall() sets up the EVM and runs the transaction:

1
// internal/ethapi/api.go  (simplified)
2

3
func doCall(ctx context.Context, b Backend, args TransactionArgs, state *state.StateDB,
4
    header *types.Header, overrides *override.StateOverride,
5
    blockOverrides *override.BlockOverrides, timeout time.Duration,
6
    globalGasCap uint64) (*core.ExecutionResult, error) {
7

8
    // 1. Create EVM block context from the target header
9
    blockCtx := core.NewEVMBlockContext(header, NewChainContext(ctx, b), nil)
10

11
    // 2. Apply block overrides (custom block number, timestamp, etc.)
12
    if blockOverrides != nil {
13
        blockOverrides.Apply(&blockCtx)
14
    }
15

16
    // 3. Apply state overrides (custom balances, code, storage)
17
    rules := b.ChainConfig().Rules(blockCtx.BlockNumber, blockCtx.Random != nil, blockCtx.Time)
18
    precompiles := vm.ActivePrecompiledContracts(rules)
19
    overrides.Apply(state, precompiles)
20

21
    // 4. Set up gas pool and timeout
22
    var cancel context.CancelFunc
23
    if timeout > 0 {
24
        ctx, cancel = context.WithTimeout(ctx, timeout)
25
    } else {
26
        ctx, cancel = context.WithCancel(ctx)
27
    }
28
    defer cancel()
29
    gp := new(core.GasPool)
30
    if globalGasCap == 0 {
31
        gp.AddGas(gomath.MaxUint64)
32
    } else {
33
        gp.AddGas(globalGasCap)
34
    }
35

36
    // 5. Execute the message
37
    return applyMessage(ctx, b, args, state, header, timeout, gp, &blockCtx, ...)
38
}

Walking through the key steps:

• Step 1 constructs the EVM block context from the target block’s header.
• Steps 2–3 are the override mechanism: callers can modify block fields (number, timestamp, base fee) and state (account balances, contract code, storage slots) before execution. This powers tools like Tenderly simulations.
• Step 4 creates a gas pool. If RPCGasCap is configured (default: 50M gas), it limits the gas available for the call. If zero, the call gets unlimited gas.
• Step 5 converts TransactionArgs to a core.Message, creates an EVM instance, and calls core.ApplyMessage() — the same execution path used for real transactions (see Chapter 06). A goroutine monitors the context and cancels the EVM if the timeout expires.

TransactionArgs#

The TransactionArgs struct represents the input to eth_call, eth_estimateGas, and eth_sendTransaction:

1
type TransactionArgs struct {
2
    From                 *common.Address
3
    To                   *common.Address
4
    Gas                  *hexutil.Uint64
5
    GasPrice             *hexutil.Big
6
    MaxFeePerGas         *hexutil.Big
7
    MaxPriorityFeePerGas *hexutil.Big
8
    Value                *hexutil.Big
9
    Nonce                *hexutil.Uint64
10

11
    Data  *hexutil.Bytes
12
    Input *hexutil.Bytes
13

14
    AccessList *types.AccessList
15
    ChainID    *hexutil.Big
16

17
    BlobFeeCap *hexutil.Big
18
    BlobHashes []common.Hash
19

20
    Blobs       []kzg4844.Blob
21
    Commitments []kzg4844.Commitment
22
    Proofs      []kzg4844.Proof
23

24
    AuthorizationList []types.SetCodeAuthorization
25
}

All fields are pointers so callers can omit any of them. The CallDefaults() method fills in sensible defaults for omitted fields (zero value, gas cap, etc.), and ToMessage() converts the args into a core.Message for EVM execution.

State and Block Overrides#

eth_call supports two override mechanisms that let callers customize the execution environment:

1
type StateOverride map[common.Address]OverrideAccount
2

3
type OverrideAccount struct {
4
    Nonce            *hexutil.Uint64
5
    Code             *hexutil.Bytes
6
    Balance          *hexutil.Big
7
    State            map[common.Hash]common.Hash // complete state replacement
8
    StateDiff        map[common.Hash]common.Hash // incremental state diff
9
    MovePrecompileTo *common.Address
10
}
11

12
type BlockOverrides struct {
13
    Number        *hexutil.Big
14
    Time          *hexutil.Uint64
15
    GasLimit      *hexutil.Uint64
16
    FeeRecipient  *common.Address
17
    PrevRandao    *common.Hash
18
    BaseFeePerGas *hexutil.Big
19
    BlobBaseFee   *hexutil.Big
20
    // ...
21
}

StateOverride lets callers replace an account’s balance, nonce, code, or storage before the call executes. BlockOverrides lets callers modify block context fields like the block number and timestamp. These are applied to the in-memory state and block context only — nothing is written to disk.

eth_sendRawTransaction#

This is how signed transactions enter geth from external clients:

1
func (api *TransactionAPI) SendRawTransaction(ctx context.Context,
2
    input hexutil.Bytes) (common.Hash, error) {
3

4
    tx := new(types.Transaction)
5
    if err := tx.UnmarshalBinary(input); err != nil {
6
        return common.Hash{}, err
7
    }
8
    // Handle blob sidecar version conversion if needed
9
    if sc := tx.BlobTxSidecar(); sc != nil {
10
        // ...convert v0 -> v1 if needed...
11
    }
12
    return SubmitTransaction(ctx, api.b, tx)
13
}

The input is a raw RLP-encoded transaction. After decoding, SubmitTransaction() performs final checks and submits to the pool:

1
// internal/ethapi/api.go  (simplified)
2

3
func SubmitTransaction(ctx context.Context, b Backend, tx *types.Transaction) (common.Hash, error) {
4
    // Check fee cap against RPCTxFeeCap
5
    if err := checkTxFee(tx.GasPrice(), tx.Gas(), b.RPCTxFeeCap()); err != nil {
6
        return common.Hash{}, err
7
    }
8
    // Reject unprotected (non-EIP-155) transactions unless explicitly allowed
9
    if !b.UnprotectedAllowed() && !tx.Protected() {
10
        return common.Hash{}, errors.New("only replay-protected transactions allowed")
11
    }
12
    // Submit to the transaction pool
13
    if err := b.SendTx(ctx, tx); err != nil {
14
        return common.Hash{}, err
15
    }
16
    return tx.Hash(), nil
17
}

SendTx() delegates to the transaction pool’s Add() method (see Chapter 08). From there, the transaction enters the pool and is broadcast to peers (see Chapter 12).

eth_getTransactionByHash#

Transaction lookup searches two places — the canonical chain and the pending pool:

1
// internal/ethapi/api.go  (simplified)
2

3
func (api *TransactionAPI) GetTransactionByHash(ctx context.Context,
4
    hash common.Hash) (*RPCTransaction, error) {
5

6
    // 1. Try the canonical chain index
7
    found, tx, blockHash, blockNumber, index := api.b.GetCanonicalTransaction(hash)
8
    if found {
9
        header, _ := api.b.HeaderByHash(ctx, blockHash)
10
        return newRPCTransaction(tx, blockHash, blockNumber, header.Time, index, header.BaseFee, ...)
11
    }
12

13
    // 2. Try the pending pool
14
    if tx := api.b.GetPoolTransaction(hash); tx != nil {
15
        return NewRPCPendingTransaction(tx, ...)
16
    }
17

18
    // 3. If the transaction indexer is still building the index, return a specific error
19
    if !api.b.TxIndexDone() {
20
        return nil, errors.New("transaction indexing is in progress")
21
    }
22
    return nil, nil  // not found
23
}

Pending pool transactions are returned with null block fields, signaling to the client that the transaction hasn’t been mined yet.

The Manager#

The Manager aggregates all wallet backends and provides a unified API:

1
type Manager struct {
2
    backends    map[reflect.Type][]Backend
3
    updaters    []event.Subscription
4
    updates     chan WalletEvent
5
    newBackends chan newBackendEvent
6
    wallets     []Wallet
7

8
    feed event.Feed
9
    quit chan chan error
10
    term chan struct{}
11
    lock sync.RWMutex
12
}

The manager subscribes to each backend’s wallet events (arrival, departure) and maintains a sorted cache of all wallets. When an API method needs to sign a transaction, it calls Manager.Find(account) to locate the wallet that contains the requested account.

Wallet events are broadcast to subscribers:

1
const (
2
    WalletArrived WalletEventType = iota  // New wallet detected
3
    WalletOpened                           // Wallet successfully opened
4
    WalletDropped                          // Wallet removed or disconnected
5
)
6

7
type WalletEvent struct {
8
    Wallet Wallet
9
    Kind   WalletEventType
10
}

The KeyStore#

The KeyStore is the most common wallet backend. It stores encrypted private keys as JSON files on disk:

1
type KeyStore struct {
2
    storage  keyStore
3
    cache    *accountCache
4
    changes  chan struct{}
5
    unlocked map[common.Address]*unlocked
6

7
    wallets     []accounts.Wallet
8
    updateFeed  event.Feed
9
    updateScope event.SubscriptionScope
10
    updating    bool
11

12
    mu       sync.RWMutex
13
    importMu sync.Mutex
14
}

Key operations:

• NewKeyStore(keydir, scryptN, scryptP) — creates a keystore backed by the given directory with specified scrypt parameters.
• NewAccount(passphrase) — generates a new ECDSA key pair, encrypts the private key with the passphrase, and writes it to disk.
• Unlock(account, passphrase) — decrypts the key and holds it in memory indefinitely.
• TimedUnlock(account, passphrase, timeout) — decrypts and holds the key for a limited duration.
• Lock(address) — removes the decrypted key from memory immediately.
• SignTx(account, tx, chainID) — signs a transaction using an unlocked key.

Key Encryption#

Private keys are stored in the Web3 Secret Storage format (version 3). The encryption uses scrypt for key derivation and AES-128-CTR for encryption:

1
const (
2
    StandardScryptN = 1 << 18  // 262144 — ~256MB memory, ~1s CPU
3
    StandardScryptP = 1
4
    LightScryptN    = 1 << 12  // 4096   — ~4MB memory, ~100ms CPU
5
    LightScryptP    = 6
6

7
    scryptR     = 8
8
    scryptDKLen = 32
9
)
10

11
func EncryptDataV3(data, auth []byte, scryptN, scryptP int) (CryptoJSON, error) {
12
    salt := make([]byte, 32)
13
    io.ReadFull(rand.Reader, salt)
14

15
    derivedKey, err := scrypt.Key(auth, salt, scryptN, scryptR, scryptP, scryptDKLen)
16
    encryptKey := derivedKey[:16]
17

18
    iv := make([]byte, aes.BlockSize)
19
    io.ReadFull(rand.Reader, iv)
20

21
    cipherText, _ := aesCTRXOR(encryptKey, data, iv)
22
    mac := crypto.Keccak256(derivedKey[16:32], cipherText)
23
    // ...
24
}

The encryption flow:

1. Key derivation — scrypt derives a 32-byte key from the passphrase and a random salt. The StandardScrypt parameters use ~256MB of memory and ~1 second of CPU time, making brute-force attacks expensive.
2. Encryption — the first 16 bytes of the derived key encrypt the private key data using AES-128-CTR with a random IV.
3. MAC — Keccak256(derivedKey[16:32] || cipherText) produces a MAC that verifies both the passphrase and the ciphertext integrity during decryption.

The encrypted key is stored as a JSON file named UTC--<timestamp>--<address> in the keystore directory.

Signing a Transaction via eth_sendTransaction#

When a client calls eth_sendTransaction (as opposed to eth_sendRawTransaction), geth signs the transaction using a managed key:

1
// internal/ethapi/api.go  (simplified)
2

3
func (api *TransactionAPI) SendTransaction(ctx context.Context,
4
    args TransactionArgs) (common.Hash, error) {
5

6
    account := accounts.Account{Address: args.from()}
7
    wallet, err := api.b.AccountManager().Find(account)
8
    if err != nil {
9
        return common.Hash{}, err
10
    }
11

12
    // Lock the nonce to prevent concurrent transactions from using the same nonce
13
    if args.Nonce == nil {
14
        api.nonceLock.LockAddr(args.from())
15
        defer api.nonceLock.UnlockAddr(args.from())
16
    }
17

18
    // Set defaults (nonce, gas, gas price) and build the transaction
19
    args.setDefaults(ctx, api.b, sidecarConfig{})
20
    tx := args.ToTransaction(types.LegacyTxType)
21

22
    // Sign with the wallet
23
    signed, err := wallet.SignTx(account, tx, api.b.ChainConfig().ChainID)
24
    if err != nil {
25
        return common.Hash{}, err
26
    }
27
    return SubmitTransaction(ctx, api.b, signed)
28
}

The AddrLocker (nonceLock) ensures that concurrent eth_sendTransaction calls from the same address don’t race on nonce assignment.