Skip to content

Commit

Permalink
docs: add links in middleware docs to fee middleware implementation (#…
Browse files Browse the repository at this point in the history 
…1641)

* docs: add links in middleware docs to fee middleware implementation

* add extra line for better readability
  • Loading branch information
@crodriguezvega
crodriguezvega authored Jul 4, 2022
1 parent 839b9db commit 563a88e
Showing 1 changed file with 81 additions and 14 deletions.
95 changes: 81 additions & 14 deletions docs/ibc/middleware/develop.md
View file
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 @@ -129,7 +132,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 @@ -181,7 +190,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 @@ -205,7 +220,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 @@ -215,7 +236,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 @@ -225,7 +252,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 @@ -237,12 +270,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 @@ -256,7 +293,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 @@ -267,7 +310,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 @@ -279,10 +328,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 @@ -296,18 +366,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 @@ -332,3 +397,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.

0 comments on commit 563a88e

Please sign in to comment.