Aller au contenu principal

Q-Day Counter

Le Q-Day Counter est le plus petit projet EVM utile sur QoreChain. C'est un contrat Solidity qui stocke un nombre, un projet Hardhat qui le met sur le testnet qorechain-diana, et un court script qui lit ce nombre et lui ajoute un.

Ce guide s'adresse aux débutants. Vous n'avez pas besoin de connaître Solidity ni les outils blockchain. Chaque commande est expliquée, et chaque étape se termine par ce que vous devez voir.

Durée : environ 25 minutes la première fois, dont l'essentiel passe à installer les outils et à attendre le faucet.

Ce que cela démontre​

  • La signature hybride fait partie du chemin de déploiement. Avant toute transaction EVM, y compris le déploiement d'un contrat, le compte a besoin d'une clé post-quantique enregistrée (ML-DSA-87) et d'une fenêtre d'autorisation EVM active. La fenêtre est ouverte par une transaction signée deux fois, avec la clé classique (secp256k1) et avec la clé post-quantique. C'est une signature hybride. La chaîne vérifie les deux.
  • Une transaction signée de façon hybride que vous pouvez vérifier. L'étape pnpm window open envoie cette transaction. Vous pouvez la retrouver dans l'explorateur et y lire le verdict de la chaîne elle-même.
  • Vos outils EVM habituels continuent de fonctionner. Hardhat et viem envoient des transactions Ethereum ordinaires. La protection post-quantique se trouve dans la fenêtre, de sorte qu'une clé secp256k1 volée ne peut pas, à elle seule, dépenser depuis le compte.

Un ordinateur quantique assez grand pour casser secp256k1 pourrait falsifier les signatures classiques. QoreChain exige une seconde signature (ML-DSA-87, standard FIPS 204) qu'un tel ordinateur ne peut pas falsifier. Le Counter montre toute la boucle du développeur avec cette règle activée : enregistrer la clé, ouvrir une fenêtre, déployer, appeler, lire.

Avant de commencer​

Ce guide utilise un compte de testnet jetable. N'utilisez jamais un vrai portefeuille ni de vrais fonds. Les QOR de testnet n'ont aucune valeur.

Il vous faut un terminal. Sur macOS, ouvrez Terminal. Sur Windows, ouvrez PowerShell (ou Git Bash, fourni avec Git). Sous Linux, ouvrez n'importe quel terminal. Installez ensuite ces trois outils. Si la commande de vérification affiche déjà une bonne version, passez l'installation.

Node.js 22 ou plus récent​

Node.js exécute du JavaScript sur votre ordinateur. Hardhat 3 exige Node.js 22 ou plus récent.

SystèmeInstallationVérification
macOSbrew install node (nécessite Homebrew), ou téléchargement sur https://nodejs.orgnode --version
Windowswinget install OpenJS.NodeJS.LTS, ou téléchargement sur https://nodejs.orgnode --version
Linuxcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash, ouvrez un nouveau terminal, puis nvm install 22node --version

Ce que vous devez voir : un nombre qui commence par v22 ou plus, comme v22.12.0. Sur Windows, fermez et rouvrez PowerShell après l'installation.

pnpm​

pnpm télécharge les bibliothèques dont un projet a besoin. Il n'est pas fourni avec Node.js, vous l'ajoutez donc vous-même, sur tous les systèmes.

npm install -g pnpm
ÉlémentSignification
npmL'outil fourni avec Node.js. Il installe d'autres outils.
installTélécharger et installer.
-gGlobal : installer pour tout l'ordinateur, et non pour un seul dossier.
pnpmL'outil à installer.

Vérifiez avec pnpm --version. Vous devez voir un numéro comme 9.12.0 (9 ou plus). Si vous voyez un jour pnpm: command not found, c'est que vous avez sauté cette étape : lancez la commande d'installation ci-dessus, puis ouvrez un nouveau terminal.

Si Linux ou macOS affiche EACCES: permission denied, lancez plutôt sudo npm install -g pnpm.

Git​

Git télécharge le projet depuis GitHub.

SystèmeInstallationVérification
macOSxcode-select --install ou brew install gitgit --version
Windowswinget install Git.Git, ou téléchargement sur https://git-scm.comgit --version
Linuxsudo apt install git (Debian, Ubuntu) ou sudo dnf install git (Fedora)git --version

Ce que vous devez voir : git version 2. suivi d'un nombre.

Un portefeuille de testnet​

