# Stack, outils, code — guide complet (dépôt autonome)

Ce fichier complète [`README.md`](../README.md) (choix techniques) et [`documentation/README.md`](README.md) (utilisation du token). **Aucun autre dépôt n’est requis** : tout est sous `README.md`, `code/`, `deployment/`, `documentation/`.

---

## 1. Autonomie du rendu

| Question | Réponse |
|----------|---------|
| Faut-il un dossier `docs/` externe ? | **Non.** |
| Le token fonctionne sans redeploy ? | **Oui** — contrat déjà sur BSC Testnet ; voir [`deployment/addresses.json`](../deployment/addresses.json). |
| Que faire après `git clone` ? | Suivre [§2 Parcours](#2-parcours-rendre-le-projet-opérationnel) ci-dessous. |
| Où est le « vrai » code du token ? | [`code/contracts/FGC42Forge.sol`](../code/contracts/FGC42Forge.sol) |

---

## 2. Parcours : rendre le projet opérationnel

### A — Correcteur / utilisateur (sans redeploy)

Objectif : **comprendre** et **utiliser** FG42 on-chain.

1. Lire le [README racine](../README.md) (adresse, réseau, choix).
2. Suivre [`documentation/README.md`](README.md) : MetaMask testnet, importer le contrat, transfer.
3. Vérifier sur [BscScan token](https://testnet.bscscan.com/token/0x0c76df26A1149fDc22C8f994975705271b070fF4) et onglet **Contract** (source vérifiée).

**Prérequis :** navigateur + extension **MetaMask** + un peu de **tBNB** (faucet) sur le compte qui envoie des FG42.

### B — Développeur (tests locaux Hardhat)

Objectif : compiler et lancer les **tests automatisés** (chaîne simulée, pas de gas réel).

```bash
# Depuis la racine du dépôt Git (contenu de ce rendu)
cd code
npm install
npx hardhat build          # compile Solidity → artifacts locaux
npx hardhat test --grep FGC42Forge   # 2 tests attendus
```

| Étape | Rôle |
|-------|------|
| `cd code` | Hardhat lit `hardhat.config.ts` **uniquement** dans ce dossier. |
| `npm install` | Installe Hardhat, OpenZeppelin, ethers, Mocha (voir `package.json`). |
| `npx hardhat build` | Télécharge le compilateur Solidity si besoin, compile les contrats. |
| `npx hardhat test` | Exécute les tests ; `--grep FGC42Forge` limite au token du sujet. |

### C — Développeur (redéployer sur testnet — optionnel)

Le projet est **déjà déployé**. Pour **reproduire** un deploy :

1. `cd code && cp .env.example .env` — renseigner `PRIVATE_KEY` (compte test) et `BSC_TESTNET_RPC`.
2. Obtenir **tBNB** (faucet).
3. `npx hardhat ignition deploy --network bscTestnet ignition/modules/FGC42Forge.ts`
4. Mettre à jour [`deployment/addresses.json`](../deployment/addresses.json) et le README racine.

Détails : [`deployment/README.md`](../deployment/README.md).

---

## 3. Glossaire — chaque outil du projet

### Langage et contrat

| Terme | Définition | Rôle dans **ce** projet |
|-------|------------|-------------------------|
| **Solidity** | Langage de smart contracts pour chaînes **EVM** (Ethereum, BSC, etc.). | Fichier principal : [`FGC42Forge.sol`](../code/contracts/FGC42Forge.sol). |
| **Smart contract** | Programme déployé on-chain à une **adresse** fixe ; état (soldes) stocké sur la blockchain. | Le token FG42 est un contrat BEP-20. |
| **BEP-20** | Standard de jeton **fongible** sur BNB Chain (équivalent fonctionnel à **ERC-20**). | Respecté via OpenZeppelin `ERC20` + deploy sur BSC Testnet. |
| **OpenZeppelin** | Bibliothèque Solidity auditée (`ERC20`, `Ownable`). | Évite de réécrire `transfer`, `balanceOf`, etc. |

### Environnement de développement (off-chain)

| Terme | Définition | Rôle dans **ce** projet |
|-------|------------|-------------------------|
| **Node.js / npm** | Runtime JavaScript + gestionnaire de paquets. | Exécute Hardhat et les tests TypeScript. |
| **Hardhat** | **Framework** de développement Ethereum : compile Solidity, tests, réseaux, deploy. | Projet dans `code/` ; config : [`hardhat.config.ts`](../code/hardhat.config.ts). |
| **Hardhat Ignition** | Sous-système de **déploiement déclaratif** (modules TypeScript). | [`ignition/modules/FGC42Forge.ts`](../code/ignition/modules/FGC42Forge.ts). |
| **Mocha** | Framework de tests JavaScript. | Lance les fichiers `code/test/*.ts`. |
| **ethers.js** | Bibliothèque pour parler à la blockchain (deploy, appels, signatures). | Utilisée dans les tests via `network.create()`. |
| **TypeScript** | JavaScript typé. | Tests, config Hardhat, module Ignition (`.ts`). |

### Alternatives citées par le sujet (non utilisées ici)

| Outil | À quoi ça sert | Pourquoi Hardhat a été choisi |
|-------|----------------|-------------------------------|
| **Remix** | IDE web Solidity, compile + deploy dans le navigateur. | Tests reproductibles en CLI, Ignition, dépôt `code/` structuré. |
| **Truffle** | Ancien framework compile / migrate / test. | Hardhat 3 plus actif, même écosystème npm. |
| **Foundry** | Toolkit Rust (`forge`, `cast`) très rapide pour Solidity. | Stack 42 / Node déjà en place ; Mocha + Hardhat suffisants pour ce token simple. |

### Blockchain publique (on-chain)

| Terme | Définition | Rôle dans **ce** projet |
|-------|------------|-------------------------|
| **BNB Smart Chain (BSC)** | Blockchain EVM ; partenaire du sujet Tokenizer. | **Testnet** uniquement (pas de mainnet / argent réel). |
| **Testnet** | Copie publique de la chaîne pour développeurs ; jetons sans valeur. | Chain ID **97**, gas en **tBNB**. |
| **tBNB** | BNB de test pour payer le **gas** (frais de transaction). | Faucet BNB Chain ; requis pour deploy et transfers MetaMask. |
| **RPC** | URL HTTP vers un nœud qui lit/écrit la chaîne. | `BSC_TESTNET_RPC` dans `.env` ; même URL que MetaMask (voir doc utilisateur). |
| **Gas** | Coût d’exécution d’une transaction (deploy, `transfer`). | Payé en tBNB ; les FG42 ne paient pas le gas (séparé du token). |
| **BscScan** | **Explorateur** : adresses, transactions, code source vérifié. | Preuve du deploy + historique des transfers. |

### Wallet (interface utilisateur)

| Terme | Définition | Rôle dans **ce** projet |
|-------|------------|-------------------------|
| **MetaMask** | Extension navigateur **wallet** : stocke des comptes (clés), signe des txs, affiche soldes. | Importer FG42 par **adresse du contrat** ; envoyer des FG42 ; réseau BSC Testnet. |
| **Adresse `0x…`** | Identifiant public d’un compte ou d’un contrat (40 hex après `0x`). | Contrat token : voir README racine ; compte deployer dans `addresses.json`. |
| **Clé privée / seed** | Secret qui contrôle un compte. | **Uniquement** dans `code/.env` local pour Hardhat ; **jamais** dans Git. MetaMask garde la clé dans l’extension. |

**MetaMask n’est pas obligatoire pour corriger le code** : les tests Hardhat simulent la chaîne. En **démo sujet**, MetaMask prouve l’usage réel du token BEP-20.

---

## 4. Carte du code (où trouver quoi)

| Chemin | Contenu |
|--------|---------|
| [`code/contracts/FGC42Forge.sol`](../code/contracts/FGC42Forge.sol) | Contrat token : constructeur, supply fixe, NatSpec, sécurité. |
| [`code/test/FGC42Forge.ts`](../code/test/FGC42Forge.ts) | Tests : nom/symbole/supply, `transfer`, `owner`. |
| [`code/hardhat.config.ts`](../code/hardhat.config.ts) | Solidity 0.8.34, optimizer production, réseau `bscTestnet`. |
| [`code/ignition/modules/FGC42Forge.ts`](../code/ignition/modules/FGC42Forge.ts) | Déploiement du contrat sur le réseau choisi. |
| [`code/.env.example`](../code/.env.example) | Modèle `RPC` + `PRIVATE_KEY` (sans secrets). |
| [`deployment/addresses.json`](../deployment/addresses.json) | Adresse officielle, chainId, liens explorer. |
| [`deployment/FGC42Forge_flat.sol`](../deployment/FGC42Forge_flat.sol) | Source aplati pour vérification BscScan. |
| [`deployment/BSCSCAN_VERIFICATION.md`](../deployment/BSCSCAN_VERIFICATION.md) | Paramètres de vérification explorer. |

Fichiers **template Hardhat** (hors token évalué) : `Counter.sol`, `test/Counter.ts` — ignorés en soutenance sauf question sur le template.

---

## 5. Explication rapide du contrat (lien code)

Le contrat **hérite** de `ERC20` et `Ownable` :

1. **Constructeur** : définit nom `FGC42Forge`, symbole `FG42`, définit l’`owner`, appelle `_mint` une fois pour **1 000 000 × 10¹⁸** unités vers le déployeur.
2. **Pas de `mint` exposé** : `totalSupply` ne peut plus augmenter via ce contrat.
3. **Fonctions utilisées en démo** : `transfer`, `balanceOf`, `totalSupply`, `name`, `symbol` (héritées ERC-20).

Détail ligne par ligne : commentaires dans [`FGC42Forge.sol`](../code/contracts/FGC42Forge.sol) et index [`code/README.md`](../code/README.md).

---

## 6. Commandes Hardhat — récapitulatif

Toutes depuis **`code/`** :

| Commande | À quoi elle sert |
|----------|------------------|
| `npm install` | Installe les dépendances du projet (`package.json`). |
| `npx hardhat build` | Compile les contrats Solidity. |
| `npx hardhat test` | Lance tous les tests (FGC42Forge + Counter template). |
| `npx hardhat test --grep FGC42Forge` | Tests **uniquement** du token du sujet. |
| `npx hardhat ignition deploy --network bscTestnet ignition/modules/FGC42Forge.ts` | Déploie le contrat sur BSC Testnet (gas tBNB, `.env` requis). |
| `npx hardhat flatten contracts/FGC42Forge.sol` | Produit un fichier unique pour BscScan (voir deployment). |

---

## 7. Documentation sujet — où c’est couvert

| Exigence sujet | Fichier(s) dans ce dépôt |
|----------------|---------------------------|
| README : choix + pourquoi | [`../README.md`](../README.md) § Choix techniques |
| `code/` commenté, lisible | [`FGC42Forge.sol`](../code/contracts/FGC42Forge.sol), [`code/README.md`](../code/README.md) |
| `deployment/` + adresse + réseau | [`deployment/`](../deployment/), README racine |
| Comprendre + utiliser le token | [`documentation/README.md`](README.md) |
| Whitepaper léger (rôle, limites) | [`documentation/README.md`](README.md) § 5 |