Passa al contenuto principale

Guida per exchange e integratori

Tutto ciò di cui un exchange, un custode o un integratore di pagamenti ha bisogno per quotare QOR ed elaborare depositi e prelievi: scegliere un'interfaccia, rilevare i depositi in modo sicuro e firmare i prelievi.

nota

Questa guida si riferisce alla mainnet qorechain-vladi (attiva dal 7 giugno 2026; release del nodo v3.2.7 al momento della stesura, applicata all'altezza 4.164.600 il 12 novembre 2026 dalla proposta di governance 16, dopo la v3.2.6 all'altezza 4.020.000 il 4 novembre 2026, la v3.2.5 all'altezza 3.906.833 il 29 ottobre 2026, la v3.2.4 all'altezza 3.742.566 il 23 ottobre 2026 e la v3.2.3 all'altezza 3.662.051 il 20 ottobre 2026). Prova prima l'intero flusso sulla testnet qorechain-diana. Esegue la v3.2.8 dal 12 novembre 2026 (la v3.2.7 dal 6 novembre, la v3.2.6 dal 27 ottobre, la v3.2.5 è stata applicata il 26 ottobre) e esegue la v3.2.4 dal 19 ottobre 2026, quindi le modifiche dalla v3.2.2 alla v3.2.4 elencate di seguito valgono per entrambe le reti (gli endpoint di entrambe le reti sono in Reti). Se gestisci un tuo full node, mantienilo sulla release raccomandata dal manifest di download e mai al di sotto del suo minCompatible (3.2.7 sulla mainnet e 3.2.8 sulla testnet al momento della stesura): un nodo non aggiornato non riesce a seguire gli upgrade della chain e si ferma all'altezza dell'upgrade; vedi Gestire un nodo.

Cosa è cambiato per gli integratori nella v3.2.2 e nella v3.2.3 (formato di firma, indirizzi, decimali, memo e commissioni restano invariati):

  • Le transazioni Ethereum non protette (pre-EIP-155) vengono rifiutate nel mempool e nell'esecuzione dei blocchi (v3.2.2). Il wallet di un depositante deve firmare con un chain id; ogni wallet attuale lo fa.
  • Gli account di modulo non possono essere rivendicati tramite la EVM (v3.2.2); non usare l'indirizzo di un account di modulo come indirizzo di deposito o di prelievo.
  • Gli account di vesting possono essere creati solo per il firmatario stesso (v3.2.3); i tre messaggi di creazione di vesting si trovano inoltre attualmente nella lista del circuit breaker della mainnet.
  • I messaggi sulle chiavi PQC richiedono la firma ibrida una volta che un account ha una chiave (v3.2.3): vedi Firma post-quantum. Registra la chiave della hot wallet una sola volta, presto.
  • Le finestre EVM possono avere un ambito limitato (v3.2.3): una hot wallet che invia solo QOR semplice può aprire una finestra native_only, vedi Sviluppo EVM.

Cosa cambia per gli integratori nella v3.2.4 (sulla testnet dal 19 ottobre 2026 e sulla mainnet dal 23 ottobre 2026). La firma delle transazioni, gli indirizzi, i decimali, i memo e le commissioni restano invariati, e nulla cambia nel modo in cui un deposito viene rilevato o un prelievo viene firmato e trasmesso:

  • Blocchi di staking facoltativi (nuovo modulo x/stakingtier). Un delegatore può bloccare una parte di una delega per 3, 6 o 12 mesi (blocco minimo 10 QOR, al massimo 16 blocchi aperti per delegatore). Non succede nulla a un account che non crea un blocco. Finché un blocco è aperto, quell'importo non può essere undelegato né ridelegato, da nessuna via (una transazione semplice, authz, un gruppo o un contratto); terminare un blocco in anticipo brucia una penalità dallo stake bloccato. Un custode che mette in staking i fondi dei clienti non dovrebbe quindi bloccare la parte che potrebbe dover restituire. Leggi i parametri su GET /qorechain/stakingtier/v1/params.
  • Una nuova fonte di burn, staking_tier_penalty, compare nelle statistiche di burn quando avvengono sblocchi anticipati. I job di riconciliazione dell'offerta che enumerano le fonti di burn dovrebbero accettare il nome di una fonte sconosciuta.
  • Limiti JSON-RPC locali al nodo per i nodi che gestisci tu stesso: i corpi di richiesta superiori a 256 KiB vengono rifiutati (HTTP 413), non vengono servite più di 256 richieste contemporaneamente (HTTP 503 oltre questo limite), e un filtro eth_getLogs o eth_newFilter con più di 4 posizioni di topic, 1000 alternative in una posizione o 1000 indirizzi viene rifiutato. I limiti sono configurabili nella sezione [json-rpc] di app.toml (vedi Gestire un nodo). Uno scanner di depositi che interroga eth_getLogs con una lunga lista di indirizzi dovrebbe dividere la lista.
  • Una registrazione ripetuta della chiave viene rifiutata prima di essere pagata. Un nodo che esegue la v3.2.4 rifiuta, al momento della trasmissione, un MsgRegisterPQCKeyV2 che reca esattamente la chiave pubblica già registrata dall'account, con l'errore che la chain avrebbe restituito (codice PQC 7, account già esistente), e senza addebitare alcuna commissione. Controlla GET /qorechain/pqc/v1/account/{address} prima di registrare la chiave di una hot wallet, come raccomandato di seguito.
  • Flag di possesso facoltativo. Il record dell'account acquisisce un campo possession_proven che indica se una prova di possesso è stata verificata alla registrazione; non cambia chi può inviare o ricevere. Vedi Firma post-quantum.

Solo testnet: altre denominazioni su qorechain-diana (v3.2.8). La testnet detiene più di uqor: tre token di test (fUSD, fETH, fBTC) registrati come coppie di token ERC-20 ed esposti come denom bank chiamati erc20:<indirizzo 0x EIP-55>, più un token IBC. Sono token di test senza valore, e la mainnet non ne ha nessuno (la sua supply bank contiene solo uqor). Se provi uno scanner di depositi sulla testnet, tratta il denom come parte della chiave e mantieni la regola qui sotto: accredita solo uqor e rifiuta ogni altro denom. Il denom erc20: è sensibile alle maiuscole (la scrittura minuscola dell'indirizzo è un denom diverso e sconosciuto), e convertire un saldo ERC-20 in un bank coin con MsgConvertERC20 richiede il mittente come indirizzo bech32 qor1. Dettagli e i tre indirizzi dei contratti: Sviluppo EVM.

Scegliere un percorso di integrazione​

QoreChain è un'unica chain con un solo saldo nativo QOR unificato esposto attraverso tre interfacce. La stessa chiave privata controlla gli stessi fondi sotto un indirizzo Cosmos (qor1...), uno EVM (0x...) e uno SVM (base58) — scegli l'interfaccia più adatta al tuo stack.

A) Cosmos (nativo)B) EVMC) SVM (Solana VM)
Indirizzoqor1... (bech32)0x... (Ethereum)Solana base58 (stessa chiave)
Decimali (QOR nativo)6 (uqor)18 (stile wei)9 (lamport; 1 uqor = 1.000 lamport)
StrumentiCosmos SDK / CosmJSEthereum standard (ethers/web3, MetaMask)@solana/web3.js
Firma dei prelieviPQC ibrida richiesta (ML-DSA-87 + secp256k1)secp256k1 standard / EIP-155, ma solo all'interno di una finestra di autorizzazione PQC aperta (chiave ML-DSA registrata + finestra aperta da un messaggio Cosmos firmato in modo ibrido)tramite tx Cosmos o invio dal nodo (canale attualmente disabilitato)
Supporto memo / tagSì (indirizzo condiviso + memo)No (un indirizzo per utente)No (un indirizzo per utente)
Rilevamento depositiscansione degli eventi MsgSendscansione dei blocchi via eth_getBlockByNumbergetBalance / getSignaturesForAddress
Ideale perPiattaforme native CosmosPiattaforme con integrazione EVM esistentePiattaforme con strumenti Solana

