Skip to main content

Authenticators & delegated spending

Authenticator lanes (SDK 0.7.0, chain v3.1.85) let a linked external key — a Phantom ed25519 key, or a MetaMask / EVM secp256k1 key — spend from the ONE canonical PQC-required account under least-privilege, spend-limited, revocable terms, without the external key ever producing an ML-DSA co-signature.

This is the SDK counterpart of the chain's account abstraction module.

Not available on mainnet

The x/abstractaccount module is disabled on qorechain-vladi (mainnet): GET /qorechain/abstractaccount/v1/config returns "enabled": false. From chain v3.2.0 that flag is enforced on every path (creating an abstract account, linking an authenticator, and both MsgExecuteEVM / MsgExecuteCosmos), and the chain refuses them with abstract account module is disabled (code 9). No transaction can switch it on. On the qorechain-diana testnet the same route returned "enabled": true on 27 October 2026, so the flows below can be tried there. Do not build a linked-key or delegated-spending flow for mainnet until the module is enabled there, and check the flag on the network you target before offering any such flow.

The relayer model​

A relayer submits the transaction and pays the fees. The relayer's own hybrid (classical + ML-DSA-87) signature satisfies the ante handler on the envelope, so the canonical account's PQC signature is not needed on-chain. The authorization is instead the linked key's signature over a domain-separated, replay-bound sign-bytes digest.

Phantom / MetaMask key Relayer (pays fees) Chain
───────────────────── ─────────────────── ─────
sign(authSignBytes) ──────────▶ wrap in Msg, sign envelope ──▶ verify authenticator sig
check permission + rule
spend FROM canonical account

The relayer is a different account than the owner. The nonce the authenticator signs is the linked key's own sequence, kept by the chain (see Nonces), not the account's EVM nonce.

The three lanes​

LaneMessageSign-bytesSpends
EVMMsgExecuteEVMevmAuthSignBytesnative QOR / EVM call from the account's 0x address
NativeMsgExecuteCosmoscosmosAuthSignBytesnative QOR via x/bank from the account
Key rotationMsgRotatePQCKeyrotationSignBytes(rotates the account's PQC key)

The message type URLs are /qorechain.abstractaccount.v1.MsgExecuteEVM, /qorechain.abstractaccount.v1.MsgExecuteCosmos, and /qorechain.pqc.v1.MsgRotatePQCKey.

Register a Phantom authenticator​

Linking a key is owner-signed (a normal hybrid transaction by the canonical account): MsgRegisterAuthenticator names the key (scheme + raw pubkey bytes), the granted permissions, and an expiryUnix session deadline. Spending limits are attached with a SpendingRule via MsgUpdateSpendingRules:

import { msg } from "@qorechain/sdk";

// The Phantom wallet in the browser:
const phantomPubkey = window.solana.publicKey.toBytes(); // 32-byte ed25519

// 1) Link the key: least privilege ("send" only) + a session expiry.
const register = msg.abstractaccount.registerAuthenticator({
owner: canonicalAccount, // the PQC-required account ("qor1…")
accountAddress: canonicalAccount, // the account the key may act for
scheme: "ed25519", // Phantom keys are ed25519
pubkey: phantomPubkey,
permissions: ["send"], // e.g. "send", "evm", "svm" — never "all" for a hot key
expiryUnix: String(Math.floor(Date.now() / 1000) + 7 * 24 * 3600), // 7 days
label: "phantom",
});

// 2) Bound what it can move: per-tx and daily limits, uqor only.
const limits = msg.abstractaccount.updateSpendingRules({
owner: canonicalAccount,
accountAddress: canonicalAccount,
rules: [
{
id: "phantom-hot",
perTxLimit: "1000000", // ≤ 1 QOR per spend
dailyLimit: "10000000", // ≤ 10 QOR per day
allowedDenoms: ["uqor"],
enabled: true,
},
],
});

// Broadcast BOTH owner-signed (hybrid) — e.g. via the hybrid tx path:
// await signAndBroadcastHybrid({ ..., messages: [register, limits] });
A rule bounds a key only when one exists

The chain resolves the limit in this order: the authenticator's own rule if it is set and enabled; otherwise the first enabled rule on the account; otherwise none, and then there is no limit. A rule stored with enabled: false is no limit, not a zero limit. MsgRegisterAuthenticator carries no rule, so a key linked by that message alone is bounded only by an account-level rule. Set a rule deliberately with MsgUpdateSpendingRules, and register only the permissions the key needs. A limit bounds the damage a linked key can do; it does not replace revoking the key. Spending rules bind only authenticators and session keys, not the owner's own key (on the EVM lane the owner's key is limited by the EVM window).

To disable a key instantly, the owner broadcasts msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }).

