Clés et garde des portefeuilles

BlockLucky manipule trois familles de clés Ethereum : les portefeuilles des citoyens, conservés par le backend ; le compte opérateur, qui signe les opérations de service ; et les comptes de la Mairie qui administrent le contrat. Cette page décrit qui détient quoi, quels pouvoirs chaque clé confère sur la chaîne, et comment réagir à une compromission. Le fonctionnement technique des portefeuilles est détaillé dans Portefeuilles intégrés et celui du client RPC dans Client RPC et compte opérateur.

#Vue d'ensemble

flowchart TD
    subgraph Backend
        EK["ENCRYPTION_KEY"]
        RK["RELAYER_PRIVATE_KEY"]
        DB[("User.walletEncryptedKey")]
    end
    EK -->|"déchiffre"| DB
    DB -->|"signe achats, cadeaux, retraits"| SC["Contrat BlockLucky"]
    RK -->|"OPERATOR_ROLE, PAUSER_ROLE"| SC
    RK -->|"MINTER_ROLE"| POAP["Contrat BlockLuckyPOAP"]
    RK -->|"dotation de bienvenue"| DB
    ADM["Compte administrateur Mairie"] -->|"DEFAULT_ADMIN_ROLE"| SC
    VO["Propriétaire VRF, le multisig par défaut"] -->|"owner, setCoordinator"| SC
    DEP["Compte déployeur"] -.->|"aucun rôle après le déploiement"| SC

#Portefeuilles custodial des citoyens

Le backend signe à la place du citoyen les opérations suivantes, toutes déclenchées par une requête authentifiée du citoyen lui-même :

Ce modèle retire au citoyen toute manipulation de clé, mais fait de la Ville le dépositaire des fonds. Ses conséquences juridiques sont traitées dans Crypto-actifs et MiCA. Ses conséquences de sécurité sont les suivantes :

• le backend en fonctionnement peut signer pour n'importe quel citoyen ; une prise de contrôle du serveur équivaut à celle de tous les portefeuilles ;
• une copie de la base seule ne suffit pas : il faut aussi ENCRYPTION_KEY ;
• la perte de ENCRYPTION_KEY rend tous les portefeuilles inutilisables, sans recours (voir Rotation).

#Compte opérateur

RELAYER_PRIVATE_KEY est chargée par chainClient.operator, un NonceManager d'ethers, dans backend/src/blockchain/chain.client.ts. Le backend s'en sert pour :

#Rôles sur la chaîne

Les rôles sont gérés par AccessControl d'OpenZeppelin dans smart-contract/contracts/BlockLucky.sol et smart-contract/contracts/BlockLuckyPOAP.sol.

Les contrats sont construits avec le déployeur comme administrateur provisoire. Les deux scripts de déploiement répartissent ensuite les rôles avec la même bibliothèque, smart-contract/scripts/lib/roles.ts : planRoles refuse une adresse absente, invalide ou nulle et un administrateur confondu avec l'opérateur (sauf ALLOW_SHARED_ROLES=true), applyRoles accorde les rôles, positionne la trésorerie, propose la propriété VRF, retire au déployeur ses rôles d'exploitation et le fait renoncer à DEFAULT_ADMIN_ROLE, et roleProblems arrête le script si un titulaire manque. Ce comportement est couvert par smart-contract/test/roles.test.ts.

#Selon l'environnement

En local, la séparation est appliquée comme sur Sepolia, à une exception près : l'opérateur garde DEFAULT_ADMIN_ROLE pour que le reversement de commission puisse appeler setTreasury. Avec la clé de développement par défaut, l'opérateur est aussi le déployeur, qui garde alors ses rôles ; les clés locales sont de toute façon publiques. LOCAL_STRICT_ROLES=true reproduit exactement la configuration de Sepolia.

#Séparation recommandée

C'est la séparation que met en place npm run deploy:sepolia (variables MAIRIE_ADMIN_ADDRESS, MAIRIE_TREASURY_ADDRESS, OPERATOR_ADDRESS, PAUSER_ADDRESS, VRF_OWNER_ADDRESS). La route de trésorerie doit alors envoyer l'adresse de trésorerie déjà enregistrée ; tout changement de trésorerie passe par le multisig. Le multisig lui-même n'est pas créé par les scripts, qui ne vérifient pas non plus que l'adresse fournie en est un.

#Compromission et révocation

#Clé opérateur compromise

1. Mettre le contrat en pause depuis un autre compte détenant PAUSER_ROLE (l'administrateur), si l'attaquant n'a pas déjà agi.
2. Depuis le compte administrateur, appeler revokeRole(OPERATOR_ROLE, ancien), revokeRole(PAUSER_ROLE, ancien) et, sur le contrat POAP, revokeRole(MINTER_ROLE, ancien). Si l'ancien opérateur détenait DEFAULT_ADMIN_ROLE, le révoquer en dernier, depuis un autre administrateur.
3. Générer une nouvelle clé, accorder les trois rôles à la nouvelle adresse, la financer.
4. Remplacer RELAYER_PRIVATE_KEY dans l'environnement du backend et du worker, redémarrer.
5. Transférer les ETH restants de l'ancien compte s'ils sont encore accessibles.

Ce que l'attaquant peut faire avant la révocation : pauser le contrat, annuler le tour en cours (les participants restent remboursables), vider le solde de l'opérateur, émettre de faux badges POAP. Il ne peut ni désigner un gagnant ni retirer la cagnotte, sauf s'il détient aussi DEFAULT_ADMIN_ROLE ou la propriété VRF.

#ENCRYPTION_KEY ou base de données compromise

Avec la base et la clé, l'attaquant peut signer pour chaque citoyen, donc acheter des tickets avec leurs fonds ou retirer leurs gains vers leur propre portefeuille, qu'il contrôle alors. Il faut :

1. mettre le contrat en pause (achats bloqués ; claimPrize et claimRefund restent possibles, car ils ne sont pas soumis à whenNotPaused) ;
2. arrêter le backend ;
3. générer pour chaque citoyen un nouveau portefeuille, puis transférer les fonds de l'ancien au nouveau avant l'attaquant, ce qui suppose un script qui n'existe pas dans le dépôt ;
4. remplacer ENCRYPTION_KEY après re-chiffrement.

Sur un réseau de test, la réponse raisonnable est de redéployer et de redistribuer des ethers fictifs. Le plan de réponse aux incidents et les runbooks blockchain donnent les procédures d'exploitation.

#Clé administrateur ou déployeur compromise

C'est le scénario le plus grave : l'attaquant peut changer la configuration des tours, la trésorerie, les rôles et, avec la propriété VRF, le coordinateur. Une fois le déploiement terminé et acceptOwnership signé par le multisig, la clé du déployeur ne détient plus aucun de ces pouvoirs : sa fuite n'a d'effet qu'avant ce moment. Le contrat n'étant pas modifiable, la seule réponse est de le mettre en pause s'il en est encore temps, d'informer les participants et de redéployer. D'où l'importance d'un multisig pour ces deux comptes.

#Limites connues