摘要

x/authz 是 Cosmos SDK 模块的一种实现,遵循 ADR 30,允许将任意权限从一个账户(granter)授予另一个账户(grantee)。授权必须针对特定的 Msg 服务方法逐一授予,并通过实现 Authorization 接口来完成。

目录

概念

Authorization 与 Grant

x/authz 模块定义了接口和消息,用于向其他账户授予代表某个账户执行操作的权限。其设计定义见 ADR 030。 Grant 是指允许 grantee 代表 granter 执行某个 Msg。Authorization 是一个接口,具体的授权逻辑必须实现它,以便校验和执行 grant。Authorization 具备可扩展性,可以针对任意 Msg 服务方法定义,甚至可以定义在声明该 Msg 方法的模块之外。更多细节可参考下一节中的 SendAuthorization 示例。 注意: authz 模块不同于负责定义基础交易和账户类型的 auth(authentication) 模块。
package authz

import (
    
	"github.com/cosmos/gogoproto/proto"

	sdk "github.com/cosmos/cosmos-sdk/types"
)

// Authorization represents the interface of various Authorization types implemented
// by other modules.
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
}

// AcceptResponse instruments the controller of an authz message if the request is accepted
// and if it should be updated or deleted.
type AcceptResponse struct {
	// If Accept=true, the controller can accept and authorization and handle the update.
	Accept bool
	// If Delete=true, the controller must delete the authorization object and release
	// storage resources.
	Delete bool
	// Controller, who is calling Authorization.Accept must check if `Updated != nil`. If yes,
	// it must use the updated version and handle the update on the storage level.
	Updated Authorization
}

内置授权类型

Cosmos SDK 的 x/authz 模块内置了以下授权类型:

GenericAuthorization

GenericAuthorization 实现了 Authorization 接口,赋予对指定 Msg 的不受限制执行权限,允许代表 granter 的账户执行该 Msg。
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L14-L22
package authz

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
)

var _ Authorization = &GenericAuthorization{
}

// NewGenericAuthorization creates a new GenericAuthorization object.
func NewGenericAuthorization(msgTypeURL string) *GenericAuthorization {
    return &GenericAuthorization{
    Msg: msgTypeURL,
}
}

// 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 存储 Msg 类型 URL。

SendAuthorization

SendAuthorization 为 cosmos.bank.v1beta1.MsgSend Msg 实现了 Authorization 接口。
  • 它接收一个(正数)SpendLimit,用于指定 grantee 最多可花费的代币数量。随着代币被使用,SpendLimit 会同步更新。
  • 它接收一个(可选)AllowList,用于指定 grantee 可以将代币发送到哪些地址。
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/authz.proto#L11-L30
package types

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// TODO: Revisit this once we have proper gas fee framework.
// Ref: https://github.com/cosmos/cosmos-sdk/issues/9054
// Ref: https://github.com/cosmos/cosmos-sdk/discussions/9072
const gasCostPerIteration = uint64(10)

var _ authz.Authorization = &SendAuthorization{
}

// NewSendAuthorization creates a new SendAuthorization object.
func NewSendAuthorization(spendLimit sdk.Coins, allowed []sdk.AccAddress) *SendAuthorization {
    return &SendAuthorization{
    AllowList:  toBech32Addresses(allowed),
    SpendLimit: spendLimit,
}
}

// MsgTypeURL implements Authorization.MsgTypeURL.
func (a SendAuthorization)

MsgTypeURL()

string {
    return sdk.MsgTypeURL(&MsgSend{
})
}

// 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")
}
    toAddr := mSend.ToAddress

	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
}
    isAddrExists := false
    allowedList := a.GetAllowList()
    for _, addr := range allowedList {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "send authorization")
    if addr == toAddr {
    isAddrExists = true
			break
}
	
}
    if len(allowedList) > 0 && !isAddrExists {
    return authz.AcceptResponse{
}, sdkerrors.ErrUnauthorized.Wrapf("cannot send to %s address", toAddr)
}

return authz.AcceptResponse{
    Accept: true,
    Delete: false,
    Updated: &SendAuthorization{
    SpendLimit: limitLeft,
    AllowList: allowedList
}}, nil
}

// ValidateBasic implements Authorization.ValidateBasic.
func (a SendAuthorization)

ValidateBasic()

error {
    if a.SpendLimit == nil {
    return sdkerrors.ErrInvalidCoins.Wrap("spend limit cannot be nil")
}
    if !a.SpendLimit.IsAllPositive() {
    return sdkerrors.ErrInvalidCoins.Wrapf("spend limit must be positive")
}
    found := make(map[string]bool, 0)
    for i := 0; i < len(a.AllowList); i++ {
    if found[a.AllowList[i]] {
    return ErrDuplicateEntry
}

found[a.AllowList[i]] = true
}

return nil
}

func toBech32Addresses(allowed []sdk.AccAddress) []string {
    if len(allowed) == 0 {
    return nil
}
    allowedAddrs := make([]string, len(allowed))
    for i, addr := range allowed {
    allowedAddrs[i] = addr.String()
}

return allowedAddrs
}
  • spend_limit 用于跟踪该授权中剩余可用的币数量。
  • allow_list 指定一个可选地址列表,grantee 可以代表 granter 向这些地址发送代币。

StakeAuthorization

StakeAuthorization 为 staking 模块 中的消息实现了 Authorization 接口。它接受一个 AuthorizationType,用于指定你想授权的是委托、取消委托还是重新委托(也就是说,这些操作必须分别授权)。它还接受一个可选的 MaxTokens,用于跟踪可委托/取消委托/重新委托的代币数量上限。若留空,则数量不受限制。此外,此 Msg 还接受一个 AllowList 或 DenyList,使你能够选择允许或禁止被授权人与哪些验证者进行质押。
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/authz.proto#L11-L35
package types

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// TODO: Revisit this once we have proper gas fee framework.
// Tracking issues https://github.com/cosmos/cosmos-sdk/issues/9054, https://github.com/cosmos/cosmos-sdk/discussions/9072
const gasCostPerIteration = uint64(10)

var _ authz.Authorization = &StakeAuthorization{
}

// 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
}

// MsgTypeURL implements Authorization.MsgTypeURL.
func (a StakeAuthorization)

MsgTypeURL()

string {
    authzType, err := normalizeAuthzType(a.AuthorizationType)
    if err != nil {
    panic(err)
}

return authzType
}

func (a StakeAuthorization)

ValidateBasic()

error {
    if a.MaxTokens != nil && a.MaxTokens.IsNegative() {
    return sdkerrors.Wrapf(authz.ErrNegativeMaxTokens, "negative coin amount: %v", a.MaxTokens)
}
    if a.AuthorizationType == AuthorizationType_AUTHORIZATION_TYPE_UNSPECIFIED {
    return authz.ErrUnknownAuthorizationType
}

return nil
}

// Accept implements Authorization.Accept.
func (a StakeAuthorization)

Accept(ctx sdk.Context, msg sdk.Msg) (authz.AcceptResponse, error) {
    var validatorAddress string
	var amount sdk.Coin
    switch msg := msg.(type) {
    case *MsgDelegate:
		validatorAddress = msg.ValidatorAddress
		amount = msg.Amount
    case *MsgUndelegate:
		validatorAddress = msg.ValidatorAddress
		amount = msg.Amount
    case *MsgBeginRedelegate:
		validatorAddress = msg.ValidatorDstAddress
		amount = msg.Amount
	default:
		return authz.AcceptResponse{
}, sdkerrors.ErrInvalidRequest.Wrap("unknown msg type")
}
    isValidatorExists := false
    allowedList := a.GetAllowList().GetAddress()
    for _, validator := range allowedList {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "stake authorization")
    if validator == validatorAddress {
    isValidatorExists = true
			break
}
	
}
    denyList := a.GetDenyList().GetAddress()
    for _, validator := range denyList {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "stake authorization")
    if validator == validatorAddress {
    return authz.AcceptResponse{
}, sdkerrors.ErrUnauthorized.Wrapf("cannot delegate/undelegate to %s validator", validator)
}
	
}
    if len(allowedList) > 0 && !isValidatorExists {
    return authz.AcceptResponse{
}, sdkerrors.ErrUnauthorized.Wrapf("cannot delegate/undelegate to %s validator", validatorAddress)
}
    if a.MaxTokens == nil {
    return authz.AcceptResponse{
    Accept: true,
    Delete: false,
    Updated: &StakeAuthorization{
    Validators: a.GetValidators(),
    AuthorizationType: a.GetAuthorizationType()
},
}, nil
}

