4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: alignement complet sur le niveau de documentation de 4NK_node - Correction de l'INDEX.md pour sdk_common (au lieu de 4NK_node) - Transformation complète de l'INSTALLATION.md pour bibliothèque Rust (au lieu de Docker) - Remplacement total de l'USAGE.md pour SDK commun (compilation, intégration, types) - Transformation complète de l'ARCHITECTURE.md pour bibliothèque commune (types, traits, utils) - Documentation spécifique au développement de bibliothèque Rust - Structure cohérente et navigation intuitive - Guides pratiques et techniques complets pour sdk_common

Browse Source
This commit is contained in:
Nicolas Cantu 2025-08-25 19:44:24 +02:00
parent ae95dbfaeb
commit b4dcadbb34
4 changed files with 1350 additions and 1504 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

847
docs/ARCHITECTURE.md
View File

@ -1,465 +1,572 @@
# Architecture Technique - 4NK Node # Architecture Technique - sdk_common
Ce guide décrit l'architecture technique détaillée de l'infrastructure 4NK Node, incluant la synchronisation entre relais et les composants système. Ce guide décrit l'architecture technique détaillée de la bibliothèque commune sdk_common pour les Silent Payments Bitcoin.
## Vue d'Ensemble de l'Architecture ## Vue d'Ensemble de l'Architecture
L'infrastructure 4NK Node est composée de plusieurs services interconnectés qui forment un système distribué pour les paiements silencieux Bitcoin. La bibliothèque sdk_common est conçue comme une couche d'abstraction commune pour les Silent Payments, fournissant des types, traits et utilitaires partagés entre sdk_client et sdk_relay.
### Architecture Générale ### Architecture Générale
``` ```
┌─────────────────────────────────────────────────────────────┐
│ sdk_common │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ Types │ │ Traits │ │ Utils │ │
│ │ │ │ │ │ │ │
│ │ • Wallet │ │ • WalletOps │ │ • Validation │ │
│ │ • Transaction │ │ • PaymentOps │ │ • Serialize │ │
│ │ • SilentPayment │ │ • NetworkOps │ │ • Crypto │ │
│ │ • Address │ │ • ErrorOps │ │ • Encoding │ │
│ └─────────────────┘ └─────────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Bitcoin Core │ │ Blindbit │ │ SDK Relay 1 │ │ sdk_client │ │ sdk_relay │ │ Applications │
│ (Signet) │ │ (Service SP) │ │ (WebSocket) │ │ (WASM/JS) │ │ (Rust) │ │ (Rust/JS) │
│ Port: 18443 │ │ Port: 8000 │ │ Port: 8090 │ │ │ │ │ │ │
│ • Frontend │ │ • Backend │ │ • Intégration │
│ • WebAssembly │ │ • WebSocket │ │ • API │
│ • TypeScript │ │ • HTTP API │ │ • CLI │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Docker Network │
│ (btcnet) │
└─────────────────┘
│
┌─────────────────┐
│ SDK Relay 2 │
│ (WebSocket) │
│ Port: 8092 │
└─────────────────┘
│
┌─────────────────┐
│ SDK Relay 3 │
│ (WebSocket) │
│ Port: 8094 │
└─────────────────┘
``` ```
## Composants Principaux ## Composants Principaux
### 1. Bitcoin Core (Nœud Signet) ### 1. Module Types
**Rôle :** Nœud Bitcoin Core configuré en mode signet pour le développement et les tests. **Rôle :** Définition des structures de données fondamentales pour les Silent Payments.
**Caractéristiques :** **Structures principales :**
- **Port RPC :** 18443
- **Port ZMQ :** 29000
- **Réseau :** Signet
- **Validation :** Complète des transactions
- **Stockage :** Blockchain complète
- **Interface :** JSON-RPC
**Fonctionnalités :**
- Validation des transactions
- Stockage de la blockchain
- Interface RPC pour les interactions
- Support des wallets
- Notifications ZMQ pour les événements
### 2. Service Blindbit
**Rôle :** Service pour les paiements silencieux (Silent Payments).
**Caractéristiques :**
- **Port :** 8000
- **Interface :** HTTP REST API
- **Protocole :** HTTP
**Fonctionnalités :**
- Génération d'adresses de paiement silencieux
- Validation des transactions
- Interface HTTP pour les interactions
- Gestion des clés et signatures
### 3. Service SDK Relay
**Rôle :** Relais pour les interactions SDK avec synchronisation mesh.
**Caractéristiques :**
- **Port WebSocket :** 8090
- **Port HTTP :** 8091
- **Protocole :** WebSocket/WSS
- **Synchronisation :** Mesh network
**Fonctionnalités :**
- Connexion au nœud Bitcoin Core
- Gestion des wallets
- Interface WebSocket
- Scan des blocs pour les paiements silencieux
- Synchronisation entre relais
- Cache de déduplication
## Architecture de Synchronisation
### Gestionnaire de Synchronisation (`SyncManager`)
Le `SyncManager` est le composant central qui gère toute la logique de synchronisation entre les relais :
```rust ```rust
pub struct SyncManager { // Wallet - Gestion des clés et identités
relay_id: String, pub struct Wallet {
sequence_counter: Arc<Mutex<u64>>, pub private_key: PrivateKey,
sync_cache: Arc<Mutex<HashMap<String, Instant>>>, pub public_key: PublicKey,
last_sync: Arc<Mutex<HashMap<SyncType, u64>>>, pub address: Address,
mesh_connections: Arc<Mutex<HashMap<String, MeshConnection>>>, }
known_relays: Arc<Mutex<HashMap<String, RelayInfo>>>,
metrics: Arc<Mutex<SyncMetrics>>, // SilentPayment - Paiement silencieux
pub struct SilentPayment {
pub scan_key: ScanKey,
pub spend_key: SpendKey,
pub address: SilentAddress,
}
// Transaction - Transaction Bitcoin
pub struct Transaction {
pub txid: Txid,
pub version: u32,
pub inputs: Vec<TxIn>,
pub outputs: Vec<TxOut>,
pub locktime: u32,
}
// Address - Adresses Bitcoin
pub struct Address {
pub network: Network,
pub address_type: AddressType,
pub bytes: Vec<u8>,
} }
``` ```
### Types de Synchronisation **Caractéristiques :**
- **Sérialisation :** Support Serde pour JSON/MessagePack
- **Validation :** Validation intégrée des données
- **Sécurité :** Gestion sécurisée des clés privées
- **Compatibilité :** Support multi-réseaux (mainnet, testnet, signet)
Le système supporte plusieurs types de synchronisation : ### 2. Module Traits
- **StateSync** : Synchronisation de l'état général du relais **Rôle :** Définition des interfaces et contrats pour les opérations communes.
- **ProcessSync** : Synchronisation des processus en cours
- **MemberSync** : Synchronisation des membres
- **TxSync** : Synchronisation des transactions
- **BlockSync** : Synchronisation des blocs
- **PeerSync** : Synchronisation des pairs connectés
- **RelaySync** : Synchronisation des informations des relais
- **HealthSync** : Synchronisation de la santé du relais
- **MetricsSync** : Synchronisation des métriques
- **ConfigSync** : Synchronisation de la configuration
- **CapabilitySync** : Synchronisation des capacités
### Messages de Synchronisation **Traits principaux :**
#### Structure des Messages
```rust ```rust
pub struct SyncMessage { // Opérations de wallet
pub sync_type: SyncType, pub trait WalletOperations {
pub relay_id: String, fn generate_address(&self) -> Result<Address, SdkError>;
pub sequence: u64, fn sign_transaction(&self, tx: &Transaction) -> Result<Signature, SdkError>;
pub timestamp: u64, fn verify_signature(&self, sig: &Signature, msg: &[u8]) -> bool;
pub payload: SyncPayload, }
// Opérations de paiement silencieux
pub trait SilentPaymentOperations {
fn generate_payment(&self, wallet: &Wallet) -> Result<SilentPayment, SdkError>;
fn scan_transaction(&self, tx: &Transaction) -> Result<Vec<Output>, SdkError>;
fn create_output(&self, amount: u64) -> Result<TxOut, SdkError>;
}
// Opérations réseau
pub trait NetworkOperations {
fn connect(&self, endpoint: &str) -> Result<Connection, SdkError>;
fn send_message(&self, msg: &Message) -> Result<(), SdkError>;
fn receive_message(&self) -> Result<Message, SdkError>;
}
// Gestion des erreurs
pub trait ErrorOperations {
fn to_sdk_error(self) -> SdkError;
fn from_sdk_error(error: SdkError) -> Self;
} }
``` ```
#### Types de Payload **Caractéristiques :**
- **Abstraction :** Interfaces génériques et réutilisables
- **Extensibilité :** Facilite l'ajout de nouvelles implémentations
- **Testabilité :** Permet le mocking pour les tests
- **Flexibilité :** Support de différentes stratégies d'implémentation
### 3. Module Utils
**Rôle :** Utilitaires et fonctions helper pour les opérations communes.
**Fonctionnalités principales :**
```rust ```rust
pub enum SyncPayload { // Validation
StateData { state: String, version: String }, pub mod validation {
ProcessData { processes: HashMap<String, String> }, pub fn is_valid_bitcoin_address(address: &str) -> bool;
MemberData { members: HashMap<String, String> }, pub fn is_valid_transaction_hex(hex: &str) -> bool;
HealthData { status: HealthStatus, uptime: u64, cpu_usage: f64 }, pub fn is_valid_private_key(key: &str) -> bool;
MetricsData { metrics: SyncMetrics }, }
PeerData { peers: Vec<PeerInfo>, last_seen: u64 },
RelayData { relays: Vec<RelayInfo>, network_topology: NetworkTopology }, // Sérialisation
pub mod serialization {
pub fn to_json<T: Serialize>(value: &T) -> Result<String, SdkError>;
pub fn from_json<T: DeserializeOwned>(json: &str) -> Result<T, SdkError>;
pub fn to_hex(bytes: &[u8]) -> String;
pub fn from_hex(hex: &str) -> Result<Vec<u8>, SdkError>;
}
// Cryptographie
pub mod crypto {
pub fn sha256(data: &[u8]) -> [u8; 32];
pub fn ripemd160(data: &[u8]) -> [u8; 20];
pub fn hmac_sha256(key: &[u8], data: &[u8]) -> [u8; 32];
pub fn generate_random_bytes(length: usize) -> Vec<u8>;
}
// Encodage
pub mod encoding {
pub fn base58_encode(data: &[u8]) -> String;
pub fn base58_decode(encoded: &str) -> Result<Vec<u8>, SdkError>;
pub fn bech32_encode(hrp: &str, data: &[u8]) -> Result<String, SdkError>;
pub fn bech32_decode(encoded: &str) -> Result<(String, Vec<u8>), SdkError>;
} }
``` ```
## Fonctionnalités de Synchronisation ## Architecture des Silent Payments
### 1. Découverte Automatique des Relais ### 1. Génération de Paiement Silencieux
Le système implémente une découverte automatique des relais dans le réseau :
```rust ```rust
pub async fn discover_relays(&self) -> Result<()> { pub struct SilentPaymentGenerator {
let relay_hosts = vec![ wallet: Wallet,
"sdk_relay_1", network: Network,
"sdk_relay_2", }
"sdk_relay_3",
];
for host in relay_hosts { impl SilentPaymentGenerator {
if host == self.relay_id { pub fn new(wallet: Wallet, network: Network) -> Self {
continue; // Ignorer soi-même Self { wallet, network }
} }
let relay_info = RelayInfo { pub fn generate_payment(&self) -> Result<SilentPayment, SdkError> {
relay_id: host.to_string(), // 1. Générer la clé de scan
address: format!("{}:8090", host), let scan_key = self.generate_scan_key()?;
// ... autres champs
};
self.add_relay(relay_info)?; // 2. Générer la clé de dépense
let spend_key = self.generate_spend_key()?;
// 3. Créer l'adresse silencieuse
let address = self.create_silent_address(&scan_key, &spend_key)?;
Ok(SilentPayment {
scan_key,
spend_key,
address,
})
} }
}
```
### 2. Scan de Transactions
```rust
pub struct TransactionScanner {
scan_key: ScanKey,
network: Network,
}
impl TransactionScanner {
pub fn scan_transaction(&self, tx: &Transaction) -> Result<Vec<Output>, SdkError> {
let mut outputs = Vec::new();
for (index, output) in tx.outputs.iter().enumerate() {
// 1. Extraire les données de l'output
let script_pubkey = &output.script_pubkey;
// 2. Vérifier si c'est un paiement silencieux
if self.is_silent_payment_output(script_pubkey)? {
// 3. Dériver la clé de scan
let derived_key = self.derive_scan_key(script_pubkey)?;
// 4. Vérifier la correspondance
if self.matches_scan_key(&derived_key)? {
outputs.push(Output {
txid: tx.txid.clone(),
index: index as u32,
amount: output.value,
script_pubkey: script_pubkey.clone(),
});
}
}
}
Ok(outputs)
}
}
```
### 3. Création de Sorties
```rust
pub struct OutputCreator {
spend_key: SpendKey,
network: Network,
}
impl OutputCreator {
pub fn create_output(&self, amount: u64, address: &Address) -> Result<TxOut, SdkError> {
// 1. Créer le script de sortie
let script_pubkey = self.create_output_script(address)?;
// 2. Créer la sortie
Ok(TxOut {
value: amount,
script_pubkey,
})
}
}
```
## Architecture de Sécurité
### 1. Gestion des Clés
```rust
pub struct SecureKeyManager {
private_key: SecureKey,
public_key: PublicKey,
}
impl SecureKeyManager {
pub fn new() -> Result<Self, SdkError> {
// Générer une clé privée sécurisée
let private_key = SecureKey::generate()?;
let public_key = private_key.public_key()?;
Ok(Self {
private_key,
public_key,
})
}
pub fn sign(&self, message: &[u8]) -> Result<Signature, SdkError> {
// Signature sécurisée avec protection contre les attaques par timing
self.private_key.sign_secure(message)
}
}
impl Drop for SecureKeyManager {
fn drop(&mut self) {
// Effacer la clé privée de la mémoire
self.private_key.zeroize();
}
}
```
### 2. Validation des Entrées
```rust
pub struct InputValidator {
network: Network,
max_tx_size: usize,
}
impl InputValidator {
pub fn validate_transaction(&self, tx: &Transaction) -> Result<(), SdkError> {
// 1. Vérifier la taille
if tx.serialized_size() > self.max_tx_size {
return Err(SdkError::TransactionTooLarge);
}
// 2. Vérifier les entrées
for input in &tx.inputs {
self.validate_input(input)?;
}
// 3. Vérifier les sorties
for output in &tx.outputs {
self.validate_output(output)?;
}
// 4. Vérifier la cohérence
self.validate_consistency(tx)?;
Ok(()) Ok(())
}
```
### 2. Cache de Déduplication
Pour éviter les doublons, un cache de déduplication est implémenté :
```rust
pub struct MessageCache {
cache: Arc<Mutex<HashMap<String, Instant>>>,
}
impl MessageCache {
pub fn is_duplicate(&self, message_id: &str) -> bool {
let mut cache = self.cache.lock().unwrap();
if cache.contains_key(message_id) {
true
} else {
cache.insert(message_id.to_string(), Instant::now());
false
}
} }
} }
``` ```
### 3. Synchronisation Périodique ### 3. Protection contre les Attaques
Le système effectue une synchronisation périodique avec des intervalles configurés :
- **Synchronisation d'état** : Toutes les 30 secondes
- **Synchronisation de santé** : Toutes les 60 secondes
- **Synchronisation de métriques** : Toutes les 120 secondes
- **Synchronisation des relais** : Toutes les 300 secondes (5 minutes)
### 4. Gestion des Connexions Mesh
```rust ```rust
pub struct MeshConnection { pub struct SecurityManager {
pub relay_id: String, rate_limiter: RateLimiter,
pub address: String, input_sanitizer: InputSanitizer,
pub connected_since: u64, }
pub last_heartbeat: u64,
pub status: ConnectionStatus, impl SecurityManager {
pub fn process_request(&self, request: &Request) -> Result<Response, SdkError> {
// 1. Rate limiting
self.rate_limiter.check_limit(&request.source)?;
// 2. Sanitisation des entrées
let sanitized_request = self.input_sanitizer.sanitize(request)?;
// 3. Validation
self.validate_request(&sanitized_request)?;
// 4. Traitement sécurisé
self.process_secure(&sanitized_request)
}
} }
``` ```
## Configuration Multi-Relais ## Architecture de Performance
### Configuration Docker ### 1. Optimisations Rust
Le système supporte la configuration de plusieurs relais via Docker :
```yaml
services:
sdk_relay_1:
container_name: sdk_relay_1
ports:
- "8090:8090"
- "8091:8091"
environment:
- ENABLE_SYNC_TEST=1
sdk_relay_2:
container_name: sdk_relay_2
ports:
- "8092:8090"
- "8093:8091"
environment:
- ENABLE_SYNC_TEST=1
sdk_relay_3:
container_name: sdk_relay_3
ports:
- "8094:8090"
- "8095:8091"
environment:
- ENABLE_SYNC_TEST=1
```
### Configuration par Relais
Chaque relais a sa propre configuration :
```ini
# .conf.docker.relay1
relay_id=relay-1
ws_url=0.0.0.0:8090
# .conf.docker.relay2
relay_id=relay-2
ws_url=0.0.0.0:8090
# .conf.docker.relay3
relay_id=relay-3
ws_url=0.0.0.0:8090
```
## Métriques de Synchronisation
```rust ```rust
pub struct SyncMetrics { // Utilisation de references pour éviter les copies
pub messages_sent: u64, pub fn process_wallet_optimized(wallet: &Wallet) -> Result<(), SdkError> {
pub messages_received: u64, // Traitement sans copie
pub sync_errors: u64, wallet.process_transactions()?;
pub last_sync_timestamp: u64, Ok(())
pub connected_relays: u64, }
pub mesh_health: f64,
// Utilisation de iterators pour les performances
pub fn process_transactions_batch(txs: &[Transaction]) -> Vec<Result<(), SdkError>> {
txs.iter()
.map(|tx| process_transaction(tx))
.collect()
}
// Utilisation de Box pour les gros objets
pub fn create_large_wallet() -> Box<Wallet> {
Box::new(Wallet::new().unwrap())
} }
``` ```
## Flux de Données ### 2. Optimisations WASM
### 1. Flux de Synchronisation ```rust
#[cfg(feature = "wasm")]
pub mod wasm_optimizations {
use wasm_bindgen::prelude::*;
``` // Utilisation de Web Workers pour les calculs lourds
Relay 1 ──┐ #[wasm_bindgen]
├─── SyncManager ──── MessageCache ──── Mesh Network pub fn process_payment_async(payment_data: JsValue) -> js_sys::Promise {
Relay 2 ──┤ // Traitement asynchrone
│ wasm_bindgen_futures::JsFuture::from(
Relay 3 ──┘ process_payment_worker(payment_data)
).into()
}
// Utilisation de SharedArrayBuffer pour les gros datasets
#[wasm_bindgen]
pub fn process_large_dataset(data: &js_sys::Uint8Array) -> Result<(), JsValue> {
// Traitement optimisé pour WASM
process_data_optimized(data)
}
}
``` ```
### 2. Flux de Traitement des Transactions ### 3. Cache et Mémoire
``` ```rust
Bitcoin Core ──── ZMQ Notifications ──── SDK Relay ──── Blindbit pub struct CacheManager {
│ │ │ │ wallet_cache: LruCache<String, Wallet>,
└─── Block Scan ─────┴─── Silent Payment ─┴─── Validation tx_cache: LruCache<Txid, Transaction>,
}
impl CacheManager {
pub fn new() -> Self {
Self {
wallet_cache: LruCache::new(100),
tx_cache: LruCache::new(1000),
}
}
pub fn get_wallet(&mut self, id: &str) -> Option<&Wallet> {
self.wallet_cache.get(id)
}
pub fn cache_wallet(&mut self, id: String, wallet: Wallet) {
self.wallet_cache.put(id, wallet);
}
}
``` ```
### 3. Flux de Communication WebSocket ## Architecture de Monitoring
``` ### 1. Métriques de Performance
Client ──── WebSocket ──── SDK Relay ──── Bitcoin Core RPC
│ │ │ ```rust
└─── Events ─┴─── Commands ─┴─── Responses pub struct PerformanceMetrics {
operation_times: HashMap<String, Duration>,
error_counts: HashMap<String, u64>,
memory_usage: MemoryTracker,
}
impl PerformanceMetrics {
pub fn record_operation(&mut self, operation: &str, duration: Duration) {
self.operation_times.insert(operation.to_string(), duration);
}
pub fn record_error(&mut self, error_type: &str) {
*self.error_counts.entry(error_type.to_string()).or_insert(0) += 1;
}
pub fn get_memory_usage(&self) -> MemoryUsage {
self.memory_usage.current_usage()
}
}
``` ```
## Sécurité et Isolation ### 2. Logs et Debug
### 1. Isolation Réseau ```rust
pub struct Logger {
level: LogLevel,
output: Box<dyn LogOutput>,
}
- **Réseau privé :** `btcnet` pour la communication inter-services impl Logger {
- **Ports exposés :** Seulement les ports nécessaires pub fn log(&self, level: LogLevel, message: &str) {
- **Volumes :** Données persistantes isolées if level >= self.level {
self.output.write(level, message);
}
}
### 2. Authentification pub fn debug(&self, message: &str) {
self.log(LogLevel::Debug, message);
}
- **Bitcoin Core :** Cookie d'authentification pub fn info(&self, message: &str) {
- **Blindbit :** À définir selon les besoins self.log(LogLevel::Info, message);
- **SDK Relay :** Authentification WebSocket }
- **Tor :** Pas d'authentification requise
### 3. Chiffrement pub fn error(&self, message: &str) {
self.log(LogLevel::Error, message);
}
}
```
- **RPC Bitcoin :** HTTP (non chiffré en local) ## Architecture de Déploiement
- **HTTP Blindbit :** HTTP (non chiffré en local)
- **WebSocket SDK Relay :** WSS (chiffré)
- **Tor :** Chiffrement intégré
## Performance et Optimisations ### 1. Support Multi-Plateforme
### 1. Ressources Requises ```rust
// Configuration conditionnelle pour différentes plateformes
#[cfg(target_arch = "wasm32")]
pub mod wasm_config {
pub const MAX_MEMORY: usize = 32 * 1024 * 1024; // 32MB
pub const STACK_SIZE: usize = 1024 * 1024; // 1MB
}
- **CPU :** Minimum 2 cœurs #[cfg(not(target_arch = "wasm32"))]
- **RAM :** Minimum 4 GB pub mod native_config {
- **Stockage :** Minimum 50 GB pour la blockchain pub const MAX_MEMORY: usize = 1024 * 1024 * 1024; // 1GB
- **Réseau :** Connexion stable à Internet pub const STACK_SIZE: usize = 8 * 1024 * 1024; // 8MB
}
```
### 2. Optimisations Implémentées ### 2. Features Conditionnelles
- **Cache :** Mise en cache des données fréquemment utilisées ```rust
- **Compression :** Compression des données de blockchain // Features pour différentes configurations
- **Parallélisation :** Traitement parallèle des blocs #[cfg(feature = "std")]
- **Monitoring :** Métriques de performance pub mod std_support {
pub use std::collections::HashMap;
pub use std::time::Instant;
}
### 3. Métriques de Performance #[cfg(feature = "wasm")]
pub mod wasm_support {
pub use js_sys::Object;
pub use wasm_bindgen::prelude::*;
}
- **Latence de synchronisation :** < 100ms #[cfg(feature = "blindbit-wasm")]
- **Débit de messages :** > 1000 msg/s pub mod blindbit_wasm {
- **Utilisation mémoire :** < 2GB par relais pub use js_sys;
- **Temps de démarrage :** < 30 secondes pub use web_sys;
}
```
## Monitoring et Observabilité ### 3. Intégration CI/CD
### 1. Métriques Collectées ```rust
// Tests conditionnels pour différents environnements
#[cfg(test)]
mod tests {
#[test]
fn test_wallet_creation() {
// Test de base
}
- **Métriques système :** CPU, RAM, disque, réseau #[cfg(feature = "wasm")]
- **Métriques de synchronisation :** Messages envoyés/reçus, erreurs #[test]
- **Métriques de santé :** Uptime, statut des connexions fn test_wasm_integration() {
- **Métriques métier :** Transactions traitées, paiements détectés // Test WASM
}
### 2. Logs #[cfg(feature = "blindbit-wasm")]
#[test]
fn test_blindbit_wasm() {
// Test Blindbit WASM
}
}
```
- **Logs système :** Démarrage, arrêt, erreurs ## Évolutions Futures
- **Logs de synchronisation :** Messages, erreurs, métriques
- **Logs métier :** Transactions, paiements, événements
### 3. Alertes ### 1. Extensions Planifiées
- **Alertes critiques :** Services arrêtés, erreurs de synchronisation - **Support de nouveaux réseaux** : Lightning Network, Liquid
- **Alertes de performance :** Latence élevée, utilisation mémoire - **Optimisations avancées** : SIMD, GPU acceleration
- **Alertes métier :** Échecs de traitement, anomalies - **Nouvelles fonctionnalités** : Multi-signature, Time-locks
- **Intégrations** : Support de nouveaux wallets et services
## Évolutivité ### 2. Améliorations de Performance
### 1. Scalabilité Horizontale - **Compilation JIT** : Optimisations dynamiques
- **Parallélisation** : Support multi-threading avancé
- **Cache intelligent** : Cache adaptatif basé sur l'usage
- **Compression** : Optimisation de la taille des données
- **Ajout de relais :** Configuration automatique ### 3. Sécurité Renforcée
- **Load balancing :** Distribution de charge
- **Redondance :** Relais de secours
### 2. Scalabilité Verticale - **Audit de sécurité** : Vérifications automatisées
- **Isolation mémoire** : Protection avancée contre les attaques
- **Chiffrement** : Support de nouveaux algorithmes
- **Validation** : Vérifications supplémentaires
- **Ressources :** Augmentation CPU/RAM ---
- **Stockage :** Extension des volumes
- **Réseau :** Bande passante
### 3. Architecture Distribuée **🏗️ Architecture sdk_common - Fondation solide pour les Silent Payments** 🚀
- **Microservices :** Services indépendants
- **API Gateway :** Point d'entrée unifié
- **Service Discovery :** Découverte automatique
## Déploiement et Infrastructure
### 1. Environnements
- **Développement :** Configuration locale
- **Test :** Environnement de test
- **Production :** Configuration optimisée
### 2. Orchestration
- **Docker Compose :** Orchestration locale
- **Kubernetes :** Orchestration distribuée (futur)
- **Service Mesh :** Communication inter-services
### 3. CI/CD
- **Build :** Construction des images
- **Test :** Tests automatisés
- **Déploiement :** Déploiement automatique
## Troubleshooting
### 1. Problèmes de Synchronisation
- **Connexions perdues :** Vérifier la connectivité réseau
- **Messages dupliqués :** Vérifier le cache de déduplication
- **Latence élevée :** Vérifier les ressources système
### 2. Problèmes de Performance
- **Utilisation mémoire :** Vérifier les fuites mémoire
- **CPU élevé :** Vérifier les boucles infinies
- **Disque plein :** Nettoyer les logs et données
### 3. Problèmes de Configuration
- **Ports bloqués :** Vérifier le pare-feu
- **Volumes manquants :** Vérifier les permissions
- **Variables d'environnement :** Vérifier la configuration
## Évolution Future
### 1. Améliorations Planifiées
- **Synchronisation temps réel :** Réduction de la latence
- **Compression avancée :** Optimisation de la bande passante
- **Chiffrement end-to-end :** Sécurité renforcée
### 2. Nouvelles Fonctionnalités
- **API REST :** Interface REST pour les clients
- **Webhooks :** Notifications en temps réel
- **Analytics :** Tableaux de bord avancés
### 3. Intégrations
- **Monitoring :** Prometheus, Grafana
- **Logging :** ELK Stack
- **Alerting :** PagerDuty, Slack

417
docs/INDEX.md
View File

@ -1,60 +1,55 @@
# 📚 Index de Documentation - 4NK Node # 📚 Index de Documentation - sdk_common
Index complet de la documentation de l'infrastructure 4NK Node. Index complet de la documentation de la bibliothèque commune sdk_common pour les Silent Payments.
## 📖 Guides Principaux ## 📖 Guides Principaux
### 🚀 [Guide d'Installation](INSTALLATION.md) ### 🚀 [Guide d'Installation](INSTALLATION.md)
Guide complet pour installer et configurer l'infrastructure 4NK Node. Guide complet pour installer et configurer la bibliothèque sdk_common.
- **Prérequis système et logiciels** - **Prérequis système et logiciels**
- **Installation de Docker et dépendances** - **Installation de Rust et dépendances**
- **Configuration SSH et GitLab** - **Configuration Cargo et features**
- **Configuration initiale des services**
- **Tests post-installation** - **Tests post-installation**
- **Dépannage et monitoring** - **Dépannage et monitoring**
### 📖 [Guide d'Utilisation](USAGE.md) ### 📖 [Guide d'Utilisation](USAGE.md)
Guide complet pour utiliser l'infrastructure 4NK Node au quotidien. Guide complet pour utiliser la bibliothèque sdk_common au quotidien.
- **Démarrage quotidien des services** - **Compilation et build**
- **Opérations de surveillance et monitoring** - **Intégration dans les projets**
- **Utilisation du réseau de relais** - **Utilisation des types et structures**
- **Connexion aux services (Bitcoin Core, Blindbit, sdk_relay)**
- **Tests et validation** - **Tests et validation**
- **Configuration et maintenance** - **Configuration et maintenance**
- **Gestion des nœuds externes** - **Optimisations de performance**
### ⚙️ [Guide de Configuration](CONFIGURATION.md) ### ⚙️ [Guide de Configuration](CONFIGURATION.md)
Guide complet pour configurer l'infrastructure selon vos besoins. Guide complet pour configurer la bibliothèque selon vos besoins.
- **Configuration générale et variables d'environnement** - **Configuration générale et variables d'environnement**
- **Configuration Bitcoin Core (base et avancée)** - **Configuration Rust et Cargo**
- **Configuration Blindbit (base et avancée)** - **Configuration des features**
- **Configuration des relais (base et avancée)** - **Configuration de build**
- **Configuration des nœuds externes** - **Configuration de tests**
- **Configuration Tor** - **Configuration de sécurité**
- **Configuration Docker Compose**
- **Configuration SSL/TLS**
- **Configuration de monitoring et sauvegarde**
## 🔧 Guides Techniques ## 🔧 Guides Techniques
### 🏗️ [Architecture Technique](ARCHITECTURE.md) ### 🏗️ [Architecture Technique](ARCHITECTURE.md)
Documentation technique détaillée de l'architecture. Documentation technique détaillée de l'architecture.
- **Architecture générale du système** - **Architecture générale de la bibliothèque**
- **Composants principaux (Bitcoin Core, Blindbit, SDK Relay)** - **Composants principaux (types, structures, traits)**
- **Architecture de synchronisation mesh** - **Architecture des Silent Payments**
- **Flux de données entre services** - **Flux de données et types**
- **Configuration multi-relais** - **Intégration avec sdk_client et sdk_relay**
- **Sécurité et isolation** - **Sécurité et isolation**
- **Performance et optimisations** - **Performance et optimisations**
- **Monitoring et observabilité** - **Monitoring et observabilité**
### 📡 [API Reference](API.md) ### 📡 [API Reference](API.md)
Documentation complète des APIs disponibles. Documentation complète des APIs disponibles.
- **API Bitcoin Core RPC** : Interface JSON-RPC pour Bitcoin - **API Types** : Types et structures de données
- **API Blindbit HTTP** : API REST pour les paiements silencieux - **API Traits** : Traits et interfaces
- **API SDK Relay WebSocket** : Interface temps réel pour les clients - **API Functions** : Fonctions utilitaires
- **API SDK Relay HTTP** : API REST pour les opérations de gestion - **API Error Handling** : Gestion des erreurs
- **Format des messages et payloads** - **Format des données et payloads**
- **Gestion des erreurs** - **Gestion des erreurs**
- **Exemples d'utilisation** - **Exemples d'utilisation**
- **Limites et quotas** - **Limites et quotas**
@ -63,7 +58,7 @@ Documentation complète des APIs disponibles.
Guide de sécurité et bonnes pratiques. Guide de sécurité et bonnes pratiques.
- **Authentification et autorisation** - **Authentification et autorisation**
- **Chiffrement et certificats** - **Chiffrement et certificats**
- **Isolation réseau** - **Sécurité des types et structures**
- **Audit et monitoring de sécurité** - **Audit et monitoring de sécurité**
- **Bonnes pratiques** - **Bonnes pratiques**
@ -98,215 +93,191 @@ Roadmap de développement détaillée.
- **Fonctionnalités planifiées** - **Fonctionnalités planifiées**
- **Évolution de l'architecture** - **Évolution de l'architecture**
- **Métriques de succès** - **Métriques de succès**
- **Vision long terme**
### 📈 [Performance](PERFORMANCE.md)
Guide d'optimisation et monitoring des performances.
- **Optimisation des ressources**
- **Monitoring des performances**
- **Tests de charge**
- **Métriques et alertes**
- **Troubleshooting des performances**
## 🧪 Guides de Test ## 🧪 Guides de Test
### 🧪 [Guide de Tests](TESTING.md) ### 🧪 [Guide des Tests](TESTING.md)
Guide complet des tests de l'infrastructure 4NK Node. Guide complet pour les tests de la bibliothèque.
- **Tests unitaires** : Tests individuels des composants - **Tests unitaires Rust**
- **Tests d'intégration** : Tests d'interaction entre services - **Tests d'intégration**
- **Tests de connectivité** : Tests réseau et WebSocket - **Tests de performance**
- **Tests externes** : Tests avec des nœuds externes - **Tests de sécurité**
- **Tests de performance** : Tests de charge et performance (à venir) - **Tests de compatibilité**
- **Organisation et exécution des tests** - **Tests de régression**
- **Interprétation des résultats**
- **Dépannage et maintenance**
### 🔄 [Tests de Synchronisation](SYNC_TESTING.md) ### 🔍 [Audit de Sécurité](SECURITY_AUDIT.md)
Guide des tests de synchronisation entre relais. Audit de sécurité détaillé.
- **Tests de synchronisation mesh** - **Vulnérabilités connues**
- **Tests de découverte de relais** - **Tests de pénétration**
- **Tests de cache de déduplication** - **Audit de code**
- **Tests de métriques de synchronisation** - **Recommandations de sécurité**
- **Troubleshooting de la synchronisation** - **Plan de remédiation**
### 📊 [Tests de Performance](PERFORMANCE_TESTING.md) ## 🔧 Guides de Développement
Guide des tests de performance et de charge.
- **Tests de charge WebSocket**
- **Tests de performance Bitcoin Core**
- **Tests de performance Blindbit**
- **Tests de scalabilité**
- **Benchmarks et métriques**
## 🌐 Guides Réseau ### 🔧 [Guide de Développement](DEVELOPMENT.md)
Guide complet pour le développement.
- **Environnement de développement**
- **Workflow de développement**
- **Standards de code**
- **Debugging et profiling**
- **Optimisation des performances**
- **Déploiement et CI/CD**
### 🌐 [Réseau de Relais](RELAY_NETWORK.md) ### 📋 [Référence Rapide](QUICK_REFERENCE.md)
Guide de configuration du réseau mesh de relais. Référence rapide pour les développeurs.
- **Architecture mesh** - **Commandes essentielles**
- **Configuration des relais locaux** - **Structure du projet**
- **Synchronisation entre relais** - **APIs principales**
- **Découverte automatique** - **Configuration rapide**
- **Gestion des connexions** - **Dépannage rapide**
### 🌍 [Nœuds Externes](EXTERNAL_NODES.md) ### 🔄 [Guide de Migration](MIGRATION.md)
Guide d'ajout et de gestion de nœuds externes. Guide pour les migrations et mises à jour.
- **Configuration des nœuds externes** - **Migration des versions**
- **Script d'administration** - **Breaking changes**
- **Validation et sécurité** - **Mise à jour des dépendances**
- **Tests de connectivité** - **Migration des données**
- **Gestion multi-sites** - **Tests de migration**
### 🔄 [Synchronisation](SYNCHRONIZATION.md) ## 🌐 Guides d'Intégration
Guide du protocole de synchronisation.
- **Protocole de synchronisation**
- **Types de messages**
- **Cache de déduplication**
- **Métriques de synchronisation**
- **Troubleshooting**
## 📋 Guides de Référence ### 🔗 [Intégration 4NK_node](INTEGRATION_4NK_NODE.md)
Guide d'intégration avec l'infrastructure 4NK_node.
- **Configuration Docker**
- **Variables d'environnement**
- **Communication inter-services**
- **Déploiement intégré**
- **Monitoring et logs**
### 📋 [Commandes Rapides](QUICK_REFERENCE.md) ### 🔑 [Configuration SSH](SSH_SETUP.md)
Référence rapide des commandes essentielles. Guide de configuration SSH pour le développement.
- **Commandes de démarrage** - **Génération des clés SSH**
- **Commandes de monitoring** - **Configuration Git**
- **Commandes de test** - **Intégration avec Gitea**
- **Commandes de dépannage** - **Automatisation des déploiements**
- **Commandes de maintenance**
### 📋 [Troubleshooting](TROUBLESHOOTING.md) ### 🤖 [Push SSH Automatisé](AUTO_SSH_PUSH.md)
Guide de résolution des problèmes courants. Guide pour l'automatisation des pushes SSH.
- **Problèmes de démarrage** - **Configuration des scripts**
- **Problèmes de connectivité** - **Intégration CI/CD**
- **Problèmes de synchronisation** - **Gestion des clés**
- **Problèmes de performance** - **Sécurité et bonnes pratiques**
- **Logs et diagnostics**
### 📋 [FAQ](FAQ.md) ## 📊 État et Monitoring
Questions fréquemment posées.
- **Questions d'installation**
- **Questions de configuration**
- **Questions d'utilisation**
- **Questions de performance**
- **Questions de sécurité**
## 📁 Structure des Fichiers ### 📊 [État Actuel](ETAT_ACTUEL.md)
État détaillé du projet sdk_common.
- **Statut des compilations**
- **Configuration des branches**
- **Fonctionnalités opérationnelles**
- **Métriques de performance**
- **Problèmes connus**
``` ### 📋 [Résumé Final](RESUME_FINAL.md)
4NK_node/ Résumé complet de l'état final du projet.
├── README.md # Documentation principale - **Succès accomplis**
├── docs/ # Documentation organisée - **Prêt pour la production**
│ ├── INDEX.md # Cet index - **Documentation complète**
│ ├── INSTALLATION.md # Guide d'installation - **Support et maintenance**
│ ├── USAGE.md # Guide d'utilisation
│ ├── CONFIGURATION.md # Guide de configuration
│ ├── ARCHITECTURE.md # Architecture technique
│ ├── API.md # Référence API
│ ├── SECURITY.md # Guide de sécurité
│ ├── PERFORMANCE.md # Guide de performance
│ ├── TESTING.md # Tests de base
│ ├── SYNC_TESTING.md # Tests de synchronisation
│ ├── PERFORMANCE_TESTING.md # Tests de performance
│ ├── RELAY_NETWORK.md # Réseau de relais
│ ├── EXTERNAL_NODES.md # Nœuds externes
│ ├── SYNCHRONIZATION.md # Protocole de synchronisation
│ ├── QUICK_REFERENCE.md # Commandes rapides
│ ├── TROUBLESHOOTING.md # Guide de dépannage
│ └── FAQ.md # Questions fréquentes
├── specs/ # Spécifications techniques
│ ├── spec-technique.md # Spécification technique
│ └── spec-fonctionnel.md # Spécification fonctionnelle
├── scripts/ # Scripts utilitaires
├── tests/ # Scripts de test
└── examples/ # Exemples d'utilisation
```
## 🎯 Parcours d'Apprentissage ## 🔧 Guides d'Open Source
### 🚀 **Débutant** ### ✅ [Checklist Open Source](OPEN_SOURCE_CHECKLIST.md)
1. [Guide d'Installation](INSTALLATION.md) - Installer l'infrastructure Checklist complète pour l'ouverture en open source.
2. [Guide d'Utilisation](USAGE.md) - Utiliser les services de base - **Préparation du code**
3. [Tests de Base](TESTING.md) - Vérifier le fonctionnement - **Documentation**
4. [FAQ](FAQ.md) - Réponses aux questions courantes - **Licences et légal**
- **Infrastructure**
- **Communication**
### 🔧 **Intermédiaire** ## 📞 Support et Contact
1. [Guide de Configuration](CONFIGURATION.md) - Configurer selon vos besoins
2. [Réseau de Relais](RELAY_NETWORK.md) - Comprendre l'architecture mesh
3. [Nœuds Externes](EXTERNAL_NODES.md) - Ajouter des nœuds externes
4. [Tests de Synchronisation](SYNC_TESTING.md) - Tester la synchronisation
### 🏗️ **Avancé** ### 📞 [Support](SUPPORT.md)
1. [Architecture Technique](ARCHITECTURE.md) - Comprendre l'architecture Guide de support et contact.
2. [API Reference](API.md) - Utiliser les APIs - **Comment obtenir de l'aide**
3. [Sécurité](SECURITY.md) - Sécuriser l'infrastructure - **Création d'issues**
4. [Performance](PERFORMANCE.md) - Optimiser les performances - **Canal de communication**
5. [Tests de Performance](PERFORMANCE_TESTING.md) - Tests avancés - **FAQ**
- **Ressources additionnelles**
### 🛠️ **Expert**
1. [Synchronisation](SYNCHRONIZATION.md) - Protocole de synchronisation
2. [Troubleshooting](TROUBLESHOOTING.md) - Résolution de problèmes
3. [Commandes Rapides](QUICK_REFERENCE.md) - Référence rapide
4. Spécifications techniques dans `/specs/`
## 🔍 Recherche dans la Documentation
### Par Sujet
- **Installation** : [INSTALLATION.md](INSTALLATION.md)
- **Configuration** : [CONFIGURATION.md](CONFIGURATION.md)
- **Utilisation** : [USAGE.md](USAGE.md)
- **Tests** : [TESTING.md](TESTING.md), [SYNC_TESTING.md](SYNC_TESTING.md)
- **Réseau** : [RELAY_NETWORK.md](RELAY_NETWORK.md), [EXTERNAL_NODES.md](EXTERNAL_NODES.md)
- **Performance** : [PERFORMANCE.md](PERFORMANCE.md)
- **Sécurité** : [SECURITY.md](SECURITY.md)
- **Dépannage** : [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
### Par Service
- **Bitcoin Core** : [CONFIGURATION.md](CONFIGURATION.md#configuration-bitcoin-core)
- **Blindbit** : [CONFIGURATION.md](CONFIGURATION.md#configuration-blindbit)
- **sdk_relay** : [CONFIGURATION.md](CONFIGURATION.md#configuration-des-relais)
- **Tor** : [CONFIGURATION.md](CONFIGURATION.md#configuration-tor)
### Par Tâche
- **Démarrer** : [USAGE.md](USAGE.md#démarrage-quotidien)
- **Configurer** : [CONFIGURATION.md](CONFIGURATION.md)
- **Tester** : [TESTING.md](TESTING.md)
- **Monitorer** : [USAGE.md](USAGE.md#monitoring-et-alertes)
- **Dépanner** : [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
## 📞 Support
### Documentation
- **Index** : [INDEX.md](INDEX.md) - Cet index
- **FAQ** : [FAQ.md](FAQ.md) - Questions fréquentes
- **Troubleshooting** : [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Résolution de problèmes
### Ressources Externes
- **Repository** : [GitLab 4NK Node](https://git.4nkweb.com/4nk/4NK_node)
- **Issues** : [Issues GitLab](https://git.4nkweb.com/4nk/4NK_node/issues)
- **Wiki** : [Wiki GitLab](https://git.4nkweb.com/4nk/4NK_node/wikis)
### Contact
- **Email** : support@4nkweb.com
- **Chat** : [Discord 4NK](https://discord.gg/4nk)
- **Forum** : [Forum 4NK](https://forum.4nkweb.com)
## 🔄 Mise à Jour de la Documentation
### Dernière Mise à Jour
- **Date** : $(date)
- **Version** : 1.0.0
- **Auteur** : Équipe 4NK
### Historique des Versions
- **v1.0.0** : Documentation initiale complète
- **v0.9.0** : Documentation de base
- **v0.8.0** : Guides techniques
- **v0.7.0** : Guides de test
### Contribution
Pour contribuer à la documentation :
1. Fork le repository
2. Créer une branche pour votre contribution
3. Modifier la documentation
4. Créer une Pull Request
--- ---
## 🎯 Navigation Rapide
### 🚀 Démarrage Rapide
1. [Installation](INSTALLATION.md) - Installer sdk_common
2. [Configuration](CONFIGURATION.md) - Configurer l'environnement
3. [Utilisation](USAGE.md) - Utiliser la bibliothèque
### 🔧 Développement
1. [Architecture](ARCHITECTURE.md) - Comprendre l'architecture
2. [API](API.md) - Consulter les APIs
3. [Tests](TESTING.md) - Exécuter les tests
### 📚 Documentation
1. [Index](INDEX.md) - Cet index
2. [Quick Reference](QUICK_REFERENCE.md) - Référence rapide
3. [Roadmap](ROADMAP.md) - Évolution du projet
### 🤝 Communauté
1. [Guide Communauté](COMMUNITY_GUIDE.md) - Contribuer
2. [Code de Conduite](../CODE_OF_CONDUCT.md) - Règles de conduite
3. [Support](SUPPORT.md) - Obtenir de l'aide
---
## 🧪 Tests et Validation
### Tests Automatisés
```bash
# Tests unitaires
cargo test --all
# Tests d'intégration
cargo test --test integration
# Tests de performance
cargo test --test performance
# Linting
cargo clippy -- -D warnings
# Formatage
cargo fmt -- --check
```
### Tests de Compatibilité
```bash
# Tests de compatibilité avec sdk_client
cargo test --features sdk-client
# Tests de compatibilité avec sdk_relay
cargo test --features sdk-relay
# Tests de compatibilité WASM
cargo test --features wasm
```
---
## 🚀 Développement
### Commandes Essentielles
```bash
# Build de développement
cargo build
# Build de production
cargo build --release
# Tests
cargo test --all
# Documentation
cargo doc --open
```
---
**📚 Documentation complète pour sdk_common - Bibliothèque commune pour les Silent Payments** 🚀

660
docs/INSTALLATION.md
View File

@ -1,533 +1,423 @@
# 📦 Guide d'Installation - 4NK Node # 📦 Guide d'Installation - sdk_common
Guide complet pour installer et configurer l'infrastructure 4NK Node. Guide complet pour installer et configurer la bibliothèque commune sdk_common pour les Silent Payments.
## 📋 Prérequis ## 📋 Prérequis
### Système ### Système
- **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+) - **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+), macOS 10.15+, Windows 10+
- **Architecture** : x86_64 - **Architecture** : x86_64, ARM64 (pour certaines plateformes)
- **RAM** : 4 Go minimum, 8 Go recommandés - **RAM** : 2 Go minimum, 4 Go recommandés
- **Stockage** : 20 Go minimum, 50 Go recommandés - **Stockage** : 5 Go minimum, 10 Go recommandés
- **Réseau** : Connexion Internet stable - **Réseau** : Connexion Internet stable pour télécharger les dépendances
### Logiciels ### Logiciels
- **Docker** : Version 20.10+ - **Rust** : Version 1.70+ (stable)
- **Docker Compose** : Version 2.0+ - **Cargo** : Inclus avec Rust
- **Git** : Version 2.25+ - **Git** : Version 2.25+
- **Bash** : Version 4.0+ - **wasm-pack** : Version 0.12+ (pour compilation WASM)
- **Node.js** : Version 18+ (pour tests WASM)
## 🚀 Installation ## 🚀 Installation
### 1. Installation de Docker ### 1. Installation de Rust
#### Ubuntu/Debian #### Linux/macOS
```bash ```bash
# Mettre à jour les paquets # Installer Rust via rustup
sudo apt update curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Installer les dépendances # Recharger l'environnement
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release source ~/.cargo/env
# Ajouter la clé GPG Docker # Vérifier l'installation
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg rustc --version
cargo --version
# Ajouter le repository Docker
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Installer Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER
# Démarrer Docker
sudo systemctl start docker
sudo systemctl enable docker
``` ```
#### CentOS/RHEL #### Windows
```bash ```bash
# Installer les dépendances # Télécharger et installer rustup-init.exe depuis
sudo yum install -y yum-utils # https://rustup.rs/
# Puis exécuter dans PowerShell :
# Ajouter le repository Docker rustup-init.exe
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
# Installer Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Démarrer Docker
sudo systemctl start docker
sudo systemctl enable docker
# Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER
``` ```
### 2. Configuration SSH (Recommandé) ### 2. Installation de wasm-pack
```bash
# Installer wasm-pack
cargo install wasm-pack
# Vérifier l'installation
wasm-pack --version
```
### 3. Configuration SSH (Recommandé)
```bash ```bash
# Générer une clé SSH # Générer une clé SSH
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk -C "4nk-automation" ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_sdk_common -C "sdk-common-automation"
# Ajouter à l'agent SSH # Ajouter à l'agent SSH
ssh-add ~/.ssh/id_ed25519_4nk ssh-add ~/.ssh/id_ed25519_sdk_common
# Configurer Git pour utiliser la clé # Configurer Git pour utiliser la clé
git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_4nk" git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_sdk_common"
# Afficher la clé publique pour GitLab # Afficher la clé publique pour Gitea
cat ~/.ssh/id_ed25519_4nk.pub cat ~/.ssh/id_ed25519_sdk_common.pub
``` ```
**Ajouter la clé publique à GitLab :** **Ajouter la clé publique à Gitea :**
1. Aller sur GitLab > Settings > SSH Keys 1. Aller sur Gitea > Settings > SSH Keys
2. Coller la clé publique 2. Coller la clé publique
3. Cliquer sur "Add key" 3. Cliquer sur "Add key"
### 3. Clonage du Repository ### 4. Clonage du Repository
```bash ```bash
# Cloner avec SSH (recommandé) # Cloner avec SSH (recommandé)
git clone git@git.4nkweb.com:4nk/4NK_node.git git clone git@git.4nkweb.com:4nk/sdk_common.git
cd 4NK_node cd sdk_common
# Ou avec HTTPS (si SSH non configuré) # Ou cloner avec HTTPS
# git clone https://git.4nkweb.com/4nk/4NK_node.git git clone https://git.4nkweb.com/4nk/sdk_common.git
# cd 4NK_node cd sdk_common
``` ```
### 4. Vérification de l'Installation ### 5. Configuration de l'Environnement
```bash ```bash
# Vérifier Docker # Créer le fichier de configuration
docker --version cp .env.example .env
docker-compose --version
# Vérifier la connectivité GitLab # Éditer les variables d'environnement
ssh -T git@git.4nkweb.com nano .env
# Vérifier les permissions
ls -la
``` ```
## 🔧 Configuration Initiale **Variables d'environnement principales :**
### 1. Configuration des Variables d'Environnement
```bash ```bash
# Créer le fichier d'environnement # Configuration Rust
cat > .env << EOF RUST_LOG=info
# Configuration 4NK Node RUST_BACKTRACE=1
PROJECT_NAME=4NK Node
NETWORK_NAME=4nk_node_btcnet
# Logs # Configuration de build
RUST_LOG=debug,bitcoincore_rpc=trace CARGO_PROFILE_RELEASE_OPT_LEVEL=3
CARGO_PROFILE_RELEASE_LTO=true
# Bitcoin # Configuration des tests
BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie TEST_TIMEOUT=300
TEST_PARALLEL=true
# Synchronisation # Configuration WASM
ENABLE_SYNC_TEST=1 WASM_PACK_TARGET=web
WASM_PACK_PROFILE=release
# Ports
TOR_PORTS=9050:9050,9051:9051
BITCOIN_PORTS=38333:38333,18443:18443,29000:29000
BLINDBIT_PORTS=8000:8000
RELAY_1_PORTS=8090:8090,8091:8091
RELAY_2_PORTS=8092:8090,8093:8091
RELAY_3_PORTS=8094:8090,8095:8091
EOF
``` ```
### 2. Configuration Bitcoin Core ### 6. Installation des Dépendances
```bash ```bash
# Vérifier la configuration Bitcoin # Mettre à jour Rust
cat bitcoin/bitcoin.conf rustup update
# Modifier si nécessaire # Installer les dépendances Rust
nano bitcoin/bitcoin.conf cargo build
```
**Configuration recommandée :** # Installer les dépendances de développement
```ini cargo install cargo-audit
# Configuration Bitcoin Core Signet cargo install cargo-tarpaulin
signet=1 cargo install cargo-watch
rpcuser=bitcoin
rpcpassword=your_secure_password
rpcbind=0.0.0.0
rpcallowip=172.19.0.0/16
zmqpubrawblock=tcp://0.0.0.0:29000
zmqpubrawtx=tcp://0.0.0.0:29000
txindex=1
server=1
listen=1
```
### 3. Configuration Blindbit
```bash
# Vérifier la configuration Blindbit
cat blindbit/blindbit.toml
# Modifier si nécessaire
nano blindbit/blindbit.toml
```
**Configuration recommandée :**
```toml
# Configuration Blindbit
host = "0.0.0.0:8000"
chain = "signet"
rpc_endpoint = "http://bitcoin:18443"
cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie"
sync_start_height = 1
max_parallel_tweak_computations = 4
max_parallel_requests = 4
```
### 4. Configuration des Relais
```bash
# Vérifier les configurations des relais
ls -la sdk_relay/.conf.docker.*
# Modifier si nécessaire
nano sdk_relay/.conf.docker.relay1
nano sdk_relay/.conf.docker.relay2
nano sdk_relay/.conf.docker.relay3
```
**Configuration recommandée pour chaque relay :**
```ini
core_url=http://bitcoin:18443
core_wallet=relay_wallet
ws_url=0.0.0.0:8090
wallet_name=relay_wallet.json
network=signet
blindbit_url=http://blindbit:8000
zmq_url=tcp://bitcoin:29000
data_dir=.4nk
cookie_path=/home/bitcoin/.4nk/bitcoin.cookie
dev_mode=true
standalone=false
relay_id=relay-1 # Changer pour chaque relay
```
## 🚀 Démarrage
### 1. Démarrage Complet
```bash
# Démarrer tous les services
./restart_4nk_node.sh
# Vérifier le statut
docker ps
```
### 2. Démarrage Séquentiel (Debug)
```bash
# Démarrer Tor
./restart_4nk_node.sh -t
# Démarrer Bitcoin Core
./restart_4nk_node.sh -b
# Attendre la synchronisation Bitcoin (10-30 minutes)
echo "Attendre la synchronisation Bitcoin..."
docker logs bitcoin-signet | grep "progress"
# Démarrer Blindbit
./restart_4nk_node.sh -l
# Démarrer les relais
./restart_4nk_node.sh -r
```
### 3. Vérification du Démarrage
```bash
# Vérifier tous les services
docker ps
# Vérifier les logs
docker-compose logs --tail=50
# Vérifier la connectivité
./test_final_sync.sh
``` ```
## 🧪 Tests Post-Installation ## 🧪 Tests Post-Installation
### 1. Tests de Connectivité ### 1. Tests de Compilation
```bash ```bash
# Test de base # Test de compilation en mode debug
./test_final_sync.sh cargo build
# Test de synchronisation # Test de compilation en mode release
./test_sync_logs.sh cargo build --release
# Test des messages WebSocket # Test de compilation avec toutes les features
python3 test_websocket_messages.py cargo build --all-features
``` ```
### 2. Tests de Performance ### 2. Tests Unitaires
```bash ```bash
# Vérifier l'utilisation des ressources # Tests unitaires de base
docker stats cargo test
# Test de charge # Tests avec output détaillé
python3 test_websocket_messages.py --load-test cargo test -- --nocapture
# Monitoring de la synchronisation # Tests avec couverture
./monitor_sync.sh cargo tarpaulin --out Html
``` ```
### 3. Tests de Sécurité ### 3. Tests d'Intégration
```bash ```bash
# Vérifier les ports exposés # Tests d'intégration
netstat -tlnp | grep -E "(18443|8000|9050|8090)" cargo test --test integration
# Vérifier les permissions # Tests de performance
ls -la sdk_relay/.conf* cargo test --test performance
ls -la bitcoin/bitcoin.conf
ls -la blindbit/blindbit.toml # Tests de sécurité
cargo audit
```
### 4. Tests WASM
```bash
# Compilation WASM
wasm-pack build --target web
# Tests WASM
wasm-pack test --headless --firefox
wasm-pack test --headless --chrome
```
### 5. Tests de Linting
```bash
# Clippy (linter Rust)
cargo clippy -- -D warnings
# Formatage
cargo fmt -- --check
# Audit de sécurité
cargo audit
``` ```
## 🔧 Configuration Avancée ## 🔧 Configuration Avancée
### 1. Configuration Réseau ### Configuration Cargo
```bash **`Cargo.toml` - Configuration de base :**
# Créer un réseau Docker personnalisé
docker network create 4nk-network --subnet=172.20.0.0/16
# Modifier docker-compose.yml ```toml
sed -i 's/4nk_default/4nk-network/g' docker-compose.yml [package]
name = "sdk_common"
version = "0.1.0"
edition = "2021"
authors = ["4NK Team <team@4nkweb.com>"]
description = "Bibliothèque commune pour les Silent Payments"
license = "MIT"
repository = "https://git.4nkweb.com/4nk/sdk_common"
keywords = ["bitcoin", "silent-payments", "cryptography"]
categories = ["cryptography", "blockchain"]
[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
thiserror = "1.0"
log = "0.4"
env_logger = "0.10"
[dev-dependencies]
tokio = { version = "1.0", features = ["full"] }
criterion = "0.5"
[features]
default = ["std"]
std = []
wasm = ["getrandom/js"]
blindbit-wasm = ["wasm", "js-sys", "web-sys"]
[lib]
name = "sdk_common"
crate-type = ["cdylib", "rlib"]
``` ```
### 2. Configuration SSL/TLS ### Configuration de Build
```bash **Optimisations de performance :**
# Générer un certificat auto-signé
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
# Configurer nginx comme proxy SSL ```toml
cat > nginx.conf << EOF [profile.release]
server { opt-level = 3
listen 443 ssl; lto = true
server_name your-domain.com; codegen-units = 1
panic = "abort"
strip = true
ssl_certificate cert.pem; [profile.dev]
ssl_certificate_key key.pem; opt-level = 0
debug = true
location / {
proxy_pass http://localhost:8090;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host \$host;
}
}
EOF
``` ```
### 3. Configuration de Pare-feu ### Configuration des Tests
```bash **Configuration des tests dans `Cargo.toml` :**
# Autoriser seulement les ports nécessaires
sudo ufw allow 18443/tcp # Bitcoin Core RPC
sudo ufw allow 8090/tcp # sdk_relay WebSocket
sudo ufw allow 8000/tcp # Blindbit API
sudo ufw enable
# Vérifier les règles ```toml
sudo ufw status numbered [[test]]
name = "integration"
path = "tests/integration.rs"
harness = true
[[test]]
name = "performance"
path = "tests/performance.rs"
harness = true
[[bench]]
name = "benchmarks"
harness = false
``` ```
## 🚨 Dépannage ## 🚨 Dépannage
### Problèmes Courants ### Problèmes Courants
#### 1. Docker Non Installé #### Erreur de Compilation Rust
```bash ```bash
# Vérifier l'installation Docker # Mettre à jour Rust
docker --version rustup update
# Si non installé, suivre les étapes d'installation ci-dessus # Nettoyer le cache
cargo clean
# Recompiler
cargo build
``` ```
#### 2. Permissions Docker #### Erreur WASM
```bash ```bash
# Vérifier les permissions # Mettre à jour wasm-pack
docker ps cargo install wasm-pack --force
# Si erreur de permission # Nettoyer le build WASM
sudo usermod -aG docker $USER rm -rf pkg/
newgrp docker
# Recompiler WASM
wasm-pack build --target web
``` ```
#### 3. Ports Déjà Utilisés #### Erreur de Dépendances
```bash ```bash
# Vérifier les ports utilisés # Mettre à jour les dépendances
sudo netstat -tlnp | grep -E "(18443|8000|9050|8090)" cargo update
# Arrêter les services conflictuels # Vérifier les vulnérabilités
sudo docker-compose down cargo audit
# Nettoyer et recompiler
cargo clean && cargo build
``` ```
#### 4. Problèmes de Synchronisation Bitcoin #### Problèmes de Performance
```bash ```bash
# Vérifier les logs Bitcoin # Compiler en mode release
docker logs bitcoin-signet cargo build --release
# Vérifier l'espace disque # Activer les optimisations
df -h export RUSTFLAGS="-C target-cpu=native"
# Redémarrer Bitcoin Core # Utiliser LTO
docker restart bitcoin-signet export RUSTFLAGS="-C lto=fat"
``` ```
### Logs Utiles ### Logs et Debug
```bash ```bash
# Logs de tous les services # Activer les logs détaillés
docker-compose logs -f export RUST_LOG=debug
# Logs d'un service spécifique # Activer le backtrace
docker logs bitcoin-signet export RUST_BACKTRACE=1
docker logs blindbit-oracle
docker logs sdk_relay_1
# Logs avec timestamps # Exécuter avec logs
docker-compose logs -t cargo run --bin sdk_common
```
# Logs depuis une date ## 🔒 Sécurité
docker-compose logs --since="2024-01-01T00:00:00"
### Bonnes Pratiques
1. **Mise à jour régulière** : Maintenir Rust et les dépendances à jour
2. **Audit de sécurité** : Exécuter `cargo audit` régulièrement
3. **Tests de sécurité** : Inclure des tests de sécurité dans la suite de tests
4. **Validation des entrées** : Valider toutes les entrées utilisateur
5. **Gestion des erreurs** : Gérer proprement les erreurs sans exposer d'informations sensibles
### Configuration de Sécurité
```bash
# Activer les vérifications de sécurité
export RUSTFLAGS="-C overflow-checks=on"
# Activer les sanitizers (Linux/macOS)
export RUSTFLAGS="-Z sanitizer=address"
# Tests de sécurité
cargo test --features security-tests
``` ```
## 📊 Monitoring ## 📊 Monitoring
### 1. Monitoring de Base ### Métriques de Build
```bash ```bash
# Statut des conteneurs # Taille du binaire
docker ps ls -lh target/release/libsdk_common.*
# Utilisation des ressources # Taille WASM
docker stats ls -lh pkg/sdk_common_bg.wasm
# Espace disque # Temps de compilation
docker system df time cargo build --release
``` ```
### 2. Monitoring Avancé ### Métriques de Performance
```bash ```bash
# Surveillance de la synchronisation # Benchmarks
./monitor_sync.sh cargo bench
# Monitoring en continu # Profiling
while true; do cargo install flamegraph
echo "=== $(date) ===" cargo flamegraph --bin sdk_common
docker stats --no-stream | grep -E "(sdk_relay|bitcoin)"
sleep 30 # Couverture de code
done cargo tarpaulin --out Html
``` ```
### 3. Alertes ## 🎯 Prochaines Étapes
```bash ### 1. Intégration
# Script d'alerte simple
cat > monitor_alert.sh << 'EOF'
#!/bin/bash
if ! docker ps | grep -q "bitcoin-signet.*Up"; then
echo "ALERTE: Bitcoin Core n'est pas en cours d'exécution!"
# Ajouter notification (email, Slack, etc.)
fi
EOF
chmod +x monitor_alert.sh - [Guide d'Utilisation](USAGE.md) - Utiliser la bibliothèque
``` - [Guide de Configuration](CONFIGURATION.md) - Configurer selon vos besoins
- [API Reference](API.md) - Consulter les APIs
## 🔄 Mise à Jour ### 2. Développement
### 1. Mise à Jour de l'Infrastructure - [Guide de Développement](DEVELOPMENT.md) - Contribuer au développement
- [Guide des Tests](TESTING.md) - Écrire et exécuter des tests
- [Architecture](ARCHITECTURE.md) - Comprendre l'architecture
```bash ### 3. Intégration avec 4NK_node
# Sauvegarder la configuration
cp -r . ../4NK_node_backup_$(date +%Y%m%d)
# Mettre à jour le code - [Intégration 4NK_node](INTEGRATION_4NK_NODE.md) - Intégrer avec l'infrastructure
git pull origin main - [Configuration SSH](SSH_SETUP.md) - Configurer SSH pour l'automatisation
- [Push SSH Automatisé](AUTO_SSH_PUSH.md) - Automatiser les déploiements
# Redémarrer les services
./restart_4nk_node.sh
```
### 2. Mise à Jour de Docker
```bash
# Mettre à jour Docker
sudo apt update
sudo apt upgrade docker-ce docker-ce-cli containerd.io
# Redémarrer Docker
sudo systemctl restart docker
```
### 3. Mise à Jour des Images
```bash
# Reconstruire les images
docker-compose build --no-cache
# Redémarrer les services
docker-compose up -d
```
## 📝 Checklist d'Installation
- [ ] Docker installé et configuré
- [ ] Docker Compose installé
- [ ] Clé SSH configurée pour GitLab
- [ ] Repository cloné
- [ ] Variables d'environnement configurées
- [ ] Configurations Bitcoin Core vérifiées
- [ ] Configurations Blindbit vérifiées
- [ ] Configurations des relais vérifiées
- [ ] Services démarrés avec succès
- [ ] Tests de connectivité passés
- [ ] Tests de synchronisation passés
- [ ] Monitoring configuré
- [ ] Pare-feu configuré (optionnel)
- [ ] SSL/TLS configuré (optionnel)
## 🎉 Installation Terminée
Félicitations ! L'infrastructure 4NK Node est maintenant installée et configurée.
**Prochaines étapes :**
1. Consulter le [Guide d'Utilisation](USAGE.md)
2. Configurer les [Nœuds Externes](EXTERNAL_NODES.md)
3. Tester la [Synchronisation](SYNCHRONIZATION.md)
4. Configurer le [Monitoring](PERFORMANCE.md)
--- ---
**📦 Installation réussie ! La bibliothèque sdk_common est maintenant prête à être utilisée.** 🚀

888
docs/USAGE.md
View File

File diff suppressed because it is too large Load Diff