This is my book about Ethereum 2.0: Ethereum on proof of stake and beyond.
You can read it at eth2book.info (also available at upgrading-ethereum.info).
It is a work in progress. There's more about the roll-out plan in the preface.
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International licence.
I am not looking for contributions at this time. That may change in future, but for now I will not be accepting any PRs to src/book.md.
Feel free to raise issues for typos, inaccuracies, omissions, and suggestions, but please don't make PRs for these. I'll happily consider PRs for improvements to the CSS or JavaScript.
Kindly note that British spelling is not a typo.
As of May 2025, I have migrated the entire build from Gatsby to Astro. Please let me know if you spot any issues!
Install node and npm. These are my versions:
> node --version
v22.16.0
> npm --version
11.4.1
You'll need a working perl installed at /usr/bin/perl to run the pre-build checks.
I've implemented a heap of pre-build checks for linting and spelling issues. You can run them standalone with npm run check, and they also run as a first step in the build process, though a failure will not stop the build.
To cause Git commits to halt when trying to commit src/book.md while these checks are failing, add the following symlink:
(cd .git/hooks; ln -s ../../bin/util/git-pre-commit-hook.sh pre-commit)
The controlling script for the checks is bin/build/prebuild.js. You can enable and disable specific checks there.
If the
sudo apt install libipc-run3-perl chktex
Clone this repo. cd into it, then:
npm install
npm run build
After building as above, do
npm run serve
Astro will tell you where it is serving the content (somewhere like http://localhost:4321/capella).
Instead of building and serving, you can run npm run devel. This will live-update pages in response to changes to src/book.md and other files like CSS and Astro scripts. Note that the one-page annotated spec and the search index will not update interactively - do npm run clean for a full rebuild.
The entire text for the book is in the src/book.md file. Everything under src/md/pages is auto-generated and any changes there will be lost.
There are various npm script commands to help with building and testing. See package.json for the full list.
npm run cleandeletes the output directory (dist/) and the Astro cache.- Astro caches aggressively and will often skip things like rebulding the search index.
npm run checkruns a bunch of custom linting and checking, controlled by the bin/build/prebuild.js script.- Check all links to internal anchors, image files, and footnotes.
- Spell check. Add any exceptions to src/spellings.en.pws (or use
npm run spfix). - Markdown linting with
markdownlint. - HTML checks and LaTeX expression linting.
npm run buildrunsastro build.npm run serverunsastro preview.npm run develruns the interactive development server.npm run linkschecks external links.- Checking links to GitHub it will fail due to rate-limiting unless you supply GitHub credentials.
npm run spellruns a spell checknpm run spfixcan be used to maintain the list of spellings.npm run validsubmits a page to the W3C markup validation service and lists any issues aboveinfolevel.npm run pdfitcreates a PDF of the whole thing. See the README.npm run statsshows some stats about the book. Build the PDF first to get the full set.npm run debugbuilds with debugging output for my custom integrations.npm run minimdoes a minimal build with only a couple of pages. Seesrc/content.config.js.
A couple of environment variables can be used to shorten the build time when testing infrastructure changes:
UE_MINIMAL= npm run build # Build a minimal version with only a couple of pages
UE_NOCHECK= npm run build # Skip checks on the source markdown when building
New pages are created by appending HTML comments to headings (first three levels only):
## Heading <!-- /new/page/path -->
Take care to get the white space correct.
Do this if a page has no content yet. It will appear in the index, but not linkable.
Append a * to the path:
## Heading <!-- /unlinked/page/path* -->
All images are in SVG format and get embedded directly into the HTML pages so that they can be responsive to light and dark mode. I have spent absurd amounts of time making this work, so please enjoy.
Diagrams have been created in drawio.com desktop application, version 27.0.9. The script in bin/util/drawio2svg.sh converts a drawio file to one or more SVG files.
Source files for all diagrams are in the src/diagrams directory. The font used is the Gloria Hallelujah Google font.
Charts (graphs, barcharts) are generated using my hackedextended version of the roughViz library. Load the src/charts/charts.html file in a browser (you might need to fiddle with some browser security settings to allow it to load local files). The charts are downloaded via the link that should appear on each image. If the download link doesn't appear check the browser console for errors.
Pre-requisites:
- roughviz.min.js needs to be downloaded from my repo and put in the charts directory.
- svg-text-to-path.js needs to be downloaded, also to the charts directory.
- The Gaegu-Light.ttf file needs to be extracted from the Gaegu Google font and put in the charts/font directory.
There's an experimental pipeline for typesetting the whole text as a PDF book in bin/pdf/. See the README there for instructions.
Kind souls sometimes ask for a way to send me a cup of coffee or make a donation. My account info is below - donations are absolutely not expected or necessary, but are always very encouraging and gratefully received.
0xd262d146e869915444d0f34ecdaabab5ab43007eon Ethereum, Polygon, Optimism, Arbitrum, Base.- Also at
benjaminion.eth
Any whales or large treasuries out there, I encourage you to take a look at the Protocol Guild which supports the people developing and maintaining our incredible technology, not just writing about it.
Finally, all feedback is very welcome!