Manage smart accounts

Add and remove authenticators on an IXO smart account, select them on a transaction, combine them with composite rules, and check what an account registered.

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.

Before you start

You need:

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

npm install @ixo/impactxclient-sdk
import { 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:

  1. Authenticate. Verify that the transaction is authorised.
  2. Track. Record any state changes the authenticator needs. These are committed regardless of the transaction's outcome.
  3. 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 seeWhat to do
Unknown authenticator typeauthenticatorType 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 foundMsgRemoveAuthenticator fails when id does not exist for sender. Query AccountAuthenticators to confirm the id.
Module inactiveWhen is_smart_account_active is false, MsgAddAuthenticator and MsgRemoveAuthenticator are rejected. The module is gated by gov through MsgSetActiveState.
Signature verification failedCheck 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