Overview

This is a work in progress. Errors certainly exist. Corrections, comments and suggestions are most welcome.

This documentation contains several tours through the go-ethereum source code. The tours are contained in the last section of this documentation. The penultimate section discusses the major types used in go-ethereum, broken into the subsections so they can be conveniently referenced from each of the tours.

This documentation is up to date with the upcoming go-ethereum v1.8.12 source files in the master branch of the official Go language implementation of Ethereum, which includes the geth command-line Ethereum client program, along with many others. Ethereum clients include an implementation of the Ethereum Virtual Machine (EVM), which are able to parse and verify the Ethereum blockchain, including smart contracts, and provides interfaces to create transactions and mine blocks.

Current Specs

A fully verifying go-ethereum (v1.8.12, AWS i3 x2 large, cache=2GB) in full sync mode requires:

• 1M blocks: 32 mins
• 2M blocks: 1h 48 mins
• 3M blocks: 6h 54 mins
• 4M blocks: 11h 23 mins
• 5M blocks: 1 day 20 hours
• 5887204: 3 days 22 hours

FYI, the Gitter channel for go-ethereum is aethereum/go-ethereum.

Code Reference Comments

I've added special comments in the displayed source code, in this format:

var x = 41
var y = 42   // <<=== #1
var z = 43

The above comment indicates that the line containing the definition of a variable called y is the first subject of discussion; the other lines merely provide context.

When a reference would benefit from showing more code, I try to provide that code in a subordinate item with a corresponding identifier; for example, if references #3a, #3b and #3c all have their own code blocks to clarify the explanations, those blocks would be provided under item 3 as 3(a), 3(b) and 3(c).

If a block of code is referenced it is demarked with start and end comments. In the following example, the first line is reference #5a, while the entire Run function is reference #5b:

manager.SubProtocols = append(manager.SubProtocols, p2p.Protocol{ // <<=== #5a
    Name: ProtocolName,
    Version: version,
    Length: ProtocolLengths[i],
    Run: func(p *p2p.Peer, rw p2p.MsgReadWriter) error { // <<=== #5b start
        peer := manager.newPeer(int(version), p, rw)
        select {
        case manager.newPeerCh &lt;- peer:
            manager.wg.Add(1)
            defer manager.wg.Done()
            return manager.handle(peer)</b>
        case &lt;-manager.quitSync:
            return p2p.DiscQuitting
        }
    }, // <<=== #5b end
    NodeInfo: func() interface{} {
    return manager.NodeInfo()
},

TODO and Suggestion

I've added some suggestions for how the source code might be improved (to locate them, search for Suggestion). If there is general agreement that these suggestions make sense (tell me in the comments!) then I'll create a pull request. Anything I don't know or am unsure about is marked with TODO.