limitLeft, err := a.MaxTokens.SafeSub(amount)
    if err != nil {
    return authz.AcceptResponse{
}, err
}
    if limitLeft.IsZero() {
    return authz.AcceptResponse{
    Accept: true,
    Delete: true
}, nil
}

return authz.AcceptResponse{
    Accept: true,
    Delete: false,
    Updated: &StakeAuthorization{
    Validators: a.GetValidators(),
    AuthorizationType: a.GetAuthorizationType(),
    MaxTokens: &limitLeft
},
}, nil
}

func validateAllowAndDenyValidators(allowed []sdk.ValAddress, denied []sdk.ValAddress) ([]string, []string, error) {
    if len(allowed) == 0 && len(denied) == 0 {
    return nil, nil, sdkerrors.ErrInvalidRequest.Wrap("both allowed & deny list cannot be empty")
}
    if len(allowed) > 0 && len(denied) > 0 {
    return nil, nil, sdkerrors.ErrInvalidRequest.Wrap("cannot set both allowed & deny list")
}
    allowedValidators := make([]string, len(allowed))
    if len(allowed) > 0 {
    for i, validator := range allowed {
    allowedValidators[i] = validator.String()
}

return allowedValidators, nil, nil
}
    deniedValidators := make([]string, len(denied))
    for i, validator := range denied {
    deniedValidators[i] = validator.String()
}

return nil, deniedValidators, nil
}

// Normalized Msg type URLs
func normalizeAuthzType(authzType AuthorizationType) (string, error) {
    switch authzType {
    case AuthorizationType_AUTHORIZATION_TYPE_DELEGATE:
		return sdk.MsgTypeURL(&MsgDelegate{
}), nil
    case AuthorizationType_AUTHORIZATION_TYPE_UNDELEGATE:
		return sdk.MsgTypeURL(&MsgUndelegate{
}), nil
    case AuthorizationType_AUTHORIZATION_TYPE_REDELEGATE:
		return sdk.MsgTypeURL(&MsgBeginRedelegate{
}), nil
	default:
		return "", sdkerrors.Wrapf(authz.ErrUnknownAuthorizationType, "cannot normalize authz type with %T", authzType)
}
}

Gas

为了防止 DoS 攻击,通过 x/authz 授予 StakeAuthorization 会消耗 gas。StakeAuthorization 允许你授权另一个账户向验证者执行委托、取消委托或重新委托。授权方可以定义一个验证者列表,指定允许或禁止将委托发送到哪些验证者。Cosmos SDK 会遍历这些列表,并对两个列表中的每个验证者各收取 10 gas。 由于状态会为具有相同过期时间的 granter、grantee 对维护一个列表,因此我们需要遍历该列表来移除授权(在撤销某个特定 msgType 的情况下),并且每次迭代收取 20 gas。

状态

授权

授权通过组合 granter 地址(granter 的地址字节)、grantee 地址(grantee 的地址字节)以及 Authorization 类型(其 type URL)来标识。因此,对于 (granter, grantee, Authorization) 三元组,我们只允许存在一条授权。
  • 授权:0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes -> ProtocolBuffer(AuthorizationGrant)
授权对象封装了一个 Authorization 类型和一个过期时间戳:
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L24-L32

GrantQueue

我们维护了一个用于 authz 清理的队列。每当创建一个 grant 时,都会向 GrantQueue 中添加一项,其键由过期时间、granter、grantee 组成。 在 EndBlock(每个区块都会运行)中,我们会持续检查并清理已过期的 grants:使用当前区块时间构造一个前缀键,以匹配 GrantQueue 中已超过存储过期时间的记录;随后遍历 GrantQueue 中所有匹配的记录,并将它们从 GrantQueue 和 Grant 的存储中删除。
package keeper

