diff --git a/docs/ibc/middleware/develop.md b/docs/ibc/middleware/develop.md index a6f1b5cd1d4..366a2b89f42 100644 --- a/docs/ibc/middleware/develop.md +++ b/docs/ibc/middleware/develop.md @@ -77,8 +77,11 @@ In the case where the middleware wishes to send a packet or acknowledgment witho ### Handshake callbacks +#### `OnChanOpenInit` + ```go -func (im IBCModule) OnChanOpenInit(ctx sdk.Context, +func (im IBCModule) OnChanOpenInit( + ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID string, @@ -92,9 +95,9 @@ func (im IBCModule) OnChanOpenInit(ctx sdk.Context, // otherwise, pass version directly to app callback. metadata, err := Unmarshal(version) if err != nil { - // Since it is valid for fee version to not be specified, the above middleware version may be for a middleware - // pass the entire version string onto the underlying - // application. + // Since it is valid for fee version to not be specified, + // the above middleware version may be for another middleware. + // Pass the entire version string onto the underlying application. return im.app.OnChanOpenInit( ctx, order, @@ -130,7 +133,13 @@ func (im IBCModule) OnChanOpenInit(ctx sdk.Context, return version, nil } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L34-L82) an example implementation of this callback for the ICS29 Fee Middleware module. +#### `OnChanOpenTry` + +```go func OnChanOpenTry( ctx sdk.Context, order channeltypes.Order, @@ -182,7 +191,13 @@ func OnChanOpenTry( return version, nil } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L84-L124) an example implementation of this callback for the ICS29 Fee Middleware module. +#### `OnChanOpenAck` + +```go func OnChanOpenAck( ctx sdk.Context, portID, @@ -206,7 +221,13 @@ func OnChanOpenAck( // call the underlying applications OnChanOpenTry callback return app.OnChanOpenAck(ctx, portID, channelID, counterpartyChannelID, cpMetadata.AppVersion) } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L126-L152) an example implementation of this callback for the ICS29 Fee Middleware module. +### `OnChanOpenConfirm` + +```go func OnChanOpenConfirm( ctx sdk.Context, portID, @@ -216,7 +237,13 @@ func OnChanOpenConfirm( return app.OnChanOpenConfirm(ctx, portID, channelID) } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L154-L162) an example implementation of this callback for the ICS29 Fee Middleware module. +#### `OnChanCloseInit` + +```go func OnChanCloseInit( ctx sdk.Context, portID, @@ -226,7 +253,13 @@ func OnChanCloseInit( return app.OnChanCloseInit(ctx, portID, channelID) } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L164-L187) an example implementation of this callback for the ICS29 Fee Middleware module. +#### `OnChanCloseConfirm` + +```go func OnChanCloseConfirm( ctx sdk.Context, portID, @@ -238,12 +271,16 @@ func OnChanCloseConfirm( } ``` -NOTE: Middleware that does not need to negotiate with a counterparty middleware on the remote stack will not implement the version unmarshalling and negotiation, and will simply perform its own custom logic on the callbacks without relying on the counterparty behaving similarly. +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L189-L212) an example implementation of this callback for the ICS29 Fee Middleware module. + +**NOTE**: Middleware that does not need to negotiate with a counterparty middleware on the remote stack will not implement the version unmarshalling and negotiation, and will simply perform its own custom logic on the callbacks without relying on the counterparty behaving similarly. ### Packet callbacks The packet callbacks just like the handshake callbacks wrap the application's packet callbacks. The packet callbacks are where the middleware performs most of its custom logic. The middleware may read the packet flow data and perform some additional packet handling, or it may modify the incoming data before it reaches the underlying application. This enables a wide degree of usecases, as a simple base application like token-transfer can be transformed for a variety of usecases by combining it with custom middleware. +#### `OnRecvPacket` + ```go func OnRecvPacket( ctx sdk.Context, @@ -257,7 +294,13 @@ func OnRecvPacket( doCustomLogic(ack) // middleware may modify outgoing ack return ack } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L214-L237) an example implementation of this callback for the ICS29 Fee Middleware module. +#### `OnAcknowledgementPacket` + +```go func OnAcknowledgementPacket( ctx sdk.Context, packet channeltypes.Packet, @@ -268,7 +311,13 @@ func OnAcknowledgementPacket( return app.OnAcknowledgementPacket(ctx, packet, ack, relayer) } +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L239-L292) an example implementation of this callback for the ICS29 Fee Middleware module. + +#### `OnTimeoutPacket` +```go func OnTimeoutPacket( ctx sdk.Context, packet channeltypes.Packet, @@ -280,10 +329,31 @@ func OnTimeoutPacket( } ``` +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L294-L334) an example implementation of this callback for the ICS29 Fee Middleware module. + ### ICS-4 wrappers Middleware must also wrap ICS-4 so that any communication from the application to the `channelKeeper` goes through the middleware first. Similar to the packet callbacks, the middleware may modify outgoing acknowledgements and packets in any way it wishes. +#### `SendPacket` + +```go +func SendPacket( + ctx sdk.Context, + chanCap *capabilitytypes.Capability, + appPacket exported.PacketI, +) { + // middleware may modify packet + packet = doCustomLogic(appPacket) + + return ics4Keeper.SendPacket(ctx, chanCap, packet) +} +``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L336-L343) an example implementation of this function for the ICS29 Fee Middleware module. + +#### `WriteAcknowledgement` + ```go // only called for async acks func WriteAcknowledgement( @@ -297,18 +367,13 @@ func WriteAcknowledgement( return ics4Keeper.WriteAcknowledgement(packet, ack_bytes) } +``` -func SendPacket( - ctx sdk.Context, - chanCap *capabilitytypes.Capability, - appPacket exported.PacketI, -) { - // middleware may modify packet - packet = doCustomLogic(appPacket) +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L345-L353) an example implementation of this function for the ICS29 Fee Middleware module. - return ics4Keeper.SendPacket(ctx, chanCap, packet) -} +#### `GetAppVersion` +```go // middleware must return the underlying application version func GetAppVersion( ctx sdk.Context, @@ -333,3 +398,5 @@ func GetAppVersion( return metadata.AppVersion, true } ``` + +See [here](https://github.com/cosmos/ibc-go/blob/48a6ae512b4ea42c29fdf6c6f5363f50645591a2/modules/apps/29-fee/ibc_middleware.go#L355-L358) an example implementation of this function for the ICS29 Fee Middleware module.