FAQ e risoluzione dei problemi
La mainnet è attiva?
Sì. La mainnet è attiva (chain id qorechain-vladi, attiva dal 7 giugno
2026) esegue la versione della chain v3.2.7 (applicata all'altezza 4.164.600 il 12 novembre 2026, proposta di governance 16; la v3.2.6 è stata applicata all'altezza 4.020.000 il 4 novembre 2026, proposta 15; la v3.2.5 è stata applicata all'altezza 3.906.833 il 29 ottobre 2026 e la v3.2.4 all'altezza 3.742.566 il 23 ottobre 2026); la testnet esegue la v3.2.6 dal 27 ottobre 2026, la v3.2.7 dal 6 novembre e la v3.2.8 dal 12 novembre 2026 (altezza 9.929.500; la mainnet non l'ha applicata). Anche il
preset testnet (qorechain-diana) rimane disponibile. Dall'SDK 0.12.0 entrambi i preset
usano per default gli endpoint pubblici; seleziona la rete con
createClient({ network: "mainnet" }) e sovrascrivi endpoints solo per il
tuo nodo. Vedi Rete ed endpoint.
Perché le mie chiamate finiscono su localhost?
Stai usando un SDK precedente alla 0.12.0, i cui preset usano per default gli endpoint localhost:
aggiorna, oppure passa un oggetto endpoints. Dalla 0.12.0 createClient() e
createClient({ network: "mainnet" }) usano gli endpoint pubblici, e il preset
localnet è quello che usa localhost.
const client = createClient({
endpoints: {
rest: "https://api-testnet.qore.host",
rpc: "https://rpc-testnet.qore.host",
evmRpc: "https://evm-testnet.qore.host",
},
});
Se invece ricevi "endpoint ... is not configured for the mainnet preset", la chiamata
ha bisogno di un endpoint che i preset pubblici non impostano (gRPC, un RPC SVM, il
WebSocket EVM della mainnet); passalo in endpoints.
Il percorso di firma (connectTx) richiede l'endpoint di consenso rpc;
anche le letture QoreChain Native lo usano. Le letture REST usano rest; le chiamate
EVM usano evmRpc (e anche le chiamate qor_, su un nodo che serve quel
namespace). Gli URL della mainnet si trovano nel
riferimento di rete.
"Cannot find module 'viem'" / "'@solana/web3.js'"
Sono dipendenze peer rispettivamente di @qorechain/evm e
@qorechain/svm. Installale nel tuo progetto:
npm i @qorechain/evm viem
npm i @qorechain/svm @solana/web3.js
Una chiamata a un precompile lancia "returned no data" / "feature not present"
I precompile EVM di QoreChain sono compilati nel nodo ma non sono attivi
sulla mainnet, e sulla testnet ne sono attivi solo tre: rispondono solo dove i
loro indirizzi sono elencati nel parametro active_static_precompiles del modulo
EVM. Quell'elenco è vuoto sulla mainnet; sulla testnet contiene i precompile PQC
verify (0x…0A01), PQC key status (0x…0A02) e dei parametri di consenso
(0x…0C01) (verificato il 27 ottobre 2026; l'elenco della testnet conteneva anche il bridge cross-VM 0x…0901 dal 4 novembre e il 7 novembre 2026, attivo con una allowlist (testato con eth_call), e l'elenco della mainnet era ancora vuoto), quindi la coppia AI lì
non risponde ancora nulla. Dove un precompile è inattivo la
chiamata restituisce dati vuoti, quindi viem segnala returned no data ("0x") e
l'helper lancia un errore (vedi
Precompile EVM: stato della rete).
Su un nodo EVM semplice le chiamate falliscono allo stesso modo. Controlla
GET /cosmos/evm/vm/v1/params e avvolgi ogni chiamata a un precompile in modo
da gestire l'errore per ciascuna chiamata.
La mia chiamata client.qor fallisce con -32601
client.qor chiama il namespace JSON-RPC qor_, che nessuna build di nodo
rilasciata serve; rpc_modules sugli endpoint EVM pubblici elenca solo eth,
net, rpc, txpool e web3. Usa invece una route REST, ad esempio
GET /qorechain/pqc/v1/account/{address} (stato della chiave PQC) oppure
GET /qorechain/burn/v1/stats, tramite client.rest.get(...). Vedi
il namespace qor_.
I miei importi sono sballati di un fattore un milione
QOR ha 10^6 unità base uqor. Usa toBase / fromBase e fai tutti i
calcoli in unità base:
toBase("1.5"); // "1500000"
fromBase("1500000"); // "1.5"
Nota che il runtime EVM rappresenta QOR con 18 decimali (convenzione
EVM), che è distinto dalla base Native uqor di 10^6.
Quali pacchetti sono pubblicati, e dove?
Tutti (verificato il 12 novembre 2026). Il core TypeScript (@qorechain/sdk, 0.14.0),
il kit React (@qorechain/react, 0.14.0), lo scaffolder create-qorechain-dapp
(0.14.0, che porta anche le correzioni ai template della 0.13.1) e gli adapter EVM/SVM (@qorechain/evm, @qorechain/svm, 0.14.0) sono su
npm; il client Python è su PyPI (pip install qorechain-sdk alla 0.14.0, import
qorsdk); il client Go è sul module proxy
(go get github.com/qorechain/qorechain-sdk/packages/go@v0.14.0); il client Rust è su
crates.io (cargo add qorechain-sdk, 0.14.0); e il client Java è su Maven
Central (io.github.qorechain:qorechain-sdk, 0.14.0, JDK 17 o successivo). Vedi Installazione
per i comandi completi per ogni linguaggio.
Il mio mnemonic viene rifiutato
L'SDK valida sia la wordlist BIP-39 sia il checksum prima di derivare
qualsiasi chiave, così una frase con un errore di battitura genera
un'eccezione invece di produrre silenziosamente l'account sbagliato.
Ricontrolla le parole; usa validateMnemonic per testare una frase.
Transazioni ibride (PQC)
L'invio ibrido (classico + ML-DSA-87) è attivo e obbligatorio sul percorso
Native: le transazioni Native solo classiche vengono rifiutate on-chain
(chain v3.2.0).
Prima che una tx ibrida superi la verifica PQC, la chiave pubblica PQC del
firmatario deve essere registrata esplicitamente con
MsgRegisterPQCKeyV2 (una transazione firmata in modo classico ed esente dalla
firma ibrida); incorporare la chiave pubblica nell'estensione
(includePqcPublicKey: true) non la registra, e la chain non registra una
chiave al primo utilizzo. In TypeScript, passa al client la coppia di chiavi
(client.connectTx(signer, { pqcKeypair }), SDK 0.9.0 o successivo) e ogni transazione che
invia viene firmata in modalità ibrida.
La chain accetta qualsiasi firma ML-DSA-87 valida secondo FIPS-204, hedged o
deterministica. L'SDK firma in modo deterministico per default (dalla versione
0.5.1) affinché una transazione abbia sempre la stessa firma e lo stesso hash di
tx. Se una tx ibrida fallisce con codice pqc 21 (hybrid_verify_failed), la
causa è la versione dei sign-bytes, il chain-id, una libreria PQC obsoleta o una
chiave non registrata o diversa, mai la firma hedged.
Entrambe le reti verificano la forma v2 dei sign-bytes, quindi usa l'SDK
0.8.1 o successivo (la 0.14.0 è quella attuale) e passa rest (oppure
signBytesVersion): i builder lanciano un errore su qorechain-vladi /
qorechain-diana se manca uno dei due.
Vedi
Risoluzione del codice 21 e
Account e firma PQC.
La mia transazione EVM viene rifiutata con "no open EVM authorisation window"
Dalla chain v3.2.0 la lane EVM ammette una transazione solo da un account che
abbia una chiave PQC registrata e una finestra di autorizzazione aperta.
Registra una chiave, apri una finestra, poi invia. Vedi
Finestra di autorizzazione EVM. Con l'SDK,
classifyEvmWindowRejection(err) restituisce "no-pqc-key", "no-window",
"exhausted" oppure "invalid".
Le mie transazioni ibride falliscono a CheckTx con un errore di parsing della tx
Aggiorna l'SDK. Le versioni 0.6.0 e precedenti serializzavano in JSON
l'estensione del tx-body /qorechain.pqc.v1.PQCHybridSignature, che il
decoder di tx della chain rifiuta a CheckTx. Dalla 0.6.1 l'estensione è
codificata in protobuf (il valore inizia con 0x08) in tutti e cinque i
linguaggi — le transazioni ibride costruite con versioni più vecchie vengono
rifiutate on-chain, in ogni lane (incluso eth-native).
Con quali versioni della chain funziona l'SDK?
L'SDK 0.12.0 è la release client per la chain v3.2.5 (mainnet dal 29 ottobre
2026 all'altezza 3.906.833; la testnet dal 26 ottobre). La mainnet esegue la v3.2.7
(dal 12 novembre) e la testnet la v3.2.8 (dal 12 novembre; la v3.2.7 dal 6 novembre, la v3.2.6 dal 27 ottobre); il formato di firma non è
cambiato fino alla v3.2.7, quindi la 0.12.0 funziona sulla mainnet. La 0.12.0 non ha builder per le aggiunte della v3.2.7 (registrazione del multisig PQC, la modalità di firma textual, l'APR, l'identità del cluster e i messaggi per la verification key), che sono sulla mainnet dal 12 novembre 2026, e il suo percorso di firma non è stato ricontrollato rispetto alla v3.2.7; per quelle usa la CLI. Aggiunge la regola esatta del gas per le
transazioni ibride, i builder e la lettura del registro delle chiavi ML-KEM, le letture
degli account astratti e i builder verificati dei parametri di governance (vedi
Novità della 0.12.0), in aggiunta a ciò che la 0.10.0 ha
aggiunto per la v3.2.4 (i builder e le letture dello staking-tier, fetchAuthNonce e le
letture delle funzionalità di protocollo, vedi
Cosa ha aggiunto la 0.10.0) e la 0.9.0 per la v3.2.2 e la v3.2.3: builder per la prova di
possesso facoltativa alla registrazione (allegata automaticamente da
ensurePqcRegistered una volta che la rete ha applicato la v3.2.3), per le
finestre EVM con ambito limitato e per i messaggi di consenso EIP-7702.
L'SDK 0.8.1 o successivo transa anch'esso su entrambe le reti (la forma v2
dei sign-bytes ibridi, la registrazione, gli invii ibridi e la finestra EVM
funzionano senza modifiche), ma non ha nessuno di quei builder: usa la CLI per
quelli (vedi Versioni precedenti alla 0.9.0). Il
formato di firma non è cambiato nella v3.2.4, nella v3.2.5 né nella v3.2.6. La mainnet esegue la v3.2.7 e la testnet la v3.2.8 (la testnet ha applicato la
v3.2.5 il 26 ottobre 2026, la v3.2.6 il 27 ottobre, la v3.2.7 il 6 novembre e la v3.2.8 il 12 novembre; la mainnet ha applicato la v3.2.5 il 29 ottobre, la v3.2.6 il 4 novembre e la v3.2.7 il 12 novembre). L'SDK 0.10.0 e la 0.9.0 continuano a funzionare su di esse ma non hanno builder per
le aggiunte della v3.2.5 (il registro delle chiavi ML-KEM, la regola esatta del gas); con quelle release usa la CLI, oppure passa alla 0.14.0. La 0.12.0 è stata costruita e verificata contro la v3.2.5.
La registrazione della mia chiave PQC è stata rifiutata ma la fee è stata prelevata
Una registrazione per un account che detiene già una chiave viene rifiutata
dalla chain dopo che la fee è stata detratta. ensurePqcRegistered nella 0.9.0 e successive
legge prima GET /qorechain/pqc/v1/account/{address} (passa rest), salta la
registrazione quando la chiave di questa coppia di chiavi è registrata, e lancia
PqcKeyMismatchError quando ne è registrata una diversa. Le release precedenti
non controllavano prima, a meno che tu non passassi di tuo conto
status: { registered: found }, dove found proviene da quella route. Dalla
v3.2.3 la chain rifiuta inoltre chiavi deboli, degeneri e riutilizzate; le
chiavi da derivePqcCanonical o tx pqc gen-key vanno bene.
create-qorechain-dapp installa un SDK che non può firmare
Solo la versione 0.8.0 dello scaffolder lo faceva: scriveva intervalli ^0.3.0
per @qorechain/sdk e @qorechain/evm, e un intervallo con caret su una
versione 0.x resta dentro la 0.3. Dalla versione 0.9.0 in poi lo scaffolding
è generato sull'SDK attuale; se hai usato la 0.8.0, esegui npm i @qorechain/sdk@latest
(e @qorechain/evm@latest) dopo lo scaffolding.
VERSION dice 0.8.0 ma ho installato la 0.8.3
La costante esportata VERSION della 0.8.3 non era stata aggiornata e riporta
0.8.0; dalla 0.9.0 corrisponde al pacchetto. Nelle release precedenti leggi la
versione installata da package.json.
La mia spesa tramite authenticator viene rifiutata con authenticator_replay
(Il modulo abstractaccount è disattivato sulla mainnet; una spesa lì viene
rifiutata con abstract account module is disabled prima che venga controllato
qualsiasi nonce. Sulla testnet è abilitato. Vedi
Authenticator e spesa delegata. Le indicazioni
qui sotto valgono ovunque il modulo sia abilitato.)
Il nonce è sbagliato. Sia MsgExecuteEVM.nonce sia MsgExecuteCosmos.nonce sono
la sequenza dell'authenticator della chiave collegata per (account, pubkey):
un contatore che la chain mantiene per ogni chiave collegata, parte da 0 e viene
incrementato a ogni esecuzione riuscita. Non è il nonce EVM dell'account, e
leggilo con fetchAuthNonce (SDK 0.10.0 o successivo, chain v3.2.4 o successiva), oppure tienine traccia per ogni chiave
collegata nelle versioni precedenti. Dalla v3.2.3 la lane EVM firma anche evmAuthSignBytesV2, che lega il
gas limit della chiamata (resolveEvmAuthDigestVersion sceglie la forma). Usa il
contatore che leggi (o di cui tieni traccia) per quella chiave e ri-firma.
Gli altri errori dell'authenticator si decodificano con decodeTxError: codici
abstractaccount 5 (spending_limit_exceeded), 6 (session_key_expired) e 10
(permission_denied). Vedi
Authenticator e spesa delegata.