Skip to main content

x/authz

Introduction​

The authz module facilitates granting authorizations to perform actions, such as spending tokens, on behalf of one account to other accounts.

Overview​

An authorization is an allowance to execute an action by the grantee on behalf of the authorization granter, e.g. to send tokens to an account from the granter, or to delegate tokens to a validator from the granter. There are 3 major built-in authorization types:

  • SendAuthorization
  • StakeAuthorization
  • GenericAuthorization

SendAuthorization​

SendAuthorization implements an authorization to the grantee to perform, on behalf of the granter, a basic send action defined in the bank module. It takes a SpendLimit that is greater than 0 to specify the maximum amount of tokens the grantee can spend with. The SpendLimit keeps track of how many tokens allowed are left in the authorization and is updated as the tokens are spent until the SendAuthorization gets cleared when the SpendLimitreaches 0. Sending an amount greater than the SpendLimit is not allowed.

StakeAuthorization​

StakeAuthorization implements an authorization to the grantee to perform, on behalf of the granter, delegate, unbond (undelegate), or redelegate actions defined in the staking module. Each of the above actions need to be authorized separately, with which either an AllowList or a DenyList must be specified to restrict which validators to or not to perform a staking action with. Optionally, MaxTokens can also be specified in the authorization that keeps track of a limit to the amount of tokens to be delegated/undelegated/redelegated. If left unspecified, the amount is unlimited. Similar to the SpendLimit in SendAuthorization, MaxTokens gets updated after each valid authorized staking action. An authorized staking action that uses tokens beyond the MaxTokens is not allowed.

GenericAuthorization​

GenericAuthorization implements an authorization to the grantee to perform, on behalf of the granter, a generic action. In other words, GenericAuthorization facilitates an arbitrary action grant, where a MsgTypeURL must be specified to correspond to an action defined in the modules. A GenericAuthorization is currently unrestricted beyond the MsgTypeURL. For example, when granting someone to send tokens, the SpendLimit in SendAuthorization will not be enforced. Therefore, a SendAuthorization without a spend limit may in fact be implemented as a GenericAuthorization with the MsgTypeURL been set to /cosmos.bank.v1beta1.MsgSend. The following are some common MsgTypeURLs:

  • Send: /cosmos.bank.v1beta1.MsgSend
  • Delegate: /cosmos.staking.v1beta1.MsgDelegate
  • Unbond/Undelegate: /cosmos.staking.v1beta1.MsgUndelegate
  • Redelegate: /cosmos.staking.v1beta1.MsgBeginRedelegate
  • Withdraw delegator reward: /cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward
NOTE

Expiration of Grant: The granter can optionally set an Expiration time in form of a UNIX Timestamp for any authorization grant. The Expiration time should be later than current UNIX Timestamp and is defaulted to be one year from current time if unspecified. An authorization may be executed only if the grant has not yet expired. Setting an Expiration time for an authorization grant is generally encouraged.