import (
    
	"fmt"
    "strconv"
    "time"
    "github.com/cosmos/gogoproto/proto"
	abci "github.com/tendermint/tendermint/abci/types"
    "github.com/tendermint/tendermint/libs/log"
    "github.com/cosmos/cosmos-sdk/baseapp"
    "github.com/cosmos/cosmos-sdk/codec"
	codectypes "github.com/cosmos/cosmos-sdk/codec/types"
	storetypes "github.com/cosmos/cosmos-sdk/store/types"
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// TODO: Revisit this once we have proper gas fee framework.
// Tracking issues https://github.com/cosmos/cosmos-sdk/issues/9054,
// https://github.com/cosmos/cosmos-sdk/discussions/9072
const gasCostPerIteration = uint64(20)

type Keeper struct {
    storeKey   storetypes.StoreKey
	cdc        codec.BinaryCodec
	router     *baseapp.MsgServiceRouter
	authKeeper authz.AccountKeeper
}

// NewKeeper constructs a message authorization Keeper
func NewKeeper(storeKey storetypes.StoreKey, cdc codec.BinaryCodec, router *baseapp.MsgServiceRouter, ak authz.AccountKeeper)

Keeper {
    return Keeper{
    storeKey:   storeKey,
		cdc:        cdc,
		router:     router,
		authKeeper: ak,
}
}

// Logger returns a module-specific logger.
func (k Keeper)

Logger(ctx sdk.Context)

log.Logger {
    return ctx.Logger().With("module", fmt.Sprintf("x/%s", authz.ModuleName))
}

// getGrant returns grant stored at skey.
func (k Keeper)

getGrant(ctx sdk.Context, skey []byte) (grant authz.Grant, found bool) {
    store := ctx.KVStore(k.storeKey)
    bz := store.Get(skey)
    if bz == nil {
    return grant, false
}

k.cdc.MustUnmarshal(bz, &grant)

return grant, true
}

func (k Keeper)

update(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress, updated authz.Authorization)

author {
    skey := grantStoreKey(grantee, granter, updated.MsgTypeURL())

grant, found := k.getGrant(ctx, skey)
    if !found {
    return authz.ErrNoAuthorizationFound
}

msg, ok := updated.(proto.Message)
    if !ok {
    return sdkerrors.ErrPackAny.Wrapf("cannot proto marshal %T", updated)
}

any, err := codectypes.NewAnyWithValue(msg)
    if err != nil {
    return err
}

grant.Authorization = any
    store := ctx.KVStore(k.storeKey)

store.Set(skey, k.cdc.MustMarshal(&grant))

return nil
}

// DispatchActions attempts to execute the provided messages via authorization
// grants from the message signer to the grantee.
func (k Keeper)

DispatchActions(ctx sdk.Context, grantee sdk.AccAddress, msgs []sdk.Msg) ([][]byte, error) {
    results := make([][]byte, len(msgs))
    now := ctx.BlockTime()
    for i, msg := range msgs {
    signers := msg.GetSigners()
    if len(signers) != 1 {
    return nil, authz.ErrAuthorizationNumOfSigners
}
    granter := signers[0]

		// If granter != grantee then check authorization.Accept, otherwise we
		// implicitly accept.
    if !granter.Equals(grantee) {
    skey := grantStoreKey(grantee, granter, sdk.MsgTypeURL(msg))

grant, found := k.getGrant(ctx, skey)
    if !found {
    return nil, sdkerrors.Wrapf(authz.ErrNoAuthorizationFound, "failed to update grant with key %s", string(skey))
}
    if grant.Expiration != nil && grant.Expiration.Before(now) {
    return nil, authz.ErrAuthorizationExpired
}

authorization, err := grant.GetAuthorization()
    if err != nil {
    return nil, err
}

resp, err := authorization.Accept(ctx, msg)
    if err != nil {
    return nil, err
}
    if resp.Delete {
    err = k.DeleteGrant(ctx, grantee, granter, sdk.MsgTypeURL(msg))
}

else if resp.Updated != nil {
    err = k.update(ctx, grantee, granter, resp.Updated)
}
    if err != nil {
    return nil, err
}
    if !resp.Accept {
    return nil, sdkerrors.ErrUnauthorized
}
	
}
    handler := k.router.Handler(msg)
    if handler == nil {
    return nil, sdkerrors.ErrUnknownRequest.Wrapf("unrecognized message route: %s", sdk.MsgTypeURL(msg))
}

msgResp, err := handler(ctx, msg)
    if err != nil {
    return nil, sdkerrors.Wrapf(err, "failed to execute message; message %v", msg)
}

results[i] = msgResp.Data

		// emit the events from the dispatched actions
    events := msgResp.Events
    sdkEvents := make([]sdk.Event, 0, len(events))
    for _, event := range events {
    e := event
			e.Attributes = append(e.Attributes, abci.EventAttribute{
    Key: "authz_msg_index",
    Value: strconv.Itoa(i)
})

sdkEvents = append(sdkEvents, sdk.Event(e))
}

ctx.EventManager().EmitEvents(sdkEvents)
}

return results, nil
}

// SaveGrant method grants the provided authorization to the grantee on the granter's account
// with the provided expiration time and insert authorization key into the grants queue. If there is an existing authorization grant for the
// same `sdk.Msg` type, this grant overwrites that.
func (k Keeper)

SaveGrant(ctx sdk.Context, grantee, granter sdk.AccAddress, authorization authz.Authorization, expiration *time.Time)

error {
    store := ctx.KVStore(k.storeKey)
    msgType := authorization.MsgTypeURL()
    skey := grantStoreKey(grantee, granter, msgType)

grant, err := authz.NewGrant(ctx.BlockTime(), authorization, expiration)
    if err != nil {
    return err
}

var oldExp *time.Time
    if oldGrant, found := k.getGrant(ctx, skey); found {
    oldExp = oldGrant.Expiration
}
    if oldExp != nil && (expiration == nil || !oldExp.Equal(*expiration)) {
    if err = k.removeFromGrantQueue(ctx, skey, granter, grantee, *oldExp); err != nil {
    return err
}
	
}

	// If the expiration didn't change, then we don't remove it and we should not insert again
    if expiration != nil && (oldExp == nil || !oldExp.Equal(*expiration)) {
    if err = k.insertIntoGrantQueue(ctx, granter, grantee, msgType, *expiration); err != nil {
    return err
}
	
}
    bz := k.cdc.MustMarshal(&grant)

store.Set(skey, bz)

return ctx.EventManager().EmitTypedEvent(&authz.EventGrant{
    MsgTypeUrl: authorization.MsgTypeURL(),
    Granter:    granter.String(),
    Grantee:    grantee.String(),
})
}

// DeleteGrant revokes any authorization for the provided message type granted to the grantee
// by the granter.
func (k Keeper)

DeleteGrant(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress, msgType string)

error {
    store := ctx.KVStore(k.storeKey)
    skey := grantStoreKey(grantee, granter, msgType)

grant, found := k.getGrant(ctx, skey)
    if !found {
    return sdkerrors.Wrapf(authz.ErrNoAuthorizationFound, "failed to delete grant with key %s", string(skey))
}
    if grant.Expiration != nil {
    err := k.removeFromGrantQueue(ctx, skey, granter, grantee, *grant.Expiration)
    if err != nil {
    return err
}
	
}

store.Delete(skey)

return ctx.EventManager().EmitTypedEvent(&authz.EventRevoke{
    MsgTypeUrl: msgType,
    Granter:    granter.String(),
    Grantee:    grantee.String(),
})
}

// GetAuthorizations Returns list of `Authorizations` granted to the grantee by the granter.
func (k Keeper)

GetAuthorizations(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress) ([]authz.Authorization, error) {
    store := ctx.KVStore(k.storeKey)
    key := grantStoreKey(grantee, granter, "")
    iter := sdk.KVStorePrefixIterator(store, key)

defer iter.Close()

var authorization authz.Grant
	var authorizations []authz.Authorization
    for ; iter.Valid(); iter.Next() {
    if err := k.cdc.Unmarshal(iter.Value(), &authorization); err != nil {
    return nil, err
}

a, err := authorization.GetAuthorization()
    if err != nil {
    return nil, err
}

authorizations = append(authorizations, a)
}

return authorizations, nil
}

// GetAuthorization returns an Authorization and it's expiration time.
// A nil Authorization is returned under the following circumstances:
//   - No grant is found.
//   - A grant is found, but it is expired.
//   - There was an error getting the authorization from the grant.
func (k Keeper)

GetAuthorization(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress, msgType string) (authz.Authorization, *time.Time) {
    grant, found := k.getGrant(ctx, grantStoreKey(grantee, granter, msgType))
    if !found || (grant.Expiration != nil && grant.Expiration.Before(ctx.BlockHeader().Time)) {
    return nil, nil
}

auth, err := grant.GetAuthorization()
    if err != nil {
    return nil, nil
}

return auth, grant.Expiration
}

// IterateGrants iterates over all authorization grants
// This function should be used with caution because it can involve significant IO operations.
// It should not be used in query or msg services without charging additional gas.
// The iteration stops when the handler function returns true or the iterator exhaust.
func (k Keeper)

IterateGrants(ctx sdk.Context,
	handler func(granterAddr sdk.AccAddress, granteeAddr sdk.AccAddress, grant authz.Grant)

bool,
) {
    store := ctx.KVStore(k.storeKey)
    iter := sdk.KVStorePrefixIterator(store, GrantKey)

defer iter.Close()
    for ; iter.Valid(); iter.Next() {
    var grant authz.Grant
		granterAddr, granteeAddr, _ := parseGrantStoreKey(iter.Key())

k.cdc.MustUnmarshal(iter.Value(), &grant)
    if handler(granterAddr, granteeAddr, grant) {
    break
}
	
}
}

func (k Keeper)

getGrantQueueItem(ctx sdk.Context, expiration time.Time, granter, grantee sdk.AccAddress) (*authz.GrantQueueItem, error) {
    store := ctx.KVStore(k.storeKey)
    bz := store.Get(GrantQueueKey(expiration, granter, grantee))
    if bz == nil {
    return &authz.GrantQueueItem{
}, nil
}

var queueItems authz.GrantQueueItem
    if err := k.cdc.Unmarshal(bz, &queueItems); err != nil {
    return nil, err
}

return &queueItems, nil
}

func (k Keeper)

setGrantQueueItem(ctx sdk.Context, expiration time.Time,
	granter sdk.AccAddress, grantee sdk.AccAddress, queueItems *authz.GrantQueueItem,
)

error {
    store := ctx.KVStore(k.storeKey)

bz, err := k.cdc.Marshal(queueItems)
    if err != nil {
    return err
}

store.Set(GrantQueueKey(expiration, granter, grantee), bz)

return nil
}

// insertIntoGrantQueue inserts a grant key into the grant queue
func (k Keeper)

insertIntoGrantQueue(ctx sdk.Context, granter, grantee sdk.AccAddress, msgType string, expiration time.Time)

error {
    queueItems, err := k.getGrantQueueItem(ctx, expiration, granter, grantee)
    if err != nil {
    return err
}
    if len(queueItems.MsgTypeUrls) == 0 {
    k.setGrantQueueItem(ctx, expiration, granter, grantee, &authz.GrantQueueItem{
    MsgTypeUrls: []string{
    msgType
},
})
}

else {
    queueItems.MsgTypeUrls = append(queueItems.MsgTypeUrls, msgType)

k.setGrantQueueItem(ctx, expiration, granter, grantee, queueItems)
}

return nil
}

// removeFromGrantQueue removes a grant key from the grant queue
func (k Keeper)

removeFromGrantQueue(ctx sdk.Context, grantKey []byte, granter, grantee sdk.AccAddress, expiration time.Time)

error {
    store := ctx.KVStore(k.storeKey)
    key := GrantQueueKey(expiration, granter, grantee)
    bz := store.Get(key)
    if bz == nil {
    return sdkerrors.Wrap(authz.ErrNoGrantKeyFound, "can't remove grant from the expire queue, grant key not found")
}

var queueItem authz.GrantQueueItem
    if err := k.cdc.Unmarshal(bz, &queueItem); err != nil {
    return err
}

	_, _, msgType := parseGrantStoreKey(grantKey)
    queueItems := queueItem.MsgTypeUrls
    for index, typeURL := range queueItems {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "grant queue")
    if typeURL == msgType {
    end := len(queueItem.MsgTypeUrls) - 1
			queueItems[index] = queueItems[end]
			queueItems = queueItems[:end]
    if err := k.setGrantQueueItem(ctx, expiration, granter, grantee, &authz.GrantQueueItem{
    MsgTypeUrls: queueItems,
}); err != nil {
    return err
}

break
}
	
}

return nil
}

// DequeueAndDeleteExpiredGrants deletes expired grants from the state and grant queue.
func (k Keeper)

DequeueAndDeleteExpiredGrants(ctx sdk.Context)

