Passa al contenuto principale

Hybrid Inspector

L'Hybrid Inspector è una piccola pagina web (costruita con React) che mostra com'è fatta una firma ibrida di QoreChain sulla testnet qorechain-diana. Colleghi il wallet QoreX, invii una transazione che QoreX firma sia con secp256k1 sia con ML-DSA-87, e la pagina la apre e la mostra pezzo per pezzo: la firma classica, la firma post-quantistica e il verdetto della catena stessa. Puoi anche incollare l'hash di qualsiasi transazione della testnet.

Quanto ci vuole: circa 20 minuti, installazioni comprese. Dopo, la pagina parte in pochi secondi.

Cosa mostra​

  • Firma ibrida ML-DSA-87 + secp256k1 da una pagina web. La pagina passa a QoreX un messaggio codificato con qorexSignAndBroadcast. QoreX firma con entrambe le chiavi e trasmette.
  • Una transazione firmata in modo ibrido, verificata on chain. La pagina legge l'evento pqc_hybrid_verify della catena per quella transazione. Quell'evento è la catena che dichiara di aver controllato la firma post-quantistica.
  • Le dimensioni si vedono. La firma classica è di 64 byte. La firma ML-DSA-87 (FIPS 204) è di 4.627 byte e viaggia nell'estensione PQCHybridSignature della transazione.

Passo dopo passo​

Lavori nel tuo terminale e nel tuo browser. Usa solo un account di testnet usa e getta. Il QOR di testnet non ha alcun valore. Non usare mai un wallet reale né fondi reali qui.

1. Prima di iniziare: installa gli strumenti​

Servono quattro cose: un browser basato su Chromium (Chrome, Edge o Brave), Git (scarica il codice), Node.js (esegue gli strumenti della pagina) e pnpm (installa le librerie della pagina). Usa Node.js 22 o successivo. La pagina funziona anche da Node.js 20, ma 22 è la scelta sicura per tutte le app del workshop.

macOS

StrumentoCome installarloCome verificarlo
Gitxcode-select --install (oppure brew install git)git --version
Node.js 22+Scarica l'installer LTS da https://nodejs.org, oppure esegui brew install nodenode --version (deve mostrare v22 o superiore)
pnpmnpm install -g pnpmpnpm --version

Windows (usa PowerShell)

StrumentoCome installarloCome verificarlo
GitScarica da https://git-scm.com/download/wingit --version
Node.js 22+Scarica l'installer LTS da https://nodejs.org (oppure winget install OpenJS.NodeJS.LTS)node --version
pnpmnpm install -g pnpmpnpm --version

Linux (Debian o Ubuntu)

StrumentoCome installarloCome verificarlo
Gitsudo apt update && sudo apt install -y git curlgit --version
Node.js 22+Segui https://nodejs.org/en/download (scegli Linux, poi la versione LTS)node --version
pnpmnpm install -g pnpmpnpm --version

Attenzione: Node.js installato con Homebrew non include pnpm. Se vedi pnpm: command not found, esegui npm install -g pnpm, poi apri un nuovo terminale.

Cosa dovresti vedere: ogni comando di verifica stampa un numero di versione. node --version inizia con v22 o un numero più alto.

2. Prima di iniziare: QoreX sulla testnet​

QoreX è il wallet ufficiale di QoreChain. Questa pagina richiede l'estensione del browser QoreX nel browser in cui apri la pagina. Installala dallo store del tuo browser. Vedi Integrazioni QoreX e il browser dApp.

Usa un nuovo account usa e getta creato solo per questo esercizio. QoreX mostra una frase di recupero quando crea l'account. Scrivila su carta, tienila privata e non riutilizzarla mai sulla mainnet.

