# Référence Technique Complète - 4NK Environment

**Date** : 2025-01-27
**Version** : 2.0
**Contexte** : Référence technique complète pour les développeurs et agents IA

## 📋 Vue d'ensemble Technique

Cette référence technique présente tous les détails techniques de l'environnement 4NK, incluant les configurations, dépendances, ports, et interfaces.

## 🔧 Modules 4NK - Référence Technique Complète

### 1. **sdk_relay** - Service de Relais WebSocket Central
**Technologie** : Rust (tokio, async-trait, futures-util)
**Ports** : 8090 (WebSocket), 8091 (HTTP health)
**Dépendances Rust** :
```toml
anyhow = "1.0"
async-trait = "0.1"
bitcoincore-rpc = { version = "0.18" }
env_logger = "0.9"
futures-util = { version = "0.3.28", default-features = false, features = ["sink", "std"] }
hex = "0.4.3"
log = "0.4.20"
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", rev = "e205229e", features = ["parallel", "blindbit-backend"] }
serde = { version = "1.0.193", features = ["derive"]}
serde_json = "1.0"
serde_with = "3.6.0"
tokio = { version = "1.0.0", features = ["io-util", "rt-multi-thread", "macros", "sync"] }
tokio-stream = "0.1"
tokio-tungstenite = "0.21.0"
zeromq = "0.4.1"
```
**Fonctionnalités** :
- Serveur WebSocket configurable
- Synchronisation mesh entre relais
- Gestion des processus et membres
- Interface avec Bitcoin Core (RPC + ZMQ)
- Intégration Blindbit pour Silent Payments
- Cache de déduplication
- Gestion d'état locale dans `~/<data_dir>`
**Configuration** : Fichier de configuration via `--config`
**Healthcheck** : `/health` sur port 8091
**Variables d'environnement** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL

### 2. **sdk_storage** - Service de Stockage Temporaire Sécurisé
**Technologie** : Rust (tide, async-std)
**Port** : 8081 (mappé depuis 8080)
**Dépendances Rust** :
```toml
tide = "0.16"
async-std = { version = "1", features = ["attributes"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
hex = "0.4"
env_logger = "0.10"
```
**API** :
- `POST /store` : Stockage avec clé/valeur/TTL
- `GET /retrieve/:key` : Récupération des données
**Fonctionnalités** :
- Stockage temporaire avec expiration
- Clés hexadécimales 64 caractères
- Valeurs hexadécimales
- TTL optionnel (permanent si non spécifié)
- Chiffrement des données
**Healthcheck** : `/health` sur port 8080
**Variables d'environnement** : STORAGE_PORT, STORAGE_DATA_DIR

### 3. **sdk_signer** - Service de Signature TypeScript
**Technologie** : TypeScript avec support WASM
**Fonctionnalités** :
- Gestion des processus et signatures
- Communication sécurisée
- Compatibilité WASM (stub temporaire)
- Interface avec le réseau de relais
- Validation des permissions
**Dépendances** : Node.js 18+, npm/yarn
**Architecture** : TypeScript avec support WASM
**État** : Compatible avec stub sdk_client

### 4. **sdk_client** - Client SDK Rust/WASM
**Technologie** : Rust avec interface WebAssembly
**Fonctionnalités** :
- Interface avec les services 4NK
- Gestion des connexions WebSocket
- Support des processus et transactions
- Compilation WASM pour le web
**Architecture** : Rust avec interface WASM
**Usage** : Importé par sdk_signer et autres clients

### 5. **sdk_common** - Bibliothèque Commune
**Technologie** : Rust
**Fonctionnalités** :
- Types et structures communes
- Utilitaires partagés
- Protocoles de communication
- Support Blindbit (feature: "blindbit-backend")
- Support parallèle (feature: "parallel")
**Usage** : Importé par tous les autres modules
**Features** : parallel, blindbit-backend

### 6. **sdk-signer-client** - Client Signeur
**Technologie** : TypeScript
**Fonctionnalités** :
- Interface avec sdk_signer
- Gestion des signatures
- Communication sécurisée
**Architecture** : TypeScript client

