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.

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. Please feel free, however, to raise issues for typos, inaccuracies, omissions, and suggestions. And I'll happily consider PRs for improvements to the CSS or JavaScript. (But PRs for typos break my workflow so please raise issues instead.)

Licence

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

Installing

Pre-requisites

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

> node --version
v16.17.0
> npm --version
8.15.0
> gatsby --version
Gatsby CLI version: 4.21.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.

Building

Clone this repo. cd into it, then:

npm install
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:

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

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 ~~hacked~~extended 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.