Raccomandazione: usa il Percorso A (Cosmos) per i prelievi; è la via nativa e offre indirizzi di deposito condivisi basati su memo. Dalla v3.2.0 anche il canale EVM (Percorso B) richiede una chiave ML-DSA-87 registrata e una finestra di autorizzazione EVM aperta e delimitata, che può essere aperta solo con un messaggio del canale Cosmos firmato in modo ibrido; un binario di prelievo EVM richiede quindi lo stesso stack di firma post-quantum del Percorso A più la gestione delle finestre (vedi Percorso B e la finestra di autorizzazione EVM). Il Percorso B resta adatto al rilevamento dei depositi con strumenti Ethereum standard. Il Percorso C (SVM) è sulla carta un'interfaccia nativa QOR completa, ma il suo canale di transazione è attualmente disabilitato a livello dell'intera rete (vedi Percorso C) — usa il Percorso A, oppure il Percorso B per il rilevamento dei depositi, finché non riapre.

Le tre interfacce non si escludono a vicenda — i fondi inviati alla forma 0x, qor1 o SVM della stessa chiave sono lo stesso saldo.

Eseguire il tuo nodo​

Le integrazioni in produzione dovrebbero verificare i depositi sul proprio nodo sincronizzato, non su un endpoint di terze parti. Segui Connessione alla Mainnet — copre il pacchetto di binari precompilati (con checksum SHA-256), il genesis, i peer pubblici, la soglia minima di commissione (0.1uqor) e un bootstrap rapido tramite lo snapshot pubblicato dei dati della chain. Non è richiesta alcuna licenza per eseguire un full node non validatore.

