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.
Illustrative example. The code on this page shows the shape of each message. It is not a tested project you can run as written: you supply the signer, the endpoint and the addresses. Try it on a test network first.
Before you start
You need:
- An IXO account with
uixofor 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-sdkimport { 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.
| Query | Returns |
|---|---|
cosmos.authz.v1beta1.Query/Grants | Grants between a granter and a grantee |
cosmos.authz.v1beta1.Query/GranterGrants | All grants issued by a granter |
cosmos.authz.v1beta1.Query/GranteeGrants | All grants received by a grantee |
cosmos.feegrant.v1beta1.Query/Allowance | Fee allowance status |
When something goes wrong
| What you see | What to check |
|---|---|
| Invalid authorisation parameters | The bech32 addresses are valid for the chain prefix (ixo), the denom is supported, and the amount is within spend_limit. |
| Execution failures | The 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 issues | The 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
How a grant is stored, and the IXO authorisation types for claims.
Manage smart accountsAdd programmable authenticators on top of authz.
Cosmos authz moduleFull reference for x/authz.
Full reference for x/feegrant.