Update paths for consistency; revise ICS 2 for client type sub-specs

misc/aspell_dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 544 
+personal_ws-1.1 en 545 
 ABCI
 ABI
 Agoric
@@ -214,6 +214,7 @@ connectionPath
 conns
 consensusHeight
 consensusState
+consensusStateHeight
 consensusStateKey
 consensusStatePath
 consensusStates

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

@@ -8,7 +8,7 @@ requires: 23, 24
 required-by: 3
 author: Juwoon Yun <joon@tendermint.com>, Christopher Goes <cwgoes@tendermint.com>
 created: 2019-02-25
-modified: 2019-08-25
+modified: 2020-01-13
 ---
 
 ## Synopsis
@@ -253,10 +253,18 @@ but they must expose this common set of query functions to the IBC handler.
 type ClientState = bytes
 ```
 
-Client types must also define a method to initialize a client state with a provided consensus state:
+Client types MUST define a method to initialize a client state with a provided consensus state, writing to state as appropriate.
 
 ```typescript
-type initialize = (state: ConsensusState) => ClientState
+type initialize = (state: ConsensusState) => ()
+```
+
+Client types MUST define a method to fetch the current height (height of the most recent validated header).
+
+```typescript
+type latestHeight = (
+  clientState: ClientState)
+  => uint64
 ```
 
 #### CommitmentProof
@@ -280,6 +288,7 @@ type verifyClientConsensusState = (
   height: uint64,
   proof: CommitmentProof,
   clientIdentifier: Identifier,
+  consensusStateHeight: uint64,
   consensusState: ConsensusState)
   => boolean
 ```
@@ -420,34 +429,6 @@ type validateClientIdentifier = (id: Identifier) => boolean
 
 If not provided, the default `validateClientIdentifier` will always return `true`. 
 
-#### Path-space
-
-`clientStatePath` takes an `Identifier` and returns a `Path` under which to store a particular client state.
-
-```typescript
-function clientStatePath(id: Identifier): Path {
-    return "clients/{id}/state"
-}
-```
-
-`clientTypePath` takes an `Identifier` and returns `Path` under which to store the type of a particular client.
-
-```typescript
-function clientTypePath(id: Identifier): Path {
-    return "clients/{id}/type"
-}
-```
-
-Consensus states MUST be stored separately so that they can be independently verified.
-
-`consensusStatePath` takes an `Identifier` and returns a `Path` under which to store the consensus state of a client.
-
-```typescript
-function consensusStatePath(id: Identifier): Path {
-    return "clients/{id}/consensusState"
-}
-```
-
 ##### Utilising past roots
 
 To avoid race conditions between client updates (which change the state root) and proof-carrying
