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 : 1.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

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

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 :

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
• 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 :

   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 :

   systemctl --user restart anchorage-api.service
   

3. Vérifier les logs :

   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 :

   curl http://localhost:3010/health
   

   Doit retourner un statut 200 avec bitcoin_connected: true

Modalités d'analyse

Vérifier la résolution DNS

# 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

# 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

# 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

# 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
• Cette correction s'applique à tous les environnements (test, pre-production, production)