Aller au contenu principal

Authentificateurs et dépenses déléguées

Les voies d'authentificateur (SDK 0.7.0, chaîne v3.1.85) permettent à une clé externe liée — une clé ed25519 Phantom, ou une clé secp256k1 MetaMask / EVM — de dépenser depuis LE compte canonique unique à PQC obligatoire, selon des conditions de moindre privilège, plafonnées en dépenses et révocables, sans que la clé externe ne produise jamais de co-signature ML-DSA.

C'est le pendant côté SDK du module d'abstraction de compte de la chaîne.

Non disponible sur le mainnet

Le module x/abstractaccount est désactivé sur qorechain-vladi (mainnet) : GET /qorechain/abstractaccount/v1/config renvoie "enabled": false. À partir de la chaîne v3.2.0, cet indicateur est appliqué sur tous les chemins (création d'un compte abstrait, liaison d'un authentificateur, et MsgExecuteEVM / MsgExecuteCosmos), et la chaîne les refuse avec abstract account module is disabled (code 9). Aucune transaction ne peut l'activer. Sur le testnet qorechain-diana, la même route a renvoyé "enabled": true le 27 octobre 2026 ; les flux ci-dessous peuvent donc y être essayés. Ne construisez pas de flux de clé liée ou de dépense déléguée pour le mainnet tant que le module n'y est pas activé, et vérifiez l'indicateur sur le réseau que vous ciblez avant de proposer un tel flux.

Le modèle du relayeur​

Un relayeur soumet la transaction et paie les frais. La signature hybride (classique + ML-DSA-87) propre au relayeur satisfait le ante handler sur l'enveloppe, si bien que la signature PQC du compte canonique n'est pas requise on-chain. L'autorisation est à la place la signature de la clé liée sur un condensat de sign-bytes à séparation de domaine et protégé contre le rejeu.

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

Le relayeur est un compte différent de celui du propriétaire. Le nonce que signe l'authentificateur est la séquence propre à la clé liée, tenue par la chaîne (voir Nonces), et non le nonce EVM du compte.

Les trois voies​

VoieMessageSign-bytesDépense
EVMMsgExecuteEVMevmAuthSignBytesQOR natif / appel EVM depuis l'adresse 0x du compte
NativeMsgExecuteCosmoscosmosAuthSignBytesQOR natif via x/bank depuis le compte
Rotation de cléMsgRotatePQCKeyrotationSignBytes(fait tourner la clé PQC du compte)

Les URL de type des messages sont /qorechain.abstractaccount.v1.MsgExecuteEVM, /qorechain.abstractaccount.v1.MsgExecuteCosmos et /qorechain.pqc.v1.MsgRotatePQCKey.

Enregistrer un authentificateur Phantom​

La liaison d'une clé est signée par le propriétaire (une transaction hybride normale du compte canonique) : MsgRegisterAuthenticator désigne la clé (schéma + octets bruts de la clé publique), les permissions accordées et une échéance de session expiryUnix. Les plafonds de dépense sont attachés avec une 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] });
Une règle ne borne une clé que si elle existe

La chaîne résout le plafond dans cet ordre : la règle propre à l'authentificateur si elle est définie et enabled ; sinon la première règle enabled du compte ; sinon aucune, et alors il n'y a aucun plafond. Une règle stockée avec enabled: false n'est pas un plafond nul : c'est l'absence de plafond. MsgRegisterAuthenticator ne porte aucune règle, donc une clé liée par ce seul message n'est bornée que par une règle au niveau du compte. Définissez une règle délibérément avec MsgUpdateSpendingRules, et n'enregistrez que les permissions dont la clé a besoin. Un plafond limite les dégâts qu'une clé liée peut causer ; il ne remplace pas la révocation de la clé. Les règles de dépenses ne lient que les authentificateurs et les clés de session, pas la clé propre du propriétaire (sur la voie EVM, la clé du propriétaire est limitée par la fenêtre EVM).

Pour désactiver instantanément une clé, le propriétaire diffuse msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }).

