The Yellow Paper is out of date and won't be maintained because of all rights reserved copyright (by default). Feel free to make PRs to my repo. Improving readability and reliability: cross-refs, hyperref, grammar, clarifications, extra references, URLs added for existing refs; list of maths symbols; fixed formatting e.g. subscripts to \mathrm font; archive links; readme: omitted yellowpaper.io and added more details on how to build.

[jamesray1]

Here is the latest version of the PDF that is based on the changes that I've made:

Paper.pdf

Feel free to make PRs to this branch in this repo. There is also https://github.com/chronaeon/modules/, however I see that as a WIP, e.g. with more formal specification in the paper needed, and still prefer my version of the yellow paper, e.g. because pseudocode isn't as concise or formal as maths (more details are in this closed issue).

I was requested to split the large PR #365 into smaller PRs, which this PR extends upon. However, this is a very time-consuming, tedious job that I don't want to do. I'd rather be working on sharding, PoS or other protocol improvements. I just decided to edit the Yellow Paper as I read it. Additionally I have made a few smaller PRs that are a subset of this one, but none of them have been merged, which doesn't give me a lot of encouragement to do further work in splitting this up.

(I created a separate issue for this paragraph plus the many open PRs.) Furthermore, the Byzantium EIPS have not even been added to the yellow paper, which means that it is technically also outdated. It would be good to get the yellow paper up-to-date, very readable and reliable. Something else that would be worth doing is to have online modules like Pydocs. Using hyperlinks in LaTeX PDF is not as efficient for reading or writing as modules on a website. Therefore I would like permission for the public to take the content of the yellow paper and develop into online docs, like on readthedocs, while incorporating Byzantium and future EIPS.

Also, it is hard to split the changes into smaller PRs, because:

1. Commits mix up different types of changes that are independent, e.g. grammar and other minor edits; clarifications and cross-references. In these cases, to keep each PR to have only related changes, the commit should probably be split up. In future, I will ensure that commits are kept small and have only related changes.
2. Many of the changes are dependent, e.g. many changes are cross-refs which are dependent on hyperref.
3. It also seems harder to work with Git and Github when there are many branches (there is one branch for each PR). Every time I make a change in Git to keep PRs short it'd be best to create the change in a separate branch with git checkout to the branch that is to be duplicated (which preferably is flush with the original master unless there are dependencies like hyperref), then git checkout -b <describe-the-change> then make the changes locally, then run git push -u after changing the default push settings. It's easier to use Github, but Github isn't good when you need to cherry-pick commits, with which you also need to use a mergetool for any conflicts.

