Request: Add rationales section.

[nathan-at-least]

Hi folks,

I'm poking around here looking specifically for rationales related to issuance rates. So far it appears the repo contains only specification, is that correct? Is there a different home for higher-level design (not just spec) that contains rationale?

IMO having rationales in-repo would be incredibly helpful to ensure the spec & rationales are "patched" coherently. Would submitting a PR that starts a rationale doc be helpful?

[mratsim]

This is the goals of the annotated specs, a link can be added to them but it's easier to have different documents for different audiences.

• https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md#rewards-and-penalties=
• https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/#rewards-and-penalties

See also this guide on good (excellent!) documentation: https://documentation.divio.com/

[nathan-at-least]

For posterity, I've found Ethereum 2.0 Economic Review by Hoban & Borgers to be really helpful so far in understanding which attacks contribute to security metrics for amount of ETH staked (which ties to issuance rate).