From chain v3.2.8 (the testnet since 12 November 2026; mainnet has not applied it) the registration above is refused unless it carries a possession proof: the key being linked signs a plain-text message that names the chain, the account, the scheme and the key. A key with send, evm, deploy, svm or all also needs the account's first enabled spending rule to bound every denom. SDK 0.14.0 has helpers for both; linkAuthenticatorMsgs builds the spending rule and the link in the order to send them in one owner-signed transaction. This snippet follows the 0.14.0 source and has not been run:

import { linkAuthenticatorMsgs, signAuthenticatorLinkPhantom } from "@qorechain/sdk";

// The key being linked signs the link message (Phantom signMessage here).
const proof = await signAuthenticatorLinkPhantom({
chainId: "qorechain-diana",
account: canonicalAccount,
wallet: window.solana,
});

const msgs = linkAuthenticatorMsgs({
owner: canonicalAccount,
chainId: "qorechain-diana", // optional: checks the proof before anything is built
scheme: proof.scheme,
pubkey: proof.pubkey,
possessionProof: proof.possessionProof,
permissions: ["send"],
expiryUnix: Math.floor(Date.now() / 1000) + 7 * 24 * 3600,
label: "phantom",
// Replaces the account's rules wholesale: pass every rule to keep.
spendingRules: [{ id: "phantom-hot", enabled: true, perTxLimit: "1000000", allowedDenoms: ["uqor"] }],
});
// Sign msgs in one owner-signed hybrid transaction.

The same file has signAuthenticatorLinkEd25519, signAuthenticatorLinkSecp256k1, signAuthenticatorLinkEip191 and signAuthenticatorLinkMetaMask for the other key types, and the register composers refuse an empty proof. On a network below v3.2.8 the proof stays optional.

From v3.2.8 an authorised MsgExecuteEVM or MsgExecuteCosmos that fails returns success=false inside a transaction with code 0 and still consumes the nonce. After a relayer broadcast, call assertAuthenticatorExecutionsSucceeded(result, messages), or decodeAuthenticatorExecutions to read each outcome, so a failed execution is not taken for a success.

Spend from Phantom (Native lane, via a relayer)​

Once the key is linked, the browser builds a relayer-ready MsgExecuteCosmos: buildPhantomExecuteCosmos rebuilds the domain-separated digest, has Phantom sign it (signMessage), and returns the { typeUrl, value } message.

Browser (the Phantom user):

import { buildPhantomExecuteCosmos } from "@qorechain/sdk";

// window.solana is a Phantom-style wallet: { publicKey, signMessage }.
const msgExecute = await buildPhantomExecuteCosmos({
wallet: window.solana,
relayer: relayerAddress, // who will submit + pay fees
chainId: "qorechain-vladi",
account: canonicalAccount, // the PQC-required owner
to: recipient, // "qor1…"
amount: "100uqor", // single-coin amount string
nonce, // the per-authenticator sequence for (account, pubkey)
});

// Ship `msgExecute` to your relayer service (it is already signed by Phantom):
await fetch("/api/relay", {
method: "POST",
body: JSON.stringify({
typeUrl: msgExecute.typeUrl,
value: {
...msgExecute.value,
pubkey: Buffer.from(msgExecute.value.pubkey).toString("base64"),
signature: Buffer.from(msgExecute.value.signature).toString("base64"),
nonce: msgExecute.value.nonce.toString(),
},
}),
});

Server (the relayer): signs the envelope with its own account using the hybrid path (signAndBroadcastHybrid, passing rest) and pays the fees. The relayer's ML-DSA-87 key must be registered, like any account's. The authenticator's signature inside the message is the authorization to spend from the owner's account.

import { StargateClient } from "@cosmjs/stargate";
import {
deriveNativeAccount,
directSignerFromPrivateKey,
derivePqcCanonical,
signAndBroadcastHybrid,
qorechainRegistry,
} from "@qorechain/sdk";

const REST = "https://api.qore.host";
const RPC = "https://rpc.qore.host";