### 7. **ihm_client** - Interface Homme-Machine
**Technologie** : Vite + React
**Port** : 3003
**Fonctionnalités** :
- Interface de gestion des clés Bitcoin
- Gestion des processus
- Interface utilisateur web
- Variables d'environnement Vite
**Dépendances** : sdk_relay, sdk_storage
**Variables d'environnement** :
- VITE_JWT_SECRET_KEY
- VITE_API_BASE_URL
- VITE_WS_URL
- VITE_STORAGE_URL
- VITE_SIGNER_URL
- VITE_BOOTSTRAPURL

### 8. **4NK_vault** - Système de Gestion des Configurations
**Technologie** : Python Flask
**Port** : 6666 (HTTPS)
**Sécurité** :
- Authentification par clés utilisateur
- Chiffrement quantique résistant (ChaCha20-Poly1305)
- Rotation automatique des clés (toutes les heures)
- Isolation par environnement (dev, prod)
**Fonctionnalités** :
- Résolution des variables d'environnement
- Synchronisation vers `confs/` dans le docker de contrôle
- Protection des secrets
- Clés individuelles par utilisateur/environnement
**Endpoints** :
- `GET /health` - Contrôle de santé
- `GET /info` - Informations API
- `GET /routes` - Routes disponibles
- `GET /<env>/<file>` - Fichier chiffré
**Déploiement** : Synchronise les configurations vers `confs/`

### 9. **4NK_certificator** - Service d'Ancrage Cryptographique
**Technologie** : Rust
**Fonctionnalités** :
- Surveillance des messages du relay 4NK
- Détection des paiements Bitcoin
- Enregistrement périodique sur blockchain
- Métriques de volume de données
- Base de données SQLite
**Architecture** : Rust avec base de données SQLite
**État** : MVP complet implémenté
**Composants** :
- RelayMonitor (surveillance WebSocket)
- PaymentWatcher (surveillance Bitcoin)
- Base de données SQLite

### 10. **4NK_miner** - Service de Minage
**Technologie** : Rust
**Fonctionnalités** :
- Minage sur réseau Signet
- Génération de blocs de test
- Interface avec le réseau Bitcoin
**Usage** : Développement et tests uniquement

### 11. **4NK_web_status** - Service de Statut
**Technologie** : Python Flask
**Port** : 3006
**Fonctionnalités** :
- Monitoring des services
- Interface de statut
- Métriques de santé
- API REST pour le statut
**Dépendances** : Docker socket, logs directory
**Variables d'environnement** : STATUS_API_PORT, STATUS_API_HOST

### 12. **blindbit-oracle** - Oracle Bitcoin Silent Payments
**Technologie** : Rust
**Port** : 8000
**Fonctionnalités** :
- Génération d'adresses Silent Payments
- Validation des transactions
- Interface HTTP REST
- Scan filtré BIP158
**Dépendances** : Bitcoin Core
**Configuration** : blindbit.toml
**Variables d'environnement** : BLINDBIT_API_PORT, BITCOIN_RPC_URL

### 13. **rust-silentpayments** - Implémentation Silent Payments
**Technologie** : Rust
**Fonctionnalités** :
- Génération d'adresses Silent Payments
- Validation des transactions
- Utilitaires cryptographiques
**Usage** : Bibliothèque pour blindbit-oracle

## 🏢 Projet LeCoffre - Référence Technique Complète

### 1. **lecoffre_node** - Orchestrateur Principal
**Architecture** : Docker Compose avec Nginx intégré
**Services déployés** :
- **tor** (btcpayserver/tor:0.4.8.10) - Proxy anonyme
- **bitcoin** (build: ./bitcoin) - Nœud Bitcoin Signet
- **blindbit** (git.4nkweb.com/4nk/blindbit-oracle:fixed-source) - Oracle Bitcoin
- **sdk_relay** (git.4nkweb.com/4nk/sdk_relay:ext) - Relais WebSocket
- **sdk_storage** (git.4nkweb.com/4nk/sdk_storage:ext) - Stockage temporaire
- **lecoffre-front** (git.4nkweb.com/4nk/lecoffre-front:ext) - Frontend Next.js
- **ihm_client** (git.4nkweb.com/4nk/ihm_client:ext) - Interface utilisateur
- **grafana** (grafana/grafana:latest) - Monitoring
- **loki** (grafana/loki:latest) - Collecte de logs
- **promtail** (grafana/promtail:latest) - Agent de collecte
- **status-api** (build: 4NK_web_status) - API de statut
- **watchtower** (containrrr/watchtower) - Mise à jour automatique
- **signet_miner** (build: 4NK_miner) - Minage (profile: miner)

