anchorage_layer_simple/fixKnowledge/anchor-api-ipv6-connection-error.md

# Problème de connexion IPv6 de l'API d'ancrage

**Auteur** : Équipe 4NK  
**Date** : 2026-01-26  
**Version** : 2.0

## Problème

L'API d'ancrage tente de se connecter au nœud Bitcoin via IPv6 (`::1:38332`) alors que le nœud Bitcoin n'écoute probablement que sur IPv4.

### Symptômes

- Erreurs de connexion lors des appels RPC Bitcoin
- Tentatives de connexion sur `::1:38332` (IPv6) au lieu de `127.0.0.1:38332` (IPv4)
- Échec des ancrages de documents

### Impact

- **Fonctionnalité** : Les ancrages de documents ne fonctionnent pas
- **Service** : L'API d'ancrage ne peut pas communiquer avec le nœud Bitcoin
- **Utilisateurs** : Impossible d'ancrer des documents sur la blockchain

## Root causes

1. **Valeur par défaut `localhost`** : Le code utilisait `localhost` comme valeur par défaut, qui peut être résolu en IPv6 (`::1`) selon la configuration système
2. **Configuration système** : Le système peut avoir une préférence IPv6, ce qui fait que `localhost` résout vers `::1` au lieu de `127.0.0.1`
3. **Nœud Bitcoin** : Le nœud Bitcoin n'écoute que sur IPv4 (`127.0.0.1`), pas sur IPv6
4. **Résolution DNS Node.js** : Node.js peut préférer IPv6 lors de la résolution DNS, même si `127.0.0.1` est utilisé directement, la bibliothèque `bitcoin-core` peut effectuer des résolutions DNS internes qui aboutissent à IPv6

## Correctifs

### Modifications du code

1. **`api-anchorage/src/bitcoin-rpc.js`** :
   - Ligne 13 : Remplacement de `'localhost'` par `'127.0.0.1'` dans le constructeur
   - Ligne 234 : Remplacement de `'localhost'` par `'127.0.0.1'` dans la fonction `createAnchorTransaction`
   - Ajout de `dns.setDefaultResultOrder('ipv4first')` au début du fichier pour forcer Node.js à préférer IPv4 lors de la résolution DNS

2. **`api-anchorage/.env.example`** :
   - Ligne 2 : Remplacement de `BITCOIN_RPC_HOST=localhost` par `BITCOIN_RPC_HOST=127.0.0.1`

### Configuration

Le fichier `.env` doit utiliser `127.0.0.1` au lieu de `localhost` :

```env
BITCOIN_RPC_HOST=127.0.0.1
```

## Evolutions

- **Valeur par défaut sécurisée** : Le code utilise maintenant `127.0.0.1` par défaut, forçant IPv4
- **Configuration DNS Node.js** : Ajout de `dns.setDefaultResultOrder('ipv4first')` pour forcer Node.js à préférer IPv4 même si le système préfère IPv6
- **Documentation** : Le fichier `.env.example` reflète la bonne pratique

## Pages affectées

- `api-anchorage/src/bitcoin-rpc.js` : Constructeur et fonction `createAnchorTransaction`
- `api-anchorage/.env.example` : Configuration d'exemple
- `api-anchorage/.env` : Configuration de production (déjà corrigée)

## Modalités de déploiement

1. **Vérifier la configuration `.env`** :
   ```bash
   cd /home/ncantu/Bureau/code/bitcoin/api-anchorage
   grep BITCOIN_RPC_HOST .env
   ```
   Doit afficher : `BITCOIN_RPC_HOST=127.0.0.1`

2. **Redémarrer le service** :
   ```bash
   systemctl --user restart anchorage-api.service
   ```

3. **Vérifier les logs** :
   ```bash
   journalctl --user -u anchorage-api.service -f
   ```
   Vérifier que les connexions se font bien sur `127.0.0.1:38332` et non sur `::1:38332`

4. **Tester la connexion** :
   ```bash
   curl http://localhost:3010/health
   ```
   Doit retourner un statut `200` avec `bitcoin_connected: true`

## Modalités d'analyse

### Vérifier la résolution DNS

```bash
# Vérifier la résolution de localhost
getent hosts localhost
# Peut retourner ::1 (IPv6) ou 127.0.0.1 (IPv4)

# Vérifier la résolution de 127.0.0.1
getent hosts 127.0.0.1
# Doit retourner 127.0.0.1
```

### Vérifier l'écoute du nœud Bitcoin

```bash
# Vérifier sur quel port/IP le nœud Bitcoin écoute
ss -tlnp | grep 38332
# Doit afficher 127.0.0.1:38332 (IPv4)
```

### Vérifier les logs de l'API

```bash
# Vérifier les tentatives de connexion
journalctl --user -u anchorage-api.service | grep -i "connection\|rpc\|bitcoin"
# Vérifier qu'il n'y a plus d'erreurs de connexion IPv6
```

### Tester la connexion RPC directement

```bash
# Tester la connexion RPC avec IPv4
curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}' -H 'content-type: text/plain;' http://127.0.0.1:38332/

# Tester avec localhost (peut échouer si résolu en IPv6)
curl --user bitcoin:bitcoin --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}' -H 'content-type: text/plain;' http://localhost:38332/
```

## Notes

- Le problème peut persister si le service n'est pas redémarré après modification du `.env`
- Le code utilise maintenant `127.0.0.1` par défaut, ce qui garantit l'utilisation d'IPv4 même si la variable d'environnement n'est pas définie
- La configuration `dns.setDefaultResultOrder('ipv4first')` garantit que Node.js préfère IPv4 même si le système a une préférence IPv6
- Cette correction s'applique à tous les environnements (test, pre-production, production)