| ics | title | stage | category | author | created | modified |
|---|---|---|---|---|---|---|
1 |
ICS Specification Standard |
draft |
meta |
Christopher Goes <[email protected]> |
2019-02-12 |
2019-03-28 |
An inter-chain standard (ICS) is a design document describing a particular protocol, standard, or feature expected to be of use to the Cosmos ecosystem. An ICS should list the desired properties of the standard, explain the design rationale, and provide a concise but comprehensive technical specification. The primary ICS 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.
The inter-chain standardization process should be the primary vehicle for proposing ecosystem-wide protocols, changes, and features, and ICS documents should persist after consensus as a record of design decisions and an information repository for future implementers.
Inter-chain standards should not be used for proposing changes to a particular blockchain (such as the Cosmos Hub), specifying implementation particulars (such as language-specific data structures), or debating governance proposals on existing Cosmos blockchains (although it is possible that individual blockchains in the Cosmos ecosystem may utilize their governance processes to approve or reject inter-chain standards).
An ICS consists of a header, synopsis, 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.
An ICS header contains metadata relevant to the ICS.
ics: # - ICS number (assigned sequentially)
title - ICS title (keep it short & sweet)
stage - Current ICS stage, see PROCESS.md for the list of possible stages.
See README.md for a description of the ICS acceptance stages.
category - ICS category, one of the following:
meta- A standard about the ICS processibc-core- A standard about the inter-blockchain communication system core protocol.ibc-app- A standard about the inter-blockchain communication system application layer.misc- A standard about miscellaneous / auxiliary features, e.g. message signing
author - ICS author(s) & contact information (in order of preference: email, GitHub handle, Twitter handle, other contact methods likely to elicit response).
The first author is the primary "owner" of the ICS and is responsible for advancing it through the standardization process.
Subsequent author ordering should be in order of contribution amount.
created - Date ICS was first created (YYYY-MM-DD)
modified - Date ICS was last modified (YYYY-MM-DD)
requires - Other ICS standards, referenced by number, which are required or depended upon by this standard.
required-by - Other ICS standards, referenced by number, which require or depend upon this standard.
replaces - Another ICS standard replaced or supplanted by this standard, if applicable.
replaced-by - Another ICS standard which replaces or supplants this standard, if applicable.
Following the header, an ICS should include a brief (~200 word) synopsis providing a high-level description of and rationale for the specification.
The specification section is the main component of an ICS, and should contain protocol documentation, design rationale, required references, and technical details where appropriate.
The specification may have any or all of the following sub-components, as appropriate to the particular ICS. Included sub-components should be listed in the order specified here.
- Motivation - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature.
- Desired Properties - A list of the desired properties or characteristics of the protocol or feature specified, and expected effects or failures when the properties are violated.
- Technical Specification - All technical details of the proposed protocol including syntax, semantics, sub-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.
- Forwards Compatibility - A discussion of compatibility (or lack thereof) with future possible or expected features or protocol versions.
- Example Implementation - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers.
- Other Implementations - A list of candidate or finalized implementations (external references, not inline).
An ICS should include a history section, listing any inspiring documents and a plaintext log of significant changes.
See an example history section below.
An ICS should include a copyright section waiving rights via CC0.
ICS specifications must be written in GitHub-flavored Markdown.
For a GitHub-flavored Markdown cheat sheet, see here. For a local Markdown renderer, see here.
ICS 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.
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. If desired, images can be generated with LaTeX and rendered in Markdown - if this is done, LaTeX source code should be included.
Example pseudocode:
11: FunctionStartRound(round):
12: round_p ← round
13: step_p ← propose
14: if proposer(h_p, round_p) = p then
15: if validValue_p /= nil then
16: proposal ← validValue_p
17: else
18: proposal ← getValue()
19: broadcast <PROPOSAL, h_p, round_p, proposal, validRound>
20: else
21: scheduleOnTimeoutPropose(h_p, round_p) to be executed after timeoutPropose(round_p)
This specification was significantly inspired by and derived from Ethereum's EIP 1, which was in turn derived from Bitcoin's BIP process and Python's PEP process. Antecedent authors are not responsible for any shortcomings of this ICS spec or the ICS process. Please direct all comments to the ICS repository maintainers.
March 4th, 2019: Initial ICS 1 draft finished and submitted as a PR March 7th, 2019: ICS 1 draft merged
Copyright and related rights waived via CC0.