@aladas-org/cryptocalc/tests/jest/unit/wallet/README_HDWALLET_TESTS.md

Cryptocurrency wallet generator

# Tests Unitaires - HD Wallet (BIP32/BIP44)

## 📋 Vue d'Ensemble

Tests complets pour la classe `HDWallet` qui gère la génération de portefeuilles hiérarchiques déterministes (Hierarchical Deterministic Wallets) selon les standards BIP32 et BIP44.

## 🎯 Classe Testée

**Fichier** : `www/js/crypto/HDWallet/hd_wallet.js`  
**Classe** : `HDWallet`  
**Standards** : BIP32, BIP44  
**Blockchains supportées** : Bitcoin, Ethereum, Litecoin, Dogecoin, Solana, Cardano, Avalanche, Polygon, et bien d'autres

## 📦 Structure des Tests

### 1. **Initialization Tests** (1 test)
Vérifie que la fonction `InitializeWallet()` crée correctement un wallet vide.

### 2. **Error Handling Tests** (4 tests)
- Entropy vide ou undefined
- UUID vide ou undefined

### 3. **Bitcoin HD Wallet Tests** (7 tests)
- Génération valide
- Adresse Bitcoin valide
- Clé privée valide
- WIF valide
- Phrase mnémonique valide
- Chemin de dérivation correct (`m/44'/0'/0'/0/0`)
- Informations de type de coin

### 4. **Ethereum HD Wallet Tests** (6 tests)
- Génération valide
- Adresse Ethereum valide
- Clé privée valide
- Phrase mnémonique valide
- Chemin de dérivation correct (`m/44'/60'/0'/0/0`)
- Informations de type de coin

### 5. **Litecoin HD Wallet Tests** (5 tests)
- Génération et validation d'adresses Litecoin
- Chemin de dérivation (`m/44'/2'/0'/0/0`)

### 6. **Dogecoin HD Wallet Tests** (5 tests)
- Génération et validation d'adresses Dogecoin
- Chemin de dérivation (`m/44'/3'/0'/0/0`)

### 7. **Avalanche HD Wallet Tests** (5 tests)
- Wallets compatibles Ethereum
- Utilise le chemin de dérivation Ethereum (`m/44'/60'/0'/0/0`)

### 8. **Polygon HD Wallet Tests** (4 tests)
- Wallets compatibles Ethereum
- Utilise le chemin de dérivation Ethereum

### 9. **Solana HD Wallet Tests** (4 tests)
- API HD spécifique à Solana
- Format d'adresse Base58

### 10. **Cardano HD Wallet Tests** (4 tests)
- API HD spécifique à Cardano
- Format d'adresse Cardano (`addr1...`)

### 11. **Derivation Path Variations Tests** (3 tests)
- Adresses différentes pour différents index
- Adresses différentes pour différents comptes
- BIP32 vs BIP44

### 12. **BIP32 Passphrase Support Tests** (3 tests)
- Passphrases différentes génèrent des adresses différentes
- Stockage du passphrase
- Comportement sans passphrase

### 13. **Default Values Tests** (4 tests)
- Valeurs par défaut quand les args sont minimaux
- Blockchain par défaut (Bitcoin)
- Protocole par défaut (BIP44)
- Compte et index par défaut (0, 0)

### 14. **Cross-Blockchain Consistency Tests** (3 tests)
- Même entropy → même mnémonique pour toutes les blockchains
- Même entropy → adresses différentes pour blockchains différentes
- Tous les HD wallets ont le mode `HD_WALLET_TYPE`

### 15. **Testnet Support Tests** (2 tests)
- Bitcoin testnet
- Ethereum testnet

## 📊 Statistiques

- **Total des tests** : ~75 tests
- **Blockchains testées** : 10+ (Bitcoin, Ethereum, Litecoin, Dogecoin, Solana, Cardano, Avalanche, Polygon, etc.)
- **Scénarios couverts** : 
  - Génération basique
  - Gestion d'erreurs
  - Chemins de dérivation
  - Passphrases BIP32
  - Valeurs par défaut
  - Testnet
  - Consistance multi-blockchain

## 🔧 Configuration

### Arguments de GetWallet

La méthode `HDWallet.GetWallet()` accepte les paramètres suivants :

```javascript
const args = {
  [BLOCKCHAIN]: BITCOIN,        // Blockchain cible
  [CRYPTO_NET]: MAINNET,        // mainnet ou testnet
  [BIP32_PROTOCOL]: 44,         // 32 ou 44
  [BIP32_PASSPHRASE]: '',       // Passphrase optionnelle
  [ACCOUNT]: 0,                 // Index du compte
  [ADDRESS_INDEX]: 0            // Index de l'adresse
};

const wallet = await HDWallet.GetWallet(entropy, uuid, args);
```

### Chemins de Dérivation BIP44

Format : `m / purpose' / coin_type' / account' / change / address_index`

**Exemples :**
- Bitcoin : `m/44'/0'/0'/0/0`
- Ethereum : `m/44'/60'/0'/0/0`
- Litecoin : `m/44'/2'/0'/0/0`
- Dogecoin : `m/44'/3'/0'/0/0`

## ✅ Propriétés Vérifiées

Pour chaque blockchain, les tests vérifient :

