Implement IBCModule interface and callbacks
Learn how to implement the IBCModule interface and all of the callbacks it requires.
The Cosmos SDK expects all IBC modules to implement the IBCModule
interface. This interface contains all of the callbacks IBC expects modules to implement. They include callbacks related to channel handshake, closing and packet callbacks (OnRecvPacket, OnAcknowledgementPacket and OnTimeoutPacket).
// IBCModule implements the ICS26 interface for given the keeper.
// The implementation of the IBCModule interface could for example be in a file called ibc_module.go,
// but ultimately file structure is up to the developer
type IBCModule struct {
keeper keeper.Keeper
}
Additionally, in the module.go file, add the following line:
var (
_ module.AppModule = AppModule{}
_ module.AppModuleBasic = AppModuleBasic{}
// Add this line
_ porttypes.IBCModule = IBCModule{}
)
Pre-requisite readings
Channel handshake callbacks
This section will describe the callbacks that are called during channel handshake execution. Among other things, it will claim channel capabilities passed on from core IBC. For a refresher on capabilities, check the Overview section.
Here are the channel handshake callbacks that modules are expected to implement:
Note that some of the code below is pseudo code, indicating what actions need to happen but leaving it up to the developer to implement a custom implementation. E.g. the
checkArgumentsandnegotiateAppVersionfunctions.
// Called by IBC Handler on MsgOpenInit
func (im IBCModule) OnChanOpenInit(ctx sdk.Context,
order channeltypes.Order,
connectionHops []string,
portID string,
channelID string,
channelCap *capabilitytypes.Capability,
counterparty channeltypes.Counterparty,
version string,
) (string, error) {
// ... do custom initialization logic
// Use above arguments to determine if we want to abort handshake
// Examples:
// - Abort if order == UNORDERED,
// - Abort if version is unsupported
if err := checkArguments(args); err != nil {
return "", err
}
// OpenInit must claim the channelCapability that IBC passes into the callback
if err := im.keeper.ClaimCapability(ctx, chanCap, host.ChannelCapabilityPath(portID, channelID)); err != nil {
return "", err
}
return version, nil
}
// Called by IBC Handler on MsgOpenTry
func (im IBCModule) OnChanOpenTry(
ctx sdk.Context,
order channeltypes.Order,
connectionHops []string,
portID,
channelID string,
channelCap *capabilitytypes.Capability,
counterparty channeltypes.Counterparty,
counterpartyVersion string,
) (string, error) {
// ... do custom initialization logic
// Use above arguments to determine if we want to abort handshake
if err := checkArguments(args); err != nil {
return "", err
}
// OpenTry must claim the channelCapability that IBC passes into the callback
if err := im.keeper.scopedKeeper.ClaimCapability(ctx, chanCap, host.ChannelCapabilityPath(portID, channelID)); err != nil {
return err
}
// Construct application version
// IBC applications must return the appropriate application version
// This can be a simple string or it can be a complex version constructed
// from the counterpartyVersion and other arguments.
// The version returned will be the channel version used for both channel ends.
appVersion := negotiateAppVersion(counterpartyVersion, args)
return appVersion, nil
}
// Called by IBC Handler on MsgOpenAck
func (im IBCModule) OnChanOpenAck(
ctx sdk.Context,
portID,
channelID string,
counterpartyVersion string,
) error {
if counterpartyVersion != types.Version {
return sdkerrors.Wrapf(types.ErrInvalidVersion, "invalid counterparty version: %s, expected %s", counterpartyVersion, types.Version)
}
// do custom logic
return nil
}
// Called by IBC Handler on MsgOpenConfirm
func (im IBCModule) OnChanOpenConfirm(
ctx sdk.Context,
portID,
channelID string,
) error {
// do custom logic
return nil
}
Channel closing callbacks
The channel closing handshake will also invoke module callbacks that can return errors to abort the closing handshake. Closing a channel is a 2-step handshake, the initiating chain calls ChanCloseInit and the finalizing chain calls ChanCloseConfirm.
Currently, all IBC modules in this repository return an error for OnChanCloseInit to prevent the channels from closing. This is because any user can call ChanCloseInit by submitting a MsgChannelCloseInit transaction.
// Called by IBC Handler on MsgCloseInit
func (im IBCModule) OnChanCloseInit(
ctx sdk.Context,
portID,
channelID string,
) error {
// ... do custom finalization logic
// Use above arguments to determine if we want to abort handshake
err := checkArguments(args)
return err
}
// Called by IBC Handler on MsgCloseConfirm
func (im IBCModule) OnChanCloseConfirm(
ctx sdk.Context,
portID,
channelID string,
) error {
// ... do custom finalization logic
// Use above arguments to determine if we want to abort handshake
err := checkArguments(args)
return err
}
Channel handshake version negotiation
Application modules are expected to verify versioning used during the channel handshake procedure.
OnChanOpenInitwill verify that the relayer-chosen parameters are valid and perform any customINITlogic. It may return an error if the chosen parameters are invalid in which case the handshake is aborted. If the provided version string is non-empty,OnChanOpenInitshould return the version string if valid or an error if the provided version is invalid. If the version string is empty,OnChanOpenInitis expected to return a default version string representing the version(s) it supports. If there is no default version string for the application, it should return an error if the provided version is an empty string.OnChanOpenTrywill verify the relayer-chosen parameters along with the counterparty-chosen version string and perform customTRYlogic. If the relayer-chosen parameters are invalid, the callback must return an error to abort the handshake. If the counterparty-chosen version is not compatible with this module's supported versions, the callback must return an error to abort the handshake. If the versions are compatible, the try callback must select the final version string and return it to core IBC.OnChanOpenTrymay also perform custom initialization logic.OnChanOpenAckwill error if the counterparty selected version string is invalid and abort the handshake. It may also perform custom ACK logic.
Versions must be strings but can implement any versioning structure. If your application plans to have linear releases then semantic versioning is recommended. If your application plans to release various features in between major releases then it is advised to use the same versioning scheme as IBC. This versioning scheme specifies a version identifier and compatible feature set with that identifier. Valid version selection includes selecting a compatible version identifier with a subset of features supported by your application for that version. The struct used for this scheme can be found in 03-connection/types.
Since the version type is a string, applications have the ability to do simple version verification via string matching or they can use the already implemented versioning system and pass the proto encoded version into each handhshake call as necessary.
ICS20 currently implements basic string matching with a single supported version.
Packet callbacks
Just as IBC expects modules to implement callbacks for channel handshakes, it also expects modules to implement callbacks for handling the packet flow through a channel, as defined in the IBCModule interface.
Once a module A and module B are connected to each other, relayers can start relaying packets and acknowledgements back and forth on the channel.
Briefly, a successful packet flow works as follows:
- Module A sends a packet through the IBC module
- The packet is received by module B
- If module B writes an acknowledgement of the packet then module A will process the acknowledgement
- If the packet is not successfully received before the timeout, then module A processes the packet's timeout.
Sending packets
Modules do not send packets through callbacks, since the modules initiate the action of sending packets to the IBC module, as opposed to other parts of the packet flow where messages sent to the IBC
module must trigger execution on the port-bound module through the use of callbacks. Thus, to send a packet a module simply needs to call SendPacket on the IBCChannelKeeper.
Note that some of the code below is pseudo code, indicating what actions need to happen but leaving it up to the developer to implement a custom implementation. E.g. the
EncodePacketData(customPacketData)function.
// retrieve the dynamic capability for this channel
channelCap := scopedKeeper.GetCapability(ctx, channelCapName)
// Sending custom application packet data
data := EncodePacketData(customPacketData)
// Send packet to IBC, authenticating with channelCap
sequence, err := IBCChannelKeeper.SendPacket(
ctx,
channelCap,
sourcePort,
sourceChannel,
timeoutHeight,
timeoutTimestamp,
data,
)
In order to prevent modules from sending packets on channels they do not own, IBC expects modules to pass in the correct channel capability for the packet's source channel.
Receiving packets
To handle receiving packets, the module must implement the OnRecvPacket callback. This gets
invoked by the IBC module after the packet has been proved valid and correctly processed by the IBC
keepers. Thus, the OnRecvPacket callback only needs to worry about making the appropriate state
changes given the packet data without worrying about whether the packet is valid or not.
Modules may return to the IBC handler an acknowledgement which implements the Acknowledgement interface.
The IBC handler will then commit this acknowledgement of the packet so that a relayer may relay the
acknowledgement back to the sender module.
The state changes that occurred during this callback will only be written if:
- the acknowledgement was successful as indicated by the
Success()function of the acknowledgement - if the acknowledgement returned is nil indicating that an asynchronous process is occurring
NOTE: Applications which process asynchronous acknowledgements must handle reverting state changes
when appropriate. Any state changes that occurred during the OnRecvPacket callback will be written
for asynchronous acknowledgements.
Note that some of the code below is pseudo code, indicating what actions need to happen but leaving it up to the developer to implement a custom implementation. E.g. the
DecodePacketData(packet.Data)function.
func (im IBCModule) OnRecvPacket(
ctx sdk.Context,
packet channeltypes.Packet,
) ibcexported.Acknowledgement {
// Decode the packet data
packetData := DecodePacketData(packet.Data)
// do application state changes based on packet data and return the acknowledgement
// NOTE: The acknowledgement will indicate to the IBC handler if the application
// state changes should be written via the `Success()` function. Application state
// changes are only written if the acknowledgement is successful or the acknowledgement
// returned is nil indicating that an asynchronous acknowledgement will occur.
ack := processPacket(ctx, packet, packetData)
return ack
}
Reminder, the Acknowledgement interface:
// Acknowledgement defines the interface used to return
// acknowledgements in the OnRecvPacket callback.
type Acknowledgement interface {
Success() bool
Acknowledgement() []byte
}
Acknowledging packets
After a module writes an acknowledgement, a relayer can relay back the acknowledgement to the sender module. The sender module can
then process the acknowledgement using the OnAcknowledgementPacket callback. The contents of the
acknowledgement is entirely up to the modules on the channel (just like the packet data); however, it
may often contain information on whether the packet was successfully processed along
with some additional data that could be useful for remediation if the packet processing failed.
Since the modules are responsible for agreeing on an encoding/decoding standard for packet data and
acknowledgements, IBC will pass in the acknowledgements as []byte to this callback. The callback
is responsible for decoding the acknowledgement and processing it.
Note that some of the code below is pseudo code, indicating what actions need to happen but leaving it up to the developer to implement a custom implementation. E.g. the
DecodeAcknowledgement(acknowledgments)andprocessAck(ack)functions.
func (im IBCModule) OnAcknowledgementPacket(
ctx sdk.Context,
packet channeltypes.Packet,
acknowledgement []byte,
) (*sdk.Result, error) {
// Decode acknowledgement
ack := DecodeAcknowledgement(acknowledgement)
// process ack
res, err := processAck(ack)
return res, err
}
Timeout packets
If the timeout for a packet is reached before the packet is successfully received or the
counterparty channel end is closed before the packet is successfully received, then the receiving
chain can no longer process it. Thus, the sending chain must process the timeout using
OnTimeoutPacket to handle this situation. Again the IBC module will verify that the timeout is
indeed valid, so our module only needs to implement the state machine logic for what to do once a
timeout is reached and the packet can no longer be received.
func (im IBCModule) OnTimeoutPacket(
ctx sdk.Context,
packet channeltypes.Packet,
) (*sdk.Result, error) {
// do custom timeout logic
}
Optional interfaces
The following interface are optional and MAY be implemented by an IBCModule.
PacketDataUnmarshaler
The PacketDataUnmarshaler interface is defined as follows:
// PacketDataUnmarshaler defines an optional interface which allows a middleware to
// request the packet data to be unmarshaled by the base application.
type PacketDataUnmarshaler interface {
// UnmarshalPacketData unmarshals the packet data into a concrete type
UnmarshalPacketData([]byte) (interface{}, error)
}
The implementation of UnmarshalPacketData should unmarshal the bytes into the packet data type defined for an IBC stack.
The base application of an IBC stack should unmarshal the bytes into its packet data type, while a middleware may simply defer the call to the underlying application.
This interface allows middlewares to unmarshal a packet data in order to make use of interfaces the packet data type implements.
For example, the callbacks middleware makes use of this function to access packet data types which implement the PacketData and PacketDataProvider interfaces.