error {
    store := ctx.KVStore(k.storeKey)
    iterator := store.Iterator(GrantQueuePrefix, sdk.InclusiveEndBytes(GrantQueueTimePrefix(ctx.BlockTime())))

defer iterator.Close()
    for ; iterator.Valid(); iterator.Next() {
    var queueItem authz.GrantQueueItem
    if err := k.cdc.Unmarshal(iterator.Value(), &queueItem); err != nil {
    return err
}

		_, granter, grantee, err := parseGrantQueueKey(iterator.Key())
    if err != nil {
    return err
}

store.Delete(iterator.Key())
    for _, typeURL := range queueItem.MsgTypeUrls {
    store.Delete(grantStoreKey(grantee, granter, typeURL))
}
	
}

return nil
}
  • GrantQueue: 0x02 | expiration_bytes | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes -> ProtocalBuffer(GrantQueueItem)
expiration_bytes 是 UTC 时区的过期日期,格式为 "2006-01-02T15:04:05.000000000"。
package keeper

import (
    
	"time"
    "github.com/cosmos/cosmos-sdk/internal/conv"
	sdk "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/types/address"
    "github.com/cosmos/cosmos-sdk/types/kv"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// Keys for store prefixes
// Items are stored with the following key: values
//
// - 0x01<grant_Bytes>: Grant
// - 0x02<grant_expiration_Bytes>: GrantQueueItem
var (
	GrantKey         = []byte{0x01
} // prefix for each key
	GrantQueuePrefix = []byte{0x02
}
)

var lenTime = len(sdk.FormatTimeBytes(time.Now()))

// StoreKey is the store key string for authz
const StoreKey = authz.ModuleName

// grantStoreKey - return authorization store key
// Items are stored with the following key: values
//
// - 0x01<granterAddressLen (1 Byte)><granterAddress_Bytes><granteeAddressLen (1 Byte)><granteeAddress_Bytes><msgType_Bytes>: Grant
func grantStoreKey(grantee sdk.AccAddress, granter sdk.AccAddress, msgType string) []byte {
    m := conv.UnsafeStrToBytes(msgType)

granter = address.MustLengthPrefix(granter)

grantee = address.MustLengthPrefix(grantee)
    key := sdk.AppendLengthPrefixedBytes(GrantKey, granter, grantee, m)

return key
}

// parseGrantStoreKey - split granter, grantee address and msg type from the authorization key
func parseGrantStoreKey(key []byte) (granterAddr, granteeAddr sdk.AccAddress, msgType string) {
	// key is of format:
	// 0x01<granterAddressLen (1 Byte)><granterAddress_Bytes><granteeAddressLen (1 Byte)><granteeAddress_Bytes><msgType_Bytes>

	granterAddrLen, granterAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, 1, 1) // ignore key[0] since it is a prefix key
	granterAddr, granterAddrEndIndex := sdk.ParseLengthPrefixedBytes(key, granterAddrLenEndIndex+1, int(granterAddrLen[0]))

grinteeAddrLen, granteeAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, granterAddrEndIndex+1, 1)

grinteeAddr, granteeAddrEndIndex := sdk.ParseLengthPrefixedBytes(key, granteeAddrLenEndIndex+1, int(granteeAddrLen[0]))

kv.AssertKeyAtLeastLength(key, granteeAddrEndIndex+1)

return granterAddr, granteeAddr, conv.UnsafeBytesToStr(key[(granteeAddrEndIndex + 1):])
}

// parseGrantQueueKey split expiration time, granter and grantee from the grant queue key
func parseGrantQueueKey(key []byte) (time.Time, sdk.AccAddress, sdk.AccAddress, error) {
	// key is of format:
	// 0x02<grant_expiration_Bytes><granterAddress_Bytes><granteeAddressLen (1 Byte)><granteeAddress_Bytes>

	expBytes, expEndIndex := sdk.ParseLengthPrefixedBytes(key, 1, lenTime)

exp, err := sdk.ParseTimeBytes(expBytes)
    if err != nil {
    return exp, nil, nil, err
}

granterAddrLen, granterAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, expEndIndex+1, 1)

granter, granterEndIndex := sdk.ParseLengthPrefixedBytes(key, granterAddrLenEndIndex+1, int(granterAddrLen[0]))

grinteeAddrLen, granteeAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, granterEndIndex+1, 1)

grintee, _ := sdk.ParseLengthPrefixedBytes(key, granteeAddrLenEndIndex+1, int(granteeAddrLen[0]))

return exp, granter, grantee, nil
}

// GrantQueueKey - return grant queue store key. If a given grant doesn't have a defined
// expiration, then it should not be used in the pruning queue.
// Key format is:
//
//	0x02<expiration><granterAddressLen (1 Byte)><granterAddressBytes><granteeAddressLen (1 Byte)><granteeAddressBytes>: GrantQueueItem
func GrantQueueKey(expiration time.Time, granter sdk.AccAddress, grantee sdk.AccAddress) []byte {
    exp := sdk.FormatTimeBytes(expiration)

granter = address.MustLengthPrefix(granter)

grintee = address.MustLengthPrefix(grantee)

return sdk.AppendLengthPrefixedBytes(GrantQueuePrefix, exp, granter, grantee)
}

// GrantQueueTimePrefix - return grant queue time prefix
func GrantQueueTimePrefix(expiration time.Time) []byte {
    return append(GrantQueuePrefix, sdk.FormatTimeBytes(expiration)...)
}

// firstAddressFromGrantStoreKey parses the first address only
func firstAddressFromGrantStoreKey(key []byte)

sdk.AccAddress {
    addrLen := key[0]
	return sdk.AccAddress(key[1 : 1+addrLen])
}
GrantQueueItem 对象包含 granter 与 grantee 之间、在键中所示时间过期的 type url 列表。

消息

本节介绍 authz 模块中的消息处理流程。

MsgGrant

授权使用 MsgGrant 消息创建。 如果 (granter, grantee, Authorization) 三元组已存在授权,则新授权会覆盖旧授权。要更新或延长现有授权,应创建一个具有相同 (granter, grantee, Authorization) 三元组的新授权。
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L35-L45
在以下情况下,消息处理应失败:
  • granter 和 grantee 地址相同。
  • 提供的 Expiration 时间小于当前 Unix 时间戳(但如果未提供 expiration 时间,仍会创建授权,因为 expiration 是可选的)。
  • 提供的 Grant.Authorization 尚未实现。
  • Authorization.MsgTypeURL() 未在路由器中定义(即应用路由器中没有为该 Msg 类型定义处理器)。

MsgRevoke

可以使用 MsgRevoke 消息移除授权。
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L69-L78
在以下情况下,消息处理应失败:
  • granter 和 grantee 地址相同。
  • 提供的 MsgTypeUrl 为空。
注意:如果授权已过期,MsgExec 消息会移除该授权。

MsgExec

当 grantee 想要代表 granter 执行交易时,必须发送 MsgExec。
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L52-L63
在以下情况下,消息处理应失败:
  • 提供的 Authorization 尚未实现。
  • grantee 没有权限执行该交易。
  • 已授予的授权已过期。

事件

authz 模块会发出在Protobuf 参考中定义的 proto 事件。

客户端

CLI

用户可以使用 CLI 查询并与 authz 模块交互。

查询

query 命令允许用户查询 authz 状态。
simd query authz --help
grants
grants 命令允许用户查询某个 granter-grantee 对的授权。如果设置了消息类型 URL,则只选择该消息类型的授权。
simd query authz grants [granter-addr] [grantee-addr] [msg-type-url]? [flags]
示例:
simd query authz grants cosmos1.. cosmos1.. /cosmos.bank.v1beta1.MsgSend
示例输出:
grants:
- authorization:
    '@type': /cosmos.bank.v1beta1.SendAuthorization
    spend_limit:
    - amount: "100"
      denom: stake
  expiration: "2022-01-01T00:00:00Z"
pagination: null

交易

tx 命令允许用户与 authz 模块交互。
simd tx authz --help
exec
exec 命令允许 grantee 代表 granter 执行交易。
  simd tx authz exec [tx-json-file] --from [grantee] [flags]
示例:
simd tx authz exec tx.json --from=cosmos1..
grant
grant 命令允许 granter 向 grantee 授予授权。
simd tx authz grant <grantee> <authorization_type="send"|"generic"|"delegate"|"unbond"|"redelegate"> --from <granter> [flags]
  • send authorization_type 指内置的 SendAuthorization 类型。可用的自定义参数为 spend-limit(必需)和 allow-list(可选),文档见此处
示例:
    simd tx authz grant cosmos1.. send --spend-limit=100stake --allow-list=cosmos1...,cosmos2... --from=cosmos1..
  • generic authorization_type 指内置的 GenericAuthorization 类型。可用的自定义参数为 msg-type(必需),文档见此处。
