Go Ethereum: How Geth Uses Go to Power the Ethereum Network
If you want to see Go pushed hard, read the geth source. go-ethereum, commonly called geth, is the most widely used implementation of the Ethereum protocol, and it’s written entirely in Go. Peer-to-peer networking, cryptographic verification, a virtual machine, a state database and consensus, all shipped as one binary.
To be clear, this isn’t a post about using Ethereum. I don’t much care whether you ever touch blockchain code. What interests me is how geth solves hard engineering problems in Go, because the patterns it uses are ones you can steal for far more ordinary software.
The architecture at a glance
Geth is split into packages that map cleanly onto parts of the protocol. Some of the key ones:
eth/— The main Ethereum protocol handlerp2p/— Peer-to-peer networking (peer discovery, message transport)core/vm/— The Ethereum Virtual Machine (EVM)core/state/— World state management (account balances, contract storage)consensus/— Consensus engine interfaces and implementationsrpc/— JSON-RPC server for external API accessethdb/— Database abstraction layer
The layout is worth noticing on its own. Each package owns one job, and packages talk to each other through interfaces rather than reaching into internals. It’s the discipline you’d want in any large Go codebase; geth just needs it more than most.
Interfaces everywhere: the consensus engine
My favourite bit of interface design in geth is consensus.Engine. Ethereum has changed its consensus mechanism over time (from proof-of-work to proof-of-stake), so geth has to support multiple consensus algorithms behind one abstraction.
Here’s a simplified version of the interface:
// From consensus/consensus.go
type Engine interface {
// VerifyHeader checks whether a header conforms to the consensus rules.
VerifyHeader(chain ChainHeaderReader, header *types.Header) error
// VerifyHeaders is similar to VerifyHeader, but verifies a batch.
VerifyHeaders(chain ChainHeaderReader, headers []*types.Header) (chan<- struct{}, <-chan error)
// Prepare initializes the consensus fields of a block header.
Prepare(chain ChainHeaderReader, header *types.Header) error
// Finalize runs any post-transaction state modifications (e.g., block rewards).
Finalize(chain ChainHeaderReader, header *types.Header, state *state.StateDB,
body *types.Body)
// Seal generates a new sealing request for the given input block
// and pushes the result into the given channel.
Seal(chain ChainHeaderReader, block *types.Block, results chan<- *types.Block,
stop <-chan struct{}) error
}
The channel usage here rewards a closer look. VerifyHeaders takes a batch of headers and hands back a quit channel (chan<- struct{}) and an error channel (<-chan error), so the caller can cancel verification early and consume results as they arrive. If you’ve read about how to use context in Go, you’ll recognise the cancellation idea, expressed here with raw channels. Seal does something similar: rather than blocking until a block is sealed, it pushes results into a channel so sealing can run in the background while the caller gets on with other work.
The other thing I like is how small the interface is. Ethash (proof-of-work), Beacon (proof-of-stake) and Clique (proof-of-authority) each implement it, and swapping engines is trivial. This is worth copying. If a component might grow multiple implementations, define a small interface and let each implementation satisfy it. Go makes it cheap because interfaces are implicit; there’s no implements keyword, no ceremony.
P2P networking: how geth finds and talks to peers
The p2p/ package is where I’d start if I were reading this repo for the first time. Ethereum nodes have to find each other on the open internet, establish encrypted connections and exchange protocol messages, with no central server to lean on.
Peer discovery with UDP
Geth uses a Kademlia-based distributed hash table for peer discovery, implemented in p2p/discover/. Nodes fire UDP packets at each other to build a routing table of known peers.
Here’s how geth sets up a UDP listener for discovery:
// Simplified from p2p/discover/v5_udp.go
func ListenV5(conn UDPConn, ln *enode.LocalNode, cfg Config) (*UDPv5, error) {
t := &UDPv5{
conn: conn,
localNode: ln,
tab: newTable(ln.ID()),
// Buffered channels for incoming packets
callCh: make(chan *callV5, 16),
respCh: make(chan *callV5, 16),
}
go t.readLoop() // goroutine: read incoming UDP packets
go t.dispatch() // goroutine: handle routing of responses
return t, nil
}
Two goroutines are spawned immediately: one reads incoming packets, the other dispatches responses, and they talk over channels. Separating the I/O loop from the processing logic like this is one of the oldest tricks in Go network programming. It’s still one of the best.
Encrypted TCP connections with RLPx
Once a peer is discovered, the node opens a TCP connection using the RLPx protocol, which includes an ECIES handshake for encryption. The p2p/rlpx/ package handles it:
// Simplified from p2p/rlpx/rlpx.go
type Conn struct {
dialDest *ecdsa.PublicKey
conn net.Conn
// After handshake:
enc cipher.Stream
dec cipher.Stream
// ...
}
func (c *Conn) Handshake(prv *ecdsa.PrivateKey) (*ecdsa.PublicKey, error) {
var (
sec Secrets
err error
)
if c.dialDest != nil {
sec, err = initiatorEncHandshake(c.conn, prv, c.dialDest)
} else {
sec, err = receiverEncHandshake(c.conn, prv)
}
if err != nil {
return nil, err
}
// Install encryption/decryption streams
c.enc = cipher.NewCTR(sec.aes, sec.ingressIV)
c.dec = cipher.NewCTR(sec.aes, sec.egressIV)
return sec.remote, nil
}
Three details stand out to me. The struct wraps a net.Conn, which is an interface, so you can test the whole thing with anything that satisfies it, including net.Pipe() in unit tests. The encryption is entirely standard library: AES-CTR built from crypto/aes and crypto/cipher, no third-party crypto required. And the handshake tells initiator from receiver with a simple nil check on dialDest, which is a tidy way to run both sides of a protocol through the same type.
The EVM: a stack machine in Go
The Ethereum Virtual Machine (EVM) executes smart contract bytecode. It’s a stack machine: every operation pushes and pops values from a stack rather than using registers.
The core interpreter loop in core/vm/interpreter.go looks roughly like this:
// Simplified from core/vm/interpreter.go
func (in *EVMInterpreter) Run(contract *Contract, input []byte, readOnly bool) ([]byte, error) {
var (
op OpCode
mem = NewMemory()
stack = newstack()
pc = uint64(0)
)
for {
// Get the current opcode
op = contract.GetOp(pc)
// Look up the operation in the jump table
operation := in.table[op]
// Check stack requirements
if sLen := stack.len(); sLen < operation.minStack {
return nil, &ErrStackUnderflow{}
} else if sLen > operation.maxStack {
return nil, &ErrStackOverflow{}
}
// Execute the operation
res, err := operation.execute(&pc, in, callContext)
if err != nil {
return nil, err
}
pc++
}
}
The jump table (in.table) is a [256]*operation array, one entry per possible opcode byte. Each operation struct carries its execution function, stack bounds and gas cost. That avoids a massive switch statement, and supporting a new Ethereum hard fork becomes a matter of swapping jump tables.
type operation struct {
execute executionFunc
minStack int
maxStack int
gasCost gasFunc
// ...
}
type executionFunc func(pc *uint64, interpreter *EVMInterpreter,
callContext *ScopeContext) ([]byte, error)
Storing function values in a struct like this is idiomatic Go. You get polymorphism without interfaces: each opcode is just a different function assigned to the same field. It’s the same mindset behind table-driven tests in Go, applied to a virtual machine.
The RPC layer: reflection and method registration
Geth exposes a JSON-RPC API so wallets, dApps and other tools can talk to the node. The rpc/ package uses reflection to register service methods automatically.
When you register a service, the RPC server inspects the type’s methods and exposes the ones matching a specific signature:
// Register a service with the RPC server
server := rpc.NewServer()
server.RegisterName("eth", &EthAPI{})
The server uses reflect to find methods whose first argument is context.Context and whose return values are (result, error). Anything that matches becomes an endpoint, so your API handlers are plain Go methods:
type EthAPI struct {
backend Backend
}
func (api *EthAPI) BlockNumber(ctx context.Context) (hexutil.Uint64, error) {
header := api.backend.CurrentHeader()
return hexutil.Uint64(header.Number.Uint64()), nil
}
func (api *EthAPI) GetBalance(ctx context.Context, address common.Address,
blockNrOrHash rpc.BlockNumberOrHash) (*hexutil.Big, error) {
state, _, err := api.backend.StateAndHeaderByNumberOrHash(ctx, blockNrOrHash)
if err != nil {
return nil, err
}
return (*hexutil.Big)(state.GetBalance(address).ToBig()), state.Error()
}
No code generation. No protobuf files. Write a method with the right signature and it becomes an RPC endpoint. The trade-off is real, though: mistakes surface at runtime rather than compile time. Geth accepts that in exchange for a simple developer experience, which I think is a defensible call. If you’ve worked with gRPC in Go, this is the opposite philosophy, and it’s worth understanding both before you pick one.
Concurrency patterns worth stealing
Geth is dense with practical concurrency. Two patterns in particular keep showing up.
Worker pools for block downloading
When syncing the blockchain, geth downloads blocks from multiple peers in parallel. The eth/downloader/ package runs a pool of peer workers, each in its own goroutine, coordinated through channels:
// Simplified pattern from eth/downloader
type Downloader struct {
peers *peerSet
queue *queue
cancelCh chan struct{}
}
func (d *Downloader) fetchBodies(from uint64) error {
deliver := make(chan bodyPack)
// Fan-out: request bodies from multiple peers
for _, peer := range d.peers.AllPeers() {
go func(p *peerConnection) {
bodies, err := p.RequestBodies(hashes)
if err == nil {
deliver <- bodyPack{p.id, bodies}
}
}(peer)
}
// Fan-in: collect results
for {
select {
case pack := <-deliver:
d.queue.DeliverBodies(pack.peerId, pack.bodies)
case <-d.cancelCh:
return errCanceled
}
}
}
Fan-out, fan-in, and a cancellation channel. Nothing clever, which is exactly why it works: you can hold the whole design in your head.
Event feeds for pub/sub
Geth has its own event.Feed type, a thread-safe pub/sub mechanism used throughout the codebase:
// From event/feed.go
type Feed struct {
mu sync.Mutex
subs []chan interface{}
}
// Usage example
var txFeed event.Feed
// Subscriber
ch := make(chan core.NewTxsEvent)
sub := txFeed.Subscribe(ch)
defer sub.Unsubscribe()
for event := range ch {
// Handle new transactions
fmt.Println("New txs:", len(event.Txs))
}
// Publisher (elsewhere in the code)
txFeed.Send(core.NewTxsEvent{Txs: txs})
This decouples components properly. The transaction pool has no idea who cares about new transactions; it just sends to the feed and moves on.
What Go developers can learn from geth
I often tell people that once you’re comfortable with Go, the fastest way to improve is to read other people’s code, and geth is a good repo to do it with. It shows small interfaces enabling swappable implementations, channels handling async results and cancellation, table-driven dispatch replacing giant switch statements, and a conscious trade of compile-time safety for convenience in the RPC layer. It also leans hard on composition: structs embedding structs, wrapping net.Conn and io.Reader, nothing inherited from anywhere.
The go-ethereum repository is large, but each package is fairly self-contained. Pick whichever interests you most, whether that’s p2p/, core/vm/ or rpc/, set aside 30 minutes, and just read. Follow the interesting types and see what you’d steal. You’ll come away with patterns you can use in your own Go code, blockchain or not.