From 96f3c49f2711498d968b29f72a8122c88b8e16e5 Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 10 Jun 2022 14:22:22 +0200 Subject: [PATCH 1/5] fix broken link --- docs/middleware/ics29-fee/overview.md | 33 +++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/middleware/ics29-fee/overview.md diff --git a/docs/middleware/ics29-fee/overview.md b/docs/middleware/ics29-fee/overview.md new file mode 100644 index 00000000000..86153f21067 --- /dev/null +++ b/docs/middleware/ics29-fee/overview.md @@ -0,0 +1,33 @@ + + +# Overview + +Learn about what the Fee Middleware module is, and how to build custom modules that utilize the Fee Middleware functionality {synopsis} + +## What is the Fee Middleware module? + +IBC does not depend on relayer operators for transaction verification. However, the relayer infrastructure ensures liveness of the Interchain network — operators listen for packets sent through channels opened between chains, and perform the vital service of ferrying these packets (and proof of the transaction on the sending chain/receipt on the receiving chain) to the clients on each side of the channel. + +Though relaying is permissionless and completely decentralized and accessible, it does come with operational costs. Running full nodes to query transaction proofs and paying for transaction fees associated with IBC packets are two of the primary cost burdens which have driven the overall discussion on a general, in-protocol incentivization mechanism for relayers. + +Initially, a [simple proposal](https://github.com/cosmos/ibc/pull/577/files) was created to incentivize relaying on ICS20 token transfers on the destination chain. However, the proposal was specific to ICS20 token transfers and would have to be reimplemented in this format on every other IBC application module. + +After much discussion, the proposal was expanded to a [general incentivisation design](https://github.com/cosmos/ibc/tree/master/spec/app/ics-029-fee-payment) that can be adopted by any ICS application protocol as [middleware](../../ibc/middleware/develop.md). THe first version of fee payments middleware will only support incentivisation of new channels, however, channel upgradeability will enable incentivisation of all existing channels. + +## Concepts + +ICS29 fee payments in this middleware design are built on the assumption that sender chains are the source of incentives — the chain that sends the packets is the same chain that pays out fees to operators. Therefore, the middleware enables the registering of addresses associated with each party involved in relaying the packet on the source chain, and the escrowing of fees by any party which will be paid out to each party on completion of the packet lifecycle. This registration process can be automated on start up of relayer infrastructure. + +`forward relayer`: The relayer that submits the recvPacket message for a given packet (on the destination chain) + +`reverse relayer`: The relayer that submits the acknowledgePacket message for a given packet (on the source chain) + +`timeout relayer`: The relayer that submits the timeoutPacket or timeoutOnClose messages for a given packet (on the source chain) + +`payee`: The account address on the source chain to be paid on completion of the packet lifecycle + +`counterparty payee`: The account address to be paid on completion of the packet lifecycle on the destination chain + +`refund address`: The address of the account paying for the fees \ No newline at end of file From ed4a153be5d98d751e9200bfc693fb513b90cdf2 Mon Sep 17 00:00:00 2001 From: Charly Date: Tue, 14 Jun 2022 09:38:21 +0200 Subject: [PATCH 2/5] fix: rm AllowUpdateAfter... check (#1118) * update code & test * update proto and adr026 * update CHANGELOG * update cli docs * update broken milestone link --- docs/.vuepress/config.js | 17 +++++++++++++++++ docs/middleware/ics29-fee/overview.md | 20 ++++++++++++-------- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 43bd93590cd..7bb36d7c0f8 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -166,6 +166,23 @@ module.exports = { }, ] }, + { + title: "IBC Middleware Modules", + children: [ + { + title: "ICS29 Fee Middleware", + directory: true, + path: "/middleware", + children: [ + { + title: "Overview", + directory: false, + path: "/middleware/ics29-fee/overview.html" + }, + ] + }, + ] + }, { title: "Migrations", children: [ diff --git a/docs/middleware/ics29-fee/overview.md b/docs/middleware/ics29-fee/overview.md index 86153f21067..e23261c712e 100644 --- a/docs/middleware/ics29-fee/overview.md +++ b/docs/middleware/ics29-fee/overview.md @@ -14,20 +14,24 @@ Though relaying is permissionless and completely decentralized and accessible, i Initially, a [simple proposal](https://github.com/cosmos/ibc/pull/577/files) was created to incentivize relaying on ICS20 token transfers on the destination chain. However, the proposal was specific to ICS20 token transfers and would have to be reimplemented in this format on every other IBC application module. -After much discussion, the proposal was expanded to a [general incentivisation design](https://github.com/cosmos/ibc/tree/master/spec/app/ics-029-fee-payment) that can be adopted by any ICS application protocol as [middleware](../../ibc/middleware/develop.md). THe first version of fee payments middleware will only support incentivisation of new channels, however, channel upgradeability will enable incentivisation of all existing channels. +After much discussion, the proposal was expanded to a [general incentivisation design](https://github.com/cosmos/ibc/tree/master/spec/app/ics-029-fee-payment) that can be adopted by any ICS application protocol as [middleware](../../ibc/middleware/develop.md). ## Concepts -ICS29 fee payments in this middleware design are built on the assumption that sender chains are the source of incentives — the chain that sends the packets is the same chain that pays out fees to operators. Therefore, the middleware enables the registering of addresses associated with each party involved in relaying the packet on the source chain, and the escrowing of fees by any party which will be paid out to each party on completion of the packet lifecycle. This registration process can be automated on start up of relayer infrastructure. +ICS29 fee payments in this middleware design are built on the assumption that sender chains are the source of incentives — the chain on which packets are sent is the same chain that fee distribution to relayer operators takes place. Therefore, the middleware enables the registering of addresses associated with each party involved in relaying the packet on the source chain, and the escrowing of fees by any party which will be paid out to each party on completion of the packet lifecycle. This registration process can be automated on start up of relayer infrastructure. -`forward relayer`: The relayer that submits the recvPacket message for a given packet (on the destination chain) +`Forward relayer`: The relayer that submits the `MsgRecvPacket` message for a given packet (on the destination chain). -`reverse relayer`: The relayer that submits the acknowledgePacket message for a given packet (on the source chain) +`Reverse relayer`: The relayer that submits the `MsgAcknowledgement` message for a given packet (on the source chain). -`timeout relayer`: The relayer that submits the timeoutPacket or timeoutOnClose messages for a given packet (on the source chain) +`Timeout relayer`: The relayer that submits the `MsgTimeout` or `MsgTimeoutOnClose` messages for a given packet (on the source chain). -`payee`: The account address on the source chain to be paid on completion of the packet lifecycle +`Payee`: The account address on the source chain to be paid on completion of the packet lifecycle. The packet lifecycle on the source chain completes with the receipt of a `MsgTimeout`/`MsgTimeoutOnClose` or a `MsgAcknowledgement`. -`counterparty payee`: The account address to be paid on completion of the packet lifecycle on the destination chain +`Counterparty payee`: The account address to be paid on completion of the packet lifecycle on the destination chain. The package lifecycle on the destination chain completes with a successful `MsgRecvPacket`. -`refund address`: The address of the account paying for the fees \ No newline at end of file +`Refund address`: The address of the account paying for the incentivization of packet relaying. The account is refunded timeout fees upon successful acknowledgement. In the event of a packet timeout, both acknowledgement and receive fees are refunded. + +## Known Limitations + +The first version of fee payments middleware will only support incentivisation of new channels, however, channel upgradeability will enable incentivisation of all existing channels. From a06b2f3ca9424f5786de4141b4786253a7f15fb1 Mon Sep 17 00:00:00 2001 From: Charly Date: Thu, 23 Jun 2022 17:50:26 +0200 Subject: [PATCH 3/5] updated docs --- docs/.vuepress/config.js | 2 +- docs/middleware/ics29-fee/msgs.md | 64 +++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 docs/middleware/ics29-fee/msgs.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index aaf668ffc97..313a7e47cf2 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -182,7 +182,7 @@ module.exports = { title: "IBC Middleware Modules", children: [ { - title: "ICS29 Fee Middleware", + title: "Fee Middleware", directory: true, path: "/middleware", children: [ diff --git a/docs/middleware/ics29-fee/msgs.md b/docs/middleware/ics29-fee/msgs.md new file mode 100644 index 00000000000..2fdce22a8a9 --- /dev/null +++ b/docs/middleware/ics29-fee/msgs.md @@ -0,0 +1,64 @@ + + +# Escrowing and paying out 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 the receive this fee, however, this feature has not yet been enabled at this time. + + ``` + MsgPayPacketFee{ + Fee Fee, + SourcePortId string, + SourceChannelId string, + Signer string, + Relayers []string, + } + ``` + + The `Fee` message contained in this synchronous fee payment method configures different fees which will be paid out for `RecvPackets`, `Acknowledgements`, and `Timeouts`. + + ``` + Fee { + RecvFee types.Coins + AckFee types.Coins + TimeoutFee types.Coins + + } + ``` + +2. `MsgPayPacketFeeAsync`, which enables the asynchronous escrowing of fees for a specified packet: + + ``` + MsgPayPacketFeeAsync{ + PacketId channeltypes.PacketId, + 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 + ``` + PacketFee { + 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. + +# 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 `Acknowledgement`, `AckFee` will be paid out to the relayer address which has submitted the `Acknowledgement` 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 section to understand the flow for registering 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 registered 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. \ No newline at end of file From 21ac60f50040ffbef6b34e7a8ae3061d4749b224 Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 24 Jun 2022 12:39:43 +0200 Subject: [PATCH 4/5] update re: comments --- docs/.vuepress/config.js | 5 +++++ docs/middleware/ics29-fee/msgs.md | 36 +++++++++++++++---------------- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index a70884792fc..6e705ca7b79 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -238,6 +238,11 @@ module.exports = { directory: false, path: "/middleware/ics29-fee/integration.html" }, + { + title: "Fee Messages", + directory: false, + path: "/middleware/ics29-fee/msgs.html" + }, ] }, ] diff --git a/docs/middleware/ics29-fee/msgs.md b/docs/middleware/ics29-fee/msgs.md index 2fdce22a8a9..5197f882ae4 100644 --- a/docs/middleware/ics29-fee/msgs.md +++ b/docs/middleware/ics29-fee/msgs.md @@ -8,25 +8,25 @@ The fee middleware module exposes two different ways to pay fees for relaying IB 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 the receive this fee, however, this feature has not yet been enabled at this time. + 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. ``` - MsgPayPacketFee{ - Fee Fee, - SourcePortId string, - SourceChannelId string, - Signer string, - Relayers []string, + type MsgPayPacketFee struct{ + Fee Fee + SourcePortId string + SourceChannelId string + Signer string + Relayers []string } ``` - The `Fee` message contained in this synchronous fee payment method configures different fees which will be paid out for `RecvPackets`, `Acknowledgements`, and `Timeouts`. + The `Fee` message contained in this synchronous fee payment method configures different fees which will be paid out for `MsgRecvPacket`, `MsgAcknowledgement`, and `MsgTimeout`/`MsgTimeoutOnClose`. ``` - Fee { + type Fee struct { RecvFee types.Coins AckFee types.Coins - TimeoutFee types.Coins + TimeoutFee types.Coin` } ``` @@ -34,15 +34,15 @@ The fee middleware module exposes two different ways to pay fees for relaying IB 2. `MsgPayPacketFeeAsync`, which enables the asynchronous escrowing of fees for a specified packet: ``` - MsgPayPacketFeeAsync{ - PacketId channeltypes.PacketId, - PacketFee PacketFee, + type MsgPayPacketFeeAsync struct { + PacketId channeltypes.PacketId + 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 + where the `PacketFee` also specifies the `Fee` to be paid as well as the refund address for fees which are not paid out ``` - PacketFee { + type PacketFee struct { Fee Fee RefundAddress string Relayers []]string @@ -53,12 +53,12 @@ Please see our [wiki](https://github.com/cosmos/ibc-go/wiki/Fee-enabled-fungible # 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 `Acknowledgement`, `AckFee` will be paid out to the relayer address which has submitted the `Acknowledgement` 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. +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 section to understand the flow for registering fee-receiving addresses. +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 [our wiki](https://github.com/cosmos/ibc-go/wiki/Fee-enabled-fungible-token-transfers#register-the-counterparty-payee) 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 registered for each packet. This situation indicates a severe bug. In this case, the fee module will be locked until manual intervention fixes the issue. +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. \ No newline at end of file From c4412fe3533fded5eb43d1fdfb59dc7c5a635fac Mon Sep 17 00:00:00 2001 From: Sean King Date: Mon, 27 Jun 2022 17:27:57 +0200 Subject: [PATCH 5/5] nits: adding inline comments --- docs/.vuepress/config.js | 3 ++- docs/middleware/ics29-fee/msgs.md | 25 ++++++++++++++++--------- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 2ddfffa1d84..a6da1d7ad8c 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -242,7 +242,8 @@ module.exports = { title: "Fee Messages", directory: false, path: "/middleware/ics29-fee/msgs.html" - } + }, + { title: "Fee Distribution", directory: false, path: "/middleware/ics29-fee/fee-distribution.html" diff --git a/docs/middleware/ics29-fee/msgs.md b/docs/middleware/ics29-fee/msgs.md index 299730e0fd1..91d67849236 100644 --- a/docs/middleware/ics29-fee/msgs.md +++ b/docs/middleware/ics29-fee/msgs.md @@ -12,11 +12,16 @@ The fee middleware module exposes two different ways to pay fees for relaying IB ``` type MsgPayPacketFee struct{ - Fee Fee - SourcePortId string - SourceChannelId string - Signer string - Relayers []string + // 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 } ``` @@ -34,9 +39,11 @@ The fee middleware module exposes two different ways to pay fees for relaying IB ``` type MsgPayPacketFeeAsync struct { - PacketId channeltypes.PacketId - PacketFee PacketFee - } + // 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 @@ -48,7 +55,7 @@ The fee middleware module exposes two different ways to pay fees for relaying IB } ``` -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. +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