Geth

Skill based on go-ethereum (geth), generated 2026-02-09. Official docs: https://geth.ethereum.org/docs

Go Ethereum (geth) is the Golang execution-layer client for Ethereum. It runs full/archive/light nodes, exposes JSON-RPC over HTTP/WebSocket/IPC, and ships tools like Clef (signer) and abigen (Go contract bindings).

Core References

Features

Tools

Best Practices

External Links

• geth.ethereum.org/docs
• go-ethereum GitHub
• Execution APIs (JSON-RPC)

Generation Info

• Source: sources/geth (https://github.com/ethereum/go-ethereum)
• Git SHA: 777265620d1d6fa51558aace39c86b957445e97b
• Generated: 2026-02-09
• Docs used: README.md, cmd/clef/README.md, cmd/evm/README.md, cmd/devp2p/README.md, cmd/ethkey/README.md, https://geth.ethereum.org/docs (CLI, RPC, native-bindings, dev-mode, console)
• Supplement (more x2): 2026-02-25 — Loop 1: features-evm, features-devp2p, features-console, features-dev-mode, features-simulated-backend, features-rlpdump, features-ethkey. Loop 2: core-sync-modes, features-beacon-engine, features-docker, features-kurtosis, best-practices-rpc-security.

RPC and API Security

Exposing geth over HTTP/WS creates risk. Follow these practices so agents and tools do not recommend unsafe setups.

API exposure

• Default --http.api and --ws.api are eth,net,web3. Only enable additional namespaces (admin, debug, txpool, personal, etc.) when necessary and never expose them on a public endpoint.
• admin and debug allow node control and state extraction; restrict to IPC or trusted networks only.
• Use --http.corsdomain and --ws.origins to limit browser origins when serving DApps.

Account unlocking

• Account unlocking over HTTP or WebSocket is disabled by default when --http or --ws is enabled. Do not use --allow-insecure-unlock on any reachable interface; it is deprecated and unsafe.
• For local scripts: use IPC (geth attach <ipcpath>) with unlock, or run geth with --http only on localhost and accept the risk only for dev.
• For DApps and signing: use Clef (geth --signer <clef-url>). Keys stay in Clef; geth never holds unlocked accounts when using external signer.

Transport choice

• IPC: most secure for local tools; supports all namespaces and subscriptions; not remote.
• HTTP: simple request/response; no subscriptions; restrict to needed APIs and bind to localhost or firewall.
• WebSocket: subscriptions; same API restrictions as HTTP.

Key Points

• Prefer IPC for local; Clef for remote node + local signing. Never expose admin/debug over public HTTP/WS. Do not unlock accounts over HTTP/WS in production.

<!-- Source: https://geth.ethereum.org/docs/interacting-with-geth/rpc, https://github.com/ethereum/go-ethereum (README.md) -->

Geth CLI

Geth is driven by the geth command and command-line flags. Subcommands provide console, attach, db ops, import/export, dumpconfig, etc.

Getting Help

geth --help
geth <command> --help

Important Flag Groups

• Account: --keystore, --signer (Clef URL or IPC path), --usb (hardware wallets), --password (file for non-interactive).
• API: --http / --http.addr (default localhost), --http.port (8545), --http.api (default eth,net,web3). Same pattern for --ws, --ws.port (8546), --ws.api. --ipcdisable / --ipcpath for IPC.
• Ethereum: --config (TOML), --datadir, --mainnet, --holesky, --sepolia, --networkid, --syncmode, --snapshot.
• Beacon: --beacon.api (consensus client API URL), --beacon.checkpoint, etc.
• Dev: --dev (ephemeral PoA with prefunded account, mining), --dev.gaslimit, --dev.period.
• Logging: --verbosity (0–5), --log.format (json|logfmt|terminal), --log.file, --log.rotate.
• RPC limits: --rpc.gascap, --rpc.evmtimeout, --rpc.txfeecap, --rpc.batch-request-limit.

Subcommands (examples)

• geth console — Start node + JS console.
• geth attach [endpoint] — Attach to running node (default IPC).
• geth account list / account new / account update — Keystore management.
• geth dumpconfig — Export current options as TOML.
• geth init — Initialize genesis; geth import / export — blockchain file.
• geth db, geth snapshot, geth verkle — Low-level DB/snapshot/verkle commands.

Config File

Use a TOML file instead of many flags:

geth --config /path/to/config.toml

Produce a template from current flags:

geth --http --http.api eth,net,web3 dumpconfig

Key Points

• Default HTTP API list is eth,net,web3; enable admin, debug, txpool etc. only when needed and avoid exposing them over HTTP/WS.
• --allow-insecure-unlock is deprecated and unsafe when HTTP/WS is enabled.
• Testnets use nested datadir (e.g. ~/.ethereum/holesky); attach with explicit IPC path if needed: geth attach <datadir>/holesky/geth.ipc.

<!-- Source references:

• https://geth.ethereum.org/docs/fundamentals/command-line-options
• https://github.com/ethereum/go-ethereum (README.md)

-->

Geth Overview

Go Ethereum (geth) is the Golang execution-layer client for the Ethereum protocol. It runs as a full, archive, or light node and exposes JSON-RPC over HTTP, WebSocket, and IPC.

Executables (cmd/)

Common Flows

• Full node, mainnet: geth console — snap sync (default), then JS console.
• Testnet (e.g. Holesky): geth --holesky console — same UX, different datadir (e.g. ~/.ethereum/holesky), different genesis/bootnodes.
• Config file: geth --config /path/to/config.toml. Export current flags: geth --your-flags dumpconfig.
• Programmatic access: Enable --http / --ws and call standard JSON-RPC and geth-specific APIs. IPC is on by default and exposes all namespaces.
• Private / dev: Post-merge, multi-node private nets need a consensus client. For local testing use Dev Mode or Simulated Backend; for multi-node, Kurtosis.

Key Points

• Build: make geth or make all. Requires Go 1.23+ and a C compiler.
• Binaries: https://geth.ethereum.org/downloads/
• Do not expose HTTP/WS with unlocked accounts unless you understand the risk; prefer IPC locally or Clef for signing.

<!-- Source references:

• https://github.com/ethereum/go-ethereum (README.md)
• https://geth.ethereum.org/docs/

-->

Geth JSON-RPC

Geth exposes JSON-RPC over three transports. Methods are namespaced (e.g. eth_call). Access is controlled per transport and per namespace.

Transports

• HTTP: geth --http or geth --http --http.port 3334. Whitelist APIs with --http.api eth,net,web3. CORS: --http.corsdomain (e.g. * or https://remix.ethereum.org).
• WebSocket: geth --ws --ws.port 3334 --ws.api eth,net,web3. Origins: --ws.origins.
• IPC: All namespaces by default. Disable with --ipcdisable; custom path: --ipcpath.

Namespaces

• eth, net, web3 — Default for HTTP/WS. Standard execution APIs.
• admin, debug, clique, txpool, miner (deprecated), personal (deprecated) — Must be enabled explicitly via --http.api / --ws.api. Do not expose admin/debug over public HTTP/WS.

Security

• Account unlocking is forbidden by default when HTTP or WS is enabled. Use --allow-insecure-unlock only if you fully accept the risk (not recommended).
• Prefer IPC for local tools; use Clef for remote nodes + local signing.

Choosing a Transport

• IPC: Most secure, local only, supports subscriptions.
• HTTP: Simple, one request/response; no subscriptions.
• WebSocket: Persistent connection, subscriptions (e.g. eth_subscribe), lower per-message overhead for many calls.

Engine API

Geth exposes the Engine API for consensus clients by default (JWT auth, etc.). Not for end-user RPC use.

<!-- Source references:

• https://geth.ethereum.org/docs/interacting-with-geth/rpc
• https://github.com/ethereum/go-ethereum (README.md)

-->

Sync Modes

Geth can run as a full node (default), archive node, or light node. Sync mode determines how much historical state is kept and how initial sync works.

Modes

• Snap (default) - Snap sync: downloads state in snapshots rather than replaying all blocks. Fastest way to reach the head; does not retain full history. Use for typical nodes and DApps.
• Full - Full sync: replays blocks to build state. Slower than snap; still prunes old state by default.
• Archive - Keeps full historical state. Required for historical queries (e.g. state at old block). High storage and resource usage.
• Light - Light client: retrieves data on demand; minimal storage. Experimental; check docs for current support.

Flags

--syncmode snap|full|archive|light --snapshot (enable/disable snapshot for snap sync)

Default is snap. Use archive only when you need full history; prefer snap for normal operation.

<!-- Source: https://github.com/ethereum/go-ethereum (README.md), https://geth.ethereum.org/docs/fundamentals/command-line-options -->

abigen and Go Contract Bindings

abigen generates Go bindings from a contract ABI (and optionally bytecode for deployment). Use the bindings to call contracts from Go without hand-writing RPC encoding.

Install

go install github.com/ethereum/go-ethereum/cmd/abigen@latest

Generate from ABI only (calls only)

abigen --abi build/Storage.abi --pkg main --type Storage --out Storage.go

• --abi: Path to ABI JSON (required).
• --pkg: Go package name.
• --type: Struct name for the binding (optional).
• --out: Output file (default stdout).

Generate with bytecode (deploy + calls)

Include compiled bytecode so the generator can emit Deploy<Type>:

solc --abi Storage.sol -o build && solc --bin Storage.sol -o build
abigen --abi build/Storage.abi --bin build/Storage.bin --pkg main --type Storage --out Storage.go

Using the bindings

• Backend: Use ethclient.Dial(ipcPath) or HTTP/WS URL for bind.ContractBackend.
• Deploy: Call DeployStorage(auth, backend) (from generated code); auth is a *bind.TransactOpts (e.g. from bind.NewTransactorWithChainID(keys, password, chainID)).
• Attach to existing contract: NewStorage(address, backend) returns an instance; call instance.Retrieve(callOpts) (read) or instance.Store(auth, value) (write).
• Call opts: For reads, pass nil or &bind.CallOpts{Pending: true}. For writes, use a transactor (signed tx). Go bindings expect local signing; do not delegate signing to a remote node.

Key types

• bind.CallOpts: Block/pending, gas limit for view calls.
• bind.TransactOpts: From account, signer, gas limit, value, etc.
• Generated struct embeds caller (read), transactor (write), and filterer (events).

Key Points

• ABI is the minimum input; bytecode is needed only for deployment helpers.
• Prefer Go Contract Bindings v2 for new code when available.
• For testing without a live chain, use the simulated backend (backends.SimulatedBackend) as the ContractBackend.

<!-- Source references:

• https://geth.ethereum.org/docs/developers/dapp-developer/native-bindings
• https://geth.ethereum.org/docs/tools/abigen
• https://github.com/ethereum/go-ethereum (README.md)

-->

Clef

Clef is a standalone signer that can replace geth's built-in account management. DApps send sign requests to Clef; the user approves in a UI. Keys stay in Clef (or hardware), not in geth. Use when connecting to an untrusted or remote node while signing locally.

Running Clef

• Default HTTP: http.addr:localhost, http.port:8550. Enable with --http.
• Geth uses it via geth --signer http://localhost:8550 (or IPC path).

clef -keystore /path/to/keystore -chainid 1

Security Model

• External API (HTTP/IPC): Untrusted. No credentials; only sign requests.
• Trusted channel: Process that started Clef (stdin/stdout when using --stdio-ui). Approvals and passwords go here.
• Signing and key handling are only inside the Clef binary.

External API (JSON-RPC 2.0)

Encoding: numbers and data as hex with 0x prefix.

Responses can be delayed or never come if the user denies. UI must handle timeouts.

UI API (--stdio-ui)

When started with --stdio-ui, stdin/stdout are used for the UI. Clef sends approval requests (e.g. ui_approveTx, ui_approveSignData, ui_approveListing, ui_approveNewAccount) and expects approve/deny. One JSON-RPC message per line (no newlines inside).

• ui_approveTx — Transaction to sign; includes transaction, call_info, meta.
• ui_approveSignData — Data sign request.
• ui_approveListing — List accounts.
• ui_approveNewAccount — New account creation.
• ui_onApprovedTx — Callback after tx signed (for rules/rate limits).
• ui_onSignerStartup — Version and API addresses.
• ui_onInputRequired — Password prompt.
• ui_showInfo / ui_showError — Display only; no response.

Commands and Flags

• clef init — Initialize signer storage.
• --keystore, --configdir, --chainid, --rules (auto-approve rules file), --auditlog, --stdio-ui, --http / --http.port.

Key Points

• Use --signer in geth to point to Clef; do not unlock accounts in geth when using Clef.
• For custom UIs, implement the UI API and start Clef with --stdio-ui; see repo cmd/clef/README.md and pythonsigner.py for examples.
• Rules (and optional storage) allow auto-approving certain operations; see rules.md in the Clef tree.

<!-- Source references:

• https://github.com/ethereum/go-ethereum/tree/master/cmd/clef (README.md)
• https://geth.ethereum.org/docs/tools/clef/

-->

Beacon and Engine API

After the Merge, geth (execution) must pair with a consensus client. Communication uses the Engine API (JWT-authenticated). Configure for checkpoint sync and normal operation.

Geth flags

--beacon.api <url> Consensus client Engine API URL (e.g. http://localhost:8551) --authrpc.addr, --authrpc.port Auth RPC for Engine API (default 8551) --authrpc.jwtsecret <path> Path to shared JWT secret file (hex, 32 bytes). Must match consensus client. --beacon.checkpoint <url> Optional checkpoint URL for fast sync

JWT

Engine API uses JWT in the Authorization header. Both geth and the consensus client must use the same secret. Generate with: openssl rand -hex 32 > jwt.secret. Do not expose the auth RPC publicly.

Key Points

• Auth RPC is separate from HTTP-RPC (--http). Engine API is for consensus<->execution only; not for end-user RPC. For multi-node private nets, run a consensus client and point geth at it via --beacon.api and --authrpc.jwtsecret.

<!-- Source: https://github.com/ethereum/go-ethereum (README.md), https://geth.ethereum.org/docs/ -->

JavaScript Console

Geth ships an interactive JavaScript console. Use it to call standard JSON-RPC (eth, net, web3) and geth-specific management APIs.

Starting / attaching

geth console geth --holesky console geth attach geth attach ~/.ethereum/holesky/geth.ipc geth attach http://localhost:8545

HTTP/WS only expose APIs enabled via --http.api / --ws.api; IPC exposes all namespaces by default.

Common usage

personal.listWallets(), eth.accounts, eth.getBalance(addr), eth.blockNumber, eth.getBlock('latest'), eth.sendTransaction({...}), eth.getTransactionReceipt(txhash). Unlocking over HTTP/WS is disabled by default; use IPC or Clef.

Key Points

• Bundled web3 is legacy; for production DApps use ethers/viem against the same RPC. Avoid exposing admin/debug over public HTTP/WS.

<!-- Source: https://geth.ethereum.org/docs/interacting-with-geth/javascript-console, https://github.com/ethereum/go-ethereum (README.md) -->

Dev Mode

Dev mode runs a single-node ephemeral PoA chain with a prefunded developer account and instant block production. Use for local contract testing without syncing or running a consensus client.

Enabling

geth --dev console

Chain is ephemeral; blocks produced when txs are pending (--dev.period). One prefunded account; --dev.gaslimit sets block gas limit.

With external client

geth --dev --http --http.api eth,net,web3

Connect ethers/viem to http://localhost:8545; use dev account (unlock only on localhost or use Clef).

Key Points

• Post-merge, multi-node private nets require a consensus client; dev mode is single-node only. For Go tests without a live node use Simulated Backend. For multi-node see Kurtosis.

<!-- Source: https://geth.ethereum.org/docs/developers/dapp-developer/dev-mode, https://github.com/ethereum/go-ethereum (README.md) -->

devp2p

The devp2p CLI provides low-level P2P utilities: ENR handling, node key management, DNS discovery tree maintenance, discovery v4/v5 crawl and ping, node set filtering, and eth protocol conformance tests.

ENR and node keys

devp2p enrdump <base64> devp2p key generate mynode.key devp2p key to-enode mynode.key -ip 127.0.0.1 -tcp 30303

DNS discovery

devp2p dns sign <directory> devp2p dns sync <enrtree-URL> devp2p dns to-cloudflare <directory> / devp2p dns to-route53 <directory>

Node set

devp2p nodeset info nodes.json devp2p nodeset filter nodes.json -eth-network mainnet -snap -limit 20

Filters: -limit N, -ip CIDR, -min-age duration, -eth-network mainnet|sepolia|holesky, -les-server, -snap.

Discovery v4/v5

devp2p discv4 ping|resolve|crawl | discv5 ping|resolve|listen|crawl|test

Eth protocol test suite

devp2p rlpx eth-test --chain internal/ethtest/testdata --node enode://... --engineapi http://127.0.0.1:8551 --jwtsecret (cat jwt.secret)

Node must be initialized with test chain and Engine API + JWT.

Key Points

• Node sets are JSON; use nodeset filter to restrict by network, snap, IP, age, limit. discv5 test requires two local IPs.

<!-- Source: https://github.com/ethereum/go-ethereum/tree/master/cmd/devp2p (README.md), https://geth.ethereum.org/docs/developers/geth-developer/dns-discovery-setup -->

Docker

Geth provides official Docker images for quick local or server deployment.

Quick start

docker run -d --name ethereum-node -v /Users/alice/ethereum:/root -p 8545:8545 -p 30303:30303 ethereum/client-go

Starts geth in snap-sync mode with default DB memory. Volume persists chain data. Ports: 8545 (HTTP-RPC), 30303 (P2P). Alpine tag available for slimmer image.

Exposing RPC to host/other containers

By default geth binds RPC to localhost. To allow access from other containers or the host:

docker run ... ethereum/client-go --http --http.addr 0.0.0.0

Then map -p 8545:8545 so host can reach RPC. Restrict --http.api to eth,net,web3 unless you need more (and only on trusted networks).

Key Points

• Use a volume for datadir so state persists across container restarts. Do not expose RPC with unlocked accounts or admin/debug on untrusted networks.

<!-- Source: https://github.com/ethereum/go-ethereum (README.md) -->

ethkey

ethkey is a CLI for working with Ethereum keyfiles (Web3 Secret Storage format).

Commands

ethkey generate [--privatekey path] ethkey inspect <keyfile> [--private] ethkey signmessage <keyfile> <message|file> [--msgfile] ethkey verifymessage <address> <signature> <message|file> [--msgfile] ethkey changepassword <keyfile> [--newpasswordfile path]

--passwordfile for non-interactive password. --json for JSON output.

Key Points

• Keyfiles compatible with geth keystore and Clef. Prefer Clef/geth account management for DApp signing; ethkey for keyfile ops and message signing in toolchains.

<!-- Source: https://github.com/ethereum/go-ethereum/tree/master/cmd/ethkey (README.md) -->

EVM Tool

The evm binary provides stateless state-transition and block-assembly utilities plus interactive bytecode execution.

Subcommands

• t8n - Stateless state transition: alloc + env + txs to post-state, receipts, trace.
• t9n - Transaction validation (intrinsic gas, fee semantics, tx type vs fork).
• b11r - Block builder: header + txs + ommers to sealed block RLP.
• run - Run bytecode (e.g. evm --code 60ff60ff --debug run).

t8n

evm t8n --input.alloc=alloc.json --input.env=env.json --input.txs=txs.json --state.fork=Berlin --output.result=stdout

Inputs: alloc (pre-state), env (block context), txs (JSON or RLP). Outputs: result, alloc, body. Use --state.fork (e.g. London, Shanghai) and optional --trace.*

t9n

evm t9n --state.fork London --input.txs signed_txs.rlp

b11r

evm b11r --input.header header.json --input.txs txs.rlp --seal.ethash --output.block block.json

Key Points

• t8n exit codes: 2 (EVM), 3 (invalid fork), 4 (BLOCKHASH missing), 10 (JSON), 11 (IO). Test data in cmd/evm/testdata/.

<!-- Source: https://github.com/ethereum/go-ethereum/tree/master/cmd/evm (README.md), https://geth.ethereum.org/docs/ -->

Kurtosis

Post-merge, a multi-node private network requires both execution (geth) and consensus clients. Kurtosis is the recommended way to run such a setup for testing.

Use case

When you need multiple geth nodes plus a beacon chain (e.g. private testnet, multi-node dev), use Kurtosis instead of hand-rolling configs. Single-node options remain: Dev mode (geth --dev) or Simulated Backend for Go tests.

Getting started

Follow the Kurtosis guide at https://geth.ethereum.org/docs/fundamentals/kurtosis. It provisions geth + consensus nodes, network topology, and JWT/Engine API wiring.

Key Points

• Use Kurtosis for multi-node private nets; use dev mode or simulated backend for single-node/unit testing. Kurtosis handles genesis, bootnodes, and consensus-execution pairing.

<!-- Source: https://github.com/ethereum/go-ethereum (README.md), https://geth.ethereum.org/docs/fundamentals/kurtosis -->

rlpdump

rlpdump converts binary RLP dumps into a human-readable hierarchical representation. Use to inspect raw Ethereum data or output from evm t8n --output.body.

Usage

rlpdump --hex CE0183FFFFFFC4C304050583616263

--hex for hex input. Omit for stdin raw bytes. Output is nested RLP decoding.

Key Points

• RLP is used network- and consensus-side in Ethereum. Often used with evm (e.g. evm t8n --output.body=file.rlp then rlpdump).

<!-- Source: https://github.com/ethereum/go-ethereum (README.md), https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/ -->

Simulated Backend

The go-ethereum backends.SimulatedBackend provides an in-process, in-memory blockchain for testing Go contract bindings without running geth or dev mode.

Usage

sim := backends.NewSimulatedBackend(genesisAlloc, blockGasLimit). Defer sim.Close(). Fund via genesis alloc or sim.FundAddress(addr, amount). Pass sim as bind.ContractBackend to generated contract constructors; use bind.TransactOpts for sends. sim.Commit() after txs to advance blocks. View methods with callOpts; state updated after Commit().

Example

alloc := core.GenesisAlloc{addr: {Balance: big.NewInt(1e18)}} sim := backends.NewSimulatedBackend(alloc, 30_000_000) defer sim.Close() auth := bind.NewKeyedTransactor(key) _, _, contract, _ := DeployMyContract(auth, sim, arg) sim.Commit() ret, _ := contract.GetValue(nil)

Key Points

• No network; ideal for CI. Same ContractBackend interface as ethclient.Dial(). Call Commit() after each batch for multi-tx scenarios.

<!-- Source: https://geth.ethereum.org/docs/developers/dapp-developer/native-bindings#blockchain-simulator, https://github.com/ethereum/go-ethereum (README.md) -->