Skip to main content

FAQ & troubleshooting

Is mainnet live?​

Yes. Mainnet is live (chain id qorechain-vladi, live since 7 June 2026) and runs chain version v3.2.7 (applied at height 4,164,600 on 12 November 2026, governance proposal 16; v3.2.6 was applied at height 4,020,000 on 4 November 2026, proposal 15; v3.2.5 was applied at height 3,906,833 on 29 October 2026 and v3.2.4 at height 3,742,566 on 23 October 2026); the testnet has run v3.2.6 since 27 October 2026, v3.2.7 from 6 November and v3.2.8 since 12 November 2026 (height 9,929,500; mainnet has not applied it). The testnet preset (qorechain-diana) also remains available. From SDK 0.12.0 both presets default to the public endpoints; select the network with createClient({ network: "mainnet" }) and override endpoints only for your own node. See Network & endpoints.

Why do my calls hit localhost?​

You are on an SDK before 0.12.0, whose presets default to localhost endpoints: upgrade, or pass an endpoints object. From 0.12.0 createClient() and createClient({ network: "mainnet" }) use the public endpoints, and the localnet preset is the one that uses localhost.

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

If instead you get "endpoint ... is not configured for the mainnet preset", the call needs an endpoint the public presets do not set (gRPC, an SVM RPC, the mainnet EVM WebSocket); pass it in endpoints.

The signing path (connectTx) needs the consensus rpc endpoint; QoreChain Native reads also use it. REST reads use rest; EVM calls use evmRpc (and qor_ calls too, on a node that serves that namespace). The mainnet URLs are in the network reference.

"Cannot find module 'viem'" / "'@solana/web3.js'"​

These are peer dependencies of @qorechain/evm and @qorechain/svm respectively. Install them in your project:

npm i @qorechain/evm viem
npm i @qorechain/svm @solana/web3.js

A precompile call throws "returned no data" / "feature not present"​

The QoreChain EVM precompiles are compiled into the node but are not active on mainnet, and only three are active on the testnet: they answer only where their addresses are listed in the EVM module's active_static_precompiles parameter. That list is empty on mainnet; on the testnet it holds the PQC verify (0x…0A01), PQC key status (0x…0A02) and consensus-parameters (0x…0C01) precompiles (checked 27 October 2026; the testnet list also held the cross-VM bridge 0x…0901 from 4 November and on 7 November 2026, active with an allowlist (tested with eth_call), and mainnet's list was still empty), so the AI pair still answers nothing there. Where a precompile is inactive the call returns empty data, so viem reports returned no data ("0x") and the helper throws (see EVM Precompiles: Network status). On a plain EVM node the calls fail the same way. Check GET /cosmos/evm/vm/v1/params and wrap each precompile call so the error is handled per call.

My client.qor call fails with -32601​

client.qor calls the qor_ JSON-RPC namespace, which no released node build serves; rpc_modules on the public EVM endpoints lists only eth, net, rpc, txpool and web3. Use a REST route instead, for example GET /qorechain/pqc/v1/account/{address} (PQC key status) or GET /qorechain/burn/v1/stats, through client.rest.get(...). See the qor_ namespace.

My amounts are off by a factor of a million​

QOR has 10^6 base uqor units. Use toBase / fromBase and do all math in base units:

toBase("1.5"); // "1500000"
fromBase("1500000"); // "1.5"

Note the EVM runtime represents QOR with 18 decimals (EVM convention), which is distinct from the Native uqor base of 10^6.

Which packages are published, and where?​

All of them (checked 12 November 2026). The TypeScript core (@qorechain/sdk, 0.14.0), the React kit (@qorechain/react, 0.14.0), the create-qorechain-dapp scaffolder (0.14.0, which also carries the 0.13.1 template fixes) and the EVM/SVM adapters (@qorechain/evm, @qorechain/svm, 0.14.0) are on npm; the Python client is on PyPI (pip install qorechain-sdk at 0.14.0, import qorsdk); the Go client is on the module proxy (go get github.com/qorechain/qorechain-sdk/packages/go@v0.14.0); the Rust client is on crates.io (cargo add qorechain-sdk, 0.14.0); and the Java client is on Maven Central (io.github.qorechain:qorechain-sdk, 0.14.0, JDK 17 or later). See Install for the full per-language commands.

My mnemonic is rejected​

The SDK validates both the BIP-39 wordlist and the checksum before deriving any key, so a typo'd phrase raises instead of silently producing the wrong account. Re-check the words; use validateMnemonic to test a phrase.

Hybrid (PQC) transactions​

Hybrid (classical + ML-DSA-87) submission is live and required on the Native path: classical-only Native transactions are rejected on-chain (chain v3.2.0). Before a hybrid tx PQC-verifies, the signer's PQC public key must be registered explicitly with MsgRegisterPQCKeyV2 (a classical-signed, hybrid-exempt transaction); embedding the public key in the extension (includePqcPublicKey: true) does not register it, and the chain does not register a key on first use. In TypeScript, give the client the keypair (client.connectTx(signer, { pqcKeypair }), SDK 0.9.0 or later) and every transaction it sends is signed hybrid. 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. Both networks verify the v2 sign-bytes form, so use SDK 0.8.1 or later (0.14.0 is current) and pass rest (or signBytesVersion): the builders throw on qorechain-vladi / qorechain-diana without one of them. See Troubleshooting code 21 and Accounts & PQC signing.

