exported

Documentation

Index

• Constants
• type Acknowledgement
• type ClientMessage
• type ClientState
• type ClientStoreProvider
• type ConsensusState
• type GenesisMetadata
• type Height
• type LightClientModule
• type PacketData
• type PacketDataProvider
• type PacketI
• type Path
• type Prefix
• type Root
• type ScopedKeeper
• type Status
  • func (s Status) String() string

Constants

const (
	// TypeClientMisbehaviour is the shared evidence misbehaviour type
	TypeClientMisbehaviour string = "client_misbehaviour"

	// Solomachine is used to indicate that the light client is a solo machine.
	Solomachine string = "06-solomachine"

	// Tendermint is used to indicate that the client uses the Tendermint Consensus Algorithm.
	Tendermint string = "07-tendermint"

	// Localhost is the client type for the localhost client.
	Localhost string = "09-localhost"

	// LocalhostClientID is the sentinel client ID for the localhost client.
	LocalhostClientID string = Localhost

	// Active is a status type of a client. An active client is allowed to be used.
	Active Status = "Active"

	// Frozen is a status type of a client. A frozen client is not allowed to be used.
	Frozen Status = "Frozen"

	// Expired is a status type of a client. An expired client is not allowed to be used.
	Expired Status = "Expired"

	// Unknown indicates there was an error in determining the status of a client.
	Unknown Status = "Unknown"

	// Unauthorized indicates that the client type is not registered as an allowed client type.
	Unauthorized Status = "Unauthorized"
)

const (
	// ModuleName is the name of the IBC module
	ModuleName = "ibc"
	// StoreKey is the string store representation
	StoreKey = ModuleName
	// QuerierRoute is the querier route for the IBC module
	QuerierRoute = ModuleName
	// RouterKey is the msg router key for the IBC module
	RouterKey = ModuleName
)

const LocalhostConnectionID string = "connection-localhost"

LocalhostConnectionID is the sentinel connection ID for the localhost connection.

Types

type Acknowledgement

type Acknowledgement interface {
	// Success determines if the IBC application state should be persisted when handling `RecvPacket`.
	// During `OnRecvPacket` IBC application callback execution, all state changes are held in a cache store and committed if:
	// - the acknowledgement.Success() returns true
	// - a nil acknowledgement is returned (asynchronous acknowledgements)
	//
	// Note 1: IBC application callback events are always persisted so long as `RecvPacket` succeeds without error.
	//
	// Note 2: The return value should account for the success of the underlying IBC application or middleware. Thus the  `acknowledgement.Success` is representative of the entire IBC stack's success when receiving a packet. The individual success of each acknowledgement associated with an IBC application or middleware must be determined by obtaining the actual acknowledgement type after decoding the acknowledgement bytes.
	//
	// See https://github.com/cosmos/ibc-go/blob/v7.0.0/docs/ibc/apps.md for further explanations.
	Success() bool
	Acknowledgement() []byte
}

Acknowledgement defines the interface used to return acknowledgements in the OnRecvPacket callback. The Acknowledgement interface is used by core IBC to ensure partial state changes are not committed when packet receives have not properly succeeded (typically resulting in an error acknowledgement being returned). The interface also allows core IBC to obtain the acknowledgement bytes whose encoding is determined by each IBC application or middleware. Each custom acknowledgement type must implement this interface.

type ClientMessage

type ClientMessage interface {
	proto.Message

	ClientType() string
	ValidateBasic() error
}

ClientMessage is an interface used to update an IBC client. The update may be done by a single header, a batch of headers, misbehaviour, or any type which when verified produces a change to state of the IBC client

type ClientState

type ClientState interface {
	proto.Message

	ClientType() string
	Validate() error
}

ClientState defines the required common functions for light clients.

type ClientStoreProvider

type ClientStoreProvider interface {
	// ClientStore will return a client prefixed store using the given client identifier
	ClientStore(ctx sdk.Context, clientID string) storetypes.KVStore
}

ClientStoreProvider is an interface which gives access to the client prefixed stores. It is implemented by the 02-client keeper and may be called by a light client module to obtain a client prefixed store for the given client identifier.

type ConsensusState

type ConsensusState interface {
	proto.Message

	ClientType() string // Consensus kind

	// GetTimestamp returns the timestamp (in nanoseconds) of the consensus state
	//
	// Deprecated: GetTimestamp is not used outside of the light client implementations,
	// and therefore it doesn't need to be an interface function.
	GetTimestamp() uint64

	ValidateBasic() error
}

ConsensusState is the state of the consensus process

type GenesisMetadata

type GenesisMetadata interface {
	// return store key that contains metadata without clientID-prefix
	GetKey() []byte
	// returns metadata value
	GetValue() []byte
}

GenesisMetadata is a wrapper interface over clienttypes.GenesisMetadata all clients must use the concrete implementation in types

type Height

type Height interface {
	IsZero() bool
	LT(Height) bool
	LTE(Height) bool
	EQ(Height) bool
	GT(Height) bool
	GTE(Height) bool
	GetRevisionNumber() uint64
	GetRevisionHeight() uint64
	Increment() Height
	Decrement() (Height, bool)
	String() string
}

Height is a wrapper interface over clienttypes.Height all clients must use the concrete implementation in types

type LightClientModule

