Merge PR cosmos#190: RC1 updates

.circleci/config.yml

@@ -39,6 +39,13 @@ jobs:
       - run: sudo apt-get update && sudo apt-get -y install protobuf-compiler
       - run: make check_proto
 
+  spellcheck:
+    <<: *linux_defaults
+    steps:
+      - checkout
+      - run: sudo apt-get update && sudo apt-get -y install aspell
+      - run: make spellcheck_noninteractive
+
 workflows:
   version: 2
   test-suite:
@@ -48,3 +55,4 @@ workflows:
       - check_sections
       - check_syntax
       - check_proto
+      - spellcheck

Makefile

@@ -29,4 +29,10 @@ check_proto:
 spec_pdf:
 	pandoc --pdf-engine=xelatex --template eisvogel --filter pandoc-include --mathjax --toc --number-sections -o spec.pdf spec.pdc
 
-.PHONY: $(TOPTARGETS) $(SUBDIRS) check check_links check_dependencies check_syntax check_sections check_proto spec_pdf
+spellcheck:
+	find . -type f -name "*.md" -exec aspell -p ./misc/aspell_dict -x -d en_GB -c {} \;
+
+spellcheck_noninteractive:
+	find . -type f -name "*.md" | xargs -n 1 -I % ./scripts/spellcheck.sh %
+
+.PHONY: $(TOPTARGETS) $(SUBDIRS) check check_links check_dependencies check_syntax check_sections check_proto spec_pdf spellcheck spellcheck_noninteractive

README.md

@@ -4,15 +4,15 @@
 
 ## Synopsis
 
-This repository is the canonical location for development and documentation of inter-chain standards utilized by the Cosmos network & interchain ecosystem. Initially it will be used to consolidate design documentation for the inter-blockchain communication protocol (IBC), encoding standards for Cosmos chains, and miscellaneous utilities such as off-chain message signing.
+This repository is the canonical location for development and documentation of inter-chain standards utilised by the Cosmos network & interchain ecosystem. Initially it will be used to consolidate design documentation for the inter-blockchain communication protocol (IBC), encoding standards for Cosmos chains, and miscellaneous utilities such as off-chain message signing.
 
-## Standardization
+## Standardisation
 
 Please see [ICS 1](spec/ics-001-ics-standard) for a description of what a standard entails.
 
