Ana içeriğe geç

Varsayılan olarak hibrit imzalama

QoreChain, post-kuantum kriptografiyi birinci sınıf bir imza şeması olarak ele alır. Bir hesap, zincir üzerinde bir ML-DSA-87 (Dilithium-5, NIST FIPS 204) anahtarı kaydeder, ardından işlemleri bir hibrit imza taşıyabilir — olağan klasik secp256k1 imzası artı bir ML-DSA-87 imzası. Zincirin ante işleyicisi her ikisini de doğrular; böylece kayıtlı anahtara sahip bir hesap klasik doğrulamayla tam uyumlu kalır ve işlemleri ayrıca post-kuantum bir imza da taşır.

SDK bunu küçük, bağımsız uygulanabilir bir yüzeye paketler; böylece bir dApp varsayılan olarak hibrit imzalar: anahtarı kaydetmek için tek bir çağrı yeterlidir. Canlı ağlarda bu, Native yol işlemleri için isteğe bağlı değildir: anahtar açıkça kaydedilmelidir (ilk işlemde otomatik kayıt yoktur) ve ardından her Native yol işlemi hibrit imzayı taşımalıdır.

Durumu kontrol edin​

isPqcRegistered / getPqcStatus, bir adresin kayıtlı bir PQC anahtarına sahip olup olmadığını okur. createClient'tan oluşturulan istemci verildiğinde REST üzerinden okurlar (GET /qorechain/pqc/v1/account/{address}, her genel uç nokta tarafından sunulur); çıplak bir QorClient verildiğinde ise genel uç noktaların sunmadığı qor_getPQCKeyStatus JSON-RPC yöntemini kullanırlar (bkz. qor_ ad alanı); bu nedenle *.qore.host karşısında oluşturulmuş istemciyi geçin. 0.9.0 öncesi sürümler her zaman qor_ yöntemini kullanıyordu ve -32601 JSON-RPC hatasıyla başarısız oluyordu; orada REST rotasını doğrudan okuyun.

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 }

Rota GET /qorechain/pqc/v1/account/{address} şeklindedir (tekil account). Kayıtlı bir adres için {"found": true, "account": {…}}, aksi halde {"found": false, "account": null} yanıtını verir; client.rest.getPqcAccount(address) bu gövdeyi döndürür ve fetchPqcStatus({ rest, address }) onu yukarıdaki duruma dönüştürür. Okunamayan bir yanıt (bir HTTP hatası, bir aktarım hatası) bir yeniden denemeden sonra hata olarak fırlatılır: asla "kayıtlı değil" olarak okunmaz. 0.8.x'te getPqcAccount, zincirin sunmadığı çoğul bir /accounts/ yolunu çağırıyordu.

Aynı durum EVM tarafında da 0x0000000000000000000000000000000000000a02 adresindeki pqcKeyStatus(address) returns (bool registered, uint8 algorithmId, bytes pubkey) ön derlemesi (@qorechain/evm içinde pqcKeyStatus olarak sunulur) etkinleştiğinde okunabilir; bu ön derleme mainnet üzerinde etkin değildir ve testnet üzerinde etkin olarak listelenir (27 Ekim 2026'da kontrol edildi; bkz. Ağ durumu).

Tek çağrıda kaydedin​

ensurePqcRegistered, hesabın ML-DSA-87 anahtarını kaydeder. İmzalayanın ML-DSA-87 genel anahtarıyla MsgRegisterPQCKeyV2 oluşturur ve yayınlar. Bağımsız uygulanabilirdir: önce hesabın durumunu okur (rest geçtiğinizde REST üzerinden), hesap zaten bu anahtar çiftinin anahtarını taşıyorsa kaydı atlar ve bu nedenle her uygulama başlangıcında çağrılması güvenlidir. Hesap farklı bir anahtar taşıyorsa PqcKeyMismatchError fırlatır ve hiçbir şey göndermez, çünkü anahtar çiftinizle imzalanan her hibrit işlem reddedilirdi. Asla körü körüne kaydetmez: durum okunamazsa hata fırlatır (force: true değerini yalnızca anahtarı olmadığını bildiğiniz bir hesap için geçin).

Kayıt klasik olarak imzalanır ve hibrit gereksiniminden muaftır; böylece yeni bir hesap ilk anahtarını önyükleyebilir; v3.2.3'ten beri bu muafiyet yalnızca anahtarı olmayan bir hesabı kapsar (zaten bir anahtarı olan bir hesap, bir kayıt veya geçişi hibrit imzalamalıdır ve zincir zayıf, dejenere veya yeniden kullanılmış anahtarları reddeder). Ağ v3.2.3'ü uyguladıktan sonra yardımcı, isteğe bağlı sahiplik kanıtını (proof of possession) yeni anahtarla imzalar ve ekler (zincir kimliğini chainId'den veya düğümden okur ve v3.2.3'ü uygulamamış bir ağda alanı boş bırakır, çünkü eski bir düğüm onu reddeder). Bir CosmJS imzalayıcısı, yani coin-type-118 hesabı (deriveNativeAccount) üzerinden imzalar; birleşik eth-native hesap için kaydı EthNativeSigner ve signMode: "classical" ile imzalayın (bkz. Hesaplar ve PQC imzalama). 2.592 baytlık anahtar yaklaşık 600.000 gas limiti gerektirir; ağın asgari gas fiyatı gas birimi başına 0,1 uqor'dur.

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

Kurtarabileceğiniz bir anahtar​

derivePqcCanonical(address, mnemonic), hesabın ML-DSA-87 anahtarını adresinden ve mnemonic'inden türetir; böylece kaybedilen bir cihaz kurtarılabilir ve her dil ve cüzdan aynı anahtarı türetir (bir mnemonic, hesap başına bir anahtar). Önce adresi küçük harfli qor1… biçimine çözümler; dolayısıyla birleşik bir hesabın 0x biçimi aynı anahtarı verir. Eşdeğerleri:

DilİşlevYayımlandı
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) (bir Result döndürür)0.9.0
JavaAuthenticator.derivePqcCanonical(address, mnemonic)0.9.0

