lightclient.gno

  1package lightclient
  2
  3import (
  4	"gno.land/p/aib/ibc/types"
  5	"gno.land/p/aib/ics23"
  6)
  7
  8// Status represents the status of a client
  9type Status = string
 10
 11const (
 12	// Solomachine is used to indicate that the light client is a solo machine.
 13	Solomachine string = "06-solomachine"
 14
 15	// Tendermint is used to indicate that the client uses the Tendermint Consensus Algorithm.
 16	Tendermint string = "07-tendermint"
 17
 18	// Localhost is the client type for the localhost client.
 19	Localhost string = "09-localhost"
 20
 21	// LocalhostClientID is the sentinel client ID for the localhost client.
 22	LocalhostClientID string = Localhost
 23
 24	// Active is a status type of a client. An active client is allowed to be used.
 25	Active Status = "Active"
 26
 27	// Frozen is a status type of a client. A frozen client is not allowed to be used.
 28	Frozen Status = "Frozen"
 29
 30	// Expired is a status type of a client. An expired client is not allowed to be used.
 31	Expired Status = "Expired"
 32
 33	// Unknown indicates there was an error in determining the status of a client.
 34	Unknown Status = "Unknown"
 35
 36	// Unauthorized indicates that the client type is not registered as an allowed client type.
 37	Unauthorized Status = "Unauthorized"
 38)
 39
 40// Interface is an interface which core IBC uses to interact with light
 41// client modules.  Light client modules must implement this interface to
 42// integrate with core IBC.
 43type Interface interface {
 44	// Initialize is called upon client creation, it allows the client to perform
 45	// validation on the client state and initial consensus state.  The light
 46	// client module is responsible for setting any client-specific data in the
 47	// store. This includes the client state, initial consensus state and any
 48	// associated metadata.
 49	Initialize(ClientState, ConsensusState) error
 50
 51	// VerifyClientMessage must verify a ClientMessage. A ClientMessage could be
 52	// a Header, Misbehaviour, or batch update.  It must handle each type of
 53	// ClientMessage appropriately. Calls to CheckForMisbehaviour, UpdateState,
 54	// and UpdateStateOnMisbehaviour will assume that the content of the
 55	// ClientMessage has been verified and can be trusted. An error should be
 56	// returned if the ClientMessage fails to verify.
 57	VerifyClientMessage(ClientMessage) error
 58
 59	// Checks for evidence of a misbehaviour in Header or Misbehaviour type. It
 60	// assumes the ClientMessage has already been verified.
 61	CheckForMisbehaviour(ClientMessage) bool
 62
 63	// UpdateStateOnMisbehaviour should perform appropriate state changes on a
 64	// client state given that misbehaviour has been detected and verified.
 65	UpdateStateOnMisbehaviour(ClientMessage)
 66
 67	// UpdateState updates and stores as necessary any associated information for
 68	// an IBC client, such as the ClientState and corresponding ConsensusState.
 69	// Upon successful update, a list of consensus heights is returned. It
 70	// assumes the ClientMessage has already been verified.
 71	UpdateState(ClientMessage) []types.Height
 72
 73	// VerifyMembership is a generic proof verification method which verifies a
 74	// proof of the existence of a value at a given CommitmentPath at the
 75	// specified height.  The caller is expected to construct the full
 76	// CommitmentPath from a CommitmentPrefix and a standardized path (as defined
 77	// in ICS 24).
 78	VerifyMembership(height types.Height, proofs []ics23.CommitmentProof,
 79		path types.MerklePath, value []byte) error
 80
 81	// VerifyNonMembership is a generic proof verification method which verifies
 82	// the absence of a given CommitmentPath at a specified height.  The caller
 83	// is expected to construct the full CommitmentPath from a CommitmentPrefix
 84	// and a standardized path (as defined in ICS 24).
 85	VerifyNonMembership(height types.Height,
 86		proofs []ics23.CommitmentProof, path types.MerklePath) error
 87
 88	// Status must return the status of the client. Only Active clients are
 89	// allowed to process packets.
 90	Status() Status
 91
 92	// LatestHeight returns the latest height of the client. If no client is
 93	// present for the provided client identifier a zero value height may be
 94	// returned.
 95	LatestHeight() types.Height
 96
 97	// TimestampAtHeight must return the timestamp in seconds for the consensus
 98	// state associated with the provided height.
 99	TimestampAtHeight(types.Height) (uint64, error)
100
101	// RecoverClient must verify that the provided substitute may be used to
102	// recover the subject (receiver) client, and copy the substitute's updated
103	// client and consensus state into the subject. The caller is responsible
104	// for verifying Status() on both sides and authorization beforehand.
105	RecoverClient(substitute Interface) error
106
107	// Upgrade functions NOTE: proof heights are not included as upgrade to a new
108	// revision is expected to pass only on the last height committed by the
109	// current revision. Clients are responsible for ensuring that the planned
110	// last height of the current revision is somehow encoded in the proof
111	// verification process.  This is to ensure that no premature upgrades occur,
112	// since upgrade plans committed to by the counterparty may be cancelled or
113	// modified before the last planned height.  If the upgrade is verified, the
114	// upgraded client and consensus states must be set in the client store.
115	VerifyUpgradeAndUpdateState(newClient, newConsState, upgradeClientProof,
116		upgradeConsensusStateProof any) error
117}
118
119// ClientState defines the required common functions for light clients.
120type ClientState interface {
121	ClientType() string
122	ValidateBasic() error
123}
124
125// ConsensusState is the state of the consensus process
126type ConsensusState interface {
127	ClientType() string
128	ValidateBasic() error
129}
130
131// ClientMessage is an interface used to update an IBC client.
132// The update may be done by a single header, a batch of headers, misbehaviour,
133// or any type which when verified produces a change to state of the IBC client
134type ClientMessage interface {
135	ClientType() string
136	ValidateBasic() error
137}