lecoffre_node/docs/DETECTION_AUTOMATIQUE_FONDS.md

Détection Automatique de Fonds dans les Applications

Vue d'ensemble

Ce système implémente une détection automatique des fonds insuffisants directement dans les applications et déclenche automatiquement un transfert de fonds du wallet mining vers le relay.

Architecture

1. Détection dans les Applications

ihm_client (Frontend)

• Fichier: src/services/service.ts
• Méthode: createProcess()
• Détection: Erreurs "Insufficient funds" ou "Missing sats"
• Action: Appel automatique à l'API de transfert

try {
  const result = this.sdkClient.create_new_process(...);
  // ... traitement normal
} catch (error) {
  const errorMessage = error.toString().toLowerCase();
  if (errorMessage.includes('insufficient funds') || 
      (errorMessage.includes('missing') && errorMessage.includes('sats'))) {
    // Transfert automatique de fonds
    await this.triggerAutomaticFundsTransfer();
    // Retry automatique
    const retryResult = this.sdkClient.create_new_process(...);
  }
}

lecoffre-back (Backend)

• Fichier: src/routes/funds.routes.ts
• Endpoints:
  • POST /api/v1/funds/transfer - Transfert de fonds
  • GET /api/v1/funds/check - Vérification des fonds

2. Service de Détection

Service Node.js

• Fichier: scripts/funds/funds_detector_service.js
• Fonctionnalités:
  • Monitoring continu des fonds
  • Transfert automatique si nécessaire
  • Logs détaillés
  • Gestion des erreurs

3. Scripts de Support

Scripts Bash

• scripts/funds/simple_transfer.sh - Transfert de base
• scripts/funds/check_and_transfer_funds.sh - Vérification et transfert
• scripts/funds/monitor_funds.sh - Monitoring continu
• scripts/startup-with-funds-check.sh - Démarrage avec vérification

Flux de Fonctionnement

1. Détection Automatique

Application (ihm_client) → createProcess() → Erreur "Insufficient funds"
                        ↓
                    Détection automatique
                        ↓
                    Appel API /api/v1/funds/transfer
                        ↓
                    Transfert de fonds
                        ↓
                    Retry automatique
                        ↓
                    Succès

2. API de Transfert

POST /api/v1/funds/transfer
Content-Type: application/json

{
  "amount": 0.01,
  "source": "mining_mnemonic",
  "target": "default"
}

Réponse:

{
  "success": true,
  "message": "Transfert de 0.01 BTC réussi",
  "transactionId": "abc123...",
  "address": "tb1q...",
  "sourceBalance": 49.99,
  "targetBalance": 0.01
}

3. Vérification des Fonds

GET /api/v1/funds/check

Réponse:

{
  "success": true,
  "relay": {
    "outputsCount": 1,
    "balance": 0.01
  },
  "mining": {
    "balance": 49.99
  },
  "needsTransfer": false
}

Configuration

Variables d'Environnement

• MINING_WALLET: "mining_mnemonic" (par défaut)
• RELAY_WALLET: "default" (par défaut)
• MIN_FUNDS_THRESHOLD: 0.001 BTC (par défaut)
• TRANSFER_AMOUNT: 0.01 BTC (par défaut)

Seuils

• Seuil minimum: 0.001 BTC (100,000 sats)
• Montant de transfert: 0.01 BTC (1,000,000 sats)
• Vérification: Toutes les 30 secondes (service)

Intégration

Docker Compose

volumes:
  - ./scripts/funds:/scripts/funds:ro

Démarrage

# Démarrage avec vérification automatique
./scripts/startup-with-funds-check.sh

# Service de monitoring
node scripts/funds/funds_detector_service.js

Avantages

1. Transparence

• L'utilisateur ne voit pas l'erreur de fonds insuffisants
• Le transfert se fait automatiquement en arrière-plan
• Retry automatique après transfert

2. Fiabilité

• Détection proactive des problèmes
• Transfert automatique avant échec
• Gestion des erreurs et fallback

3. Performance

• Pas d'interruption du workflow utilisateur
• Transfert rapide (quelques secondes)
• Monitoring continu

4. Maintenance

• Logs détaillés pour debugging
• Configuration flexible
• Scripts réutilisables

Dépannage

Problèmes Courants

1. API non accessible

   # Vérifier que lecoffre-back est démarré
   docker compose ps lecoffre-back
   
   # Vérifier les logs
   docker logs lecoffre-back
   

2. Transfert échoue

   # Vérifier la connectivité Bitcoin
   docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo
   
   # Vérifier les soldes
   curl http://localhost:8080/api/v1/funds/check
   

3. Service de détection ne démarre pas

   # Vérifier les permissions
   chmod +x scripts/funds/funds_detector_service.js
   
   # Vérifier Node.js
   node --version
   

Logs

• Service de détection: /tmp/funds_detector.log
• lecoffre-back: docker logs lecoffre-back
• ihm_client: Console du navigateur

Tests

Test Manuel

# 1. Vérifier les fonds
curl http://localhost:8080/api/v1/funds/check

# 2. Transférer des fonds
curl -X POST http://localhost:8080/api/v1/funds/transfer \
  -H "Content-Type: application/json" \
  -d '{"amount": 0.01}'

# 3. Vérifier à nouveau
curl http://localhost:8080/api/v1/funds/check

Test Automatique

# Lancer le service de détection
node scripts/funds/funds_detector_service.js

# Dans un autre terminal, simuler un manque de fonds
# Le service devrait détecter et transférer automatiquement

Sécurité

• Vérification des soldes avant transfert
• Limitation des montants de transfert
• Logs de toutes les opérations
• Gestion des erreurs sécurisée

Performance

• Transfert en ~5-10 secondes
• Détection en temps réel
• Monitoring toutes les 30 secondes
• Pas d'impact sur les performances utilisateur