4NK_node/README.md

🚀 4NK Node - Infrastructure Docker Complète

Infrastructure Docker complète pour le développement et le déploiement de services 4NK avec support des paiements silencieux (Silent Payments).

📋 Table des Matières

• 🏗️ Architecture
• 🚀 Démarrage Rapide
• 📚 Documentation
• 🔧 Configuration
• 🧪 Tests et Monitoring
• 🌐 Réseau de Relais
• 🛠️ Développement
• 🚨 Dépannage

🏗️ Architecture

4NK Node est composé de plusieurs services orchestrés via Docker :

Service	Port	Description	Statut
Tor	9050, 9051	Proxy anonyme pour Bitcoin Core	✅ Stable
Bitcoin Core	18443 (RPC), 29000 (ZMQ)	Nœud Bitcoin en mode signet	✅ Stable
Blindbit	8000	Service de filtres pour les paiements silencieux	✅ Stable
sdk_relay	8090-8095	Services de relais (3 instances)	✅ Stable

🔄 Flux de Données

Client → sdk_relay → Bitcoin Core
                ↓
            Blindbit → Bitcoin Core
                ↓
            Tor (anonymat)

🚀 Démarrage Rapide

Prérequis

• Docker et Docker Compose installés
• 10 Go d'espace disque minimum
• Connexion Internet stable
• Clé SSH configurée pour Gitea (recommandé)

Installation

# 1. Cloner le repository (SSH recommandé)
git clone git@git.4nkweb.com:4nk/4NK_node.git
cd 4NK_node

# 2. Amorcer l’environnement (git, Docker, Compose, Node/npm)
./scripts/orchestrate_start.sh
# Astuce: se déconnecter/reconnecter pour activer le groupe docker

# 3. Démarrer tous les services
./scripts/restart_4nk_node.sh

# 4. Vérifier le statut
docker ps

Configuration SSH (Recommandé)

# Générer une clé SSH
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk -C "4nk-automation"

# Ajouter à l'agent SSH
ssh-add ~/.ssh/id_ed25519_4nk

# Configurer Git
git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_4nk"

# Ajouter la clé publique à Gitea
cat ~/.ssh/id_ed25519_4nk.pub

📚 Documentation

📖 Guides Principaux

• Guide d'Installation - Installation et configuration complète
• Guide d'Utilisation - Utilisation quotidienne et cas d'usage
• Guide de Configuration - Configuration avancée
• Guide de Développement - Développement et contribution

🔧 Guides Techniques

• Architecture Technique - Architecture détaillée
• API Reference - Documentation des APIs
• Sécurité - Sécurité et bonnes pratiques
• Performance - Optimisation et monitoring

🧪 Guides de Test

• Tests de Base - Tests de connectivité et fonctionnalité
• Tests de Synchronisation - Tests de synchronisation entre relais
• Tests de Performance - Tests de charge et performance

🌐 Guides Réseau

• Réseau de Relais - Configuration du réseau mesh
• Nœuds Externes - Ajout et gestion de nœuds externes
• Synchronisation - Protocole de synchronisation

🔧 Configuration

Services Disponibles

Service	Configuration	Volume	Description
Bitcoin Core	bitcoin/bitcoin.conf	bitcoin_data	Nœud Bitcoin signet avec RPC et ZMQ
Blindbit	blindbit/blindbit.toml	blindbit_data	Service de filtres Silent Payments
sdk_relay	sdk_relay/.conf.docker.*	sdk_relay_*_data	Relais avec synchronisation mesh
Tor	tor/torrc	-	Proxy anonyme

Variables d'Environnement

# Logs
RUST_LOG=debug,bitcoincore_rpc=trace

# Bitcoin
BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie

# Synchronisation
ENABLE_SYNC_TEST=1

🧪 Tests et Monitoring

Tests de Base

# Test de connectivité
./test_final_sync.sh

# Test de synchronisation
./test_sync_logs.sh

# Test des messages WebSocket
python3 test_websocket_messages.py

Monitoring

# Surveillance de la synchronisation
./monitor_sync.sh

# Logs en temps réel
docker-compose logs -f

# Statut des services
docker ps

Tests de Performance

# Test de charge WebSocket
python3 test_websocket_messages.py --load-test