**Configuration** : Centralisée dans `confs/` (synchronisée depuis 4NK_vault)
**Déploiement** : Scripts automatisés avec phases de démarrage
**Réseau** : btcnet (172.20.0.0/16)
**Volumes** : Persistance des données (bitcoin_data, blindbit_data, sdk_data, etc.)

### 2. **lecoffre-front** - Interface Utilisateur
**Technologie** : Next.js avec React
**Port** : 3004 (mappé depuis 8080)
**Fonctionnalités** :
- Interface utilisateur pour les notaires
- Gestion des documents
- Intégration avec l'écosystème 4NK
- Variables d'environnement Next.js
**Variables d'environnement** :
- NEXT_PUBLIC_API_URL
- NEXT_PUBLIC_4NK_URL
- NEXT_PUBLIC_4NK_IFRAME_URL
- NEXT_PUBLIC_IDNOT_BASE_URL
**Déploiement** : Conteneur Docker sur port 3004
**User** : lecoffreuser (non-root)

### 3. **lecoffre-back-mini** - Backend Centralisé
**Déploiement** : Sur dev3.4nkweb.com
**Fonctionnalités** :
- APIs avec Stripe (paiements)
- Intégration Mailchimp (email marketing)
- Intégration OVH (SMS)
- Intégration IdNot (HMR dev3 ↔ dev4 via OAuth2)
**Architecture** : Service centralisé indépendant
**APIs** :
- `/api/v1/health` - Santé du service
- `/api/v1/status` - Statut du service
- `/api/v1/idnot/state` - État IdNot

## 🌐 Architecture de Déploiement - Référence Technique

### Environnements et URLs
- **dev4.4nkweb.com** : Machine principale (LeCoffre)
- **dev3.4nkweb.com** : Nœud de bootstrap (signer centralisé, mini back)

### URLs et Services
- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre
- **4NK iframe** : https://dev4.4nkweb.com
- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires)
- **Mini back** : dev3.4nkweb.com (APIs Stripe, Mailchimp, OVH, IdNot)

### Architecture de Déploiement par Phases

#### Phase 1: Services de Base (Parallèle)
- **tor** : Proxy anonyme (btcpayserver/tor:0.4.8.10)
- **sdk_storage** : Stockage temporaire (git.4nkweb.com/4nk/sdk_storage:ext)
- **status-api** : API de statut (build: 4NK_web_status)

#### Phase 2: Services Blockchain (Séquentiel)
- **bitcoin** → **blindbit** → **sdk_relay**
- Chaîne de dépendances blockchain respectée

#### Phase 3: Services Applicatifs (Séquentiel)
- **lecoffre-front** : Frontend Next.js
- **ihm_client** : Interface utilisateur
- Dépendances : sdk_relay + sdk_storage

#### Phase 4: Services de Monitoring (Indépendant)
- **loki** → **promtail** → **grafana**
- Chaîne de dépendances monitoring

#### Phase 5: Services Utilitaires
- **watchtower** : Mise à jour automatique (interval: 30s)

## 🔐 Sécurité et Configuration - Référence Technique

### 4NK_vault - Gestion Centralisée des Configurations
- **Rôle** : API sécurisée pour la gestion des configurations
- **Sécurité** :
  - Chiffrement quantique résistant (ChaCha20-Poly1305)
  - Authentification par clés utilisateur
  - Rotation automatique des clés (toutes les heures)
  - Isolation par environnement (dev, prod)
- **Déploiement** : Synchronise vers `confs/` dans le docker de contrôle
- **Protection des secrets** : Fichiers .env inaccessibles, variables séparées

### Variables d'Environnement par Service
- **bitcoin** : BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD, BITCOIN_RPC_PORT
- **blindbit** : BLINDBIT_API_PORT, BITCOIN_RPC_URL
- **sdk_relay** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL
- **sdk_storage** : STORAGE_PORT, STORAGE_DATA_DIR
- **lecoffre-front** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_IDNOT_BASE_URL
- **ihm_client** : VITE_API_URL, VITE_4NK_URL, VITE_RELAY_URL
- **grafana** : GF_SECURITY_ADMIN_PASSWORD, GF_DATABASE_TYPE
- **loki** : LOKI_CONFIG_FILE, LOKI_DATA_DIR
- **promtail** : PROMTAIL_CONFIG_FILE, LOKI_URL
- **status-api** : STATUS_API_PORT, STATUS_API_HOST

