R4R: ICS 1: Interchain Standard

README.md

@@ -64,7 +64,7 @@ This repository is for standards development of Interchain Standards. Initially
 - _**Implementation Types Expected**_:
   * Spec compliant
 
-#### Stage 4 - `Finished`
+#### Stage 4 - `Finalized`
 - _**Purpose**_:
   * Indicate that the addition is included in the formal ICS system
 - _**Entrance Criteria**_:

_layouts/ics.html

@@ -0,0 +1,20 @@
+---
+layout: default
+---
+
+<div class="home">
+  <h1 class="page-heading">
+    ICS {{ page.eip | xml_escape }}: {{ page.title | xml_escape }}
+    <a href="{{site.github.repository_url}}/blob/master/{{page.path}}"><svg role="img" aria-label="Source" xmlns="http://www.w3.org/2000/svg" width="14" height="16" viewBox="0 0 14 16"><title>Source</title><path fill-rule="evenodd" d="M9.5 3L8 4.5 11.5 8 8 11.5 9.5 13 14 8 9.5 3zm-5 0L0 8l4.5 5L6 11.5 2.5 8 6 4.5 4.5 3z"/></svg></a>
+  </h1>
+  <table>
+    <tr><th>Stage</th><td>{{ page.stage | xml_escape }}</td></tr>
+    <tr><th>Category</th><td>{{ page.category | xml_escape }}</td></tr>
+    <tr><th>Author</th><td>{{ page.author | xml_escape }}</td></tr>
+    <tr><th>Created</th><td>{{ page.created | xml_escape }}</td></tr>
+    <tr><th>Modified</th><td>{{ page.modified | xml_escape }}</td></tr>
+  </table>
+
+  {{ content }}
+
+</div>

spec/ics-1-ics-standard/README.md

@@ -0,0 +1,156 @@
+---
+ics: 1
+title: ICS Specification Standard
+stage: draft
+category: meta
+author: Christopher Goes <cwgoes@tendermint.com>
+created: 2019-02-12
+modified: 2019-03-04
+---
+
+## What is an ICS?
+
+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).
+
+## Components
+
+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.
+
+### Header
+
+An ICS header contains metadata relevant to the ICS.
+
+#### Required fields
+
+`ics: #` - ICS number (assigned sequentially)
+
+`title` - ICS title (keep it short & sweet)
+
+`stage` - Current ICS stage, one of the following:
+- `proposal` - A standard in the "proposal" stage
+- `draft` - A standard in the "draft" stage
+- `candidate` - A standard in the "candidate" stage
+- `finalized` - A standard in the "finalized" stage
+
+See [README.md](../../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-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`)
+
+#### Optional fields
+
+`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.
+
+### Synopsis
+
+Following the header, an ICS should include a brief (~200 word) synopsis providing a high-level
+description of and rationale for the specification.
+
+### 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.
+
+#### Sub-components
+
+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).
+
+### History
+
+An ICS 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
+
+An ICS should include a copyright section waiving rights via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+## Formatting
+
+### General
+
+ICS specifications must be written in GitHub-flavored Markdown.
+
+For a GitHub-flavored 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
+
+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](https://simple.wikipedia.org/wiki/Main_Page).
+
+### 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. 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)
+```
+
+## History
+
+This specification was significantly inspired by and derived from Ethereum's [EIP 1](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md), 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
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).