// The relayer's OWN account: a different account than the owner.
const mnemonic = process.env.RELAYER_MNEMONIC!;
const relayer = await deriveNativeAccount(mnemonic);
const signer = await directSignerFromPrivateKey(relayer.privateKey, "qor");
const pqcKeypair = derivePqcCanonical(relayer.address, mnemonic);

const transport = await StargateClient.connect(RPC);
const info = await transport.getSequence(relayer.address);

// `msgExecute` is the message decoded from the request. The relayer pays fees.
const result = await signAndBroadcastHybrid({
registry: qorechainRegistry(),
signer,
pqcKeypair,
messages: [msgExecute],
fee: { amount: [{ denom: "uqor", amount: "40000" }], gas: "400000" },
chainId: "qorechain-vladi",
accountNumber: info.accountNumber,
sequence: info.sequence,
rest: REST,
transport,
});
console.log(result.transactionHash);

A runnable end-to-end version (with a local ed25519 key standing in for Phantom) is the authenticator-spend example.

Spend from MetaMask (EVM lane)​

A MetaMask key is linked by its 20-byte ETH address (scheme secp256k1) with registerEthAuthenticatorMsg, and authorizes spends with a 65-byte EIP-191 personal_sign signature over the same kind of digest.

1) Owner links the MetaMask address (owner-signed, hybrid):

import { registerEthAuthenticatorMsg } from "@qorechain/sdk";

const [ethAddress] = await window.ethereum.request({
method: "eth_requestAccounts",
params: [],
});

const register = registerEthAuthenticatorMsg({
owner: canonicalAccount,
ethAddress, // 0x-hex 20-byte address = the authenticator pubkey
permissions: ["evm"], // EVM lane only
expiryUnix: Math.floor(Date.now() / 1000) + 24 * 3600, // 24 h session
label: "metamask",
});
// broadcast owner-signed (hybrid), like any other message

2) MetaMask authorizes an EVM transfer — buildMetaMaskExecuteEvm builds the digest, requests personal_sign (EIP-191) from the provider, and returns a relayer-ready MsgExecuteEVM:

import { buildMetaMaskExecuteEvm } from "@qorechain/sdk";

const msgExecute = await buildMetaMaskExecuteEvm({
provider: window.ethereum, // any EIP-1193 provider
address: ethAddress, // the linked 20-byte address (0x-hex)
relayer: relayerAddress,
chainId: "qorechain-vladi",
account: canonicalAccount, // the PQC-required owner
to: "0xRecipient…", // 0x-hex recipient
value: "1000000000000000000",// decimal wei string (EVM lane: 18 decimals)
gasLimit: 100000,
nonce: authSequence, // the linked key's authenticator sequence (see Nonces) — NOT the EVM nonce
digestVersion: "v2", // from chain v3.2.3 (see "Sign-bytes"); use resolveEvmAuthDigestVersion
});
// hand `msgExecute` to the relayer, exactly as in the Phantom flow

buildMetaMaskExecuteCosmos works the same way for the Native lane (to: "qor1…", amount: "100uqor", nonce = the per-authenticator sequence). There are matching low-level composers — executeEvmMsg, executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg, rotatePqcKeyMsg — if you manage keys and signatures yourself.

Sign-bytes (byte-exact)​

Two byte helpers: BE64(n) is an 8-byte big-endian integer; LP(bytes) is BE64(len) ‖ bytes (length-prefixed).

EVM lane — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce }) returns a 32-byte digest:

sha256( "qorechain-evm-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )

to is the 0x-hex recipient, value the decimal wei string, data the raw calldata.

EVM lane, v2 (chain v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) appends the call's gas limit, so a relayer cannot replay a valid signature with another limit. The chain verifies exactly one form per block: v1 below the v3.2.3 upgrade, v2 from it. resolveEvmAuthDigestVersion({ rest }) returns "v2" once the network has applied v3.2.3 and "v1" before, and buildPhantomExecuteEvm / buildMetaMaskExecuteEvm take digestVersion (default "v1", so pass "v2" on a network at v3.2.3 or later). gasLimit must be non-zero.

sha256( "qorechain-evm-auth-v2"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) ‖ BE64(gasLimit) )

Native lane — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce }) returns a 32-byte digest:

sha256( "qorechain-cosmos-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )

amount is the canonical single-coin string (e.g. 100uqor).

Rotation — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub) returns the string both keys sign (UTF-8 of it):

qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>

Nonces​

