Go-Ethereum (Geth) Administrator & Architecture Guide

This guide is for node operators, infrastructure engineers, protocol developers, and architects who deploy, operate, secure, or extend Geth. It documents the system architecture, the complete configuration surface, deployment and operations procedures, security hardening, and the internal package design — written from the go-ethereum source at commit f5c62d0 (Go 1.24).

For installation and day-to-day usage, see the companion User Guide. This guide assumes familiarity with Ethereum concepts (accounts, transactions, the EVM, proof-of-stake) and focuses on how Geth is built, wired together, and run in production.

1. Executive Summary

Geth is the official Go implementation of an Ethereum execution-layer (EL) client. It is one process in a two-client node: Geth executes transactions and maintains state, while a separate consensus-layer (CL) client drives proof-of-stake fork choice. The two communicate over the authenticated Engine API.

Important

The single most consequential operational fact: a Geth process is not self-sufficient. Production deployment is always "Geth + a CL client + a shared JWT secret." Plan capacity, monitoring, and incident response around the pair, not Geth in isolation.

2. Architecture

2.1 High-level component diagram

                         ┌──────────────────────────────────────────────┐
                         │                cmd/geth (CLI)                  │
                         │  urfave/cli app · flag parsing · subcommands   │
                         └───────────────────────┬──────────────────────┘
                                                 │ builds
                                                 ▼
        ┌────────────────────────────────────────────────────────────────────────┐
        │                              node.Node                                   │
        │  Service container: lifecycle, account manager, P2P server,              │
        │  RPC stack (IPC/HTTP/WS/Auth), GraphQL, datadir/keystore resolution      │
        └───────┬───────────────────────────────┬───────────────────────┬─────────┘
                │ registers                      │ exposes               │ auth port
                ▼                                ▼                       ▼
   ┌─────────────────────────┐      ┌──────────────────────┐   ┌──────────────────┐
   │      eth.Ethereum       │      │  rpc + internal/      │   │  eth/catalyst    │
   │  (the EL service)       │      │  ethapi + graphql     │   │  Engine API impl │
   │                         │      │  JSON-RPC / GraphQL   │   │  (CL <-> EL)     │
   │  ┌───────────────────┐  │      └──────────────────────┘   └──────────────────┘
   │  │ core.BlockChain   │  │
   │  │  · state processor│  │      ┌──────────────────────┐   ┌──────────────────┐
   │  │  · core/vm (EVM)  │  │      │   eth/downloader     │   │  miner (payload  │
   │  │  · consensus      │  │◄────►│  snap / full sync    │   │  building)       │
   │  └───────────────────┘  │      └──────────────────────┘   └──────────────────┘
   │  ┌───────────────────┐  │
   │  │ core/txpool       │  │      ┌──────────────────────────────────────────┐
   │  │  legacy + blob    │  │      │  eth/protocols (eth, snap) · eth/fetcher  │
   │  └───────────────────┘  │◄────►│  wire protocols over p2p                  │
   └───────────┬─────────────┘      └──────────────────────────────────────────┘
               │ reads/writes
               ▼
   ┌──────────────────────────────────────────────────────────────────────────┐
   │  State & storage: core/state (StateDB) → trie → triedb (hashdb|pathdb)     │
   │  → ethdb (pebble|leveldb) + core/rawdb (schema) + freezer/ancient + era    │
   └──────────────────────────────────────────────────────────────────────────┘
               ▲
               │ transport
   ┌───────────┴──────────────────────────────────────────────────────────────┐
   │  p2p: discover(v4/v5) · enode/enr · rlpx · dnsdisc · nat · netutil          │
   └────────────────────────────────────────────────────────────────────────────┘

2.2 The node service container

node.Node (package node) is the lifecycle and resource container that everything else plugs into. It owns:

• Datadir and keystore resolution — resolves the data directory, keystore path, and node key; manages the instance directory lock.
• P2P server — the devp2p p2p.Server that handles discovery and peer connections.
• The account manager (accounts.Manager) — aggregates keystore, USB, and smartcard backends.
• The RPC stack — IPC, HTTP, WebSocket, and the separate authenticated (Engine API) server, plus optional GraphQL. Default hosts/ports come from node.DefaultConfig:

