Skip to main content

x/authz

Transactions​

In general, a granter can grant an authorization to a grantee or revoke an existing authorization already granted to the grantee. A grantee can execute an authorization already granted by the granter.

grant​

An authorization starts from the granter granting the grantee.

  • under SendAuthorization

tx authz grant [grantee_address] send --spend-limit [amount] --from [granter_address]

Example: Grant to send with a spend limit and an expiration time

The granter may grant a grantee to send tokens on the granter's behalf, where a spend limit should be provided through the --spend-limit flag. For example, granter may authorize grantee to spend up to 10 SHR, and sets an expiration time at the end of the year 2022 (i.e. 1672531199 in Unix timestamp) by running

$ shareledger tx authz grant <grantee_address> send --spend-limit 10000000000nshr --from <granter_address> --expiration 1672531199 --chain-id <chain-id>

## Illustrative partial transaction payload
{
  "@type": "/cosmos.authz.v1beta1.MsgGrant",
  "grant": {
      "authorization": {
          "@type": "/cosmos.bank.v1beta1.SendAuthorization",
          "spend_limit": [
              {
                  "amount": "10000000000",
                  "denom": "nshr"
              }
          ]
      },
      "expiration": "2022-12-31T23:59:59Z"
  },
  "grantee": "shareledger...",
  "granter": "shareledger..."
}
  • under StakeAuthorization

tx authz grant [grantee_address] delegate --spend-limit [amount] --allowed-validators [list_of_allowed_validators_separated_by_,] --from [granter_address]

Example: Grant to delegate to validators on a specified list with a spend limit

The granter may grant a grantee to delegate tokens on the granter's behalf, where either a list of allowed validators (through the --allowed-validators flag) or denied validators (through the --deny-validators flag) should be provided. For example, granter may authorize grantee to delegate on the granter's behalf up to 10 SHR towards a specified list of validators by running

$ shareledger tx authz grant <grantee_address> delegate --spend-limit 10000000000nshr --allowed-validators <list_of_allowed_validators_separated_by_,> --from <granter_address> --expiration <expiration_time> --chain-id <chain-id>

## Illustrative partial transaction payload ##
{
  "@type": "/cosmos.authz.v1beta1.MsgGrant",
  "grant": {
      "authorization": {
          "@type": "/cosmos.staking.v1beta1.StakeAuthorization",
          "allow_list": {
              "address": [
                  "shareledger..."
              ]
          },
          "authorization_type": "AUTHORIZATION_TYPE_REDELEGATE",
          "max_tokens": {
              "amount": "10000000000",
              "denom": "nshr"
          }
      },
      "expiration": "2022-12-31T23:59:59Z"
  },
  "grantee": "shareledger...",
  "granter": "shareledger..."
}

On the contrary, the granter may choose to exclude a list of validators the grantee can delegate to on the granter's behalf:

tx authz grant [grantee_address] delegate --spend-limit [amount] --deny-validators [list_of_deny_validators_separated_by_,] --from [granter_address] - Grant to delegate to validators excluding a specified list

Granting to redelegate or undelegate (unbond) is very similar by just replacing the delegate with redelegate or unbond:

tx authz grant [grantee_address] redelegate --spend-limit [amount] --allowed-validators [list_of_allowed_validators_separated_by_,] --from [granter_address] - Grant to redelegate to validators on a specified list

tx authz grant [grantee_address] unbond --spend-limit [amount] --allowed-validators [list_of_allowed_validators_separated_by_,] --from [granter_address] - Grant to unbond from validators on a specified list

NOTE

Spend Limit for StakeAuthorization: A spend limit for a grant to delegate/redelegate/unbond is not necessary but generally recommended.

  • under GenericAuthorization Other than the above grants under SendAuthorization or StakeAuthorization, one may authorize other grants through GenericAuthorization:

tx authz grant [grantee_address] generic --msg-type [msg_type_url] --from [granter_address] - Grant for generic authorization with a specified Message Type URL

Example: Grant to withdraw delegator reward
$ shareledger tx authz grant <grantee_address> generic --msg-type /cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward --from <granter_address> --expiration <expiration_time> --chain-id <chain-id>

## Illustrative partial transaction payload
{
  "@type": "/cosmos.authz.v1beta1.MsgGrant",
  "grant": {
      "authorization": {
          "@type": "/cosmos.authz.v1beta1.GenericAuthorization",
          "msg": "/cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward"
      },
      "expiration": "2022-12-31T23:59:59Z"
  },
  "grantee": "shareledger...",
  "granter": "shareledger..."
}
NOTE

Message Type URL & Updating an Existing Grant: At any time, there is up to one grant allowed for each Message Type URL over a unique granter-grantee pair. To update an existing grant, the granter will need to re-grant the grantee and the new grant will overwrite the old grant.

exec​

The exec transaction composes of 2 transactions:

  • the authorized transaction: the transaction to be executed on behalf of the granter
  • the execution transaction: the transaction that contains and executes the above authorized transaction.

After a valid grant is set up, the grantee needs to first prepare the authorized transaction, in JSON format, on behalf of the granter. For instance, when the grantee wants to execute a SendAuthorization to send 10 SHR from the granter to a recipient, one easy way to generate such authorized transaction and saves it to a file named tx.json is to use the --generate-only flag by running:

$ shareledger tx bank send <granter_address> <recipient_address> 10000000000nshr --from <granter_address> --chain-id <chain-id> --generate-only > tx.json

## Illustrative partial transaction payload in tx.json
{
    "@type": "/cosmos.bank.v1beta1.MsgSend",
    "amount": [
        {
            "amount": "10000000000",
            "denom": "nshr"
        }
    ],
    "from_address": "shareledger...",
    "to_address": "shareledger..."
}
NOTE

The authorized transaction here does not need to be signed and the address after the --from flag is the granter_address instead of the grantee_address. In other words, this authorized transaction is created by the grantee but prepared as if he/she were the granter.

After the authorized transaction is properly prepared, the grantee needs to issue an execution transaction to execute the authorized transaction:

tx authz exec [tx_json] --from [grantee_address] - Execute an authorization

$ shareledger tx authz exec tx.json --from <grantee_address> --chain-id <chain-id>

## Illustrative partial transaction payload
{
    "@type": "/cosmos.authz.v1beta1.MsgExec",
    "grantee": "shareledger...",
    "msgs": [
        {
            "@type": "/cosmos.bank.v1beta1.MsgSend",
            "amount": [
                {
                    "amount": "10000000000",
                    "denom": "nshr"
                }
            ],
            "from_address": "shareledger...",
            "to_address": "shareledger..."
        }
    ]
}

Likewise, all valid authorized grants can be executed with proper authorized transaction and execution transaction.

revoke​

The granter may choose to revoke an existing authorization already granted to the grantee by running:

tx authz revoke [grantee_address] [msg_type_url] --from [granter_address] - Revoke an authorization with a specified Message Type URL

Example: Revoke an existing SendAuthorization
$ shareledger tx authz revoke <grantee_address> /cosmos.bank.v1beta1.MsgSend --from <granter_address> --chain-id <chain-id>

## Illustrative partial transaction payload
{
  "@type": "/cosmos.authz.v1beta1.MsgRevoke",
  "grantee": "shareledger...",
  "granter": "shareledger...",
  "msg_type_url": "/cosmos.bank.v1beta1.MsgSend"
}

Queries​

query authz grants [granter_address] [grantee_address] - Query all existing grants between a granter-grantee pair

Example: Query all existing grants between the specified granter and grantee
$ shareledger query authz grants <granter_address> <grantee_address> --output json
{
"grants": [
  {
    "authorization": {
      "@type": "/cosmos.authz.v1beta1.GenericAuthorization",
      "msg": "/cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward"
    },
    "expiration": "2022-12-31T23:59:59Z"
  },
  {
    "authorization": {
      "@type": "/cosmos.staking.v1beta1.StakeAuthorization",
      "max_tokens": {
        "denom": "nshr",
        "amount": "10000000000"
      },
      "allow_list": {
        "address": [
          "crocn..."
        ]
      },
      "authorization_type": "AUTHORIZATION_TYPE_DELEGATE"
    },
    "expiration": "2022-12-31T23:59:59Z"
  }
],
"pagination": {
  "next_key": null,
  "total": "0"
}
}
Last updated on