| ics | title | stage | category | kind | author | created | modified |
|---|---|---|---|---|---|---|---|
1 |
ICS Specification Standard |
draft |
meta |
meta |
Christopher Goes <[email protected]> |
2019-02-12 |
2019-08-25 |
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 standardisation process, soliciting input and support from the community, and communicating with relevant stakeholders to ensure (social) consensus.
The inter-chain standardisation 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 utilise 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 process.IBC/TAO- A standard about an inter-blockchain communication system core transport, authentication, and ordering layer protocol.IBC/APP- A standard about an inter-blockchain communication system application layer protocol.
kind - ICS kind, one of the following:
meta- A standard about the ICS process.interface- A standard about the minimal set of interfaces that must be provided and properties that must be fulfilled by a state machine hosting an implementation of the inter-blockchain communication protocol.instantiation- A standard about concrete implementation details that explains how the standard is realized in pseudocode or software components.
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 standardisation 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.
version compatibility - List of versions of implementations compatible with the ICS standard.
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.
- Definitions - A list of new terms or concepts utilised in this ICS or required to understand this ICS. Any terms not defined in the top-level "docs" folder must be defined here.
- 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 Implementations - Concrete example implementations or descriptions of expected implementations to serve as the primary reference for implementers.
- Other Implementations - A list of candidate or finalised 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 Apache 2.0.
ICS specifications must be written in GitHub-flavoured Markdown.
For a GitHub-flavoured 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.
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.
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:
interface Connection {
state: ConnectionState
version: Version
counterpartyIdentifier: Identifier
consensusState: ConsensusState
}Pseudocode for algorithms should be written in simple Typescript, as functions.
Example pseudocode algorithm:
function startRound(round) {
round_p = round
step_p = PROPOSE
if (proposer(h_p, round_p) === p) {
if (validValue_p !== nil)
proposal = validValue_p
else
proposal = getValue()
broadcast( {PROPOSAL, h_p, round_p, proposal, validRound} )
} else
schedule(onTimeoutPropose(h_p, round_p), 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.
Mar 4, 2019 - Initial draft finished and submitted as a PR
Mar 7, 2019 - Draft merged
Apr 11, 2019 - Updates to pseudocode formatting, add definitions subsection
Aug 17, 2019 - Clarifications to categories
All content herein is licensed under Apache 2.0.