Services register with the node and are started/stopped in dependency order. cmd/geth's makeFullNode wires eth.Ethereum and its satellites into the node.

2.3 The eth execution service

eth.Ethereum (package eth) is the main EL service. It composes:

• core.BlockChain — the canonical chain, block insertion/validation, the state processor that runs each block through the EVM, and reorg handling.
• core/vm — the Ethereum Virtual Machine: opcode interpreter, gas accounting, and precompiled contracts.
• core/txpool — the transaction mempool, split into the legacy pool (legacypool) for normal transactions and blobpool for EIP-4844 blob transactions.
• eth/downloader — orchestrates snap and full sync.
• eth/protocols/eth and eth/protocols/snap — the wire protocols spoken to peers; eth/fetcher pulls announced blocks and transactions.
• eth/filters — log/event filtering backing eth_getLogs and subscriptions, accelerated by core/filtermaps log indexes.
• eth/gasprice — the gas-price oracle backing fee suggestions.
• eth/tracers — transaction tracing engines (native Go tracers and JavaScript tracers via goja).
• miner — block/payload construction, invoked when the CL requests a payload via the Engine API.

eth/ethconfig defines the service's configuration struct and its defaults (sync mode, cache splits, txpool sizing, GPO parameters, RPC caps, history retention).

2.4 Consensus and the Engine API

Geth supports multiple consensus engines behind the consensus.Engine interface:

eth/catalyst implements the Engine API — the engine_forkchoiceUpdated, engine_newPayload, and payload-building methods the CL calls on the authenticated port. beacon/engine defines the shared request/response types. The beacon/ tree also contains a full beacon light client (beacon/light, beacon/blsync) that powers the blsync tool.

2.5 State and storage stack

State storage is layered from high-level abstraction down to bytes on disk:

core/state.StateDB        ← accounts, balances, nonces, code, storage slots
        │
        ▼
trie (Merkle-Patricia)    ← cryptographic state commitment; trie/bintrie = experimental binary trie
        │
        ▼
triedb                    ← node store with two schemes:
        ├─ hashdb         ← legacy: nodes keyed by hash
        └─ pathdb         ← modern default: nodes keyed by path, online pruning, state history
        │
        ▼
ethdb (KV interface)      ← pebble (default) | leveldb | memorydb | remotedb
        │
        ▼
core/rawdb                ← concrete key schema; "ancient"/freezer for immutable old data
        └─ eradb / internal/era  ← Era archive format for historical blocks

• triedb/pathdb is the largest single module in the codebase and the modern default (--state.scheme path). It supports efficient pruning and bounded state history.
• triedb/hashdb is the legacy hash-keyed scheme.
• The freezer (ancient store) moves immutable old blocks out of the hot KV store into append-only flat files (--datadir.ancient), dramatically shrinking the live database.
• Era files (--datadir.era, geth import-history/export-history/download-era) provide compact, verifiable archives of historical blocks.

2.6 Networking stack (p2p)

core/forkid computes the fork identity used during the handshake so peers only connect to compatible chains.

2.7 Supporting subsystems

3. System Requirements

Caution

Mechanical disks (HDD) are not viable for any sync mode. State access during sync and block import is random-IO heavy; an HDD will cause the node to fall permanently behind the chain head. This is the most common cause of "node never syncs" support cases.

Note

Geth auto-shuts-down when free disk falls below --datadir.minfreedisk (MB). Provision generous headroom; chain data grows continuously even on a pruned node.

4. Configuration Mastery

Geth has roughly 250 command-line flags. Every flag has a matching GETH_<NAME> environment variable (via flags.AutoEnvVars), and the full effective configuration can be dumped and reloaded as TOML.

4.1 Configuration precedence and the TOML file

# Dump the effective configuration to TOML
geth dumpconfig --mainnet > geth.toml

# Run with a config file (flags still override individual values)
geth --config geth.toml --mainnet

Precedence (highest wins): explicit CLI flags → environment variables (GETH_*) → --config TOML file → built-in defaults.

Tip

