github.com/cosmos/cosmos-sdk@v0.50.10/docs/spec/SPEC_MODULE.md (about)

     1  # Specification of Modules
     2  
     3  This file intends to outline the common structure for specifications within
     4  this directory.
     5  
     6  ## Tense
     7  
     8  For consistency, specs should be written in passive present tense.
     9  
    10  ## Pseudo-Code
    11  
    12  Generally, pseudo-code should be minimized throughout the spec. Often, simple
    13  bulleted-lists which describe a function's operations are sufficient and should
    14  be considered preferable. In certain instances, due to the complex nature of
    15  the functionality being described pseudo-code may the most suitable form of
    16  specification. In these cases use of pseudo-code is permissible, but should be
    17  presented in a concise manner, ideally restricted to only the complex
    18  element as a part of a larger description.
    19  
    20  ## Common Layout
    21  
    22  The following generalized `README` structure should be used to breakdown
    23  specifications for modules. The following list is nonbinding and all sections are optional.
    24  
    25  * `# {Module Name}` - overview of the module
    26  * `## Concepts` - describe specialized concepts and definitions used throughout the spec
    27  * `## State` - specify and describe structures expected to marshalled into the store, and their keys
    28  * `## State Transitions` - standard state transition operations triggered by hooks, messages, etc.
    29  * `## Messages` - specify message structure(s) and expected state machine behaviour(s)
    30  * `## Begin Block` - specify any begin-block operations
    31  * `## End Block` - specify any end-block operations
    32  * `## Hooks` - describe available hooks to be called by/from this module
    33  * `## Events` - list and describe event tags used
    34  * `## Client` - list and describe CLI commands and gRPC and REST endpoints
    35  * `## Params` - list all module parameters, their types (in JSON) and examples
    36  * `## Future Improvements` - describe future improvements of this module
    37  * `## Tests` - acceptance tests
    38  * `## Appendix` - supplementary details referenced elsewhere within the spec
    39  
    40  ### Notation for key-value mapping
    41  
    42  Within `## State` the following notation `->` should be used to describe key to
    43  value mapping:
    44  
    45  ```text
    46  key -> value
    47  ```
    48  
    49  to represent byte concatenation the `|` may be used. In addition, encoding
    50  type may be specified, for example:
    51  
    52  ```text
    53  0x00 | addressBytes | address2Bytes -> amino(value_object)
    54  ```
    55  
    56  Additionally, index mappings may be specified by mapping to the `nil` value, for example:
    57  
    58  ```text
    59  0x01 | address2Bytes | addressBytes -> nil
    60  ```