type LightClientModule interface {
	// 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.
	RegisterStoreProvider(storeProvider ClientStoreProvider)

	// Initialize is called upon client creation, it allows the client to perform validation on the client state and initial consensus state.
	// The light client module is responsible for setting any client-specific data in the store. This includes the client state,
	// initial consensus state and any associated metadata.
	Initialize(ctx sdk.Context, clientID string, clientState, consensusState []byte) error

	// 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.
	VerifyClientMessage(ctx sdk.Context, clientID string, clientMsg ClientMessage) error

	// Checks for evidence of a misbehaviour in Header or Misbehaviour type. It assumes the ClientMessage
	// has already been verified.
	CheckForMisbehaviour(ctx sdk.Context, clientID string, clientMsg ClientMessage) bool

	// UpdateStateOnMisbehaviour should perform appropriate state changes on a client state given that misbehaviour has been detected and verified
	UpdateStateOnMisbehaviour(ctx sdk.Context, clientID string, clientMsg ClientMessage)

	// 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.
	UpdateState(ctx sdk.Context, clientID string, clientMsg ClientMessage) []Height

	// 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).
	VerifyMembership(
		ctx sdk.Context,
		clientID string,
		height Height,
		delayTimePeriod uint64,
		delayBlockPeriod uint64,
		proof []byte,
		path Path,
		value []byte,
	) error

	// 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).
	VerifyNonMembership(
		ctx sdk.Context,
		clientID string,
		height Height,
		delayTimePeriod uint64,
		delayBlockPeriod uint64,
		proof []byte,
		path Path,
	) error

	// Status must return the status of the client. Only Active clients are allowed to process packets.
	Status(ctx sdk.Context, clientID string) Status

	// LatestHeight returns the latest height of the client. If no client is present for the provided client identifier a zero value height may be returned.
	LatestHeight(ctx sdk.Context, clientID string) Height

	// TimestampAtHeight must return the timestamp for the consensus state associated with the provided height.
	TimestampAtHeight(
		ctx sdk.Context,
		clientID string,
		height Height,
	) (uint64, error)

	// RecoverClient must verify that the provided substitute may be used to update the subject client.
	// The light client module must set the updated client and consensus states within the clientStore for the subject client.
	RecoverClient(ctx sdk.Context, clientID, substituteClientID string) error

	// 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.
	VerifyUpgradeAndUpdateState(
		ctx sdk.Context,
		clientID string,
		newClient []byte,
		newConsState []byte,
		upgradeClientProof,
		upgradeConsensusStateProof []byte,
	) error
}

LightClientModule is an interface which core IBC uses to interact with light client modules. Light client modules must implement this interface to integrate with core IBC.

type PacketData

type PacketData interface {
	// GetPacketSender returns the sender address of the packet data.
	// If the packet sender is unknown or undefined, an empty string should be returned.
	GetPacketSender(sourcePortID string) string
}

PacketData defines an optional interface which an application's packet data structure may implement.

type PacketDataProvider

type PacketDataProvider interface {
	// GetCustomPacketData returns the packet data held on behalf of another application.
	// The name the information is stored under should be provided as the key.
	// If no custom packet data exists for the key, nil should be returned.
	GetCustomPacketData(key string) interface{}
}

PacketDataProvider defines an optional interfaces for retrieving custom packet data stored on behalf of another application. An existing problem in the IBC middleware design is the inability for a middleware to define its own packet data type and insert packet sender provided information. A short term solution was introduced into several application's packet data to utilize a memo field to carry this information on behalf of another application. This interfaces standardizes that behaviour. Upon realization of the ability for middleware's to define their own packet data types, this interface will be deprecated and removed with time.

type PacketI

type PacketI interface {
	GetSequence() uint64
	GetTimeoutHeight() Height
	GetTimeoutTimestamp() uint64
	GetSourcePort() string
	GetSourceChannel() string
	GetDestPort() string
	GetDestChannel() string
	GetData() []byte
	ValidateBasic() error
}

PacketI defines the standard interface for IBC packets

type Path

type Path interface {
	Empty() bool
}

Path implements spec:CommitmentPath. A path is the additional information provided to the verification function.

type Prefix

type Prefix interface {
	Bytes() []byte
	Empty() bool
}

Prefix implements spec:CommitmentPrefix. Prefix represents the common "prefix" that a set of keys shares.

type Root

type Root interface {
	GetHash() []byte
	Empty() bool
}

Root implements spec:CommitmentRoot. A root is constructed from a set of key-value pairs, and the inclusion or non-inclusion of an arbitrary key-value pair can be proven with the proof.

type ScopedKeeper

type ScopedKeeper interface {
	NewCapability(ctx sdk.Context, name string) (*capabilitytypes.Capability, error)
	GetCapability(ctx sdk.Context, name string) (*capabilitytypes.Capability, bool)
	AuthenticateCapability(ctx sdk.Context, cap *capabilitytypes.Capability, name string) bool
	LookupModules(ctx sdk.Context, name string) ([]string, *capabilitytypes.Capability, error)
	ClaimCapability(ctx sdk.Context, cap *capabilitytypes.Capability, name string) error
}

ScopedKeeper defines the expected x/capability scoped keeper interface

type Status

type Status string

Status represents the status of a client

func (Status) String

func (s Status) String() string

String returns the string representation of a client status.