sdk_client — bibliothèque cliente Silent Payments (WASM)
Ce dépôt fournit une bibliothèque cliente visant l’intégration WebAssembly pour gérer appareil, portefeuille, processus et échanges chiffrés associés aux Silent Payments. Cette documentation renvoie vers docs/ pour les spécifications détaillées, sans exemples exécutables.
📋 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 GitLab (recommandé)
Installation
# 1. Cloner le repository (SSH recommandé)
git clone git@git.4nkweb.com:4nk/4NK_node.git
cd 4NK_node
# 2. Démarrer tous les services
./restart_4nk_node.sh
# 3. 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 à GitLab
cat ~/.ssh/id_ed25519_4nk.pub
📚 Documentation
📖 Guides Principaux
🔧 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
La surface de code est centrée sur src/ (Rust) avec export WASM. Les parcours et invariants sont décrits dans docs/ARCHITECTURE.md et docs/API.md.
Ajout d'un Nouveau Service
- Créer le Dockerfile dans un sous-répertoire
- Ajouter le service dans
docker-compose.yml - Configurer les dépendances et le réseau
- Ajouter les healthchecks si nécessaire
- 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
Les bonnes pratiques d’optimisation, d’observabilité et de limites à la frontière WASM sont présentes dans docs/ARCHITECTURE.md.
🤝 Contribution
- Fork le repository
- Créer une branche feature (
git checkout -b feature/nouvelle-fonctionnalite) - Commit les changements (
git commit -am 'Ajout de nouvelle fonctionnalité') - Push la branche (
git push origin feature/nouvelle-fonctionnalite) - 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 :
- Consulter la documentation
- Vérifier les issues existantes
- Créer une nouvelle issue avec les détails du problème
- Inclure les logs et la configuration utilisée
Documentation de référence: voir docs/ pour la table des matières.