1. **Wallet valide** : Structure correcte et définie
2. **Blockchain** : Identifiant de blockchain correct
3. **Mode** : `HD_WALLET_TYPE` pour tous les HD wallets
4. **Adresse** : Format valide selon la blockchain
5. **Clé privée** : Hash hexadécimal de 64 caractères
6. **Mnémonique** : Phrase de 12, 18 ou 24 mots valide
7. **Chemin de dérivation** : Conforme au standard BIP44
8. **Type de coin** : Valeur correcte selon BIP44
9. **WIF** : Format WIF valide (pour blockchains compatibles)

## 🚀 Exécution

### Lancer tous les tests
```bash
npm run test:jest
```

### Lancer uniquement les tests HD Wallet
```bash
npm test -- hd_wallet.test.js
```

### Lancer avec coverage
```bash
npm run test:jest:coverage
```

### Mode watch
```bash
npm run test:jest:watch
```

## 📝 Exemple de Test

```javascript
describe('Bitcoin HD Wallet (BIP44)', () => {
  let wallet;
  
  beforeAll(async () => {
    const args = {
      [BLOCKCHAIN]: BITCOIN,
      [CRYPTO_NET]: MAINNET,
      [BIP32_PROTOCOL]: 44,
      [ACCOUNT]: 0,
      [ADDRESS_INDEX]: 0
    };
    wallet = await HDWallet.GetWallet(testEntropy, testUuid, args);
  });
  
  test('has valid Bitcoin address', () => {
    expect(wallet[ADDRESS]).toBeDefined();
    expect(wallet[ADDRESS]).toBeValidBitcoinAddress();
  });
  
  test('has correct derivation path', () => {
    expect(wallet[DERIVATION_PATH]).toBeDefined();
    expect(wallet[DERIVATION_PATH]).toMatch(/^m\/44'\/0'\/0'\/0\/0$/);
  });
});
```

## 🔍 Matchers Personnalisés

Les tests utilisent les matchers Jest personnalisés définis dans `setup.js` :

- `toBeValidHash(length)` : Vérifie un hash hexadécimal
- `toBeValidBitcoinAddress()` : Vérifie une adresse Bitcoin
- `toBeValidEthereumAddress()` : Vérifie une adresse Ethereum
- `toBeValidWIF()` : Vérifie un format WIF
- `toBeValidMnemonic()` : Vérifie une phrase mnémonique

## ⚠️ Notes Importantes

### 1. Tests Asynchrones
Tous les tests de génération de wallets sont asynchrones car `HDWallet.GetWallet()` est une fonction async :

```javascript
test('generates a valid wallet', async () => {
  const wallet = await HDWallet.GetWallet(entropy, uuid, args);
  expect(wallet).toBeDefined();
});
```

### 2. beforeAll vs beforeEach
Les tests utilisent `beforeAll()` pour générer les wallets une seule fois par suite, car la génération est coûteuse en temps.

### 3. Entropy Déterministe
Les tests utilisent une entropy fixe (`CRYPTO_CONFIG.TEST_ENTROPY_256`) pour garantir des résultats reproductibles.

### 4. Blockchains avec APIs Spéciales
Certaines blockchains (Solana, Cardano, SUI) utilisent leurs propres APIs HD et peuvent avoir des comportements légèrement différents.

## 🐛 Débogage

### Voir les logs de génération
Même si les logs sont supprimés pendant les tests, vous pouvez temporairement les réactiver :

```javascript
// Dans le test
beforeAll(() => {
  const { PrettyLog, PRODUCTION_LOG_MODE } = require('@util/log/log_utils.js');
  PrettyLog.This.logMode = PRODUCTION_LOG_MODE; // Réactive les logs
});
```

### Inspecter un wallet
```javascript
test('inspect wallet structure', async () => {
  const wallet = await HDWallet.GetWallet(testEntropy, testUuid, args);
  console.log(JSON.stringify(wallet, null, 2));
});
```

## 📦 Installation

```bash
# Placer le fichier de test
cp hd_wallet.test.js tests/jest/unit/wallet/hd_wallet.test.js

# Lancer les tests
npm run test:jest
```

## 🎯 Résultat Attendu

```
 PASS  tests/jest/unit/wallet/hd_wallet.test.js
  HD Wallet Generation (BIP32/BIP44)
    HDWallet Initialization
      ✓ InitializeWallet creates null wallet with correct structure
    Error Handling
      ✓ throws error when entropy_hex is undefined
      ✓ throws error when entropy_hex is empty string
      ✓ throws error when salt_uuid is undefined
      ✓ throws error when salt_uuid is empty string
    Bitcoin HD Wallet (BIP44)
      ✓ generates a valid Bitcoin HD wallet
      ✓ has valid Bitcoin address
      ✓ has valid private key
      ✓ has valid WIF
      ✓ has valid mnemonic phrase
      ✓ has correct derivation path
      ✓ has coin type information
    Ethereum HD Wallet (BIP44)
      ✓ generates a valid Ethereum HD wallet
      ✓ has valid Ethereum address
      [... etc ...]

Test Suites: 1 passed, 1 total
Tests:       75 passed, 75 total
Snapshots:   0 total
Time:        X.XXXs
```

## 🚀 Améliorations Futures

1. **Tests de Performance** : Mesurer le temps de génération
2. **Tests de Mémoire** : Vérifier les fuites mémoire
3. **Tests de Sécurité** : Vérifier l'unicité des clés privées
4. **Tests d'Intégration** : Vérifier la compatibilité avec des wallets réels
5. **Tests de Fixtures** : Utiliser des fichiers JSON de test

---

**Auteur** : Claude (Anthropic)  
**Date** : 2025-02-13  
**Version** : 1.0  
**Blockchain Standards** : BIP32, BIP44