It seems like it would be less time-consuming overall to review the big PR incrementally (it doesn't need to be all in one go) by adding comments and checkpoints. I also suggested to post a link in the readme to a comment e.g. this comment that contains a link to my latest version of the paper, with a warning that this version has not been reviewed, approved, or merged. In either case, for reviewing the PR and merging it or posting a link, whatever change would need to be approved by @gavofyork. If the link in the readme option is preferred, I can create another PR for that change. At any rate, it seems like there is a bit of a stalemate since I don't really want to cherry pick commits and modify ones that have non-related changes, but reviewers don't want to merge it as is.

I think the reason the yellow paper is a bit outdated and isn't being improved much may be because it's hard or time consuming to keep up with the pace of development. Additionally with PoS replacing PoW the formal specification will need an almost complete rewrite. I definitely think it's a good idea to have more useful docs, but I guess that reviewers may think that it is not worth spending time on making existing docs more readable! However, continuing to release docs for improvements is more important. If a document is outdated it would at least be good to have a flag to indicate that and refer to more recent developments (preferably docs).

[jamesray1]

This is the file: Paper.pdf.

Note that more cross-references could be added.

[jamesray1]

Updated: Paper.pdf

Note that I may make more commits as there are still more cross-refs to be added.

[jamesray1]

https://gitter.im/ethereum/yellowpaper?at=5a4ad08e03838b2f2a5d350f

[jamesray1]

I closed other PRs to reduce clutter.

[jamesray1]

See the ensuing discussion at https://gitter.im/ethereum/yellowpaper?at=5a4ad08e03838b2f2a5d350f to gain a better understanding of why the Yellow paper won't be maintained by the Ethereum Foundation. In short, because of using the KEVM, "the first fully executable formal semantics of the EVM", which is reasonable.

Here is the latest version of the PDF that is based on the changes that I've made:

Paper.pdf

This version of the yellow paper can be used to get links that direct to specific info in the yellow paper, which is useful e.g. for pedagogical and academic purposes. Here is an example of that:

https://github.com/ethereum/yellowpaper/files/1596574/Paper.pdf#blockhash

To get this link you just right click on a link that directs to the target that you want in the PDF (in a browser or program) and copy the link.

Feel free to make PRs to this branch in my repo.

[jamesray1]

I won't split all the commits in this PR, or I closed ones that I did split.
~~

• >94 total commits. >7 split off. List of splitted commits (details are below): 1-3, 4, 5, 6, 7, 8, 10, 11, 21.

Aug 10 2017

• 1: PR URLs for existing refs #373, editing existing URLs: rebased commits 2 (97b534c) and 3 (e71e30e), and implicitly commit 1 (ca0b74e).
• 2: as above

Sep 12

• 3: as above
• 4: PR Footnote clarifying meaning of low-order 11 bits #379: commit 4 (08172f4). Footnote clarifying meaning of low-order 11 bits.
• 5: PR Rewording accumulation of nibbles keys and branches #380: commit 5 (23c65d3). Rewording accumulation of nibbles keys and branches.
• 6: PR to proof [sic] that a correct DAG has been used #381: commit 6 (f8cf733). to proof [sic] that a correct DAG has been used.
• 7, 10, 11 & 21: [WIP] hyperref package #377: hyperref. 21 supercedes earlier commits. Commits fceced5/ 9072ca8 /no. 7, 105c407/ 4710b8e /no. 10, fff9812/ 3feff95 /no. 11 and dbb2d05/ 1e78492 /no. 21.

Sep 16

• 8 + 3 more: Adding references #382 (a few refs: Keccak, Mist, commitdateforEthash, Courtois2014, ASICSmithMJS, ECDSAcerticom and npmElectrum2017), Difficulty note and thompson ref #383 (Thompson <-> difficulty), Zbmath01748069 ref and math symbol appendix #384 (zbMath & appendix math symbols, bigvee): commit 8 (merged into the previously mentioned PRs), ac388fb: includes unreliable references, which have been replaced in a later commit [merged into the previously mentioned PRs, the second last one, 93, d48dd68]). Also related are: jamesray1@e55a5f6 (remaining content needing to be merged should be in \textit{Homestead} #385) and jamesray1@54036a3.
• 9 (Order of author names; 634ca40, Sep 16). URLs for existing refs #373: 3dde35d. URLs superceded with [WIP] hyperref package #377.
• 10: see 7. Hyperref. 4710b8e. Superceded by 21.

Sep 19

• 11: see 7. Hyperref. 3feff95. Superceded by 21.
• 12:
• 13
• 14

Sep 21

• 15.
• 16
• 17

Sep 22 (8)

• 18.
• 19
• 20
• 21: [WIP] hyperref package #377. see 7. Hyperref. 1e78492
• 22
• 23
• 24
• 25

Sep 23 (9)

• 26.
• 27
• 28
• 29
• 30
• 31
• 32
• 33
• 34

Sep 24 (4)

• 35: PR Hyperref: hyperlinks and hypertargets #378 (merged into 377). hyperlinks and hypertargets in commit 9a4d050
• 36
• 37
• 38

Sep 26 (3)

• 39:
• 40
• 41

Sep 28

• 42:

Sep 29 (4)

• 43:
• 44
• 45
• 46

Sep 30 (4)

• 47:
• 48
• 49
• 50

Oct 1 (9+5 = 14)

• 51:
• 52
• 53
• 54
• 55
• 56
• 57
• 58
• 59
• 60
• 61
• 62
• 63
• 64

Oct 2 (14)

• 65:
• 66
• 67
• 68
• 69
• 70
• 71
• 72
• 73
• 74
• 75
• 76
• 78

Oct 5 (9)

• 79:
• 80
• 81
• 82
• 83
• 84
• 85
• 86
• 87

Oct 6 (5)

• 88: Oct 6 as above for the commit 8 point 54036a3.
• 89: Oct 6 as above for the commit 8 point e55a5f6.
• 90
• 91
• 92

Oct 14

• 93

Oct 15 2017

• 94: just a merge, N/A

• PR [WIP] probably needs rebasing into smaller PRs: clarifications, hyperref and grammar #371: Merged 59bcf73, 51b0afb, b2f7605, 08172f4 and 9f03f58 and 60ea686 to local Clarifications branch, but got mixed up with other commits. All commits: numbers 4 (08172f4) to 17 (9f03f58). It's probably better to rebase into still smaller PRs.

• PR \usepackage{hyperref} #370: Merged commits 7 (9072ca8) and 11, (3feff95), and implicitly commit 10 (4710b8e), which was overwritten by 11. Done on Github, but another commit needs to be merged 1e78492

  ~~