From aa6af5d47180aafbf671fd861df0541d478ea657 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 24 Jun 2022 16:35:06 +0200 Subject: [PATCH 1/6] adding fee distribution docs for relayer operators --- docs/.vuepress/config.js | 5 ++ docs/middleware/ics29-fee/fee-distribution.md | 65 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 docs/middleware/ics29-fee/fee-distribution.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 663a40a093b..4bdb47a74d8 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -196,6 +196,11 @@ module.exports = { directory: false, path: "/middleware/ics29-fee/integration.html" }, + { + title: "Fee Distribution", + directory: false, + path: "/middleware/ics29-fee/fee-distribution.html" + }, ] }, ] diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md new file mode 100644 index 00000000000..d8e7e97b5a5 --- /dev/null +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -0,0 +1,65 @@ + + +# Fee Distribution + +Learn about payee registration for 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 fees distributed to a payee for successful execution of `MsgRecvPacket`. +- `AckFee`: The sum of all packet fees distributed to a payee for successful execution of `MsgAcknowledgement`. +- `TimeoutFee`: The sum of all packet fees distributed to a payee for successful execution of `MsgTimeout`. + + +## Register a payee address for forward relaying + +As mentioned previously 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 `RecvFees` 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 desintation 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 +} +``` + +## Register a payee address for reverse and timeout relaying + +As mentioned previously 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` on the source chain. +Relayer operators may choose to register an optional payee address, in order to be compensated accordingly with `AckFees` and `TimeoutFees` 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`. + +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 +} +``` From 2999f54a99d9e1a16db676cc36c5069500ec4673 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 24 Jun 2022 16:55:08 +0200 Subject: [PATCH 2/6] adding validation information and basic cli examples --- docs/middleware/ics29-fee/fee-distribution.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index d8e7e97b5a5..041ecbbaf8d 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -41,6 +41,19 @@ type MsgRegisterCounterpartyPayee struct { } ``` +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 previously in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the reverse relayer describes the actor who performs the submission of `MsgAcknowledgement` on the source chain. @@ -63,3 +76,16 @@ type MsgRegisterPayee struct { 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 +``` From 474a4e6eb59444833546c69cd1f2e4586c51b86d Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 24 Jun 2022 17:02:37 +0200 Subject: [PATCH 3/6] removing unnecessary whitespace --- docs/middleware/ics29-fee/fee-distribution.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index 041ecbbaf8d..239b175e8d2 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -16,7 +16,6 @@ Packet fees are divided into 3 distinct amounts in order to compensate relayer o - `AckFee`: The sum of all packet fees distributed to a payee for successful execution of `MsgAcknowledgement`. - `TimeoutFee`: The sum of all packet fees distributed to a payee for successful execution of `MsgTimeout`. - ## Register a payee address for forward relaying As mentioned previously in [ICS29 Concepts](../ics29-fee/overview.md#concepts), the forward relayer describes the actor who performs the submission of `MsgRecvPacket` on the destination chain. From de000c65693d4f631675d9185b16fb88f3462844 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 24 Jun 2022 17:10:17 +0200 Subject: [PATCH 4/6] updating definitions --- docs/middleware/ics29-fee/fee-distribution.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/middleware/ics29-fee/fee-distribution.md b/docs/middleware/ics29-fee/fee-distribution.md index 239b175e8d2..945c6e4bc1e 100644 --- a/docs/middleware/ics29-fee/fee-distribution.md +++ b/docs/middleware/ics29-fee/fee-distribution.md @@ -12,9 +12,9 @@ Learn about payee registration for distribution of packet fees. The following do 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 fees distributed to a payee for successful execution of `MsgRecvPacket`. -- `AckFee`: The sum of all packet fees distributed to a payee for successful execution of `MsgAcknowledgement`. -- `TimeoutFee`: The sum of all packet fees distributed to a payee for successful execution of `MsgTimeout`. +- `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 From 40559366402039b4addb99131788117ab82a59e6 Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 24 Jun 2022 18:33:33 +0200 Subject: [PATCH 5/6] adding ics29 fee middleware events docs --- docs/.vuepress/config.js | 5 ++++ docs/middleware/ics29-fee/events.md | 36 +++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 docs/middleware/ics29-fee/events.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index e748d200226..9096d937097 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -243,6 +243,11 @@ module.exports = { directory: false, path: "/middleware/ics29-fee/fee-distribution.html" }, + { + title: "Events", + directory: false, + path: "/middleware/ics29-fee/events.html" + }, ] }, ] diff --git a/docs/middleware/ics29-fee/events.md b/docs/middleware/ics29-fee/events.md new file mode 100644 index 00000000000..6266edcfaf3 --- /dev/null +++ b/docs/middleware/ics29-fee/events.md @@ -0,0 +1,36 @@ + + +# 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 | From a3392f22eab8f1d1f3cd3d594c7b616f3d31697b Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Fri, 24 Jun 2022 18:35:27 +0200 Subject: [PATCH 6/6] cleanup --- docs/middleware/ics29-fee/events.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/middleware/ics29-fee/events.md b/docs/middleware/ics29-fee/events.md index 6266edcfaf3..04ab5b34cee 100644 --- a/docs/middleware/ics29-fee/events.md +++ b/docs/middleware/ics29-fee/events.md @@ -4,7 +4,6 @@ order: 5 # Events -## ## `MsgPayPacketFee`, `MsgPayPacketFeeAsync` | Type | Attribute Key | Attribute Value | @@ -31,6 +30,6 @@ order: 5 | Type | Attribute Key | Attribute Value | |-----------------------------|--------------------|---------------------| | register_counterparty_payee | relayer | {relayer} | -| register_counterparty_payee | counterparty_payee | {counterpartyPayee} | | +| register_counterparty_payee | counterparty_payee | {counterpartyPayee} | | register_counterparty_payee | channel_id | {channelID} | | message | module | fee-ibc |