Concepts

Authorization and Grant

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.

Grant is an allowance to execute a Msg by the grantee on behalf of the granter. Authorization is an interface which must be implemented by a concrete authorization logic to validate and execute grants. They 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.

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.ServiceMsg 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

Cosmos-SDK x/authz module comes with following authorization types

SendAuthorization

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

Copy // SendAuthorization allows the grantee to spend up to spend_limit coins from // the granter's account. 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 }

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

GenericAuthorization

GenericAuthorization implements the Authorization interface, that gives unrestricted permission to execute the provided Msg on behalf of granter's account.

Copy 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.

Gas

In order to prevent DoS attacks, granting StakeAuthorizaitons with x/authz incur gas. StakeAuthorizaiton allows you to authorize another account to delegate, undelegate, or redelegate to validators. The authorizer can define a list of validators they will allow and/or deny delegations to. The SDK will iterate over these lists and charge 10 gas for each validator in both of the lists.