diff --git a/CHANGELOG.md b/CHANGELOG.md index cb6e080f5f4..281715f19ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -58,6 +58,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (app/29-fee) [\#1305](https://github.com/cosmos/ibc-go/pull/1305) Change version string for fee module to `ics29-1` * (app/29-fee) [\#1341](https://github.com/cosmos/ibc-go/pull/1341) Check if the fee module is locked and if the fee module is enabled before refunding all fees * (testing/simapp) [\#1397](https://github.com/cosmos/ibc-go/pull/1397) Adding mock module to maccperms and adding check to ensure mock module is not a blocked account address. +* (core/02-client) [\#1570](https://github.com/cosmos/ibc-go/pull/1570) Emitting an event when handling an upgrade client proposal. ### Features diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5183df990c1..a15407fd54a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -224,7 +224,7 @@ module.exports = { title: "IBC Middleware Modules", children: [ { - title: "ICS29 Fee Middleware", + title: "Fee Middleware", directory: true, path: "/middleware", children: [ @@ -238,6 +238,26 @@ module.exports = { directory: false, path: "/middleware/ics29-fee/integration.html" }, + { + title: "End Users", + directory: false, + path: "/middleware/ics29-fee/end-users.html" + }, + { + title: "Fee Messages", + directory: false, + path: "/middleware/ics29-fee/msgs.html" + }, + { + title: "Fee Distribution", + directory: false, + path: "/middleware/ics29-fee/fee-distribution.html" + }, + { + title: "Events", + directory: false, + path: "/middleware/ics29-fee/events.html" + }, ] }, ] diff --git a/docs/apps/interchain-accounts/active-channels.md b/docs/apps/interchain-accounts/active-channels.md index c574ea87d85..d387bdea038 100644 --- a/docs/apps/interchain-accounts/active-channels.md +++ b/docs/apps/interchain-accounts/active-channels.md @@ -12,11 +12,11 @@ channel type that provides ordering of packets without the channel closing on ti When an Interchain Account is registered using the `RegisterInterchainAccount` API, a new channel is created on a particular port. During the `OnChanOpenAck` and `OnChanOpenConfirm` steps (controller & host chain) the `Active Channel` for this interchain account is stored in state. -It is possible to create a new channel using the same controller chain portID if the previously set `Active Channel` is now in a `CLOSED` state. This channel creation can be initialized programatically by sending a new `OnChanOpenInit` message like so: +It is possible to create a new channel using the same controller chain portID if the previously set `Active Channel` is now in a `CLOSED` state. This channel creation can be initialized programatically by sending a new `MsgChannelOpenInit` message like so: ```go - msg := channeltypes.NewMsgChannelOpenInit(portID, string(versionBytes), channeltypes.ORDERED, []string{connectionID}, icatypes.PortID, icatypes.ModuleName) - handler := k.msgRouter.Handler(msg) +msg := channeltypes.NewMsgChannelOpenInit(portID, string(versionBytes), channeltypes.ORDERED, []string{connectionID}, icatypes.PortID, icatypes.ModuleName) +handler := k.msgRouter.Handler(msg) ``` Alternatively, any relayer operator may initiate a new channel handshake for this interchain account once the previously set `Active Channel` is in a `CLOSED` state. This is done by initiating the channel handshake on the controller chain using the same portID associated with the interchain account in question. diff --git a/docs/apps/interchain-accounts/auth-modules.md b/docs/apps/interchain-accounts/auth-modules.md index fdff2385282..5d75409b3c4 100644 --- a/docs/apps/interchain-accounts/auth-modules.md +++ b/docs/apps/interchain-accounts/auth-modules.md @@ -38,15 +38,15 @@ func (im IBCModule) OnChanOpenInit( chanCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, version string, -) error { +) (string, error) { // the authentication module *must* claim the channel capability on OnChanOpenInit if err := im.keeper.ClaimCapability(ctx, chanCap, host.ChannelCapabilityPath(portID, channelID)); err != nil { - return err + return version, err } // perform custom logic - return nil + return version, nil } // OnChanOpenAck implements the IBCModule interface @@ -157,7 +157,7 @@ if err := keeper.icaControllerKeeper.RegisterInterchainAccount(ctx, connectionID return nil ``` -The `version` argument is used to support ICS29 fee middleware for relayer incentivization of ICS27 packets. Consumers of the `RegisterInterchainAccount` are expected to build the appropriate JSON encoded version string themselves and pass it accordingly. +The `version` argument is used to support ICS29 fee middleware for relayer incentivization of ICS27 packets. Consumers of the `RegisterInterchainAccount` are expected to build the appropriate JSON encoded version string themselves and pass it accordingly. If an empty string is passed in the `version` argument, then the version will be initialized to a default value in the `OnChanOpenInit` callback of the controller's handler, so that channel handshake can proceed. The following code snippet illustrates how to construct an appropriate interchain accounts `Metadata` and encode it as a JSON bytestring: diff --git a/docs/middleware/ics29-fee/end-users.md b/docs/middleware/ics29-fee/end-users.md new file mode 100644 index 00000000000..08857d21a37 --- /dev/null +++ b/docs/middleware/ics29-fee/end-users.md @@ -0,0 +1,31 @@ + + +# For end users + +Learn how to incentivize IBC packets using the ICS29 Fee Middleware module. {synopsis} + +## Pre-requisite readings + +* [Fee Middleware](overview.md) {prereq} + +## Summary + +Different types of end users: + +- CLI users who want to manually incentivize IBC packets +- Client developers + + +The Fee Middleware module allows end users to add a 'tip' to each IBC packet which will incentivize relayer operators to relay packets between chains. gRPC endpoints are exposed for client developers as well as a simple CLI for manually incentivizing IBC packets. + +## CLI Users + +For an in depth guide on how to use the ICS29 Fee Middleware module using the CLI please take a look at the [wiki](https://github.com/cosmos/ibc-go/wiki/Fee-enabled-fungible-token-transfers#asynchronous-incentivization-of-a-fungible-token-transfer) on the `ibc-go` repo. + +## Client developers + +Client developers can read more about the relevant ICS29 message types in the [Escrowing and paying out fees section](../ics29-fee/msgs.md). + +[CosmJS](https://github.com/cosmos/cosmjs) is a useful client library for signing and broadcasting Cosmos SDK messages. diff --git a/docs/middleware/ics29-fee/events.md b/docs/middleware/ics29-fee/events.md new file mode 100644 index 00000000000..04ab5b34cee --- /dev/null +++ b/docs/middleware/ics29-fee/events.md @@ -0,0 +1,35 @@ + + +# Events + +## `MsgPayPacketFee`, `MsgPayPacketFeeAsync` + +| Type | Attribute Key | Attribute Value | +|-------------------------|-----------------|-----------------| +| incentivized_ibc_packet | port_id | {portID} | +| incentivized_ibc_packet | channel_id | {channelID} | +| incentivized_ibc_packet | packet_sequence | {sequence} | +| incentivized_ibc_packet | recv_fee | {recvFee} | +| incentivized_ibc_packet | ack_fee | {ackFee} | +| incentivized_ibc_packet | timeout_fee | {timeoutFee} | +| message | module | fee-ibc | + +## `RegisterPayee` + +| Type | Attribute Key | Attribute Value | +|----------------|------------|--------------------| +| register_payee | relayer | {relayer} | +| register_payee | payee | {payee} | +| register_payee | channel_id | {channelID} | +| message | module | fee-ibc | + +## `RegisterCounterpartyPayee` + +| Type | Attribute Key | Attribute Value | +|-----------------------------|--------------------|---------------------| +| register_counterparty_payee | relayer | {relayer} | +| register_counterparty_payee | counterparty_payee | {counterpartyPayee} | +| register_counterparty_payee | channel_id | {channelID} | +| message | module | fee-ibc | diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md new file mode 100644 index 00000000000..0ca1bce921f --- /dev/null +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -0,0 +1,90 @@ + + +# Fee distribution + +Learn about payee registration for the distribution of packet fees. The following document is intended for relayer operators. {synopsis} + +## Pre-requisite readings + +* [Fee Middleware](overview.md) {prereq} + +Packet fees are divided into 3 distinct amounts in order to compensate relayer operators for packet relaying on fee enabled IBC channels. + +- `RecvFee`: The sum of all packet receive fees distributed to a payee for successful execution of `MsgRecvPacket`. +- `AckFee`: The sum of all packet acknowledgement fees distributed to a payee for successful execution of `MsgAcknowledgement`. +- `TimeoutFee`: The sum of all packet timeout fees distributed to a payee for successful execution of `MsgTimeout`. + +## Register a payee address for forward relaying + +As mentioned in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the forward relayer describes the actor who performs the submission of `MsgRecvPacket` on the destination chain. +Fee distribution for incentivized packet relays takes place on the packet source chain. +Relayer operators are expected to register a counterparty payee address, in order to be compensated accordingly with `RecvFee`s upon completion of a packet lifecycle. +The counterparty payee address registered on the destination chain is encoded into the packet acknowledgement and communicated as such to the source chain for fee distribution. +If a counterparty payee is not registered for the forward relayer on the destination chain, the escrowed fees will be refunded upon fee distribution. + +A transaction must be submitted to the destination chain including a `CounterpartyPayee` address of an account on the source chain. +The transaction must be signed by the `Relayer`. + +```go +type MsgRegisterCounterpartyPayee struct { + // unique port identifier + PortId string + // unique channel identifier + ChannelId string + // the relayer address + Relayer string + // the counterparty payee address + CounterpartyPayee string +} +``` + +This message is expected to fail if: + +- `PortId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators). +- `ChannelId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)). +- `Relayer` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)). +- `CounterpartyPayee` is empty. + +See below for an example CLI command: + +``` +simd tx ibc-fee register-counterparty-payee transfer channel-0 cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh osmo1v5y0tz01llxzf4c2afml8s3awue0ymju22wxx2 --from cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh +``` + +## Register a payee address for reverse and timeout relaying + +As mentioned in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the reverse relayer describes the actor who performs the submission of `MsgAcknowledgement` on the source chain. +Similarly the timeout relayer describes the actor who performs the submission of `MsgTimeout` (or `MsgTimeoutOnClose`) on the source chain. +Relayer operators may choose to register an optional payee address, in order to be compensated accordingly with `AckFee`s and `TimeoutFee`s upon completion of a packet life cycle. +If a payee is not registered for the reverse or timeout relayer on the source chain, then fee distribution assumes the default behaviour, where fees are paid out to the relayer account which delivers `MsgAcknowledgement` or `MsgTimeout`/`MsgTimeoutOnClose`. + +A transaction must be submitted to the source chain including a `Payee` address of an account on the source chain. +The transaction must be signed by the `Relayer`. + +```go +type MsgRegisterPayee struct { + // unique port identifier + PortId string + // unique channel identifier + ChannelId string + // the relayer address + Relayer string + // the payee address + Payee string +} +``` + +This message is expected to fail if: + +- `PortId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators). +- `ChannelId` is invalid (see [24-host naming requirements](https://github.com/cosmos/ibc/blob/master/spec/core/ics-024-host-requirements/README.md#paths-identifiers-separators)). +- `Relayer` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)). +- `Payee` is an invalid address (see [Cosmos SDK Addresses](https://github.com/cosmos/cosmos-sdk/blob/main/docs/basics/accounts.md#Addresses)). + +See below for an example CLI command: + +``` +simd tx ibc-fee register-payee transfer channel-0 cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh cosmos153lf4zntqt33a4v0sm5cytrxyqn78q7kz8j8x5 --from cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh +``` diff --git a/docs/middleware/ics29-fee/msgs.md b/docs/middleware/ics29-fee/msgs.md new file mode 100644 index 00000000000..7ab81cd9552 --- /dev/null +++ b/docs/middleware/ics29-fee/msgs.md @@ -0,0 +1,72 @@ + + +# Escrowing fees + +The fee middleware module exposes two different ways to pay fees for relaying IBC packets: + +1. `MsgPayPacketFee`, which enables the escrowing of fees for a packet at the next sequence send and should be combined into one `MultiMsgTx` with the message that will be paid for. + + Note that the `Relayers` field has been set up to allow for an optional whitelist of relayers permitted to receive this fee, however, this feature has not yet been enabled at this time. + + ``` + type MsgPayPacketFee struct{ + // fee encapsulates the recv, ack and timeout fees associated with an IBC packet + Fee Fee + // the source port unique identifier + SourcePortId string + // the source channel unique identifer + SourceChannelId string + // account address to refund fee if necessary + Signer string + // optional list of relayers permitted to the receive packet fee + Relayers []string + } + ``` + + The `Fee` message contained in this synchronous fee payment method configures different fees which will be paid out for `MsgRecvPacket`, `MsgAcknowledgement`, and `MsgTimeout`/`MsgTimeoutOnClose`. + + ``` + type Fee struct { + RecvFee types.Coins + AckFee types.Coins + TimeoutFee types.Coin` + } + ``` + +2. `MsgPayPacketFeeAsync`, which enables the asynchronous escrowing of fees for a specified packet: + + Note that a packet can be 'topped up' multiple times with additional fees of any coin denomination by broadcasting multiple `MsgPayPacketFeeAsync` messages. + + ``` + type MsgPayPacketFeeAsync struct { + // unique packet identifier comprised of the channel ID, port ID and sequence + PacketId channeltypes.PacketId + // the packet fee associated with a particular IBC packet + PacketFee PacketFee + } + ``` + + where the `PacketFee` also specifies the `Fee` to be paid as well as the refund address for fees which are not paid out + ``` + type PacketFee struct { + Fee Fee + RefundAddress string + Relayers []]string + } + ``` + +Please see our [wiki](https://github.com/cosmos/ibc-go/wiki/Fee-enabled-fungible-token-transfers) for example flows on how to use these messages to incentivise a token transfer channel using a CLI. + +# Paying out the escrowed fees + +In the case of a successful transaction, `RecvFee` will be paid out to the designated counterparty payee address which has been registered on the receiver chain and sent back with the `MsgAcknowledgement`, `AckFee` will be paid out to the relayer address which has submitted the `MsgAcknowledgement` on the sending chain (or the registered payee in case one has been registered for the relayer address), and `TimeoutFee` will be reimbursed to the account which escrowed the fee. In cases of timeout transactions, `RecvFee` and `AckFee` will be reimbursed. + +Please note that fee payments are built on the assumption that sender chains are the source of incentives — the chain that sends the packets is the same chain where fee payments will occur -- please see the [relayer operator section](../ics29-fee/fee-distribution.md) to understand the flow for registering payee and counterparty payee (fee receiving) addresses. + +# A locked fee middleware module + +The fee middleware module can become locked if the situation arises that the escrow account for the fees does not have sufficient funds to pay out the fees which have been escrowed for each packet. This situation indicates a severe bug. In this case, the fee module will be locked until manual intervention fixes the issue. + +A locked fee module will simply skip fee logic and continue on to the underlying packet flow. A channel with a locked fee module will temporarily function as a fee disabled channel, and the locking of a fee module will not affect the continued flow of packets over the channel. diff --git a/docs/migrations/v3-to-v4.md b/docs/migrations/v3-to-v4.md index 49f311a844e..1cd08f5bd49 100644 --- a/docs/migrations/v3-to-v4.md +++ b/docs/migrations/v3-to-v4.md @@ -30,7 +30,7 @@ The return signature now includes the application version as detailed in the lat The `RegisterInterchainAccount` API has been modified to include an additional `version` argument. This change has been made in order to support ICS29 fee middleware, for relayer incentivization of ICS27 packets. Consumers of the `RegisterInterchainAccount` are now expected to build the appropriate JSON encoded version string themselves and pass it accordingly. -This should be constructed within the interchain accounts authentication module which leverages the APIs exposed via the interchain accounts `controllerKeeper`. +This should be constructed within the interchain accounts authentication module which leverages the APIs exposed via the interchain accounts `controllerKeeper`. If an empty string is passed in the `version` argument, then the version will be initialized to a default value in the `OnChanOpenInit` callback of the controller's handler, so that channel handshake can proceed. The following code snippet illustrates how to construct an appropriate interchain accounts `Metadata` and encode it as a JSON bytestring: diff --git a/modules/apps/29-fee/keeper/events.go b/modules/apps/29-fee/keeper/events.go index b3b26400803..162542f4e4d 100644 --- a/modules/apps/29-fee/keeper/events.go +++ b/modules/apps/29-fee/keeper/events.go @@ -27,7 +27,7 @@ func EmitIncentivizedPacketEvent(ctx sdk.Context, packetID channeltypes.PacketId } } - ctx.EventManager().EmitEvent( + ctx.EventManager().EmitEvents(sdk.Events{ sdk.NewEvent( types.EventTypeIncentivizedPacket, sdk.NewAttribute(channeltypes.AttributeKeyPortID, packetID.PortId), @@ -37,7 +37,11 @@ func EmitIncentivizedPacketEvent(ctx sdk.Context, packetID channeltypes.PacketId sdk.NewAttribute(types.AttributeKeyAckFee, totalAckFees.String()), sdk.NewAttribute(types.AttributeKeyTimeoutFee, totalTimeoutFees.String()), ), - ) + sdk.NewEvent( + sdk.EventTypeMessage, + sdk.NewAttribute(sdk.AttributeKeyModule, types.ModuleName), + ), + }) } // EmitRegisterPayeeEvent emits an event containing information of a registered payee for a relayer on a particular channel diff --git a/modules/core/02-client/keeper/events.go b/modules/core/02-client/keeper/events.go index 21a32c49c9b..0702651a611 100644 --- a/modules/core/02-client/keeper/events.go +++ b/modules/core/02-client/keeper/events.go @@ -1,6 +1,8 @@ package keeper import ( + "fmt" + sdk "github.com/cosmos/cosmos-sdk/types" "github.com/cosmos/ibc-go/v4/modules/core/02-client/types" @@ -68,6 +70,17 @@ func EmitUpdateClientProposalEvent(ctx sdk.Context, clientID string, clientState ) } +// EmitUpgradeClientProposalEvent emits an upgrade client proposal event +func EmitUpgradeClientProposalEvent(ctx sdk.Context, title string, height int64) { + ctx.EventManager().EmitEvent( + sdk.NewEvent( + types.EventTypeUpgradeClientProposal, + sdk.NewAttribute(types.AttributeKeyUpgradePlanTitle, title), + sdk.NewAttribute(types.AttributeKeyUpgradePlanHeight, fmt.Sprintf("%d", height)), + ), + ) +} + // EmitSubmitMisbehaviourEvent emits a client misbehaviour event func EmitSubmitMisbehaviourEvent(ctx sdk.Context, clientID string, clientState exported.ClientState) { ctx.EventManager().EmitEvent( diff --git a/modules/core/02-client/keeper/proposal.go b/modules/core/02-client/keeper/proposal.go index a52437e91b2..4b182e5e7c3 100644 --- a/modules/core/02-client/keeper/proposal.go +++ b/modules/core/02-client/keeper/proposal.go @@ -98,5 +98,12 @@ func (k Keeper) HandleUpgradeProposal(ctx sdk.Context, p *types.UpgradeProposal) // sets the new upgraded client in last height committed on this chain is at plan.Height, // since the chain will panic at plan.Height and new chain will resume at plan.Height - return k.upgradeKeeper.SetUpgradedClient(ctx, p.Plan.Height, bz) + if err = k.upgradeKeeper.SetUpgradedClient(ctx, p.Plan.Height, bz); err != nil { + return err + } + + // emitting an event for handling client upgrade proposal + EmitUpgradeClientProposalEvent(ctx, p.Title, p.Plan.Height) + + return nil } diff --git a/modules/core/02-client/types/events.go b/modules/core/02-client/types/events.go index dda21daf7ae..d23f6d24e02 100644 --- a/modules/core/02-client/types/events.go +++ b/modules/core/02-client/types/events.go @@ -8,20 +8,23 @@ import ( // IBC client events const ( - AttributeKeyClientID = "client_id" - AttributeKeySubjectClientID = "subject_client_id" - AttributeKeyClientType = "client_type" - AttributeKeyConsensusHeight = "consensus_height" - AttributeKeyHeader = "header" + AttributeKeyClientID = "client_id" + AttributeKeySubjectClientID = "subject_client_id" + AttributeKeyClientType = "client_type" + AttributeKeyConsensusHeight = "consensus_height" + AttributeKeyHeader = "header" + AttributeKeyUpgradePlanTitle = "title" + AttributeKeyUpgradePlanHeight = "height" ) // IBC client events vars var ( - EventTypeCreateClient = "create_client" - EventTypeUpdateClient = "update_client" - EventTypeUpgradeClient = "upgrade_client" - EventTypeSubmitMisbehaviour = "client_misbehaviour" - EventTypeUpdateClientProposal = "update_client_proposal" + EventTypeCreateClient = "create_client" + EventTypeUpdateClient = "update_client" + EventTypeUpgradeClient = "upgrade_client" + EventTypeSubmitMisbehaviour = "client_misbehaviour" + EventTypeUpdateClientProposal = "update_client_proposal" + EventTypeUpgradeClientProposal = "upgrade_client_proposal" AttributeValueCategory = fmt.Sprintf("%s_%s", host.ModuleName, SubModuleName) )