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 openenvoie 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ème | Installation | Vérification |
|---|---|---|
| macOS | brew install node (nécessite Homebrew), ou téléchargement sur https://nodejs.org | node --version |
| Windows | winget install OpenJS.NodeJS.LTS, ou téléchargement sur https://nodejs.org | node --version |
| Linux | curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash, ouvrez un nouveau terminal, puis nvm install 22 | node --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ément | Signification |
|---|---|
npm | L'outil fourni avec Node.js. Il installe d'autres outils. |
install | Télécharger et installer. |
-g | Global : installer pour tout l'ordinateur, et non pour un seul dossier. |
pnpm | L'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ème | Installation | Vérification |
|---|---|---|
| macOS | xcode-select --install ou brew install git | git --version |
| Windows | winget install Git.Git, ou téléchargement sur https://git-scm.com | git --version |
| Linux | sudo 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 installlit la liste des bibliothèques danspackage.jsonet les télécharge dans un dossiernode_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 testlance 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 buildtransforme le contrat Solidity en code machine (il le compile). Aprèspnpm test, il afficheNo 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(oucopy) copie le fichier modèle.env.examplevers 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
0xdevant. 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 windowlance le script d'assistancescripts/window.ts. Le mot qui suit est l'action à effectuer.recovery-codeaffiche 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
statusaffiche 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
- Ouvrez https://dashboard.qorechain.io/faucet et connectez-vous.
- Vérifiez que la page est réglée sur Testnet.
- Collez votre adresse
qor1...et demandez les QOR. Vous recevez 100 QOR une fois toutes les 24 heures par compte. - 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
registerenvoie 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
openenvoie 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 avecQORE_WINDOW_BLOCKSetQORE_WINDOW_TXSdans.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 10attend 10 secondes (cela fonctionne aussi dans PowerShell et Git Bash).statusaffiche 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
Countersur le réseauqorechainTestnet(ID de chaîne 9800, le testnet QoreChain). - Elle vous demande de confirmer. Tapez
yet 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
--readsignifie 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, tapezcurl.exeau lieu decurl.api-testnet.qore.hostest 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
PQCHybridSignaturequi contient la signature ML-DSA-87, longue de 4 627 octets. - Un événement
pqc_hybrid_verifydont l'attributstatusvautverified.
b. Avec l'explorateur.
- Ouvrez https://explore.qore.network et passez le sélecteur de réseau sur Testnet.
- Recherchez le hash de
pnpm window open. La page montre une signature post-quantique que la chaîne a vérifiée. - Recherchez le hash
increment txde 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ément | Signification |
|---|---|
npx | Exécute un outil directement depuis Internet, sans l'installer. |
create-qorechain-dapp@latest | Le créateur de projets QoreChain, dans sa version la plus récente. |
qday-demo | Le nom du nouveau dossier. |
-t hardhat | Le modèle de projet à utiliser : un projet Hardhat 3 avec un contrat, des tests et l'assistant de fenêtre. |
--network testnet | Le réseau QoreChain avec lequel le projet communique : le réseau de test, pas le réseau réel. |
--package-manager pnpm | L'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 testaffiche2 passing.pnpm window statusaffichePQC key: registeredetwindow: liveavec les blocs, les transactions et la valeur restants.pnpm deploy:testnetaffiche l'adresse duCounterdéployé (0x...).pnpm interactaffichecountqui passe de 0 à 1,status: success, et un lien vers l'explorateur.- La vérification avec
curlmontre"code": 0, l'extensionPQCHybridSignatureet l'événementpqc_hybrid_verifyavecstatusverified. L'explorateur (Testnet) marque la même transaction comme vérifiée.
Dépannage
| Ce que vous voyez | Pourquoi | Que faire |
|---|---|---|
pnpm: command not found | pnpm 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 Hardhat | Node.js est trop ancien. | Installez Node.js 22 ou plus récent et vérifiez avec node --version. |
node: .env: not found | Il 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 .env | Le 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 code | Le 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 limite | Une 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 disabled | Vous 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être | Le 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_ADDRESS | pnpm interact ne trouve pas le contrat. | Terminez l'étape 8 dans ce dossier. |
PQC key: registered, but NOT this key | Le 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 navigateur | Le 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
| Paquet | Version | Utilisé pour |
|---|---|---|
@qorechain/sdk | ^0.13.0 | Signature hybride, enregistrement de la clé PQC, openEvmWindowMsg |
@qorechain/evm | ^0.13.0 | Assistants de fenêtre EVM (evmWindowStatus, evmWindowCost) |
@cosmjs/stargate | ^0.39.0 | Diffusion de la transaction de la voie native |
hardhat | ^3.21.1 | Compiler, tester, déployer avec Ignition |
viem | ^2.47.6 | Lire et écrire dans le contrat |
tsx | ^4.19.0 | Exécuter les scripts TypeScript |
typescript | ^5.6.3 | Vérification des types |
Voir Générateurs et CLI et Installer le SDK.
Détails du réseau
| Élément | Valeur |
|---|---|
| Réseau | testnet qorechain-diana |
| ID de chaîne EVM | 9800 |
| RPC | https://rpc-testnet.qore.host |
| REST | https://api-testnet.qore.host |
| RPC EVM | https://evm-testnet.qore.host |
Source : https://github.com/qorechain/build-before-qday/tree/main/workshop-1/01-qday-counter