Poiché QoreChain ha finalità istantanea (nessun reorg), 1 conferma è definitiva; attendere 1–2 blocchi offre un comodo margine operativo.

Percorso A — Cosmos (nativo)​

URL REST di base: https://api.qore.host (oppure http://localhost:1317 sul tuo nodo).

Monitorare i depositi​

# latest height
curl -s https://rpc.qore.host/status | jq -r .result.sync_info.latest_block_height

# all txs in a height (deposit scanning)
curl -s "https://api.qore.host/cosmos/tx/v1beta1/txs/block/{HEIGHT}" | jq '.txs'

# incoming transfers to an address
curl -s "https://api.qore.host/cosmos/tx/v1beta1/txs?query=transfer.recipient='qor1...'&limit=50" | jq '.tx_responses[].txhash'

# balance (uqor — divide by 1e6 for QOR)
curl -s "https://api.qore.host/cosmos/bank/v1beta1/balances/qor1.../by_denom?denom=uqor" | jq -r .balance.amount

Lista di controllo anti-falso-deposito​

Accredita un deposito solo quando tutte le condizioni seguenti sono soddisfatte:

  1. tx_response.code == 0 — la transazione è andata a buon fine; non accreditare mai una tx fallita.
  2. Il messaggio è /cosmos.bank.v1beta1.MsgSend (o un output di MsgMultiSend) — non una chiamata a contratto o un altro modulo.
  3. Il campo to_address corrisponde al tuo indirizzo di deposito e, con il modello ad indirizzo condiviso, il memo corrisponde all'utente.
  4. Il denom == "uqor" e l'amount è il valore da accreditare (uqor → ÷ 10⁶ per ottenere QOR). Rifiuta qualsiasi altro denom, compreso un denom erc20:... o ibc/... (la testnet ne contiene; la mainnet oggi non ne ha, ma la regola non deve dipendere da questo).
  5. La tx si trova in un blocco confermato (height presente e ≤ l'ultima altezza confermata). La finalità è istantanea — 1 conferma è definitiva; attendi 1–2 blocchi per margine.
  6. Ricalcola l'importo dagli eventi di trasferimento (coin_received / coin_spent) e confrontalo con l'importo nel messaggio — non fidarti mai di un unico campo o del solo memo.
  7. Verifica che l'hash della tx esista tramite GET /cosmos/tx/v1beta1/txs/{hash} sul tuo proprio nodo sincronizzato.

Prelievi — firma PQC ibrida​

La mainnet impone firme post-quantum sulle transazioni cosmos (allow_classical_fallback = false): ogni prelievo richiede una firma ibrida — ML-DSA-87 (Dilithium-5, FIPS-204) più secp256k1. I depositi non ne hanno bisogno (ti limiti a osservare la chain).

La libreria di firma è @qorechain/wallet-adapter (npm), che include @qorechain/pqc per le primitive FIPS-204:

npm i @qorechain/wallet-adapter @qorechain/pqc @cosmjs/proto-signing@0.32 @cosmjs/stargate@0.32 cosmjs-types@0.9.0
# pin the cosmjs packages to 0.32 (the adapter's peer range) and cosmjs-types to 0.9.x — 0.10 breaks the subpath imports the adapter uses

La firma è un flusso in due fasi (che rispecchia qorechaind tx pqc cosign):

Fase 1 — una tantum per ogni hot wallet: registra la sua chiave ML-DSA-87. Questa transazione di registrazione, unica, è firmata in modo classico (esenzione di bootstrap, per un account che non ha ancora una chiave; una volta che esiste una chiave, qualsiasi ulteriore messaggio sulla chiave deve essere firmato in modo ibrido): messaggio /qorechain.pqc.v1.MsgRegisterPQCKeyV2 con {sender, public_key, algorithm_id: 1, key_type: "hybrid"}. Deriva la chiave ML-DSA in modo deterministico affinché sia recuperabile dal tuo segreto esistente — ad es. seed = SHAKE-256("qorechain:pqc:v1|" + address + "|" + mnemonic), poi mldsa.keygen(seed) — e conserva il seed insieme alla chiave della hot wallet. La registrazione è esplicita: nulla registra la chiave al posto tuo quando compare per la prima volta una transazione ibrida, e una chiave incorporata in una transazione non è registrata. La chain rifiuta le chiavi classical_only e le chiavi che non offrono alcuna protezione post-quantum (codice 230) e verifica una prova di possesso facoltativa quando ne alleghi una (CLI: register-key-v2 ... --pqc-key; @qorechain/sdk 0.9.0 ne allega una da solo tramite ensurePqcRegistered una volta che la rete ha applicato la v3.2.3, mentre @qorechain/wallet-adapter 0.4.0 no, e ciò è accettato). Imposta il gas in modo esplicito (la chiave da 2.592 byte richiede più dei 200.000 predefiniti; usa --gas 600000 nella CLI, un limite di gas di 600.000 nel codice e una commissione di almeno gas × 0.1 uqor, cioè 60.000 uqor).

Fase 2 — ogni prelievo successivo: firma in modo ibrido il MsgSend. L'adapter incorpora la firma ML-DSA-87 in un'estensione del tx-body prima della normale signDirect secp256k1, così il tuo firmatario esistente rimane invariato:

import { QoreChainSigner } from "@qorechain/wallet-adapter";
import { MsgSend } from "cosmjs-types/cosmos/bank/v1beta1/tx.js";

// pqc = { publicKey, secretKey } from mldsa.keygen(seed)
// accountNumber + sequence from the auth query
const signer = new QoreChainSigner({ wallet, chainId: "qorechain-vladi",
rest: "https://api.qore.host", // used to pick the network's hybrid sign-bytes form (required on mainnet and testnet)
address, pubkeySecp256k1, accountNumber, pqc });
const txBytes = await signer.signHybrid({
messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend",
value: MsgSend.encode(MsgSend.fromPartial({ fromAddress, toAddress,
amount: [{ denom: "uqor", amount: "1000000" }] })).finish() }],
fee: { amount: [{ denom: "uqor", amount: "40000" }], gasLimit: 400000n },
sequence });

