# x/authz
# Abstract
x/authz is an implementation of a Cosmos SDK module, per ADR 30 (opens new window), that allows
granting arbitrary privileges from one account (the granter) to another account (the grantee). Authorizations must be granted for a particular Msg service method one by one using an implementation of the Authorization interface.
# Contents
# Concepts
# Authorization and Grant
The x/authz module defines interfaces and messages grant authorizations to perform actions
on behalf of one account to other accounts. The design is defined in the ADR 030 (opens new window).
A grant is an allowance to execute a Msg by the grantee on behalf of the granter.
Authorization is an interface that must be implemented by a concrete authorization logic to validate and execute grants. Authorizations are extensible and can be defined for any Msg service method even outside of the module where the Msg method is defined. See the SendAuthorization example in the next section for more details.
Note: The authz module is different from the auth (authentication) module that is responsible for specifying the base transaction and account types.
# Built-in Authorizations
The Cosmos SDK x/authz module comes with following authorization types:
# GenericAuthorization
GenericAuthorization implements the Authorization interface that gives unrestricted permission to execute the provided Msg on behalf of granter's account.
msgstores Msg type URL.
# SendAuthorization
SendAuthorization implements the Authorization interface for the cosmos.bank.v1beta1.MsgSend Msg.
- It takes a (positive)
SpendLimitthat specifies the maximum amount of tokens the grantee can spend. TheSpendLimitis updated as the tokens are spent. - It takes an (optional)
AllowListthat specifies to which addresses a grantee can send token.
spend_limitkeeps track of how many coins are left in the authorization.allow_listspecifies an optional list of addresses to whom the grantee can send tokens on behalf of the granter.
# StakeAuthorization
StakeAuthorization implements the Authorization interface for messages in the staking module (opens new window). It takes an AuthorizationType to specify whether you want to authorise delegating, undelegating or redelegating (i.e. these have to be authorised seperately). It also takes a required MaxTokens that keeps track of a limit to the amount of tokens that can be delegated/undelegated/redelegated. If left empty, the amount is unlimited. Additionally, this Msg takes an AllowList or a DenyList, which allows you to select which validators you allow or deny grantees to stake with.
# Gas
In order to prevent DoS attacks, granting StakeAuthorizations with x/authz incurs gas. StakeAuthorization allows you to authorize another account to delegate, undelegate, or redelegate to validators. The authorizer can define a list of validators they allow or deny delegations to. The Cosmos SDK iterates over these lists and charge 10 gas for each validator in both of the lists.
Since the state maintaining a list for granter, grantee pair with same expiration, we are iterating over the list to remove the grant (incase of any revoke of paritcular msgType) from the list and we are charging 20 gas per iteration.
# State
# Grant
Grants are identified by combining granter address (the address bytes of the granter), grantee address (the address bytes of the grantee) and Authorization type (its type URL). Hence we only allow one grant for the (granter, grantee, Authorization) triple.
- Grant:
0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes -> ProtocolBuffer(AuthorizationGrant)
The grant object encapsulates an Authorization type and an expiration timestamp:
# GrantQueue
We are maintaining a queue for authz pruning. Whenever a grant is created, an item will be added to GrantQueue with a key of expiration, granter, grantee.
In EndBlock (which runs for every block) we continuously check and prune the expired grants by forming a prefix key with current blocktime that passed the stored expiration in GrantQueue, we iterate through all the matched records from GrantQueue and delete them from the GrantQueue & Grants store.
- GrantQueue:
0x02 | expiration_bytes | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes -> ProtocalBuffer(GrantQueueItem)
The expiration_bytes are the expiration date in UTC with the format "2006-01-02T15:04:05.000000000".
The GrantQueueItem object contains the list of type urls between granter and grantee that expire at the time indicated in the key.
# Messages
In this section we describe the processing of messages for the authz module.
# MsgGrant
An authorization grant is created using the MsgGrant message.
If there is already a grant for the (granter, grantee, Authorization) triple, then the new grant overwrites the previous one. To update or extend an existing grant, a new grant with the same (granter, grantee, Authorization) triple should be created.
The message handling should fail if:
- both granter and grantee have the same address.
- provided
Expirationtime is less than current unix timestamp (but a grant will be created if noexpirationtime is provided sinceexpirationis optional). - provided
Grant.Authorizationis not implemented. Authorization.MsgTypeURL()is not defined in the router (there is no defined handler in the app router to handle that Msg types).
# MsgRevoke
A grant can be removed with the MsgRevoke message.
The message handling should fail if:
- both granter and grantee have the same address.
- provided
MsgTypeUrlis empty.
NOTE: The MsgExec message removes a grant if the grant has expired.
# MsgExec
When a grantee wants to execute a transaction on behalf of a granter, they must send MsgExec.
The message handling should fail if:
- provided
Authorizationis not implemented. - grantee doesn't have permission to run the transaction.
- if granted authorization is expired.
# Events
The authz module emits proto events defined in the Protobuf reference (opens new window).
# Client
# CLI
A user can query and interact with the authz module using the CLI.
# Query
The query commands allow users to query authz state.
# grants
The grants command allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type.
Example:
Example Output:
# Transactions
The tx commands allow users to interact with the authz module.
# exec
The exec command allows a grantee to execute a transaction on behalf of granter.
Example:
# grant
The grant command allows a granter to grant an authorization to a grantee.
Example:
# revoke
The revoke command allows a granter to revoke an authorization from a grantee.
Example:
# gRPC
A user can query the authz module using gRPC endpoints.
# Grants
The Grants endpoint allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type.
Example:
Example Output:
# REST
A user can query the authz module using REST endpoints.
Example:
Example Output: