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

     1  # What is an SDK standard?
     2  
     3  An SDK standard is a design document describing a particular protocol, standard, or feature expected to be used by the Cosmos SDK. A SDK standard should list the desired properties of the standard, explain the design rationale, and provide a concise but comprehensive technical specification. The primary author is responsible for pushing the proposal through the standardization process, soliciting input and support from the community, and communicating with relevant stakeholders to ensure (social) consensus.
     4  
     5  ## Sections
     6  
     7  A SDK standard consists of:
     8  
     9  * a synopsis, 
    10  * overview and basic concepts,
    11  * technical specification,
    12  * history log, and
    13  * copyright notice.
    14  
    15  All top-level sections are required. References should be included inline as links, or tabulated at the bottom of the section if necessary.  Included sub-sections should be listed in the order specified below. 
    16  
    17  ### Table Of Contents 
    18   
    19  Provide a table of contents at the top of the file to assist readers.
    20  
    21  ### Synopsis
    22  
    23  The document should include a brief (~200 word) synopsis providing a high-level description of and rationale for the specification.
    24  
    25  ### Overview and basic concepts
    26  
    27  This section should include a motivation sub-section and a definitions sub-section if required:
    28  
    29  * *Motivation* - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature.
    30  * *Definitions* - A list of new terms or concepts utilized in the document or required to understand it.
    31  
    32  ### System model and properties
    33  
    34  This section should include an assumptions sub-section if any, the mandatory properties sub-section, and a dependencies sub-section. Note that the first two sub-section are are tightly coupled: how to enforce a property will depend directly on the assumptions made. This sub-section is important to capture the interactions of the specified feature with the "rest-of-the-world", i.e., with other features of the ecosystem.
    35  
    36  * *Assumptions* - A list of any assumptions made by the feature designer. It should capture which features are used by the feature under specification, and what do we expect from them.
    37  * *Properties* - A list of the desired properties or characteristics of the feature specified, and expected effects or failures when the properties are violated. In case it is relevant, it can also include a list of properties that the feature does not guarantee.
    38  * *Dependencies* - A list of the features that use the feature under specification and how.
    39  
    40  ### Technical specification
    41  
    42  This is the main section of the document, and should contain protocol documentation, design rationale, required references, and technical details where appropriate.
    43  The section may have any or all of the following sub-sections, as appropriate to the particular specification. The API sub-section is especially encouraged when appropriate.
    44  
    45  * *API* - A detailed description of the features's API.
    46  * *Technical Details* - All technical details including syntax, diagrams, semantics, protocols, data structures, algorithms, and pseudocode as appropriate. The technical specification should be detailed enough such that separate correct implementations of the specification without knowledge of each other are compatible.
    47  * *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions.
    48  * *Known Issues* - A list of known issues. This sub-section is specially important for specifications of already in-use features.
    49  * *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers.
    50  
    51  ### History
    52  
    53  A specification should include a history section, listing any inspiring documents and a plaintext log of significant changes.
    54  
    55  See an example history section [below](#history-1).
    56  
    57  ### Copyright
    58  
    59  A specification should include a copyright section waiving rights via [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
    60  
    61  ## Formatting
    62  
    63  ### General
    64  
    65  Specifications must be written in GitHub-flavoured Markdown.
    66  
    67  For a GitHub-flavoured Markdown cheat sheet, see [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). For a local Markdown renderer, see [here](https://github.com/joeyespo/grip).
    68  
    69  ### Language
    70  
    71  Specifications should be written in Simple English, avoiding obscure terminology and unnecessary jargon. For excellent examples of Simple English, please see the [Simple English Wikipedia](https://simple.wikipedia.org/wiki/Main_Page).
    72  
    73  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in specifications are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
    74  
    75  ### Pseudocode
    76  
    77  Pseudocode in specifications should be language-agnostic and formatted in a simple imperative standard, with line numbers, variables, simple conditional blocks, for loops, and
    78  English fragments where necessary to explain further functionality such as scheduling timeouts. LaTeX images should be avoided because they are difficult to review in diff form.
    79  
    80  Pseudocode for structs can be written in a simple language like Typescript or golang, as interfaces.
    81  
    82  Example Golang pseudocode struct:
    83  
    84  ```go
    85  type CacheKVStore interface {
    86    cache: map[Key]Value
    87    parent: KVStore
    88    deleted: Key
    89  }
    90  ```
    91  
    92  Pseudocode for algorithms should be written in simple Golang, as functions.
    93  
    94  Example pseudocode algorithm:
    95  
    96  ```go
    97  func get(
    98    store CacheKVStore,
    99    key Key) Value {
   100  
   101    value = store.cache.get(Key)
   102    if (value !== null) {
   103      return value
   104    } else {
   105      value = store.parent.get(key)
   106      store.cache.set(key, value)
   107      return value
   108    }
   109  }
   110  ```
   111  
   112  ## History
   113  
   114  This specification was significantly inspired by and derived from IBC's [ICS](https://github.com/cosmos/ibc/blob/main/spec/ics-001-ics-standard/README.md), which
   115  was in turn derived from Ethereum's [EIP 1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md).
   116  
   117  Nov 24, 2022 - Initial draft finished and submitted as a PR
   118  
   119  ## Copyright
   120  
   121  All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).