Sari la conținutul principal

Hybrid Inspector

Hybrid Inspector este o mică pagină web (construită cu React) care arată cum arată o semnătură hibridă QoreChain pe testnet-ul qorechain-diana. Conectezi portofelul QoreX, trimiți o tranzacție pe care QoreX o semnează atât cu secp256k1, cât și cu ML-DSA-87, iar pagina deschide tranzacția și îți arată: semnătura clasică, semnătura post-cuantică și verdictul lanțului însuși. Poți lipi și orice hash de tranzacție de pe testnet.

Cât durează: aproximativ 20 de minute, cu tot cu instalări. După aceea, pagina rulează în câteva secunde.

Ce demonstrează​

  • Semnare hibridă ML-DSA-87 + secp256k1 dintr-o pagină web. Pagina trimite un mesaj codificat către QoreX cu qorexSignAndBroadcast. QoreX semnează cu ambele chei și transmite tranzacția.
  • O tranzacție semnată hibrid, verificată pe lanț. Pagina citește evenimentul pqc_hybrid_verify al tranzacției. Acel eveniment este lanțul care spune că a verificat semnătura post-cuantică.
  • Dimensiunile se văd. Semnătura clasică are 64 de octeți. Semnătura ML-DSA-87 (FIPS 204) are 4.627 de octeți și circulă în extensia PQCHybridSignature a tranzacției.

Pas cu pas​

Lucrezi în propriul terminal și în browser. Folosești doar un cont de testnet de unică folosință. QOR de testnet nu are valoare. Nu folosi niciodată aici un portofel real sau fonduri reale.

1. Înainte să începi: instalează uneltele​

Ai nevoie de patru lucruri: un browser bazat pe Chromium (Chrome, Edge sau Brave), Git (descarcă codul), Node.js (rulează uneltele paginii) și pnpm (instalează bibliotecile paginii). Folosește Node.js 22 sau mai nou. Pagina funcționează și cu Node.js 20, dar 22 este alegerea sigură pentru toate aplicațiile atelierului.

macOS

UnealtăCum se instaleazăVerifică
Gitxcode-select --install (sau brew install git)git --version
Node.js 22+Descarcă instalatorul LTS de la https://nodejs.org sau rulează brew install nodenode --version (trebuie să afișeze v22 sau mai mare)
pnpmnpm install -g pnpmpnpm --version

Windows (folosește PowerShell)

UnealtăCum se instaleazăVerifică
GitDescarcă de la https://git-scm.com/download/wingit --version
Node.js 22+Descarcă instalatorul LTS de la https://nodejs.org (sau winget install OpenJS.NodeJS.LTS)node --version
pnpmnpm install -g pnpmpnpm --version

Linux (Debian sau Ubuntu)

UnealtăCum se instaleazăVerifică
Gitsudo apt update && sudo apt install -y git curlgit --version
Node.js 22+Urmează https://nodejs.org/en/download (alege Linux, apoi versiunea LTS)node --version
pnpmnpm install -g pnpmpnpm --version

Capcană: Node.js instalat cu Homebrew nu include pnpm. Dacă vezi pnpm: command not found, rulează npm install -g pnpm, apoi deschide un terminal nou.

Ce ar trebui să vezi: fiecare comandă de verificare afișează un număr de versiune. node --version începe cu v22 sau mai mare.

2. Înainte să începi: QoreX pe testnet​

QoreX este portofelul oficial QoreChain. Această pagină are nevoie de extensia de browser QoreX în browserul în care deschizi pagina. Instaleaz-o din magazinul browserului tău. Vezi Integrări QoreX și browserul de dApp-uri.

Folosește un cont nou, de unică folosință, creat doar pentru acest exercițiu. QoreX afișează o frază de recuperare când creează contul. Scrie-o pe hârtie, ține-o privată și nu o reutiliza niciodată pe mainnet.

Comută QoreX pe testnet:

  • Extensia de browser: deblocheaz-o, atinge de 7 ori numărul versiunii din partea de jos, apoi alege Switch to testnet (diana).
  • Aplicația QoreX: deschide Setări și activează Use testnet (developers). (Pagina rulează într-un browser de desktop, așa că în acest tutorial folosești extensia.)

Vezi Deploy în 5 minute pentru mai multe detalii despre comutarea pe testnet. Copiază adresa contului tău (începe cu qor1...).

Nu ai nevoie de un cont Ethereum (coin 60) pentru această pagină, deoarece ea trimite o plată QoreChain Native.

3. Ia QOR de testnet de la faucet​

Faucet-ul este un site care trimite QOR de testnet gratuit către o adresă.

  1. Deschide https://dashboard.qorechain.io/faucet și autentifică-te.
  2. Lipește adresa ta qor1... și cere fonduri. Faucet-ul oferă 100 QOR la fiecare 24 de ore pentru fiecare cont.

