Keys & funding
Every operation that broadcasts a transaction — creating a rollup, submitting a batch, managing lifecycle, executing a withdrawal — needs a signer and a funded account. This guide covers generating keys, where the kit looks for them, quantum-safe signing, and funding an account on testnet.
Generate a key
The CLI generates a mnemonic and its derived qor1… address in one step:
qorollup keygen
The mnemonic is printed once. Store it securely and offline — anyone with it controls the account.
In code, use generateMnemonic and deriveNativeAccount:
import { generateMnemonic, deriveNativeAccount } from "@qorechain/rdk";
const mnemonic = generateMnemonic();
const account = await deriveNativeAccount(mnemonic);
console.log(account.address); // qor1...
// account.privateKey is the raw key bytes for building a signer.
You can validate an existing mnemonic with validateMnemonic.
Where keys come from
The kit reads signing material from the environment, preferring a raw hex key over a mnemonic:
| Variable | Meaning |
|---|---|
QORE_OPERATOR_PRIVATE_KEY_HEX | Raw private key, hex (with or without 0x). Takes priority. |
QORE_MNEMONIC | BIP-39 mnemonic. Used when no hex key is set. |
signerFromEnv builds an OfflineSigner from these, returning undefined when
neither is set (so callers can show a friendly message rather than crash):
import { signerFromEnv } from "@qorechain/rdk";
const signer = await signerFromEnv(); // reads process.env by default
if (!signer) throw new Error("set QORE_OPERATOR_PRIVATE_KEY_HEX or QORE_MNEMONIC");
const tx = await rdk.connectTx(signer, { gasPrice: "0.15uqor" });
The chain enforces a minimum gas price (fee floor) of 0.1uqor per gas unit on both mainnet and testnet. Transactions priced below the floor are rejected at the mempool;
0.15uqoris a comfortable default.
The qorollup CLI uses the same precedence and also accepts --key and
--mnemonic flags, which override the environment. From 0.7.1 its
transaction commands sign hybrid: with --mnemonic the post-quantum key is
derived and matched against the chain (the canonical or the legacy derivation,
whichever your account registered; a new account registers the canonical one on
its first transaction); with --key, pass your 32-byte ML-DSA-87 seed with
--pqc-seed or QORE_PQC_SEED_HEX. Without a post-quantum key the CLI refuses
to send, since both networks would refuse the transaction. Releases before
0.7.1 signed classical-only, so every qorollup transaction was refused.
Build a signer directly
If you already hold a key, build the signer yourself. The RDK accepts any
@cosmjs OfflineSigner.
import { directSignerFromPrivateKey, deriveNativeAccount } from "@qorechain/rdk";
// From a derived account:
const account = await deriveNativeAccount(process.env.QORE_MNEMONIC!);
const signer = await directSignerFromPrivateKey(account.privateKey, "qor");
Signing on a PQC-required network
QoreChain's native lane requires a hybrid signature — ML-DSA-87 (Dilithium-5)
alongside the classical secp256k1 one — on both qorechain-vladi (mainnet) and
qorechain-diana (testnet). A plain OfflineSigner produces only the classical
half, so a classical-only transaction is rejected on those networks.
Pass a pqcKeypair on connect and the tx client signs hybrid for every
transaction it sends — nothing else in your code changes, and the tx methods keep
returning the same response shape:
import { createRdkClient, signerFromEnv, pqcKeypairFromEnv } from "@qorechain/rdk";
const rdk = createRdkClient({ network: "testnet" });
const signer = await signerFromEnv();
if (!signer) throw new Error("set QORE_OPERATOR_PRIVATE_KEY_HEX or QORE_MNEMONIC");
const [{ address }] = await signer.getAccounts();
// Finds the post-quantum key your account actually has on chain (see below).
const pqc = await pqcKeypairFromEnv(rdk, address);
if (!pqc) throw new Error("set QORE_MNEMONIC, or QORE_PQC_SEED_HEX with a raw key");
const tx = await rdk.connectTx(signer, {
gasPrice: "0.15uqor",
pqcKeypair: pqc.keypair, // switches the client to hybrid signing
includePqcPublicKey: pqc.includePqcPublicKey, // registers the key first, if needed
});
await tx.createRollup({ /* … */ });
Which post-quantum key?
A mnemonic can yield two ML-DSA-87 keys, and a wallet may have registered either: the canonical one, bound to your account address (what unified accounts and QoreX use), or the legacy one from the older chain-bridge scheme. Signing with the wrong one is not a soft failure — the signature would not match the registered key and every transaction would be refused.
So resolvePqcKeypair(client, address, mnemonic) (and pqcKeypairFromEnv,
which calls it) derives both and asks the chain which one your account
holds:
| On chain | Result |
|---|---|
| the canonical key | canonical, registered: true |
| the legacy key | legacy, registered: true |
| no key yet | canonical, includePqcPublicKey: true — the first transaction registers it |
| some other key | throws: it was registered from another secret, and guessing would only cost a refused transaction |
If you sign with QORE_OPERATOR_PRIVATE_KEY_HEX, there is no mnemonic to
derive from: set QORE_PQC_SEED_HEX to your 32-byte ML-DSA-87 seed. It is
checked against the chain the same way.
A few things to know:
- The signer must be a direct signer. Hybrid signing uses SIGN_MODE_DIRECT;
an amino-only signer cannot carry the signature extension and is rejected with
an explicit error.
directSignerFromPrivateKeyandsignerFromEnvboth give you a direct signer. - The PQC key must be registered on chain (
MsgRegisterPQCKeyV2) before your operator account can send anything else: since chain v3.2.3 an account without a registered key may send only a registration. WithincludePqcPublicKey: truethe client registers it for you, with a proof of possession, in a transaction of its own before the first real one (about 0.09 QOR in fees, once). restis filled in for you. The sign-bytes form is resolved from the network (signBytesVersion: "auto", the default), which needs the REST/LCD endpoint;rdk.connectTxpasses the network preset's REST endpoint automatically. UsingRdkTxClient.connectdirectly, passrestyourself."auto"resolves the sign-bytes form for you. It reads the network's upgrade state over REST and recognises both plan names the v2 hybrid sign-bytes have shipped under (mainnet took v2 in v3.2.0, the testnet in v3.1.98). Force a form withsignBytesVersion: "v1"or"v2"only for a custom network you know better than the resolver does.resolveSignBytesVersionandisHybridSignBytesRejectionare re-exported if you want to inspect or handle this yourself.- Fees must be explicit. The hybrid builder needs a concrete
StdFee, so either passfeeper transaction or setgasPriceon connect (a gas limit is priced with it, and"auto"simulates first). Without either, the client throws instead of guessing.
Every client signs hybrid from 0.8.0. Python, Go, Rust and Java sign through their QoreChain SDK when given a post-quantum keypair, with the same key resolution (
resolve_pqc_keypair/ResolvePqcKeypair/resolve_pqc_keypair/Accounts.resolvePqcKeypair, and theQORE_PQC_SEED_HEX/QORE_MNEMONICenvironment form), and produce the same bytes as TypeScript for the same input. Releases before 0.8.0 signed those four classical-only, so only their reads worked on mainnet and testnet. The Java package needs Java 21 from 0.8.0.
The kit also re-exports HybridSigner, PqcSigner, generatePqcKeypair,
pqcSign, and pqcVerify for lower-level post-quantum use. The kit exposes
exactly the primitives the SDK and chain implement — nothing more.
Unified keys & Phantom
QoreChain supports a unified account: one key controls all three address
forms — qor1… (QoreChain Native), 0x… (EVM), and the SVM address — as a
single identity, and that same key can sign on every lane (one balance across
them). Wallets such as Phantom can derive and hold this unified key.
The RDK is agnostic to how your signer was produced: it signs operator
transactions with any @cosmjs OfflineSigner, so a unified eth-native key
(or a Phantom-derived one) works exactly like a classic qor-derived signer —
the operator address is simply whatever your signer presents, with no RDK
configuration changes.
Generating and managing the unified wallet itself is the job of
@qorechain/sdk and
@qorechain/wallet-adapter
— the wallet adapter derives all three addresses from one key
(generateQoreWallet, walletFromMnemonic) and supports the Phantom flow via
walletFromSeed (shake256(phantomSignature) → qor1/0x/svm). Build the signer
there, then hand it to the RDK's tx client.
Funding an account
Creating a rollup commits a stake and burns a small percentage on creation, so
the operator account must hold at least the live minStakeForRollup plus fees.
Check readiness with qorollup doctor (the balance check) before you spend.
Testnet faucet
The network does not publish a fixed faucet endpoint, so the faucet helper
posts to a URL you supply. Set QORE_FAUCET_URL (or pass --faucet-url):
export QORE_FAUCET_URL=https://faucet.testnet.example
qorollup faucet qor1youraddress...
In code:
import { requestFaucet } from "@qorechain/rdk";
const result = await requestFaucet({
url: process.env.QORE_FAUCET_URL,
address: "qor1youraddress...",
denom: "uqor", // default
});
console.log(result.ok, result.status);
If no URL is configured, requestFaucet throws a clear message rather than
guessing an endpoint. When you do not have a faucet, fund the address by transfer
from another funded account instead.
Mainnet
There is no faucet on mainnet — fund the operator account from an exchange or
another account you control. Preview the exact stake and burn with
estimateCreationCost against the live params; see Stake & burn.
Next
- Zero to a live rollup — the end-to-end flow.
- Stake & burn — read the live creation cost.
- Withdrawals — the submitter signs the execute message.