ICS-06: Solomachine Refactor

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

@@ -70,22 +70,37 @@ The `Height` of a solo machine is just a `uint64`, with the usual comparison ope
 
 ```typescript
 interface Header {
-  sequence: uint64
   timestamp: uint64
   signature: Signature
   newPublicKey: PublicKey
   newDiversifier: string
 }
 ```
 
+### Signature Verification
+
+The solomachine public key must sign over the following struct:
+
+```typescript
+interface SignBytes {
+  sequence: uint64
+  timestamp: uint64  
+  diversifier: string
+  path: []byte
+  data: []byte
+}
+```
+
 ### Misbehaviour 
 
 `Misbehaviour` for solo machines consists of a sequence and two signatures over different messages at that sequence.
 
 ```typescript
 interface SignatureAndData {
   sig: Signature
+  path: Path
   data: []byte
+  timestamp: Timestamop
 }
 
 interface Misbehaviour {
@@ -129,201 +144,174 @@ function latestClientHeight(clientState: ClientState): uint64 {
 
 ### 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.
+The solo machine client `verifyClientMessage` function checks that the currently registered public key and diversifier signed over the client message at the expected sequence. If the client message is an update, then it must be the current sequence. If the client message is misbehaviour then it must be the sequence of the misbehaviour.
 
 ```typescript