À partir de la chaîne v3.2.8 (le testnet depuis le 12 novembre 2026 ; le mainnet ne l'a pas appliquée), l'enregistrement ci-dessus est refusé s'il ne porte pas une preuve de possession : la clé liée signe un message en texte brut qui nomme la chaîne, le compte, le schéma et la clé. Une clé avec send, evm, deploy, svm ou all exige aussi que la première règle de dépense activée du compte borne chaque dénomination. Le SDK 0.14.0 fournit des assistants pour les deux ; linkAuthenticatorMsgs construit la règle de dépense et le lien dans l'ordre où les envoyer, dans une seule transaction signée par le propriétaire. Cet extrait suit le code source de la 0.14.0 et n'a pas été exécuté :

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.

Le même fichier contient signAuthenticatorLinkEd25519, signAuthenticatorLinkSecp256k1, signAuthenticatorLinkEip191 et signAuthenticatorLinkMetaMask pour les autres types de clés, et les composeurs d'enregistrement refusent une preuve vide. Sur un réseau antérieur à la v3.2.8, la preuve reste facultative.

À partir de la v3.2.8, un MsgExecuteEVM ou MsgExecuteCosmos autorisé qui échoue renvoie success=false dans une transaction de code 0 et consomme quand même le nonce. Après une diffusion par relayeur, appelez assertAuthenticatorExecutionsSucceeded(result, messages), ou decodeAuthenticatorExecutions pour lire chaque résultat, afin qu'une exécution échouée ne soit pas prise pour un succès.

Dépenser depuis Phantom (voie Native, via un relayeur)​

Une fois la clé liée, le navigateur construit un MsgExecuteCosmos prêt pour le relayeur : buildPhantomExecuteCosmos reconstruit le condensat à séparation de domaine, le fait signer par Phantom (signMessage) et renvoie le message { typeUrl, value }.

Navigateur (l'utilisateur Phantom) :

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(),
},
}),
});

Serveur (le relayeur) : signe l'enveloppe avec son propre compte via le chemin hybride (signAndBroadcastHybrid, en passant rest) et paie les frais. La clé ML-DSA-87 du relayeur doit être enregistrée, comme celle de tout compte. La signature de l'authentificateur contenue dans le message constitue l'autorisation de dépenser depuis le compte du propriétaire.

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);

Une version exécutable de bout en bout (avec une clé ed25519 locale tenant le rôle de Phantom) est l'exemple authenticator-spend.

Dépenser depuis MetaMask (voie EVM)​

Une clé MetaMask est liée par son adresse ETH de 20 octets (schéma secp256k1) avec registerEthAuthenticatorMsg, et autorise les dépenses avec une signature personal_sign EIP-191 de 65 octets sur le même type de condensat.

1) Le propriétaire lie l'adresse MetaMask (signé par le propriétaire, hybride) :

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 autorise un transfert EVM — buildMetaMaskExecuteEvm construit le condensat, demande personal_sign (EIP-191) au fournisseur et renvoie un MsgExecuteEVM prêt pour le relayeur :

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 fonctionne de la même manière pour la voie Native (to: "qor1…", amount: "100uqor", nonce = la séquence par authentificateur). Il existe des composeurs bas niveau correspondants — executeEvmMsg, executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg, rotatePqcKeyMsg — si vous gérez vous-même les clés et les signatures.

Sign-bytes (à l'octet près)​

Deux fonctions utilitaires d'octets : BE64(n) est un entier big-endian de 8 octets ; LP(bytes) est BE64(len) ‖ bytes (préfixé par la longueur).

Voie EVM — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce }) renvoie un condensat de 32 octets :

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

to est le destinataire en hexadécimal 0x, value la chaîne décimale en wei, data le calldata brut.

Voie EVM, v2 (chaîne v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) ajoute la limite de gas de l'appel, afin qu'un relayeur ne puisse pas rejouer une signature valide avec une autre limite. La chaîne vérifie exactement une forme par bloc : v1 avant la mise à niveau v3.2.3, v2 à partir de celle-ci. resolveEvmAuthDigestVersion({ rest }) renvoie "v2" une fois que le réseau a appliqué v3.2.3 et "v1" avant, et buildPhantomExecuteEvm / buildMetaMaskExecuteEvm acceptent digestVersion (par défaut "v1" : passez donc "v2" sur un réseau en v3.2.3 ou ultérieure). gasLimit doit être non nul.

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

