Blockchain locale

En développement et en CI, les contrats tournent sur un nœud Hardhat local, avec un coordinateur Chainlink VRF simulé et un petit oracle qui répond aux demandes de tirage. Le backend s'y connecte sans aucune configuration : les adresses des contrats sont déterministes et correspondent à ses valeurs par défaut. Cette page décrit le nœud, le script de déploiement, l'oracle, l'image Docker et les variables. Le démarrage de toute l'infrastructure locale est décrit dans Infrastructure locale.

#Vue d'ensemble

flowchart LR
    subgraph conteneur["Conteneur blockchain"]
        node["hardhat node, port 8545"]
        deploy["deploy-local.ts"]
        oracle["local-vrf-responder.ts, compte 9"]
    end
    deploy -->|"déploie mock VRF, BlockLucky, POAP"| node
    oracle -->|"lit RandomWordsRequested, appelle fulfillRandomWords"| node
    backend["Backend, compte opérateur"] -->|"RPC_URL"| node

#Démarrer

#Avec Docker

Le service blockchain de docker-compose.yml construit l'image de smart-contract/Dockerfile et publie le port sur 127.0.0.1:8545 uniquement.

docker compose up -d --wait blockchain

--wait attend que le conteneur soit sain, c'est-à-dire que les contrats soient déployés.

#Sans Docker

Dans un premier terminal, depuis smart-contract/ :

npm run node

Dans un second terminal, une fois le nœud prêt :

npm run deploy:local && npx hardhat run scripts/local-vrf-responder.ts --network localhost

L'oracle tourne au premier plan tant que le terminal reste ouvert. Sans lui, les tours restent en Drawing après la demande de tirage.

#Le nœud Hardhat

hardhat node lance un réseau Ethereum en mémoire, au chain ID 31337, avec 20 comptes dérivés de la phrase mnémonique publique de développement de Hardhat, chacun approvisionné en ethers fictifs. Un bloc est produit à chaque transaction.

La clé privée du compte 0 est la valeur par défaut de RELAYER_PRIVATE_KEY dans backend/src/config/env.config.ts. Ces clés sont publiques : elles ne doivent jamais recevoir de vrais fonds ni servir hors de la chaîne locale.

#Le script deploy-local.ts

scripts/deploy-local.ts enchaîne, avec le compte 0 :

#Pourquoi les adresses sont déterministes

L'adresse d'un contrat créé par un compte ne dépend que de l'adresse de ce compte et de son nonce. Le nœud démarre toujours avec les mêmes comptes, et le script envoie toujours les mêmes transactions dans le même ordre : le coordinateur naît au nonce 0, BlockLucky au nonce 3 et BlockLuckyPOAP au nonce 5. Ces adresses sont les valeurs par défaut de LOTTERY_CONTRACT_ADDRESS et POAP_CONTRACT_ADDRESS dans le backend et dans docker-compose.yml.

Conséquence : toute transaction ajoutée avant le nonce 5 dans le script, ou toute transaction envoyée par le compte 0 avant le déploiement, décale les adresses et casse la configuration par défaut du backend. L'identifiant d'abonnement, en revanche, change à chaque démarrage, car le mock le dérive notamment du hash du bloc précédent.

#Configuration déployée

Le tour est configuré par roundConfigFromEnv avec une durée par défaut de 30 minutes. La configuration VRF est fixe :

#Répartition des rôles

Les deux contrats sont construits avec le compte 0 comme administrateur provisoire. Le script calcule ensuite un plan de rôles avec planRoles de scripts/lib/roles.ts, le même module que pour Sepolia, l'applique avec applyRoles, puis le contrôle avec roleProblems : il s'arrête sur « Rôles incohérents » si un titulaire attendu manque. Il affiche enfin le tableau des titulaires (roleSummaryRows).

L'administrateur additionnel existe pour le reversement de commission de l'espace Mairie : le backend y appelle setTreasury, réservé à DEFAULT_ADMIN_ROLE, quand l'adresse saisie diffère de la trésorerie enregistrée. Le script le rappelle à la fin de son exécution.

