Zum Hauptinhalt springen

Standardmäßig hybrides Signieren

QoreChain behandelt Post-Quanten-Kryptografie als erstklassiges Signaturverfahren. Ein Konto registriert einen ML-DSA-87-Schlüssel (Dilithium-5, NIST FIPS 204) on-chain, woraufhin seine Transaktionen eine hybride Signatur tragen können — die übliche klassische secp256k1-Signatur plus eine ML-DSA-87-Signatur. Der Ante-Handler der Chain verifiziert beide, sodass ein Konto mit registriertem Schlüssel vollständig mit der klassischen Verifikation kompatibel bleibt, während seine Transaktionen zusätzlich eine Post-Quanten-Signatur tragen.

Das SDK fasst dies in eine winzige, idempotente Oberfläche zusammen, sodass eine dApp standardmäßig hybrid signiert: ein Aufruf registriert den Schlüssel. Auf den Live-Netzwerken ist dies für Transaktionen auf dem Native-Pfad nicht optional: Der Schlüssel muss explizit registriert werden (es gibt keine automatische Registrierung bei der ersten Transaktion), und jede Transaktion auf dem Native-Pfad muss danach die hybride Signatur tragen.

Status prüfen​

isPqcRegistered / getPqcStatus lesen, ob eine Adresse einen registrierten PQC-Schlüssel besitzt. Mit dem zusammengesetzten Client aus createClient lesen sie über REST (GET /qorechain/pqc/v1/account/{address}, von jedem öffentlichen Endpunkt bereitgestellt); mit einem reinen QorClient verwenden sie die JSON-RPC-Methode qor_getPQCKeyStatus, die die öffentlichen Endpunkte nicht bereitstellen (siehe den Namensraum qor_); übergeben Sie daher gegen *.qore.host den zusammengesetzten Client. Releases vor 0.9.0 verwendeten immer die Methode qor_ und scheiterten mit dem JSON-RPC-Fehler -32601; lesen Sie dort die REST-Route direkt.

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 }

Die Route lautet GET /qorechain/pqc/v1/account/{address} (Singular account). Sie antwortet mit {"found": true, "account": {…}} für eine registrierte Adresse und andernfalls mit {"found": false, "account": null}; client.rest.getPqcAccount(address) liefert diesen Body, und fetchPqcStatus({ rest, address }) macht daraus den oben gezeigten Status. Eine nicht lesbare Antwort (ein HTTP-Fehler, ein Transportfehler) wird nach einem Wiederholungsversuch als Fehler geworfen: Sie wird nie als „nicht registriert“ gelesen. In 0.8.x rief getPqcAccount einen Pfad im Plural /accounts/ auf, den die Chain nicht bereitstellt.

Derselbe Status ist auf der EVM-Seite ebenfalls über das Precompile pqcKeyStatus(address) returns (bool registered, uint8 algorithmId, bytes pubkey) an 0x0000000000000000000000000000000000000a02 lesbar (in @qorechain/evm als pqcKeyStatus bereitgestellt), sobald dieses Precompile aktiv ist; im Mainnet ist es nicht aktiv, und im Testnet wird es als aktiv geführt (geprüft am 27. Oktober 2026; siehe Netzwerkstatus).

Registrierung in einem Aufruf​

ensurePqcRegistered registriert den ML-DSA-87-Schlüssel des Kontos. Es erstellt und sendet MsgRegisterPQCKeyV2 mit dem ML-DSA-87-Public-Key des Signierers. Es ist idempotent: Es liest zuerst den Status des Kontos (über REST, wenn Sie rest übergeben), überspringt die Registrierung, wenn das Konto bereits den Schlüssel dieses Schlüsselpaars hält, und kann daher bei jedem App-Start sicher aufgerufen werden. Hält das Konto einen anderen Schlüssel, wirft es PqcKeyMismatchError und sendet nichts, weil jede mit Ihrem Schlüsselpaar signierte hybride Transaktion abgelehnt würde. Es registriert nie blind: Wenn der Status nicht gelesen werden kann, wirft es einen Fehler (übergeben Sie force: true nur für ein Konto, von dem Sie wissen, dass es keinen Schlüssel hat).

