e17dd4fd50
* Update documentation for x/bank * Update ModuleAccounts * Put contets on top * Update comments * Do x/evidence * Add ValidatorEvidence * Update SPEC-SPEC * Update anchor
67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# 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
|
|
```
|