Skip to main content

Hybrid signing by default

QoreChain treats post-quantum cryptography as a first-class signature scheme. An account registers an ML-DSA-87 (Dilithium-5, NIST FIPS 204) key on-chain, after which its transactions can carry a hybrid signature — the usual classical secp256k1 signature plus an ML-DSA-87 signature. The chain's ante handler verifies both, so an account with a registered key stays fully compatible with classical verification while its transactions also carry a post-quantum signature.

The SDK packages this into a tiny, idempotent surface so a dApp signs hybrid by default: one call registers the key. On the live networks this is not optional for Native-path transactions: the key must be registered explicitly (there is no auto-registration on the first transaction), and every Native-path transaction must then carry the hybrid signature.

Check status​

isPqcRegistered / getPqcStatus read whether an address has a registered PQC key. Given the composed client from createClient they read over REST (GET /qorechain/pqc/v1/account/{address}, served by every public endpoint); given a bare QorClient they use the qor_getPQCKeyStatus JSON-RPC method, which the public endpoints do not serve (see the qor_ namespace), so against *.qore.host pass the composed client. Releases before 0.9.0 always used the qor_ method and failed with JSON-RPC error -32601; read the REST route directly there.

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 }

The route is GET /qorechain/pqc/v1/account/{address} (singular account). It answers {"found": true, "account": {…}} for a registered address and {"found": false, "account": null} otherwise; client.rest.getPqcAccount(address) returns that body, and fetchPqcStatus({ rest, address }) turns it into the status above. An unreadable answer (an HTTP error, a transport failure) is thrown after one retry: it is never read as "not registered". In 0.8.x getPqcAccount called a plural /accounts/ path that the chain does not serve.

The same status is also readable on the EVM side via the pqcKeyStatus(address) returns (bool registered, uint8 algorithmId, bytes pubkey) precompile at 0x0000000000000000000000000000000000000a02 (exposed as pqcKeyStatus in @qorechain/evm) once that precompile is active; it is not active on mainnet, and it is listed as active on the testnet (checked 27 October 2026; see Network status).

Register in one call​

ensurePqcRegistered registers the account's ML-DSA-87 key. It builds and broadcasts MsgRegisterPQCKeyV2 with the signer's ML-DSA-87 public key. It is idempotent: it reads the account's status first (over REST when you pass rest), skips the registration when the account already holds this keypair's key, and is therefore safe to call on every app start. When the account holds a different key it throws PqcKeyMismatchError and sends nothing, because every hybrid transaction signed with your keypair would be refused. It never registers blind: if the status cannot be read it throws (pass force: true only for an account you know has no key).

Registration is classical-signed and exempt from the hybrid requirement, so a new account can bootstrap its first key; since v3.2.3 that exemption covers only an account with no key (an account that already holds one must hybrid-sign a register or migrate, and the chain refuses weak, degenerate or reused keys). Once the network has applied v3.2.3 the helper signs the optional proof of possession with the new key and attaches it (it reads the chain id from chainId or from the node, and leaves the field off on a network that has not applied v3.2.3, because an older node refuses it). It signs through a CosmJS signer, that is, a coin-type-118 account (deriveNativeAccount); for a unified eth-native account sign the registration with EthNativeSigner and signMode: "classical" (see Accounts & PQC signing). The 2,592-byte key needs a gas limit of about 600,000; the network's minimum gas price is 0.1 uqor per unit of gas.

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

A key you can recover​

derivePqcCanonical(address, mnemonic) derives the account's ML-DSA-87 key from its address and mnemonic, so a lost device is recoverable and every language and wallet derives the same key (one mnemonic, one key per account). It resolves the address to its lower-case qor1… form first, so the 0x form of a unified account gives the same key. The equivalents:

LanguageFunctionPublished
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) (returns a Result)0.9.0
JavaAuthenticator.derivePqcCanonical(address, mnemonic)0.9.0

The legacy derivation (derivePqcLegacy, "bridge") is not bound to the account and is deprecated for new keys; the rotation helpers refuse it as the new key (see Rotate a key).

Registration in Python (0.9.0; the status read goes over REST and the call raises PqcKeyMismatchError for a different registered key instead of paying for a second registration):

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

The Go (pqcdx.Signer.RestURL), Rust (pqc_dx rest_url) and Java (signer.restUrl) helpers read the status from the same REST route and attach the proof of possession the same way.