Die Registrierung wird klassisch signiert und ist von der Hybrid-Pflicht ausgenommen, sodass ein neues Konto seinen ersten Schlüssel bootstrappen kann; seit v3.2.3 gilt diese Ausnahme nur noch für ein Konto ohne Schlüssel (ein Konto, das bereits einen besitzt, muss eine Registrierung oder Migration hybrid signieren, und die Chain lehnt schwache, degenerierte oder wiederverwendete Schlüssel ab). Sobald das Netzwerk v3.2.3 angewendet hat, signiert der Helfer den optionalen Besitznachweis (Proof of Possession) mit dem neuen Schlüssel und hängt ihn an (er liest die Chain-ID aus chainId oder vom Node und lässt das Feld in einem Netzwerk weg, das v3.2.3 nicht angewendet hat, weil ein älterer Node es ablehnt). Er signiert über einen CosmJS-Signer, das heißt über ein Konto mit Coin-Type 118 (deriveNativeAccount); signieren Sie die Registrierung eines vereinheitlichten eth-nativen Kontos mit EthNativeSigner und signMode: "classical" (siehe Konten & PQC-Signierung). Der 2.592 Byte große Schlüssel benötigt ein Gaslimit von etwa 600.000; der Mindest-Gaspreis des Netzwerks beträgt 0,1 uqor pro Gaseinheit.

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

Ein Schlüssel, den Sie wiederherstellen können​

derivePqcCanonical(address, mnemonic) leitet den ML-DSA-87-Schlüssel des Kontos aus seiner Adresse und Mnemonic ab, sodass ein verlorenes Gerät wiederherstellbar ist und jede Sprache und jede Wallet denselben Schlüssel ableitet (eine Mnemonic, ein Schlüssel pro Konto). Es löst die Adresse zuerst in ihre kleingeschriebene Form qor1… auf, sodass die 0x-Form eines vereinheitlichten Kontos denselben Schlüssel ergibt. Die Entsprechungen:

SpracheFunktionVeröffentlicht
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) (liefert ein Result)0.9.0
JavaAuthenticator.derivePqcCanonical(address, mnemonic)0.9.0

Die ältere Ableitung (derivePqcLegacy, "bridge") ist nicht an das Konto gebunden und für neue Schlüssel veraltet; die Rotations-Helfer lehnen sie als neuen Schlüssel ab (siehe Einen Schlüssel rotieren).

Registrierung in Python (0.9.0; das Lesen des Status läuft über REST, und der Aufruf wirft PqcKeyMismatchError bei einem anderen registrierten Schlüssel, statt für eine zweite Registrierung zu bezahlen):

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"},
)

Die Helfer für Go (pqcdx.Signer.RestURL), Rust (pqc_dx rest_url) und Java (signer.restUrl) lesen den Status von derselben REST-Route und hängen den Besitznachweis auf dieselbe Weise an.

Die anderen SDKs signieren hybrid über ihre Builder für hybride Transaktionen (build_hybrid_tx in Python und Rust, tx.BuildHybridMessages in Go, PqcDx.HybridSendPath in Java); nur der TypeScript-TxClient signiert für Sie hybrid.

Immer zuerst prüfen lassen

Die Chain lehnt eine zweite Registrierung desselben Schlüssels ab, nachdem sie die Gebühr abgezogen hat. ensurePqcRegistered liest daher zuerst den Status, über REST (/qorechain/pqc/v1/account/{address}), und weigert sich zu registrieren, wenn es ihn nicht feststellen kann. Übergeben Sie rest (oder statusSource für einen Node, der qor_* bereitstellt, oder einen vorab gelesenen status); force: true überspringt die Prüfung. In 0.8.x hatte der Helfer keinen REST-Fallback und sendete die Registrierung ungeprüft, sofern Sie nicht selbst status übergaben.

Hybrid signieren​

Mit einem pqcKeypair am Client signieren tx.bankSend(...) und tx.signAndBroadcast([messages], "auto") hybrid (der Pfad fee: "auto" simuliert die hybride Transaktion; ab SDK 0.12.0 ist das Limit auf einem v3.2.5-Netzwerk die exakte Regel ceil(simulated x 1.02) + 2000, davor addiert der Client das Gas der Post-Quanten-Verifikation selbst). Die hybride Signatur wird über die Sign-Bytes-Form berechnet, die das Netzwerk verifiziert (siehe Welche Sign-Bytes-Form?); der Client fragt das Netzwerk über seinen REST-Endpunkt ab.

migrateToHybrid stellt die Registrierung sicher und liefert einen hybriden Sendepfad zurück, bei dem das Schlüsselpaar bereits an die Builder auf niedrigerer Ebene buildHybridTx / signAndBroadcastHybrid gebunden ist, für den Fall, dass Sie Gebühr, Kontonummer und Sequence selbst verwalten. Übergeben Sie rest, damit das SDK die Sign-Bytes-Form ermitteln kann:

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

