Merge PR cosmos#235: More minor fixes from review

* ibc/3: external relayer process

* ics24: privateStore/provableStore intro

* ics2: some code fixes

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

Author: ebuchman

ibc/3_IBC_TERMINOLOGY.md

@@ -86,7 +86,7 @@ A *handshake* is a particular class of sub-protocol involving multiple datagrams
 
 Sub-protocols are defined as a set of datagram kinds and functions which must be implemented by the IBC handler module of the implementing blockchain.
 
-Datagrams must be relayed between chains by an external process. This process is assumed to behave in an arbitrary manner — no safety properties are dependent on its behaviour, although progress is generally dependent on the existence of at least one correct relayer process.
+Datagrams must be relayed between chains by an external relayer process. This relayer process is assumed to behave in an arbitrary manner — no safety properties are dependent on its behaviour, although progress is generally dependent on the existence of at least one correct relayer process.
 
 IBC sub-protocols are reasoned about as interactions between two chains `A` and `B` — there is no prior distinction between these two chains and they are assumed to be executing the same, correct IBC protocol. `A` is simply by convention the chain which goes first in the sub-protocol and `B` the chain which goes second. Protocol definitions should generally avoid including `A` and `B` in variable names to avoid confusion (as the chains themselves do not know whether they are `A` or `B` in the protocol).
 

spec/ics-002-client-semantics/README.md

@@ -185,7 +185,7 @@ but they must expose this common set of query functions to the IBC handler.
 type ClientState = bytes
 ```
 
-Client types must also define a function to initialize a client state with a provided consensus state:
+Client types must also define a method to initialize a client state with a provided consensus state:
 
 ```typescript
 type initialize = (ConsensusState) => ClientState
@@ -274,7 +274,7 @@ function createClient(
   privateStore.set(clientStatePath(id), clientState)
 }
   assert(!client.frozen)
-  return client.verifiedRoots[height].verifyNonMembership(path, proof)
+  return clientState.verifiedRoots[height].verifyNonMembership(path, proof)
 ```
 
 #### Query
@@ -374,7 +374,7 @@ function commit(
   sequence: uint64,
   newPublicKey: Maybe<PublicKey>): Header {
   signature = privateKey.sign(root, sequence, newPublicKey)
-  header = Header{sequence, root, signature}
+  header = Header{sequence, root, signature, newPublicKey}
   return header
 }
 
@@ -405,7 +405,7 @@ function verifyMembership(
   path: Path,
   value: Value) {
   assert(!client.frozen)
-  return client.verifiedRoots[sequence].verifyMembership(path, value, proof)
+  return clientState.verifiedRoots[sequence].verifyMembership(path, value, proof)
 }
 
 // state non-membership function defined by the client type
@@ -415,7 +415,7 @@ function verifyNonMembership(
   proof: CommitmentProof,
   path: Path) {
   assert(!client.frozen)
-  return client.verifiedRoots[sequence].verifyNonMembership(path, proof)
+  return clientState.verifiedRoots[sequence].verifyNonMembership(path, proof)
 }
 
 // misbehaviour verification function defined by the client type

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

@@ -45,7 +45,8 @@ Variable interpolation, denoted by curly braces, MAY be used as shorthand to def
 
 ### Key/value Store
 
-The host state machine MUST provide two separate key-value store interfaces, each with three functions which behave in the standard way:
+The host state machine MUST provide a key-value store interface 
+with three functions that behave in the standard way:
 
 ```typescript
 type Path = string
@@ -69,11 +70,20 @@ type delete = (path: Path) => 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 paths which can be read by `get`. This can possibly be implemented as a sub-store (prefixed key-space) 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.
+Host state machines must provide two instances of this interface - 
+a `provableStore` for storage read by (i.e. proven to) other chains,
+and a `privateStore` for storage local to the host.
 
-These interfaces are referred to throughout specifications which utilise them as the `provableStore` and the `privateStore` respectively, where `get`, `set`, and `delete` are called as methods, e.g. `provableStore.set('path', 'value')`.
+The `provableStore`:
 
-The `provableStore` and `privateStore` differ also in their encoding restrictions. The `provableStore` MUST use canonical data structure encodings provided in these specifications as proto3 files, since values stored in the `provableStore` must be comprehensible to other machines implementing IBC.
+- 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). 
+- MUST use canonical data structure encodings provided in these specifications as proto3 files
+
+The `privateStore`:
+
+- MAY support external proofs, but is not required to - the IBC handler will never write data to it which needs to be proved.
+- MAY use canonical proto3 data structures, but is not required to - it can use
+  whatever format is preferred by the application environment.
 
 > Note: any key-value store interface which provides these methods & properties is sufficient for IBC. Host state machines may implement "proxy stores" with underlying storage models which do not directly match the path & value pairs set and retrieved through the store interface — paths could be grouped into buckets & values stored in pages which could be proved in a single commitment, path-spaces could be remapped non-contiguously in some bijective manner, etc — as long as `get`, `set`, and `delete` behave as expected and other machines can verify commitment proofs of path & value pairs (or their absence) in the provable store.