From 2efebe98707bdac872aef51025cc017347a0a36f Mon Sep 17 00:00:00 2001 From: crodriguezvega Date: Mon, 4 Jul 2022 10:17:46 +0200 Subject: [PATCH 1/2] docs: add links in middleware docs to fee middleware implementation --- docs/ibc/middleware/develop.md | 89 +++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 11 deletions(-) diff --git a/docs/ibc/middleware/develop.md b/docs/ibc/middleware/develop.md index 555dce4534e..e3cc8f16e77 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, @@ -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, + app_packet exported.PacketI, +) { + // middleware may modify packet + packet = doCustomLogic(app_packet) + + 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, - app_packet exported.PacketI, -) { - // middleware may modify packet - packet = doCustomLogic(app_packet) +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. \ No newline at end of file From ca4e34289f99732cc80f651823d3b9382d8b1af7 Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Mon, 4 Jul 2022 13:58:39 +0200 Subject: [PATCH 2/2] add extra line for better readability --- docs/ibc/middleware/develop.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ibc/middleware/develop.md b/docs/ibc/middleware/develop.md index 5d8795693c6..366a2b89f42 100644 --- a/docs/ibc/middleware/develop.md +++ b/docs/ibc/middleware/develop.md @@ -95,9 +95,9 @@ func (im IBCModule) OnChanOpenInit( // 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, @@ -399,4 +399,4 @@ func GetAppVersion( } ``` -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. \ No newline at end of file +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.