Use this guide to put your own rules on how an IXO account's transactions are authenticated. The
IXO smartaccount module replaces the default Cosmos SDK signature ante handler with a pluggable
system that each account opts in to. An account can register one or more authenticators:
signature verifiers, message filters, spend-limit contracts, or composite logic. They execute on
every transaction the account opts in to. If no authenticators are selected, a transaction falls
back to the standard Cosmos SDK signature flow.
After reading this page you will be able to add and remove an authenticator, select authenticators on a transaction, and query what an account has registered.
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 authenticator's configuration. 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.
- An authenticator type and config payload to register. The supported types are defined in the smartaccount types proto.
Install the IXO MultiClient SDK and create a signing client. Illustrative example:
npm install @ixo/impactxclient-sdkimport { ixo, createSigningClient } from "@ixo/impactxclient-sdk";
const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);Steps
1. Add an authenticator
Illustrative example:
const addAuthenticatorMsg = {
typeUrl: "/ixo.smartaccount.v1beta1.MsgAddAuthenticator",
value: ixo.smartaccount.v1beta1.MsgAddAuthenticator.fromPartial({
sender: signerAddress,
authenticatorType: "SignatureVerification",
data: new TextEncoder().encode(JSON.stringify({ pubkey: pubkeyHex })),
}),
};
await signingClient.signAndBroadcast(signerAddress, [addAuthenticatorMsg], "auto");The chain assigns an id to each authenticator on success. Read it from the transaction events so
that you can refer to the authenticator in later transactions.
2. Use authenticators on a transaction
A transaction opts in to specific authenticators through the AuthenticatorTxExtension TX
extension. The extension carries the list of authenticator IDs to use for each signer.
The full pattern depends on your signing flow. For the helpers that exist, see the smartaccount module README and the README for the IXO MultiClient SDK.
3. Remove an authenticator
Illustrative example:
const removeAuthenticatorMsg = {
typeUrl: "/ixo.smartaccount.v1beta1.MsgRemoveAuthenticator",
value: ixo.smartaccount.v1beta1.MsgRemoveAuthenticator.fromPartial({
sender: signerAddress,
id: 1n,
}),
};Check the result
Query an account's authenticators through the
ixo.smartaccount.v1beta1.Query/AccountAuthenticators endpoint on the
gRPC gateway API. Module params, including
is_smart_account_active, are read from Query/Params.
What an authenticator does on each transaction
Each authenticator runs through three phases on every transaction:
- Authenticate. Verify that the transaction is authorised.
- Track. Record any state changes the authenticator needs. These are committed regardless of the transaction's outcome.
- Confirm execution. Validate the effects after execution.
Composite authenticators
A composite authenticator combines sub-authenticators with boolean logic.
- AllOf. Approves only when every sub-authenticator approves:
auth(a) && auth(b) && .... - AnyOf. Approves when at least one sub-authenticator approves:
auth(a) || auth(b) || .... - PartitionedAllOf. Multi-signature where signatures are split across sub-authenticators, one signer per sub-authenticator.
Example shapes:
// One-click trading: hot key restricted to swap messages with on-chain spend-limit guard
AllOf(
SignatureVerification(usersPubKey),
AnyOf(
MessageFilter(SwapMsg1),
MessageFilter(SwapMsg2)
),
CosmwasmAuthenticator(spendLimitContract, params)
)
// Multisig (2-of-3): each signer satisfies one branch
PartitionedAllOf(pubkey1, pubkey2, pubkey3)
// Cosigner protection: cosigner approves alongside a user-selected set
AllOf(
SignatureVerification(cosignerPubKey),
AnyOf(...userAuthenticators)
)Pause the module (governance)
MsgSetActiveState is the module's circuit breaker. Only the module's gov authority can broadcast
it.
Illustrative example:
const setActiveMsg = ixo.smartaccount.v1beta1.MsgSetActiveState.fromPartial({
authority: govAuthority,
active: false,
});When active is false, the smart-account ante handler is skipped and all transactions use the
default Cosmos SDK signature path.
When something goes wrong
| What you see | What to do |
|---|---|
| Unknown authenticator type | authenticatorType must match one of the registered types in the chain's smartaccount module. Check Query/Params.maximum_unauthenticated_gas and the module's registered types. |
| Authenticator id not found | MsgRemoveAuthenticator fails when id does not exist for sender. Query AccountAuthenticators to confirm the id. |
| Module inactive | When is_smart_account_active is false, MsgAddAuthenticator and MsgRemoveAuthenticator are rejected. The module is gated by gov through MsgSetActiveState. |
| Signature verification failed | Check that the TX extension lists the correct authenticator IDs in the order matching the signer set, and that the data payload registered with MsgAddAuthenticator is the canonical encoding for that authenticator type. |
Next steps
Module-level features and types.
Smart account protoThe definitions of the smart-account messages.
(opens in a new tab)Session signing with SignXSign from a browser app with the user's mobile wallet, and pair it with authenticators.
Manage authz grants and fee allowancesUse Cosmos authz alongside smart-account authenticators.