## 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](#️-architecture)
- [🚀 Démarrage Rapide](#-démarrage-rapide)
- [📚 Documentation](#-documentation)
- [🔧 Configuration](#-configuration)
- [🧪 Tests et Monitoring](#-tests-et-monitoring)
- [🌐 Réseau de Relais](#-réseau-de-relais)
- [🛠️ Développement](#️-développement)
- [🚨 Dépannage](#-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

```bash
# 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é)

```bash
# 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

- **[Guide d'installation](docs/INSTALLATION.md)**
- **[Guide d'utilisation](docs/USAGE.md)**
- **[Guide de configuration](docs/CONFIGURATION.md)**
- **[Architecture](docs/ARCHITECTURE.md)**
- **[Référence API](docs/API.md)**

### 🔧 Guides Techniques

- **[Architecture Technique](docs/ARCHITECTURE.md)** - Architecture détaillée
- **[API Reference](docs/API.md)** - Documentation des APIs
- **[Sécurité](docs/SECURITY.md)** - Sécurité et bonnes pratiques
- **[Performance](docs/PERFORMANCE.md)** - Optimisation et monitoring

### 🧪 Guides de Test

- **[Tests de Base](docs/TESTING.md)** - Tests de connectivité et fonctionnalité
- **[Tests de Synchronisation](docs/SYNC_TESTING.md)** - Tests de synchronisation entre relais
- **[Tests de Performance](docs/PERFORMANCE_TESTING.md)** - Tests de charge et performance

### 🌐 Guides Réseau

- **[Réseau de Relais](docs/RELAY_NETWORK.md)** - Configuration du réseau mesh
- **[Nœuds Externes](docs/EXTERNAL_NODES.md)** - Ajout et gestion de nœuds externes
- **[Synchronisation](docs/SYNCHRONIZATION.md)** - 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

```bash
# 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

```bash
# Test de connectivité
./test_final_sync.sh

# Test de synchronisation
./test_sync_logs.sh

# Test des messages WebSocket
python3 test_websocket_messages.py
```

### Monitoring

```bash
# Surveillance de la synchronisation
./monitor_sync.sh

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

# Statut des services
docker ps
```

### Tests de Performance

```bash
# 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

```bash
# 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

```toml
# 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

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

```bash
# 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

```bash
# 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

```bash
# 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

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

# Vérifier la configuration
./debug_container.sh
```

### Logs Détaillés

```bash
# 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

```bash
# 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

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](docs/)
2. Vérifier les [issues existantes](https://git.4nkweb.com/4nk/4NK_node/issues)
3. Créer une nouvelle issue avec les détails du problème
4. Inclure les logs et la configuration utilisée

---

**Documentation de référence: voir `docs/` pour la table des matières.**