Part 3: Annotated Specification

Introduction

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.¹ 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 Bellatrix version of the beacon chain specification, and corresponds to Release v1.2.0, made on the 22nd of September 2022.

There is no single specification document that covers Bellatrix. Rather, we have the Phase 0 specification, an additional Altair specification, and the Bellatrix specification. Each builds on top of the previous version in a kind of text-based diff.

To make the whole thing easier to follow in this chapter, I have consolidated the three specifications, omitting most of the parts that were superseded by Altair and then Bellatrix. 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

The main references:

• The Phase 0 beacon chain specification.
• Altair updates to the beacon chain specification.
• Bellatrix updates to the beacon chain specification.

Other useful, but in places outdated references:

• Vitalik's annotated specifications, covering Phase 0, Altair, The Merge, and beyond.
• Serenity Design Rationale
• Phase 0 for Humans [v0.10.0]
• Phase 0 design notes (Justin Drake)
• My own Phase 0 annotated specification remains available for historical interest.

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.