docs: store spec template/guideline (#14020)

* first draft store-spec-standard * minor changes * generalize * Update store/SPEC_STANDARD.md Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com> * Update store/SPEC_STANDARD.md Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com> * move and write golang * Update docs/spec/SPEC_STANDARD.md Co-authored-by: Marko <marbar3778@yahoo.com> Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com>
2022-12-05 22:39:47 +00:00
parent 07b24d5d50
commit a31c4acc7b
2 changed files with 121 additions and 1 deletions
@@ -0,0 +1,60 @@
+# Specification of Modules
+
+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 following generalized `README` structure should be used to breakdown
+specifications for modules. The following list is nonbinding and all sections are optional.
+
+* `# {Module Name}` - overview of the module
+* `## Concepts` - describe specialized concepts and definitions used throughout the spec
+* `## State` - specify and describe structures expected to marshalled into the store, and their keys
+* `## State Transitions` - standard state transition operations triggered by hooks, messages, etc.
+* `## Messages` - specify message structure(s) and expected state machine behaviour(s)
+* `## Begin Block` - specify any begin-block operations
+* `## End Block` - specify any end-block operations
+* `## Hooks` - describe available hooks to be called by/from this module
+* `## Events` - list and describe event tags used
+* `## Client` - list and describe CLI commands and gRPC and REST endpoints
+* `## Params` - list all module parameters, their types (in JSON) and examples
+* `## Future Improvements` - describe future improvements of this module
+* `## Tests` - acceptance tests
+* `## Appendix` - supplementary details referenced elsewhere within the spec
+
+### Notation for key-value mapping
+
+Within `state.md` the following notation `->` should be used to describe key to
+value mapping:
+
+```text
+key -> value
+```
+
+to represent byte concatenation the `|` may be used. In addition, encoding
+type may be specified, for example:
+
+```text
+0x00 | addressBytes | address2Bytes -> amino(value_object)
+```
+
+Additionally, index mappings may be specified by mapping to the `nil` value, for example:
+
+```text
+0x01 | address2Bytes | addressBytes -> nil
+```