Eski türetme (derivePqcLegacy, "bridge") hesaba bağlı değildir ve yeni anahtarlar için kullanımdan kaldırılmıştır; döndürme yardımcıları onu yeni anahtar olarak reddeder (bkz. Bir anahtarı döndürün).

Python'da kayıt (0.9.0; durum okuması REST üzerinden yapılır ve çağrı, ikinci bir kayıt için ödeme yapmak yerine farklı bir kayıtlı anahtar için PqcKeyMismatchError fırlatır):

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

Go (pqcdx.Signer.RestURL), Rust (pqc_dx rest_url) ve Java (signer.restUrl) yardımcıları durumu aynı REST rotasından okur ve sahiplik kanıtını aynı şekilde ekler.

Diğer SDK'lar hibrit imzayı kendi hibrit işlem oluşturucuları üzerinden atar (Python ve Rust'ta build_hybrid_tx, Go'da tx.BuildHybridMessages, Java'da PqcDx.HybridSendPath); yalnızca TypeScript TxClient sizin için hibrit imzalar.

Her zaman önce kontrol etmesine izin verin

Zincir, aynı anahtarın ikinci kaydını ücreti aldıktan sonra reddeder. Bu nedenle ensurePqcRegistered durumu önce REST üzerinden okur (/qorechain/pqc/v1/account/{address}) ve karar veremediğinde kaydetmeyi reddeder. rest geçin (veya qor_* sunan bir düğüm için statusSource, ya da önceden okunmuş bir status); force: true kontrolü atlar. 0.8.x'te yardımcının REST yedeği yoktu ve siz kendiniz status geçmedikçe kaydı kontrol etmeden yayınlıyordu.

Hibrit imzalayın​

İstemcide bir pqcKeypair varken tx.bankSend(...) ve tx.signAndBroadcast([messages], "auto") hibrit imzalar (fee: "auto" yolu hibrit işlemi simüle eder; SDK 0.12.0'dan itibaren bir v3.2.5 ağında sınır ceil(simulated x 1.02) + 2000 kesin kuralıdır, öncesinde istemci post-kuantum doğrulamasının gas'ını kendisi ekler). Hibrit imza, ağın doğruladığı sign-bytes biçimi üzerinden hesaplanır (bkz. Hangi sign-bytes biçimi?); istemci ağa kendi REST uç noktası üzerinden sorar.

migrateToHybrid kaydı sağlar ve anahtar çiftini daha alt düzey buildHybridTx / signAndBroadcastHybrid oluşturucularına önceden bağlı olarak bir hibrit gönderme yolu geri verir; bu, ücreti, hesap numarasını ve sıra numarasını kendiniz yönettiğinizde işe yarar. SDK'nın sign-bytes biçimini çözebilmesi için rest geçin:

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