Il vous faut un compte de testnet avec un peu de QOR dedans. Ce guide en crée un pour vous dans les étapes suivantes (un fichier de clés). Vous n'avez pas besoin de QoreX pour le Counter. Si vous voulez retrouver ensuite le même compte dans un portefeuille, utilisez QoreX sur le testnet :

  • Application QoreX : Réglages, puis Use testnet (developers).
  • Extension de navigateur QoreX : déverrouillez-la, touchez 7 fois le numéro de version en bas, puis choisissez Switch to testnet (diana).
  • Pour la voie EVM, choisissez Add an Ethereum account (coin 60).

Le faucet donne gratuitement des QOR de testnet : https://dashboard.qorechain.io/faucet. Vous vous connectez, collez une adresse et faites la demande. Vous recevez 100 QOR par 24 heures et par compte.

À propos des montants. QOR est la pièce. uqor est sa plus petite fraction : 1 QOR = 1 000 000 uqor. Les frais sur la chaîne sont affichés en uqor. La première transaction d'un nouveau compte enregistre sa clé post-quantique, ce qui coûte des frais uniques d'environ 0,09 QOR.

Pas à pas​

1. Récupérer le code​

git clone https://github.com/qorechain/build-before-qday
cd build-before-qday/workshop-1/01-qday-counter

Ce que font les commandes

  • git clone <adresse> télécharge une copie du projet depuis GitHub dans un nouveau dossier nommé build-before-qday.
  • cd <dossier> déplace votre terminal dans le dossier du projet Counter. Toutes les commandes suivantes se lancent d'ici.

Ce que vous devez voir : Cloning into 'build-before-qday'..., puis votre invite de commande dans le nouveau dossier. Durée : quelques secondes.

Facultatif : si vous préférez construire le projet à partir de rien, comme dans l'atelier en direct, voyez Construire le même projet de zéro à la fin des étapes.

2. Installer les bibliothèques​

pnpm install

