Authenticator e spesa delegata
Le corsie authenticator (SDK 0.7.0, chain v3.1.85) permettono a una chiave esterna collegata — una chiave ed25519 di Phantom, oppure una chiave secp256k1 MetaMask / EVM — di spendere dall'UNICO account canonico con PQC obbligatoria in termini di privilegio minimo, con limiti di spesa e revocabili, senza che la chiave esterna produca mai una co-firma ML-DSA.
Questa è la controparte lato SDK del modulo di account abstraction della chain.
Il modulo x/abstractaccount è disabilitato su qorechain-vladi (mainnet):
GET /qorechain/abstractaccount/v1/config restituisce "enabled": false. Dalla chain
v3.2.0 quel flag viene applicato su ogni percorso (creazione di un abstract account,
collegamento di un authenticator, e sia MsgExecuteEVM sia MsgExecuteCosmos), e la
chain li rifiuta con abstract account module is disabled (codice 9). Nessuna
transazione può attivarlo. Sulla testnet qorechain-diana la stessa route restituiva
"enabled": true il 27 ottobre 2026, quindi i flussi qui sotto possono essere provati
lì. Non costruire un flusso di chiave collegata o di spesa delegata per la mainnet
finché il modulo non è abilitato lì, e controlla il flag sulla rete di destinazione
prima di offrire un flusso di questo tipo.
Il modello relayer
Un relayer invia la transazione e paga le commissioni. La firma ibrida (classica + ML-DSA-87) del relayer stesso soddisfa l'ante handler sull'envelope, quindi la firma PQC dell'account canonico non è necessaria on-chain. L'autorizzazione è invece la firma della chiave collegata su un digest di sign-bytes con separazione di dominio e protezione anti-replay.
Phantom / MetaMask key Relayer (pays fees) Chain
───────────────────── ─────────────────── ─────
sign(authSignBytes) ──────────▶ wrap in Msg, sign envelope ──▶ verify authenticator sig
check permission + rule
spend FROM canonical account
Il relayer è un account diverso da quello del proprietario. Il nonce che l'authenticator firma è la sequenza propria della chiave collegata, tenuta dalla chain (vedi Nonces), non il nonce EVM dell'account.
Le tre corsie
| Corsia | Messaggio | Sign-bytes | Spende |
|---|---|---|---|
| EVM | MsgExecuteEVM | evmAuthSignBytes | QOR nativo / chiamata EVM dall'indirizzo 0x dell'account |
| Nativa | MsgExecuteCosmos | cosmosAuthSignBytes | QOR nativo via x/bank dall'account |
| Rotazione chiave | MsgRotatePQCKey | rotationSignBytes | (ruota la chiave PQC dell'account) |
Gli URL di tipo dei messaggi sono /qorechain.abstractaccount.v1.MsgExecuteEVM,
/qorechain.abstractaccount.v1.MsgExecuteCosmos e
/qorechain.pqc.v1.MsgRotatePQCKey.
Registrare un authenticator Phantom
Il collegamento di una chiave è firmato dal proprietario (una normale
transazione ibrida dell'account canonico): MsgRegisterAuthenticator indica la
chiave (schema + byte grezzi della pubkey), le permissions concesse e una
scadenza di sessione expiryUnix. I limiti di spesa si applicano con una
SpendingRule tramite 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] });
La chain risolve il limite in quest'ordine: la regola propria dell'authenticator
se è impostata ed enabled; altrimenti la prima regola enabled dell'account;
altrimenti nessuna, e allora non c'è alcun limite. Una regola memorizzata con
enabled: false non è un limite pari a zero: è assenza di limite.
MsgRegisterAuthenticator non contiene alcuna regola, quindi una chiave
collegata solo con quel messaggio è limitata unicamente da una regola a livello di
account. Imposta una regola in modo deliberato con MsgUpdateSpendingRules e
registra soltanto i permessi di cui la chiave ha bisogno. Un limite circoscrive il
danno che una chiave collegata può fare; non sostituisce la revoca della chiave. Le regole di spesa vincolano solo gli authenticator e le session key, non la chiave del proprietario (sulla corsia EVM la chiave del proprietario è limitata dalla finestra EVM).
Per disattivare una chiave all'istante, il proprietario trasmette
msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }).
Collegamento dalla chain v3.2.8 (SDK 0.14.0)
Dalla chain v3.2.8 (la testnet dal 12 novembre 2026; la mainnet non l'ha applicata)
la registrazione qui sopra viene rifiutata se non porta una prova di possesso: la chiave
che viene collegata firma un messaggio in chiaro che nomina la chain, l'account, lo schema
e la chiave. Una chiave con send, evm, deploy, svm o all richiede inoltre che la
prima regola di spesa abilitata dell'account limiti ogni denom. L'SDK 0.14.0 ha helper
per entrambe; linkAuthenticatorMsgs costruisce la regola di spesa e il collegamento nell'ordine
in cui inviarli in un'unica transazione firmata dal proprietario. Questo snippet segue il sorgente della 0.14.0
e non è stato eseguito:
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.
Lo stesso file ha signAuthenticatorLinkEd25519, signAuthenticatorLinkSecp256k1,
signAuthenticatorLinkEip191 e signAuthenticatorLinkMetaMask per gli altri tipi di
chiave, e i composer di registrazione rifiutano una prova vuota. Su una rete precedente alla v3.2.8 la
prova resta facoltativa.
Dalla v3.2.8 un MsgExecuteEVM o MsgExecuteCosmos autorizzato che fallisce restituisce
success=false dentro una transazione con codice 0 e consuma comunque il nonce. Dopo un
broadcast tramite relayer, chiama assertAuthenticatorExecutionsSucceeded(result, messages), oppure
decodeAuthenticatorExecutions per leggere ogni esito, così che un'esecuzione fallita non venga
scambiata per un successo.
Spendere da Phantom (corsia Nativa, tramite un relayer)
Una volta collegata la chiave, il browser costruisce un MsgExecuteCosmos
pronto per il relayer: buildPhantomExecuteCosmos ricostruisce il digest con
separazione di dominio, lo fa firmare da Phantom (signMessage) e restituisce
il messaggio { typeUrl, value }.
Browser (l'utente 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(),
},
}),
});
Server (il relayer): firma l'envelope con il proprio account tramite il
percorso ibrido (signAndBroadcastHybrid, passando rest) e paga le
commissioni. La chiave ML-DSA-87 del relayer deve essere registrata, come quella
di qualsiasi account. La firma dell'authenticator all'interno del messaggio è
l'autorizzazione a spendere dall'account del proprietario.
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);
Una versione end-to-end eseguibile (con una chiave ed25519 locale al posto di
Phantom) è l'esempio
authenticator-spend.
Spendere da MetaMask (corsia EVM)
Una chiave MetaMask viene collegata tramite il suo indirizzo ETH da 20 byte
(schema secp256k1) con registerEthAuthenticatorMsg e autorizza le spese con
una firma personal_sign EIP-191 da 65 byte sullo stesso tipo di digest.
1) Il proprietario collega l'indirizzo MetaMask (firmato dal proprietario, ibrido):
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 autorizza un trasferimento EVM — buildMetaMaskExecuteEvm
costruisce il digest, richiede personal_sign (EIP-191) al provider e
restituisce un MsgExecuteEVM pronto per il relayer:
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 funziona allo stesso modo per la corsia Nativa
(to: "qor1…", amount: "100uqor", nonce = la sequenza per-authenticator).
Esistono compositori di basso livello corrispondenti — executeEvmMsg,
executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg,
rotatePqcKeyMsg — se gestisci chiavi e firme in autonomia.
Sign-bytes (byte per byte)
Due helper sui byte: BE64(n) è un intero big-endian da 8 byte; LP(bytes) è
BE64(len) ‖ bytes (con prefisso di lunghezza).
Corsia EVM — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce })
restituisce un digest da 32 byte:
sha256( "qorechain-evm-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )
to è il destinatario in 0x-hex, value la stringa decimale in wei, data
la calldata grezza.
Corsia EVM, v2 (chain v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) aggiunge
il gas limit della chiamata, così un relayer non può riproporre una firma valida
con un limite diverso. La chain verifica esattamente una forma per blocco: v1
prima dell'upgrade v3.2.3, v2 da esso in poi. resolveEvmAuthDigestVersion({ rest })
restituisce "v2" una volta che la rete ha applicato la v3.2.3 e "v1" prima, e
buildPhantomExecuteEvm / buildMetaMaskExecuteEvm accettano digestVersion
(predefinito "v1", quindi passa "v2" su una rete alla v3.2.3 o successiva).
gasLimit deve essere diverso da zero.
sha256( "qorechain-evm-auth-v2"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) ‖ BE64(gasLimit) )
Corsia Nativa — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce })
restituisce un digest da 32 byte:
sha256( "qorechain-cosmos-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )
amount è la stringa canonica a moneta singola (es. 100uqor).
Rotazione — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub)
restituisce la stringa che entrambe le chiavi firmano (in UTF-8):
qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>
Nonces
Entrambe le corsie usano la sequenza per-authenticator per (account, pubkey):
un contatore che la chain tiene per ogni chiave collegata, parte da 0 e viene
incrementato a ogni esecuzione riuscita.
MsgExecuteEVM.nonceè questo contatore, non il nonce EVM dell'account (eth_getTransactionCount).MsgExecuteCosmos.nonceè lo stesso tipo di contatore.
Dalla chain v3.2.4 (entrambe le reti servono la route) e dall'SDK 0.10.0 o successivo puoi leggere
il contatore invece di tenerne traccia: fetchAuthNonce({ rest, address, pubkey }) chiama
GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex} e restituisce
{ nonce, linked }. Una chiave che non ha mai eseguito legge 0, e il contatore viene
conservato anche per una chiave non più collegata (linked indica quale caso). Inviare un valore diverso dal contatore corrente della chain
produce un rifiuto per replay (codice 11 di abstractaccount, vedi sotto). Con un SDK o una chain più vecchi, tienine traccia per ogni chiave collegata: 0 per una chiave appena collegata,
+1 dopo ogni esecuzione che la chain accetta.
Leggere le regole memorizzate e le chiavi collegate
Dalla chain v3.2.5 (SDK 0.12.0), su entrambe le reti si può chiedere che cosa ha memorizzato un account, invece di ricostruirlo dalle transazioni:
fetchSpendingRules({ rest, address })legge le regole di spesa, valide per l'intero account e per ogni chiave collegata (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).fetchAuthenticators({ rest, address })legge le chiavi collegate, comprese quelle revocate (.../accounts/{address}/authenticators).msg.abstractaccount.updateConfigè il messaggio di governance che imposta i limiti del modulo (l'autorità è l'account del modulo di governance, quindi un account ordinario non può inviarlo). L'SDK controlla i valori prima di firmare.
Le regole vengono controllate come le controlla la chain: un denom erc20/, erc721/ o erc1155/
deve indicare un indirizzo di contratto 0x, e i codici 8 (regola di spesa non valida)
e 9 (modulo disabilitato) del modulo sono nominati. Il modulo è ancora disattivato sulla mainnet
e attivo sulla testnet.
Lo schema dei permessi
La chain pubblica la tassonomia canonica dei permessi degli authenticator, così
i client convalidano gli scope senza stringhe hardcoded e rilevano le
divergenze tramite 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 è GET /qorechain/abstractaccount/v1/permission_schema; il
client di query gRPC tipizzato espone gli stessi dati come
clients.abstractaccount.permissionSchema(). Il modulo serve anche
/config, /accounts e /accounts/{address}.
Codici di errore
I fallimenti si decodificano con decodeTxError, che fornisce un kind
leggibile:
| Codespace | Codice | Kind |
|---|---|---|
abstractaccount | 5 | spending_limit_exceeded |
abstractaccount | 6 | session_key_expired |
abstractaccount | 10 | permission_denied |
abstractaccount | 11 | authenticator_replay |
pqc | 21 | hybrid_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 indica che la firma ML-DSA-87 non è stata verificata. La
firma hedged non ne è la causa (la chain accetta allo stesso modo firme ML-DSA-87
hedged e deterministiche); vedi
Risoluzione del codice 21. È anche
l'errore che compare se un SDK precedente alla 0.6.1 ha codificato in JSON
l'estensione ibrida (aggiorna - vedi
Account e firma PQC).
Rotazione delle chiavi
Ruota la chiave ML-DSA-87 di un account verso una nuova chiave dello stesso
algoritmo — ad esempio per migrare una chiave legacy derivata dal chain-bridge
(shake256(mnemonic)) alla chiave canonica legata all'indirizzo
(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) riproduce da sola la coppia di chiavi legacy quando
serve (ad esempio per continuare a firmare finché la rotazione non viene
registrata on-chain).
Prossimi passi
- Account e firma PQC — account unificati e firma ibrida.
- Account abstraction — il modulo lato chain.
- Esempio eseguibile:
authenticator-spend.