Autentificatori și cheltuieli delegate
Benzile de autentificatori (SDK 0.7.0, chain v3.1.85) permit unei chei externe conectate — o cheie Phantom ed25519 sau o cheie MetaMask / EVM secp256k1 — să cheltuiască din contul canonic UNIC cu PQC obligatoriu, în condiții de privilegii minime, cu limite de cheltuieli și revocabile, fără ca cheia externă să producă vreodată o co-semnătură ML-DSA.
Aceasta este contrapartea din SDK a modulului de abstractizare a conturilor de pe chain.
Modulul x/abstractaccount este dezactivat pe qorechain-vladi (mainnet):
GET /qorechain/abstractaccount/v1/config returnează "enabled": false. Începând cu
chain v3.2.0, acest indicator este aplicat pe fiecare cale (crearea unui cont abstract,
conectarea unui autentificator și atât MsgExecuteEVM, cât și MsgExecuteCosmos), iar
chain-ul le refuză cu abstract account module is disabled (cod 9). Nicio tranzacție
nu îl poate activa. Pe testnet-ul qorechain-diana, aceeași rută a returnat
"enabled": true pe 27 octombrie 2026, deci fluxurile de mai jos pot fi încercate
acolo. Nu construiți un flux cu cheie conectată sau cu cheltuieli delegate pentru
mainnet până când modulul nu este activat acolo și verificați indicatorul pe rețeaua
țintă înainte de a oferi un astfel de flux.
Modelul cu relayer
Un relayer trimite tranzacția și plătește comisioanele. Semnătura hibridă proprie a relayer-ului (clasică + ML-DSA-87) satisface ante handler-ul pe anvelopă, astfel încât semnătura PQC a contului canonic nu este necesară on-chain. Autorizarea este, în schimb, semnătura cheii conectate peste un digest sign-bytes separat pe domenii și protejat împotriva reluării (replay-bound).
Phantom / MetaMask key Relayer (pays fees) Chain
───────────────────── ─────────────────── ─────
sign(authSignBytes) ──────────▶ wrap in Msg, sign envelope ──▶ verify authenticator sig
check permission + rule
spend FROM canonical account
Relayer-ul este un cont diferit de cel al proprietarului. Nonce-ul pe care îl semnează autentificatorul este propria secvență a cheii conectate, ținută de chain (vezi Nonces), nu nonce-ul EVM al contului.
Cele trei benzi
| Bandă | Mesaj | Sign-bytes | Cheltuiește |
|---|---|---|---|
| EVM | MsgExecuteEVM | evmAuthSignBytes | QOR nativ / apel EVM de la adresa 0x a contului |
| Nativă | MsgExecuteCosmos | cosmosAuthSignBytes | QOR nativ prin x/bank din cont |
| Rotația cheii | MsgRotatePQCKey | rotationSignBytes | (rotește cheia PQC a contului) |
URL-urile de tip ale mesajelor sunt /qorechain.abstractaccount.v1.MsgExecuteEVM,
/qorechain.abstractaccount.v1.MsgExecuteCosmos și
/qorechain.pqc.v1.MsgRotatePQCKey.
Înregistrarea unui autentificator Phantom
Conectarea unei chei este semnată de proprietar (o tranzacție hibridă
normală a contului canonic): MsgRegisterAuthenticator specifică cheia
(schemă + octeții bruți ai cheii publice), permisiunile acordate
(permissions) și un termen de sesiune expiryUnix. Limitele de cheltuieli
se atașează printr-un SpendingRule prin 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] });
Chain-ul rezolvă limita în această ordine: regula proprie a autentificatorului,
dacă este setată și enabled; altfel prima regulă enabled de pe cont; altfel
niciuna, iar atunci nu există nicio limită. O regulă stocată cu
enabled: false înseamnă lipsa limitei, nu o limită zero.
MsgRegisterAuthenticator nu poartă nicio regulă, deci o cheie conectată doar
prin acel mesaj este limitată numai de o regulă la nivel de cont. Setați o regulă
în mod deliberat prin MsgUpdateSpendingRules și înregistrați doar permisiunile
de care cheia are nevoie. O limită restrânge paguba pe care o poate face o cheie
conectată; nu înlocuiește revocarea cheii. Regulile de cheltuire leagă doar
autentificatorii și cheile de sesiune, nu cheia proprie a proprietarului (pe banda
EVM, cheia proprietarului este limitată de fereastra EVM).
Pentru a dezactiva instantaneu o cheie, proprietarul difuzează
msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }).
Legarea de la lanțul v3.2.8 (SDK 0.14.0)
De la lanțul v3.2.8 (testnet-ul din 12 noiembrie 2026; mainnet nu l-a aplicat)
înregistrarea de mai sus este refuzată dacă nu poartă o dovadă de posesie: cheia
care este legată semnează un mesaj în text simplu, care numește lanțul, contul, schema
și cheia. O cheie cu send, evm, deploy, svm sau all cere, de asemenea, ca
prima regulă de cheltuire activată a contului să limiteze fiecare denom. SDK 0.14.0 are
helpere pentru ambele; linkAuthenticatorMsgs construiește regula de cheltuire și
legarea în ordinea în care se trimit într-o singură tranzacție semnată de proprietar.
Fragmentul urmează sursa 0.14.0 și nu a fost rulat:
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.
Același fișier are signAuthenticatorLinkEd25519, signAuthenticatorLinkSecp256k1,
signAuthenticatorLinkEip191 și signAuthenticatorLinkMetaMask pentru celelalte
tipuri de chei, iar compozitoarele de înregistrare refuză o dovadă goală. Pe o rețea
sub v3.2.8, dovada rămâne opțională.
De la v3.2.8, un MsgExecuteEVM sau MsgExecuteCosmos autorizat care eșuează
returnează success=false în interiorul unei tranzacții cu cod 0 și consumă totuși
nonce-ul. După o difuzare prin relayer, apelați assertAuthenticatorExecutionsSucceeded(result, messages),
sau decodeAuthenticatorExecutions pentru a citi fiecare rezultat, ca o execuție
eșuată să nu fie luată drept reușită.
Cheltuieli din Phantom (banda Nativă, printr-un relayer)
Odată ce cheia este conectată, browserul construiește un MsgExecuteCosmos
gata pentru relayer: buildPhantomExecuteCosmos reconstruiește digestul
separat pe domenii, îl pune la semnat în Phantom (signMessage) și returnează
mesajul { typeUrl, value }.
Browser (utilizatorul 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 (relayer-ul): semnează anvelopa cu propriul său cont, folosind
calea hibridă (signAndBroadcastHybrid, transmițând rest), și plătește
comisioanele. Cheia ML-DSA-87 a relayer-ului trebuie să fie înregistrată, ca a
oricărui cont. Semnătura autentificatorului din interiorul mesajului este
autorizarea de a cheltui din contul proprietarului.
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);
O versiune completă, rulabilă cap-coadă (cu o cheie ed25519 locală în locul
Phantom), este exemplul
authenticator-spend.
Cheltuieli din MetaMask (banda EVM)
O cheie MetaMask se conectează prin adresa sa ETH de 20 de octeți (schema
secp256k1) cu registerEthAuthenticatorMsg și autorizează cheltuielile
printr-o semnătură personal_sign EIP-191 de 65 de octeți peste același tip
de digest.
1) Proprietarul conectează adresa MetaMask (semnat de proprietar, hibrid):
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 autorizează un transfer EVM — buildMetaMaskExecuteEvm
construiește digestul, solicită personal_sign (EIP-191) de la provider și
returnează un MsgExecuteEVM gata pentru 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 funcționează la fel pentru banda Nativă
(to: "qor1…", amount: "100uqor", nonce = secvența per-autentificator).
Există și compozitori de nivel jos corespunzători — executeEvmMsg,
executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg,
rotatePqcKeyMsg — dacă vă gestionați singuri cheile și semnăturile.
Sign-bytes (exact la nivel de octet)
Doi ajutători pentru octeți: BE64(n) este un întreg big-endian pe 8 octeți;
LP(bytes) este BE64(len) ‖ bytes (cu prefix de lungime).
Banda EVM — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce })
returnează un digest de 32 de octeți:
sha256( "qorechain-evm-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )
to este destinatarul în format hex 0x, value este șirul zecimal în wei,
data este calldata brută.
Banda EVM, v2 (chain v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) adaugă
limita de gaz a apelului, astfel încât un relayer să nu poată relua o semnătură
validă cu o altă limită. Chain-ul verifică exact o singură formă pe bloc: v1 sub
upgrade-ul v3.2.3, v2 de la acesta încolo. resolveEvmAuthDigestVersion({ rest })
returnează "v2" după ce rețeaua a aplicat v3.2.3 și "v1" înainte, iar
buildPhantomExecuteEvm / buildMetaMaskExecuteEvm primesc digestVersion
(implicit "v1", deci transmiteți "v2" pe o rețea cu v3.2.3 sau mai nou).
gasLimit trebuie să fie nenul.
sha256( "qorechain-evm-auth-v2"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) ‖ BE64(gasLimit) )
Banda Nativă — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce })
returnează un digest de 32 de octeți:
sha256( "qorechain-cosmos-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )
amount este șirul canonic cu o singură monedă (de ex. 100uqor).
Rotație — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub)
returnează șirul pe care îl semnează ambele chei (UTF-8 al acestuia):
qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>
Nonces
Ambele benzi folosesc secvența per-autentificator pentru (account, pubkey):
un contor pe care chain-ul îl ține pentru fiecare cheie conectată, începând de
la 0 și incrementat la fiecare execuție reușită.
MsgExecuteEVM.nonceeste acest contor, nu nonce-ul EVM al contului (eth_getTransactionCount).MsgExecuteCosmos.nonceeste același tip de contor.
Începând cu chain v3.2.4 (ambele rețele servesc ruta) și SDK 0.10.0 sau mai nou puteți citi
contorul în loc să îl urmăriți: fetchAuthNonce({ rest, address, pubkey }) apelează
GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex} și returnează
{ nonce, linked }. O cheie care nu a executat niciodată nimic citește 0, iar
contorul este păstrat chiar și pentru o cheie care nu mai este conectată (linked
spune care este cazul). Trimiterea unei valori care nu este contorul curent al
chain-ului este o respingere pentru reluare (replay) (abstractaccount cod 11, vezi
mai jos). Cu un SDK sau un chain mai vechi, urmăriți-l pentru fiecare cheie
conectată: 0 pentru o cheie nou conectată, +1 după fiecare execuție acceptată de
chain.
Citirea regulilor stocate și a cheilor conectate
Începând cu chain v3.2.5 (SDK 0.12.0), ambele rețele pot fi întrebate ce a stocat un cont, în loc să reconstruiți informația din tranzacții:
fetchSpendingRules({ rest, address })citește regulile de cheltuire, la nivel de cont și pentru fiecare cheie conectată (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).fetchAuthenticators({ rest, address })citește cheile conectate, inclusiv pe cele revocate (.../accounts/{address}/authenticators).msg.abstractaccount.updateConfigeste mesajul de guvernanță care stabilește limitele modulului (autoritatea este contul de modul de guvernanță, deci un cont obișnuit nu îl poate trimite). SDK-ul verifică valorile înainte de semnare.
Regulile sunt verificate așa cum le verifică chain-ul: un denom erc20/, erc721/ sau erc1155/
trebuie să indice o adresă de contract 0x, iar codurile modulului 8 (regulă de cheltuire
invalidă) și 9 (modul dezactivat) sunt denumite. Modulul este în continuare dezactivat pe mainnet
și activat pe testnet.
Schema de permisiuni
Chain-ul publică taxonomia canonică a permisiunilor de autentificator, astfel
încât clienții să valideze scope-urile fără a codifica șiruri în mod fix și să
detecteze derapajele prin 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
Ruta REST este GET /qorechain/abstractaccount/v1/permission_schema; clientul
tipizat de interogare gRPC expune aceleași date ca
clients.abstractaccount.permissionSchema(). Modulul mai servește și
/config, /accounts și /accounts/{address}.
Coduri de eroare
Eșecurile se decodează prin decodeTxError, cu un kind prietenos:
| Codespace | Cod | 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 înseamnă că semnătura ML-DSA-87 nu s-a verificat. Semnarea
hedged nu este cauza (chain-ul acceptă la fel semnăturile ML-DSA-87 hedged și
deterministe); vezi
Depanarea codului 21. Este, de
asemenea, ceea ce vedeți dacă un SDK anterior versiunii 0.6.1 a codificat în JSON
extensia hibridă (faceți upgrade - vezi
Conturi și semnare PQC).
Rotația cheii
Rotiți cheia ML-DSA-87 a unui cont către o cheie nouă a aceluiași
algoritm — de exemplu, migrarea unei chei legacy derivate prin chain-bridge
(shake256(mnemonic)) către cheia canonică legată de adresă
(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) reproduce de una singură perechea de chei legacy
atunci când aveți nevoie de ea (de ex. pentru a continua semnarea până când
rotația este confirmată on-chain).
Pașii următori
- Conturi și semnare PQC — conturi unificate și semnare hibridă.
- Abstractizarea conturilor — modulul de pe partea de chain.
- Exemplu rulabil:
authenticator-spend.