Component Wiki Docs Template (WIP)

[avive]

Design Wiki

• High-level component overview
• What is the component main role in the Spacemesh full node software?
• What are the main service(s) that the component is designed to provide to other components?
• Which other components use this component and what services they use? Give one example.
• What protocols / algorithms is the component design to implement? Link to research papers / wikipedia / etc.
• Document any custom algorithm that the component should implement. e.g. modified hare.
• What is the component NOT designed to do?
• What services it assumes to be provided by other components for it to provide its service?
• Flow chart of the component main algorithm(s) here. e.g. hare protocol flow
• Main protocol sequence diagram
• Context: How did we end up with this design and how it evolved since the project started?

Implementation Wiki

This is high level summary of information. Not go-docs we should have for specific types.

• What are the API(s) provided by the component? Which public types provide the API? Which go interfaces define the API(s)
• For the main types and interfaces, which concern does each type implement and what abstractions is used?
• What is the main integration test that shows how to use the component from other components?
• Point to code in another component that uses the component main API.
• What are the main data structures used in the implementation?
• What are the main dependencies used by the component in the implementation?
• What are the known implementation limitations and tradeoffs - what can be improved in the future?
• Point to the component unit tests
• Which type can use more unit and integration tests? We want to get to good coverage and if we document this we can direct contributions to write these tests.
• What are the main crypto primitives that the component uses in the implementation. e.g. eds25519, bls, etc...
• Link to components go-docs
• Control flow sequence diagram when applicable

Shared Types

• What are the main types which are shared between the different components?
• What is their interface?
• e.g. blocks

@lrettig @zalmen @liathoffman

[lrettig]

I'm now tracking this at https://github.com/spacemeshos/protocol/projects/1. Feel free to close this issue in favor of that project if you like, or else keep it open if there's more in scope here than just the initial set of wiki docs (e.g., more code documentation).