Contrat BlockLucky

BlockLucky est la loterie elle-même. Il enchaîne des tours numérotés à partir de 1. Chaque tour vend des tickets à prix fixe, se clôt quand il est complet ou que sa durée est écoulée, puis est tiré au sort par Chainlink VRF ou annulé. Un nouveau tour s'ouvre aussitôt. Source : smart-contract/contracts/BlockLucky.sol.

Cette page décrit les structures, l'état stocké, les rôles, les paramètres et les calculs. Les transitions d'état sont détaillées dans Cycle de vie d'un tour, la liste exhaustive des fonctions dans Référence de BlockLucky.

#Héritage

contract BlockLucky is VRFConsumerBaseV2Plus, AccessControl, Pausable, ReentrancyGuard, AutomationCompatibleInterface {

VRFConsumerBaseV2Plus hérite lui-même de ConfirmedOwner. Le contrat a donc, en plus des rôles, un propriétaire, d'abord le compte qui l'a déployé. Ce propriétaire peut appeler setCoordinator et transferOwnership. Les scripts de déploiement transfèrent cette propriété en deux temps (transferOwnership puis acceptOwnership) à l'administrateur de la Mairie, ou à VRF_OWNER_ADDRESS sur Sepolia. Les conséquences sont analysées dans Sécurité du contrat.

#Constantes

#Structures

#RoundStatus

enum RoundStatus {
    Open,
    Drawing,
    Completed,
    Cancelled
}

Les valeurs numériques renvoyées par l'ABI sont 0, 1, 2 et 3. Les tests les reprennent dans RoundStatus de test/fixtures.ts.

#RoundConfig

Paramètres des tours à venir, modifiables par l'administrateur.

Les défauts viennent de roundConfigFromEnv dans scripts/lib/deployment.ts et se remplacent par les variables TICKET_PRICE_WEI, MAX_TICKETS, MIN_TICKETS_TO_DRAW, MAX_TICKETS_PER_PLAYER, ROUND_DURATION_SECONDS et MUNICIPALITY_FEE_BPS. Une commission nulle est acceptée par le contrat, mais pas par le script, qui exige des entiers strictement positifs.

#VrfConfig

Paramètres des requêtes Chainlink VRF, modifiables par l'administrateur.

#Round

État complet d'un tour, renvoyé par getRound(roundId).

Les champs sont ordonnés pour que le compilateur les regroupe : les quatre uint256, puis l'adresse avec startTime, puis les autres petits entiers. Le tour tient en sept emplacements de stockage.

Chaque tour copie les paramètres de roundConfig à son ouverture. C'est ce qui permet de modifier la configuration sans toucher au tour en cours : la nouvelle valeur s'applique au tour suivant.

#État stocké

Le contrat ne stocke aucune donnée personnelle : seulement des adresses, des montants et des compteurs. Le lien entre une adresse et un citoyen reste dans la base du backend (voir Blockchain et données personnelles).

#Bénéficiaire et payeur

buyTicketsFor(player, quantity) permet d'offrir des tickets. Le contrat distingue alors deux adresses :

• le bénéficiaire (player) détient les tickets : il est inscrit dans ticketOwners et ticketsByPlayer, son plafond par participant est décompté, et c'est lui qui peut gagner ;
• le payeur (msg.sender) a versé les ethers : sa mise est inscrite dans contributions, et c'est lui qui sera remboursé si le tour est annulé.

L'événement TicketsPurchased porte les deux adresses (player et payer). Pour un achat simple, elles sont identiques. Le test « permet d'offrir des tickets : le bénéficiaire les détient, le payeur est remboursable » vérifie ce partage.

#Rôles

Le constructeur accorde les trois rôles à admin. Les scripts de déploiement passent le déployeur comme admin provisoire, puis répartissent les rôles avec scripts/lib/roles.ts : administrateur, opérateur, pauseur et trésorerie distincts, puis retrait de ses rôles au déployeur (voir Déploiement sur Sepolia et Blockchain locale). DEFAULT_ADMIN_ROLE est l'administrateur de tous les rôles : seul son titulaire peut en accorder ou en retirer.

#Constructeur

constructor(
    address vrfCoordinator,
    address admin,
    address treasury_,
    RoundConfig memory initialRoundConfig,
    VrfConfig memory initialVrfConfig
) VRFConsumerBaseV2Plus(vrfCoordinator)

Dans l'ordre, il :

1. enregistre le coordinateur (ZeroAddress de Chainlink s'il est nul) et fait du déployeur le propriétaire ;
2. refuse un admin ou un treasury_ nul (ZeroAddressNotAllowed) ;
3. valide les deux configurations (InvalidConfiguration) ;
4. accorde DEFAULT_ADMIN_ROLE, OPERATOR_ROLE et PAUSER_ROLE à admin ;
5. enregistre la trésorerie et les configurations ;
6. ouvre le tour 1 (RoundOpened).

Le contrat est donc utilisable dès son déploiement, à une condition : être ajouté comme consommateur de l'abonnement VRF avant le premier tirage.

#Achat de tickets

buyTickets(quantity) et buyTicketsFor(player, quantity) sont payable, whenNotPaused et nonReentrant. Elles délèguent à _buyTickets, qui contrôle dans cet ordre :

Le paiement doit être exact : un excédent n'est pas rendu, il est refusé. Ensuite, le contrat ajoute quantity fois l'adresse du bénéficiaire à ticketOwners[roundId], met à jour ticketCount, totalCollected, ticketsByPlayer et contributions, puis émet TicketsPurchased avec l'index du premier ticket acheté (firstTicketIndex) et le total vendu.

La boucle d'inscription est bornée par maxTicketsPerPlayer. Son coût croît avec la quantité, de l'ordre de 25 000 gaz par ticket supplémentaire : le rapport de gaz relève 119 577 gaz au minimum et 356 745 gaz au maximum, pour un achat de dix tickets.

Les tickets sont numérotés à partir de 0. Si Alice achète 3 tickets puis Bob 5, Alice détient les index 0 à 2 et Bob les index 3 à 7. ticketOwner(roundId, 5) renvoie l'adresse de Bob.

#Calcul de la commission et de la cagnotte

Au tirage, dans fulfillRandomWords :

uint256 fee = (round.totalCollected * round.feeBps) / BPS_DENOMINATOR;
uint256 prize = round.totalCollected - fee;

• La commission est arrondie à l'inférieur par la division entière ; l'arrondi profite au gagnant.
• prize + fee == totalCollected exactement : aucun wei n'est perdu. Le test de fuzzing testFuzz_PrizeAndFeeMatchCollectedFunds le vérifie sur 256 jeux de données.
• La commission s'ajoute à accruedFees ; la cagnotte est inscrite dans round.prize. Aucun transfert n'a lieu à ce moment.
• Le taux est celui du tour (round.feeBps), copié à son ouverture : changer feeBps en cours de tour n'a pas d'effet rétroactif.

Exemple tiré des tests : 10 tickets à 0,01 ETH donnent totalCollected = 0,1 ETH. Avec feeBps = 1 000, la commission vaut 0,01 ETH et la cagnotte 0,09 ETH.

Un tour annulé ne prélève aucune commission : chaque payeur récupère l'intégralité de sa mise.

#Tirage du gagnant

uint32 winningTicket = uint32(randomWords[0] % round.ticketCount);
address winner = ticketOwners[roundId][winningTicket];

Le mot aléatoire de Chainlink, un entier de 256 bits, est réduit modulo le nombre de tickets vendus. Le résultat est l'index d'un ticket ; son bénéficiaire est le gagnant. Chaque ticket a donc la même chance, et un participant qui détient 5 tickets sur 10 a une chance sur deux.

• ticketCount est au moins égal à minTicketsToDraw, lui-même au moins 1 : la division par zéro est impossible.
• Le biais du modulo est négligeable : ticketCount tient sur 32 bits, l'aléa sur 256 bits.
• Le test « tire le gagnant parmi les tickets vendus quel que soit l'aléa » utilise ethers.MaxUint256 comme mot aléatoire et vérifie que l'index obtenu est MaxUint256 % 10.

Le mécanisme complet de la requête et de la réponse est sur la page Tirage Chainlink VRF.

#Retraits à l'initiative du bénéficiaire

Le contrat n'envoie jamais d'ethers de lui-même lors d'un tirage ou d'une annulation. Il inscrit des droits, que chaque bénéficiaire retire ensuite (« pull payment ») :

Ce choix a trois effets :

1. Un destinataire défaillant ne bloque personne. Si un contrat gagnant refuse les ethers, seul son retrait échoue (TransferFailed), et l'état est restauré par le revert : il peut réessayer. Le tour suivant est déjà ouvert.
2. Le tirage reste bon marché et prévisible en gaz. Le callback VRF ne fait aucun transfert, ce qui borne sa consommation (voir Sécurité du contrat).
3. Les fonds restent disponibles même en pause. claimPrize, claimRefund et withdrawFees n'ont pas whenNotPaused.

Les citoyens n'appellent pas ces fonctions à la main : la file d'actions on-chain du backend signe claimPrize et claimRefund avec leur portefeuille intégré.

Les retraits ne sont pas limités dans le temps : une cagnotte non réclamée reste due indéfiniment au gagnant.

#Absence de fonction receive

Le contrat ne déclare ni receive ni fallback. Un envoi d'ethers direct, hors buyTickets ou buyTicketsFor, est rejeté par l'EVM. Le test « refuse tout envoi direct d'ethers hors achat » le vérifie.

Conséquence : le solde du contrat est égal, à tout instant, à la somme des mises des tours ouverts ou en tirage, des cagnottes non réclamées, des remboursements non réclamés et de accruedFees. Les tests de fuzzing testFuzz_ClaimsEmptyTheContractExactly et testFuzz_RefundsReturnEveryContribution vérifient que tous les retraits vident le contrat exactement à zéro.

Seul un envoi forcé (par exemple un selfdestruct d'un autre contrat) pourrait ajouter des ethers ; ils ne seraient alors comptés nulle part et resteraient bloqués, sans perturber la comptabilité.

#Fonctions de lecture

Un tour qui n'existe pas renvoie une structure vide : getRound(999) ne revert pas, son status vaut 0 (Open) et endTime vaut 0. Il faut donc toujours comparer roundId à currentRoundId avant d'interpréter le statut.