Part 3: Annotated Specification


The beacon chain specification is the guts of the machine. Like the guts of a computer, all the components are showing and the wires are hanging out: everything is on display. In the course of the next sections I will be dissecting the entire core beacon chain specification line by line. My aim is not only to explain how things work, but also to give some historical context: some of the reasoning behind how we ended up where we are today.

Early versions of the specs were written with much more narrative and explanation than today's. Over time, they were coded up in Python for better precision and the benefits of being executable. However, in that process, most of the explanation and intuition was removed.1 Vitalik has created his own annotated specifications that covers many of the key insights. It's hard to compete with Vitalik, but my intention here is to go one level deeper in thoroughness and detail. And perhaps to give an independent perspective.

As and when other parts of the book get written I will add links to the specific chapters on each topic (for example on Simple Serialize, consensus, networking).

Note that the online annotated specification is available in two forms:

  • divided into chapters in Part 3 of the main book, and
  • as a standalone single page that's useful for searching.

The contents of each are identical.

Version information

This edition of Upgrading Ethereum is based on the Capella version of the beacon chain specification, and corresponds to Release v1.3.0, made on the 18th of April, 2023.

There is no single specification document that covers Capella. Rather, we have the Phase 0 specification, the Altair specification changes, the Bellatrix specification changes, and the Capella specification changes. Each builds on top of the previous version in a kind of text-based diff. In addition, these documents are not stable between upgrades. For example, the Phase 0 specs were updated as part of the Capella release. This can all be rather confusing and difficult to track.

To make the whole thing easier to follow in this chapter, I have consolidated all of the specifications to date, (mostly) omitting parts that have been superseded2. In general, I have tried to reflect the existing structure of the documents to make them easier to read side-by-side with the original specs. However, I have included the separate BLS document into the flow of this one.

See also

In addition to the spec documents referenced above, a few other current and historical documents exist.

Hsiao-Wei Wang gave a Lightning Talk on the consensus Pyspec at Devcon VI that briefly describes its structure and how it can be executed.

  1. A process called "Justinification". Iykyk ;-)
  2. You can still find old versions, as described in the Preface.

Created by Ben Edgington. Licensed under CC BY-SA 4.0. Published 2023-09-29 14:16 UTC. Commit ebfcf50.