From d05a129ae37e8c6254d971fb553381221b71b1d9 Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 23 Jan 2023 10:38:04 -0600 Subject: [PATCH 1/4] transferauthz docs --- docs/.vuepress/config.js | 5 +++ docs/apps/transfer/authorizations.md | 49 ++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/apps/transfer/authorizations.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c34ab01f54f..2e9e95352d3 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -325,6 +325,11 @@ module.exports = { directory: false, path: "/apps/transfer/params.html", }, + { + title: "Authorizations", + directory: false, + path: "/apps/transfer/authorizations.html", + }, ], }, ], diff --git a/docs/apps/transfer/authorizations.md b/docs/apps/transfer/authorizations.md new file mode 100644 index 00000000000..07331c6af20 --- /dev/null +++ b/docs/apps/transfer/authorizations.md @@ -0,0 +1,49 @@ +# TransferAuthorization + +`TransferAuthorization` implements the `Authorization` interface for `ibc.applications.transfer.v1.Msg`. It allows a granter to grant a grantee the privilege to submit MsgTransfer on its behalf. Please see the [Cosmos SDK docs](https://docs.cosmos.network/v0.47/modules/authz) for more details on granting privileges via the `Authz` module. + +More specifically, the granter shall be able to grant privileges a grantee to transfer funds that belong to the granter on a set of 1 or more source port ID/channel ID pairs. + +For each source port ID/channel ID pair, the granter shall be able to specify a spend limit for each denomination they wish to allow the grantee to be able to transfer. + +The granter shall be able to specify the list of addresses that they allow to receive funds. If empty, then all addresses are allowed. + + +It takes: + +- a range of `SourcePorts` and a range of `SourceChannels` which together comprise the unique transfer channel identifiers over which authorized funds can be transferred. + +- a range of (positive) `SpendLimits` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. This `SpendLimit` may also be updated to increase or decrease the limit as the granter wishes. + +- an `AllowedAddrs` list that specifies the list of addresses that are allowed to receive funds. If this list is empty, then all addresses are allowed to receive funds from the `TransferAuthorization`. + +Below is the `TransferAuthorization` message: + +```protobuf +message TransferAuthorization { + + option (cosmos_proto.implements_interface) = "Authorization"; + + // port and channel amounts + + repeated PortChannelAmount allocations = 1 [(gogoproto.nullable) = false]; + +} + +message PortChannelAmount { + + // the port on which the packet will be sent + string source_port = 1 [(gogoproto.moretags) = "yaml:\"source_port\""]; + + // the channel by which the packet will be sent + string source_channel = 2 [(gogoproto.moretags) = "yaml:\"source_channel\""]; + + // spend limitation on the channel + repeated cosmos.base.v1beta1.Coin spend_limit = 3 + [(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"]; + + // allowed addresses to be sent via transfer message + repeated string allowed_addresses = 4; + +} +``` \ No newline at end of file From 5e76d0415300b8adb5b652a2e38f39c52e10ba95 Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 23 Jan 2023 10:46:59 -0600 Subject: [PATCH 2/4] typo --- docs/apps/transfer/authorizations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/apps/transfer/authorizations.md b/docs/apps/transfer/authorizations.md index 07331c6af20..7896c0fc5c0 100644 --- a/docs/apps/transfer/authorizations.md +++ b/docs/apps/transfer/authorizations.md @@ -2,7 +2,7 @@ `TransferAuthorization` implements the `Authorization` interface for `ibc.applications.transfer.v1.Msg`. It allows a granter to grant a grantee the privilege to submit MsgTransfer on its behalf. Please see the [Cosmos SDK docs](https://docs.cosmos.network/v0.47/modules/authz) for more details on granting privileges via the `Authz` module. -More specifically, the granter shall be able to grant privileges a grantee to transfer funds that belong to the granter on a set of 1 or more source port ID/channel ID pairs. +More specifically, the granter allows the grantee to transfer funds that belong to the granter on a set of 1 or more source port ID/channel ID pairs. For each source port ID/channel ID pair, the granter shall be able to specify a spend limit for each denomination they wish to allow the grantee to be able to transfer. @@ -13,7 +13,7 @@ It takes: - a range of `SourcePorts` and a range of `SourceChannels` which together comprise the unique transfer channel identifiers over which authorized funds can be transferred. -- a range of (positive) `SpendLimits` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. This `SpendLimit` may also be updated to increase or decrease the limit as the granter wishes. +- a range of (positive) `SpendLimits` that specify the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. This `SpendLimit` may also be updated to increase or decrease the limit as the granter wishes. - an `AllowedAddrs` list that specifies the list of addresses that are allowed to receive funds. If this list is empty, then all addresses are allowed to receive funds from the `TransferAuthorization`. From f843a263f05a69fa912d8664bd6ed8fb737b3b31 Mon Sep 17 00:00:00 2001 From: Charly Date: Tue, 24 Jan 2023 15:33:30 -0600 Subject: [PATCH 3/4] update pr comments --- docs/apps/transfer/authorizations.md | 60 ++++++++++++++-------------- 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/docs/apps/transfer/authorizations.md b/docs/apps/transfer/authorizations.md index 7896c0fc5c0..71cb307cb35 100644 --- a/docs/apps/transfer/authorizations.md +++ b/docs/apps/transfer/authorizations.md @@ -1,49 +1,47 @@ -# TransferAuthorization +# `TransferAuthorization` -`TransferAuthorization` implements the `Authorization` interface for `ibc.applications.transfer.v1.Msg`. It allows a granter to grant a grantee the privilege to submit MsgTransfer on its behalf. Please see the [Cosmos SDK docs](https://docs.cosmos.network/v0.47/modules/authz) for more details on granting privileges via the `Authz` module. +`TransferAuthorization` implements the `Authorization` interface for `ibc.applications.transfer.v1.MsgTransfer`. It allows a granter to grant a grantee the privilege to submit MsgTransfer on its behalf. Please see the [Cosmos SDK docs](https://docs.cosmos.network/v0.47/modules/authz) for more details on granting privileges via the `x/authz` module. -More specifically, the granter allows the grantee to transfer funds that belong to the granter on a set of 1 or more source port ID/channel ID pairs. +More specifically, the granter allows the grantee to transfer funds over a specified channel that belong to the granter. -For each source port ID/channel ID pair, the granter shall be able to specify a spend limit for each denomination they wish to allow the grantee to be able to transfer. +For the specified channel, the granter shall be able to specify a spend limit of a specific denomination they wish to allow the grantee to be able to transfer. The granter shall be able to specify the list of addresses that they allow to receive funds. If empty, then all addresses are allowed. It takes: -- a range of `SourcePorts` and a range of `SourceChannels` which together comprise the unique transfer channel identifiers over which authorized funds can be transferred. +- a `SourcePort` and a `SourceChannel` which together comprise the unique transfer channel identifier over which authorized funds can be transferred. -- a range of (positive) `SpendLimits` that specify the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. This `SpendLimit` may also be updated to increase or decrease the limit as the granter wishes. +- a `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. This `SpendLimit` may also be updated to increase or decrease the limit as the granter wishes. -- an `AllowedAddrs` list that specifies the list of addresses that are allowed to receive funds. If this list is empty, then all addresses are allowed to receive funds from the `TransferAuthorization`. +- an `AllowList` list that specifies the list of addresses that are allowed to receive funds. If this list is empty, then all addresses are allowed to receive funds from the `TransferAuthorization`. -Below is the `TransferAuthorization` message: - -```protobuf -message TransferAuthorization { - - option (cosmos_proto.implements_interface) = "Authorization"; +Setting a `TransferAuthorization` is expected to fail if: +- the spend limit is nil +- the denomination of the spend limit is an invalid coin type +- the source port ID is invalid +- the source channel ID is invalid +- there are duplicate entries in the `AllowList` - // port and channel amounts - - repeated PortChannelAmount allocations = 1 [(gogoproto.nullable) = false]; +Below is the `TransferAuthorization` message: +```golang +func NewTransferAuthorization(allocations ...Allocation) *TransferAuthorization { + return &TransferAuthorization{ + Allocations: allocations, + } } -message PortChannelAmount { - - // the port on which the packet will be sent - string source_port = 1 [(gogoproto.moretags) = "yaml:\"source_port\""]; - - // the channel by which the packet will be sent - string source_channel = 2 [(gogoproto.moretags) = "yaml:\"source_channel\""]; - - // spend limitation on the channel - repeated cosmos.base.v1beta1.Coin spend_limit = 3 - [(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"]; - - // allowed addresses to be sent via transfer message - repeated string allowed_addresses = 4; - +type Allocation struct { + // the port on which the packet will be sent + SourcePort string + // the channel by which the packet will be sent + SourceChannel string + // spend limitation on the channel + SpendLimit github_com_cosmos_cosmos_sdk_types.Coins + // allow list of receivers, an empty allow list permits any receiver address + AllowList []string } + ``` \ No newline at end of file From 21d7c0f4c3f4c90936790fb3ccb43a071493a449 Mon Sep 17 00:00:00 2001 From: Charly Date: Wed, 25 Jan 2023 12:09:07 -0600 Subject: [PATCH 4/4] pr review --- docs/apps/transfer/authorizations.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/apps/transfer/authorizations.md b/docs/apps/transfer/authorizations.md index 71cb307cb35..6dbbafab59b 100644 --- a/docs/apps/transfer/authorizations.md +++ b/docs/apps/transfer/authorizations.md @@ -2,11 +2,11 @@ `TransferAuthorization` implements the `Authorization` interface for `ibc.applications.transfer.v1.MsgTransfer`. It allows a granter to grant a grantee the privilege to submit MsgTransfer on its behalf. Please see the [Cosmos SDK docs](https://docs.cosmos.network/v0.47/modules/authz) for more details on granting privileges via the `x/authz` module. -More specifically, the granter allows the grantee to transfer funds over a specified channel that belong to the granter. +More specifically, the granter allows the grantee to transfer funds that belong to the granter over a specified channel. -For the specified channel, the granter shall be able to specify a spend limit of a specific denomination they wish to allow the grantee to be able to transfer. +For the specified channel, the granter must be able to specify a spend limit of a specific denomination they wish to allow the grantee to be able to transfer. -The granter shall be able to specify the list of addresses that they allow to receive funds. If empty, then all addresses are allowed. +The granter may be able to specify the list of addresses that they allow to receive funds. If empty, then all addresses are allowed. It takes: @@ -39,7 +39,7 @@ type Allocation struct { // the channel by which the packet will be sent SourceChannel string // spend limitation on the channel - SpendLimit github_com_cosmos_cosmos_sdk_types.Coins + SpendLimit sdk.Coins // allow list of receivers, an empty allow list permits any receiver address AllowList []string }