Ce que fait la commande

  • pnpm install lit la liste des bibliothèques dans package.json et les télécharge dans un dossier node_modules (Hardhat, le SDK QoreChain, et d'autres).

Ce que vous devez voir : une liste de paquets avec des signes + et Done in quelques secondes. Durée : moins d'une minute.

3. Lancer les tests et la compilation​

pnpm test

Ce que fait la commande

  • pnpm test lance les vérifications du projet sur une fausse chaîne à l'intérieur de votre ordinateur. Il ne faut ni clé, ni réseau, ni QOR. La première exécution télécharge aussi le compilateur Solidity, il faut donc Internet.

Ce que vous devez voir : Counter, deux lignes avec une coche (starts at the constructor value, increments and emits CountChanged), et 2 passing.

pnpm build

Ce que fait la commande

  • pnpm build transforme le contrat Solidity en code machine (il le compile). Après pnpm test, il affiche No contracts to compile, ce qui est normal : le test l'a déjà compilé.

4. Créer le fichier de réglages​

Le projet lit vos secrets dans un fichier nommé .env. Créez-le à partir du modèle.

macOS, Linux, Git Bash :

cp .env.example .env

Windows PowerShell :

copy .env.example .env

Ce que fait la commande

  • cp (ou copy) copie le fichier modèle .env.example vers un nouveau fichier .env.

Le fichier .env est votre fichier de clés. Il reste uniquement dans le dossier de ce projet. Il contient une clé jetable. Ne le partagez jamais, ne le versionnez jamais dans Git, et ne réutilisez jamais ces clés pour un vrai portefeuille. Le projet ignore déjà .env dans Git. Ouvrez-le dans n'importe quel éditeur de texte (open -e .env sur macOS, notepad .env sur Windows, nano .env sous Linux). Vous allez renseigner deux valeurs.

a. Une clé privée jetable. Générez-en une au hasard :

node -e "console.log('0x' + require('crypto').randomBytes(32).toString('hex'))"

Ce que fait la commande

  • node -e "..." exécute une seule ligne de JavaScript.
  • Cette ligne produit 32 octets aléatoires et les affiche en hexadécimal avec 0x devant. C'est une clé privée.

Ce que vous devez voir : une seule ligne, 0x suivi de 64 lettres et chiffres. Copiez-la dans .env sous la forme PRIVATE_KEY=0x..., en remplaçant la valeur fictive composée de zéros.

b. Un code de récupération post-quantique. La clé ML-DSA-87 du compte est créée à partir d'un second secret, le code de récupération.

pnpm window recovery-code

Ce que fait la commande

  • pnpm window lance le script d'assistance scripts/window.ts. Le mot qui suit est l'action à effectuer.
  • recovery-code affiche un nouveau code de récupération aléatoire.

Ce que vous devez voir : une ligne qui commence par QRC1-, puis un court rappel. Copiez la ligne QRC1-... dans .env sous la forme QORE_PQC_RECOVERY_CODE=QRC1-.... Gardez le même code pour ce compte : un nouveau code donne au compte une autre clé post-quantique.

Laissez QORE_MNEMONIC vide. (Un mnémonique est une phrase de 12 ou 24 mots qui peut remplacer les deux valeurs ci-dessus. Utilisez l'un ou l'autre, pas les deux.) Gardez QORE_NETWORK=testnet, qui indique à l'assistant de dialoguer avec le réseau de test. Votre .env ressemble à ceci, avec des valeurs fictives :

PRIVATE_KEY=0x...
QORE_PQC_RECOVERY_CODE=QRC1-...
QORE_MNEMONIC=
QORE_NETWORK=testnet

Enregistrez le fichier.

5. Afficher l'adresse de votre compte​

pnpm window status

Ce que fait la commande

  • status affiche votre compte, indique si sa clé post-quantique est enregistrée, et si vous avez une fenêtre EVM.

Ce que vous devez voir : trois lignes. La première est account: 0x... (qor1...). Votre compte a deux adresses : 0x... pour l'EVM et qor1... pour la voie native. Elles appartiennent au même compte. Les deux autres lignes indiquent PQC key: not registered et window: none. C'est normal : le compte est neuf. Copiez l'adresse qor1... de la première ligne.

6. Obtenir des QOR de testnet depuis le faucet​

  1. Ouvrez https://dashboard.qorechain.io/faucet et connectez-vous.
  2. Vérifiez que la page est réglée sur Testnet.
  3. Collez votre adresse qor1... et demandez les QOR. Vous recevez 100 QOR une fois toutes les 24 heures par compte.
  4. Attendez environ 10 secondes, puis relancez pnpm window status.

Ce que vous devez voir : les trois mêmes lignes qu'avant : la clé est toujours not registered et il n'y a pas de fenêtre. Le compte contient maintenant des QOR. Si vous voulez une preuve, ouvrez https://explore.qore.network (Testnet) et recherchez votre adresse qor1....

7. Enregistrer la clé et ouvrir la fenêtre​

pnpm window register

Ce que fait la commande

  • register envoie la clé publique ML-DSA-87 du compte à la chaîne. Vous le faites une fois par compte. C'est le seul message que la chaîne accepte sans signature post-quantique, car aucune clé n'est encore enregistrée sur la chaîne pour la vérifier. Cela coûte environ 0,09 QOR.

Ce que vous devez voir : registered: suivi d'un hash de transaction (64 caractères).

pnpm window open

Ce que fait la commande

  • open envoie une transaction, signée avec les deux clés (hybride), qui ouvre une fenêtre d'autorisation EVM. Tant que la fenêtre est active, vos transactions EVM ordinaires sont autorisées. Par défaut, elle dure 600 blocs et autorise 5 transactions. Vous pouvez le modifier avec QORE_WINDOW_BLOCKS et QORE_WINDOW_TXS dans .env.

Ce que vous devez voir : opened: suivi d'un hash de transaction, puis window: 600 blocks, 5 txs, ... uqor (value plus fees). Copiez ce hash. Vous le vérifierez à l'étape 10.

Attendez maintenant environ 10 secondes. L'ouverture de la fenêtre modifie le compteur de transactions du compte, et la commande suivante doit voir la nouvelle valeur.

sleep 10
pnpm window status

Ce que font les commandes

  • sleep 10 attend 10 secondes (cela fonctionne aussi dans PowerShell et Git Bash).
  • status affiche le résultat.

Ce que vous devez voir : PQC key: registered et window: live; ... blocks, ... txs, ... uqor left.

8. Déployer le contrat​

pnpm deploy:testnet

Ce que fait la commande

  • Elle lance Hardhat Ignition, l'outil qui déploie les contrats, avec le module Counter sur le réseau qorechainTestnet (ID de chaîne 9800, le testnet QoreChain).
  • Elle vous demande de confirmer. Tapez y et appuyez sur Entrée.

Ce que vous devez voir : une question de confirmation sur le déploiement vers qorechainTestnet (9800), puis, après votre y, une ligne qui se termine par CounterModule#Counter et l'adresse 0x... de votre contrat. C'est l'adresse de votre contrat. Durée : environ 30 secondes.

9. Lire et incrémenter​

pnpm interact

Ce que fait la commande

  • Elle lit le nombre stocké, appelle increment() (ajoute un), puis le relit. L'appel utilise l'une des 5 transactions de votre fenêtre.

Ce que vous devez voir : Counter 0x... on qorechain-diana EVM (9800), count: 0, increment tx: 0x..., status: success in block ..., count: 1, et un lien vers l'explorateur.

pnpm interact --read

Ce que fait la commande

  • --read signifie lecture seule : elle affiche le nombre et n'envoie rien.

Ce que vous devez voir : l'adresse du Counter et count: 1.

10. Vérifier la transaction hybride​

La transaction de pnpm window open est votre preuve que la chaîne a contrôlé une signature post-quantique. Vérifiez-la de deux façons.

a. Avec la requête web simple. Remplacez <HASH> par le hash de l'étape 7. Retirez les < et >.

curl https://api-testnet.qore.host/cosmos/tx/v1beta1/txs/<HASH>

Ce que fait la commande

  • curl <adresse> demande à un serveur public QoreChain le dossier de cette transaction et l'affiche. Sur Windows PowerShell, tapez curl.exe au lieu de curl.
  • api-testnet.qore.host est le serveur public du testnet. <HASH> est la transaction que vous voulez voir.

Ce que vous devez voir dans la longue réponse :

  • "code": 0, ce qui signifie que la transaction a réussi.
  • Une extension de type PQCHybridSignature qui contient la signature ML-DSA-87, longue de 4 627 octets.
  • Un événement pqc_hybrid_verify dont l'attribut status vaut verified.

b. Avec l'explorateur.

  1. Ouvrez https://explore.qore.network et passez le sélecteur de réseau sur Testnet.
  2. Recherchez le hash de pnpm window open. La page montre une signature post-quantique que la chaîne a vérifiée.
  3. Recherchez le hash increment tx de l'étape 9, ou l'adresse de votre Counter, pour voir l'appel au contrat.

Le Hybrid Inspector montre le même type de preuve octet par octet.

Construire le même projet de zéro​

L'atelier en direct part d'un dossier vide. Cette commande crée le même projet Hardhat (sans le script interact, que seule la copie téléchargée possède). Lancez-la dans un dossier où vous rangez vos projets, à la place de l'étape 1.

npx create-qorechain-dapp@latest qday-demo -t hardhat --network testnet --package-manager pnpm
cd qday-demo
ÉlémentSignification
npxExécute un outil directement depuis Internet, sans l'installer.
create-qorechain-dapp@latestLe créateur de projets QoreChain, dans sa version la plus récente.
qday-demoLe nom du nouveau dossier.
-t hardhatLe modèle de projet à utiliser : un projet Hardhat 3 avec un contrat, des tests et l'assistant de fenêtre.
--network testnetLe réseau QoreChain avec lequel le projet communique : le réseau de test, pas le réseau réel.
--package-manager pnpmL'outil qui installe les bibliothèques.

Ce que vous devez voir : une liste de paquets installés, puis Done! Created qday-demo. Les bibliothèques sont déjà installées et un fichier .env existe déjà : vous pouvez donc sauter l'étape 2 et la copie de l'étape 4. Continuez avec pnpm test (étape 3), puis 4a et 4b (remplir le .env), puis les étapes 5 à 8. Durée : environ 30 secondes.

Ce que vous devez voir à la fin​

  • pnpm test affiche 2 passing.
  • pnpm window status affiche PQC key: registered et window: live avec les blocs, les transactions et la valeur restants.
  • pnpm deploy:testnet affiche l'adresse du Counter déployé (0x...).
  • pnpm interact affiche count qui passe de 0 à 1, status: success, et un lien vers l'explorateur.
  • La vérification avec curl montre "code": 0, l'extension PQCHybridSignature et l'événement pqc_hybrid_verify avec status verified. L'explorateur (Testnet) marque la même transaction comme vérifiée.

Dépannage​

Ce que vous voyezPourquoiQue faire
pnpm: command not foundpnpm n'est pas installé. Node.js ne l'inclut pas.Lancez npm install -g pnpm, puis ouvrez un nouveau terminal.
ERROR: You are using Node.js ... which is not supported by HardhatNode.js est trop ancien.Installez Node.js 22 ou plus récent et vérifiez avec node --version.
node: .env: not foundIl n'y a pas de fichier .env dans ce dossier.Faites l'étape 4, et lancez la commande depuis le dossier du projet.
Set QORE_MNEMONIC, or PRIVATE_KEY as 0x followed by 64 hex characters, in .envLe fichier .env est absent, ou PRIVATE_KEY est encore la valeur fictive ou contient une faute de frappe.Refaites l'étape 4. Enregistrez le fichier. Lancez la commande depuis le dossier du projet.
Set QORE_PQC_RECOVERY_CODE in .env ou not a valid QRC1 recovery codeLe code de récupération est vide ou contient une faute de frappe.Lancez pnpm window recovery-code et collez toute la ligne QRC1-....
... does not exist on chain yet: send it some QOR first (sur register ou open)Le compte n'a pas encore de QOR.Demandez des QOR au faucet (étape 6) et attendez 10 secondes.
Le faucet indique que vous avez atteint la limiteUne demande par 24 heures par compte.Attendez, puis réessayez. Ou utilisez un second compte jetable.
account has no PQC key and classical fallback is disabledVous avez envoyé une transaction avant d'enregistrer la clé.Lancez pnpm window register, puis pnpm window open.
EVM authorisation window exhausted (ou l'indication open an EVM window first)La fenêtre a épuisé ses blocs ou ses transactions, ou elle n'a jamais été ouverte.Lancez pnpm window open, attendez 10 secondes, réessayez.
HHE10402 après l'ouverture de la fenêtreLe déploiement s'est lancé avant la mise à jour du compteur de transactions du compte.Attendez 10 secondes et relancez pnpm deploy:testnet.
Deploy first (pnpm deploy:testnet) or set COUNTER_ADDRESSpnpm interact ne trouve pas le contrat.Terminez l'étape 8 dans ce dossier.
PQC key: registered, but NOT this keyLe code de récupération dans .env diffère de celui utilisé lors de l'enregistrement.Remettez le code de récupération d'origine. Un code différent crée une clé différente.
Erreurs CORS dans une application de navigateurLe serveur REST public n'envoie pas d'en-têtes CORS, donc un navigateur le bloque.Utilisez le proxy /lcd du modèle, comme le fait la page web du Guestbook.

Le code​

Le contrat (contracts/Counter.sol) :

contract Counter {
uint256 public count;
event CountChanged(uint256 newCount);

constructor(uint256 initial) {
count = initial;
emit CountChanged(initial);
}

function increment() external {
count += 1;
emit CountChanged(count);
}

function set(uint256 value) external {
count = value;
emit CountChanged(value);
}
}

La partie signée de façon hybride de scripts/window.ts (le message de fenêtre et le signataire) :

import { EthNativeSigner, openEvmWindowMsg } from "@qorechain/sdk";
import { evmWindowCost } from "@qorechain/evm";

// 3,000,000 gas at a 250 gwei fee cap, for a few deploys
const perTx = evmWindowCost({ gas: 3_000_000n, maxFeePerGas: 250_000_000_000n });
const maxValue = BigInt(process.env.QORE_WINDOW_MAX_UQOR ?? (perTx * maxTxs).toString());
const msg = openEvmWindowMsg({ sender: acc.cosmos, blocks, maxTxs, maxValue });

// broadcast(acc, "hybrid", [msg]) does this:
const signer = new EthNativeSigner(acc, { signMode: "hybrid", rest: net.rest });
const res = await signer.signAndBroadcast(transport, {
chainId: net.chainId, accountNumber, sequence, fee: FEE, messages: [msg],
});

acc est le compte construit à partir de votre matériel de clés, et net est la fiche du réseau désigné par QORE_NETWORK (par défaut testnet, ID de chaîne qorechain-diana). Les frais utilisés par le script sont de 100000 uqor (0,1 QOR) avec une limite de gas de 800000, car les transactions hybrides sont volumineuses.

Paquets utilisés​

PaquetVersionUtilisé pour
@qorechain/sdk^0.13.0Signature hybride, enregistrement de la clé PQC, openEvmWindowMsg
@qorechain/evm^0.13.0Assistants de fenêtre EVM (evmWindowStatus, evmWindowCost)
@cosmjs/stargate^0.39.0Diffusion de la transaction de la voie native
hardhat^3.21.1Compiler, tester, déployer avec Ignition
viem^2.47.6Lire et écrire dans le contrat
tsx^4.19.0Exécuter les scripts TypeScript
typescript^5.6.3Vérification des types

Voir Générateurs et CLI et Installer le SDK.

Détails du réseau​

ÉlémentValeur
Réseautestnet qorechain-diana
ID de chaîne EVM9800
RPChttps://rpc-testnet.qore.host
RESThttps://api-testnet.qore.host
RPC EVMhttps://evm-testnet.qore.host

Source : https://github.com/qorechain/build-before-qday/tree/main/workshop-1/01-qday-counter