@@ -468,28 +449,15 @@ function createClient(
     abortTransactionUnless(validateClientIdentifier(id))
     abortTransactionUnless(privateStore.get(clientStatePath(id)) === null)
     abortSystemUnless(provableStore.get(clientTypePath(id)) === null)
-    clientState = clientType.initialize(consensusState)
-    privateStore.set(clientStatePath(id), clientState)
+    clientType.initialise(consensusState)
     provableStore.set(clientTypePath(id), clientType)
 }
 ```
 
 #### Query
 
-Client consensus state and client internal state can be queried by identifier. The returned
-client state must fulfil an interface allowing membership / non-membership verification.
-
-```typescript
-function queryClientConsensusState(id: Identifier): ConsensusState {
-    return provableStore.get(consensusStatePath(id))
-}
-```
-
-```typescript
-function queryClient(id: Identifier): ClientState {
-    return privateStore.get(clientStatePath(id))
-}
-```
+Client consensus state and client internal state can be queried by identifier, but
+the specific paths which must be queried are defined by each client type.
 
 #### Update
 
@@ -576,12 +544,13 @@ function commit(
 }
 
 // initialisation function defined by the client type
-function initialize(consensusState: ConsensusState): ClientState {
-  return {
+function initialize(consensusState: ConsensusState): () {
+  clientState = {
     frozen: false,
     pastPublicKeys: Set.singleton(consensusState.publicKey),
     verifiedRoots: Map.empty()
   }
+  privateStore.set(identifier, clientState)
 }
 
 // validity predicate function defined by the client type
@@ -605,7 +574,7 @@ function verifyClientConsensusState(
   proof: CommitmentProof,
   clientIdentifier: Identifier,
   consensusState: ConsensusState) {
-    path = applyPrefix(prefix, "clients/{clientIdentifier}/consensusState")
+    path = applyPrefix(prefix, "clients/{clientIdentifier}/consensusStates/{height}")
     abortTransactionUnless(!clientState.frozen)
     return clientState.verifiedRoots[sequence].verifyMembership(path, consensusState, proof)
 }
@@ -617,7 +586,7 @@ function verifyConnectionState(
   proof: CommitmentProof,
   connectionIdentifier: Identifier,
   connectionEnd: ConnectionEnd) {
-    path = applyPrefix(prefix, "connection/{connectionIdentifier}")
+    path = applyPrefix(prefix, "connections/{connectionIdentifier}")
     abortTransactionUnless(!clientState.frozen)
     return clientState.verifiedRoots[sequence].verifyMembership(path, connectionEnd, proof)
 }
@@ -733,6 +702,8 @@ May 29, 2019 - Various revisions, notably multiple commitment-roots
 
 Aug 15, 2019 - Major rework for clarity around client interface
 
+Jan 13, 2020 - Revisions for client type separation & path alterations
+
 ## Copyright
 
 All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).

spec/ics-003-connection-semantics/README.md

@@ -145,9 +145,10 @@ function verifyClientConsensusState(
   height: uint64,
   proof: CommitmentProof,
   clientIdentifier: Identifier,
+  consensusStateHeight: uint64,
   consensusState: ConsensusState) {
     client = queryClient(connection.clientIdentifier)
-    return client.verifyClientConsensusState(connection, height, connection.counterpartyPrefix, proof, clientIdentifier, consensusState)
+    return client.verifyClientConsensusState(connection, height, connection.counterpartyPrefix, proof, clientIdentifier, consensusStateHeight, consensusState)
 }
 
 function verifyConnectionState(
@@ -324,7 +325,8 @@ function connOpenTry(
     connection = ConnectionEnd{state, counterpartyConnectionIdentifier, counterpartyPrefix,
                                clientIdentifier, counterpartyClientIdentifier, version}
     abortTransactionUnless(connection.verifyConnectionState(proofHeight, proofInit, counterpartyConnectionIdentifier, expected))
-    abortTransactionUnless(connection.verifyClientConsensusState(proofHeight, proofConsensus, counterpartyClientIdentifier, expectedConsensusState))
+    abortTransactionUnless(connection.verifyClientConsensusState(
+      proofHeight, proofConsensus, counterpartyClientIdentifier, consensusHeight, expectedConsensusState))
     previous = provableStore.get(connectionPath(desiredIdentifier))
     abortTransactionUnless(
       (previous === null) ||
@@ -359,7 +361,8 @@ function connOpenAck(
                              connection.counterpartyClientIdentifier, connection.clientIdentifier,
                              version}
     abortTransactionUnless(connection.verifyConnectionState(proofHeight, proofTry, connection.counterpartyConnectionIdentifier, expected))
-    abortTransactionUnless(connection.verifyClientConsensusState(proofHeight, proofConsensus, connection.counterpartyClientIdentifier, expectedConsensusState))
+    abortTransactionUnless(connection.verifyClientConsensusState(
+      proofHeight, proofConsensus, connection.counterpartyClientIdentifier, consensusHeight, expectedConsensusState))
     connection.state = OPEN
     abortTransactionUnless(getCompatibleVersions().indexOf(version) !== -1)
     connection.version = version

spec/ics-004-channel-and-packet-semantics/README.md

@@ -521,8 +521,9 @@ function sendPacket(packet: Packet) {
     abortTransactionUnless(connection !== null)
     abortTransactionUnless(connection.state !== CLOSED)
 
-    consensusState = provableStore.get(consensusStatePath(connection.clientIdentifier))
-    abortTransactionUnless(consensusState.getHeight() < packet.timeoutHeight)
+    // sanity-check that the timeout height hasn't already passed in our local client tracking the receiving chain
+    latestHeight = provableStore.get(clientPath(connection.clientIdentifier)).latestHeight()
+    abortTransactionUnless(latestHeight < packet.timeoutHeight)
 
     nextSequenceSend = provableStore.get(nextSequenceSendPath(packet.sourcePort, packet.sourceChannel))
     abortTransactionUnless(packet.sequence === nextSequenceSend)

spec/ics-006-solo-machine-client/README.md

@@ -90,6 +90,14 @@ function initialise(consensusState: ConsensusState): ClientState {
 }
 ```
 
