From 96f3c49f2711498d968b29f72a8122c88b8e16e5 Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 10 Jun 2022 14:22:22 +0200 Subject: [PATCH 1/6] 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/6] 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 ac4034d21b80a0d45c27ae5b8da54ad917f794c2 Mon Sep 17 00:00:00 2001 From: Charly Date: Thu, 14 Jul 2022 18:52:45 +0200 Subject: [PATCH 3/6] updated fee middleware docs wrt invariants --- docs/middleware/ics29-fee/fee-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index 9cf3a821a21..6edbce375da 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -27,7 +27,7 @@ If a counterparty payee is not registered for the forward relayer on the destina 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`. -Note: If a module account address is used as the `CounterpartyPayee` it is recommended to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module. +Note: If a module account address is used as the `CounterpartyPayee` it may be necessary to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module, if the module has been set as a blocked address in the BankKeeper. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance in the bank keeper. If a send to the module account occurs without going through this module and updating its internal tracking, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, it is suggested that either invariant checks are turned off, or the module is removed from the blocked address list on the BankKeeper with the understanding that this may result in consequences for module balance accounting. ```go type MsgRegisterCounterpartyPayee struct { From 261bf773e1cc44eb40b2e24a0d2109f8bd982d8c Mon Sep 17 00:00:00 2001 From: Charly Date: Fri, 15 Jul 2022 13:18:33 +0200 Subject: [PATCH 4/6] second review --- docs/middleware/ics29-fee/fee-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index 6edbce375da..974f256400d 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -27,7 +27,7 @@ If a counterparty payee is not registered for the forward relayer on the destina 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`. -Note: If a module account address is used as the `CounterpartyPayee` it may be necessary to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module, if the module has been set as a blocked address in the BankKeeper. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance in the bank keeper. If a send to the module account occurs without going through this module and updating its internal tracking, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, it is suggested that either invariant checks are turned off, or the module is removed from the blocked address list on the BankKeeper with the understanding that this may result in consequences for module balance accounting. +Note: If a module account address is used as the `CounterpartyPayee` it may be necessary to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module, if the module has been set as a blocked address in the `BankKeeper`. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance of the account stored in the `BankKeeper`. If a token transfer to the module account occurs without going through this module and updating the account balance of the module on the `BankKeeper`, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, it is suggested that either invariant checks are turned off, or the module is removed from the blocked address list on the `BankKeeper` with the understanding that this may result in consequences for module balance accounting. ```go type MsgRegisterCounterpartyPayee struct { From a80b6335a5aa72402bcaa5360983d937d201bbf3 Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 8 Aug 2022 16:09:07 +0200 Subject: [PATCH 5/6] update docs to remove language about removing invariants --- docs/middleware/ics29-fee/fee-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index 7e22ef2a1e5..b586b597830 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -31,7 +31,7 @@ The counterparty payee address registered on the destination chain is encoded in 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`. -Note: If a module account address is used as the `CounterpartyPayee` it may be necessary to [turn off invariant checks](https://github.com/cosmos/ibc-go/blob/71d7480c923f4227453e8a80f51be01ae7ee845e/testing/simapp/app.go#L659) for that module, if the module has been set as a blocked address in the `BankKeeper`. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance of the account stored in the `BankKeeper`. If a token transfer to the module account occurs without going through this module and updating the account balance of the module on the `BankKeeper`, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, it is suggested that either invariant checks are turned off, or the module is removed from the blocked address list on the `BankKeeper` with the understanding that this may result in consequences for module balance accounting. +Note: If a module account address is used as the `CounterpartyPayee` but the module has been set as a blocked address in the `BankKeeper`, the refunding to the module account will fail. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance of the account stored in the `BankKeeper`. If a token transfer to the module account occurs without going through this module and updating the account balance of the module on the `BankKeeper`, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, it is suggested that the module is removed from the blocked address list on the `BankKeeper` with the understanding that this may result in consequences for module balance accounting. ```go type MsgRegisterCounterpartyPayee struct { From 415921a547b3c3f382661fcbb139edea3650e3a7 Mon Sep 17 00:00:00 2001 From: Charly Date: Thu, 11 Aug 2022 16:54:21 +0200 Subject: [PATCH 6/6] update docs/middleware/ics29-fee/fee-distribution.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: colin axnér <25233464+colin-axner@users.noreply.github.com> --- docs/middleware/ics29-fee/fee-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index b586b597830..39e3ff00759 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -31,7 +31,7 @@ The counterparty payee address registered on the destination chain is encoded in 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`. -Note: If a module account address is used as the `CounterpartyPayee` but the module has been set as a blocked address in the `BankKeeper`, the refunding to the module account will fail. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance of the account stored in the `BankKeeper`. If a token transfer to the module account occurs without going through this module and updating the account balance of the module on the `BankKeeper`, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, it is suggested that the module is removed from the blocked address list on the `BankKeeper` with the understanding that this may result in consequences for module balance accounting. +Note: If a module account address is used as the `CounterpartyPayee` but the module has been set as a blocked address in the `BankKeeper`, the refunding to the module account will fail. This is because many modules use invariants to compare internal tracking of module account balances against the actual balance of the account stored in the `BankKeeper`. If a token transfer to the module account occurs without going through this module and updating the account balance of the module on the `BankKeeper`, then invariants may break and unknown behaviour could occur depending on the module implementation. Therefore, if it is desirable to use a module account that is currently blocked, the module developers should be consulted to gauge to possibility of removing the module account from the blocked list. ```go type MsgRegisterCounterpartyPayee struct {