Upgrading Ethereum

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.

Licence

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International licence.

Contributing

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.

Installing

Pre-requisites

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

> node --version
v18.14.2
> npm --version
9.5.0
> gatsby --version
Gatsby CLI version: 5.10.0

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.

Building

Clone this repo. cd into it, then:

npm install
npm run patch
gatsby build

Viewing

After building as above, do

gatsby serve

and visit http://localhost:9000 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/book.md and will need to be restarted to pick up changes. It is useful, though, for checking CSS and React changes interactively.

Workflow

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:

• 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.
  • Visit http://localhost:9000/bellatrix/ to see the result.
• 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* -->

Images

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

Diagrams have been created in diagrams.net 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

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.

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.

Coffee

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.