Trasmetti i byte firmati:

curl -s -X POST https://api.qore.host/cosmos/tx/v1beta1/txs \
-H 'Content-Type: application/json' \
-d '{"tx_bytes":"<base64-signed-tx>","mode":"BROADCAST_MODE_SYNC"}' | jq .tx_response.code
# 0 => accepted into the mempool
# code 20 "hybrid PQC signature required" => the transaction carries no PQC extension
# (a classical-only transaction is refused; only the key registration itself is exempt)
# code 21 => the PQC half did not verify (wrong key or sign-bytes form), see the troubleshooting link below

Poi esegui polling su GET /cosmos/tx/v1beta1/txs/{hash} finché non compare in un blocco con code == 0.

Per un HSM o un firmatario personalizzato in un altro linguaggio, usa le librerie FIPS-204 standalone qorechain-pqc (npm, PyPI, crates.io, Maven Central, Go) e componi la stessa estensione. La chain accetta qualsiasi firma ML-DSA-87 valida secondo FIPS-204, hedged o deterministica; firmare in modo deterministico (FIPS-204 §3.4, il default delle librerie) ti dà una firma e un hash di tx riproducibili. Vedi Firma deterministica, e Risoluzione del codice 21 se una transazione ibrida viene rifiutata.

Alternativa lato server: @qorechain/chain-bridge​