The other SDKs sign hybrid through their hybrid transaction builders (build_hybrid_tx in Python and Rust, tx.BuildHybridMessages in Go, PqcDx.HybridSendPath in Java); only the TypeScript TxClient signs hybrid for you.

Always let it check first

The chain refuses a second registration of the same key after charging the fee. ensurePqcRegistered therefore reads the status first, over REST (/qorechain/pqc/v1/account/{address}), and refuses to register when it cannot tell. Pass rest (or statusSource for a node that exposes qor_*, or a pre-read status); force: true skips the check. In 0.8.x the helper had no REST fallback and broadcast the registration unchecked unless you passed status yourself.

Sign hybrid​

With a pqcKeypair on the client, tx.bankSend(...) and tx.signAndBroadcast([messages], "auto") sign hybrid (the fee: "auto" path simulates the hybrid transaction; from SDK 0.12.0 on a v3.2.5 network the limit is the exact rule ceil(simulated x 1.02) + 2000, before that the client adds the gas of the post-quantum verification itself). The hybrid signature is computed over the sign-bytes form the network verifies (see Which sign-bytes form?); the client asks the network through its REST endpoint.

migrateToHybrid ensures registration and hands back a hybrid send path with the keypair pre-bound to the lower-level buildHybridTx / signAndBroadcastHybrid builders, for when you manage the fee, account number and sequence yourself. Pass rest so the SDK can resolve the sign-bytes form:

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

The chain accepts any valid FIPS-204 ML-DSA-87 signature, hedged or deterministic. The SDK signs deterministically by default (since 0.5.1) so a transaction always has the same signature and tx hash. If a hybrid tx fails with pqc code 21 (hybrid_verify_failed), the cause is the sign-bytes version, the chain-id, a stale PQC library or an unregistered or different key, never hedged signing: see Troubleshooting code 21.

Rotate a key​

To replace an account's ML-DSA-87 key with another key of the same algorithm (for example moving a legacy shake256(mnemonic) key to the canonical address-bound key, or retiring a compromised key), build a MsgRotatePQCKey with rotatePqcKeyMsgFromMnemonic; both keys dual-sign it. See Key rotation for the full example.

migratePqcKeyHybrid broadcasts the older MsgMigratePQCKey, which moves an account between algorithms, with the hybrid signature the chain requires from v3.2.3 of an account that has a key. pqcKeypair is the key that is currently registered (the one being rotated out), and the caller supplies the two ownership signatures (oldSignature by the old key, newSignature by the new key). The classical migratePqcKey is deprecated: a v3.2.3 node refuses a classical migration from a keyed account.

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

Publish an ML-KEM-1024 key​

Signing proves who sent a transaction; encryption needs a different key. From chain v3.2.5 an account can publish one ML-KEM-1024 encapsulation key (algorithm id 2, 1,568 bytes) in the on-chain KEM registry, so anyone can encrypt a payload to it. SDK 0.12.0 composes the two messages and reads the registry back; it does not encrypt or decrypt (for sealed payloads see QoreSeal). The route and the messages are served on mainnet and the testnet.

  • msg.pqc.registerKemKey({ sender, publicKey }) publishes the key (a second call replaces it). The composer checks the key first, as the chain does: exact size, every coefficient below 3329, not all zero (validateKemPublicKey runs the same check on its own).
  • msg.pqc.removeKemKey({ sender }) withdraws it.
  • fetchKemKey({ rest, address }) reads /qorechain/pqc/v1/kem/{address} (a bech32 or 0x address) and returns { found, key? }, with the algorithm, the key bytes and the registration height.

Both messages need the account's hybrid signature, so send them through the hybrid TxClient (client.connectTx(signer, { pqcKeypair })) like any other native transaction, and register the account's ML-DSA-87 key first. Chain refusals pqc 250 to 254 are named by decodeTxError. The other four languages carry the same messages and read.

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 the UI​

The @qorechain/react kit surfaces all of this in React: the usePqcStatus hook and the <PqcStatusBadge/> component (<QuantumSafeBadge/> is a deprecated alias) show a status indicator whenever the connected account has a registered PQC key. Both read the status through getPqcStatus with the composed client, so from @qorechain/react 0.9.0 they read it over REST and work against the public endpoints; 0.8.x could not confirm a key there.