Namada specs review

[cwgoes]

I made some minor changes in #275, but wanted to propose the major ones here for discussion before making them (and this will require some coordination).

General notes:

• This document should be scoped to protocol behavior only. All interfaces (including ours) are out-of-scope and do not even need to be mentioned.
• Should I write British English or American English? I don't care, but we should pick one - it's inconsistent.
• Do we want to include all storage keys, or not? I lean towards "yes" - but then we'll want to ensure that we actually cover everything (we definitely don't yet), and standardize the format to cleanly separate prose from storage key specs and code snippets.

Organization:

• We're striking an awkward balance between organizing on the basis of "features" and organizing on the basis of accounts/VPs - I think we should just do the latter directly. This would result in the following structure:

  • Base ledger
    • Consensus
    • Execution model
    • Block space allocator
    • Replay protection
  • Modules
    • Multitoken
    • Multisignature
    • Proof-of-stake
    • MASP
    • IBC
    • Governance
    • Ethereum bridge

  This would also match up nicely with the ongoing refactors in Restructure codebase for a module-based separation of concerns namada#2111 - the modules should align 1-1, which will make it easier to review the specs & code side-by-side.

• The specs mix content which specifies what the protocol does, content which explains why the protocol does it, and content which explains what the protocol could have done otherwise or could do in the future. These kinds of content should be distinguished, and the focus should be on the first only (so that a reader interested in only understanding what the protocol does can read only that easily). Could we put the others under some kind of optionally visible sections (inline) with a different color / visual cue for clarity?

• We need some standard templates for pages, the organization of content within pages is all over the place. For example, for each module page, we could have something like:

  • Introduction
  • Design
  • Type definitions
  • VP pseudocode
  • Storage keys
  • Transaction actions

Notation:

• The specs mix mathematical (LaTeX) notation, Rust types / code snippets, and pseudocode / bulleted procedural explanations. Since we can't typecheck it anyways, I recommend that we stick to mathematical notation, remove the Rust types / code snippets in lieu of it, and come up with at least a standard visual representation format for pseudocode procedures.

[bengtlofgren]

This document should be scoped to protocol behavior only. All interfaces (including ours) are out-of-scope and do not even need to be mentioned.

Agree.

Should I write British English or American English? I don't care, but we should pick one - it's inconsistent.

I guess most people use the American English so I can switch over to it :(

Do we want to include all storage keys, or not? I lean towards "yes" - but then we'll want to ensure that we actually cover everything (we definitely don't yet), and standardize the format to cleanly separate prose from storage key specs and code snippets.

I'm split here. On the pro side, by the definition of the specs, I believe it is essential for the storage keys to be explicit and mentioned else it is not possible to re-implement the protocol in another language. On the con side, there are A LOT of storage keys. Listing every single one may bloat the specs. My first consideration would be to include them but in an extra subsection for each section.

We're striking an awkward balance ...

I agree with above structure

The specs mix content which specifies... Could we put the others under some kind of optionally visible sections (inline) with a different color / visual cue for clarity?

I like this suggestion

We need some standard templates for pages, the organization of content within pages is all over the place. For example, for each module page, we could have something like ...

I agree with structure, I don't know if the proposed structure is the best but maybe we can start with this and edit the meta spec as we go along

[bengtlofgren]

• Restructure reorg seaorg #280
• Proper English -> American English Bengt/cuppa tea #279
• Protocol behaviour only
• Optionally visible sections
• Template for pages

[cwgoes]

Further notes:

• We may want to add a section for common abstractions, such as PD-controllers (used both by proof-of-stake and by the MASP). This will correspond to the shared types in the codebase.
• Revised recommended module structure:
  • Introduction (this can be on the module top-level page)
  • Design rationale (page)
  • Data types (page, potentially sub-pages)
  • Storage layout
  • Validity predicate logic (page, potentially sub-pages for large VPs)
  • Transactions (summary page, a sub-page for each transaction)
  • Handlers (e.g. finalize block, end-of-epoch actions)

[cwgoes]

• We need some standard templates for pages, the organization of content within pages is all over the place. For example, for each module page, we could have something like:

  • Introduction
  • Design
  • Type definitions
  • VP pseudocode
  • Storage keys
  • Transaction actions

Let's simplify this to:

• Introduction in the module page itself
• Required sub-pages for
  • Design rationale
  • Types and storage (type definitions & storage keys)
  • Validity conditions (VP pseudocode)
  • Transaction actions