Sari la conținutul principal

Semnare hibridă în mod implicit

QoreChain tratează criptografia post-cuantică drept o schemă de semnătură de prim rang. Un cont înregistrează pe lanț o cheie ML-DSA-87 (Dilithium-5, NIST FIPS 204), după care tranzacțiile sale pot purta o semnătură hibridă — obișnuita semnătură clasică secp256k1 plus o semnătură ML-DSA-87. Ante handler-ul lanțului verifică ambele, astfel încât un cont cu o cheie înregistrată rămâne pe deplin compatibil cu verificarea clasică, iar tranzacțiile sale poartă în plus o semnătură post-cuantică.

SDK-ul împachetează acest lucru într-o suprafață minusculă, idempotentă, astfel încât o dApp semnează hibrid în mod implicit: un singur apel înregistrează cheia. Pe rețelele live, acest lucru nu este opțional pentru tranzacțiile pe calea Native: cheia trebuie înregistrată explicit (nu există înregistrare automată la prima tranzacție), iar fiecare tranzacție pe calea Native trebuie apoi să poarte semnătura hibridă.

Verificarea stării​

isPqcRegistered / getPqcStatus citesc dacă o adresă are o cheie PQC înregistrată. Dacă primesc clientul compus din createClient, citesc prin REST (GET /qorechain/pqc/v1/account/{address}, servit de fiecare endpoint public); dacă primesc un QorClient simplu, folosesc metoda JSON-RPC qor_getPQCKeyStatus, pe care endpoint-urile publice nu o servesc (vezi spațiul de nume qor_), așa că față de *.qore.host transmite clientul compus. Versiunile anterioare lui 0.9.0 foloseau întotdeauna metoda qor_ și eșuau cu eroarea JSON-RPC -32601; citește direct ruta REST acolo.

import { createClient, isPqcRegistered, getPqcStatus } from "@qorechain/sdk";

const client = createClient({
network: "mainnet",
endpoints: {
rest: "https://api.qore.host",
rpc: "https://rpc.qore.host",
evmRpc: "https://evm.qore.host",
},
});

const registered = await isPqcRegistered(client, address); // boolean
const status = await getPqcStatus(client, address);
// { registered: boolean; algorithmId?: number; pubkey?: string | Uint8Array }

Ruta este GET /qorechain/pqc/v1/account/{address} (account la singular). Răspunde cu {"found": true, "account": {…}} pentru o adresă înregistrată și cu {"found": false, "account": null} în caz contrar; client.rest.getPqcAccount(address) returnează acel corp, iar fetchPqcStatus({ rest, address }) îl transformă în starea de mai sus. Un răspuns care nu poate fi citit (o eroare HTTP, un eșec de transport) este aruncat ca eroare după o singură reîncercare: nu este niciodată citit ca „neînregistrat". În 0.8.x, getPqcAccount apela o cale la plural /accounts/ pe care lanțul nu o servește.

Aceeași stare este citibilă și pe partea EVM prin precompila pqcKeyStatus(address) returns (bool registered, uint8 algorithmId, bytes pubkey) de la 0x0000000000000000000000000000000000000a02 (expusă ca pqcKeyStatus în @qorechain/evm) odată ce acea precompilă este activă; nu este activă pe mainnet și este listată ca activă pe testnet (verificat la 27 octombrie 2026; vezi Starea rețelei).

Înregistrare într-un singur apel​

ensurePqcRegistered înregistrează cheia ML-DSA-87 a contului. Construiește și difuzează MsgRegisterPQCKeyV2 cu cheia publică ML-DSA-87 a semnatarului. Este idempotent: citește mai întâi starea contului (prin REST când transmiți rest), sare peste înregistrare atunci când contul deține deja cheia acestei perechi de chei și poate fi, prin urmare, apelat în siguranță la fiecare pornire a aplicației. Când contul deține o cheie diferită, aruncă PqcKeyMismatchError și nu trimite nimic, deoarece fiecare tranzacție hibridă semnată cu perechea ta de chei ar fi refuzată. Nu înregistrează niciodată orbește: dacă starea nu poate fi citită, aruncă o eroare (transmite force: true doar pentru un cont despre care știi că nu are nicio cheie).