My EVM transaction is refused with "no open EVM authorisation window"​

Since chain v3.2.0 the EVM lane admits a transaction only from an account that has a registered PQC key and an open authorization window. Register a key, open a window, then send. See EVM authorization window. With the SDK, classifyEvmWindowRejection(err) returns "no-pqc-key", "no-window", "exhausted" or "invalid".

My hybrid transactions fail at CheckTx with a tx parse error​

Upgrade the SDK. Versions 0.6.0 and earlier JSON-serialized the /qorechain.pqc.v1.PQCHybridSignature tx-body extension, which the chain's tx decoder rejects at CheckTx. Since 0.6.1 the extension is protobuf-encoded (the value begins with 0x08) in all five languages — hybrid transactions built with older versions are rejected on-chain, in every lane (including eth-native).

Which chain versions does the SDK work with?​

SDK 0.12.0 is the client release for chain v3.2.5 (mainnet since 29 October 2026 at height 3,906,833; the testnet since 26 October). Mainnet runs v3.2.7 (since 12 November) and the testnet v3.2.8 (since 12 November; v3.2.7 from 6 November, v3.2.6 from 27 October); the signing format did not change up to v3.2.7, so 0.12.0 works on mainnet. 0.12.0 has no builders for the v3.2.7 additions (PQC multisig registration, the textual sign mode, the APR, cluster identity and verification key messages), which are on mainnet since 12 November 2026, and its signing path was not re-checked against v3.2.7; use the CLI for those. It adds the exact gas rule for hybrid transactions, the ML-KEM key registry builders and read, the abstract-account reads and the checked governance parameter builders (see What 0.12.0 adds), on top of what 0.10.0 added for v3.2.4 (the staking-tier builders and reads, fetchAuthNonce and the protocol-feature reads, see What 0.10.0 added) and 0.9.0 for v3.2.2 and v3.2.3: builders for the optional proof of possession on registration (attached automatically by ensurePqcRegistered once the network has applied v3.2.3), scoped EVM windows and the EIP-7702 consent messages. SDK 0.8.1 or later also transacts on both networks (the v2 hybrid sign-bytes form, registration, hybrid sends and the EVM window work unchanged), but it has none of those builders: use the CLI for them (see Versions before 0.9.0). The signing format did not change in v3.2.4, v3.2.5 or v3.2.6. Mainnet runs v3.2.7 and the testnet v3.2.8 (the testnet applied v3.2.5 on 26 October 2026, v3.2.6 on 27 October, v3.2.7 on 6 November and v3.2.8 on 12 November; mainnet applied v3.2.5 on 29 October, v3.2.6 on 4 November and v3.2.7 on 12 November). SDK 0.10.0 and 0.9.0 keep working on them but have no builders for the v3.2.5 additions (the ML-KEM key registry, the exact gas rule); with those releases use the CLI, or upgrade to 0.14.0. 0.12.0 was built and checked against v3.2.5.

My PQC key registration was refused but the fee was taken​

A registration for an account that already holds a key is refused by the chain after the fee is deducted. ensurePqcRegistered in 0.9.0 and later reads GET /qorechain/pqc/v1/account/{address} first (pass rest), skips the registration when this keypair's key is registered, and throws PqcKeyMismatchError when a different one is. Earlier releases did not look first unless you passed status: { registered: found } yourself, where found comes from that route. Since v3.2.3 the chain also refuses weak, degenerate and reused keys; keys from derivePqcCanonical or tx pqc gen-key are fine.

create-qorechain-dapp installs an SDK that cannot sign​

Only version 0.8.0 of the scaffolder did: it wrote ^0.3.0 ranges for @qorechain/sdk and @qorechain/evm, and a caret range on a 0.x version stays inside 0.3. Version 0.9.0 and later scaffold on the current SDK; if you used 0.8.0, run npm i @qorechain/sdk@latest (and @qorechain/evm@latest) after scaffolding.

VERSION says 0.8.0 but I installed 0.8.3​

The exported VERSION constant of 0.8.3 was not updated and reports 0.8.0; from 0.9.0 it matches the package. Read the installed version from package.json on earlier releases.

My authenticator spend is rejected with authenticator_replay​

(The abstractaccount module is switched off on mainnet; a spend there is refused with abstract account module is disabled before any nonce is checked. It is enabled on the testnet. See Authenticators & delegated spending. The guidance below applies wherever the module is enabled.)

The nonce is wrong. Both MsgExecuteEVM.nonce and MsgExecuteCosmos.nonce are the linked key's authenticator sequence for (account, pubkey): a counter the chain keeps per linked key, starting at 0 and incremented by each successful execution. It is not the account's EVM nonce. Read it with fetchAuthNonce (SDK 0.10.0 or later, chain v3.2.4 or later), or track it per linked key on older versions. Since v3.2.3 the EVM lane also signs evmAuthSignBytesV2, which binds the call's gas limit (resolveEvmAuthDigestVersion picks the form). Use the counter you read (or track) for that key and re-sign.

Other authenticator failures decode via decodeTxError: abstractaccount codes 5 (spending_limit_exceeded), 6 (session_key_expired), and 10 (permission_denied). See Authenticators & delegated spending.