Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

02-client routing: add godoc to LightClientModule functions #5900

Merged
merged 2 commits into from
Feb 26, 2024
Merged

02-client routing: add godoc to LightClientModule functions #5900

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30869a8
add godoc for light client module functions
crodriguezvega Feb 25, 2024
cf7475a
linter
crodriguezvega Feb 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 6 additions & 10 deletions modules/light-clients/06-solomachine/light_client_module.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import (

var _ exported.LightClientModule = (*LightClientModule)(nil)

// LightClientModule implements the core IBC api.LightClientModule interface?
// LightClientModule implements the core IBC api.LightClientModule interface
type LightClientModule struct {
cdc codec.BinaryCodec
storeProvider exported.ClientStoreProvider
Expand All @@ -25,6 +25,9 @@ func NewLightClientModule(cdc codec.BinaryCodec) LightClientModule {
}
}

// RegisterStoreProvider is called by core IBC when a LightClientModule is added to the router.
// It allows the LightClientModule to set a ClientStoreProvider which supplies isolated prefix client stores
// to IBC light client instances.
func (lcm *LightClientModule) RegisterStoreProvider(storeProvider exported.ClientStoreProvider) {
lcm.storeProvider = storeProvider
}
Expand Down Expand Up @@ -86,7 +89,7 @@ func (lcm LightClientModule) CheckForMisbehaviour(ctx sdk.Context, clientID stri
return clientState.CheckForMisbehaviour(ctx, lcm.cdc, clientStore, clientMsg)
}

// UpdateStateOnMisbehaviour should perform appropriate state changes on a client state given that misbehaviour has been detected and verified
// UpdateStateOnMisbehaviour should perform appropriate state changes on a client state given that misbehaviour has been detected and verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 08-solomachine-{n}.
func (lcm LightClientModule) UpdateStateOnMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) {
Expand Down Expand Up @@ -217,14 +220,7 @@ func (lcm LightClientModule) RecoverClient(ctx sdk.Context, clientID, substitute
return clientState.CheckSubstituteAndUpdateState(ctx, lcm.cdc, clientStore, substituteClientStore, substituteClient)
}

// // Upgrade functions
// // NOTE: proof heights are not included as upgrade to a new revision is expected to pass only on the last
// // height committed by the current revision. Clients are responsible for ensuring that the planned last
// // height of the current revision is somehow encoded in the proof verification process.
// // This is to ensure that no premature upgrades occur, since upgrade plans committed to by the counterparty
// // may be cancelled or modified before the last planned height.
// // If the upgrade is verified, the upgraded client and consensus states must be set in the client store.
// // Deprecated: will be removed as performs internal functionality
// VerifyUpgradeAndUpdateState returns an error since solomachine client does not support upgrades
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 08-solomachine-{n}.
func (LightClientModule) VerifyUpgradeAndUpdateState(ctx sdk.Context, clientID string, newClient []byte, newConsState []byte, upgradeClientProof, upgradeConsensusStateProof []byte) error {
Expand Down
34 changes: 34 additions & 0 deletions modules/light-clients/07-tendermint/light_client_module.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,22 @@ import (

var _ exported.LightClientModule = (*LightClientModule)(nil)

// LightClientModule implements the core IBC api.LightClientModule interface.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess api isn't a module yet but I'm happy to keep it here regardless

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I am assuming that we will have it by the time we release this. :)

type LightClientModule struct {
keeper keeper.Keeper
storeProvider exported.ClientStoreProvider
}

// NewLightClientModule creates and returns a new 08-wasm LightClientModule.
func NewLightClientModule(cdc codec.BinaryCodec, authority string) LightClientModule {
return LightClientModule{
keeper: keeper.NewKeeper(cdc, authority),
}
}

// RegisterStoreProvider is called by core IBC when a LightClientModule is added to the router.
// It allows the LightClientModule to set a ClientStoreProvider which supplies isolated prefix client stores
// to IBC light client instances.
func (lcm *LightClientModule) RegisterStoreProvider(storeProvider exported.ClientStoreProvider) {
lcm.storeProvider = storeProvider
}
Expand Down Expand Up @@ -56,6 +61,11 @@ func (lcm LightClientModule) Initialize(ctx sdk.Context, clientID string, client
return clientState.Initialize(ctx, lcm.keeper.Codec(), clientStore, &consensusState)
}

// VerifyClientMessage must verify a ClientMessage. A ClientMessage could be a Header, Misbehaviour, or batch update.
// It must handle each type of ClientMessage appropriately. Calls to CheckForMisbehaviour, UpdateState, and UpdateStateOnMisbehaviour
// will assume that the content of the ClientMessage has been verified and can be trusted. An error should be returned
// if the ClientMessage fails to verify.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) VerifyClientMessage(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) error {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
Expand All @@ -69,6 +79,9 @@ func (lcm LightClientModule) VerifyClientMessage(ctx sdk.Context, clientID strin
return clientState.VerifyClientMessage(ctx, cdc, clientStore, clientMsg)
}

// CheckForMisbehaviour checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage
// has already been verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) CheckForMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) bool {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
Expand All @@ -82,6 +95,8 @@ func (lcm LightClientModule) CheckForMisbehaviour(ctx sdk.Context, clientID stri
return clientState.CheckForMisbehaviour(ctx, cdc, clientStore, clientMsg)
}

// UpdateStateOnMisbehaviour should perform appropriate state changes on a client state given that misbehaviour has been detected and verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) UpdateStateOnMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
Expand All @@ -95,6 +110,9 @@ func (lcm LightClientModule) UpdateStateOnMisbehaviour(ctx sdk.Context, clientID
clientState.UpdateStateOnMisbehaviour(ctx, cdc, clientStore, clientMsg)
}

// UpdateState updates and stores as necessary any associated information for an IBC client, such as the ClientState and corresponding ConsensusState.
// Upon successful update, a list of consensus heights is returned. It assumes the ClientMessage has already been verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) UpdateState(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) []exported.Height {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
Expand All @@ -108,6 +126,9 @@ func (lcm LightClientModule) UpdateState(ctx sdk.Context, clientID string, clien
return clientState.UpdateState(ctx, cdc, clientStore, clientMsg)
}

// VerifyMembership is a generic proof verification method which verifies a proof of the existence of a value at a given CommitmentPath at the specified height.
// The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24).
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) VerifyMembership(
ctx sdk.Context,
Expand All @@ -130,6 +151,9 @@ func (lcm LightClientModule) VerifyMembership(
return clientState.VerifyMembership(ctx, clientStore, cdc, height, delayTimePeriod, delayBlockPeriod, proof, path, value)
}

// VerifyNonMembership is a generic proof verification method which verifies the absence of a given CommitmentPath at a specified height.
// The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24).
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) VerifyNonMembership(
ctx sdk.Context,
Expand All @@ -151,6 +175,8 @@ func (lcm LightClientModule) VerifyNonMembership(
return clientState.VerifyNonMembership(ctx, clientStore, cdc, height, delayTimePeriod, delayBlockPeriod, proof, path)
}

// Status must return the status of the client. Only Active clients are allowed to process packets.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) Status(ctx sdk.Context, clientID string) exported.Status {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
Expand All @@ -164,6 +190,8 @@ func (lcm LightClientModule) Status(ctx sdk.Context, clientID string) exported.S
return clientState.Status(ctx, clientStore, cdc)
}

// TimestampAtHeight must return the timestamp for the consensus state associated with the provided height.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) TimestampAtHeight(
ctx sdk.Context,
Expand All @@ -181,6 +209,9 @@ func (lcm LightClientModule) TimestampAtHeight(
return clientState.GetTimestampAtHeight(ctx, clientStore, cdc, height)
}

// RecoverClient must verify that the provided substitute may be used to update the subject client.
// The light client must set the updated client and consensus states within the clientStore for the subject client.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) RecoverClient(ctx sdk.Context, clientID, substituteClientID string) error {
substituteClientType, _, err := clienttypes.ParseClientIdentifier(substituteClientID)
Expand Down Expand Up @@ -213,6 +244,9 @@ func (lcm LightClientModule) RecoverClient(ctx sdk.Context, clientID, substitute
return clientState.CheckSubstituteAndUpdateState(ctx, cdc, clientStore, substituteClientStore, substituteClient)
}

// VerifyUpgradeAndUpdateState, on a successful verification expects the contract to update
// the new client state, consensus state, and any other client metadata.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 07-tendermint-{n}.
func (lcm LightClientModule) VerifyUpgradeAndUpdateState(
ctx sdk.Context,
Expand Down
19 changes: 8 additions & 11 deletions modules/light-clients/08-wasm/light_client_module.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import (

var _ exported.LightClientModule = (*LightClientModule)(nil)

// LightClientModule implements the core IBC api.LightClientModule interface?
// LightClientModule implements the core IBC api.LightClientModule interface.
type LightClientModule struct {
keeper wasmkeeper.Keeper
storeProvider exported.ClientStoreProvider
Expand All @@ -26,6 +26,9 @@ func NewLightClientModule(keeper wasmkeeper.Keeper) LightClientModule {
}
}

// RegisterStoreProvider is called by core IBC when a LightClientModule is added to the router.
// It allows the LightClientModule to set a ClientStoreProvider which supplies isolated prefix client stores
// to IBC light client instances.
func (lcm *LightClientModule) RegisterStoreProvider(storeProvider exported.ClientStoreProvider) {
lcm.storeProvider = storeProvider
}
Expand Down Expand Up @@ -77,7 +80,7 @@ func (lcm LightClientModule) VerifyClientMessage(ctx sdk.Context, clientID strin
return clientState.VerifyClientMessage(ctx, lcm.keeper.Codec(), clientStore, clientMsg)
}

// Checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage
// CheckForMisbehaviour checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage
// has already been verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 08-wasm-{n}.
Expand All @@ -93,7 +96,7 @@ func (lcm LightClientModule) CheckForMisbehaviour(ctx sdk.Context, clientID stri
return clientState.CheckForMisbehaviour(ctx, cdc, clientStore, clientMsg)
}

// UpdateStateOnMisbehaviour should perform appropriate state changes on a client state given that misbehaviour has been detected and verified
// UpdateStateOnMisbehaviour should perform appropriate state changes on a client state given that misbehaviour has been detected and verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 08-wasm-{n}.
func (lcm LightClientModule) UpdateStateOnMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) {
Expand Down Expand Up @@ -238,14 +241,8 @@ func (lcm LightClientModule) RecoverClient(ctx sdk.Context, clientID, substitute
return clientState.CheckSubstituteAndUpdateState(ctx, cdc, clientStore, substituteClientStore, substituteClient)
}

// // Upgrade functions
// // NOTE: proof heights are not included as upgrade to a new revision is expected to pass only on the last
// // height committed by the current revision. Clients are responsible for ensuring that the planned last
// // height of the current revision is somehow encoded in the proof verification process.
// // This is to ensure that no premature upgrades occur, since upgrade plans committed to by the counterparty
// // may be cancelled or modified before the last planned height.
// // If the upgrade is verified, the upgraded client and consensus states must be set in the client store.
// // DEPRECATED: will be removed as performs internal functionality
// VerifyUpgradeAndUpdateState, on a successful verification expects the contract to update
// the new client state, consensus state, and any other client metadata.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 08-wasm-{n}.
func (LightClientModule) VerifyUpgradeAndUpdateState(ctx sdk.Context, clientID string, newClient []byte, newConsState []byte, upgradeClientProof, upgradeConsensusStateProof []byte) error {
Expand Down
42 changes: 30 additions & 12 deletions modules/light-clients/09-localhost/light_client_module.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,32 @@ import (

var _ exported.LightClientModule = (*LightClientModule)(nil)

// LightClientModule implements the core IBC api.LightClientModule interface.
type LightClientModule struct {
cdc codec.BinaryCodec
key storetypes.StoreKey
storeProvider exported.ClientStoreProvider
}

// NewLightClientModule creates and returns a new 09-localhost LightClientModule.
func NewLightClientModule(cdc codec.BinaryCodec, key storetypes.StoreKey) *LightClientModule {
return &LightClientModule{
cdc: cdc,
key: key,
}
}

// RegisterStoreProvider is called by core IBC when a LightClientModule is added to the router.
// It allows the LightClientModule to set a ClientStoreProvider which supplies isolated prefix client stores
// to IBC light client instances.
func (lcm *LightClientModule) RegisterStoreProvider(storeProvider exported.ClientStoreProvider) {
lcm.storeProvider = storeProvider
}

// Initialize ensures that initial consensus state for localhost is nil.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 09-localhost-{n}.
func (lcm LightClientModule) Initialize(ctx sdk.Context, clientID string, clientStateBz, consensusStateBz []byte) error {
func (lcm LightClientModule) Initialize(ctx sdk.Context, clientID string, _, consensusStateBz []byte) error {
if len(consensusStateBz) != 0 {
return errorsmod.Wrap(clienttypes.ErrInvalidConsensus, "initial consensus state for localhost must be nil.")
}
Expand All @@ -46,27 +53,26 @@ func (lcm LightClientModule) Initialize(ctx sdk.Context, clientID string, client
return nil
}

// VerifyClientMessage is unsupported by the 09-localhost client type and returns an error.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 09-localhost-{n}.
func (lcm LightClientModule) VerifyClientMessage(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) error {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
cdc := lcm.cdc

clientState, found := getClientState(clientStore, cdc)
if !found {
return errorsmod.Wrap(clienttypes.ErrClientNotFound, clientID)
}

return clientState.VerifyClientMessage(ctx, cdc, clientStore, clientMsg)
func (LightClientModule) VerifyClientMessage(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) error {
return errorsmod.Wrap(clienttypes.ErrUpdateClientFailed, "client message verification is unsupported by the localhost client")
}

// CheckForMisbehaviour is unsupported by the 09-localhost client type and performs a no-op, returning false.
func (LightClientModule) CheckForMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) bool {
return false
}

// UpdateStateOnMisbehaviour is unsupported by the 09-localhost client type and performs a no-op.
func (LightClientModule) UpdateStateOnMisbehaviour(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) {
// no-op
}

// UpdateState updates and stores as necessary any associated information for an IBC client, such as the ClientState and corresponding ConsensusState.
// Upon successful update, a list of consensus heights is returned. It assumes the ClientMessage has already been verified.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 09-localhost-{n}.
func (lcm LightClientModule) UpdateState(ctx sdk.Context, clientID string, clientMsg exported.ClientMessage) []exported.Height {
clientStore := lcm.storeProvider.ClientStore(ctx, clientID)
Expand All @@ -80,6 +86,10 @@ func (lcm LightClientModule) UpdateState(ctx sdk.Context, clientID string, clien
return clientState.UpdateState(ctx, cdc, clientStore, clientMsg)
}

// VerifyMembership is a generic proof verification method which verifies the existence of a given key and value within the IBC store.
// The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24).
// The caller must provide the full IBC store.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 09-localhost-{n}.
func (lcm LightClientModule) VerifyMembership(
ctx sdk.Context,
Expand All @@ -103,6 +113,10 @@ func (lcm LightClientModule) VerifyMembership(
return clientState.VerifyMembership(ctx, ibcStore, cdc, height, delayTimePeriod, delayBlockPeriod, proof, path, value)
}

// VerifyNonMembership is a generic proof verification method which verifies the absence of a given CommitmentPath within the IBC store.
// The caller is expected to construct the full CommitmentPath from a CommitmentPrefix and a standardized path (as defined in ICS 24).
// The caller must provide the full IBC store.
//
// CONTRACT: clientID is validated in 02-client router, thus clientID is assumed here to have the format 09-localhost-{n}.
func (lcm LightClientModule) VerifyNonMembership(
ctx sdk.Context,
Expand Down Expand Up @@ -130,6 +144,8 @@ func (LightClientModule) Status(ctx sdk.Context, clientID string) exported.Statu
return exported.Active
}

// TimestampAtHeight returns the current block time retrieved from the application context. The localhost client does not store consensus states and thus
// cannot provide a timestamp for the provided height.
func (LightClientModule) TimestampAtHeight(
ctx sdk.Context,
clientID string,
Expand All @@ -138,10 +154,12 @@ func (LightClientModule) TimestampAtHeight(
return uint64(ctx.BlockTime().UnixNano()), nil
}

func (LightClientModule) RecoverClient(ctx sdk.Context, clientID, substituteClientID string) error {
// RecoverClient returns an error. The localhost cannot be modified by proposals.
func (LightClientModule) RecoverClient(_ sdk.Context, _, _ string) error {
return errorsmod.Wrap(clienttypes.ErrUpdateClientFailed, "cannot update localhost client with a proposal")
}

// VerifyUpgradeAndUpdateState returns an error since localhost cannot be upgraded.
func (LightClientModule) VerifyUpgradeAndUpdateState(
ctx sdk.Context,
clientID string,
Expand Down
Loading