Înregistrarea este semnată clasic și scutită de cerința hibridă, astfel încât un cont nou își poate iniția prima cheie; începând cu v3.2.3, această scutire acoperă doar un cont fără cheie (un cont care deține deja una trebuie să semneze hibrid un register sau un migrate, iar lanțul refuză cheile slabe, degenerate sau refolosite). Odată ce rețeaua a aplicat v3.2.3, helperul semnează dovada de posesie opțională cu noua cheie și o atașează (citește chain id-ul din chainId sau de la nod și omite câmpul pe o rețea care nu a aplicat v3.2.3, deoarece un nod mai vechi îl refuză). Semnează printr-un semnatar CosmJS, adică un cont coin-type-118 (deriveNativeAccount); pentru un cont eth-native unificat, semnează înregistrarea cu EthNativeSigner și signMode: "classical" (vezi Conturi și semnare PQC). Cheia de 2.592 de octeți necesită o limită de gaz de aproximativ 600.000; prețul minim al gazului în rețea este de 0,1 uqor per unitate de gaz.

import {
createClient,
deriveNativeAccount,
directSignerFromPrivateKey,
derivePqcCanonical,
ensurePqcRegistered,
} from "@qorechain/sdk";

const account = await deriveNativeAccount(mnemonic);
const signer = await directSignerFromPrivateKey(account.privateKey, "qor");

// The address-bound key, recoverable from { address, mnemonic } (0.8.3+; see below).
// Never register a throwaway key from generatePqcKeypair() unless you store it.
const pqcKeypair = derivePqcCanonical(account.address, mnemonic);

// With the keypair the client signs every transaction hybrid; the registration
// itself stays classical (the chain's bootstrap path).
const tx = await client.connectTx(signer, { pqcKeypair });

const res = await ensurePqcRegistered(tx, {
pqcKeypair,
rest: client.network.endpoints.rest,
fee: { amount: [{ denom: "uqor", amount: "60000" }], gas: "600000" },
});
// res: { alreadyRegistered: boolean; txHash?: string }

await tx.bankSend("qor1…", [{ denom: "uqor", amount: "1000000" }]); // hybrid-signed

O cheie pe care o poți recupera​

derivePqcCanonical(address, mnemonic) derivă cheia ML-DSA-87 a contului din adresa și mnemonicul său, astfel încât un dispozitiv pierdut este recuperabil, iar fiecare limbaj și portofel derivă aceeași cheie (un mnemonic, o cheie per cont). Rezolvă mai întâi adresa la forma sa qor1… cu litere mici, deci forma 0x a unui cont unificat dă aceeași cheie. Echivalentele:

LimbajFuncțiePublicat
TypeScriptderivePqcCanonical(address, mnemonic) (@qorechain/sdk)0.9.0
Pythonderive_pqc_canonical(address, mnemonic) (qorsdk)0.9.0
Goauthenticator.DerivePQCCanonical(address, mnemonic)v0.9.0
Rustauthenticator::try_derive_pqc_canonical(address, mnemonic) (returnează un Result)0.9.0
JavaAuthenticator.derivePqcCanonical(address, mnemonic)0.9.0

Derivarea veche (derivePqcLegacy, "bridge") nu este legată de cont și este depreciată pentru chei noi; helperele de rotire o refuză ca cheie nouă (vezi Rotirea unei chei).

Înregistrarea în Python (0.9.0; citirea stării se face prin REST, iar apelul aruncă PqcKeyMismatchError pentru o altă cheie înregistrată, în loc să plătească pentru o a doua înregistrare):

import httpx
from qorsdk import derive_native_account, derive_pqc_canonical, ensure_pqc_registered, fetch_pqc_status

REST = "https://api.qore.host"
native = derive_native_account(mnemonic, 0)
pqc_keypair = derive_pqc_canonical(native.address, mnemonic)

print(fetch_pqc_status(REST, native.address)) # {'registered': False} for a new account