注意:msg-type 可以是任何有效的 Cosmos SDK Msg type url。
示例:
    simd tx authz grant cosmos1.. generic --msg-type=/cosmos.bank.v1beta1.MsgSend --from=cosmos1..
  • delegate、unbond、redelegate authorization_type 指内置的 StakeAuthorization 类型。可用的自定义参数为 spend-limit(可选)、allowed-validators(可选)和 deny-validators(可选),文档见此处。
注意:allowed-validators 和 deny-validators 不能同时为空。spend-limit 表示 MaxTokens
示例:
simd tx authz grant cosmos1.. delegate --spend-limit=100stake --allowed-validators=cosmos...,cosmos... --deny-validators=cosmos... --from=cosmos1..
revoke
revoke 命令允许 granter 撤销授予 grantee 的授权。
simd tx authz revoke [grantee] [msg-type-url] --from=[granter] [flags]
示例:
simd tx authz revoke cosmos1.. /cosmos.bank.v1beta1.MsgSend --from=cosmos1..

gRPC

用户可以使用 gRPC 端点查询 authz 模块。

Grants

Grants 端点允许用户查询某个 granter-grantee 对的授权。如果设置了消息类型 URL,则只选择该消息类型的授权。
cosmos.authz.v1beta1.Query/Grants
示例:
grpcurl -plaintext \
    -d '{"granter":"cosmos1..","grantee":"cosmos1..","msg_type_url":"/cosmos.bank.v1beta1.MsgSend"}' \
    localhost:9090 \
    cosmos.authz.v1beta1.Query/Grants
示例输出:
{
  "grants": [
    {
      "authorization": {
        "@type": "/cosmos.bank.v1beta1.SendAuthorization",
        "spendLimit": [
          {
            "denom":"stake",
            "amount":"100"
          }
        ]
      },
      "expiration": "2022-01-01T00:00:00Z"
    }
  ]
}

REST

用户可以使用 REST 端点查询 authz 模块。
/cosmos/authz/v1beta1/grants
示例:
curl "localhost:1317/cosmos/authz/v1beta1/grants?granter=cosmos1..&grantee=cosmos1..&msg_type_url=/cosmos.bank.v1beta1.MsgSend"
示例输出:
{
  "grants": [
    {
      "authorization": {
        "@type": "/cosmos.bank.v1beta1.SendAuthorization",
        "spend_limit": [
          {
            "denom": "stake",
            "amount": "100"
          }
        ]
      },
      "expiration": "2022-01-01T00:00:00Z"
    }
  ],
  "pagination": null
}

Abstract

x/authz is an implementation of a Cosmos SDK module, per ADR 30, 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. 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.
package authz

import (
    
	"github.com/cosmos/gogoproto/proto"

	sdk "github.com/cosmos/cosmos-sdk/types"
)

// Authorization represents the interface of various Authorization types implemented
// by other modules.
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
}

// AcceptResponse instruments the controller of an authz message if the request is accepted
// and if it should be updated or deleted.
type AcceptResponse struct {
	// If Accept=true, the controller can accept and authorization and handle the update.
	Accept bool
	// If Delete=true, the controller must delete the authorization object and release
	// storage resources.
	Delete bool
	// Controller, who is calling Authorization.Accept must check if `Updated != nil`. If yes,
	// it must use the updated version and handle the update on the storage level.
	Updated Authorization
}

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.
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L14-L22
package authz

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
)

var _ Authorization = &GenericAuthorization{
}

// NewGenericAuthorization creates a new GenericAuthorization object.
func NewGenericAuthorization(msgTypeURL string) *GenericAuthorization {
    return &GenericAuthorization{
    Msg: msgTypeURL,
}
}

// 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.
  • It takes an (optional) AllowList that specifies to which addresses a grantee can send token.
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/authz.proto#L11-L30
package types

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// TODO: Revisit this once we have proper gas fee framework.
// Ref: https://github.com/cosmos/cosmos-sdk/issues/9054
// Ref: https://github.com/cosmos/cosmos-sdk/discussions/9072
const gasCostPerIteration = uint64(10)

var _ authz.Authorization = &SendAuthorization{
}

// NewSendAuthorization creates a new SendAuthorization object.
func NewSendAuthorization(spendLimit sdk.Coins, allowed []sdk.AccAddress) *SendAuthorization {
    return &SendAuthorization{
    AllowList:  toBech32Addresses(allowed),
    SpendLimit: spendLimit,
}
}

// MsgTypeURL implements Authorization.MsgTypeURL.
func (a SendAuthorization)

MsgTypeURL()

string {
    return sdk.MsgTypeURL(&MsgSend{
})
}

// 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")
}
    toAddr := mSend.ToAddress

	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
}
    isAddrExists := false
    allowedList := a.GetAllowList()
    for _, addr := range allowedList {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "send authorization")
    if addr == toAddr {
    isAddrExists = true
			break
}
	
}
    if len(allowedList) > 0 && !isAddrExists {
    return authz.AcceptResponse{
}, sdkerrors.ErrUnauthorized.Wrapf("cannot send to %s address", toAddr)
}

return authz.AcceptResponse{
    Accept: true,
    Delete: false,
    Updated: &SendAuthorization{
    SpendLimit: limitLeft,
    AllowList: allowedList
}}, nil
}

// ValidateBasic implements Authorization.ValidateBasic.
func (a SendAuthorization)

ValidateBasic()

error {
    if a.SpendLimit == nil {
    return sdkerrors.ErrInvalidCoins.Wrap("spend limit cannot be nil")
}
    if !a.SpendLimit.IsAllPositive() {
    return sdkerrors.ErrInvalidCoins.Wrapf("spend limit must be positive")
}
    found := make(map[string]bool, 0)
    for i := 0; i < len(a.AllowList); i++ {
    if found[a.AllowList[i]] {
    return ErrDuplicateEntry
}

found[a.AllowList[i]] = true
}

return nil
}

func toBech32Addresses(allowed []sdk.AccAddress) []string {
    if len(allowed) == 0 {
    return nil
}
    allowedAddrs := make([]string, len(allowed))
    for i, addr := range allowed {
    allowedAddrs[i] = addr.String()
}

return allowedAddrs
}
  • spend_limit keeps track of how many coins are left in the authorization.
  • allow_list specifies 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. It takes an AuthorizationType to specify whether you want to authorise delegating, undelegating or redelegating (i.e. these have to be authorised separately). It also takes an optional 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.
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/authz.proto#L11-L35
package types

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// TODO: Revisit this once we have proper gas fee framework.
// Tracking issues https://github.com/cosmos/cosmos-sdk/issues/9054, https://github.com/cosmos/cosmos-sdk/discussions/9072
const gasCostPerIteration = uint64(10)

var _ authz.Authorization = &StakeAuthorization{
}

// 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
}

// MsgTypeURL implements Authorization.MsgTypeURL.
func (a StakeAuthorization)

MsgTypeURL()

string {
    authzType, err := normalizeAuthzType(a.AuthorizationType)
    if err != nil {
    panic(err)
}

return authzType
}

func (a StakeAuthorization)

ValidateBasic()

error {
    if a.MaxTokens != nil && a.MaxTokens.IsNegative() {
    return sdkerrors.Wrapf(authz.ErrNegativeMaxTokens, "negative coin amount: %v", a.MaxTokens)
}
    if a.AuthorizationType == AuthorizationType_AUTHORIZATION_TYPE_UNSPECIFIED {
    return authz.ErrUnknownAuthorizationType
}

return nil
}

// Accept implements Authorization.Accept.
func (a StakeAuthorization)

Accept(ctx sdk.Context, msg sdk.Msg) (authz.AcceptResponse, error) {
    var validatorAddress string
	var amount sdk.Coin
    switch msg := msg.(type) {
    case *MsgDelegate:
		validatorAddress = msg.ValidatorAddress
		amount = msg.Amount
    case *MsgUndelegate:
		validatorAddress = msg.ValidatorAddress
		amount = msg.Amount
    case *MsgBeginRedelegate:
		validatorAddress = msg.ValidatorDstAddress
		amount = msg.Amount
	default:
		return authz.AcceptResponse{
}, sdkerrors.ErrInvalidRequest.Wrap("unknown msg type")
}
    isValidatorExists := false
    allowedList := a.GetAllowList().GetAddress()
    for _, validator := range allowedList {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "stake authorization")
    if validator == validatorAddress {
    isValidatorExists = true
			break
}
	
}
    denyList := a.GetDenyList().GetAddress()
    for _, validator := range denyList {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "stake authorization")
    if validator == validatorAddress {
    return authz.AcceptResponse{
}, sdkerrors.ErrUnauthorized.Wrapf("cannot delegate/undelegate to %s validator", validator)
}
	
}
    if len(allowedList) > 0 && !isValidatorExists {
    return authz.AcceptResponse{
}, sdkerrors.ErrUnauthorized.Wrapf("cannot delegate/undelegate to %s validator", validatorAddress)
}
    if a.MaxTokens == nil {
    return authz.AcceptResponse{
    Accept: true,
    Delete: false,
    Updated: &StakeAuthorization{
    Validators: a.GetValidators(),
    AuthorizationType: a.GetAuthorizationType()
},
}, nil
}