For reproducible production deployments, generate a geth.toml with dumpconfig, commit it to configuration management, and pass --config. Keep only environment-specific values (datadir, JWT path, RPC exposure) as CLI flags.

4.2 Data, database, and history

4.3 Sync and cache

Tip

On a memory-rich machine, raising --cache (e.g. --cache 8192) materially speeds sync and block import. The percentage sub-flags rebalance how that budget is split; the defaults are sensible for full mode.

4.4 Networking and discovery

4.5 RPC, Engine API, and GraphQL

Warning

--http.vhosts and --http.corsdomain default to localhost/empty for a reason. Setting either to * removes a layer of protection against DNS-rebinding and cross-origin attacks. Only widen them behind a trusted reverse proxy.

4.6 Transaction pool

4.7 Block building (miner / payload)

Note

On a post-merge network the actual fee recipient for produced blocks is supplied by the CL via the Engine API's payload attributes, not by a Geth flag. The --miner.* flags configure block-building parameters; they do not enable PoW mining.

4.8 Metrics, telemetry, and gas-price oracle

4.9 Fork overrides

Caution

Fork-override flags are for testing and emergency coordination. Setting an incorrect fork timestamp will fork your node off the canonical chain. Do not use them on a production mainnet node unless following explicit, official guidance.

5. Deployment

5.1 Reference topology

            ┌────────────── host (firewalled) ──────────────┐
   :30303   │  ┌───────────┐  Engine API     ┌────────────┐ │
 ◄── P2P ──►│  │   geth    │◄── :8551 + JWT ──│ CL client  │ │
            │  │  (EL)     │                  │ (beacon)   │◄┼─► :9000 CL P2P
   :8545    │  └─────┬─────┘                  └────────────┘ │
 ◄── RPC ───┼────────┘ (localhost only)                      │
 (proxy)    │  jwt.hex (chmod 600) shared between the two     │
            └─────────────────────────────────────────────────┘

5.2 systemd unit (Geth)

# /etc/systemd/system/geth.service
[Unit]
Description=Go Ethereum (execution layer)
After=network-online.target
Wants=network-online.target

[Service]
User=geth
Group=geth
Type=simple
Restart=on-failure
RestartSec=5
TimeoutStopSec=300
ExecStart=/usr/local/bin/geth \
  --mainnet \
  --datadir /srv/geth \
  --http --http.addr 127.0.0.1 --http.api eth,net,web3 \
  --authrpc.addr localhost --authrpc.port 8551 \
  --authrpc.jwtsecret /etc/ethereum/jwt.hex \
  --metrics --metrics.addr 127.0.0.1
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now geth
journalctl -u geth -f

Important

Set TimeoutStopSec generously (≥ 300s). Geth needs time to flush state on shutdown; a short stop timeout causes systemd to SIGKILL it, leading to a slow state-recovery rewind on the next start.

5.3 JWT secret provisioning

sudo mkdir -p /etc/ethereum
openssl rand -hex 32 | tr -d "\n" | sudo tee /etc/ethereum/jwt.hex >/dev/null
sudo chown geth:geth /etc/ethereum/jwt.hex
sudo chmod 600 /etc/ethereum/jwt.hex

Point both Geth (--authrpc.jwtsecret) and the CL client at this file.

5.4 Docker / Compose

# docker-compose.yml (excerpt)
services:
  geth:
    build: .
    command:
      - --mainnet
      - --datadir=/data
      - --http
      - --http.addr=0.0.0.0
      - --http.api=eth,net,web3
      - --authrpc.addr=0.0.0.0
      - --authrpc.jwtsecret=/jwt/jwt.hex
    volumes:
      - geth-data:/data
      - ./jwt:/jwt:ro
    ports:
      - "127.0.0.1:8545:8545"
      - "30303:30303"
      - "30303:30303/udp"
volumes:
  geth-data:

Warning

Inside containers you must bind --http.addr 0.0.0.0 so the port is reachable, but publish it to 127.0.0.1 on the host (as above) — never 0.0.0.0:8545:8545 on a public host.

5.5 Deployment checklist

