diff --git a/docs/ibc/apps/ibcmodule.md b/docs/ibc/apps/ibcmodule.md index 510fd5bcf31..ec68681ced6 100644 --- a/docs/ibc/apps/ibcmodule.md +++ b/docs/ibc/apps/ibcmodule.md @@ -347,3 +347,26 @@ func (im IBCModule) OnTimeoutPacket( // 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: + +```go +// 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. diff --git a/docs/ibc/apps/packets_acks.md b/docs/ibc/apps/packets_acks.md index 1d5061cf03f..fda814324f9 100644 --- a/docs/ibc/apps/packets_acks.md +++ b/docs/ibc/apps/packets_acks.md @@ -68,6 +68,55 @@ packetData := DecodePacketData(packet.Data) // handle received custom packet data ``` + +### Optional interfaces + +The following interfaces are optional and MAY be implemented by a custom packet type. +They allow middlewares such as callbacks to access information stored within the packet data. + +#### PacketData interface + +The `PacketData` interface is defined as follows: + +```go +// PacketData defines an optional interface which an application's packet data structure may implement. +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 +} +``` + +The implementation of `GetPacketSender` should return the sender of the packet data. +If the packet sender is unknown or undefined, an empty string should be returned. + +This interface is intended to give IBC middlewares access to the packet sender of a packet data type. + +#### PacketDataProvider interface + +The `PacketDataProvider` interface is defined as follows: + +```go +// 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 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{} +} +``` + +The implementation of `GetCustomPacketData` should return packet data held on behalf of another application (if present and supported). +If this functionality is not supported, it should return nil. Otherwise it should return the packet data associated with the provided key. + +This interface gives IBC applications access to the packet data information embedded into the base packet data type. +Within transfer and interchain accounts, the embedded packet data is stored within the Memo field. + +Once all IBC applications within an IBC stack are capable of creating/maintaining their own packet data type's, this interface function will be deprecated and removed. + ## Acknowledgements Modules may commit an acknowledgement upon receiving and processing a packet in the case of synchronous packet processing.