github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/ibc-go/modules/light-clients/06-solomachine/spec/01_concepts.md (about)

     1  <!--
     2  order: 1
     3  -->
     4  
     5  # Concepts
     6  
     7  ## Client State
     8  
     9  The `ClientState` for a solo machine light client stores the latest sequence, the frozen sequence,
    10  the latest consensus state, and client flag indicating if the client should be allowed to be updated
    11  after a governance proposal. 
    12  
    13  If the client is not frozen then the frozen sequence is 0. 
    14  
    15  ## Consensus State
    16  
    17  The consensus states stores the public key, diversifier, and timestamp of the solo machine light client. 
    18  
    19  The diversifier is used to prevent accidental misbehaviour if the same public key is used across
    20  different chains with the same client identifier. It should be unique to the chain the light client
    21  is used on. 
    22  
    23  ## Public Key
    24  
    25  The public key can be a single public key or a multi-signature public key. The public key type used
    26  must fulfill the tendermint public key interface (this will become the SDK public key interface in the
    27  near future). The public key must be registered on the application codec otherwise encoding/decoding 
    28  errors will arise. The public key stored in the consensus state is represented as a protobuf `Any`. 
    29  This allows for flexibility in what other public key types can be supported in the future. 
    30   
    31  ## Counterparty Verification
    32  
    33  The solo machine light client can verify counterparty client state, consensus state, connection state,
    34  channel state, packet commitments, packet acknowledgements, packet receipt absence, 
    35  and the next sequence receive. At the end of each successful verification call the light
    36  client sequence number will be incremented. 
    37  
    38  Successful verification requires the current public key to sign over the proof.
    39  
    40  ## Proofs
    41  
    42  A solo machine proof should verify that the solomachine public key signed
    43  over some specified data. The format for generating marshaled proofs for
    44  the SDK's implementation of solo machine is as follows:
    45  
    46  1. Construct the data using the associated protobuf definition and marshal it.
    47  
    48  For example:
    49  
    50  ```go
    51  data := &ClientStateData{
    52    Path:        []byte(path.String()),
    53    ClientState: any,
    54  }
    55  
    56  dataBz, err := cdc.Marshal(data)
    57  ```
    58  
    59  The helper functions `...DataBytes()` in [proof.go](../types/proof.go) handle this
    60  functionality. 
    61  
    62  2. Construct the `SignBytes` and marshal it.
    63  
    64  For example:
    65  
    66  ```go
    67  signBytes := &SignBytes{
    68    Sequence:    sequence,
    69    Timestamp:   timestamp,
    70    Diversifier: diversifier,
    71    DataType:    CLIENT,
    72    Data:        dataBz,
    73  }
    74  
    75  signBz, err := cdc.Marshal(signBytes)
    76  ```
    77  
    78  The helper functions `...SignBytes()` in [proof.go](../types/proof.go) handle this functionality.
    79  The `DataType` field is used to disambiguate what type of data was signed to prevent potential 
    80  proto encoding overlap.
    81  
    82  3. Sign the sign bytes. Embed the signatures into either `SingleSignatureData` or `MultiSignatureData`.
    83  Convert the `SignatureData` to proto and marshal it.
    84  
    85  For example:
    86  
    87  ```go
    88  sig, err := key.Sign(signBz)
    89  sigData := &signing.SingleSignatureData{
    90    Signature: sig,
    91  }
    92  
    93  protoSigData := signing.SignatureDataToProto(sigData)
    94  bz, err := cdc.Marshal(protoSigData)
    95  ```
    96  
    97  4. Construct a `TimestampedSignatureData` and marshal it. The marshaled result can be passed in 
    98  as the proof parameter to the verification functions.
    99  
   100  For example:
   101  
   102  ```go
   103  timestampedSignatureData := &types.TimestampedSignatureData{
   104    SignatureData: sigData,
   105    Timestamp: solomachine.Time,
   106  }
   107  
   108  proof, err := cdc.Marshal(timestampedSignatureData)
   109  ```
   110  
   111  NOTE: At the end of this process, the sequence associated with the key needs to be updated. 
   112  The sequence must be incremented each time proof is generated. 
   113  
   114  ## Updates By Header
   115  
   116  An update by a header will only succeed if:
   117  
   118  - the header provided is parseable to solo machine header
   119  - the header sequence matches the current sequence
   120  - the header timestamp is greater than or equal to the consensus state timestamp
   121  - the currently registered public key generated the proof
   122  
   123  If the update is successful:
   124  
   125  - the public key is updated
   126  - the diversifier is updated
   127  - the timestamp is updated
   128  - the sequence is incremented by 1
   129  - the new consensus state is set in the client state 
   130  
   131  ## Updates By Proposal
   132  
   133  An update by a governance proposal will only succeed if:
   134  
   135  - the substitute provided is parseable to solo machine client state
   136  - the `AllowUpdateAfterProposal` client parameter is set to `true`
   137  - the new consensus state public key does not equal the current consensus state public key
   138  
   139  If the update is successful:
   140  
   141  - the subject client state is updated to the substitute client state
   142  - the subject consensus state is updated to the substitute consensus state
   143  - the client is unfrozen (if it was previously frozen)
   144  
   145  ## Misbehaviour
   146  
   147  Misbehaviour handling will only succeed if:
   148  
   149  - the misbehaviour provided is parseable to solo machine misbehaviour
   150  - the client is not already frozen
   151  - the current public key signed over two unique data messages at the same sequence and diversifier. 
   152  
   153  If the misbehaviour is successfully processed:
   154  
   155  - the client is frozen by setting the frozen sequence to the misbehaviour sequence
   156  
   157  NOTE: Misbehaviour processing is data processing order dependent. A misbehaving solo machine
   158  could update to a new public key to prevent being frozen before misbehaviour is submitted. 
   159  
   160  ## Upgrades
   161  
   162  Upgrades to solo machine light clients are not supported since an entirely different type of 
   163  public key can be set using normal client updates.