limitLeft, err := a.MaxTokens.SafeSub(amount)
    if err != nil {
    return authz.AcceptResponse{
}, err
}
    if limitLeft.IsZero() {
    return authz.AcceptResponse{
    Accept: true,
    Delete: true
}, nil
}

return authz.AcceptResponse{
    Accept: true,
    Delete: false,
    Updated: &StakeAuthorization{
    Validators: a.GetValidators(),
    AuthorizationType: a.GetAuthorizationType(),
    MaxTokens: &limitLeft
},
}, nil
}

func validateAllowAndDenyValidators(allowed []sdk.ValAddress, denied []sdk.ValAddress) ([]string, []string, error) {
    if len(allowed) == 0 && len(denied) == 0 {
    return nil, nil, sdkerrors.ErrInvalidRequest.Wrap("both allowed & deny list cannot be empty")
}
    if len(allowed) > 0 && len(denied) > 0 {
    return nil, nil, sdkerrors.ErrInvalidRequest.Wrap("cannot set both allowed & deny list")
}
    allowedValidators := make([]string, len(allowed))
    if len(allowed) > 0 {
    for i, validator := range allowed {
    allowedValidators[i] = validator.String()
}

return allowedValidators, nil, nil
}
    deniedValidators := make([]string, len(denied))
    for i, validator := range denied {
    deniedValidators[i] = validator.String()
}

return nil, deniedValidators, nil
}