Die Chain akzeptiert jede gültige FIPS-204-ML-DSA-87-Signatur, ob hedged oder deterministisch. Das SDK signiert standardmäßig deterministisch (seit 0.5.1), sodass eine Transaktion immer dieselbe Signatur und denselben Tx-Hash hat. Schlägt eine Hybrid-Tx mit pqc-Code 21 (hybrid_verify_failed) fehl, liegt die Ursache an der Sign-Bytes-Version, der Chain-ID, einer veralteten PQC-Bibliothek oder einem nicht registrierten oder anderen Schlüssel, niemals am Hedged-Signieren: siehe Fehlerbehebung Code 21.

Einen Schlüssel rotieren​

Um den ML-DSA-87-Schlüssel eines Kontos durch einen anderen Schlüssel desselben Algorithmus zu ersetzen (zum Beispiel um einen älteren shake256(mnemonic)-Schlüssel auf den kanonischen, adressgebundenen Schlüssel umzustellen oder um einen kompromittierten Schlüssel stillzulegen), erstellen Sie mit rotatePqcKeyMsgFromMnemonic eine MsgRotatePQCKey; beide Schlüssel signieren sie gemeinsam. Das vollständige Beispiel finden Sie unter Schlüsselrotation.

migratePqcKeyHybrid sendet die ältere MsgMigratePQCKey, die ein Konto zwischen Algorithmen verschiebt, mit der hybriden Signatur, die die Chain ab v3.2.3 von einem Konto verlangt, das einen Schlüssel hat. pqcKeypair ist der Schlüssel, der aktuell registriert ist (der, der ausgetauscht wird), und der Aufrufer liefert die beiden Eigentumssignaturen (oldSignature vom alten Schlüssel, newSignature vom neuen Schlüssel). Das klassische migratePqcKey ist veraltet: Ein v3.2.3-Node lehnt eine klassische Migration von einem Konto mit Schlüssel ab.

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

Einen ML-KEM-1024-Schlüssel veröffentlichen​

Signieren beweist, wer eine Transaktion gesendet hat; Verschlüsselung braucht einen anderen Schlüssel. Ab Chain v3.2.5 kann ein Konto einen ML-KEM-1024-Encapsulation-Schlüssel (Algorithmus-ID 2, 1.568 Bytes) im KEM-Register der Chain veröffentlichen, sodass jeder eine Nutzlast an ihn verschlüsseln kann. SDK 0.12.0 setzt die beiden Nachrichten zusammen und liest das Register zurück; es verschlüsselt oder entschlüsselt nicht (für versiegelte Nutzlasten siehe QoreSeal). Die Route und die Nachrichten werden auf dem Mainnet und dem Testnet bereitgestellt.

  • msg.pqc.registerKemKey({ sender, publicKey }) veröffentlicht den Schlüssel (ein zweiter Aufruf ersetzt ihn). Der Composer prüft den Schlüssel zuerst, wie es die Chain tut: exakte Größe, jeder Koeffizient unter 3329, nicht komplett null (validateKemPublicKey führt dieselbe Prüfung für sich allein aus).
  • msg.pqc.removeKemKey({ sender }) zieht ihn zurück.
  • fetchKemKey({ rest, address }) liest /qorechain/pqc/v1/kem/{address} (eine bech32- oder 0x-Adresse) und liefert { found, key? }, mit dem Algorithmus, den Schlüssel-Bytes und der Registrierungshöhe.

Beide Nachrichten brauchen die hybride Signatur des Kontos, senden Sie sie also über den hybriden TxClient (client.connectTx(signer, { pqcKeypair })) wie jede andere native Transaktion, und registrieren Sie zuerst den ML-DSA-87-Schlüssel des Kontos. Die Chain-Ablehnungen pqc 250 bis 254 werden von decodeTxError benannt. Die anderen vier Sprachen enthalten dieselben Nachrichten und denselben Lesezugriff.

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

In der UI​

Das @qorechain/react-Kit stellt all dies in React bereit: der usePqcStatus-Hook und die <PqcStatusBadge/>-Komponente (<QuantumSafeBadge/> ist ein veralteter Alias) zeigen einen Status- Indikator an, sobald das verbundene Konto einen registrierten PQC-Schlüssel besitzt. Beide lesen den Status über getPqcStatus mit dem zusammengesetzten Client, sodass sie ihn ab @qorechain/react 0.9.0 über REST lesen und gegen die öffentlichen Endpunkte funktionieren; 0.8.x konnte dort einen Schlüssel nicht bestätigen.