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 Altair version of the beacon chain specification, and corresponds to Release v1.1.1, made on the 4th of October 2021.

At the time of writing, there is no single specification document for Altair. Instead, there is the Phase 0 specification and an additional Altair document describing the differences (a kind of text-based diff).

For this work, I have consolidated the two specifications into one, omitting parts that were superseded by Altair. For the most part, I have tried to reflect the existing structure of the documents to make it easier to read side-by-side with the original spec. However, I have included the separate BLS and Altair fork documents into the flow of this one.

References

The main references:

• The Phase 0 beacon chain specification.
• Altair updates to the beacon chain specification.
• Vitalik's annotated specifications, covering Phase 0, Altair, The Merge, and beyond.

Other excellent, but in places outdated references:

• 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.