// Normalized Msg type URLs
func normalizeAuthzType(authzType AuthorizationType) (string, error) {
    switch authzType {
    case AuthorizationType_AUTHORIZATION_TYPE_DELEGATE:
		return sdk.MsgTypeURL(&MsgDelegate{
}), nil
    case AuthorizationType_AUTHORIZATION_TYPE_UNDELEGATE:
		return sdk.MsgTypeURL(&MsgUndelegate{
}), nil
    case AuthorizationType_AUTHORIZATION_TYPE_REDELEGATE:
		return sdk.MsgTypeURL(&MsgBeginRedelegate{
}), nil
	default:
		return "", sdkerrors.Wrapf(authz.ErrUnknownAuthorizationType, "cannot normalize authz type with %T", authzType)
}
}

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 maintains a list for granter, grantee pair with the same expiration, we are iterating over the list to remove the grant (in case of any revoke of a particular 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:
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L24-L32

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.
package keeper

import (
    
	"fmt"
    "strconv"
    "time"
    "github.com/cosmos/gogoproto/proto"
	abci "github.com/tendermint/tendermint/abci/types"
    "github.com/tendermint/tendermint/libs/log"
    "github.com/cosmos/cosmos-sdk/baseapp"
    "github.com/cosmos/cosmos-sdk/codec"
	codectypes "github.com/cosmos/cosmos-sdk/codec/types"
	storetypes "github.com/cosmos/cosmos-sdk/store/types"
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// TODO: Revisit this once we have proper gas fee framework.
// Tracking issues https://github.com/cosmos/cosmos-sdk/issues/9054,
// https://github.com/cosmos/cosmos-sdk/discussions/9072
const gasCostPerIteration = uint64(20)

type Keeper struct {
    storeKey   storetypes.StoreKey
	cdc        codec.BinaryCodec
	router     *baseapp.MsgServiceRouter
	authKeeper authz.AccountKeeper
}

// NewKeeper constructs a message authorization Keeper
func NewKeeper(storeKey storetypes.StoreKey, cdc codec.BinaryCodec, router *baseapp.MsgServiceRouter, ak authz.AccountKeeper)

Keeper {
    return Keeper{
    storeKey:   storeKey,
		cdc:        cdc,
		router:     router,
		authKeeper: ak,
}
}

// Logger returns a module-specific logger.
func (k Keeper)

Logger(ctx sdk.Context)

log.Logger {
    return ctx.Logger().With("module", fmt.Sprintf("x/%s", authz.ModuleName))
}

// getGrant returns grant stored at skey.
func (k Keeper)

getGrant(ctx sdk.Context, skey []byte) (grant authz.Grant, found bool) {
    store := ctx.KVStore(k.storeKey)
    bz := store.Get(skey)
    if bz == nil {
    return grant, false
}

k.cdc.MustUnmarshal(bz, &grant)

return grant, true
}

func (k Keeper)

update(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress, updated authz.Authorization)

error {
    skey := grantStoreKey(grantee, granter, updated.MsgTypeURL())

grant, found := k.getGrant(ctx, skey)
    if !found {
    return authz.ErrNoAuthorizationFound
}

msg, ok := updated.(proto.Message)
    if !ok {
    return sdkerrors.ErrPackAny.Wrapf("cannot proto marshal %T", updated)
}

any, err := codectypes.NewAnyWithValue(msg)
    if err != nil {
    return err
}

grant.Authorization = any
    store := ctx.KVStore(k.storeKey)

store.Set(skey, k.cdc.MustMarshal(&grant))

return nil
}

// DispatchActions attempts to execute the provided messages via authorization
// grants from the message signer to the grantee.
func (k Keeper)

DispatchActions(ctx sdk.Context, grantee sdk.AccAddress, msgs []sdk.Msg) ([][]byte, error) {
    results := make([][]byte, len(msgs))
    now := ctx.BlockTime()
    for i, msg := range msgs {
    signers := msg.GetSigners()
    if len(signers) != 1 {
    return nil, authz.ErrAuthorizationNumOfSigners
}
    granter := signers[0]

		// If granter != grantee then check authorization.Accept, otherwise we
		// implicitly accept.
    if !granter.Equals(grantee) {
    skey := grantStoreKey(grantee, granter, sdk.MsgTypeURL(msg))

grant, found := k.getGrant(ctx, skey)
    if !found {
    return nil, sdkerrors.Wrapf(authz.ErrNoAuthorizationFound, "failed to update grant with key %s", string(skey))
}
    if grant.Expiration != nil && grant.Expiration.Before(now) {
    return nil, authz.ErrAuthorizationExpired
}

authorization, err := grant.GetAuthorization()
    if err != nil {
    return nil, err
}

resp, err := authorization.Accept(ctx, msg)
    if err != nil {
    return nil, err
}
    if resp.Delete {
    err = k.DeleteGrant(ctx, grantee, granter, sdk.MsgTypeURL(msg))
}

else if resp.Updated != nil {
    err = k.update(ctx, grantee, granter, resp.Updated)
}
    if err != nil {
    return nil, err
}
    if !resp.Accept {
    return nil, sdkerrors.ErrUnauthorized
}
	
}
    handler := k.router.Handler(msg)
    if handler == nil {
    return nil, sdkerrors.ErrUnknownRequest.Wrapf("unrecognized message route: %s", sdk.MsgTypeURL(msg))
}

msgResp, err := handler(ctx, msg)
    if err != nil {
    return nil, sdkerrors.Wrapf(err, "failed to execute message; message %v", msg)
}

results[i] = msgResp.Data

		// emit the events from the dispatched actions
    events := msgResp.Events
    sdkEvents := make([]sdk.Event, 0, len(events))
    for _, event := range events {
    e := event
			e.Attributes = append(e.Attributes, abci.EventAttribute{
    Key: "authz_msg_index",
    Value: strconv.Itoa(i)
})

sdkEvents = append(sdkEvents, sdk.Event(e))
}

ctx.EventManager().EmitEvents(sdkEvents)
}

return results, nil
}

// SaveGrant method grants the provided authorization to the grantee on the granter's account
// with the provided expiration time and insert authorization key into the grants queue. If there is an existing authorization grant for the
// same `sdk.Msg` type, this grant overwrites that.
func (k Keeper)

SaveGrant(ctx sdk.Context, grantee, granter sdk.AccAddress, authorization authz.Authorization, expiration *time.Time)

error {
    store := ctx.KVStore(k.storeKey)
    msgType := authorization.MsgTypeURL()
    skey := grantStoreKey(grantee, granter, msgType)

grant, err := authz.NewGrant(ctx.BlockTime(), authorization, expiration)
    if err != nil {
    return err
}

var oldExp *time.Time
    if oldGrant, found := k.getGrant(ctx, skey); found {
    oldExp = oldGrant.Expiration
}
    if oldExp != nil && (expiration == nil || !oldExp.Equal(*expiration)) {
    if err = k.removeFromGrantQueue(ctx, skey, granter, grantee, *oldExp); err != nil {
    return err
}
	
}

	// If the expiration didn't change, then we don't remove it and we should not insert again
    if expiration != nil && (oldExp == nil || !oldExp.Equal(*expiration)) {
    if err = k.insertIntoGrantQueue(ctx, granter, grantee, msgType, *expiration); err != nil {
    return err
}
	
}
    bz := k.cdc.MustMarshal(&grant)

store.Set(skey, bz)

return ctx.EventManager().EmitTypedEvent(&authz.EventGrant{
    MsgTypeUrl: authorization.MsgTypeURL(),
    Granter:    granter.String(),
    Grantee:    grantee.String(),
})
}

// DeleteGrant revokes any authorization for the provided message type granted to the grantee
// by the granter.
func (k Keeper)

DeleteGrant(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress, msgType string)

error {
    store := ctx.KVStore(k.storeKey)
    skey := grantStoreKey(grantee, granter, msgType)

grant, found := k.getGrant(ctx, skey)
    if !found {
    return sdkerrors.Wrapf(authz.ErrNoAuthorizationFound, "failed to delete grant with key %s", string(skey))
}
    if grant.Expiration != nil {
    err := k.removeFromGrantQueue(ctx, skey, granter, grantee, *grant.Expiration)
    if err != nil {
    return err
}
	
}

store.Delete(skey)

return ctx.EventManager().EmitTypedEvent(&authz.EventRevoke{
    MsgTypeUrl: msgType,
    Granter:    granter.String(),
    Grantee:    grantee.String(),
})
}

// GetAuthorizations Returns list of `Authorizations` granted to the grantee by the granter.
func (k Keeper)

GetAuthorizations(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress) ([]authz.Authorization, error) {
    store := ctx.KVStore(k.storeKey)
    key := grantStoreKey(grantee, granter, "")
    iter := sdk.KVStorePrefixIterator(store, key)

defer iter.Close()

var authorization authz.Grant
	var authorizations []authz.Authorization
    for ; iter.Valid(); iter.Next() {
    if err := k.cdc.Unmarshal(iter.Value(), &authorization); err != nil {
    return nil, err
}

a, err := authorization.GetAuthorization()
    if err != nil {
    return nil, err
}

authorizations = append(authorizations, a)
}

return authorizations, nil
}

// GetAuthorization returns an Authorization and it's expiration time.
// A nil Authorization is returned under the following circumstances:
//   - No grant is found.
//   - A grant is found, but it is expired.
//   - There was an error getting the authorization from the grant.
func (k Keeper)

GetAuthorization(ctx sdk.Context, grantee sdk.AccAddress, granter sdk.AccAddress, msgType string) (authz.Authorization, *time.Time) {
    grant, found := k.getGrant(ctx, grantStoreKey(grantee, granter, msgType))
    if !found || (grant.Expiration != nil && grant.Expiration.Before(ctx.BlockHeader().Time)) {
    return nil, nil
}

auth, err := grant.GetAuthorization()
    if err != nil {
    return nil, nil
}

return auth, grant.Expiration
}

// IterateGrants iterates over all authorization grants
// This function should be used with caution because it can involve significant IO operations.
// It should not be used in query or msg services without charging additional gas.
// The iteration stops when the handler function returns true or the iterator exhaust.
func (k Keeper)

IterateGrants(ctx sdk.Context,
	handler func(granterAddr sdk.AccAddress, granteeAddr sdk.AccAddress, grant authz.Grant)

bool,
) {
    store := ctx.KVStore(k.storeKey)
    iter := sdk.KVStorePrefixIterator(store, GrantKey)

defer iter.Close()
    for ; iter.Valid(); iter.Next() {
    var grant authz.Grant
		granterAddr, granteeAddr, _ := parseGrantStoreKey(iter.Key())

k.cdc.MustUnmarshal(iter.Value(), &grant)
    if handler(granterAddr, granteeAddr, grant) {
    break
}
	
}
}

func (k Keeper)

getGrantQueueItem(ctx sdk.Context, expiration time.Time, granter, grantee sdk.AccAddress) (*authz.GrantQueueItem, error) {
    store := ctx.KVStore(k.storeKey)
    bz := store.Get(GrantQueueKey(expiration, granter, grantee))
    if bz == nil {
    return &authz.GrantQueueItem{
}, nil
}

var queueItems authz.GrantQueueItem
    if err := k.cdc.Unmarshal(bz, &queueItems); err != nil {
    return nil, err
}

return &queueItems, nil
}

func (k Keeper)

setGrantQueueItem(ctx sdk.Context, expiration time.Time,
	granter sdk.AccAddress, grantee sdk.AccAddress, queueItems *authz.GrantQueueItem,
)

error {
    store := ctx.KVStore(k.storeKey)

bz, err := k.cdc.Marshal(queueItems)
    if err != nil {
    return err
}

store.Set(GrantQueueKey(expiration, granter, grantee), bz)

return nil
}

// insertIntoGrantQueue inserts a grant key into the grant queue
func (k Keeper)

insertIntoGrantQueue(ctx sdk.Context, granter, grantee sdk.AccAddress, msgType string, expiration time.Time)

error {
    queueItems, err := k.getGrantQueueItem(ctx, expiration, granter, grantee)
    if err != nil {
    return err
}
    if len(queueItems.MsgTypeUrls) == 0 {
    k.setGrantQueueItem(ctx, expiration, granter, grantee, &authz.GrantQueueItem{
    MsgTypeUrls: []string{
    msgType
},
})
}

else {
    queueItems.MsgTypeUrls = append(queueItems.MsgTypeUrls, msgType)

k.setGrantQueueItem(ctx, expiration, granter, grantee, queueItems)
}

return nil
}

// removeFromGrantQueue removes a grant key from the grant queue
func (k Keeper)

removeFromGrantQueue(ctx sdk.Context, grantKey []byte, granter, grantee sdk.AccAddress, expiration time.Time)

error {
    store := ctx.KVStore(k.storeKey)
    key := GrantQueueKey(expiration, granter, grantee)
    bz := store.Get(key)
    if bz == nil {
    return sdkerrors.Wrap(authz.ErrNoGrantKeyFound, "can't remove grant from the expire queue, grant key not found")
}

var queueItem authz.GrantQueueItem
    if err := k.cdc.Unmarshal(bz, &queueItem); err != nil {
    return err
}

	_, _, msgType := parseGrantStoreKey(grantKey)
    queueItems := queueItem.MsgTypeUrls
    for index, typeURL := range queueItems {
    ctx.GasMeter().ConsumeGas(gasCostPerIteration, "grant queue")
    if typeURL == msgType {
    end := len(queueItem.MsgTypeUrls) - 1
			queueItems[index] = queueItems[end]
			queueItems = queueItems[:end]
    if err := k.setGrantQueueItem(ctx, expiration, granter, grantee, &authz.GrantQueueItem{
    MsgTypeUrls: queueItems,
}); err != nil {
    return err
}

break
}
	
}

return nil
}

// DequeueAndDeleteExpiredGrants deletes expired grants from the state and grant queue.
func (k Keeper)

DequeueAndDeleteExpiredGrants(ctx sdk.Context)

error {
    store := ctx.KVStore(k.storeKey)
    iterator := store.Iterator(GrantQueuePrefix, sdk.InclusiveEndBytes(GrantQueueTimePrefix(ctx.BlockTime())))

defer iterator.Close()
    for ; iterator.Valid(); iterator.Next() {
    var queueItem authz.GrantQueueItem
    if err := k.cdc.Unmarshal(iterator.Value(), &queueItem); err != nil {
    return err
}

		_, granter, grantee, err := parseGrantQueueKey(iterator.Key())
    if err != nil {
    return err
}

store.Delete(iterator.Key())
    for _, typeURL := range queueItem.MsgTypeUrls {
    store.Delete(grantStoreKey(grantee, granter, typeURL))
}
	
}

return nil
}
  • 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".
package keeper

import (
    
	"time"
    "github.com/cosmos/cosmos-sdk/internal/conv"
	sdk "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/types/address"
    "github.com/cosmos/cosmos-sdk/types/kv"
    "github.com/cosmos/cosmos-sdk/x/authz"
)

// Keys for store prefixes
// Items are stored with the following key: values
//
// - 0x01<grant_Bytes>: Grant
// - 0x02<grant_expiration_Bytes>: GrantQueueItem
var (
	GrantKey         = []byte{0x01
} // prefix for each key
	GrantQueuePrefix = []byte{0x02
}
)

var lenTime = len(sdk.FormatTimeBytes(time.Now()))

// StoreKey is the store key string for authz
const StoreKey = authz.ModuleName

// grantStoreKey - return authorization store key
// Items are stored with the following key: values
//
// - 0x01<granterAddressLen (1 Byte)><granterAddress_Bytes><granteeAddressLen (1 Byte)><granteeAddress_Bytes><msgType_Bytes>: Grant
func grantStoreKey(grantee sdk.AccAddress, granter sdk.AccAddress, msgType string) []byte {
    m := conv.UnsafeStrToBytes(msgType)

granter = address.MustLengthPrefix(granter)

grantee = address.MustLengthPrefix(grantee)
    key := sdk.AppendLengthPrefixedBytes(GrantKey, granter, grantee, m)

return key
}

// parseGrantStoreKey - split granter, grantee address and msg type from the authorization key
func parseGrantStoreKey(key []byte) (granterAddr, granteeAddr sdk.AccAddress, msgType string) {
	// key is of format:
	// 0x01<granterAddressLen (1 Byte)><granterAddress_Bytes><granteeAddressLen (1 Byte)><granteeAddress_Bytes><msgType_Bytes>

	granterAddrLen, granterAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, 1, 1) // ignore key[0] since it is a prefix key
	granterAddr, granterAddrEndIndex := sdk.ParseLengthPrefixedBytes(key, granterAddrLenEndIndex+1, int(granterAddrLen[0]))

granteeAddrLen, granteeAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, granterAddrEndIndex+1, 1)

granteeAddr, granteeAddrEndIndex := sdk.ParseLengthPrefixedBytes(key, granteeAddrLenEndIndex+1, int(granteeAddrLen[0]))

kv.AssertKeyAtLeastLength(key, granteeAddrEndIndex+1)

return granterAddr, granteeAddr, conv.UnsafeBytesToStr(key[(granteeAddrEndIndex + 1):])
}

