Vitalik's annotated eth2 spec. Not intended to be "the" annotated spec; other documents like Ben Edgington's https://benjaminion.xyz/eth2-annotated-spec/ also exist. This one is intended to focus more on design rationale.
This rule that your rewards decrease if other validators do less well was included to disincentivize harming other validators; see [my writing on discouragement attacks](https://github.com/ethereum/research/blob/master/papers/discouragement/discouragement.pdf) (and [Barnabe's summary](https://hackingresear.ch/discouragement-attacks/)) for reasoning why this is a good idea.
Currently, the documents are not labeled to which spec version they are. That makes it difficult to sync with upstream eth2.0-specs repo, especially the phase 1 specs are in development.
In the forkchoice file, ensure that we are correctly referring to blocks vs checkpoints in the right context, and better clarify the difference between the block tree and the checkpoint tree.
Link: https://github.com/ethereum/annotated-spec/blob/master/altair/beacon-chain.md#aside-what-is-the-break-even-uptime
This section says that the online optimal reward is 50/64 * p + 14/64 * p**2, and the offline reward is -42/64 * B. So, if my offline probability is q, Shouldn't my rewards equal to B * [(50/64 * p + 14/64 * p**2) * (1-q) - 42/64 * q] not B * [(50/64 * p + 14/64 * p**2) * q - 42/64 * (1-q)]? This confuses me because I thought the logic here would be "best reward * online probability + offline reward * offline probability"?
Ben's spec is very nice, but there's one more great document worth mentioning: https://notes.ethereum.org/@djrtwo/Bkn3zpwxB
Especially since Ben's work currently does not cover anything related to the transition function, and djrtwo has this covered.