SDK 标准是一份设计文档，用于描述 Cosmos SDK 预期采用的某项协议、标准或功能。SDK 标准应列出该标准期望具备的属性，说明设计原理，并提供简明但完整的技术规范。主要作者负责推动提案通过标准化流程，向社区征求意见与支持，并与相关利益相关方沟通，以确保形成（社会）共识。

​
章节

一份 SDK 标准由以下部分组成：
  • 摘要，
  • 概览与基本概念，
  • 技术规范，
  • 历史记录，以及
  • 版权声明。
所有一级章节都是必需的。参考资料应以内联链接的形式包含在正文中，或者在必要时以表格形式列在章节底部。所包含的子章节应按下文规定的顺序排列。

​
目录

在文件顶部提供目录，以帮助读者查阅。

​
摘要

文档应包含一段简短的摘要（约 200 词），对该规范提供高层描述及其设计依据。

​
概览与基本概念

如果需要，本节应包含“动机”和“定义”两个子章节：
  • 动机 - 说明所提功能存在的理由，或对现有功能拟议变更的理由。
  • 定义 - 列出文档中使用的、或理解文档所必需的新术语或概念。

​
系统模型与属性

本节应包含“假设”子章节（如有）、必需的“属性”子章节，以及“依赖关系”子章节。请注意，前两个子章节是紧密耦合的：如何强制满足某项属性，将直接取决于所作出的假设。本节对于描述所规定功能与“外部世界”的交互非常重要，也就是它与生态系统中其他功能之间的关系。
  • 假设 - 列出功能设计者作出的所有假设。应说明该规范中的功能使用了哪些其他功能，以及我们对这些功能的预期。
  • 属性 - 列出所规定功能期望具备的属性或特征，以及当这些属性被违反时预期产生的效果或故障。如有必要，也可以列出该功能不保证的属性。
  • 依赖关系 - 列出哪些功能会使用该规范中的功能，以及它们如何使用。

​
技术规范

这是文档的主体章节，应在适当情况下包含协议文档、设计原理、必要参考资料以及技术细节。 根据具体规范的需要，本节可以包含以下任意一个或全部子章节。其中，适用时尤其鼓励包含 API 子章节。
  • API - 对该功能 API 的详细说明。
  • 技术细节 - 所有技术细节，包括适用时的语法、图表、语义、协议、数据结构、算法和伪代码。技术规范应足够详细，以确保彼此不了解的独立正确实现仍然能够兼容。
  • 向后兼容性 - 讨论与先前功能或协议版本的兼容性（或不兼容性）。
  • 已知问题 - 列出已知问题。对于已经投入使用的功能规范，这个子章节尤为重要。
  • 示例实现 - 给出一个具体的示例实现，或对预期实现的描述，作为实现者的主要参考。

​
历史

规范应包含历史章节，列出任何启发性文档，以及重大变更的纯文本日志。 请参见下文的历史章节示例。

​
版权

规范应包含版权章节，通过 Apache 2.0 放弃相关权利。

​
格式

​
通用要求

规范必须使用 GitHub 风格的 Markdown 编写。 关于 GitHub 风格 Markdown 的速查表，请参见此处。如需本地 Markdown 渲染器，请参见此处。

​
语言

规范应使用简明英语编写，避免晦涩术语和不必要的行话。若要查看简明英语的优秀示例，请参见 Simple English Wikipedia。 规范中的关键词 “MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY” 和 “OPTIONAL” 应按照 RFC 2119 中的定义进行解释。

​
伪代码

规范中的伪代码应与具体编程语言无关，并采用简单的命令式标准格式，包含行号、变量、简单条件块、for 循环，以及在必要时用于进一步说明功能（如超时调度）的英文片段。应避免使用 LaTeX 图像，因为它们难以以 diff 形式进行审查。 结构体的伪代码可以使用类似 TypeScript 或 golang 的简单语言，以接口形式编写。 Golang 伪代码结构体示例： 
type CacheKVStore interface {
    cache: map[Key]Value
  parent: KVStore
  deleted: Key
}
算法的伪代码应使用简单的 Golang，以函数形式编写。 伪代码算法示例： 
func 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
}
}

​
历史

本规范在很大程度上受到 IBC 的 ICS 启发并在其基础上演化而来，而后者又源自以太坊的 EIP 1。 2022 年 11 月 24 日 - 初始草案完成并作为 PR 提交

​
版权

本文所有内容均依据 Apache 2.0 许可。
An SDK standard is a design document describing a particular protocol, standard, or feature expected to be used by the Cosmos SDK. An 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 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 subsections should be listed in the order specified below.

​
Table Of Contents

Provide a table of contents at the top of the file to help readers.

​
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 subsection and a definition subsection if required:
  • 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 used in the document or required to understand it.

​
System model and properties

This section should include an assumption subsection if any, the mandatory properties subsection, and a dependency subsection. Note that the first two subsections are tightly coupled: how to enforce a property will depend directly on the assumptions made. This subsection 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. 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. The section may have any or all of the following subsections, as appropriate to the particular specification. The API subsection is especially encouraged when appropriate.
  • API - A detailed description of the feature’s API.
  • 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.
  • Backwards Compatibility - A discussion of compatibility (or lack thereof) with previous feature or protocol versions.
  • Known Issues - A list of known issues. This subsection 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.

​
History

A specification should include a history section, listing any inspiring documents and a plaintext log of significant changes. See an example history section below. A specification should include a copyright section waiving rights via Apache 2.0.

​
Formatting

​
General

Specifications must be written in GitHub-flavored Markdown. For a GitHub-flavored Markdown cheat sheet, see here. For a local Markdown renderer, see here.

​
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. The keywords “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.

​
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 challenging to review in diff form. Pseudocode for structs can be written in a simple language like TypeScript or golang, as interfaces. Example Golang pseudocode struct: 
type CacheKVStore interface {
    cache: map[Key]Value
  parent: KVStore
  deleted: Key
}
Pseudocode for algorithms should be written in simple Golang, as functions. Example pseudocode algorithm: 
func 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 IBC’s ICS, which was in turn derived from Ethereum’s EIP 1. Nov 24, 2022 - Initial draft finished and submitted as a PR All content herein is licensed under Apache 2.0.