Passerelle du contrat et erreurs

backend/src/blockchain/lottery.gateway.ts exporte le singleton lotteryGateway. C'est l'interface entre les services HTTP et le contrat BlockLucky. Il fait trois choses :

1. il lit l'état du contrat et le convertit en types TypeScript simples ;
2. il envoie les transactions et indexe immédiatement leur reçu ;
3. il traduit toute erreur (contrat, réseau, solde) en AppError avec un statut HTTP et un message en français destiné au citoyen.

Les services appelants sont backend/src/api/lottery/lottery.services.ts, backend/src/api/admin/admin.services.ts et backend/src/services/blockchain.service.ts. La description du contrat lui-même est sur la page Référence du contrat BlockLucky.

#Lectures

readRound convertit la structure Solidity Round :

Les montants restent en bigint dans la passerelle. Les services les convertissent en ETH avec formatEther seulement pour l'affichage et pour la colonne prizePool.

#Écritures

La lecture ticketsOf(tour, adresse) renvoie le nombre de tickets d'une adresse sur un tour. Le service de loterie l'appelle avant chaque achat et chaque cadeau pour refuser un second ticket avant d'envoyer la transaction.

#Achat

buyTickets lit d'abord le tour courant. Si son statut n'est pas OPEN, il refuse l'achat avec une 409 sans envoyer de transaction. Sinon, il calcule la valeur exacte à payer, ticketPriceWei × quantité, car le contrat rejette tout montant différent (IncorrectPayment). Il envoie la transaction, attend le reçu, et renvoie la première entrée de purchases produite par l'indexeur. Si le reçu ne contient aucun événement TicketsPurchased, il lève une 502 « L'achat a été envoyé mais aucun ticket n'a été émis par le contrat. ».

prepareWallet(user) doit être appelé avant buyTickets pour que le portefeuille existe et soit approvisionné ; voir Portefeuilles intégrés.

#Reversement de la commission

withdrawFees(trésorerie) compare la trésorerie enregistrée dans le contrat à celle demandée. Si elles diffèrent, il appelle setTreasury, qui exige le rôle DEFAULT_ADMIN_ROLE. Il lit ensuite accruedFees, appelle withdrawFees et renvoie le hachage, le montant en ETH et la trésorerie. Le montant demandé par l'administrateur (amountEth) n'est pas utilisé en mode onchain : c'est toujours la totalité de la commission accumulée qui est reversée.

withdrawFees n'utilise pas sendAndIndex : il n'y a rien à indexer, et il n'y a pas de reprise sur NONCE_EXPIRED.

#sendAndIndex

Toutes les écritures sauf withdrawFees passent par la méthode privée sendAndIndex(send, fallback) :

flowchart TD
    A["send()"] -->|"erreur NONCE_EXPIRED"| B["resetOperatorNonce()"]
    B --> C["send() une seconde fois"]
    A -->|"transaction envoyée"| D["tx.wait()"]
    C --> D
    A -->|"autre erreur"| X["toAppError(erreur, fallback)"]
    C -->|"erreur"| X
    D -->|"reçu null"| E["AppError 502 canRetry"]
    D -->|"reçu"| F["lotteryIndexer.processReceipt(reçu)"]
    F --> G["retour reçu et achats indexés"]
    E --> X

Trois propriétés en découlent :

• Synchronisme : la réponse HTTP n'est envoyée qu'une fois la transaction minée. Sur le nœud Hardhat local, le minage est instantané ; sur Sepolia, il faut compter environ 12 s par bloc, sous la limite HTTP_REQUEST_TIMEOUT_MS de 30 s.
• Indexation immédiate : les événements du reçu sont projetés en base avant la réponse. L'API peut donc renvoyer les identifiants des tickets créés. L'indexeur périodique repassera sur le même bloc sans rien dupliquer.
• Erreurs homogènes : toute exception, y compris celles de l'indexation, passe par toAppError.

Le paramètre send est une fonction et non une promesse, pour pouvoir renvoyer la transaction lors de la reprise sur NONCE_EXPIRED (voir Client RPC).

#Traduction des erreurs

#toAppError

toAppError(erreur, messageParDéfaut) applique les règles suivantes, dans l'ordre :

1. une AppError est renvoyée telle quelle ;
2. l'erreur personnalisée Solidity est décodée par decodeContractError (voir File d'actions) ; si son nom figure dans la table CONTRACT_ERRORS, l'AppError correspondante est créée, avec contractError dans les détails ;
3. le code ethers INSUFFICIENT_FUNDS donne une 402 ;
4. les codes ethers NETWORK_ERROR, TIMEOUT et SERVER_ERROR donnent une 503 avec canRetry: true ;
5. tout le reste est journalisé en erreur (avec le code et le nom de l'erreur du contrat s'il existe) et donne une 502 avec le message par défaut et canRetry: true.

Les détails sont renvoyés au client dans le champ errors de la réponse d'erreur. Par exemple, un achat pendant une pause du contrat renvoie :

{
  "success": false,
  "message": "Le Smart Contract est temporairement en pause de sécurité par la Mairie.",
  "errors": { "contractError": "EnforcedPause", "canRetry": false, "circuitBreaker": true }
}

Le test d'intégration vérifie exactement ce cas (blocked.status 503 et blocked.body.errors.circuitBreaker à true).

#Table des erreurs du contrat

Chaque réponse porte en plus contractError avec le nom de l'erreur.

#Erreurs hors contrat

Les erreurs du contrat absentes de la table (ZeroAddressNotAllowed, TransferFailed, NothingToRefund, RoundNotCancelled, DrawNotStale, InvalidConfiguration) tombent dans le dernier cas : elles sont journalisées avec leur nom et renvoyées en 502.

#Vérifications faites avant le contrat

Certaines erreurs sont produites par la passerelle ou les services avant tout appel au contrat :

Le format général des réponses d'erreur de l'API est décrit sur la page Réponses et erreurs.