Skip to content


Repository files navigation

Upgrading Ethereum

This is my book about Ethereum 2.0: Ethereum on proof of stake and beyond.

You can read it at (also available at

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/

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.



Install node, npm, and gatsby-cli. These are my versions:

> node --version
> npm --version
> gatsby --version
Gatsby CLI version: 5.12.1

gatsby-cli can be installed with,

npm install -g gatsby-cli

You'll also need a working perl installed at /usr/bin/perl so that the build can preprocess the book document. To run the LaTex linting you'll need to install libipc-run3-perl and chktex, or you can just disable that check in bin/build/prebuild.js.


Clone this repo. cd into it, then:

npm install
gatsby build --prefix-paths


After building as above, do

gatsby serve --prefix-paths

and visit http://localhost:9000/main in a web browser.

Instead of building and serving, you can run gatsby develop and point your browser at port 8000. This will not pick up real-time changes to src/ and will need to be restarted to pick up changes. It is useful, though, for checking CSS and React changes interactively.


The entire text for the book is in the src/ 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:

  • npm run clean runs gatsby clean.
    • Do this after adding new graphics or if anything weird happens.
  • npm run check runs 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.txt
    • Markdown linting on both the original source and the generated pages.
  • npm run build runs gatsby build --prefix-paths.
  • npm run serve runs gatsby serve --prefix-paths.
  • npm run links checks external links.
    • Checking links to GitHub it will fail due to rate-limiting unless you supply GitHub credentials.
  • npm run spell can be used to maintain the list of spellings.
  • npm run valid submits a page to the W3C markup validation service and lists any issues above info level.
  • npm run pdfit creates a PDF of the whole thing. See the README.
  • npm run stats shows some stats about the book. Build the PDF first to get the full set.

How to

Create a new page

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.

Make a page unlinkable

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 SVG, and text elements are replaced by paths for maximum compatibility: it seems that a lot of applications have trouble with embedded fonts.


Diagrams have been created in and exported to SVG with the following options:

  • Border width: 10 (some of the sketched elements go out of bounds)
  • Text settings: Convert labels to SVG

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.


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

Whole book PDF

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.

  • 0xd262d146e869915444d0f34ecdaabab5ab43007e on Ethereum, ZkSync, Polygon, Optimism, Arbitrum.
  • 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, and is handy for helping me to justify to my employer why I'm spending so much time on this thing.


Source repo for Upgrading Ethereum, A technical handbook on Ethereum's move to proof of stake and beyond.







No releases published

Contributors 4