300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
# ADR 015: IBC Packet Receiver
|
|
|
|
## Changelog
|
|
|
|
- 2019 Oct 22: Initial Draft
|
|
|
|
## Context
|
|
|
|
[ICS 26 - Routing Module](https://github.com/cosmos/ics/tree/master/spec/ics-026-routing-module) defines a function [`handlePacketRecv`](https://github.com/cosmos/ics/tree/master/spec/ics-026-routing-module#packet-relay).
|
|
|
|
In ICS 26, the routing module is defined as a layer above each application module
|
|
which verifies and routes messages to the destination modules. It is possible to
|
|
implement it as a separate module, however, we already have functionality to route
|
|
messages upon the destination identifiers in the baseapp. This ADR suggests
|
|
to utilize existing `baseapp.router` to route packets to application modules.
|
|
|
|
Generally, routing module callbacks have two separate steps in them,
|
|
verification and execution. This corresponds to the `AnteHandler`-`Handler`
|
|
model inside the SDK. We can do the verification inside the `AnteHandler`
|
|
in order to increase developer ergonomics by reducing boilerplate
|
|
verification code.
|
|
|
|
For atomic multi-message transaction, we want to keep the IBC related
|
|
state modification to be preserved even the application side state change
|
|
reverts. One of the example might be IBC token sending message following with
|
|
stake delegation which uses the tokens received by the previous packet message.
|
|
If the token receiving fails for any reason, we might not want to keep
|
|
executing the transaction, but we also don't want to abort the transaction
|
|
or the sequence and commitment will be reverted and the channel will be stuck.
|
|
This ADR suggests new `CodeType`, `CodeTxBreak`, to fix this problem.
|
|
|
|
## Decision
|
|
|
|
`PortKeeper` will have the capability key that is able to access only the
|
|
channels bound to the port. Entities that hold a `PortKeeper` will be
|
|
able to call the methods on it which are corresponding with the methods with
|
|
the same names on the `ChannelKeeper`, but only with the
|
|
allowed port. `ChannelKeeper.Port(string, ChannelChecker)` will be defined to
|
|
easily construct a capability-safe `PortKeeper`. This will be addressed in
|
|
another ADR and we will use insecure `ChannelKeeper` for now.
|
|
|
|
`baseapp.runMsgs` will break the loop over the messages if one of the handlers
|
|
returns `!Result.IsOK()`. However, the outer logic will write the cached
|
|
store if `Result.IsOK() || Result.Code.IsBreak()`. `Result.Code.IsBreak()` if
|
|
`Result.Code == CodeTxBreak`.
|
|
|
|
```go
|
|
func (app *BaseApp) runTx(tx Tx) (result Result) {
|
|
msgs := tx.GetMsgs()
|
|
|
|
// AnteHandler
|
|
if app.anteHandler != nil {
|
|
anteCtx, msCache := app.cacheTxContext(ctx)
|
|
newCtx, err := app.anteHandler(anteCtx, tx)
|
|
if !newCtx.IsZero() {
|
|
ctx = newCtx.WithMultiStore(ms)
|
|
}
|
|
|
|
if err != nil {
|
|
// error handling logic
|
|
return res
|
|
}
|
|
|
|
msCache.Write()
|
|
}
|
|
|
|
// Main Handler
|
|
runMsgCtx, msCache := app.cacheTxContext(ctx)
|
|
result = app.runMsgs(runMsgCtx, msgs)
|
|
// BEGIN modification made in this ADR
|
|
if result.IsOK() || result.IsBreak() {
|
|
// END
|
|
msCache.Write()
|
|
}
|
|
|
|
return result
|
|
}
|
|
```
|
|
|
|
The Cosmos SDK will define an `AnteDecorator` for IBC packet receiving. The
|
|
`AnteDecorator` will iterate over the messages included in the transaction, type
|
|
`switch` to check whether the message contains an incoming IBC packet, and if so
|
|
verify the Merkle proof.
|
|
|
|
```go
|
|
type ProofVerificationDecorator struct {
|
|
clientKeeper ClientKeeper
|
|
channelKeeper ChannelKeeper
|
|
}
|
|
|
|
func (pvr ProofVerificationDecorator) AnteHandle(ctx Context, tx Tx, simulate bool, next AnteHandler) (Context, error) {
|
|
for _, msg := range tx.GetMsgs() {
|
|
var err error
|
|
switch msg := msg.(type) {
|
|
case client.MsgUpdateClient:
|
|
err = pvr.clientKeeper.UpdateClient(msg.ClientID, msg.Header)
|
|
case channel.MsgPacket:
|
|
err = pvr.channelKeeper.RecvPacket(msg.Packet, msg.Proofs, msg.ProofHeight)
|
|
case chanel.MsgAcknowledgement:
|
|
err = pvr.channelKeeper.AcknowledgementPacket(msg.Acknowledgement, msg.Proof, msg.ProofHeight)
|
|
case channel.MsgTimeoutPacket:
|
|
err = pvr.channelKeeper.TimeoutPacket(msg.Packet, msg.Proof, msg.ProofHeight, msg.NextSequenceRecv)
|
|
case channel.MsgChannelOpenInit;
|
|
err = pvr.channelKeeper.CheckOpen(msg.PortID, msg.ChannelID, msg.Channel)
|
|
default:
|
|
continue
|
|
}
|
|
|
|
if err != nil {
|
|
return ctx, err
|
|
}
|
|
}
|
|
|
|
return next(ctx, tx, simulate)
|
|
}
|
|
```
|
|
|
|
Where `MsgUpdateClient`, `MsgPacket`, `MsgAcknowledgement`, `MsgTimeoutPacket`
|
|
are `sdk.Msg` types correspond to `handleUpdateClient`, `handleRecvPacket`,
|
|
`handleAcknowledgementPacket`, `handleTimeoutPacket` of the routing module,
|
|
respectively.
|
|
|
|
The side effects of `RecvPacket`, `VerifyAcknowledgement`,
|
|
`VerifyTimeout` will be extracted out into separated functions,
|
|
`WriteAcknowledgement`, `DeleteCommitment`, `DeleteCommitmentTimeout`, respectively,
|
|
which will be called by the application handlers after the execution.
|
|
|
|
`WriteAcknowledgement` writes the acknowledgement to the state that can be
|
|
verified by the counter-party chain and increments the sequence to prevent
|
|
double execution. `DeleteCommitment` will delete the commitment stored,
|
|
`DeleteCommitmentTimeout` will delete the commitment and close channel in case
|
|
of ordered channel.
|
|
|
|
```go
|
|
func (keeper ChannelKeeper) WriteAcknowledgement(ctx Context, packet Packet, ack []byte) {
|
|
keeper.SetPacketAcknowledgement(ctx, packet.GetDestPort(), packet.GetDestChannel(), packet.GetSequence(), ack)
|
|
keeper.SetNextSequenceRecv(ctx, packet.GetDestPort(), packet.GetDestChannel(), packet.GetSequence())
|
|
}
|
|
|
|
func (keeper ChannelKeeper) DeleteCommitment(ctx Context, packet Packet) {
|
|
keeper.deletePacketCommitment(ctx, packet.GetSourcePort(), packet.GetSourceChannel(), packet.GetSequence())
|
|
}
|
|
|
|
func (keeper ChannelKeeper) DeleteCommitmentTimeout(ctx Context, packet Packet) {
|
|
k.deletePacketCommitment(ctx, packet.GetSourcePort(), packet.GetSourceChannel(), packet.GetSequence())
|
|
|
|
if channel.Ordering == types.ORDERED [
|
|
channel.State = types.CLOSED
|
|
k.SetChannel(ctx, packet.GetSourcePort(), packet.GetSourceChannel(), channel)
|
|
}
|
|
}
|
|
```
|
|
|
|
Each application handler should call respective finalization methods on the `PortKeeper`
|
|
in order to increase sequence (in case of packet) or remove the commitment
|
|
(in case of acknowledgement and timeout).
|
|
Calling those functions implies that the application logic has successfully executed.
|
|
However, the handlers can return `Result` with `CodeTxBreak` after calling those methods
|
|
which will persist the state changes that has been already done but prevent any further
|
|
messages to be executed in case of semantically invalid packet. This will keep the sequence
|
|
increased in the previous IBC packets(thus preventing double execution) without
|
|
proceeding to the following messages.
|
|
In any case the application modules should never return state reverting result,
|
|
which will make the channel unable to proceed.
|
|
|
|
`ChannelKeeper.CheckOpen` method will be introduced. This will replace `onChanOpen*` defined
|
|
under the routing module specification. Instead of define each channel handshake callback
|
|
functions, application modules can provide `ChannelChecker` function with the `AppModule`
|
|
which will be injected to `ChannelKeeper.Port()` at the top level application.
|
|
`CheckOpen` will find the correct `ChennelChecker` using the
|
|
`PortID` and call it, which will return an error if it is unacceptable by the application.
|
|
|
|
The `ProofVerificationDecorator` will be inserted to the top level application.
|
|
It is not safe to make each module responsible to call proof verification
|
|
logic, whereas application can misbehave(in terms of IBC protocol) by
|
|
mistake.
|
|
|
|
The `ProofVerificationDecorator` should come right after the default sybil attack
|
|
resistent layer from the current `auth.NewAnteHandler`:
|
|
|
|
```go
|
|
// add IBC ProofVerificationDecorator to the Chain of
|
|
func NewAnteHandler(
|
|
ak keeper.AccountKeeper, supplyKeeper types.SupplyKeeper, ibcKeeper ibc.Keeper,
|
|
sigGasConsumer SignatureVerificationGasConsumer) sdk.AnteHandler {
|
|
return sdk.ChainAnteDecorators(
|
|
NewSetUpContextDecorator(), // outermost AnteDecorator. SetUpContext must be called first
|
|
...
|
|
NewIncrementSequenceDecorator(ak),
|
|
ibcante.ProofVerificationDecorator(ibcKeeper.ClientKeeper, ibcKeeper.ChannelKeeper), // innermost AnteDecorator
|
|
)
|
|
}
|
|
```
|
|
|
|
The implementation of this ADR will also create a `Data` field of the `Packet` of type `[]byte`, which can be deserialised by the receiving module into its own private type. It is up to the application modules to do this according to their own interpretation, not by the IBC keeper. This is crucial for dynamic IBC.
|
|
|
|
Example application-side usage:
|
|
|
|
```go
|
|
type AppModule struct {}
|
|
|
|
// CheckChannel will be provided to the ChannelKeeper as ChannelKeeper.Port(module.CheckChannel)
|
|
func (module AppModule) CheckChannel(portID, channelID string, channel Channel) error {
|
|
if channel.Ordering != UNORDERED {
|
|
return ErrUncompatibleOrdering()
|
|
}
|
|
if channel.CounterpartyPort != "bank" {
|
|
return ErrUncompatiblePort()
|
|
}
|
|
if channel.Version != "" {
|
|
return ErrUncompatibleVersion()
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func NewHandler(k Keeper) Handler {
|
|
return func(ctx Context, msg Msg) Result {
|
|
switch msg := msg.(type) {
|
|
case MsgTransfer:
|
|
return handleMsgTransfer(ctx, k, msg)
|
|
case ibc.MsgPacket:
|
|
var data PacketDataTransfer
|
|
if err := types.ModuleCodec.UnmarshalBinaryBare(msg.GetData(), &data); err != nil {
|
|
return err
|
|
}
|
|
return handlePacketDataTransfer(ctx, k, msg, data)
|
|
case ibc.MsgTimeoutPacket:
|
|
var data PacketDataTransfer
|
|
if err := types.ModuleCodec.UnmarshalBinaryBare(msg.GetData(), &data); err != nil {
|
|
return err
|
|
}
|
|
return handleTimeoutPacketDataTransfer(ctx, k, packet)
|
|
// interface { PortID() string; ChannelID() string; Channel() ibc.Channel }
|
|
// MsgChanInit, MsgChanTry implements ibc.MsgChannelOpen
|
|
case ibc.MsgChannelOpen:
|
|
return handleMsgChannelOpen(ctx, k, msg)
|
|
}
|
|
}
|
|
}
|
|
|
|
func handleMsgTransfer(ctx Context, k Keeper, msg MsgTransfer) Result {
|
|
err := k.SendTransfer(ctx,msg.PortID, msg.ChannelID, msg.Amount, msg.Sender, msg.Receiver)
|
|
if err != nil {
|
|
return sdk.ResultFromError(err)
|
|
}
|
|
|
|
return sdk.Result{}
|
|
}
|
|
|
|
func handlePacketDataTransfer(ctx Context, k Keeper, packet Packet, data PacketDataTransfer) Result {
|
|
err := k.ReceiveTransfer(ctx, packet.GetSourcePort(), packet.GetSourceChannel(), packet.GetDestinationPort(), packet.GetDestinationChannel(), data)
|
|
if err != nil {
|
|
// TODO: Source chain sent invalid packet, shutdown channel
|
|
}
|
|
k.ChannelKeeper.WriteAcknowledgement([]byte{0x00}) // WriteAcknowledgement increases the sequence, preventing double spending
|
|
return sdk.Result{}
|
|
}
|
|
|
|
func handleCustomTimeoutPacket(ctx Context, k Keeper, packet CustomPacket) Result {
|
|
err := k.RecoverTransfer(ctx, packet.GetSourcePort(), packet.GetSourceChannel(), packet.GetDestinationPort(), packet.GetDestinationChannel(), data)
|
|
if err != nil {
|
|
// This chain sent invalid packet or cannot recover the funds
|
|
panic(err)
|
|
}
|
|
k.ChannelKeeper.DeleteCommitmentTimeout(ctx, packet)
|
|
// packet timeout should not fail
|
|
return sdk.Result{}
|
|
}
|
|
|
|
func handleMsgChannelOpen(sdk.Context, k Keeper, msg MsgOpenChannel) Result {
|
|
k.AllocateEscrowAddress(ctx, msg.ChannelID())
|
|
return sdk.Result{}
|
|
}
|
|
```
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- Intuitive interface for developers - IBC handlers do not need to care about IBC authentication
|
|
- State change commitment logic is embedded into `baseapp.runTx` logic
|
|
|
|
### Negative
|
|
|
|
- Cannot support dynamic ports, routing is tied to the baseapp router
|
|
|
|
### Neutral
|
|
|
|
- Introduces new `AnteHandler` decorator.
|
|
- Dynamic ports can be supported using hierarchical port identifier, see #5290 for detail
|
|
|
|
## References
|
|
|
|
- Relevant comment: [cosmos/ics#289](https://github.com/cosmos/ics/issues/289#issuecomment-544533583)
|
|
- [ICS26 - Routing Module](https://github.com/cosmos/ics/blob/master/spec/ics-026-routing-module)
|