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.

Copy type Authorization interface { proto.Message // MsgTypeURL returns the fully-qualified Msg service method URL (as described in ADR 031), // which will process and accept or reject a request. MsgTypeURL() string // Accept determines whether this grant permits the provided sdk.Msg to be performed, // and if so provides an upgraded authorization instance. Accept(ctx sdk.Context, msg sdk.Msg) (AcceptResponse, error) // ValidateBasic does a simple validation check that // doesn't require access to any other information. ValidateBasic() error }

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.

Copy // GenericAuthorization gives the grantee unrestricted permissions to execute // the provided method on behalf of the granter's account. message GenericAuthorization { option (cosmos_proto.implements_interface) = "Authorization"; // Msg, identified by it's type URL, to grant unrestricted permissions to execute string msg = 1; }

Copy // MsgTypeURL implements Authorization.MsgTypeURL. func (a GenericAuthorization) MsgTypeURL() string { return a.Msg } // Accept implements Authorization.Accept. func (a GenericAuthorization) Accept(ctx sdk.Context, msg sdk.Msg) (AcceptResponse, error) { return AcceptResponse{Accept: true}, nil } // ValidateBasic implements Authorization.ValidateBasic. func (a GenericAuthorization) ValidateBasic() error { return nil }

• msg stores Msg type URL.

SendAuthorization

SendAuthorization implements the Authorization interface for the cosmos.bank.v1beta1.MsgSend Msg. It takes a (positive) SpendLimit that specifies the maximum amount of tokens the grantee can spend. The SpendLimit is updated as the tokens are spent.

Copy // SendAuthorization allows the grantee to spend up to spend_limit coins from // the granter's account. // // Since: cosmos-sdk 0.43 message SendAuthorization { option (cosmos_proto.implements_interface) = "Authorization"; repeated cosmos.base.v1beta1.Coin spend_limit = 1 [(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"]; }

Copy // Accept implements Authorization.Accept. func (a SendAuthorization) Accept(ctx sdk.Context, msg sdk.Msg) (authz.AcceptResponse, error) { mSend, ok := msg.(*MsgSend) if !ok { return authz.AcceptResponse{}, sdkerrors.ErrInvalidType.Wrap("type mismatch") } limitLeft, isNegative := a.SpendLimit.SafeSub(mSend.Amount...) if isNegative { return authz.AcceptResponse{}, sdkerrors.ErrInsufficientFunds.Wrapf("requested amount is more than spend limit") } if limitLeft.IsZero() { return authz.AcceptResponse{Accept: true, Delete: true}, nil } return authz.AcceptResponse{Accept: true, Delete: false, Updated: &SendAuthorization{SpendLimit: limitLeft}}, nil }

• spend_limit keeps track of how many coins are left in the authorization.

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.

Copy // StakeAuthorization defines authorization for delegate/undelegate/redelegate. // // Since: cosmos-sdk 0.43 message StakeAuthorization { option (cosmos_proto.implements_interface) = "Authorization"; // max_tokens specifies the maximum amount of tokens can be delegate to a validator. If it is // empty, there is no spend limit and any amount of coins can be delegated. cosmos.base.v1beta1.Coin max_tokens = 1 [(gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coin"]; // validators is the oneof that represents either allow_list or deny_list oneof validators { // allow_list specifies list of validator addresses to whom grantee can delegate tokens on behalf of granter's // account. Validators allow_list = 2; // deny_list specifies list of validator addresses to whom grantee can not delegate tokens. Validators deny_list = 3; } // Validators defines list of validator addresses. message Validators { repeated string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; } // authorization_type defines one of AuthorizationType. AuthorizationType authorization_type = 4; }

Copy // NewStakeAuthorization creates a new StakeAuthorization object. func NewStakeAuthorization(allowed []sdk.ValAddress, denied []sdk.ValAddress, authzType AuthorizationType, amount *sdk.Coin) (*StakeAuthorization, error) { allowedValidators, deniedValidators, err := validateAllowAndDenyValidators(allowed, denied) if err != nil { return nil, err } a := StakeAuthorization{} if allowedValidators != nil { a.Validators = &StakeAuthorization_AllowList{AllowList: &StakeAuthorization_Validators{Address: allowedValidators}} } else { a.Validators = &StakeAuthorization_DenyList{DenyList: &StakeAuthorization_Validators{Address: deniedValidators}} } if amount != nil { a.MaxTokens = amount } a.AuthorizationType = authzType return &a, nil }

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.