ibccallbacks

README

Callbacks Middleware

IBC was designed with callbacks between core IBC and IBC applications. IBC apps would send a packet to core IBC, and receive a callback on every step of that packet's lifecycle. This allows IBC applications to be built on top of core IBC, and to be able to execute custom logic on packet lifecycle events (e.g. unescrow tokens for ICS-20).

This setup worked well for off-chain users interacting with IBC applications. However, we are now seeing the desire for secondary applications (e.g. smart contracts, modules) to call into IBC apps as part of their state machine logic and then do some actions on packet lifecycle events.

The Callbacks Middleware allows for this functionality by allowing the packets of the underlying IBC applications to register callbacks to secondary applications for lifecycle events. These callbacks are then executed by the Callbacks Middleware when the corresponding packet lifecycle event occurs.

After much discussion, the design was expanded to an ADR, and the Callbacks Middleware is an implementation of that ADR.

Version Matrix

The callbacks middleware has no stable releases yet. To use it, you need to import the git commit that contains the module with the compatible version of ibc-go. To do so, run the following command with the desired git commit in your project:

go get github.com/cosmos/ibc-go/modules/apps/callbacks@342c00b0f8bd7feeebf0780f208a820b0faf90d1

You can find the version matrix for the callbacks middleware here

Documentation

Index

• type IBCMiddleware
  • func NewIBCMiddleware(app porttypes.IBCModule, ics4Wrapper porttypes.ICS4Wrapper, ...) IBCMiddleware
  • func (im IBCMiddleware) GetAppVersion(ctx context.Context, portID, channelID string) (string, bool)
  • func (im *IBCMiddleware) GetICS4Wrapper() porttypes.ICS4Wrapper
  • func (im IBCMiddleware) OnAcknowledgementPacket(ctx context.Context, channelVersion string, packet channeltypes.Packet, ...) error
  • func (im IBCMiddleware) OnChanCloseConfirm(ctx context.Context, portID, channelID string) error
  • func (im IBCMiddleware) OnChanCloseInit(ctx context.Context, portID, channelID string) error
  • func (im IBCMiddleware) OnChanOpenAck(ctx context.Context, ...) error
  • func (im IBCMiddleware) OnChanOpenConfirm(ctx context.Context, portID, channelID string) error
  • func (im IBCMiddleware) OnChanOpenInit(ctx context.Context, channelOrdering channeltypes.Order, ...) (string, error)
  • func (im IBCMiddleware) OnChanOpenTry(ctx context.Context, channelOrdering channeltypes.Order, ...) (string, error)
  • func (im IBCMiddleware) OnChanUpgradeAck(ctx context.Context, portID, channelID, counterpartyVersion string) error
  • func (im IBCMiddleware) OnChanUpgradeInit(ctx context.Context, portID, channelID string, ...) (string, error)
  • func (im IBCMiddleware) OnChanUpgradeOpen(ctx context.Context, portID, channelID string, ...)
  • func (im IBCMiddleware) OnChanUpgradeTry(ctx context.Context, portID, channelID string, ...) (string, error)
  • func (im IBCMiddleware) OnRecvPacket(ctx context.Context, channelVersion string, packet channeltypes.Packet, ...) ibcexported.Acknowledgement
  • func (im IBCMiddleware) OnTimeoutPacket(ctx context.Context, channelVersion string, packet channeltypes.Packet, ...) error
  • func (im IBCMiddleware) SendPacket(ctx context.Context, sourcePort string, sourceChannel string, ...) (uint64, error)
  • func (im IBCMiddleware) UnmarshalPacketData(ctx context.Context, portID string, channelID string, bz []byte) (interface{}, string, error)
  • func (im *IBCMiddleware) WithICS4Wrapper(wrapper porttypes.ICS4Wrapper)
  • func (im IBCMiddleware) WriteAcknowledgement(ctx context.Context, packet ibcexported.PacketI, ...) error

Types

type IBCMiddleware

type IBCMiddleware struct {
	// contains filtered or unexported fields
}

IBCMiddleware implements the ICS26 callbacks for the ibc-callbacks middleware given the underlying application.

func NewIBCMiddleware

func NewIBCMiddleware(
	app porttypes.IBCModule, ics4Wrapper porttypes.ICS4Wrapper,
	contractKeeper types.ContractKeeper, maxCallbackGas uint64,
) IBCMiddleware

NewIBCMiddleware creates a new IBCMiddleware given the keeper and underlying application. The underlying application must implement the required callback interfaces.

func (IBCMiddleware) GetAppVersion

func (im IBCMiddleware) GetAppVersion(ctx context.Context, portID, channelID string) (string, bool)

GetAppVersion implements the ICS4Wrapper interface. Callbacks has no version, so the call is deferred to the underlying application.

func (*IBCMiddleware) GetICS4Wrapper

func (im *IBCMiddleware) GetICS4Wrapper() porttypes.ICS4Wrapper

GetICS4Wrapper returns the ICS4Wrapper.

func (IBCMiddleware) OnAcknowledgementPacket

func (im IBCMiddleware) OnAcknowledgementPacket(
	ctx context.Context,
	channelVersion string,
	packet channeltypes.Packet,
	acknowledgement []byte,
	relayer sdk.AccAddress,
) error

OnAcknowledgementPacket implements source callbacks for acknowledgement packets. It defers to the underlying application and then calls the contract callback. If the contract callback runs out of gas and may be retried with a higher gas limit then the state changes are reverted via a panic.

func (IBCMiddleware) OnChanCloseConfirm

func (im IBCMiddleware) OnChanCloseConfirm(ctx context.Context, portID, channelID string) error

OnChanCloseConfirm defers to the underlying application

func (IBCMiddleware) OnChanCloseInit

func (im IBCMiddleware) OnChanCloseInit(ctx context.Context, portID, channelID string) error

OnChanCloseInit defers to the underlying application

func (IBCMiddleware) OnChanOpenAck

func (im IBCMiddleware) OnChanOpenAck(
	ctx context.Context,
	portID,
	channelID,
	counterpartyChannelID,
	counterpartyVersion string,
) error

OnChanOpenAck defers to the underlying application

func (IBCMiddleware) OnChanOpenConfirm

func (im IBCMiddleware) OnChanOpenConfirm(ctx context.Context, portID, channelID string) error

OnChanOpenConfirm defers to the underlying application

func (IBCMiddleware) OnChanOpenInit

func (im IBCMiddleware) OnChanOpenInit(
	ctx context.Context,
	channelOrdering channeltypes.Order,
	connectionHops []string,
	portID,
	channelID string,
	counterparty channeltypes.Counterparty,
	version string,
) (string, error)

OnChanOpenInit defers to the underlying application

func (IBCMiddleware) OnChanOpenTry

func (im IBCMiddleware) OnChanOpenTry(
	ctx context.Context,
	channelOrdering channeltypes.Order,
	connectionHops []string, portID,
	channelID string,
	counterparty channeltypes.Counterparty,
	counterpartyVersion string,
) (string, error)

OnChanOpenTry defers to the underlying application

func (IBCMiddleware) OnChanUpgradeAck

func (im IBCMiddleware) OnChanUpgradeAck(ctx context.Context, portID, channelID, counterpartyVersion string) error

OnChanUpgradeAck implements the IBCModule interface

func (IBCMiddleware) OnChanUpgradeInit

func (im IBCMiddleware) OnChanUpgradeInit(ctx context.Context, portID, channelID string, proposedOrder channeltypes.Order, proposedConnectionHops []string, proposedVersion string) (string, error)

OnChanUpgradeInit implements the IBCModule interface

func (IBCMiddleware) OnChanUpgradeOpen

func (im IBCMiddleware) OnChanUpgradeOpen(ctx context.Context, portID, channelID string, proposedOrder channeltypes.Order, proposedConnectionHops []string, proposedVersion string)

OnChanUpgradeOpen implements the IBCModule interface

func (IBCMiddleware) OnChanUpgradeTry

func (im IBCMiddleware) OnChanUpgradeTry(ctx context.Context, portID, channelID string, proposedOrder channeltypes.Order, proposedConnectionHops []string, counterpartyVersion string) (string, error)

OnChanUpgradeTry implements the IBCModule interface

func (IBCMiddleware) OnRecvPacket

func (im IBCMiddleware) OnRecvPacket(ctx context.Context, channelVersion string, packet channeltypes.Packet, relayer sdk.AccAddress) ibcexported.Acknowledgement

OnRecvPacket implements the ReceivePacket destination callbacks for the ibc-callbacks middleware during synchronous packet acknowledgement. It defers to the underlying application and then calls the contract callback. If the contract callback runs out of gas and may be retried with a higher gas limit then the state changes are reverted via a panic.

func (IBCMiddleware) OnTimeoutPacket

func (im IBCMiddleware) OnTimeoutPacket(ctx context.Context, channelVersion string, packet channeltypes.Packet, relayer sdk.AccAddress) error

OnTimeoutPacket implements timeout source callbacks for the ibc-callbacks middleware. It defers to the underlying application and then calls the contract callback. If the contract callback runs out of gas and may be retried with a higher gas limit then the state changes are reverted via a panic.

func (IBCMiddleware) SendPacket

func (im IBCMiddleware) SendPacket(
	ctx context.Context,
	sourcePort string,
	sourceChannel string,
	timeoutHeight clienttypes.Height,
	timeoutTimestamp uint64,
	data []byte,
) (uint64, error)

SendPacket implements source callbacks for sending packets. It defers to the underlying application and then calls the contract callback. If the contract callback returns an error, panics, or runs out of gas, then the packet send is rejected.

func (IBCMiddleware) UnmarshalPacketData

func (im IBCMiddleware) UnmarshalPacketData(ctx context.Context, portID string, channelID string, bz []byte) (interface{}, string, error)

UnmarshalPacketData defers to the underlying app to unmarshal the packet data. This function implements the optional PacketDataUnmarshaler interface.

func (*IBCMiddleware) WithICS4Wrapper

func (im *IBCMiddleware) WithICS4Wrapper(wrapper porttypes.ICS4Wrapper)

WithICS4Wrapper sets the ICS4Wrapper. This function may be used after the middleware's creation to set the middleware which is above this module in the IBC application stack.

func (IBCMiddleware) WriteAcknowledgement

func (im IBCMiddleware) WriteAcknowledgement(
	ctx context.Context,
	packet ibcexported.PacketI,
	ack ibcexported.Acknowledgement,
) error

WriteAcknowledgement implements the ReceivePacket destination callbacks for the ibc-callbacks middleware during asynchronous packet acknowledgement. It defers to the underlying application and then calls the contract callback. If the contract callback runs out of gas and may be retried with a higher gas limit then the state changes are reverted via a panic.