-function checkValidityAndUpdateState(
+function verifyClientMessage(
   clientState: ClientState,
-  header: Header) {
-  assert(header.sequence === clientState.consensusState.sequence)
-  assert(header.timestamp >= clientstate.consensusState.timestamp)
-  assert(checkSignature(header.newPublicKey, header.sequence, header.diversifier, header.signature))
-  clientState.consensusState.publicKey = header.newPublicKey
-  clientState.consensusState.diversifier = header.newDiversifier
-  clientState.consensusState.timestamp = header.timestamp
-  clientState.consensusState.sequence++
+  clientMsg: ClientMessage) {
+  switch typeof(ClientMessage) {
+    case Header:
+      verifyHeader(clientState, clientMessage)
+    // misbehaviour only suppported for current public key and diversifier on solomachine
+    case Misbehaviour:
+      
+  }
 }
-```
 
-### Misbehaviour predicate
-
-Any duplicate signature on different messages by the current public key freezes a solo machine client.
+function verifyHeader(
+  clientState: clientState,
+  clientMessage: clientMessage) {
+    assert(header.timestamp >= clientstate.consensusState.timestamp)
+    headerData = {
+      NewPublicKey: header.newPublicKey,
+      NewDiversifier: header.newDiversifier,
+    }
+    sigBytes = SignBytes(
+      Sequence: clientState.consensusState.sequence,
+      Timestamp: header.timestamp,
+      Diversifier: clientState.consensusState.diversifier,
+      Path: []byte{"SENTINEL_HEADER_PATH"}
+      Value: marshal(headerData)
+    )
+    assert(checkSignature(cs.consensusState.publicKey, sigBytes, header.signature))
+}
 
-```typescript
-function checkMisbehaviourAndUpdateState(
-  clientState: ClientState,
+function verifyMisbehaviour(
+  clientState: clientState,
   misbehaviour: Misbehaviour) {
-    h1 = misbehaviour.h1
-    h2 = misbehaviour.h2
+    s1 = misbehaviour.signatureOne
+    s2 = misbehaviour.signatureTwo
     pubkey = clientState.consensusState.publicKey
     diversifier = clientState.consensusState.diversifier
     timestamp = clientState.consensusState.timestamp
     // assert that timestamp could have fooled the light client
-    assert(misbehaviour.h1.signature.timestamp >= timestamp)
-    assert(misbehaviour.h2.signature.timestamp >= timestamp)
-    // assert that signature data is different
-    assert(misbehaviour.h1.signature.data !== misbehaviour.h2.signature.data)
-    // assert that the signatures validate
-    assert(checkSignature(pubkey, misbehaviour.sequence, diversifier, misbehaviour.h1.signature.data))
-    assert(checkSignature(pubkey, misbehaviour.sequence, diversifier, misbehaviour.h2.signature.data))
-    // freeze the client
-    clientState.frozen = true
+    assert(misbehaviour.s1.timestamp >= timestamp)
+    assert(misbehaviour.s2.timestamp >= timestamp)
+    // assert that the signatures validate and that they are different
+    sigBytes1 = SignBytes(
+      Sequence: misbehaviour.sequence,
+      Timestamp: s1.timestamp,
+      Diversifier: cs.consensusState.diversifier,
+      Path: s1.path,
+      Data: s1.data
+    )
+    sigBytes2 = SignBytes(
+      Sequence: misbehaviour.sequence,
+      Timestamp: s2.timestamp,
+      Diversifier: cs.consensusState.diversifier,
+      Path: s2.path,
+      Data: s2,.data
+    )
+    assert(sigBytes1 != sigBytes2)
+    assert(checkSignature(pubkey, sigBytes1, clientState.consensusState.publicKey))
+    assert(checkSignature(pubkey, sigBytes2, clientState.consensusState.publicKey))
 }
 ```
 
-### State verification functions
+### Misbehaviour predicate
 
-All solo machine client state verification functions simply check a signature, which must be provided by the solo machine.
-
-Note that value concatenation should be implemented in a state-machine-specific escaped fashion.
+Since misbehaviour is checked in `verifyClientMessage`, if the client message is of type `Misbehaviour` then we return true
 
 ```typescript
-function verifyClientState(
+function checkForMisbehaviour(
   clientState: ClientState,
-  height: uint64,
-  prefix: CommitmentPrefix,
-  proof: CommitmentProof,
-  clientIdentifier: Identifier,
-  counterpartyClientState: ClientState) {
-    path = applyPrefix(prefix, "clients/{clientIdentifier}/clientState")
-    // ICS 003 will not increment the proof height after connection verification
-    // the solo machine client must increment the proof height to ensure it matches 
-    // the expected sequence used in the signature
-    abortTransactionUnless(height + 1 == clientState.consensusState.sequence)
-    abortTransactionUnless(!clientState.frozen)
-    abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + counterpartyClientState
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
-    clientState.consensusState.sequence++
-    clientState.consensusState.timestamp = proof.timestamp
+  clientMessage: ClientMessage) => bool {
+    switch typeof(ClientMessage) {
+    case Misbehaviour:
+      return true
+    }
+    return false
 }
+```
 
-function verifyClientConsensusState(
-  clientState: ClientState,
-  height: uint64,
-  prefix: CommitmentPrefix,
-  proof: CommitmentProof,
-  clientIdentifier: Identifier,
-  consensusStateHeight: uint64,
-  consensusState: ConsensusState) {
-    path = applyPrefix(prefix, "clients/{clientIdentifier}/consensusState/{consensusStateHeight}")
-    // ICS 003 will not increment the proof height after connection or client state verification
-    // the solo machine client must increment the proof height by 2 to ensure it matches 
-    // the expected sequence used in the signature
-    abortTransactionUnless(height + 2 == clientState.consensusState.sequence)
-    abortTransactionUnless(!clientState.frozen)
-    abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + consensusState
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
-    clientState.consensusState.sequence++
-    clientState.consensusState.timestamp = proof.timestamp
-}
+### Update Functions
 
-function verifyConnectionState(
-  clientState: ClientState,
-  height: uint64,
-  prefix: CommitmentPrefix,
-  proof: CommitmentProof,
-  connectionIdentifier: Identifier,
-  connectionEnd: ConnectionEnd) {
-    path = applyPrefix(prefix, "connection/{connectionIdentifier}")
-    abortTransactionUnless(height == clientState.consensusState.sequence)
-    abortTransactionUnless(!clientState.frozen)
-    abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + connectionEnd
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
-    clientState.consensusState.sequence++
-    clientState.consensusState.timestamp = proof.timestamp
-}
+`UpdateState` updates the function for a regular update:
 
-function verifyChannelState(
+```typescript
+function updateState(
   clientState: ClientState,
-  height: uint64,
-  prefix: CommitmentPrefix,
-  proof: CommitmentProof,
-  portIdentifier: Identifier,
-  channelIdentifier: Identifier,
-  channelEnd: ChannelEnd) {
-    path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}")
-    abortTransactionUnless(height == clientState.consensusState.sequence)
-    abortTransactionUnless(!clientState.frozen)
-    abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + channelEnd
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
+  clientMessage: ClientMessage) {
+    clientState.consensusState.publicKey = header.newPublicKey
+    clientState.consensusState.diversifier = header.newDiversifier
+    clientState.consensusState.timestamp = header.timestamp
     clientState.consensusState.sequence++
-    clientState.consensusState.timestamp = proof.timestamp
 }
+```
 
-function verifyPacketData(
-  clientState: ClientState,
-  height: uint64,
-  prefix: CommitmentPrefix,
-  proof: CommitmentProof,
-  portIdentifier: Identifier,
-  channelIdentifier: Identifier,
-  sequence: uint64,
-  data: bytes) {
-    path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/packets/{sequence}")
-    abortTransactionUnless(height == clientState.consensusState.sequence)
-    abortTransactionUnless(!clientState.frozen)
-    abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + data
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
-    clientState.consensusState.sequence++
-    clientState.consensusState.timestamp = proof.timestamp
-}
+`UpdateStateOnMisbehaviour` updates the function after receving valid misbehaviour:
 
-function verifyPacketAcknowledgement(
+```typescript
+function updateStateOnMisbehaviour(
   clientState: ClientState,
-  height: uint64,
-  prefix: CommitmentPrefix,
-  proof: CommitmentProof,
-  portIdentifier: Identifier,
-  channelIdentifier: Identifier,
-  sequence: uint64,
-  acknowledgement: bytes) {
-    path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/acknowledgements/{sequence}")
-    abortTransactionUnless(height == clientState.consensusState.sequence)
-    abortTransactionUnless(!clientState.frozen)
-    abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + acknowledgement
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
-    clientState.consensusState.sequence++
-    clientState.consensusState.timestamp = proof.timestamp
+  clientMessage: ClientMessage) {
+    // freeze the client
+    clientState.frozen = true
 }
+```
+
+### State verification functions
 
-function verifyPacketReceiptAbsence(
+All solo machine client state verification functions simply check a signature, which must be provided by the solo machine.
+
+Note that value concatenation should be implemented in a state-machine-specific escaped fashion.
+
+```typescript
+function verifyMembership(
   clientState: ClientState,
+  // provided height is unnecessary for solomachine
+  // since clientState maintains the expected sequence
   height: uint64,
-  prefix: CommitmentPrefix,
+  // delayPeriod is unsupported on solomachines
+  // thus these fields are ignored
+  delayTimePeriod: uint64,
+  delayBlockPeriod: uint64,
   proof: CommitmentProof,
-  portIdentifier: Identifier,
-  channelIdentifier: Identifier,
-  sequence: uint64) {
-    path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/receipts/{sequence}")
-    abortTransactionUnless(height == clientState.consensusState.sequence)
+  path: CommitmentPath,
+  value: []byte) {
+    // the expected sequence used in the signature
     abortTransactionUnless(!clientState.frozen)
     abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path
-    assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
+    sigBytes = SignBytes(
+      Sequence: clientState.consensusState.sequence,
+      Timestamp: proof.timestamp,
+      Diversifier: clientState.consensusState.diversifier,
+      path: CommitmentPath.String(),
+      data: value,
+    )
+    assert(checkSignature(clientState.consensusState.pubKey, sigBytes, proof.sig))
+
+    // increment sequence on each verification to provide
+    // replay protection
     clientState.consensusState.sequence++
     clientState.consensusState.timestamp = proof.timestamp
 }
 
-function verifyNextSequenceRecv(
+function verifyNonMembership(
   clientState: ClientState,
+  // provided height is unnecessary for solomachine
+  // since clientState maintains the expected sequence
   height: uint64,
-  prefix: CommitmentPrefix,
+  // delayPeriod is unsupported on solomachines
+  // thus these fields are ignored
+  delayTimePeriod: uint64,
+  delayBlockPeriod: uint64,
   proof: CommitmentProof,
-  portIdentifier: Identifier,
-  channelIdentifier: Identifier,
-  nextSequenceRecv: uint64) {
-    path = applyPrefix(prefix, "ports/{portIdentifier}/channels/{channelIdentifier}/nextSequenceRecv")
-    abortTransactionUnless(height == clientState.consensusState.sequence)
+  path: CommitmentPath) {
     abortTransactionUnless(!clientState.frozen)
     abortTransactionUnless(proof.timestamp >= clientState.consensusState.timestamp)
-    value = clientState.consensusState.sequence + clientState.consensusState.diversifier + proof.timestamp + path + nextSequenceRecv
+    sigBytes = SignBytes(
+      Sequence: clientState.consensusState.sequence,
+      Timestamp: proof.timestamp,
+      Diversifier: clientState.consensusState.diversifier,
+      path: CommitmentPath.String(),
+      data: nil,
+    )
     assert(checkSignature(clientState.consensusState.pubKey, value, proof.sig))
+
+    // increment sequence on each verification to provide
+    // replay protection
     clientState.consensusState.sequence++
     clientState.consensusState.timestamp = proof.timestamp
 }
@@ -353,6 +341,7 @@ None at present.
 
 December 9th, 2019 - Initial version
 December 17th, 2019 - Final first draft
+August 15th, 2022 - Changes to align with 02-client-refactor in [\#813](https://github.com/cosmos/ibc/pull/813)
 
 ## Copyright