Préparer la soutenance

Ce guide prépare la démonstration de BlockLucky devant les parties prenantes de la Ville d'EtherBay : le Maire, le responsable événementiel et le DSI, ainsi que le jury. Il donne un scénario complet, minuté, sur la stack locale, avec une vraie blockchain (nœud Hardhat), un vrai smart contract et un oracle VRF local. Il liste les preuves de transparence à montrer, les réponses aux questions probables et le plan de secours.

Les besoins de chaque partie prenante sont rappelés dans Besoins des parties prenantes. Ce qui est réel ou simulé est récapitulé dans Réel, simulé ou à venir : le relire avant la soutenance, pour ne rien affirmer de faux.

#Ce que la démonstration prouve

#La veille

#Installer et vérifier

Prérequis : Docker Desktop, Node.js 22 (voir Prérequis). Installer les dépendances une fois, à l'avance, avec une connexion fiable :

cd backend && npm ci && cd ..
cd frontend-web && npm ci && cd ..
cd smart-contract && npm ci && cd ..

Lancer la suite de tests une dernière fois pour pouvoir montrer qu'elle passe :

cd smart-contract && npm test

cd backend && npm test

#Repartir d'un état propre

Le nœud Hardhat ne garde rien entre deux démarrages : la base doit repartir de zéro en même temps que lui (voir Blockchain locale). À faire la veille au soir, puis de nouveau le matin :

docker compose down -v
docker compose up -d --wait

cd backend
npm run prisma:deploy
npm run prisma:seed
npm run dev

cd frontend-web
npm run dev

cd frontend-office-tourisme
npm run dev

docker compose up -d --wait démarre PostgreSQL, Redis, Mailpit et le service blockchain, qui déploie les contrats aux adresses habituelles et lance l'oracle VRF local. npm run dev du backend démarre l'API, les workers, l'indexeur et le keeper dans un seul processus (RUN_WORKERS=true par défaut).

#Préparer les comptes

Le seed crée trois comptes, sans portefeuille réel ; le portefeuille intégré est créé au premier achat. Les trois ont le mot de passe EtherBay2026demo et un âge déjà vérifié (VERIFIED) :