## 📊 Monitoring et Observabilité - Référence Technique

### Stack de Monitoring
- **Grafana** (grafana/grafana:latest) : Dashboards et visualisation
- **Loki** (grafana/loki:latest) : Collecte et stockage des logs
- **Promtail** (grafana/promtail:latest) : Agent de collecte des logs
- **Watchtower** (containrrr/watchtower) : Mise à jour automatique

### Configuration Loki (CRITIQUE)
- **OBLIGATOIRE** : `http_listen_address: 0.0.0.0` (pas 127.0.0.1)
- **OBLIGATOIRE** : `instance_addr: 0.0.0.0` (pas 127.0.0.1)
- **Fichier** : `/conf/loki/loki-config.yaml`
- **Healthcheck** : `wget` (pas `curl`)

### Dashboards Disponibles
- Vue d'ensemble LeCoffre
- Bitcoin & Miner
- Services Applications
- SDK Services
- Frontend Services

### Logs Centralisés
- **Répertoire** : `/home/debian/4NK_env/projects/lecoffre/lecoffre_node/logs/`
- **Services** : tor, bitcoin, blindbit, sdk_relay, sdk_storage, lecoffre-front, ihm_client, grafana, loki, promtail, status-api
- **Collecte** : Promtail → Loki → Grafana

## 🔄 CI/CD et Déploiement - Référence Technique

### Branches et Tags
- **Branche unifiée** : `ext` pour tous les dépôts 4NK
- **Branches spéciales** : `main` pour 4NK_certificator, 4NK_miner, 4NK_web_status
- **Tag Docker** : `ext` pour toutes les images
- **Déclenchement** : Push sur `ext` → Build automatique

### Scripts de Déploiement Détaillés
- **start.sh** : Démarrage complet avec phases et progression
- **validate-deployment.sh** : Validation complète du déploiement
- **maintenance.sh** : Menu de maintenance interactif
- **backup-data.sh** : Sauvegarde des données
- **update-images.sh** : Mise à jour sécurisée
- **collect-logs.sh** : Collecte des logs
- **deploy-grafana.sh** : Déploiement du monitoring
- **sync-configs.sh** : Synchronisation des configurations

### Healthchecks Détaillés
- **tor** : tor-progress.sh (bootstrap %)
- **bitcoin** : bitcoin-progress.sh (IBD, blocks, headers)
- **blindbit** : blindbit-progress.sh (API, scan)
- **sdk_relay** : sdk-relay-progress.sh (WebSocket, health)
- **sdk_storage** : curl /health
- **lecoffre-front** : ps aux | grep next-server
- **ihm_client** : curl localhost:3003
- **grafana** : curl /api/health
- **loki** : wget /ready
- **promtail** : fichier positions.yaml
- **status-api** : curl /api

## 🎯 Points Clés de l'Architecture Technique

### 1. **Séparation des Responsabilités**
- Services applicatifs indépendants du monitoring
- Monitoring observant sans impacter
- Dépendances uniquement métier

### 2. **Sécurité Multi-Niveaux**
- 4NK_vault pour la gestion centralisée des configurations
- Chiffrement quantique résistant
- Isolation des secrets et variables
- Utilisateurs non-root dans les conteneurs

### 3. **Déploiement Optimisé**
- Phases de démarrage respectées
- Scripts spécialisés obligatoires
- Surveillance continue et diagnostic facilité
- Healthchecks informatifs

### 4. **Maintenance Facilitée**
- Redémarrage sélectif possible
- Scripts de maintenance interactifs
- Documentation centralisée et à jour
- Logs centralisés et structurés

### 5. **Architecture Modulaire**
- 13 modules 4NK avec rôles spécialisés
- Projet LeCoffre : Interface notariale
- 4NK_vault : Gestion centralisée des configurations
- Scripts centralisés et réutilisables

---

**Document créé le 2025-01-27**
**Version** : 2.0
**Usage** : Référence technique complète pour les développeurs et agents IA