Update SPEC-SPEC & documentation for x/{bank,evidence} (#7404 )

* Update documentation for x/bank

* Update ModuleAccounts

* Put contets on top

* Update comments

* Do x/evidence

* Add ValidatorEvidence

* Update SPEC-SPEC

* Update anchor

2020-09-28 13:51:14 -03:00

2.6 KiB

Raw Blame History

Specification of Specifications

This file intends to outline the common structure for specifications within this directory.

Tense

For consistency, specs should be written in passive present tense.

Pseudo-Code

Generally, pseudo-code should be minimized throughout the spec. Often, simple bulleted-lists which describe a function's operations are sufficient and should be considered preferable. In certain instances, due to the complex nature of the functionality being described pseudo-code may the most suitable form of specification. In these cases use of pseudo-code is permissible, but should be presented in a concise manner, ideally restricted to only the complex element as a part of a larger description.

Common Layout

The specifications should be contained in a single README.md file inside the spec/ folder of a given module.

The following generalized document structure should be used to breakdown specifications for modules. Each bullet item corresponds to a new section in the document, and should begin with a secondary heading (## {HEADING} in Markdown). The XX at the beginning of the section name should be replaced with a number to indicate document flow (ex. read 01. Concepts before 02. State Transitions). The following list is nonbinding and all sections are optional.

XX. Abstract - overview of the module
XX. Concepts - describe specialized concepts and definitions used throughout the spec
XX. State - specify and describe structures expected to marshalled into the store, and their keys
XX. State Transitions - standard state transition operations triggered by hooks, messages, etc.
XX. Messages - specify message structure(s) and expected state machine behaviour(s)
XX. BeginBlock - specify any begin-block operations
XX. EndBlock - specify any end-block operations
XX. Hooks - describe available hooks to be called by/from this module
XX. Events - list and describe event tags used
XX. Params - list all module parameters, their types (in JSON) and examples
XX. Future Improvements - describe future improvements of this module
XX. Appendix - supplementary details referenced elsewhere within the spec

Notation for key-value mapping

Within the State section, the following notation -> should be used to describe key to value mapping:

key -> value

to represent byte concatenation the | may be used. In addition, encoding type may be specified, for example:

0x00 | addressBytes | address2Bytes -> amino(value_object)

Additionally, index mappings may be specified by mapping to the nil value, for example:

0x01 | address2Bytes | addressBytes -> nil

2.6 KiB Raw Blame History