• [ ] Chain data on NVMe/SSD with terabyte-class headroom
• [ ] LimitNOFILE/--fdlimit raised (≥ 65536)
• [ ] JWT secret generated, chmod 600, shared with the CL client
• [ ] RPC bound to localhost (or behind a reverse proxy with auth)
• [ ] Only required namespaces in --http.api; admin/debug not public
• [ ] P2P port 30303 open (TCP and UDP); NAT configured if applicable
• [ ] Metrics endpoint scraped; alerts on sync status, peer count, head age
• [ ] Consensus client running and authenticated
• [ ] Graceful-shutdown timeout (TimeoutStopSec) ≥ 300s
• [ ] Backup of keystore and jwt.hex stored securely off-host

6. Security

6.1 Threat model and surfaces

6.2 Hardening rules

Caution

Apply all of the following on any internet-connected node:

1. Default-deny RPC exposure. Keep --http.addr/--ws.addr on localhost. If remote access is required, terminate TLS and authentication at a reverse proxy; never expose Geth's raw RPC port to the internet.
2. Minimize namespaces. Expose only eth,net,web3 over HTTP/WS. admin, debug, and txpool belong on the IPC socket.
3. Lock the vhost/CORS gates. Leave --http.vhosts/--http.corsdomain at their restrictive defaults unless a proxy requires otherwise. Avoid *.
4. Protect the JWT secret. chmod 600, owned by the service user. It is the credential that lets the CL drive your node.
5. Treat the keystore as cash. Back it up offline; the password is not stored in the file. Use --lightkdf only on test networks.
6. Run as a non-root user with a dedicated datadir and minimal filesystem permissions.

6.3 Removed legacy surface (negative knowledge)

Note

The legacy personal RPC namespace (remote account unlock/sign over RPC) has been removed from Geth and is not available. Do not design integrations around personal_unlockAccount or personal_sendTransaction. Use an external signer (--signer), hardware wallets, or offline key management (ethkey) instead. This repository also does not ship the clef signer binary or a standalone bootnode binary — discovery/bootnode duties are covered by the devp2p tool.

6.4 Malicious-input resistance

Geth includes an extensive fuzzing suite (tests/fuzzers: bls12381, bn256, rangeproof, secp256k1, txfetcher, difficulty) and documented post-mortems (docs/postmortems) and security audits (docs/audits). Consensus-critical code paths (EVM, trie, crypto, RLP) are the primary fuzz targets. Operators should track upstream security advisories and apply patch releases promptly, as a consensus bug can fork a node off the network.

7. Operations

7.1 Start, stop, status

sudo systemctl start geth
sudo systemctl stop geth          # graceful; allow up to TimeoutStopSec
sudo systemctl status geth
journalctl -u geth -f             # follow logs

Health check from a console:

geth attach --exec 'eth.syncing'        # false when synced
geth attach --exec 'net.peerCount'      # healthy peer count
geth attach --exec 'eth.blockNumber'    # head should advance ~every 12s

7.2 Logging

Verbosity is controlled by the debug flag group: --verbosity <0-5> (0=silent, 3=info default, 5=trace). --log.format, --log.file, and pprof flags are available for structured output and profiling. The internal/debug package also exposes a runtime debug RPC namespace and an embedded pprof server.

7.3 Backup and restore

Tip

Chain and state data are fully reproducible from the network, so the only irreplaceable assets are the keystore and (for coordination) the JWT secret. Prioritize those in backup policy; treat chain data as a cache that can be rebuilt by re-syncing.

7.4 Database maintenance

# Stop geth first for most of these
geth snapshot verify-state          # integrity check of state vs. snapshot
geth db check-state-content         # verify state is cryptographically correct
geth db metadata                    # inspect database metadata
geth prune-history                  # reclaim space from old bodies/receipts
geth removedb                       # nuke chain/state (keeps keystore) → re-sync

Warning

geth db delete/geth db put perform raw key mutations and can corrupt the database — the help text says so explicitly. Use them only when you understand the exact key schema in core/rawdb.

7.5 Upgrades

sudo systemctl stop geth
# build/install the new geth binary
geth version                        # confirm the new build
sudo systemctl start geth
journalctl -u geth -f               # watch for migration/recovery messages