Both lanes use the per-authenticator sequence for (account, pubkey): a counter the chain keeps for each linked key, starting at 0 and incremented by each successful execution.

  • MsgExecuteEVM.nonce is this counter, not the account's EVM nonce (eth_getTransactionCount).
  • MsgExecuteCosmos.nonce is the same kind of counter.

Since chain v3.2.4 (both networks serve the route) and SDK 0.10.0 or later you can read the counter instead of tracking it: fetchAuthNonce({ rest, address, pubkey }) calls GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex} and returns { nonce, linked }. A key that never executed reads 0, and the counter is kept even for a key that is no longer linked (linked says which). Sending a value that is not the chain's current counter is a replay rejection (abstractaccount code 11, see below). With an older SDK or chain, track it per linked key: 0 for a newly linked key, +1 after each execution the chain accepts.

Reading the stored rules and linked keys​

From chain v3.2.5 (SDK 0.12.0), both networks can be asked what an account stored, instead of reconstructing it from transactions:

  • fetchSpendingRules({ rest, address }) reads the spending rules, account-wide and per linked key (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).
  • fetchAuthenticators({ rest, address }) reads the linked keys, revoked ones included (.../accounts/{address}/authenticators).
  • msg.abstractaccount.updateConfig is the governance message that sets the module's limits (the authority is the governance module account, so an ordinary account cannot send it). The SDK checks the values before signing.

Rules are checked as the chain checks them: an erc20/, erc721/ or erc1155/ denom must name a 0x contract address, and the module's codes 8 (invalid spending rule) and 9 (module disabled) are named. The module is still switched off on mainnet and enabled on the testnet.

The permission schema​

The chain publishes the canonical authenticator permission taxonomy so clients validate scopes without hardcoding strings, and detect drift via schema_version:

// REST (LCD):
const schema = await client.rest.getPermissionSchema();

schema.schema_version; // bumps on any taxonomy/mapping change
schema.permissions; // ["send", "evm", "svm", "all", ...]
schema.msg_permissions; // { "/qorechain.abstractaccount.v1.MsgExecuteEVM": "evm", ... }
schema.key_management_msgs; // typeURLs NEVER delegable to a linked key

The REST route is GET /qorechain/abstractaccount/v1/permission_schema; the typed gRPC query client exposes the same data as clients.abstractaccount.permissionSchema(). The module also serves /config, /accounts, and /accounts/{address}.

Error codes​

Failures decode through decodeTxError with a friendly kind:

CodespaceCodeKind
abstractaccount5spending_limit_exceeded
abstractaccount6session_key_expired
abstractaccount10permission_denied
abstractaccount11authenticator_replay
pqc21hybrid_verify_failed
import { decodeTxError } from "@qorechain/sdk";

const decoded = decodeTxError({
code: result.code,
codespace: result.codespace,
rawLog: result.rawLog,
});

switch (decoded.kind) {
case "spending_limit_exceeded": // over the per-tx or daily SpendingRule
break;
case "session_key_expired": // expiryUnix passed — re-register the key
break;
case "permission_denied": // scope missing — check the permission_schema
break;
case "authenticator_replay": // wrong nonce — refetch and re-sign
break;
case "hybrid_verify_failed": // ML-DSA sig did not verify (see note below)
break;
}

hybrid_verify_failed means the ML-DSA-87 signature did not verify. It is not caused by hedged signing (the chain accepts hedged and deterministic ML-DSA-87 signatures alike); see Troubleshooting code 21. It is also what you see if a pre-0.6.1 SDK JSON-encoded the hybrid extension (upgrade — see Accounts & PQC signing).

Key rotation​

Rotate an account's ML-DSA-87 key to a new key of the same algorithm — for example migrating a legacy chain-bridge-derived key (shake256(mnemonic)) to the canonical address-bound key (shake256("qorechain:pqc:v1|addr|mnemonic")):

import { rotatePqcKeyMsgFromMnemonic, derivePqcLegacy } from "@qorechain/sdk";

const { msg, oldKeypair, newKeypair } = rotatePqcKeyMsgFromMnemonic({
account,
mnemonic,
chainId: "qorechain-vladi",
// oldDerivation: "bridge" (legacy), newDerivation: "adapter" (canonical) by default
});
// broadcast `msg` BY the account, cosigned (hybrid) with the OLD key —
// both keys dual-sign the rotation bytes (old proves ownership, new proves control).

derivePqcLegacy(mnemonic) reproduces the legacy keypair on its own when you need it (e.g. to keep signing until the rotation lands).

Next​