Authorizations
This document is relevant only for fungible token transfers over channels on v1 of the ICS-20 protocol.
TransferAuthorization
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 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 over a specified channel.
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 may be able to specify the list of addresses that they allow to receive funds. If empty, then all addresses are allowed.
It takes:
- a
SourcePort
and aSourceChannel
which together comprise the unique transfer channel identifier over which authorized funds can be transferred. - a
SpendLimit
that specifies the maximum amount of tokens the grantee can transfer. TheSpendLimit
is updated as the tokens are transferred, unless the sentinel value of the maximum value for a 256-bit unsigned integer (i.e. 2^256 - 1) is used for the amount, in which case theSpendLimit
will not be updated (please be aware that using this sentinel value will grant the grantee the privilege to transfer all the tokens of a given denomination available at the granter's account). The helper functionUnboundedSpendLimit
in thetypes
package of thetransfer
module provides the sentinel value that can be used. ThisSpendLimit
may also be updated to increase or decrease the limit as the granter wishes. - 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 theTransferAuthorization
. - an
AllowedPacketData
list that specifies the list of memo strings that are allowed to be included in the memo field of the packet. If this list is empty, then only an empty memo is allowed (amemo
field with non-empty content will be denied). If this list includes a single element equal to"*"
, then any content inmemo
field will be allowed.
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
- the
memo
field is not allowed byAllowedPacketData
Below is the TransferAuthorization
message:
func NewTransferAuthorization(allocations ...Allocation) *TransferAuthorization {
return &TransferAuthorization{
Allocations: allocations,
}
}
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 sdk.Coins
// allow list of receivers, an empty allow list permits any receiver address
AllowList []string
// allow list of memo strings, an empty list prohibits all memo strings;
// a list only with "*" permits any memo string
AllowedPacketData []string
}