acct = httpx.get(f"{REST}/cosmos/auth/v1beta1/accounts/{native.address}").json()["account"]
result = ensure_pqc_registered(
account=native,
pqc_keypair=pqc_keypair,
chain_id="qorechain-vladi",
account_number=int(acct["account_number"]),
sequence=int(acct.get("sequence", 0)),
rest_url=REST,
fee={"amount": [{"denom": "uqor", "amount": "60000"}], "gas": "600000"},
)

Helperele Go (pqcdx.Signer.RestURL), Rust (pqc_dx rest_url) și Java (signer.restUrl) citesc starea din aceeași rută REST și atașează dovada de posesie în același mod.

Celelalte SDK-uri semnează hibrid prin constructorii lor de tranzacții hibride (build_hybrid_tx în Python și Rust, tx.BuildHybridMessages în Go, PqcDx.HybridSendPath în Java); doar TxClient-ul TypeScript semnează hibrid pentru tine.

Lasă-l întotdeauna să verifice mai întâi

Lanțul refuză o a doua înregistrare a aceleiași chei după ce a încasat taxa. ensurePqcRegistered citește, prin urmare, mai întâi starea, prin REST (/qorechain/pqc/v1/account/{address}), și refuză să înregistreze când nu poate stabili. Transmite rest (sau statusSource pentru un nod care expune qor_*, ori un status citit în prealabil); force: true omite verificarea. În 0.8.x, helperul nu avea nicio alternativă REST și difuza înregistrarea fără verificare, cu excepția cazului în care transmiteai tu status.

Semnare hibridă​

Cu un pqcKeypair pe client, tx.bankSend(...) și tx.signAndBroadcast([messages], "auto") semnează hibrid (calea fee: "auto" simulează tranzacția hibridă; începând cu SDK 0.12.0, pe o rețea v3.2.5 limita este regula exactă ceil(simulated x 1.02) + 2000, iar înainte clientul adaugă singur gazul verificării post-cuantice). Semnătura hibridă este calculată peste forma de sign-bytes pe care o verifică rețeaua (vezi Ce formă de sign-bytes?); clientul întreabă rețeaua prin endpoint-ul său REST.

migrateToHybrid asigură înregistrarea și returnează o cale de trimitere hibridă cu perechea de chei pre-legată la constructorii de nivel inferior buildHybridTx / signAndBroadcastHybrid, pentru cazul în care gestionezi singur taxa, numărul contului și sequence. Transmite rest pentru ca SDK-ul să poată determina forma de sign-bytes:

import { StargateClient } from "@cosmjs/stargate";
import { migrateToHybrid, qorechainRegistry } from "@qorechain/sdk";

const hybrid = await migrateToHybrid(tx, {
pqcKeypair,
rest: "https://api.qore.host",
fee: { amount: [{ denom: "uqor", amount: "60000" }], gas: "600000" },
});

const transport = await StargateClient.connect("https://rpc.qore.host");
const info = await transport.getSequence(account.address);

await hybrid.signAndBroadcastHybrid({
registry: qorechainRegistry(),
signer, // classical secp256k1 direct signer
messages,
fee: { amount: [{ denom: "uqor", amount: "40000" }], gas: "400000" },
chainId: "qorechain-vladi",
accountNumber: info.accountNumber,
sequence: info.sequence,
rest: "https://api.qore.host",
transport, // a connected broadcast transport (e.g. StargateClient)
});

Lanțul acceptă orice semnătură ML-DSA-87 FIPS-204 validă, hedged sau deterministă. SDK-ul semnează implicit determinist (începând cu 0.5.1), astfel încât o tranzacție are întotdeauna aceeași semnătură și același hash de tx. Dacă o tx hibridă eșuează cu codul pqc 21 (hybrid_verify_failed), cauza este versiunea sign-bytes, chain-id-ul, o bibliotecă PQC depășită sau o cheie neînregistrată ori diferită, niciodată semnarea hedged: vezi Depanare cod 21.

Rotirea unei chei​

Pentru a înlocui cheia ML-DSA-87 a unui cont cu o altă cheie a aceluiași algoritm (de exemplu, mutarea unei chei vechi shake256(mnemonic) la cheia canonică legată de adresă sau retragerea unei chei compromise), construiește un MsgRotatePQCKey cu rotatePqcKeyMsgFromMnemonic; ambele chei îl semnează dual. Vezi Rotirea cheilor pentru exemplul complet.