Per un worker hot-wallet completamente lato server (senza wallet da browser coinvolto), @qorechain/chain-bridge (npm) avvolge l'intero flusso — derivazione della chiave, firma ibrida e broadcast — in un'unica chiamata. È JavaScript puro (nessun componente nativo aggiuntivo), adatto a worker serverless:

import { ChainBridge } from "@qorechain/chain-bridge";

const bridge = new ChainBridge({
cosmosRpc: "https://rpc.qore.host", // or your own node
cosmosRest: "https://api.qore.host", // used to pick the network's hybrid sign-bytes form (required on mainnet and testnet)
chainId: "qorechain-vladi",
signerMnemonic: process.env.HOT_WALLET_MNEMONIC, // from your secrets manager
});

// One call: derives the canonical ML-DSA-87 key, hybrid-signs the MsgSend, and broadcasts.
// Amounts are in uqor (6 decimals). Register the key beforehand with bridge.registerPqc({ mnemonic }).
const { txHash } = await bridge.sendTokens({
to: "qor1recipient...",
amountUqor: "1000000", // 1 QOR
});

Se l'account non ha ancora una chiave registrata, è la libreria stessa a inviare l'esplicita transazione MsgRegisterPQCKeyV2 e a riprovare una volta; è un comportamento della libreria, non della chain, quindi un binario hot-wallet dovrebbe registrare la chiave in anticipo e confermarla (GET /qorechain/pqc/v1/account/{address}) prima del primo prelievo. Da chain-bridge 0.2.3, con cosmosRest impostato, la registrazione include la prova di possesso una volta che la rete ha applicato la v3.2.3, e prima di ogni nuova registrazione la libreria legge la chain: se l'account possiede già una chiave che non è né quella canonica né quella legacy della tua mnemonic, lancia pqc_key_mismatch e non invia nulla (una registrazione ripetuta costa la sua commissione e viene rifiutata). chain-bridge (≥0.1.1) usa la stessa derivazione PQC canonica legata all'indirizzo del resto dello stack — SHAKE-256("qorechain:pqc:v1|address|mnemonic") — quindi la chiave è recuperabile dalla mnemonic con qorechaind tx pqc recover-key. Gli account registrati con strumenti più vecchi sono gestiti automaticamente (fallback su chiave legacy) e possono essere migrati una volta alla chiave canonica con MsgRotatePQCKey.

Percorso B — EVM​