Passa QoreX alla testnet:

  • Estensione del browser: sbloccala, tocca 7 volte il numero di versione in basso, poi scegli Switch to testnet (diana).
  • App QoreX: apri Impostazioni e attiva Use testnet (developers). (La pagina gira in un browser desktop, quindi per questo tutorial usi l'estensione.)

Vedi Deploy in 5 minuti per approfondire il passaggio alla testnet. Copia l'indirizzo del tuo account (inizia con qor1...).

Per questa pagina non ti serve un account Ethereum (coin 60), perché invia un pagamento QoreChain Native.

3. Ottieni QOR di testnet dal faucet​

Il faucet è un sito web che invia QOR di testnet gratuiti a un indirizzo.

  1. Apri https://dashboard.qorechain.io/faucet e accedi.
  2. Incolla il tuo indirizzo qor1... e fai la richiesta. Il faucet eroga 100 QOR ogni 24 ore per account.

Importi: l'unità che leggi è il QOR. La catena conta in uqor, l'unità più piccola. 1 QOR = 1.000.000 uqor. La pagina chiede QOR e fa la conversione per te.

Da sapere: la primissima transazione di un nuovo account registra on chain la sua chiave post-quantistica ML-DSA-87. È una commissione una tantum di circa 0,09 QOR. QoreX lo fa per te al primo invio.

4. Scarica il codice​

git clone https://github.com/qorechain/build-before-qday
cd build-before-qday/workshop-1/03-hybrid-inspector
ParteSignificato
git clone <indirizzo>Scarica da GitHub una copia completa delle app di esempio in una nuova cartella chiamata build-before-qday.
cd <cartella>Sposta il terminale nella cartella dell'Hybrid Inspector. Tutti i comandi successivi si eseguono da qui.

Cosa dovresti vedere: Cloning into 'build-before-qday'.... Esegui ls per controllare: vedi package.json, src, index.html e vite.config.ts.

5. Installa le librerie​

pnpm install

Cosa fa: pnpm scarica le librerie di cui la pagina ha bisogno (elencate in package.json) in una cartella chiamata node_modules. Lo esegui una sola volta per progetto.

ParteSignificato
pnpmLo strumento che installa le librerie.
installLegge package.json e installa tutto ciò che elenca, alle versioni indicate in pnpm-lock.yaml.

Quanto ci vuole: meno di un minuto.

Cosa dovresti vedere: una barra di avanzamento e poi Done in con un tempo.

6. Controlla che compili​

pnpm build

Cosa fa: esegue lo script chiamato build di package.json. Quello script è tsc --noEmit && vite build.

ParteSignificato
pnpm buildEsegue lo script build del progetto.
tsc --noEmitIl controllo di TypeScript. Cerca errori nel codice e non scrive alcun file.
vite buildVite impacchetta la pagina in un piccolo sito web nella cartella dist.

Cosa dovresti vedere: transforming..., poi righe come dist/index.html, e infine built in con un tempo (ben sotto il secondo).

7. Avvia la pagina​

pnpm dev

Cosa fa: esegue lo script dev, che avvia un piccolo server web sul tuo computer così puoi usare la pagina nel browser. Lascia aperto questo terminale mentre lavori. Premi Ctrl+C per fermarlo.

Cosa dovresti vedere:

VITE v5.4.21 ready in 111 ms

➜ Local: http://localhost:5173/

Apri http://localhost:5173 nel browser in cui è installato QoreX. Se la porta 5173 è occupata, Vite stampa l'altra porta. Usa l'indirizzo che stampa.

Per ispezionare direttamente una transazione, aggiungi ?tx=<HASH> all'indirizzo: http://localhost:5173?tx=<HASH>.

Perché la pagina chiama /lcd: il servizio REST pubblico della testnet non invia header CORS, quindi una pagina del browser non può chiamarlo direttamente. Il server di sviluppo inoltra ogni chiamata da /lcd a https://api-testnet.qore.host. La pagina funziona solo sulla testnet e non serve alcun file .env.

8. Collega, invia e verifica​

  1. Collega. Fai clic su Connect QoreX. QoreX ti chiede di autorizzare la pagina. Approva. La pagina mostra il tuo indirizzo (qor1...), il tuo saldo di testnet e se è registrata una chiave ML-DSA-87. Dice "not registered yet" finché non fai il primo invio.
  2. Compila il modulo di invio.
CampoSignificato
ToL'indirizzo del destinatario (qor1...). Per impostazione predefinita è compilato con il tuo stesso indirizzo, e va bene così.
Amount (QOR)Quanto inviare, in QOR. 1 significa 1 QOR = 1.000.000 uqor.
MemoUn breve testo allegato alla transazione e salvato on chain. Chiunque può leggerlo, quindi non scrivere nulla di privato.
  1. Invia. Fai clic su Sign with QoreX and send. QoreX mostra cosa stai firmando e chiede l'approvazione. Approva. Aspetta il blocco (qualche secondo).
  2. Ispeziona. La pagina ispeziona la transazione in automatico. Puoi anche incollare l'hash di qualsiasi transazione di testnet di 64 caratteri nel passaggio 3 della pagina e fare clic su Inspect.

Cosa dovresti vedere: una riga QoreX: code 0, shield ..., tx <hash>, poi la scheda di ispezione descritta in "Cosa dovresti vedere" più sotto. Copia l'hash della transazione.

9. Verificalo in un secondo modo, senza la pagina​

Puoi chiedere direttamente alla catena. Ti serve solo curl, incluso in macOS e nella maggior parte dei sistemi Linux. In PowerShell su Windows usa curl.exe. Lo strumento jq è facoltativo e rende la risposta più leggibile (brew install jq su macOS, sudo apt install -y jq su Linux, winget install jqlang.jq su Windows).

curl -s https://api-testnet.qore.host/cosmos/tx/v1beta1/txs/<HASH> | jq '.tx_response.code, .tx.body.extension_options[0]["@type"], (.tx.body.extension_options[0].pqc_signature | length)'
ParteSignificato
curl -s <indirizzo>Scarica la risposta dal servizio REST della testnet. -s nasconde la barra di avanzamento.
<HASH>L'hash della tua transazione, dal passaggio 8.
| jq '...'Estrae tre valori. Senza jq, togli questa parte e leggi il testo completo.

Cosa dovresti vedere:

  • code è 0: la transazione è riuscita.
  • Un'estensione PQCHybridSignature (tipo /qorechain.pqc.v1.PQCHybridSignature) con una pqc_signature. Il suo testo base64 è lungo 6.172 caratteri, cioè 4.627 byte di firma ML-DSA-87.
  • In tx_response.events, un evento di tipo pqc_hybrid_verify con l'attributo status impostato su verified.

Nell'explorer: apri https://explore.qore.network, passa a Testnet e cerca l'hash della tua transazione.

Risoluzione dei problemi​

Cosa vediPerchéCosa fare
pnpm: command not foundpnpm non è installato. Node.js di Homebrew non lo include.Esegui npm install -g pnpm, poi apri un nuovo terminale.
node --version mostra v18 o inferioreNode.js è troppo vecchio.Installa Node.js 22 o successivo (passaggio 1).
La pagina dice QoreX was not found in this page. Install the QoreX extension, switch it to testnet, and reload.L'estensione manca, è bloccata, oppure il browser non è basato su Chromium.Installa e sblocca QoreX in Chrome, Edge o Brave. Passa alla testnet, poi ricarica la pagina.
Il faucet dice che hai raggiunto il limite di richiesteUna richiesta ogni 24 ore per account.Aspetta 24 ore, oppure usa un secondo account usa e getta.
account has no PQC key and classical fallback is disabledLa chiave post-quantistica non è ancora registrata.Fai un invio da QoreX (registra la chiave al primo invio, circa 0,09 QOR). Assicurati prima di avere QOR dal faucet.
EVM authorisation window exhaustedRiguarda l'app Hardhat, non questa pagina.In quell'app, apri una nuova finestra con pnpm window open.
HHE10402 dopo l'apertura della finestraRiguarda l'app Hardhat. La finestra ha bisogno di qualche secondo.Esegui di nuovo il deploy.
Errore CORS nella console del browserLa pagina ha chiamato direttamente il servizio REST.Usa il proxy /lcd del server di sviluppo (pnpm dev) e apri la pagina su http://localhost:5173. Non aprire dist/index.html come file.
Enter an amount in QOR, for example 1.L'importo è vuoto, zero o non è un numero.Scrivi un numero, per esempio 1.
A transaction hash is 64 hex characters.L'hash incollato è sbagliato o tagliato.Incolla tutti i 64 caratteri.
Transaction not found on qorechain-dianaL'hash appartiene a un'altra rete, oppure il blocco non è ancora finale.Aspetta 10 secondi e riprova. Controlla che QoreX sia sulla testnet.
La porta 5173 è già in usoUn altro programma la usa.Vite sceglie la porta successiva e la stampa. Apri quell'indirizzo.

Il codice​

Collegare e inviare:

import { getQorexNative, qorexSignAndBroadcast } from "@qorechain/qorex-types";

const native = getQorexNative();
await native.enable("qorechain-diana");
const key = await native.getKey("qorechain-diana"); // key.bech32Address

const r = await qorexSignAndBroadcast({
chainId: "qorechain-diana",
messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend", value: msgSendBytes(from, to, uqor) }],
memo,
}); // r.txHash, r.code, r.shield

Leggere la prova dalla catena:

const res = await fetch(`/lcd/cosmos/tx/v1beta1/txs/${hash}`).then((r) => r.json());
const tx = res.tx;
const ext = [...(tx.body.extension_options ?? []), ...(tx.body.non_critical_extension_options ?? [])];
const hyb = ext.find((x) => String(x["@type"]).includes("PQCHybridSignature"));
const verify = (res.tx_response.events ?? []).filter((e) => e.type === "pqc_hybrid_verify");
// classical signature: atob(tx.signatures[0]).length -> 64
// ML-DSA-87 signature: atob(hyb.pqc_signature).length -> 4627

msgSendBytes è un piccolo codificatore protobuf in src/App.tsx per il messaggio bancario MsgSend, perché QoreX riceve il messaggio già codificato. La pagina segna una transazione come verificata in modo ibrido quando il suo codice è 0, un evento pqc_hybrid_verify ha stato verified e la firma post-quantistica è di 4.627 byte.

Cosa dovresti vedere​

  • L'intestazione mostra qorechain-diana (testnet) e un'altezza di blocco che continua a crescere.
  • Dopo il collegamento: il tuo indirizzo, il saldo e lo stato della chiave.
  • Dopo l'invio: l'hash della transazione e il codice di risultato, poi la scheda di ispezione con il memo, il tipo di messaggio, la firma classica di 64 byte, la firma ML-DSA-87 di 4.627 byte con i suoi primi byte in esadecimale, il nome dell'algoritmo ML-DSA-87 (FIPS 204) e il verdetto pqc_hybrid_verify.
  • Sull'explorer: apri https://explore.qore.network, passa a Testnet e cerca l'hash della tua transazione.

Pacchetti usati​

PacchettoVersioneUsato per
@qorechain/qorex-types0.1.0 (fissata)getQorexNative, qorexSignAndBroadcast
@qorechain/sdk^0.13.0Elencato come dipendenza; la pagina stessa usa semplici chiamate REST
react, react-dom^18.3.1Interfaccia
@vitejs/plugin-react^4.3.0Plugin React per Vite
vite^5.4.0Server di sviluppo e build
typescript^5.6.3Controllo dei tipi

Codice sorgente​

https://github.com/qorechain/build-before-qday/tree/main/workshop-1/03-hybrid-inspector