+The solo machine client `latestHeight` function returns the latest sequence.
+
+```typescript
+function latestHeight(clientState: ClientState): uint64 {
+  return clientState.consensusState.sequence
+}
+```
+
 ### Validity predicate
 
 The solo machine client `checkValidityAndUpdateState` function checks that the currently registered public key has signed over the new public key with the correct sequence.
@@ -134,8 +142,9 @@ function verifyClientConsensusState(
   prefix: CommitmentPrefix,
   proof: CommitmentProof,
   clientIdentifier: Identifier,
+  consensusStateHeight: uint64,
   consensusState: ConsensusState) {
-    path = applyPrefix(prefix, "clients/{clientIdentifier}/consensusState")
+    path = applyPrefix(prefix, "clients/{clientIdentifier}/consensusState/{consensusStateHeight}")
     abortTransactionUnless(!clientState.frozen)
     value = clientState.consensusState.sequence + path + consensusState
     assert(checkSignature(clientState.consensusState.pubKey, value, proof))

spec/ics-007-tendermint-client/README.md

@@ -87,15 +87,23 @@ interface Evidence {
 Tendermint client initialisation requires a (subjectively chosen) latest consensus state, including the full validator set.
 
 ```typescript
-function initialize(consensusState: ConsensusState, validatorSet: List<Pair<Address, uint64>>, latestHeight: uint64): ClientState {
+function initialize(consensusState: ConsensusState, validatorSet: List<Pair<Address, uint64>>, height: uint64): ClientState {
   return ClientState{
     validatorSet,
-    latestHeight,
+    latestHeight: height,
     pastHeaders: Map.singleton(latestHeight, consensusState)
   }
 }
 ```
 
+The Tendermint client `latestHeight` function returns the latest stored height, which is updated every time a new (more recent) header is validated.
+
+```typescript
+function latestHeight(clientState: ClientState): uint64 {
+  return clientState.latestHeight
+}
+```
+
 ### Validity predicate
 
 Tendermint client validity checking uses the bisection algorithm described in the [Tendermint spec](https://github.com/tendermint/spec/blob/master/spec/consensus/light-client.md). If the provided header is valid, the client state is updated & the newly verified commitment written to the store.
@@ -112,7 +120,7 @@ function checkValidityAndUpdateState(
     clientState.latestHeight = header.height
     // create recorded consensus state, save it
     consensusState = ConsensusState{validatorSet.hash(), header.commitmentRoot}
-    set("consensusStates/{identifier}/{header.height}", consensusState)
+    set("clients/{identifier}/consensusStates/{header.height}", consensusState)
     // save the client
     set("clients/{identifier}", clientState)
 }
@@ -131,7 +139,7 @@ function checkMisbehaviourAndUpdateState(
     // assert that the commitments are different
     assert(h1.commitmentRoot !== h2.commitmentRoot)
     // fetch the previously verified commitment root & validator set hash
-    consensusState = get("consensusStates/{identifier}/{evidence.fromHeight}")
+    consensusState = get("clients/{identifier}/consensusStates/{evidence.fromHeight}")
     // check that the validator set matches
     assert(consensusState.validatorSetHash === evidence.fromValidatorSet.hash())
     // check if the light client "would have been fooled"
@@ -157,14 +165,15 @@ function verifyClientConsensusState(
   prefix: CommitmentPrefix,
   proof: CommitmentProof,
   clientIdentifier: Identifier,
+  consensusStateHeight: uint64,
   consensusState: ConsensusState) {
-    path = applyPrefix(prefix, "consensusStates/{clientIdentifier}")
+    path = applyPrefix(prefix, "clients/{clientIdentifier}/consensusState/{consensusStateHeight}")
     // check that the client is at a sufficient height
     assert(clientState.latestHeight >= height)
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that the provided consensus state has been stored
     assert(root.verifyMembership(path, consensusState, proof))
 }
@@ -176,13 +185,13 @@ function verifyConnectionState(
   proof: CommitmentProof,
   connectionIdentifier: Identifier,
   connectionEnd: ConnectionEnd) {
-    path = applyPrefix(prefix, "connection/{connectionIdentifier}")
+    path = applyPrefix(prefix, "connections/{connectionIdentifier}")
     // check that the client is at a sufficient height
     assert(clientState.latestHeight >= height)
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that the provided connection end has been stored
     assert(root.verifyMembership(path, connectionEnd, proof))
 }
@@ -201,7 +210,7 @@ function verifyChannelState(
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that the provided channel end has been stored
     assert(root.verifyMembership(path, channelEnd, proof))
 }
@@ -221,7 +230,7 @@ function verifyPacketCommitment(
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that the provided commitment has been stored
     assert(root.verifyMembership(path, commitment, proof))
 }
@@ -241,7 +250,7 @@ function verifyPacketAcknowledgement(
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that the provided acknowledgement has been stored
     assert(root.verifyMembership(path, acknowledgement, proof))
 }
@@ -260,7 +269,7 @@ function verifyPacketAcknowledgementAbsence(
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that no acknowledgement has been stored
     assert(root.verifyNonMembership(path, proof))
 }
@@ -279,7 +288,7 @@ function verifyNextSequenceRecv(
     // check that the client is unfrozen or frozen at a higher height
     assert(clientState.frozenHeight === null || clientState.frozenHeight > height)
     // fetch the previously verified commitment root & verify membership
-    root = get("consensusStates/{identifier}/{height}")
+    root = get("clients/{identifier}/consensusStates/{height}")
     // verify that the nextSequenceRecv is as claimed
     assert(root.verifyMembership(path, nextSequenceRecv, proof))
 }

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

@@ -99,11 +99,14 @@ Parts of the private store MAY safely be used for other purposes as long as the
 Keys used in the private store MAY safely vary as long as there exists a bipartite mapping between the key formats defined herein and the ones
 actually used in the private store implementation.
 
+Note that the client-related paths listed below reflect the Tendermint client as defined in [ICS 7](../ics-007-tendermint-client) and may vary for other client types.
+
 | Store          | Path format                                                                    | Value type        | Defined in |
 | -------------- | ------------------------------------------------------------------------------ | ----------------- | ---------------------- |
-| privateStore   | "clients/{identifier}"                                                         | ClientState       | [ICS 2](../ics-002-client-semantics) |
-| provableStore  | "clients/{identifier}/consensusState"                                          | ConsensusState    | [ICS 2](../ics-002-client-semantics) |
 | provableStore  | "clients/{identifier}/type"                                                    | ClientType        | [ICS 2](../ics-002-client-semantics) |
+| privateStore   | "clients/{identifier}"                                                         | ClientState       | [ICS 2](../ics-007-tendermint-client) |
+| provableStore  | "clients/{identifier}/consensusStates/{height}"                                | ConsensusState    | [ICS 7](../ics-007-tendermint-client) |
+| privateStore   | "clients/{identifier}/connections                                              | []Identifier      | [ICS 3](../ics-003-connection-semantics) |
 | provableStore  | "connections/{identifier}"                                                     | ConnectionEnd     | [ICS 3](../ics-003-connection-semantics) |
 | privateStore   | "ports/{identifier}"                                                           | CapabilityKey     | [ICS 5](../ics-005-port-allocation) |
 | provableStore  | "ports/{identifier}/channels/{identifier}"                                     | ChannelEnd        | [ICS 4](../ics-004-channel-and-packet-semantics) |