Integrazione Ethereum standard su https://evm.qore.host (chain ID 9801) oppure sulla porta 8545 del tuo nodo.

  • Decimali: QOR nativo ha 18 decimali sul binario EVM (1 uqor = 10¹² wei). Sbagliare questo valore mis-accredita i depositi di un fattore 10¹².
  • Depositi: scansiona i blocchi con eth_getBlockByNumber per i trasferimenti nativi verso i tuoi indirizzi; conferma con eth_getTransactionReceipt (status == 0x1). Anche le transazioni EVM dei depositanti sono soggette alla regola della finestra, quindi un utente il cui account non ha una chiave registrata o una finestra aperta non può inviare un deposito dal canale EVM (può usare invece il canale Cosmos), e una transazione firmata senza chain id (pre-EIP-155) viene rifiutata senza appello. Una finestra può avere un ambito limitato (native_only, allowed_targets), quindi un deposito ammesso è sempre un trasferimento nativo o una chiamata che la finestra consente; leggi comunque la receipt anziché darlo per scontato.
  • Prelievi: firma standard secp256k1 / EIP-155, ma solo da un account con una chiave ML-DSA-87 registrata e una finestra di autorizzazione EVM aperta (dalla v3.2.0; vedi la finestra di autorizzazione EVM e la guida passo-passo in La tua prima transazione). Una transazione al di fuori di una finestra viene rifiutata (codespace pqc, codici 26, 27 o 28). La finestra deve essere aperta con una transazione del canale Cosmos firmata in modo ibrido, quindi il Percorso B non elimina la necessità della firma post-quantum; dimensiona max-value in modo da coprire il valore più la commissione massima (limite di gas × commissione massima per gas) di ogni prelievo previsto all'interno della finestra (per una hot wallet che invia solo QOR semplice, aggiungi --native-only quando la apri), e monitora GET /qorechain/pqc/v1/evm_window/{address} affinché la hot wallet non resti mai a secco a metà batch. Aprire una finestra fa avanzare la sequence dell'account, che è anche il suo nonce EVM, quindi leggi il nonce dopo che la finestra è stata aperta.
  • Anti-falso-deposito: verifica lo status della receipt, che il valore spostato sia un trasferimento nativo (non un evento ERC-20 che non indicizzi) e conferma sul tuo nodo.
  • Mappatura degli indirizzi: l'indirizzo 0x e l'indirizzo qor1 sono due codifiche dello stesso account — i fondi sono condivisi. Vedi Sviluppo EVM.

Percorso C — SVM (compatibile con Solana)​

Canale SVM attualmente disabilitato

Il canale di esecuzione SVM è attualmente disabilitato a livello dell'intera rete per l'invio di transazioni, a partire dalla versione della chain v3.1.89 (22 agosto) — qualsiasi transazione inviata restituisce code 11, "SVM module is disabled". Non costruire un binario di deposito/prelievo sul Percorso C finché il canale non riapre — questa è una disabilitazione decisa in fase di compilazione, non un parametro a runtime, quindi non può essere riattivata con una votazione di governance; ci si aspetta che resti disattivata finché un audit esterno non la libera. Usa invece il Percorso A (Cosmos) o il Percorso B (EVM). Gli endpoint di lettura (ad es. getBalance) potrebbero comunque rispondere, ma non costruire il rilevamento dei depositi o i flussi di prelievo su SVM finché l'invio delle transazioni resta disabilitato.

A partire dalla v3.1.82 l'interfaccia SVM serve QOR nativo (vedi QOR nativo sull'interfaccia SVM):

  • Saldi: getBalance restituisce lamport (÷ 10⁹ per ottenere QOR; 1 uqor = 1.000 lamport).
  • Depositi: getSignaturesForAddress fornisce la cronologia delle transazioni di un indirizzo; i trasferimenti tramite System Program spostano QOR nativo.
  • Gli endpoint pubblici (https://svm.qore.host, https://svm-testnet.qore.host) sono di sola lettura; invia le transazioni tramite il tuo stesso nodo.

Riepilogo del flusso​

OperazionePercorsoServe una firma?
Deposito (utente → piattaforma)Osserva il tuo nodo sincronizzato per i trasferimenti verso il tuo indirizzo (+ memo su Cosmos)No — solo monitoraggio
Prelievo (piattaforma → utente)Costruisci il trasferimento, firma offline, trasmettiCosmos: PQC ibrida · EVM: secp256k1 standard all'interno di una finestra autorizzata PQC
Saldo / sweepQuery del saldo REST / EVM / SVM + trasferimentoFirma solo per lo sweep

Correlati​