Sume: unitatea pe care o citești este QOR. Lanțul numără în uqor, cea mai mică unitate. 1 QOR = 1.000.000 uqor. Pagina cere QOR și face conversia pentru tine.

Bine de știut: prima tranzacție a unui cont nou înregistrează pe lanț cheia sa post-cuantică ML-DSA-87. Este o taxă unică de aproximativ 0,09 QOR. QoreX o face pentru tine la prima trimitere.

4. Ia codul​

git clone https://github.com/qorechain/build-before-qday
cd build-before-qday/workshop-1/03-hybrid-inspector
ParteCe înseamnă
git clone <adresă>Descarcă de pe GitHub o copie completă a aplicațiilor-exemplu într-un folder nou numit build-before-qday.
cd <folder>Mută terminalul în folderul Hybrid Inspector. Toate comenzile următoare se rulează de aici.

Ce ar trebui să vezi: Cloning into 'build-before-qday'.... Rulează ls ca să verifici: vezi package.json, src, index.html și vite.config.ts.

5. Instalează bibliotecile​

pnpm install

Ce face: pnpm descarcă bibliotecile de care are nevoie pagina (listate în package.json) într-un folder numit node_modules. Îl rulezi o singură dată pentru fiecare proiect.

ParteCe înseamnă
pnpmUnealta care instalează bibliotecile.
installCitește package.json și instalează tot ce este listat acolo, la versiunile din pnpm-lock.yaml.

Cât durează: sub un minut.

Ce ar trebui să vezi: o bară de progres, apoi Done in și un timp.

6. Verifică dacă se construiește​

pnpm build

Ce face: rulează scriptul numit build din package.json. Acel script este tsc --noEmit && vite build.

ParteCe înseamnă
pnpm buildRulează scriptul build al proiectului.
tsc --noEmitVerificatorul TypeScript. Caută greșeli în cod și nu scrie niciun fișier.
vite buildVite împachetează pagina într-un mic site web, în folderul dist.

Ce ar trebui să vezi: transforming..., apoi linii precum dist/index.html și, în final, built in cu un timp (sub o secundă).

7. Rulează pagina​

pnpm dev

Ce face: rulează scriptul dev, care pornește un mic server web pe propriul tău calculator, ca să poți folosi pagina în browser. Lasă acest terminal deschis cât lucrezi. Apasă Ctrl+C ca să-l oprești.

Ce ar trebui să vezi:

VITE v5.4.21 ready in 111 ms

➜ Local: http://localhost:5173/

Deschide http://localhost:5173 în browserul în care este instalat QoreX. Dacă portul 5173 este ocupat, Vite afișează alt port. Folosește adresa afișată.

Ca să inspectezi direct o tranzacție, adaugă ?tx=<HASH> la adresă: http://localhost:5173?tx=<HASH>.

De ce apelează pagina /lcd: serviciul REST public de testnet nu trimite antete CORS, deci o pagină din browser nu îl poate apela direct. Serverul de dezvoltare redirecționează fiecare apel de la /lcd către https://api-testnet.qore.host. Pagina funcționează doar pe testnet și nu ai nevoie de niciun fișier .env.

8. Conectează, trimite și verifică​

  1. Conectează. Apasă Connect QoreX. QoreX îți cere să permiți pagina. Aprobă. Pagina arată adresa ta (qor1...), soldul tău de testnet și dacă o cheie ML-DSA-87 este înregistrată. Până la prima trimitere scrie "not registered yet".
  2. Completează formularul de trimitere.
CâmpCe înseamnă
ToAdresa destinatarului (qor1...). Implicit este completată cu propria ta adresă, ceea ce e în regulă.
Amount (QOR)Cât trimiți, în QOR. 1 înseamnă 1 QOR = 1.000.000 uqor.
MemoUn text scurt atașat tranzacției și stocat pe lanț. Oricine îl poate citi, așa că nu scrie nimic privat.
  1. Trimite. Apasă Sign with QoreX and send. QoreX arată ce semnezi și cere aprobarea. Aprobă. Așteaptă blocul (câteva secunde).
  2. Inspectează. Pagina inspectează tranzacția automat. Poți lipi și orice hash de tranzacție de testnet de 64 de caractere la pasul 3 al paginii și apăsa Inspect.

Ce ar trebui să vezi: o linie QoreX: code 0, shield ..., tx <hash>, apoi cardul de inspecție descris în "Ce ar trebui să vezi" mai jos. Copiază hash-ul tranzacției.

9. Verific-o și într-un al doilea mod, fără pagină​