-To propose a new standard, [open an issue](https://github.com/cosmos/ics/issues/new). To start a new standardization document, copy the [template](spec/ics-template.md) and open a PR.
+To propose a new standard, [open an issue](https://github.com/cosmos/ics/issues/new). To start a new standardisation document, copy the [template](spec/ics-template.md) and open a PR.
 
-See [PROCESS.md](PROCESS.md) for a description of the standardization process.
+See [PROCESS.md](PROCESS.md) for a description of the standardisation process.
 
 Quick references & interchain standards can be read as [a single PDF](./spec.pdf).
 
@@ -58,7 +58,7 @@ All standards in the "draft" stage are listed here in order of their ICS numbers
 | ------------------------------------------ | ----------------------- | ----- |
 | [20](spec/ics-020-fungible-token-transfer) | Fungible Token Transfer | Draft |
 
-## Standard Dependency Visualization
+## Standard Dependency Visualisation
 
 Directed arrows indicate a dependency relationship (that origin depends on destination).
 

ibc/1_IBC_ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 1: Inter-blockchain Communication Protocol Architecture
 
-**This is an overview of the high-level architecture & dataflow of the IBC protocol.**
+**This is an overview of the high-level architecture & data-flow of the IBC protocol.**
 
 **For a broad set of protocol design principles, see [here](./2_IBC_DESIGN_PRINCIPLES.md).**
 
@@ -34,17 +34,17 @@ IBC is not (only) a layer-two scaling protocol: all chains implementing IBC exis
 
 ## Motivation
 
-The two predominant blockchains by market capitalization, Bitcoin and Ethereum, currently support about seven and about twenty transactions per second respectively. Both have been operating at capacity in recent past despite still being utilized primarily by a userbase of early-adopter enthusiasts. Throughput is a limitation for most blockchain use cases, and throughput limitations are a fundamental limitation of distributed state machines, since every (validating) node in the network must process every transaction, store all state, and communicate with other validating nodes. Faster consensus algorithms, such as [Tendermint](https://github.com/tendermint/tendermint), may increase throughput by a large constant factor but will be unable to scale indefinitely for this reason. In order to support the transaction throughput, application diversity, and cost efficiency required to facilitate wide deployment of distributed ledger applications, execution and storage must be split across many independent consensus instances which can run concurrently.
+The two predominant blockchains by market capitalisation, Bitcoin and Ethereum, currently support about seven and about twenty transactions per second respectively. Both have been operating at capacity in recent past despite still being utilised primarily by a user-base of early-adopter enthusiasts. Throughput is a limitation for most blockchain use cases, and throughput limitations are a fundamental limitation of distributed state machines, since every (validating) node in the network must process every transaction, store all state, and communicate with other validating nodes. Faster consensus algorithms, such as [Tendermint](https://github.com/tendermint/tendermint), may increase throughput by a large constant factor but will be unable to scale indefinitely for this reason. In order to support the transaction throughput, application diversity, and cost efficiency required to facilitate wide deployment of distributed ledger applications, execution and storage must be split across many independent consensus instances which can run concurrently.
 
 One design direction is to shard a single programmable state machine across separate chains, referred to as "shards", which execute concurrently and store disjoint partitions of the state. In order to reason about safety and liveness, and in order to correctly route data and code between shards, these designs must take a "top-down approach" — constructing a particular network topology, featuring a single root ledger and a star or tree of shards, and engineering protocol rules & incentives to enforce that topology. This approach possesses advantages in simplicity and predictability, but faces hard [technical](https://medium.com/nearprotocol/the-authoritative-guide-to-blockchain-sharding-part-1-1b53ed31e060) [problems](https://medium.com/nearprotocol/unsolved-problems-in-blockchain-sharding-2327d6517f43), requires the adherence of all shards to a single validator set (or randomly elected subset thereof) and a single state machine or mutually comprehensible VM, and may face future problems in social scalability due to the general necessity of reaching global consensus on alterations to the network topology.
 
-Furthermore, any single consensus algorithm, state machine, and unit of Sybil resistance may fail to provide the requisite levels of security and versatility. Consensus instances are limited in the number of independent operators they can support, meaning that the amortized benefits from corrupting any particular operator increase as the value secured by the consensus instance increases — while the cost to corrupt the operator, which will always reflect the cheapest path (e.g. physical key exfiltration or social engineering), likely cannot scale indefinitely. A single global state machine must cater to the common denominator of a diverse application set, making it less well-suited for any particular application than a specialized state machine would be. Operators of a single consensus instance may abuse their privileged position to extract rent from applications which cannot easily elect to exit. We would rather construct a mechanism by which separate, sovereign consensus instances & state machines can safely, voluntarily interact while sharing only a minimum requisite common interface.
+Furthermore, any single consensus algorithm, state machine, and unit of Sybil resistance may fail to provide the requisite levels of security and versatility. Consensus instances are limited in the number of independent operators they can support, meaning that the amortised benefits from corrupting any particular operator increase as the value secured by the consensus instance increases — while the cost to corrupt the operator, which will always reflect the cheapest path (e.g. physical key exfiltration or social engineering), likely cannot scale indefinitely. A single global state machine must cater to the common denominator of a diverse application set, making it less well-suited for any particular application than a specialised state machine would be. Operators of a single consensus instance may abuse their privileged position to extract rent from applications which cannot easily elect to exit. We would rather construct a mechanism by which separate, sovereign consensus instances & state machines can safely, voluntarily interact while sharing only a minimum requisite common interface.
 
 The *interblockchain communication protocol* takes an orthogonal approach to a differently formulated version of the scaling & interoperability problems: enabling safe, reliable interoperation of a network of heterogeneous distributed ledgers, arranged in an unknown topology, which can diversify, develop, and rearrange independently of each other or of a particular imposed topology or state machine design. In a wide, dynamic network of interoperating chains, sporadic Byzantine faults are expected, so the protocol must also detect, mitigate, and contain the potential damage of Byzantine faults in accordance with the requirements of the applications & ledgers involved. For a longer list of design principles, see [here](./2_IBC_DESIGN_PRINCIPLES.md).
 
 To facilitate this heterogeneous interoperation, the interblockchain communication protocol takes a "bottom-up" approach, specifying the set of requirements, functions, and properties necessary to implement interoperation between two ledgers, and then specifying different ways in which multiple interoperating ledgers might be composed which preserve the requirements of higher-level protocols and occupy different points in the safety/speed tradeoff space. IBC thus presumes nothing about and requires nothing of the overall network topology, and of the implementing ledgers requires only that a known, minimal set of functions are available and properties fulfilled.
 
-IBC is an end-to-end, connection-oriented, stateful protocol for reliable, ordered, authenticated communication between modules on separate distributed ledgers. IBC implementations are expected to be co-resident with higher-level modules and protocols on the host ledger. Ledgers hosting IBC must provide a certain set of functions for consensus transcript verification and cryptographic commitment proof generation, and IBC packet relayers (off-chain processes) are expected to have access to network protocols and physical datalinks as required to read the state of one ledger and submit data to another.
+IBC is an end-to-end, connection-oriented, stateful protocol for reliable, ordered, authenticated communication between modules on separate distributed ledgers. IBC implementations are expected to be co-resident with higher-level modules and protocols on the host ledger. Ledgers hosting IBC must provide a certain set of functions for consensus transcript verification and cryptographic commitment proof generation, and IBC packet relayers (off-chain processes) are expected to have access to network protocols and physical data-links as required to read the state of one ledger and submit data to another.
 
 ## Scope
 

misc/aspell_dict

@@ -0,0 +1,51 @@
+personal_ws-1.1 en 50 
+topologies
+structs
+scalability
+ics
+pseudocode
+consensusState
+VMs
+counterpartyIdentifier
+validValue
+relayers
+YYYY
+renderer
+png
+struct
+md
+TCP
+VM
+deps
+BIP
+sharding
+blockchain
+stateful
+ICSs
+interchain
+interblockchain
+plaintext
+interoperating
+validRound
+Ethereum
+implementers
+getValue
+blockchains
+ibc
+EIP
+cryptographic
+onTimeoutPropose
+exfiltration
+UDP
+ConnectionState
+startRound
+timeoutPropose
+interoperation
+tradeoff
+relayer
+LaTeX
+Ethereum's
+th
+validator
+liveness
+Statefulness

scripts/spellcheck.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+lines=$(cat $1 | aspell -p ./misc/aspell_dict -x -d en_GB list)
+if [[ "$lines" -eq "" ]]; then
+  exit 0
+fi
+exit 1

spec.pdc

@@ -35,6 +35,14 @@ header-includes:
 
 !include spec/ics-001-ics-standard/README.md
 
+# ICS 023 - Vector Commitments
+
+!include spec/ics-023-vector-commitments/README.md
+
+# ICS 024 - Host Requirements
+
+!include spec/ics-024-host-requirements/README.md
+
 # ICS 002 - Consensus Verification
 
 !include spec/ics-002-consensus-verification/README.md
@@ -43,25 +51,13 @@ header-includes:
 
 !include spec/ics-003-connection-semantics/README.md
 
-# ICS 004 - Channel & Packet Semantics
-
-!include spec/ics-004-channel-and-packet-semantics/README.md
-
 # ICS 005 - Port Allocation
 
 !include spec/ics-005-port-allocation/README.md
 
-# ICS 018 - Relayer Algorithms
-
-!include spec/ics-018-relayer-algorithms/README.md
-
-# ICS 023 - Vector Commitments
-
-!include spec/ics-023-vector-commitments/README.md
-
-# ICS 024 - Host Requirements
+# ICS 004 - Channel & Packet Semantics
 
-!include spec/ics-024-host-requirements/README.md
+!include spec/ics-004-channel-and-packet-semantics/README.md
 
 # ICS 025 - Handler Interface
 
@@ -70,3 +66,11 @@ header-includes:
 # ICS 026 - Relayer Module
 
 !include spec/ics-026-relayer-module/README.md
+
+# ICS 018 - Relayer Algorithms
+
+!include spec/ics-018-relayer-algorithms/README.md
+
+# ICS 020 - Fungible Token Transfer
+
+!include spec/ics-020-fungible-token-transfer/README.md

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

@@ -14,18 +14,18 @@ An inter-chain standard (ICS) is a design document describing a particular proto
 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
+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 standardization process should be the primary vehicle for proposing
+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 utilize their governance processes
+that individual blockchains in the Cosmos ecosystem may utilise their governance processes
 to approve or reject inter-chain standards).
 
 ## Components
@@ -54,7 +54,7 @@ See [README.md](../../README.md) for a description of the ICS acceptance stages.
 - `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.
+           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`)
@@ -86,14 +86,14 @@ 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 utilized in this ICS or required to understand this ICS. Any terms not defined in the top-level "docs" folder must be defined here.
+- *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 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).
+- *Other Implementations* - A list of candidate or finalised implementations (external references, not inline).
 
 ### History
 
@@ -109,9 +109,9 @@ An ICS should include a copyright section waiving rights via [Apache 2.0](https:
 
 ### General
 
-ICS specifications must be written in GitHub-flavored Markdown.
+ICS specifications must be written in GitHub-flavoured 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).
+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
 

spec/ics-024-host-requirements/README.md

@@ -39,7 +39,7 @@ Variable interpolation, denoted by curly braces, MAY be used as shorthand to def
 
 ### Key/value Store
 
-Host chains MUST provide a simple key-value store interface, with three functions which behave in the standard way:
+The host chain MUST provide two separate key-value store interfaces, each with three functions which behave in the standard way:
 
 ```typescript
 type Key = string
@@ -63,6 +63,10 @@ type del = (key: Key) => void
 
 These functions MUST be permissioned to the IBC handler module (the implementation of which is described in separate standards) only, so only the IBC handler module can `set` or `delete` the keys which can be read by `get`. This can possibly be implemented as a sub-store (prefixed keyspace) of a larger key-value store used by the entire state machine.
 
+The first interface provided by the host state machine MUST write to a key-value store whose data can be externally proved with a vector commitment as defined in [ICS 23](../ics-023-vector-commitments). The second interface MAY support external proofs, but is not required to - the IBC handler will never write data to it which needs to be proved.
+
+These interfaces are referred to throughout specifications which utilize them as the `provableStore` and the `privateStore` respectively, where `get`, `set`, and `del` are called as methods, e.g. `provableStore.set('key', 'value')`.
+
 ### Consensus State Introspection
 
 Host chains MUST provide the ability to introspect their current height, with `getCurrentHeight`: