Manage authz grants and fee allowances

Let one account act for another on the IXO Protocol: grant, execute and revoke a Cosmos authz authorisation, and grant and revoke a feegrant fee allowance.

Use this guide to let one account act for another on the IXO Protocol. Authorisation (x/authz) lets one account grant another the right to broadcast specific message types on its behalf, scoped by amount, time, or message URL. x/feegrant lets one account pay another's transaction fees. Both are standard Cosmos SDK modules, and IXO uses the upstream message types directly.

After reading this page you will be able to grant and revoke an authorisation, execute a granted message, and grant and revoke a fee allowance.

Before you start

You need:

  • An IXO account with uixo for fees on the network you target. See Networks and endpoints.
  • An offline signer. See the SDK README.
  • The granter and grantee bech32 addresses.

Install the IXO MultiClient SDK and create a signing client. Illustrative example:

npm install @ixo/impactxclient-sdk
import { cosmos, createSigningClient } from "@ixo/impactxclient-sdk";

const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);

Steps

1. Grant a send authorisation

SendAuthorization lets the grantee call cosmos.bank.v1beta1.MsgSend from the granter, capped at spend_limit.

Illustrative example:

const sendAuth = cosmos.bank.v1beta1.SendAuthorization.fromPartial({
  spendLimit: [{ denom: "uixo", amount: "1000000" }],
});

const grantMsg = {
  typeUrl: "/cosmos.authz.v1beta1.MsgGrant",
  value: cosmos.authz.v1beta1.MsgGrant.fromPartial({
    granter: granterAddress,
    grantee: granteeAddress,
    grant: cosmos.authz.v1beta1.Grant.fromPartial({
      authorization: {
        typeUrl: "/cosmos.bank.v1beta1.SendAuthorization",
        value: cosmos.bank.v1beta1.SendAuthorization.encode(sendAuth).finish(),
      },
    }),
  }),
};

await signingClient.signAndBroadcast(granterAddress, [grantMsg], "auto");

For a broader grant, for example to authorise any IBC transfer message URL, use cosmos.authz.v1beta1.GenericAuthorization with the target msg type URL.

2. Execute a granted message

The grantee wraps the message they were authorised to send inside cosmos.authz.v1beta1.MsgExec.

Illustrative example:

const innerSend = cosmos.bank.v1beta1.MsgSend.fromPartial({
  fromAddress: granterAddress,
  toAddress: recipientAddress,
  amount: [{ denom: "uixo", amount: "100000" }],
});

const execMsg = {
  typeUrl: "/cosmos.authz.v1beta1.MsgExec",
  value: cosmos.authz.v1beta1.MsgExec.fromPartial({
    grantee: granteeAddress,
    msgs: [
      {
        typeUrl: "/cosmos.bank.v1beta1.MsgSend",
        value: cosmos.bank.v1beta1.MsgSend.encode(innerSend).finish(),
      },
    ],
  }),
};

await signingClient.signAndBroadcast(granteeAddress, [execMsg], "auto");

For an IBC transfer, replace the inner message with ibc.applications.transfer.v1.MsgTransfer.

3. Revoke an authorisation

Illustrative example:

const revokeMsg = {
  typeUrl: "/cosmos.authz.v1beta1.MsgRevoke",
  value: cosmos.authz.v1beta1.MsgRevoke.fromPartial({
    granter: granterAddress,
    grantee: granteeAddress,
    msgTypeUrl: "/cosmos.bank.v1beta1.MsgSend",
  }),
};

4. Grant a fee allowance

Illustrative example:

const basicAllowance = cosmos.feegrant.v1beta1.BasicAllowance.fromPartial({
  spendLimit: [{ denom: "uixo", amount: "500000" }],
});

const grantAllowanceMsg = {
  typeUrl: "/cosmos.feegrant.v1beta1.MsgGrantAllowance",
  value: cosmos.feegrant.v1beta1.MsgGrantAllowance.fromPartial({
    granter: granterAddress,
    grantee: granteeAddress,
    allowance: {
      typeUrl: "/cosmos.feegrant.v1beta1.BasicAllowance",
      value: cosmos.feegrant.v1beta1.BasicAllowance.encode(basicAllowance).finish(),
    },
  }),
};

To use the allowance, the grantee sets the granter's address as the feePayer in the transaction's fee object. The granter is debited instead of the grantee.

Use AllowedMsgAllowance to combine fee payment with a strict whitelist of message URLs the grantee may submit at the granter's expense.

5. Revoke a fee allowance

Illustrative example:

const revokeAllowanceMsg = {
  typeUrl: "/cosmos.feegrant.v1beta1.MsgRevokeAllowance",
  value: cosmos.feegrant.v1beta1.MsgRevokeAllowance.fromPartial({
    granter: granterAddress,
    grantee: granteeAddress,
  }),
};

Check the result

Query active grants through the gRPC gateway API.

QueryReturns
cosmos.authz.v1beta1.Query/GrantsGrants between a granter and a grantee
cosmos.authz.v1beta1.Query/GranterGrantsAll grants issued by a granter
cosmos.authz.v1beta1.Query/GranteeGrantsAll grants received by a grantee
cosmos.feegrant.v1beta1.Query/AllowanceFee allowance status

When something goes wrong

What you seeWhat to check
Invalid authorisation parametersThe bech32 addresses are valid for the chain prefix (ixo), the denom is supported, and the amount is within spend_limit.
Execution failuresThe grant has not expired, the grantee's transaction message URL exactly matches the authorisation's allowed type, and the spend limit has not been exhausted.
Fee allowance issuesThe granter has sufficient balance for the allowance, the allowance type matches the use case (BasicAllowance vs PeriodicAllowance vs AllowedMsgAllowance), and the transaction's feePayer is set to the granter.

Next steps