The ETH2.0 specs looks a lot different than ETH1.x yellow paper, and imo thats totally fine. The ETH2.0 spec is essentially a mono-repo of items that are “must haves” towards building out a full blown client. Is it organized in a meaningful way? No and yes, let me explain. You have probably over 20-30 people actively contributing to it in a month, across three different “phases” & a bunch of other docs. I wouldn’t say its a straight forward task, if you made everything into a single document, then no one would be able to keep up with the upstream changes because that one MD file would change 10 times a day (ill get back to this).
Let’s discuss the content. A specification should provide an implementer with what is absolutely necessary to maintain consensus, and as Danny famously says […] the rest is an implementation detail. A blockchain consists of a dozen or so core modules; sync, databases, caching, ops, tooling (wallet gen, etc…), networking (peer discovery, peer sync, etc…), the node itself, an api server, and then debugging tools (grafana, geth attach) the list goes on. This stuff is not described by the spec, and if it was ETH2.0 would never ship.
What does the current spec offer us? It describes all necessary data structures, constants & state transition functions. This information is expressed through pseudocode examples and light descriptions, the yellow paper looks similar (ish) but with more mathematical formulas and proofs, which thankfully was not included in this.
What does the current spec miss? It doesn’t give us a good rational for WHY things are done, and it has a supplementary doc but /shrug its not great. Using only the spec, you can in-fact implement an eth2.0 node, you just probably won’t understand what you’re writing. Also, the pseudocode is almost overly specific (in some cases) to python, or it’s overly optimized code, and requires three passes to make sure you read it correctly.
What I would like to see? A spec that walks us through a story of wtf is going on, sort of a user story. Writing it out more thoroughly would mean that instead of inline code snippets we could have an appendix to reference. Explanations of why Justification and finalization looks so bloody scary, whats going on here justification_bits[1] = 0b1? The best definition is from the supplementary doc, and says:
"justification_bits – 4 bits used to track justification during the last 4 epochs to aid in finality calculations
Still don’t get it? Most don’t at first, this is where we need better definitions.
Having a story (rather just plain english i guess?), walk through the spec might make more sense, such that researchers don’t need to spend as much time explaining things it for the 10th time. This would eliminate the need for a wiki, save time for researchers, and allow for anyone to drop in and understand whats happening. Now I think we’re in a unique time where non-implementers actually care a lot to read these specs. So the traditional, slap it on a MD and ask questions later approach is blowing up a bit.
Maybe it’s time to spend a month or so, agree on a new format, freeze all specs for a week and revamp. IMO it will be useless for “someone to create a better spec” without the researchers agreeing to it, now you’re maintaining two versions.
Wrap up - The supplementary doc is a good first start, if this was in much more detail, placed at the top of the phase 0 spec I think we would be on to something.
With all that said and done, this is a research project and the implementers jumped the gun (a year ago, not so much now), and forced them (researchers) to expedite their efforts. Here we are, and we still have lots of time to fix it and perhaps set some standards moving forward.
Shoutout to all the lads who complained and nagged but never wrote anything formally. This one’s for you Dean and Jonny.