Sur le web, la connexion se fait par code à 6 chiffres envoyé par email, lu dans Mailpit (http://localhost:8025) ; sur mobile, par email et mot de passe. Le compte du Maire doit avoir activé la double authentification avant d'ouvrir le dashboard : requireRoles refuse sinon toute route d'administration (« La double authentification est obligatoire pour les comptes d'administration »). La veille, se connecter avec maire@etherbay.fr, aller dans Profil, Sécurité, et activer la 2FA par email. En développement, la page affiche le code d'activation (devOtpPreview).

Pour la démonstration elle-même, une nouvelle citoyenne, Camille, s'inscrit en direct sur l'application mobile avec une adresse fictive non encore utilisée, par exemple camille@etherbay.fr. Un second nouveau citoyen, Dominique (dominique@etherbay.fr), reçoit un ticket offert sans s'inscrire.

Deux réglages de la veille :

• placer dans la galerie du téléphone ou du simulateur deux images JPEG ou PNG de spécimen de carte d'identité (jamais une vraie pièce), de 4 Mo au plus, pour le recto et le verso ;
• réduire le délai de révélation à une minute dans backend/.env (DRAW_REVEAL_DELAY_SECONDS=60), puis redémarrer le backend : la valeur par défaut de 10 minutes est trop longue pour la démonstration.

#Préparer l'écran

Le jeton de session web est gardé dans le localStorage du navigateur : chaque personnage web a besoin de son propre profil de navigateur.

#Préparer le secours

Enregistrer la veille une vidéo du scénario complet et une série de captures d'écran (voir Plan de secours).

#Scénario

Durée totale : environ 20 minutes, dont 5 de marge. Les étapes marquées « facultative » se sautent si le temps manque.

#1. L'Office de Tourisme annonce la loterie

Sur http://localhost:4000, montrer le bandeau « Nouveauté : La Grande Loterie citoyenne », puis la fiche de l'événement (fiche.html?event=loterie-citoyenne) : pilote pédagogique, ethers fictifs, participation réservée aux majeurs. Cliquer sur « Accéder à la loterie » : le frontend web s'ouvre.

Message : la Ville communique sur la loterie avec ses canaux habituels ; le site touristique ne touche à aucune donnée de la loterie (voir Rôle dans le projet).

#2. Inscription, dotation et vérification d'âge

Sur l'application mobile, Camille choisit « Créer un compte », saisit camille@etherbay.fr et un mot de passe d'au moins 10 caractères avec une lettre et un chiffre, coche l'acceptation des conditions générales d'utilisation et du règlement ainsi que la case « Je certifie avoir 18 ans ou plus », puis saisit le code reçu dans Mailpit. Les liens des deux cases ouvrent les textes dans l'application. En arrière-plan :

1. un portefeuille Ethereum est créé pour elle, sa clé privée chiffrée en AES-256-GCM avec ENCRYPTION_KEY ;
2. la Mairie (compte opérateur) lui verse une dotation de bienvenue de 0,5 ether fictif (WELCOME_GRANT_WEI) ;
3. elle reçoit 25 EtherPoints de bienvenue et un email de bienvenue, visible dans Mailpit.

L'application ouvre d'elle-même l'écran de vérification d'âge. Camille choisit le recto puis le verso du spécimen dans la galerie et les envoie : son statut passe à « en attente ». Dans le profil du Maire, ouvrir /mairie/identites, afficher la demande (le recto et le verso déchiffrés n'apparaissent que tant qu'elle est en attente) et la valider. Les images sont effacées, Camille reçoit l'email de décision dans Mailpit, et /mairie/audit trace la consultation et la décision.

Dans le terminal 1, la transaction de dotation apparaît dans les journaux du nœud.

Message : aucun prérequis technique ni financier pour le citoyen, et une majorité vérifiée par la Mairie sans conserver la pièce (voir Inscription et portefeuille et Vérification d'âge).

#3. Achat du ticket

Camille rouvre l'écran de vérification d'âge depuis son profil, qui relit son statut et affiche maintenant l'âge vérifié, puis achète son ticket depuis l'accueil. La transaction buyTickets est signée avec son portefeuille intégré et envoyée au contrat. Montrer :

• la confirmation avec le numéro du ticket sur cinq chiffres ;
• les 50 EtherPoints crédités ;
• le ticket dans l'onglet Mes tickets.

Un second achat est refusé : un seul ticket par participant et par grand tirage (409, PlayerLimitReached). Le prix est de 0,01 ether fictif, plus les frais de réseau payés par la dotation.

#4. Ticket offert

Sur le web, le citoyen du seed se connecte avec citoyen@etherbay.fr, puis, dans la Billetterie, choisit « Offrir un ticket » et saisit dominique@etherbay.fr. Le contrat enregistre un ticket au nom de Dominique, payé par le citoyen (buyTicketsFor) ; le citoyen reçoit 75 EtherPoints et Dominique les 50 points du ticket. Dominique n'a pas encore de compte : il en reçoit un, avec son portefeuille, mais aucun email ne le prévient (voir Ajouter un email). Un cadeau à Camille serait refusé, puisqu'elle a déjà son ticket.

Le citoyen achète ensuite son propre ticket ; la billetterie web n'en propose qu'un. Le tour compte alors 3 tickets, un par participant. Le minimum pour lancer un tirage est de 2 tickets (MIN_TICKETS_TO_DRAW).

#5. Faire passer le temps sur la chaîne

Un tour dure 30 minutes sur la blockchain locale (deploy-local.ts). Plutôt qu'attendre, avancer l'horloge du nœud Hardhat, comme le fait le test d'intégration onchain-lottery.chain.ts. Ouvrir d'abord la page /tirage dans la fenêtre du citoyen et l'accueil de l'application de Camille : l'annonce du gagnant arrive par Socket.IO et n'est affichée que par une page déjà ouverte.

Avec Git Bash, macOS ou Linux :

curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"evm_increaseTime","params":[1860]}'
curl -s -X POST http://127.0.0.1:8545 -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"evm_mine","params":[]}'

Avec PowerShell :

Invoke-RestMethod -Uri http://127.0.0.1:8545 -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":1,"method":"evm_increaseTime","params":[1860]}'
Invoke-RestMethod -Uri http://127.0.0.1:8545 -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":2,"method":"evm_mine","params":[]}'

evm_increaseTime avance l'horloge de 1 860 secondes (31 minutes) pour les prochains blocs ; evm_mine produit un bloc avec cette nouvelle heure. La valeur couvre un tour entier, quel que soit le temps déjà écoulé depuis son ouverture.

#6. Salle d'attente, tirage et annonce du gagnant

Le tour passe en phase WAITING_ROOM : les achats sont clos et GET /lottery/status publie l'heure de révélation (revealAt). Sur mobile, Camille entre dans la salle d'attente, qui affiche le compte à rebours et la discussion en direct. Le keeper attend la fin du délai de révélation (DRAW_REVEAL_DELAY_SECONDS, réglé à 60 secondes la veille), puis la chaîne d'automatismes suivante s'exécute en moins de 15 secondes.

sequenceDiagram
    participant K as Keeper du backend
    participant C as Contrat BlockLucky
    participant V as Oracle VRF local
    participant I as Indexeur
    participant W as Worker
    participant P as Pages Tirage
    K->>C: isDrawReady ? oui, délai de révélation écoulé, requestDraw()
    C->>V: requestRandomWords
    C-->>I: DrawRequested
    V->>C: fulfillRandomWords
    C->>C: gagnant = ticket aléa modulo nombre de tickets
    C-->>I: WinnerPicked, puis RoundOpened du tour suivant
    I->>P: draw:winner par Socket.IO
    I->>W: CLAIM_PRIZE pour le gagnant
    W->>C: claimPrize() signé par le portefeuille du gagnant
    C-->>I: PrizeClaimed

La page /tirage passe par « Tirage en cours », puis affiche l'adresse du portefeuille gagnant ; sur mobile, la roue s'arrête sur le numéro du ticket gagnant. Pour une mise en scène plus parlante, le Maire peut déclencher le tirage lui-même depuis /mairie/securite (« Lancer le tirage VRF ») juste après l'avance du temps : cet appel n'attend pas le délai de révélation.

Message : personne ne choisit le gagnant. La Mairie peut demander le tirage, comme n'importe qui (requestDraw est publique), mais le résultat vient de l'oracle et le calcul est fait par le contrat.

#7. Cagnotte versée et badge POAP

Le worker réclame la cagnotte au nom du gagnant, sans action de sa part. Sur 3 tickets à 0,01, la collecte est de 0,03 ether fictif : la commission de la Mairie est de 10 % (MUNICIPALITY_FEE_BPS = 1000), le gagnant reçoit 0,027. Dans la fenêtre du gagnant :

• le solde du portefeuille a augmenté d'un peu moins de 0,027 : la transaction de retrait est signée par son portefeuille, qui en paie les frais ;
• sur le web, la carte « Félicitations » apparaît sur l'accueil si l'annonce a été reçue dans la session, par exemple sur la page Tirage ; son bouton de retrait répond que la cagnotte a déjà été versée ; sur mobile, l'onglet Mes tickets marque le ticket gagnant ;
• l'onglet POAP de /historique montre le badge de participation du tour, frappé par l'opérateur après le premier achat.

Dominique n'a pas de session : s'il gagne, montrer le versement dans le terminal 1 et dans la lecture du contrat de l'étape 10.

Les métadonnées du badge sont servies par l'API : http://localhost:2053/api/v1/lottery/poap/1.json et son visuel http://localhost:2053/api/v1/lottery/poap/1.svg (remplacer 1 par le numéro du tour).

#8. EtherPoints chez un commerçant (facultative)

Camille a 75 EtherPoints : 25 de bienvenue et 50 pour son ticket. Sur l'application, elle achète le ticket à gratter violet pour 50 points (POST /marketplace/scratch), le gratte et découvre une offre tirée au hasard parmi celles en stock de la Boulangerie du Port et du Cinéma Le Phare, avec un code unique, aussi envoyé par email (Mailpit). Dans le profil du Maire, ou une autre fenêtre, se connecter avec boulangerie@etherbay.fr, ouvrir /partenaire/validation et saisir le code : il est marqué utilisé. Une seconde saisie est refusée.

Message : l'économie locale profite de la loterie (voir Échange de récompense).

#9. Disjoncteur

Le Maire ouvre /mairie/securite et clique sur « Mettre le Smart Contract en pause », avec un motif. La transaction pause() part du compte opérateur, qui détient PAUSER_ROLE. Camille tente d'acheter son ticket du tour suivant, ouvert après le tirage : refus avec le message « Le Smart Contract est temporairement en pause de sécurité par la Mairie. » (statut 503). Le Maire réactive les participations. Montrer l'entrée correspondante dans /mairie/audit.

Message : en cas d'incident, la Mairie arrête tout en un clic, et l'action est tracée. La pause bloque les achats et les tirages, mais pas claimPrize ni claimRefund : même en pause, personne ne peut empêcher un gagnant ou un participant remboursé de récupérer ses fonds. Voir Disjoncteur.

#10. Preuves de transparence

Lire l'état du tour terminé directement dans le contrat, sans passer par l'API ni par la base. Depuis backend/, avec le numéro du tour en argument :

cd backend
node -e '
const { JsonRpcProvider, Contract, formatEther } = require("ethers");
const abi = require("./src/blockchain/abi/BlockLucky.json");
const lottery = new Contract("0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9", abi, new JsonRpcProvider("http://127.0.0.1:8545"));
(async () => {
  const id = BigInt(process.argv[1] ?? (await lottery.currentRoundId()));
  const r = await lottery.getRound(id);
  console.log({
    tour: Number(id),
    statut: ["Open", "Drawing", "Completed", "Cancelled"][Number(r.status)],
    tickets: Number(r.ticketCount),
    collecte: formatEther(r.totalCollected),
    gagnant: r.winner,
    ticketGagnant: Number(r.winningTicket),
    cagnotte: formatEther(r.prize),
    versee: r.prizeClaimed,
    requeteVrf: r.vrfRequestId.toString(),
    commission: formatEther(await lottery.accruedFees()),
    pause: await lottery.paused(),
  });
})();
' 1

Les valeurs affichées doivent correspondre à celles de l'application : c'est la base qui recopie la chaîne, pas l'inverse.

#Points de transparence à montrer

#Questions probables

#Le Maire

#Le responsable événementiel

#Le DSI

#Plan de secours

Le mode simulé est un dernier recours : il prouve le parcours, pas le smart contract. Ne pas le présenter comme le fonctionnement réel (voir Mode onchain ou simulé).

#Après l'avance du temps

L'horloge de la chaîne est désormais en avance d'une trentaine de minutes sur l'horloge réelle. Le tour suivant s'ouvre avec une échéance calculée sur l'heure de la chaîne, et le compte à rebours de l'application, calculé avec l'heure réelle, affiche donc environ 30 minutes de plus que la durée restante réelle. Le dire si quelqu'un le remarque, ou repartir d'un état propre avant une seconde démonstration.

#Liste de contrôle du jour J

• Base et chaîne réinitialisées le matin, seed lancé.
• 2FA du compte maire@etherbay.fr activée.
• DRAW_REVEAL_DELAY_SECONDS=60 dans backend/.env, images de spécimen dans la galerie du téléphone.
• Backend, frontend web, application mobile et Office de Tourisme démarrés, docker compose ps sain.
• Fenêtres et profils de navigateur ouverts, Mailpit vide.
• Commandes d'avance du temps et de lecture du contrat prêtes dans un terminal.
• Pages /tirage ouvertes avant l'avance du temps.
• Vidéo et captures de secours disponibles hors ligne.
• Répartition des rôles entre les membres de l'équipe (présentateur, Camille, citoyen du seed, Maire).
• Limites et parties simulées prêtes à être énoncées.