// parseGrantQueueKey split expiration time, granter and grantee from the grant queue key
func parseGrantQueueKey(key []byte) (time.Time, sdk.AccAddress, sdk.AccAddress, error) {
	// key is of format:
	// 0x02<grant_expiration_Bytes><granterAddress_Bytes><granteeAddressLen (1 Byte)><granteeAddress_Bytes>

	expBytes, expEndIndex := sdk.ParseLengthPrefixedBytes(key, 1, lenTime)

exp, err := sdk.ParseTimeBytes(expBytes)
    if err != nil {
    return exp, nil, nil, err
}

granterAddrLen, granterAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, expEndIndex+1, 1)

granter, granterEndIndex := sdk.ParseLengthPrefixedBytes(key, granterAddrLenEndIndex+1, int(granterAddrLen[0]))

granteeAddrLen, granteeAddrLenEndIndex := sdk.ParseLengthPrefixedBytes(key, granterEndIndex+1, 1)

grantee, _ := sdk.ParseLengthPrefixedBytes(key, granteeAddrLenEndIndex+1, int(granteeAddrLen[0]))

return exp, granter, grantee, nil
}

// GrantQueueKey - return grant queue store key. If a given grant doesn't have a defined
// expiration, then it should not be used in the pruning queue.
// Key format is:
//
//	0x02<expiration><granterAddressLen (1 Byte)><granterAddressBytes><granteeAddressLen (1 Byte)><granteeAddressBytes>: GrantQueueItem
func GrantQueueKey(expiration time.Time, granter sdk.AccAddress, grantee sdk.AccAddress) []byte {
    exp := sdk.FormatTimeBytes(expiration)

granter = address.MustLengthPrefix(granter)

grantee = address.MustLengthPrefix(grantee)

return sdk.AppendLengthPrefixedBytes(GrantQueuePrefix, exp, granter, grantee)
}

// GrantQueueTimePrefix - return grant queue time prefix
func GrantQueueTimePrefix(expiration time.Time) []byte {
    return append(GrantQueuePrefix, sdk.FormatTimeBytes(expiration)...)
}

// firstAddressFromGrantStoreKey parses the first address only
func firstAddressFromGrantStoreKey(key []byte)

sdk.AccAddress {
    addrLen := key[0]
	return sdk.AccAddress(key[1 : 1+addrLen])
}
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.
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L35-L45
The message handling should fail if:
  • both granter and grantee have the same address.
  • provided Expiration time is less than current unix timestamp (but a grant will be created if no expiration time is provided since expiration is optional).
  • provided Grant.Authorization is 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.
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L69-L78
The message handling should fail if:
  • both granter and grantee have the same address.
  • provided MsgTypeUrl is 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.
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L52-L63
The message handling should fail if:
  • provided Authorization is 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.

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.
simd query authz --help
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.
simd query authz grants [granter-addr] [grantee-addr] [msg-type-url]? [flags]
Example:
simd query authz grants cosmos1.. cosmos1.. /cosmos.bank.v1beta1.MsgSend
Example Output:
grants:
- authorization:
    '@type': /cosmos.bank.v1beta1.SendAuthorization
    spend_limit:
    - amount: "100"
      denom: stake
  expiration: "2022-01-01T00:00:00Z"
pagination: null

Transactions

The tx commands allow users to interact with the authz module.
simd tx authz --help
exec
The exec command allows a grantee to execute a transaction on behalf of granter.
  simd tx authz exec [tx-json-file] --from [grantee] [flags]
Example:
simd tx authz exec tx.json --from=cosmos1..
grant
The grant command allows a granter to grant an authorization to a grantee.
simd tx authz grant <grantee> <authorization_type="send"|"generic"|"delegate"|"unbond"|"redelegate"> --from <granter> [flags]
  • The send authorization_type refers to the built-in SendAuthorization type. The custom flags available are spend-limit (required) and allow-list (optional) , documented here
Example:
    simd tx authz grant cosmos1.. send --spend-limit=100stake --allow-list=cosmos1...,cosmos2... --from=cosmos1..
  • The generic authorization_type refers to the built-in GenericAuthorization type. The custom flag available is msg-type ( required) documented here.
Note: msg-type is any valid Cosmos SDK Msg type url.
Example:
    simd tx authz grant cosmos1.. generic --msg-type=/cosmos.bank.v1beta1.MsgSend --from=cosmos1..
  • The delegate,unbond,redelegate authorization_types refer to the built-in StakeAuthorization type. The custom flags available are spend-limit (optional), allowed-validators (optional) and deny-validators (optional) documented here.
Note: allowed-validators and deny-validators cannot both be empty. spend-limit represents the MaxTokens
Example:
simd tx authz grant cosmos1.. delegate --spend-limit=100stake --allowed-validators=cosmos...,cosmos... --deny-validators=cosmos... --from=cosmos1..
revoke
The revoke command allows a granter to revoke an authorization from a grantee.
simd tx authz revoke [grantee] [msg-type-url] --from=[granter] [flags]
Example:
simd tx authz revoke cosmos1.. /cosmos.bank.v1beta1.MsgSend --from=cosmos1..

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.
cosmos.authz.v1beta1.Query/Grants
Example:
grpcurl -plaintext \
    -d '{"granter":"cosmos1..","grantee":"cosmos1..","msg_type_url":"/cosmos.bank.v1beta1.MsgSend"}' \
    localhost:9090 \
    cosmos.authz.v1beta1.Query/Grants
Example Output:
{
  "grants": [
    {
      "authorization": {
        "@type": "/cosmos.bank.v1beta1.SendAuthorization",
        "spendLimit": [
          {
            "denom":"stake",
            "amount":"100"
          }
        ]
      },
      "expiration": "2022-01-01T00:00:00Z"
    }
  ]
}

REST

A user can query the authz module using REST endpoints.
/cosmos/authz/v1beta1/grants
Example:
curl "localhost:1317/cosmos/authz/v1beta1/grants?granter=cosmos1..&grantee=cosmos1..&msg_type_url=/cosmos.bank.v1beta1.MsgSend"
Example Output:
{
  "grants": [
    {
      "authorization": {
        "@type": "/cosmos.bank.v1beta1.SendAuthorization",
        "spend_limit": [
          {
            "denom": "stake",
            "amount": "100"
          }
        ]
      },
      "expiration": "2022-01-01T00:00:00Z"
    }
  ],
  "pagination": null
}