Case study : architecture technique de GreenChain Common

March 24, 2026

Contexte

GreenChain Common est né d'un constat simple : mes quatre MVP web3 (vault, market, registry, governance) vivaient chacun dans leur propre repo avec leur propre frontend. Impossible de montrer une vision produit cohérente en entretien ou en démo.

L'objectif : les réunir dans une seule dApp avec un parcours utilisateur linéaire et un dashboard qui agrège les données des quatre contrats.

Architecture smart contracts

Chaque module est un contrat Solidity indépendant, déployé séparément :

  • GreenVault — Gère les dépôts et retraits via un pattern approve/deposit classique. Utilise un MockUSDC (ERC-20) pour simuler le stablecoin.
  • GridFlexMarket — Crée des slots de flexibilité énergétique et gère le matching via un MockGridOracle qui simule les données réseau.
  • GreenRecsRegistry — Émet et retire des certificats environnementaux (REC) avec un système de registre on-chain.
  • EnergyGovernanceDAO — Permet de créer des propositions, voter et exécuter des décisions via un mécanisme de gouvernance simplifié.

Pourquoi des contrats séparés plutôt qu'un monolithe

Chaque module a sa propre logique métier et ses propres rôles d'accès. Les séparer permet de :

  • déployer et tester chaque module indépendamment,
  • réutiliser un module dans un autre contexte sans embarquer toute la logique,
  • garder chaque contrat sous la limite de taille du bytecode.

Les contrats communiquent via leurs adresses respectives, injectées au déploiement.

Standards utilisés

Les contrats s'appuient sur OpenZeppelin pour les briques standard : ERC-20 pour les tokens, AccessControl pour la gestion des rôles, ReentrancyGuard pour la protection contre les réentrances.

Architecture frontend

Le frontend est une app Next.js en TypeScript. L'intégration blockchain repose sur wagmi (hooks React pour Ethereum) et viem (client TypeScript pour les interactions bas niveau). RainbowKit gère la connexion wallet.

Pattern d'intégration

Chaque module a sa propre page avec :

  1. Un formulaire d'action (dépôt, création de slot, émission de REC, vote).
  2. Un hook wagmi qui appelle la fonction write du contrat.
  3. Un retour utilisateur clair : état pending, confirmation, erreur.

Le dashboard agrège les events des quatre contrats via des appels getLogs filtrés par topic. Les KPI (total déposé, slots matchés, RECs émis, propositions votées) sont calculés côté client à partir de ces events.

Pourquoi pas de backend d'indexing

Pour un MVP de démonstration, l'agrégation côté client via getLogs est suffisante. Elle évite la complexité d'un indexer (The Graph, custom backend) tout en produisant des données lisibles. La limite est la scalabilité : sur un réseau avec beaucoup de blocks, les appels getLogs deviennent lents. C'est un compromis conscient pour le MVP.

Compromis et limites

Mocks

Le projet utilise un MockUSDC et un MockGridOracle pour fonctionner en environnement local sans dépendance externe. C'est un choix volontaire : le but est de démontrer l'intégration, pas de se connecter à des oracles de production.

Couverture de tests

Les tests couvrent les fonctions critiques de chaque contrat (dépôt, retrait, matching, vote) mais ne couvrent pas tous les edge cases. C'est suffisant pour un MVP, pas pour un audit.

Environnement local

Le projet tourne sur un node Hardhat local. Le frontend est déployé sur Vercel en mode démo. Le déploiement sur testnet (Sepolia) est prévu comme prochaine étape.

Ce que ce projet m'a appris

Penser produit avant de coder. Relier quatre contrats c'est facile techniquement. Relier quatre modules dans un parcours utilisateur qui fait sens, c'est un travail de conception.

L'UX transactionnelle est un vrai sujet. Une transaction blockchain prend du temps, peut échouer, nécessite une approbation préalable. Chaque étape doit être communiquée clairement à l'utilisateur.

Documenter change la perception. Un README structuré, un script de démo, une case study — c'est ce qui transforme un repo de code en un projet présentable.

Prochaines étapes

  • Déploiement sur Sepolia avec des contrats vérifiés sur Etherscan.
  • Ajout d'un indexer léger pour remplacer les getLogs côté client.
  • Démo vidéo de 3 minutes basée sur le script de démo existant.
  • Itération UI/UX sur la base de retours utilisateurs.