# Test de synchronisation
./test_sync_logs.sh continuous

🌐 Réseau de Relais

Architecture Mesh

L'infrastructure supporte un réseau mesh de relais avec :

• 3 relais locaux : sdk_relay_1, sdk_relay_2, sdk_relay_3
• Nœuds externes : Configuration via external_nodes.conf
• Synchronisation automatique : Partage de données entre relais
• Découverte automatique : Découverte des relais voisins

Ajout de Nœuds Externes

# Ajouter un nœud externe
./add_external_node.sh add external-relay-1 external-relay-1.example.com:8090

# Lister les nœuds configurés
./add_external_node.sh list

# Tester la connectivité
./add_external_node.sh test external-relay-1

Configuration Externe

# external_nodes.conf
[relays]
external-relay-1 = "external-relay-1.example.com:8090"
dev3-relay = "dev3.4nkweb.com:443"

[discovery]
auto_discover = true
bootstrap_nodes = []

🛠️ Développement

Structure du Projet

4NK_node/
├── bitcoin/           # Configuration Bitcoin Core
├── blindbit/          # Configuration Blindbit
├── sdk_relay/         # Configuration des relais
├── tor/              # Configuration Tor
├── specs/            # Spécifications techniques
├── docs/             # Documentation
├── tests/            # Scripts de test
├── scripts/          # Scripts utilitaires
└── docker-compose.yml

Ajout d'un Nouveau Service

1. Créer le Dockerfile dans un sous-répertoire
2. Ajouter le service dans docker-compose.yml
3. Configurer les dépendances et le réseau
4. Ajouter les healthchecks si nécessaire
5. Documenter dans la section appropriée

Modification de la Configuration

# Modifier la configuration Bitcoin Core
sudo docker-compose down
# Éditer bitcoin/bitcoin.conf
sudo docker-compose up -d bitcoin

# Modifier la configuration Blindbit
# Éditer blindbit/blindbit.toml
sudo docker-compose restart blindbit

🚨 Dépannage

Problèmes Courants

1. Ports Déjà Utilisés

# Vérifier les ports utilisés
sudo netstat -tlnp | grep -E "(18443|8000|9050|8090)"

# Arrêter les services conflictuels
sudo docker-compose down

2. Problèmes de Synchronisation Bitcoin

# Vérifier les logs Bitcoin Core
sudo docker-compose logs bitcoin

# Redémarrer Bitcoin Core
sudo docker-compose restart bitcoin

3. Problèmes de Connectivité sdk_relay

# Tester la connectivité
cd sdk_relay
./test_final.sh

# Vérifier la configuration
./debug_container.sh

Logs Détaillés

# Logs avec timestamps
sudo docker-compose logs -t

# Logs des 100 dernières lignes
sudo docker-compose logs --tail=100

# Logs depuis une date
sudo docker-compose logs --since="2024-01-01T00:00:00"

Healthchecks

# Vérifier l'état des healthchecks
sudo docker-compose ps

# Logs des healthchecks
sudo docker-compose logs | grep health

# Test manuel du healthcheck sdk_relay
sudo docker exec sdk_relay /usr/local/bin/healthcheck.sh

📈 Performance

Ressources Recommandées

• CPU : 2 cœurs minimum, 4 cœurs recommandés
• RAM : 4 Go minimum, 8 Go recommandés
• Stockage : 20 Go minimum pour la blockchain signet
• Réseau : Connexion stable pour la synchronisation

Optimisations

# Limiter l'utilisation CPU
sudo docker-compose up -d --scale bitcoin=1

# Surveiller l'utilisation des ressources
sudo docker stats

# Optimiser l'espace disque
sudo docker system prune -f

🤝 Contribution

1. Fork le repository
2. Créer une branche feature (git checkout -b feature/nouvelle-fonctionnalite)
3. Commit les changements (git commit -am 'Ajout de nouvelle fonctionnalité')
4. Push la branche (git push origin feature/nouvelle-fonctionnalite)
5. Créer une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🆘 Support

Pour obtenir de l'aide :

1. Consulter la documentation
2. Vérifier les issues existantes
3. Créer une nouvelle issue avec les détails du problème
4. Inclure les logs et la configuration utilisée

---

✨ Infrastructure 4NK Node - Prête pour la production !