Accueil

BlockLucky est la loterie citoyenne de fin d'année de la Ville d'EtherBay. C'est un projet de l'Epitech Digital School (rush « BlockLucky, création d'un smart contract », promotion DIGI3), conçu comme un pilote pédagogique : les tickets s'achètent en ethers fictifs, sans aucune valeur monétaire, sur un vrai smart contract Solidity.

Cette documentation s'adresse aux développeurs de la Ville qui reprennent le code source et au jury de l'école. Elle décrit ce que fait réellement le code, la manière de le lancer, de le modifier et de l'exploiter, ainsi que ce qui reste simulé ou à faire.

#Le projet en bref

Le cœur du projet est le contrat smart-contract/contracts/BlockLucky.sol. Il encaisse les tickets, ferme le tour quand il est complet ou quand sa durée est écoulée, demande un nombre aléatoire à Chainlink VRF v2.5, désigne le gagnant et lui réserve la cagnotte. Un second contrat, smart-contract/contracts/BlockLuckyPOAP.sol, frappe un badge de participation ERC-721 non transférable par participant et par tour.

Autour du contrat, le dépôt contient une plateforme complète :

• un backend Express 5 en TypeScript (backend/src/app.ts) avec PostgreSQL, Redis, BullMQ et Socket.IO. Il crée pour chaque citoyen un portefeuille Ethereum intégré, chiffré en AES-256-GCM, lui verse une dotation de bienvenue en ethers fictifs, signe ses achats avec sa clé et projette les événements du contrat en base ;
• un frontend web Next.js 16 avec trois espaces : citoyen, commerçant partenaire et dashboard de la Mairie, qui examine aussi les pièces d'identité envoyées pour la vérification d'âge ;
• une application mobile Expo pour les citoyens, avec compte par mot de passe ou Google, vérification d'âge, salle d'attente et roue du tirage ;
• un site vitrine statique de l'Office de Tourisme, livré en bonus ;
• une blockchain locale en conteneur (nœud Hardhat, contrats déployés à des adresses fixes, oracle VRF simulé), une CI GitHub Actions et des scénarios de charge k6.

Les citoyens gagnent aussi des EtherPoints en participant (achat, cadeau, parrainage, quêtes). Ces points, tenus en base de données et non sur la chaîne, s'échangent contre des offres des commerçants partenaires.

flowchart LR
    C["Citoyen"] --> W["Web Next.js"]
    C --> M["Mobile Expo"]
    A["Mairie et partenaires"] --> W
    W --> B["Backend Express"]
    M --> B
    B --> P[("PostgreSQL")]
    B --> R[("Redis")]
    B --> K["Contrat BlockLucky"]
    B --> N["Contrat POAP"]
    K --> V["Chainlink VRF"]

#Par où commencer

Le tableau suivant propose un parcours de lecture par profil. Chaque ligne liste les pages à lire dans l'ordre.

#Les questions les plus fréquentes

#Adresses locales utiles

Une fois l'environnement lancé comme décrit dans Lancer les applications :

#Conventions de cette documentation

Les liens de la forme backend/src/app.ts ouvrent le fichier source sur GitHub. Certaines pages, comme la référence de l'API ou le dictionnaire de données, sont générées depuis le code à chaque construction du site. La page Comment lire cette documentation détaille l'organisation en 16 parties, les encadrés et la recherche.