Voie Native — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce }) renvoie un condensat de 32 octets :

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

amount est la chaîne canonique à une seule pièce (par ex. 100uqor).

Rotation — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub) renvoie la chaîne que les deux clés signent (son encodage UTF-8) :

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

Nonces​

Les deux voies utilisent la séquence par authentificateur pour (account, pubkey) : un compteur que la chaîne tient pour chaque clé liée, qui démarre à 0 et est incrémenté à chaque exécution réussie.

  • MsgExecuteEVM.nonce est ce compteur, et non le nonce EVM du compte (eth_getTransactionCount).
  • MsgExecuteCosmos.nonce est un compteur du même type.

Depuis la chaîne v3.2.4 (les deux réseaux servent la route) et le SDK 0.10.0 ou ultérieur, vous pouvez lire le compteur au lieu de le suivre : fetchAuthNonce({ rest, address, pubkey }) appelle GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex} et renvoie { nonce, linked }. Une clé qui n'a jamais exécuté renvoie 0, et le compteur est conservé même pour une clé qui n'est plus liée (linked indique laquelle). Envoyer une valeur qui n'est pas le compteur actuel de la chaîne provoque un rejet pour rejeu (code 11 de abstractaccount, voir ci-dessous). Avec un SDK ou une chaîne plus ancien, suivez-le pour chaque clé liée : 0 pour une clé nouvellement liée, +1 après chaque exécution acceptée par la chaîne.

Lire les règles stockées et les clés liées​

Depuis la chaîne v3.2.5 (SDK 0.12.0), les deux réseaux peuvent être interrogés sur ce qu'un compte a stocké, au lieu de le reconstituer à partir des transactions :

  • fetchSpendingRules({ rest, address }) lit les règles de dépense, à l'échelle du compte et par clé liée (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).
  • fetchAuthenticators({ rest, address }) lit les clés liées, y compris les clés révoquées (.../accounts/{address}/authenticators).
  • msg.abstractaccount.updateConfig est le message de gouvernance qui fixe les limites du module (l'autorité est le compte de module de gouvernance, un compte ordinaire ne peut donc pas l'envoyer). Le SDK vérifie les valeurs avant de signer.

Les règles sont vérifiées comme la chaîne les vérifie : un denom erc20/, erc721/ ou erc1155/ doit désigner une adresse de contrat 0x, et les codes 8 (règle de dépense invalide) et 9 (module désactivé) du module sont nommés. Le module est toujours désactivé sur le mainnet et activé sur le testnet.

Le schéma de permissions​

La chaîne publie la taxonomie canonique des permissions d'authentificateur afin que les clients valident les portées sans coder les chaînes en dur, et détectent toute dérive 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

La route REST est GET /qorechain/abstractaccount/v1/permission_schema ; le client de requêtes gRPC typé expose les mêmes données via clients.abstractaccount.permissionSchema(). Le module sert également /config, /accounts et /accounts/{address}.

Codes d'erreur​

Les échecs se décodent via decodeTxError avec un kind lisible :

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 signifie que la signature ML-DSA-87 n'a pas été vérifiée. La signature hedged n'en est pas la cause (la chaîne accepte aussi bien les signatures ML-DSA-87 hedged que déterministes) ; voir Dépannage du code 21. C'est aussi ce que vous voyez si un SDK antérieur à 0.6.1 a encodé l'extension hybride en JSON (mettez à niveau - voir Comptes et signature PQC).

Rotation de clé​

Faites tourner la clé ML-DSA-87 d'un compte vers une nouvelle clé du même algorithme — par exemple pour migrer une clé héritée dérivée du chain-bridge (shake256(mnemonic)) vers la clé canonique liée à l'adresse (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) reproduit à elle seule la paire de clés héritée quand vous en avez besoin (par ex. pour continuer à signer jusqu'à ce que la rotation soit effective).

Et ensuite​