From e161303aea172065062e104dfe504a98ae1681f6 Mon Sep 17 00:00:00 2001 From: Manuel Bravo Date: Thu, 24 Nov 2022 16:11:43 +0100 Subject: [PATCH 1/7] first draft store-spec-standard --- store/SPEC_STANDARD.md | 108 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 store/SPEC_STANDARD.md diff --git a/store/SPEC_STANDARD.md b/store/SPEC_STANDARD.md new file mode 100644 index 000000000000..5324c8f67c03 --- /dev/null +++ b/store/SPEC_STANDARD.md @@ -0,0 +1,108 @@ +A store specification document is a design document describing a particular store feature such as a store interface or implementation that it is expected to be used (or already in use) by the Cosmos SDK. This also includes other store-related features such as caches and wrappers. + +## Sections + +An store specification document consists of, synopsis, overview and basic concepts, technical specification, history log, and copyright notice. 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. + +### Synopsis + +The document should include a brief (~200 word) synopsis providing a high-level +description of and rationale for the specification. + +### Overview and basic concepts + +This section should include a motivation sub-section and a definitions sub-section if required: + +- *Motivation* - A rationale for the existence of the proposed interface, implementation, or the proposed changes to an existing feature. +- *Definitions* - A list of new terms or concepts utilised in the document or required to understand it. + +### System model and properties + +This section should include an assumptions sub-section if any, and the mandatory properties sub-section. Note that both sub-sections are tightly coupled: how to enforce a property will depend directly on the assumptions made. + +- *Assumptions* - A list of any assumptions made by the feature designer. This may for instance include how it is assumed that the feature will be used by upper layers in the stack. +- *Properties* - The content of this sub-section depends on the type of specification. For implementations, the sub-section should include a list of properties that the implementation guarantees and list which properties it does not. The latter is as important as the former. In the case of a store interface, this sub-section should include a list of the desired properties that an implementation of the interface should guarantee. Ideally, along with each of the properties should go a text arguing why the property is required. Examples of properties are whether the feature is or must be thread-safe, atomicity-related properties or behaviour under failures. + +### Technical specification + +This is the main section of the document, and should contain protocol documentation, design rationale, +required references, and technical details where appropriate. +Apart from the API sub-section which is required, the section may have any or all of the following sub-sections, as appropriate to the particular specification. + +- *API* - A detailed description of the features's API including which interfaces implements (for implementations) or extends (for interfaces). +- *Technical Specification* - 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. +- *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions. +- *Known Issues* - A list of known issues. This sub-section is specially important for specifications of already in-use features. +- *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers. This sub-section is only expected to be included in newly proposed interfaces. + +### History + +A store specification should include a history section, listing any inspiring documents and a plaintext log of significant changes. + +See an example history section [below](#history-1). + +### Copyright + +A store specification should include a copyright section waiving rights via [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). + +## Formatting + +### General + +Specifications must be written in GitHub-flavoured Markdown. + +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). + +### Language + +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). + +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). + +### Pseudocode + +Pseudocode in specifications should be language-agnostic and formatted in a simple imperative standard, with line numbers, variables, simple conditional blocks, for loops, and +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. + +Pseudocode for structs should be written in simple Typescript, as interfaces. + +Example pseudocode struct: + +```typescript +interface CacheKVStore { + cache: Map + parent: KVStore + deleted: Key +} +``` + +Pseudocode for algorithms should be written in simple Typescript, as functions. + +Example pseudocode algorithm: + +```typescript +function get( + store: CacheKVStore, + key: Key): Value { + + value = store.cache.get(Key) + if (value !== null) { + return value + } else { + value = store.parent.get(key) + store.cache.set(key, value) + return value + } +} +``` + +## History + +This specification was significantly inspired by and derived from , which +was in turn derived from Ethereum's [EIP 1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md). + +Nov 24, 2022 - Initial draft finished and submitted as a PR + +## Copyright + +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). \ No newline at end of file From 301045db9abf9422f53aba8390a46020b3ba1503 Mon Sep 17 00:00:00 2001 From: Manuel Bravo Date: Fri, 25 Nov 2022 12:07:07 +0100 Subject: [PATCH 2/7] minor changes --- store/SPEC_STANDARD.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/store/SPEC_STANDARD.md b/store/SPEC_STANDARD.md index 5324c8f67c03..ca6e427f8ce7 100644 --- a/store/SPEC_STANDARD.md +++ b/store/SPEC_STANDARD.md @@ -1,3 +1,5 @@ +## What is a store specification document? + A store specification document is a design document describing a particular store feature such as a store interface or implementation that it is expected to be used (or already in use) by the Cosmos SDK. This also includes other store-related features such as caches and wrappers. ## Sections @@ -98,7 +100,7 @@ function get( ## History -This specification was significantly inspired by and derived from , which +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 was in turn derived from Ethereum's [EIP 1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md). Nov 24, 2022 - Initial draft finished and submitted as a PR From b84edd40e9494d9218facd08391b0c1eefad3cc4 Mon Sep 17 00:00:00 2001 From: Manuel Bravo Date: Tue, 29 Nov 2022 12:24:05 +0100 Subject: [PATCH 3/7] generalize --- store/SPEC_STANDARD.md | 40 +++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/store/SPEC_STANDARD.md b/store/SPEC_STANDARD.md index ca6e427f8ce7..a53f5e4e02a7 100644 --- a/store/SPEC_STANDARD.md +++ b/store/SPEC_STANDARD.md @@ -1,51 +1,57 @@ -## What is a store specification document? +## What is a SDK standard? -A store specification document is a design document describing a particular store feature such as a store interface or implementation that it is expected to be used (or already in use) by the Cosmos SDK. This also includes other store-related features such as caches and wrappers. +A 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. ## Sections -An store specification document consists of, synopsis, overview and basic concepts, technical specification, history log, and copyright notice. 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. +A SDK standard consists of: +- a synopsis, +- overview and basic concepts, +- technical specification, +- history log, and +- copyright notice. + +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. ### Synopsis -The document should include a brief (~200 word) synopsis providing a high-level -description of and rationale for the specification. +The document should include a brief (~200 word) synopsis providing a high-level description of and rationale for the specification. ### Overview and basic concepts This section should include a motivation sub-section and a definitions sub-section if required: -- *Motivation* - A rationale for the existence of the proposed interface, implementation, or the proposed changes to an existing feature. -- *Definitions* - A list of new terms or concepts utilised in the document or required to understand it. +- *Motivation* - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature. +- *Definitions* - A list of new terms or concepts utilized in the document or required to understand it. ### System model and properties -This section should include an assumptions sub-section if any, and the mandatory properties sub-section. Note that both sub-sections are tightly coupled: how to enforce a property will depend directly on the assumptions made. +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. -- *Assumptions* - A list of any assumptions made by the feature designer. This may for instance include how it is assumed that the feature will be used by upper layers in the stack. -- *Properties* - The content of this sub-section depends on the type of specification. For implementations, the sub-section should include a list of properties that the implementation guarantees and list which properties it does not. The latter is as important as the former. In the case of a store interface, this sub-section should include a list of the desired properties that an implementation of the interface should guarantee. Ideally, along with each of the properties should go a text arguing why the property is required. Examples of properties are whether the feature is or must be thread-safe, atomicity-related properties or behaviour under failures. +- *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. +- *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. +- *Dependencies* - A list of the features that use the feature under specification and how. ### Technical specification -This is the main section of the document, and should contain protocol documentation, design rationale, -required references, and technical details where appropriate. -Apart from the API sub-section which is required, the section may have any or all of the following sub-sections, as appropriate to the particular specification. +This is the main section of the document, and should contain protocol documentation, design rationale, required references, and technical details where appropriate. +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. -- *API* - A detailed description of the features's API including which interfaces implements (for implementations) or extends (for interfaces). +- *API* - A detailed description of the features's API. - *Technical Specification* - 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. - *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions. - *Known Issues* - A list of known issues. This sub-section is specially important for specifications of already in-use features. -- *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers. This sub-section is only expected to be included in newly proposed interfaces. +- *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers. ### History -A store specification should include a history section, listing any inspiring documents and a plaintext log of significant changes. +A specification should include a history section, listing any inspiring documents and a plaintext log of significant changes. See an example history section [below](#history-1). ### Copyright -A store specification should include a copyright section waiving rights via [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). +A specification should include a copyright section waiving rights via [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). ## Formatting From 24dee4652d2b2cbd9fe4fdcbcfb14f5aab924d02 Mon Sep 17 00:00:00 2001 From: Marko Date: Mon, 5 Dec 2022 15:01:26 +0100 Subject: [PATCH 4/7] Update store/SPEC_STANDARD.md Co-authored-by: Aleksandr Bezobchuk --- store/SPEC_STANDARD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/store/SPEC_STANDARD.md b/store/SPEC_STANDARD.md index a53f5e4e02a7..675f9616c6ee 100644 --- a/store/SPEC_STANDARD.md +++ b/store/SPEC_STANDARD.md @@ -1,4 +1,4 @@ -## What is a SDK standard? +## What is an SDK standard? A 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. From e603194a1fd1a00e563ae0b3227470edb40d78c6 Mon Sep 17 00:00:00 2001 From: Marko Date: Mon, 5 Dec 2022 15:01:38 +0100 Subject: [PATCH 5/7] Update store/SPEC_STANDARD.md Co-authored-by: Aleksandr Bezobchuk --- store/SPEC_STANDARD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/store/SPEC_STANDARD.md b/store/SPEC_STANDARD.md index 675f9616c6ee..6ab004806170 100644 --- a/store/SPEC_STANDARD.md +++ b/store/SPEC_STANDARD.md @@ -1,6 +1,6 @@ ## What is an SDK standard? -A 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. +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. ## Sections From 4fe864ed1b62dedf7769e5cebe0ba5863e9f9d2d Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Mon, 5 Dec 2022 15:10:26 +0100 Subject: [PATCH 6/7] move and write golang --- docs/spec/{SPEC-SPEC.md => SPEC_MODULE.md} | 2 +- {store => docs/spec}/SPEC_STANDARD.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) rename docs/spec/{SPEC-SPEC.md => SPEC_MODULE.md} (98%) rename {store => docs/spec}/SPEC_STANDARD.md (97%) diff --git a/docs/spec/SPEC-SPEC.md b/docs/spec/SPEC_MODULE.md similarity index 98% rename from docs/spec/SPEC-SPEC.md rename to docs/spec/SPEC_MODULE.md index f0828dfd9817..8288a294412d 100644 --- a/docs/spec/SPEC-SPEC.md +++ b/docs/spec/SPEC_MODULE.md @@ -1,4 +1,4 @@ -# Specification of Specifications +# Specification of Modules This file intends to outline the common structure for specifications within this directory. diff --git a/store/SPEC_STANDARD.md b/docs/spec/SPEC_STANDARD.md similarity index 97% rename from store/SPEC_STANDARD.md rename to docs/spec/SPEC_STANDARD.md index 6ab004806170..82833f1f73c2 100644 --- a/store/SPEC_STANDARD.md +++ b/docs/spec/SPEC_STANDARD.md @@ -72,9 +72,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S Pseudocode in specifications should be language-agnostic and formatted in a simple imperative standard, with line numbers, variables, simple conditional blocks, for loops, and 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. -Pseudocode for structs should be written in simple Typescript, as interfaces. +Pseudocode for structs can be written in a simple langauge like Typescript or golang, as interfaces. -Example pseudocode struct: +Example Typescript pseudocode struct: ```typescript interface CacheKVStore { @@ -113,4 +113,4 @@ Nov 24, 2022 - Initial draft finished and submitted as a PR ## Copyright -All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). \ No newline at end of file +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). From 0978f5d30931669105d12f97827302ebea407193 Mon Sep 17 00:00:00 2001 From: Marko Date: Mon, 5 Dec 2022 18:04:48 +0100 Subject: [PATCH 7/7] Update docs/spec/SPEC_STANDARD.md --- docs/spec/SPEC_STANDARD.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/spec/SPEC_STANDARD.md b/docs/spec/SPEC_STANDARD.md index 82833f1f73c2..da8c3178f1c8 100644 --- a/docs/spec/SPEC_STANDARD.md +++ b/docs/spec/SPEC_STANDARD.md @@ -13,6 +13,10 @@ A SDK standard consists of: 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. + ### Table Of Contents + + > Provide a table of contents at the top of the file to assist readers. + ### Synopsis The document should include a brief (~200 word) synopsis providing a high-level description of and rationale for the specification.