Zincir, hedged (rastgeleleştirilmiş) veya deterministik olsun, geçerli herhangi bir FIPS-204 ML-DSA-87 imzasını kabul eder. SDK varsayılan olarak deterministik imzalar (0.5.1'den beri); böylece bir işlem her zaman aynı imzaya ve aynı tx hash'ine sahip olur. Bir hibrit tx pqc kod 21 (hybrid_verify_failed) ile başarısız olursa, neden sign-bytes sürümü, chain-id, eski bir PQC kütüphanesi veya kayıtlı olmayan ya da farklı bir anahtardır; asla hedged imzalama değildir: bkz. Kod 21 sorun giderme.

Bir anahtarı döndürün​

Bir hesabın ML-DSA-87 anahtarını aynı algoritmanın başka bir anahtarıyla değiştirmek için (örneğin eski bir shake256(mnemonic) anahtarını adrese bağlı kanonik anahtara taşımak veya ele geçirilmiş bir anahtarı emekliye ayırmak), rotatePqcKeyMsgFromMnemonic ile bir MsgRotatePQCKey oluşturun; her iki anahtar da buna çift imza atar. Tam örnek için Anahtar döndürme bölümüne bakın.

migratePqcKeyHybrid, bir hesabı algoritmalar arasında taşıyan daha eski MsgMigratePQCKey'i, zincirin v3.2.3'ten itibaren anahtarı olan bir hesaptan gerektirdiği hibrit imzayla yayınlar. pqcKeypair, şu anda kayıtlı olan anahtardır (döndürülerek çıkarılan); çağıran iki sahiplik imzasını sağlar (eski anahtarın oldSignature'ı, yeni anahtarın newSignature'ı). Klasik migratePqcKey kullanımdan kaldırılmıştır: bir v3.2.3 düğümü, anahtarı olan bir hesaptan gelen klasik bir geçişi reddeder.

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

Bir ML-KEM-1024 anahtarı yayımlayın​

İmzalama bir işlemi kimin gönderdiğini kanıtlar; şifreleme ise farklı bir anahtar gerektirir. Zincir v3.2.5'ten itibaren bir hesap, zincir üstü KEM kayıt defterinde bir ML-KEM-1024 kapsülleme anahtarı (algoritma kimliği 2, 1.568 bayt) yayımlayabilir; böylece herkes ona bir yük şifreleyebilir. SDK 0.12.0 iki mesajı oluşturur ve kayıt defterini geri okur; şifreleme veya şifre çözme yapmaz (mühürlü yükler için bkz. QoreSeal). Rota ve mesajlar mainnet'te ve testnet'te sunulur.

  • msg.pqc.registerKemKey({ sender, publicKey }) anahtarı yayımlar (ikinci bir çağrı onu değiştirir). Oluşturucu, zincirin yaptığı gibi anahtarı önce denetler: tam boyut, her katsayı 3329'un altında, tamamı sıfır değil (validateKemPublicKey aynı denetimi tek başına çalıştırır).
  • msg.pqc.removeKemKey({ sender }) anahtarı geri çeker.
  • fetchKemKey({ rest, address }), /qorechain/pqc/v1/kem/{address} adresini (bir bech32 veya 0x adresi) okur ve algoritma, anahtar baytları ve kayıt yüksekliğiyle birlikte { found, key? } döndürür.

Her iki mesaj da hesabın hibrit imzasını gerektirir; bu yüzden onları diğer her native işlem gibi hibrit TxClient (client.connectTx(signer, { pqcKeypair })) üzerinden gönderin ve önce hesabın ML-DSA-87 anahtarını kaydedin. pqc 250 ile 254 arasındaki zincir ret kodlarını decodeTxError adlandırır. Diğer dört dil aynı mesajları ve okumayı taşır.

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

Kullanıcı arayüzünde​

@qorechain/react kiti bunların tümünü React'te sunar: usePqcStatus kancası ve <PqcStatusBadge/> bileşeni (<QuantumSafeBadge/> kullanımdan kaldırılmış bir takma addır), bağlı hesabın kayıtlı bir PQC anahtarına sahip olduğu her durumda bir durum göstergesi gösterir. Her ikisi de durumu oluşturulmuş istemciyle getPqcStatus üzerinden okur; bu nedenle @qorechain/react 0.9.0'dan itibaren bunu REST üzerinden okurlar ve genel uç noktalar karşısında çalışırlar; 0.8.x orada bir anahtarı doğrulayamıyordu.