4nk/4NK_env
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_env/docs/TECHNICAL_REFERENCE.md

15 KiB
Raw Blame History

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 :

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 :

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

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