migratePqcKeyHybrid difuzează mai vechiul MsgMigratePQCKey, care mută un cont între algoritmi, cu semnătura hibridă pe care lanțul o cere, începând cu v3.2.3, de la un cont care are o cheie. pqcKeypair este cheia care este în prezent înregistrată (cea care este scoasă din uz), iar apelantul furnizează cele două semnături de proprietate (oldSignature de cheia veche, newSignature de cheia nouă). migratePqcKey clasic este depreciat: un nod v3.2.3 refuză o migrare clasică de la un cont care are o cheie.

import { StargateClient } from "@cosmjs/stargate";
import { migratePqcKeyHybrid, qorechainRegistry } from "@qorechain/sdk";

const transport = await StargateClient.connect("https://rpc.qore.host");
const info = await transport.getSequence(account.address);

await migratePqcKeyHybrid({
sender: account.address,
registry: qorechainRegistry(),
signer,
pqcKeypair, // the currently registered key
oldPublicKey,
newPublicKey,
oldSignature, // by the old key
newSignature, // by the new key
fee: { amount: [{ denom: "uqor", amount: "60000" }], gas: "600000" },
chainId: "qorechain-vladi",
accountNumber: info.accountNumber,
sequence: info.sequence,
rest: "https://api.qore.host",
transport,
});

Publicarea unei chei ML-KEM-1024​

Semnarea dovedește cine a trimis o tranzacție; criptarea are nevoie de o cheie diferită. Începând cu chain v3.2.5, un cont poate publica o cheie de încapsulare ML-KEM-1024 (id de algoritm 2, 1.568 octeți) în registrul KEM on-chain, astfel încât oricine să poată cripta un payload către ea. SDK 0.12.0 compune cele două mesaje și citește registrul înapoi; nu criptează și nu decriptează (pentru payload-uri sigilate vedeți QoreSeal). Ruta și mesajele sunt servite pe mainnet și pe testnet.

  • msg.pqc.registerKemKey({ sender, publicKey }) publică cheia (un al doilea apel o înlocuiește). Compozitorul verifică mai întâi cheia, așa cum o face chain-ul: dimensiune exactă, fiecare coeficient sub 3329, nu toți zero (validateKemPublicKey rulează aceeași verificare de sine stătător).
  • msg.pqc.removeKemKey({ sender }) o retrage.
  • fetchKemKey({ rest, address }) citește /qorechain/pqc/v1/kem/{address} (o adresă bech32 sau 0x) și returnează { found, key? }, cu algoritmul, octeții cheii și înălțimea înregistrării.

Ambele mesaje au nevoie de semnătura hibridă a contului, așa că trimiteți-le prin TxClient hibrid (client.connectTx(signer, { pqcKeypair })) ca orice altă tranzacție nativă și înregistrați mai întâi cheia ML-DSA-87 a contului. Refuzurile chain-ului pqc 250 la 254 sunt denumite de decodeTxError. Celelalte patru limbaje poartă aceleași mesaje și aceeași citire.

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

// `kemPublicKey` is a 1,568-byte ML-KEM-1024 public key you generated (for example with
// `@qorechain/pqc`); `tx` is a hybrid TxClient.
await tx.signAndBroadcast(
[msg.pqc.registerKemKey({ sender: account.address, publicKey: kemPublicKey })],
"auto",
);

const { found, key } = await fetchKemKey({ rest: "https://api.qore.host", address: account.address });

În interfața utilizator​

Kit-ul @qorechain/react expune toate acestea în React: hook-ul usePqcStatus și componenta <PqcStatusBadge/> (<QuantumSafeBadge/> este un alias depreciat) afișează un indicator de stare ori de câte ori contul conectat are o cheie PQC înregistrată. Ambele citesc starea prin getPqcStatus cu clientul compus, deci începând cu @qorechain/react 0.9.0 o citesc prin REST și funcționează față de endpoint-urile publice; 0.8.x nu putea confirma acolo o cheie.