Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add links in middleware docs to fee middleware implementation #1641

Merged
merged 3 commits into from
Jul 4, 2022
Merged

docs: add links in middleware docs to fee middleware implementation #1641

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2efebe9
docs: add links in middleware docs to fee middleware implementation
crodriguezvega Jul 4, 2022
390fa5a
Merge branch 'carlos/update-middleware-docs' into carlos/#699-middlew…
crodriguezvega Jul 4, 2022
ca4e342
add extra line for better readability
crodriguezvega Jul 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 81 additions & 14 deletions docs/ibc/middleware/develop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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(
Expand All @@ -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,
Expand All @@ -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.