update solo machine specs (#7512)

* update solo machine specs

* update concepts

* self review fixes

* Apply suggestions from code review

* add note on upgarding solo machines

Co-authored-by: Federico Kunze <31522760+fedekunze@users.noreply.github.com>

x/ibc/core/spec/README.md

@@ -28,8 +28,8 @@ For the general specification please refer to the [Interchain Standards](https:/
 
 As stated above, the IBC implementation on the Cosmos SDK introduces some changes
 to the general specification, in order to avoid code duplication and to take
-advantage of the SDK architectural components such as the `AnteHandler` and
-transaction routing through `Handlers`.
+advantage of the SDK architectural components such as the transaction routing 
+through `Handlers`.
 
 ### Interchain Standards reference
 

x/ibc/light-clients/06-solomachine/spec/01_concepts.md

@@ -4,13 +4,46 @@ order: 1
 
 # Concepts
 
+## Client State
+
+The `ClientState` for a solo machine light client stores the latest sequence, the frozen sequence,
+the latest consensus state, and client flag indicating if the client should be allowed to be updated
+after a governance proposal. 
+
+If the client is not frozen then the frozen sequence is 0. 
+
+## Consensus State
+
+The consensus states stores the public key, diversifier, and timestamp of the solo machine light client. 
+
+The diversifier is used to prevent accidental misbehaviour if the same public key is used across
+different chains with the same client identifier. It should be unique to the chain the light client
+is used on. 
+
+## Public Key
+
+The public key can be a single public key or a multi-signature public key. The public key type used
+must fulfill the tendermint public key interface (this will become the SDK public key interface in the
+near future). The public key must be registered on the application codec otherwise encoding/decoding 
+errors will arise. The public key stored in the consensus state is represented as a protobuf `Any`. 
+This allows for flexibility in what other public key types can be supported in the future. 
+
+## Counterparty Verification
+
+The solo machine light client can verify counterparty client state, consensus state, connection state,
+channel state, packet commitments, packet acknowledgements, packet receipt absence, 
+and the next sequence receive. At the end of each successful verification call the light
+client sequence number will be incremented. 
+
+Successful verification requires the current public key to sign over the proof.
+
 ## Proofs
 
 A solo machine proof should verify that the solomachine public key signed
 over some specified data. The format for generating marshaled proofs for
 the SDK's implementation of solo machine is as follows:
 
-Construct the data using the associated protobuf definition and marshal it.
+1. Construct the data using the associated protobuf definition and marshal it.
 
 For example:
 
@@ -23,7 +56,10 @@ data := &ClientStateData{
 dataBz, err := cdc.MarshalBinaryBare(data)
 ```
 
-Construct the `SignBytes` and marshal it.
+The helper functions `...DataBytes()` in [proofs.go](../types/proofs.go) handle this
+functionality. 
+
+2. Construct the `SignBytes` and marshal it.
 
 For example:
 
@@ -39,12 +75,12 @@ signBytes := &SignBytes{
 signBz, err := cdc.MarshalBinaryBare(signBytes)
 ```
 
-The helper functions in [proofs.go](../types/proofs.go) handle the above actions.
-The `DataType` field is used to disambiguate what type of data was signed because
-of potential proto encoding overlap.
+The helper functions `...SignBytes()` in [proofs.go](../types/proofs.go) handle this functionality.
+The `DataType` field is used to disambiguate what type of data was signed to prevent potential 
+proto encoding overlap.
 
-Sign the sign bytes. Embed the signatures into either `SingleSignatureData` or
-`MultiSignatureData`. Convert the `SignatureData` to proto and marshal it
+3. Sign the sign bytes. Embed the signatures into either `SingleSignatureData` or `MultiSignatureData`.
+Convert the `SignatureData` to proto and marshal it.
 
 For example:
 
@@ -58,8 +94,8 @@ protoSigData := signing.SignatureDataToProto(sigData)
 bz, err := cdc.MarshalBinaryBare(protoSigData)
 ```
 
-Construct a `TimestampedSignatureData` and marshal it. The marshaled result can be
-passed in as the proof parameter to the verification functions.
+4. Construct a `TimestampedSignatureData` and marshal it. The marshaled result can be passed in 
+as the proof parameter to the verification functions.
 
 For example:
 
@@ -71,3 +107,54 @@ timestampedSignatureData := &types.TimestampedSignatureData{
 
 proof, err := cdc.MarshalBinaryBare(timestampedSignatureData)
 ```
+
+## Updates By Header
+
+An update by a header will only succeed if:
+
+- the header provided is parseable to solo machine header
+- the header sequence matches the current sequence
+- the header timestamp is greater than or equal to the consensus state timestamp
+- the currently registered public key generated the proof
+
+If the update is successful:
+
+- the public key is updated
+- the diversifier is updated
+- the timestamp is updated
+- the sequence is incremented by 1
+- the new consensus state is set in the client state 
+
+## Updates By Proposal
+
+An update by a governance proposal will only succeed if:
+
+- the header provided is parseable to solo machine header
+- the `AllowUpdateAfterProposal` client parameter is set to `true`
+- the new header public key does not equal the consensus state public key
+
+If the update is successful:
+
+- the public key is updated
+- the diversifier is updated
+- the timestamp is updated
+- the sequence is updated
+- the new consensus state is set in the client state 
+- the client is unfrozen (if it was previously frozen)
+
+## Misbehaviour
+
+Misbehaviour handling will only succeed if:
+
+- the misbehaviour provided is parseable to solo machine misbehaviour
+- the client is not already frozen
+- the current public key signed over two unique data messages at the same sequence and diversifier. 
+
+If the misbehaviour is successfully processed:
+
+- the client is frozen by setting the frozen sequence to the misbehaviour sequence
+
+## Upgrades
+
+Upgrades to solo machine light clients are not supported since an entirely different type of 
+public key can be set using normal client updates.

x/ibc/light-clients/06-solomachine/spec/02_state.md

@@ -0,0 +1,12 @@
+<!--
+order: 2
+-->
+
+# State
+
+The solo machine light client will only store consensus states for each update by a header
+or a governance proposal. The latest client state is also maintained in the store.
+
+These values can be found under the light client paths defined in the IBC 
+[core store specs](../../../core/spec/02_state.md).
+

x/ibc/light-clients/06-solomachine/spec/03_state_transitions.md

@@ -0,0 +1,42 @@
+<!--
+order: 3
+-->
+
+# State Transitions
+
+## Client State Verification Functions
+
+Successful state verification by a solo machine light client will result in:
+
+- the sequence being incremented by 1.
+
+## Update By Header
+
+A successful update of a solo machine light client by a header will result in:
+
+- the public key being updated to the new public key provided by the header. 
+- the diversifier being updated to the new diviersifier provided by the header.
+- the timestamp being updated to the new timestamp provided by the header.
+- the sequence being incremented by 1
+- the consensus state being updated (consensus state stores the public key, diversifier, and timestamp)
+
+## Update By Governance Proposal
+
+A successful update of a solo machine light client by a governance proposal will result in:
+
+- the public key being updated to the new public key provided by the header. 
+- the diversifier being updated to the new diviersifier provided by the header.
+- the timestamp being updated to the new timestamp provided by the header.
+- the sequence being set to the new sequence provided by the header.
+- the consensus state being updated (consensus state stores the public key, diversifier, and timestamp)
+- the frozen sequence being set to zero (client is unfrozen if it was previously frozen).
+
+## Upgrade
+
+Client udgrades are not supported for the solo machine light client. No state transition occurs.
+
+## Misbehaviour
+
+Successful misbehaviour processing of a solo machine light client will result in:
+
+- the frozen sequence being set to the sequence the misbehaviour occurred at

x/ibc/light-clients/06-solomachine/spec/04_messages.md

@@ -0,0 +1,8 @@
+<!--
+order: 4
+-->
+
+# Messages
+
+The messages used to initialize a solo machine light client are defined in the
+core sub-module [02-client](../../../core/spec/04_messages.md).

x/ibc/light-clients/06-solomachine/spec/README.md

@@ -9,10 +9,18 @@ parent:
 
 ## Abstract
 
-This paper defines the implementation of the ICS06 protocol on the Cosmos SDK.
+This paper defines the implementation of the ICS06 protocol on the Cosmos SDK. For the general
+specification please refer to the [ICS06 Specification](https://github.com/cosmos/ics/tree/master/spec/ics-006-solo-machine-client).
 
-For the general specification please refer to the [ICS06 Specification](https://github.com/cosmos/ics/tree/master/spec/ics-006-solo-machine-client).
+This implementation of a solo machine light client supports single and multi-signature public
+keys. The client is capable of handling public key updates by header and governance proposals.
+The light client is capable of processing client misbehaviour. Proofs of the counterparty state
+are generated by the solo machine client by signing over the desired state with a certain sequence,
+diversifier, and timestamp. 
 
 ## Contents
 
 1. **[Concepts](01_concepts.md)**
+2. **[State](02_state.md)**
+3. **[State Transitions](03_state_transitions.md)**
+4. **[Messages](04_messages.md)**

x/ibc/light-clients/06-solomachine/types/update.go

@@ -10,7 +10,7 @@ import (
 
 // CheckHeaderAndUpdateState checks if the provided header is valid and updates
 // the consensus state if appropriate. It returns an error if:
-// - the client or header provided are not parseable to solo machine types
+// - the header provided is not parseable to a solo machine header
 // - the header sequence does not match the current sequence
 // - the header timestamp is less than the consensus state timestamp
 // - the currently registered public key did not provide the update signature