Important

Read the release notes before upgrading across a network fork. Some releases change the state scheme, require a database migration, or carry a hard-fork activation. Upgrade the CL client and Geth in the order the release notes specify, and never skip a fork-activating release on mainnet.

7.6 Incident playbook

8. Repository Structure (Developer Reference)

The codebase is organized by subsystem. Top-level packages and their roles:

8.1 Building and testing

make geth          # build the geth binary
make all           # build all binaries
go test ./...      # run the full test suite
go test ./core/... # subsystem-scoped tests

The repository uses code generation (go:generate with gencodec, stringer, protoc-gen-go; see the tool directive in go.mod) and rlp/rlpgen for RLP codecs. Regenerate generated code rather than hand-editing it.

8.2 Contributing

Contributions follow upstream Go conventions: gofmt-clean code, focused commits, and full test coverage for consensus-critical changes. Consensus-affecting code (EVM, trie, crypto, RLP, fork rules) carries the highest review bar because a divergence forks nodes off the network. The fuzzing harnesses in tests/fuzzers should be extended alongside changes to parsing or cryptographic code paths.

9. Internals Deep Dive: Request and Block Lifecycles

9.1 Inbound block (from a peer)

1. A peer announces a block via the eth protocol; eth/fetcher requests the body.
2. core.BlockChain validates the header (consensus engine) and re-executes transactions through core/vm, mutating a core/state.StateDB.
3. The resulting state trie is committed via trie → triedb → ethdb; immutable old data eventually migrates to the freezer.
4. If the block extends the canonical chain (per CL fork choice), the head advances; otherwise a reorg is evaluated.

9.2 Engine API payload (from the CL)

1. The CL calls engine_forkchoiceUpdated with payload attributes (incl. fee recipient) on the authenticated port.
2. eth/catalyst instructs miner to build a payload: pull transactions from core/txpool, execute them, and assemble a block.
3. The CL retrieves the payload, and after consensus, calls engine_newPayload to commit it; Geth validates and imports it as in §9.1.

9.3 JSON-RPC call (eth_call)

1. The rpc server decodes the request and routes it to the eth namespace handler in internal/ethapi.
2. The handler snapshots state at the requested block, runs the call through core/vm under the --rpc.gascap and --rpc.evmtimeout limits, and returns the result without mutating state.

9.4 Sync (snap)

1. eth/downloader selects a pivot and requests account/storage ranges via eth/protocols/snap.
2. State is reconstructed into triedb; block bodies are backfilled.
3. Once the pivot is reached, the node switches to full validation and follows the head under CL fork choice.

10. Improvements and Technical Notes

Observations relevant to operators and maintainers, derived from the source structure:

1. State-scheme migration friction. Switching between path and hash schemes (or full ↔ archive) is not a live toggle and generally requires a re-sync. Operators should choose deliberately at first sync; documentation and tooling that make the migration path clearer would reduce a common operational pitfall.
2. Binary trie is in flight. trie/bintrie, the geth bintrie convert command, and the --override.ubt fork flag indicate an in-progress migration toward a binary state trie. Treat bintrie features as experimental and not for production state.
3. Two-client coordination is the dominant failure mode. The majority of "node won't sync" situations reduce to a missing/misauthenticated CL client. Surfacing Engine-API connectivity prominently in health output and logs continues to pay off.
4. Large modules. triedb/pathdb, core, core/rawdb, trie, and core/state are the largest and most consensus-critical modules; changes there warrant the deepest review and fuzzing.
5. Open upstream issues to track (from the community issue tracker at analysis time): a reported freezer error (canonical hash missing, can't freeze block) and an external-signer EIP-7702 authorization-list handling issue. Operators relying on freezer pruning or external signers with set-code (EIP-7702) transactions should monitor these.
6. Config reproducibility. The dumpconfig/--config TOML round-trip plus GETH_* env vars make Geth well-suited to declarative configuration management; standardizing on a committed geth.toml reduces drift across a fleet.

11. Quick Reference

11.1 Default ports

11.2 Default RPC modules

11.3 Essential operations

11.4 Key file locations