Poți întreba direct lanțul. Ai nevoie doar de curl, inclus în macOS și în majoritatea sistemelor Linux. În Windows PowerShell folosește curl.exe. Unealta jq este opțională și face răspunsul mai ușor de citit (brew install jq pe macOS, sudo apt install -y jq pe Linux, winget install jqlang.jq pe 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)'
ParteCe înseamnă
curl -s <adresă>Descarcă răspunsul de la serviciul REST de testnet. -s ascunde bara de progres.
<HASH>Hash-ul tranzacției tale, de la pasul 8.
| jq '...'Extrage trei valori. Fără jq, renunță la această parte și citește textul complet.

Ce ar trebui să vezi:

  • code este 0: tranzacția a reușit.
  • O extensie PQCHybridSignature (tip /qorechain.pqc.v1.PQCHybridSignature) cu un pqc_signature. Textul său base64 are 6.172 de caractere, adică 4.627 de octeți de semnătură ML-DSA-87.
  • În tx_response.events, un eveniment de tip pqc_hybrid_verify cu atributul status setat la verified.

În explorer: deschide https://explore.qore.network, comută-l pe Testnet și caută hash-ul tranzacției tale.

Depanare​

Ce veziDe ceCe faci
pnpm: command not foundpnpm nu este instalat. Node.js de la Homebrew nu îl include.Rulează npm install -g pnpm, apoi deschide un terminal nou.
node --version arată v18 sau mai micNode.js este prea vechi.Instalează Node.js 22 sau mai nou (pasul 1).
Pagina spune QoreX was not found in this page. Install the QoreX extension, switch it to testnet, and reload.Extensia lipsește, este blocată sau browserul nu este bazat pe Chromium.Instalează și deblochează QoreX în Chrome, Edge sau Brave. Comută pe testnet, apoi reîncarcă pagina.
Faucet-ul spune că ai atins o limită de cereriO cerere la 24 de ore pentru fiecare cont.Așteaptă 24 de ore sau folosește un al doilea cont de unică folosință.
account has no PQC key and classical fallback is disabledCheia post-cuantică nu este încă înregistrată.Trimite o dată din QoreX (înregistrează cheia la prima trimitere, aproximativ 0,09 QOR). Asigură-te că ai mai întâi QOR de la faucet.
EVM authorisation window exhaustedAparține aplicației Hardhat, nu acestei pagini.În acea aplicație, deschide o fereastră nouă cu pnpm window open.
HHE10402 după deschiderea ferestreiAparține aplicației Hardhat. Fereastra are nevoie de câteva secunde.Rulează din nou deploy-ul.
Eroare CORS în consola browseruluiPagina a apelat direct serviciul REST.Folosește proxy-ul /lcd al serverului de dezvoltare (pnpm dev) și deschide pagina la http://localhost:5173. Nu deschide dist/index.html ca fișier.
Enter an amount in QOR, for example 1.Suma este goală, zero sau nu este un număr.Scrie un număr, de exemplu 1.
A transaction hash is 64 hex characters.Hash-ul lipit este greșit sau tăiat.Lipește toate cele 64 de caractere.
Transaction not found on qorechain-dianaHash-ul este din altă rețea sau blocul nu este încă final.Așteaptă 10 secunde și încearcă din nou. Verifică dacă QoreX este pe testnet.
Portul 5173 este deja folositAlt program îl folosește.Vite alege următorul port și îl afișează. Deschide acea adresă.

Codul​

Conectarea și trimiterea:

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

Citirea dovezii de pe lanț:

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 este un mic codificator protobuf din src/App.tsx pentru mesajul bancar MsgSend, deoarece QoreX primește mesajul codificat. Pagina marchează o tranzacție ca verificată hibrid când codul ei este 0, un eveniment pqc_hybrid_verify are statusul verified, iar semnătura post-cuantică are 4.627 de octeți.

Ce ar trebui să vezi​

  • Antetul arată qorechain-diana (testnet) și o înălțime de bloc care tot crește.
  • După conectare: adresa ta, soldul și starea cheii.
  • După trimitere: hash-ul tranzacției și codul rezultatului, apoi cardul de inspecție cu memo-ul, tipul mesajului, semnătura clasică de 64 de octeți, semnătura ML-DSA-87 de 4.627 de octeți cu primii ei octeți în hex, numele algoritmului ML-DSA-87 (FIPS 204) și verdictul pqc_hybrid_verify.
  • În explorer: deschide https://explore.qore.network, comută-l pe Testnet și caută hash-ul tranzacției tale.

Pachete folosite​

PachetVersiuneFolosit pentru
@qorechain/qorex-types0.1.0 (fixată)getQorexNative, qorexSignAndBroadcast
@qorechain/sdk^0.13.0Listat ca dependență; pagina în sine folosește apeluri REST simple
react, react-dom^18.3.1Interfață
@vitejs/plugin-react^4.3.0Plugin Vite pentru React
vite^5.4.0Server de dezvoltare și build
typescript^5.6.3Verificarea tipurilor

Cod sursă​

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