Le compte 0 perd OPERATOR_ROLE, MINTER_ROLE et PAUSER_ROLE s'il n'est pas l'opérateur ou le pauseur, et renonce à DEFAULT_ADMIN_ROLE s'il n'est ni l'administrateur ni un administrateur additionnel. Deux cas en découlent :

Dans docker-compose.yml, OPERATOR_PRIVATE_KEY reçoit RELAYER_PRIVATE_KEY.

#Fichier de déploiement

Le script écrit smart-contract/deployments/localhost.json (ou dans DEPLOYMENTS_DIR), ignoré par Git. Il contient le réseau, le chain ID, la date, le bloc de déploiement, l'administrateur, l'opérateur, la trésorerie, les trois adresses, la configuration VRF (key hash, identifiant d'abonnement, nativePayment, propriétaire de l'abonnement, consommateur ajouté), le plan de rôles appliqué (roles), les arguments des deux constructeurs (constructorArgs) et la configuration des tours. L'oracle local le relit au démarrage.

#L'oracle local

scripts/local-vrf-responder.ts joue le rôle du réseau Chainlink :

1. il lit deployments/localhost.json ;
2. toutes les VRF_POLL_INTERVAL_MS millisecondes (2 000 par défaut), il récupère les événements RandomWordsRequested du mock depuis le dernier bloc lu ;
3. pour chaque requête qu'il n'a pas encore servie, il appelle fulfillRandomWords(requestId, consumer) sur le mock et attend la confirmation ;
4. il journalise chaque réponse et continue en cas d'erreur.

Il signe avec le compte d'index VRF_ORACLE_ACCOUNT_INDEX, 9 par défaut. Le compte est distinct de l'opérateur pour que deux processus n'envoient jamais de transactions avec le même compte : leurs nonces entreraient en conflit. Si l'index demandé n'existe pas, il se rabat sur le compte 0.

L'aléa fourni par le mock est keccak256(abi.encode(requestId, 0)) : déterministe, prévisible, et donc uniquement acceptable en développement. Voir Tirage Chainlink VRF.

#L'image Docker

Étapes du Dockerfile :

Le script de démarrage docker/start-local-chain.sh :

1. lance hardhat node --hostname 0.0.0.0 --port 8545 en arrière-plan ;
2. interroge eth_chainId chaque seconde jusqu'à ce que le nœud réponde ;
3. lance deploy-local.ts, puis crée /tmp/blockchain-ready, ce qui rend le conteneur sain ;
4. lance l'oracle local en arrière-plan ;
5. attend la fin du nœud et arrête l'oracle à la réception de INT ou TERM.

Le service compose ajoute cap_drop: [ALL], no-new-privileges et restart: unless-stopped. Cette image sert au développement et à la CI ; elle n'est jamais déployée en production (voir Images Docker).

#Variables

Les variables numériques de lib/deployment.ts, sauf TICKET_PRICE_WEI, doivent être des entiers strictement positifs, sinon le script s'arrête.

Exemple : un tour de 5 minutes à 2 tickets minimum, pour une démonstration.

ROUND_DURATION_SECONDS=300 MIN_TICKETS_TO_DRAW=2 npm run deploy:local

#Brancher le backend

Le backend lit RPC_URL, CHAIN_ID, LOTTERY_CONTRACT_ADDRESS, POAP_CONTRACT_ADDRESS et RELAYER_PRIVATE_KEY. Leurs valeurs par défaut correspondent exactement à cette chaîne locale : http://127.0.0.1:8545, 31337, les deux adresses ci-dessus et la clé du compte 0. Dans Docker Compose, RPC_URL vaut http://blockchain:8545. Voir Variables d'environnement et Mode onchain ou simulé.

#Vérifier que tout fonctionne

Depuis smart-contract/, la console Hardhat interroge directement le contrat déployé :

npx hardhat console --network localhost

const { ethers } = await network.create();
const lottery = await ethers.getContractAt("BlockLucky", "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9");
await lottery.currentRoundId();
await lottery.getRound(await lottery.currentRoundId());

Les journaux du conteneur indiquent les adresses déployées et chaque réponse de l'oracle :

docker compose logs -f blockchain