github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/docs/spec/SPEC-SPEC.md (about)

     1  # Specification of Specifications
     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 file structure should be used to breakdown
    23  specifications for modules. With the exception of README.md, `XX` at the
    24  beginning of the file name should be replaced with a number to indicate
    25  document flow (ex. read `01_state.md` before `02_state_transitions.md`). The
    26  following list is nonbinding and all files are optional.
    27  
    28  - `README.md` - overview of the module
    29  - `XX_concepts.md` - describe specialized concepts and definitions used throughout the spec
    30  - `XX_state.md` - specify and describe structures expected to marshalled into the store, and their keys
    31  - `XX_state_transitions.md` - standard state transition operations triggered by hooks, messages, etc.
    32  - `XX_messages.md` - specify message structure(s) and expected state machine behaviour(s)
    33  - `XX_begin_block.md` - specify any begin-block operations
    34  - `XX_end_block.md` - specify any end-block operations
    35  - `XX_hooks.md` - describe available hooks to be called by/from this module
    36  - `XX_events.md` - list and describe event tags used
    37  - `XX_params.md` - list all module parameters, their types (in JSON) and examples
    38  - `XX_future_improvements.md` - describe future improvements of this module
    39  - `XX_appendix.md` - supplementary details referenced elsewhere within the spec
    40  
    41  ### Notation for key-value mapping
    42  
    43  Within `state.md` the following notation `->` should be used to describe key to
    44  value mapping:
    45  
    46  ```
    47  key -> value
    48  ```
    49  
    50  to represent byte concatenation the `|` may be used. In addition, encoding
    51  type may be specified, for example:
    52  
    53  ```
    54  0x00 | addressBytes | address2Bytes -> amino(value_object)
    55  ```
    56  
    57  Additionally, index mappings may be specified by mapping to the `nil` value, for example:
    58  
    59  ```
    60  0x01 | address2Bytes | addressBytes -> nil
    61  ```