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

877
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
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
```
┌─────────────────────────────────────────────────────────────┐
│ sdk_common │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ Types │ │ Traits │ │ Utils │ │
│ │ │ │ │ │ │ │
│ │ • Wallet │ │ • WalletOps │ │ • Validation │ │
│ │ • Transaction │ │ • PaymentOps │ │ • Serialize │ │
│ │ • SilentPayment │ │ • NetworkOps │ │ • Crypto │ │
│ │ • Address │ │ • ErrorOps │ │ • Encoding │ │
│ └─────────────────┘ └─────────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Bitcoin Core │ │ Blindbit │ │ SDK Relay 1 │
│ (Signet) │ │ (Service SP) │ │ (WebSocket) │
│ Port: 18443 │ │ Port: 8000 │ │ Port: 8090 │
│ sdk_client │ │ sdk_relay │ │ Applications │
│ (WASM/JS) │ │ (Rust) │ │ (Rust/JS) │
│ │ │ │ │ │
│ • 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
### 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 :**
- **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 :
**Structures principales :**
```rust
pub struct SyncManager {
relay_id: String,
sequence_counter: Arc<Mutex<u64>>,
sync_cache: Arc<Mutex<HashMap<String, Instant>>>,
last_sync: Arc<Mutex<HashMap<SyncType, u64>>>,
mesh_connections: Arc<Mutex<HashMap<String, MeshConnection>>>,
known_relays: Arc<Mutex<HashMap<String, RelayInfo>>>,
metrics: Arc<Mutex<SyncMetrics>>,
// Wallet - Gestion des clés et identités
pub struct Wallet {
pub private_key: PrivateKey,
pub public_key: PublicKey,
pub address: Address,
}
// 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
- **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
**Rôle :** Définition des interfaces et contrats pour les opérations communes.
### Messages de Synchronisation
#### Structure des Messages
**Traits principaux :**
```rust
pub struct SyncMessage {
pub sync_type: SyncType,
pub relay_id: String,
pub sequence: u64,
pub timestamp: u64,
pub payload: SyncPayload,
// Opérations de wallet
pub trait WalletOperations {
fn generate_address(&self) -> Result<Address, SdkError>;
fn sign_transaction(&self, tx: &Transaction) -> Result<Signature, SdkError>;
fn verify_signature(&self, sig: &Signature, msg: &[u8]) -> bool;
}
// 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
pub enum SyncPayload {
StateData { state: String, version: String },
ProcessData { processes: HashMap<String, String> },
MemberData { members: HashMap<String, String> },
HealthData { status: HealthStatus, uptime: u64, cpu_usage: f64 },
MetricsData { metrics: SyncMetrics },
PeerData { peers: Vec<PeerInfo>, last_seen: u64 },
RelayData { relays: Vec<RelayInfo>, network_topology: NetworkTopology },
// Validation
pub mod validation {
pub fn is_valid_bitcoin_address(address: &str) -> bool;
pub fn is_valid_transaction_hex(hex: &str) -> bool;
pub fn is_valid_private_key(key: &str) -> bool;
}
// 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
Le système implémente une découverte automatique des relais dans le réseau :
### 1. Génération de Paiement Silencieux
```rust
pub async fn discover_relays(&self) -> Result<()> {
let relay_hosts = vec![
"sdk_relay_1",
"sdk_relay_2",
"sdk_relay_3",
];
pub struct SilentPaymentGenerator {
wallet: Wallet,
network: Network,
}
for host in relay_hosts {
if host == self.relay_id {
continue; // Ignorer soi-même
}
let relay_info = RelayInfo {
relay_id: host.to_string(),
address: format!("{}:8090", host),
// ... autres champs
};
self.add_relay(relay_info)?;
impl SilentPaymentGenerator {
pub fn new(wallet: Wallet, network: Network) -> Self {
Self { wallet, network }
}
pub fn generate_payment(&self) -> Result<SilentPayment, SdkError> {
// 1. Générer la clé de scan
let scan_key = self.generate_scan_key()?;
// 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(())
}
}
```
### 3. Protection contre les Attaques
```rust
pub struct SecurityManager {
rate_limiter: RateLimiter,
input_sanitizer: InputSanitizer,
}
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)
}
}
```
## Architecture de Performance
### 1. Optimisations Rust
```rust
// Utilisation de references pour éviter les copies
pub fn process_wallet_optimized(wallet: &Wallet) -> Result<(), SdkError> {
// Traitement sans copie
wallet.process_transactions()?;
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>>>,
// Utilisation de iterators pour les performances
pub fn process_transactions_batch(txs: &[Transaction]) -> Vec<Result<(), SdkError>> {
txs.iter()
.map(|tx| process_transaction(tx))
.collect()
}
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
}
// Utilisation de Box pour les gros objets
pub fn create_large_wallet() -> Box<Wallet> {
Box::new(Wallet::new().unwrap())
}
```
### 2. Optimisations WASM
```rust
#[cfg(feature = "wasm")]
pub mod wasm_optimizations {
use wasm_bindgen::prelude::*;
// Utilisation de Web Workers pour les calculs lourds
#[wasm_bindgen]
pub fn process_payment_async(payment_data: JsValue) -> js_sys::Promise {
// Traitement asynchrone
wasm_bindgen_futures::JsFuture::from(
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)
}
}
```
### 3. Synchronisation Périodique
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
### 3. Cache et Mémoire
```rust
pub struct MeshConnection {
pub relay_id: String,
pub address: String,
pub connected_since: u64,
pub last_heartbeat: u64,
pub status: ConnectionStatus,
pub struct CacheManager {
wallet_cache: LruCache<String, Wallet>,
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);
}
}
```
## Configuration Multi-Relais
## Architecture de Monitoring
### Configuration Docker
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
### 1. Métriques de Performance
```rust
pub struct SyncMetrics {
pub messages_sent: u64,
pub messages_received: u64,
pub sync_errors: u64,
pub last_sync_timestamp: u64,
pub connected_relays: u64,
pub mesh_health: f64,
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()
}
}
```
## Flux de Données
### 2. Logs et Debug
### 1. Flux de Synchronisation
```rust
pub struct Logger {
level: LogLevel,
output: Box<dyn LogOutput>,
}
```
Relay 1 ──┐
├─── SyncManager ──── MessageCache ──── Mesh Network
Relay 2 ──┤
│
Relay 3 ──┘
impl Logger {
pub fn log(&self, level: LogLevel, message: &str) {
if level >= self.level {
self.output.write(level, message);
}
}
pub fn debug(&self, message: &str) {
self.log(LogLevel::Debug, message);
}
pub fn info(&self, message: &str) {
self.log(LogLevel::Info, message);
}
pub fn error(&self, message: &str) {
self.log(LogLevel::Error, message);
}
}
```
### 2. Flux de Traitement des Transactions
## Architecture de Déploiement
```
Bitcoin Core ──── ZMQ Notifications ──── SDK Relay ──── Blindbit
│ │ │ │
└─── Block Scan ─────┴─── Silent Payment ─┴─── Validation
### 1. Support Multi-Plateforme
```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
}
#[cfg(not(target_arch = "wasm32"))]
pub mod native_config {
pub const MAX_MEMORY: usize = 1024 * 1024 * 1024; // 1GB
pub const STACK_SIZE: usize = 8 * 1024 * 1024; // 8MB
}
```
### 3. Flux de Communication WebSocket
### 2. Features Conditionnelles
```
Client ──── WebSocket ──── SDK Relay ──── Bitcoin Core RPC
│ │ │
└─── Events ─┴─── Commands ─┴─── Responses
```rust
// Features pour différentes configurations
#[cfg(feature = "std")]
pub mod std_support {
pub use std::collections::HashMap;
pub use std::time::Instant;
}
#[cfg(feature = "wasm")]
pub mod wasm_support {
pub use js_sys::Object;
pub use wasm_bindgen::prelude::*;
}
#[cfg(feature = "blindbit-wasm")]
pub mod blindbit_wasm {
pub use js_sys;
pub use web_sys;
}
```
## Sécurité et Isolation
### 3. Intégration CI/CD
### 1. Isolation Réseau
```rust
// Tests conditionnels pour différents environnements
#[cfg(test)]
mod tests {
#[test]
fn test_wallet_creation() {
// Test de base
}
#[cfg(feature = "wasm")]
#[test]
fn test_wasm_integration() {
// Test WASM
}
#[cfg(feature = "blindbit-wasm")]
#[test]
fn test_blindbit_wasm() {
// Test Blindbit WASM
}
}
```
- **Réseau privé :** `btcnet` pour la communication inter-services
- **Ports exposés :** Seulement les ports nécessaires
- **Volumes :** Données persistantes isolées
## Évolutions Futures
### 2. Authentification
### 1. Extensions Planifiées
- **Bitcoin Core :** Cookie d'authentification
- **Blindbit :** À définir selon les besoins
- **SDK Relay :** Authentification WebSocket
- **Tor :** Pas d'authentification requise
- **Support de nouveaux réseaux** : Lightning Network, Liquid
- **Optimisations avancées** : SIMD, GPU acceleration
- **Nouvelles fonctionnalités** : Multi-signature, Time-locks
- **Intégrations** : Support de nouveaux wallets et services
### 3. Chiffrement
### 2. Améliorations de Performance
- **RPC Bitcoin :** HTTP (non chiffré en local)
- **HTTP Blindbit :** HTTP (non chiffré en local)
- **WebSocket SDK Relay :** WSS (chiffré)
- **Tor :** Chiffrement intégré
- **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
## Performance et Optimisations
### 3. Sécurité Renforcée
### 1. Ressources Requises
- **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
- **CPU :** Minimum 2 cœurs
- **RAM :** Minimum 4 GB
- **Stockage :** Minimum 50 GB pour la blockchain
- **Réseau :** Connexion stable à Internet
---
### 2. Optimisations Implémentées
- **Cache :** Mise en cache des données fréquemment utilisées
- **Compression :** Compression des données de blockchain
- **Parallélisation :** Traitement parallèle des blocs
- **Monitoring :** Métriques de performance
### 3. Métriques de Performance
- **Latence de synchronisation :** < 100ms
- **Débit de messages :** > 1000 msg/s
- **Utilisation mémoire :** < 2GB par relais
- **Temps de démarrage :** < 30 secondes
## Monitoring et Observabilité
### 1. Métriques Collectées
- **Métriques système :** CPU, RAM, disque, réseau
- **Métriques de synchronisation :** Messages envoyés/reçus, erreurs
- **Métriques de santé :** Uptime, statut des connexions
- **Métriques métier :** Transactions traitées, paiements détectés
### 2. Logs
- **Logs système :** Démarrage, arrêt, erreurs
- **Logs de synchronisation :** Messages, erreurs, métriques
- **Logs métier :** Transactions, paiements, événements
### 3. Alertes
- **Alertes critiques :** Services arrêtés, erreurs de synchronisation
- **Alertes de performance :** Latence élevée, utilisation mémoire
- **Alertes métier :** Échecs de traitement, anomalies
## Évolutivité
### 1. Scalabilité Horizontale
- **Ajout de relais :** Configuration automatique
- **Load balancing :** Distribution de charge
- **Redondance :** Relais de secours
### 2. Scalabilité Verticale
- **Ressources :** Augmentation CPU/RAM
- **Stockage :** Extension des volumes
- **Réseau :** Bande passante
### 3. Architecture Distribuée
- **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
**🏗️ Architecture sdk_common - Fondation solide pour les Silent Payments** 🚀

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
### 🚀 [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**
- **Installation de Docker et dépendances**
- **Configuration SSH et GitLab**
- **Configuration initiale des services**
- **Installation de Rust et dépendances**
- **Configuration Cargo et features**
- **Tests post-installation**
- **Dépannage et monitoring**
### 📖 [Guide d'Utilisation](USAGE.md)
Guide complet pour utiliser l'infrastructure 4NK Node au quotidien.
- **Démarrage quotidien des services**
- **Opérations de surveillance et monitoring**
- **Utilisation du réseau de relais**
- **Connexion aux services (Bitcoin Core, Blindbit, sdk_relay)**
Guide complet pour utiliser la bibliothèque sdk_common au quotidien.
- **Compilation et build**
- **Intégration dans les projets**
- **Utilisation des types et structures**
- **Tests et validation**
- **Configuration et maintenance**
- **Gestion des nœuds externes**
- **Optimisations de performance**
### ⚙️ [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 Bitcoin Core (base et avancée)**
- **Configuration Blindbit (base et avancée)**
- **Configuration des relais (base et avancée)**
- **Configuration des nœuds externes**
- **Configuration Tor**
- **Configuration Docker Compose**
- **Configuration SSL/TLS**
- **Configuration de monitoring et sauvegarde**
- **Configuration Rust et Cargo**
- **Configuration des features**
- **Configuration de build**
- **Configuration de tests**
- **Configuration de sécurité**
## 🔧 Guides Techniques
### 🏗️ [Architecture Technique](ARCHITECTURE.md)
Documentation technique détaillée de l'architecture.
- **Architecture générale du système**
- **Composants principaux (Bitcoin Core, Blindbit, SDK Relay)**
- **Architecture de synchronisation mesh**
- **Flux de données entre services**
- **Configuration multi-relais**
- **Architecture générale de la bibliothèque**
- **Composants principaux (types, structures, traits)**
- **Architecture des Silent Payments**
- **Flux de données et types**
- **Intégration avec sdk_client et sdk_relay**
- **Sécurité et isolation**
- **Performance et optimisations**
- **Monitoring et observabilité**
### 📡 [API Reference](API.md)
Documentation complète des APIs disponibles.
- **API Bitcoin Core RPC** : Interface JSON-RPC pour Bitcoin
- **API Blindbit HTTP** : API REST pour les paiements silencieux
- **API SDK Relay WebSocket** : Interface temps réel pour les clients
- **API SDK Relay HTTP** : API REST pour les opérations de gestion
- **Format des messages et payloads**
- **API Types** : Types et structures de données
- **API Traits** : Traits et interfaces
- **API Functions** : Fonctions utilitaires
- **API Error Handling** : Gestion des erreurs
- **Format des données et payloads**
- **Gestion des erreurs**
- **Exemples d'utilisation**
- **Limites et quotas**
@ -63,7 +58,7 @@ Documentation complète des APIs disponibles.
Guide de sécurité et bonnes pratiques.
- **Authentification et autorisation**
- **Chiffrement et certificats**
- **Isolation réseau**
- **Sécurité des types et structures**
- **Audit et monitoring de sécurité**
- **Bonnes pratiques**
@ -98,215 +93,191 @@ Roadmap de développement détaillée.
- **Fonctionnalités planifiées**
- **Évolution de l'architecture**
- **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
### 🧪 [Guide de Tests](TESTING.md)
Guide complet des tests de l'infrastructure 4NK Node.
- **Tests unitaires** : Tests individuels des composants
- **Tests d'intégration** : Tests d'interaction entre services
- **Tests de connectivité** : Tests réseau et WebSocket
- **Tests externes** : Tests avec des nœuds externes
- **Tests de performance** : Tests de charge et performance (à venir)
- **Organisation et exécution des tests**
- **Interprétation des résultats**
- **Dépannage et maintenance**
### 🧪 [Guide des Tests](TESTING.md)
Guide complet pour les tests de la bibliothèque.
- **Tests unitaires Rust**
- **Tests d'intégration**
- **Tests de performance**
- **Tests de sécurité**
- **Tests de compatibilité**
- **Tests de régression**
### 🔄 [Tests de Synchronisation](SYNC_TESTING.md)
Guide des tests de synchronisation entre relais.
- **Tests de synchronisation mesh**
- **Tests de découverte de relais**
- **Tests de cache de déduplication**
- **Tests de métriques de synchronisation**
- **Troubleshooting de la synchronisation**
### 🔍 [Audit de Sécurité](SECURITY_AUDIT.md)
Audit de sécurité détaillé.
- **Vulnérabilités connues**
- **Tests de pénétration**
- **Audit de code**
- **Recommandations de sécurité**
- **Plan de remédiation**
### 📊 [Tests de Performance](PERFORMANCE_TESTING.md)
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 de Développement
## 🌐 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)
Guide de configuration du réseau mesh de relais.
- **Architecture mesh**
- **Configuration des relais locaux**
- **Synchronisation entre relais**
- **Découverte automatique**
- **Gestion des connexions**
### 📋 [Référence Rapide](QUICK_REFERENCE.md)
Référence rapide pour les développeurs.
- **Commandes essentielles**
- **Structure du projet**
- **APIs principales**
- **Configuration rapide**
- **Dépannage rapide**
### 🌍 [Nœuds Externes](EXTERNAL_NODES.md)
Guide d'ajout et de gestion de nœuds externes.
- **Configuration des nœuds externes**
- **Script d'administration**
- **Validation et sécurité**
- **Tests de connectivité**
- **Gestion multi-sites**
### 🔄 [Guide de Migration](MIGRATION.md)
Guide pour les migrations et mises à jour.
- **Migration des versions**
- **Breaking changes**
- **Mise à jour des dépendances**
- **Migration des données**
- **Tests de migration**
### 🔄 [Synchronisation](SYNCHRONIZATION.md)
Guide du protocole de synchronisation.
- **Protocole de synchronisation**
- **Types de messages**
- **Cache de déduplication**
- **Métriques de synchronisation**
- **Troubleshooting**
## 🌐 Guides d'Intégration
## 📋 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)
Référence rapide des commandes essentielles.
- **Commandes de démarrage**
- **Commandes de monitoring**
- **Commandes de test**
- **Commandes de dépannage**
- **Commandes de maintenance**
### 🔑 [Configuration SSH](SSH_SETUP.md)
Guide de configuration SSH pour le développement.
- **Génération des clés SSH**
- **Configuration Git**
- **Intégration avec Gitea**
- **Automatisation des déploiements**
### 📋 [Troubleshooting](TROUBLESHOOTING.md)
Guide de résolution des problèmes courants.
- **Problèmes de démarrage**
- **Problèmes de connectivité**
- **Problèmes de synchronisation**
- **Problèmes de performance**
- **Logs et diagnostics**
### 🤖 [Push SSH Automatisé](AUTO_SSH_PUSH.md)
Guide pour l'automatisation des pushes SSH.
- **Configuration des scripts**
- **Intégration CI/CD**
- **Gestion des clés**
- **Sécurité et bonnes pratiques**
### 📋 [FAQ](FAQ.md)
Questions fréquemment posées.
- **Questions d'installation**
- **Questions de configuration**
- **Questions d'utilisation**
- **Questions de performance**
- **Questions de sécurité**
## 📊 État et Monitoring
## 📁 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**
```
4NK_node/
├── README.md # Documentation principale
├── docs/ # Documentation organisée
│ ├── INDEX.md # Cet index
│ ├── INSTALLATION.md # Guide d'installation
│ ├── 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
```
### 📋 [Résumé Final](RESUME_FINAL.md)
Résumé complet de l'état final du projet.
- **Succès accomplis**
- **Prêt pour la production**
- **Documentation complète**
- **Support et maintenance**
## 🎯 Parcours d'Apprentissage
## 🔧 Guides d'Open Source
### 🚀 **Débutant**
1. [Guide d'Installation](INSTALLATION.md) - Installer l'infrastructure
2. [Guide d'Utilisation](USAGE.md) - Utiliser les services de base
3. [Tests de Base](TESTING.md) - Vérifier le fonctionnement
4. [FAQ](FAQ.md) - Réponses aux questions courantes
### ✅ [Checklist Open Source](OPEN_SOURCE_CHECKLIST.md)
Checklist complète pour l'ouverture en open source.
- **Préparation du code**
- **Documentation**
- **Licences et légal**
- **Infrastructure**
- **Communication**
### 🔧 **Intermédiaire**
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
## 📞 Support et Contact
### 🏗️ **Avancé**
1. [Architecture Technique](ARCHITECTURE.md) - Comprendre l'architecture
2. [API Reference](API.md) - Utiliser les APIs
3. [Sécurité](SECURITY.md) - Sécuriser l'infrastructure
4. [Performance](PERFORMANCE.md) - Optimiser les performances
5. [Tests de Performance](PERFORMANCE_TESTING.md) - Tests avancés
### 🛠️ **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
### 📞 [Support](SUPPORT.md)
Guide de support et contact.
- **Comment obtenir de l'aide**
- **Création d'issues**
- **Canal de communication**
- **FAQ**
- **Ressources additionnelles**
---
## 🎯 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
### Système
- **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
- **Architecture** : x86_64
- **RAM** : 4 Go minimum, 8 Go recommandés
- **Stockage** : 20 Go minimum, 50 Go recommandés
- **Réseau** : Connexion Internet stable
- **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+), macOS 10.15+, Windows 10+
- **Architecture** : x86_64, ARM64 (pour certaines plateformes)
- **RAM** : 2 Go minimum, 4 Go recommandés
- **Stockage** : 5 Go minimum, 10 Go recommandés
- **Réseau** : Connexion Internet stable pour télécharger les dépendances
### Logiciels
- **Docker** : Version 20.10+
- **Docker Compose** : Version 2.0+
- **Rust** : Version 1.70+ (stable)
- **Cargo** : Inclus avec Rust
- **Git** : Version 2.25+
- **Bash** : Version 4.0+
- **wasm-pack** : Version 0.12+ (pour compilation WASM)
- **Node.js** : Version 18+ (pour tests WASM)
## 🚀 Installation
### 1. Installation de Docker
### 1. Installation de Rust
#### Ubuntu/Debian
#### Linux/macOS
```bash
# Mettre à jour les paquets
sudo apt update
# Installer Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Installer les dépendances
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
# Recharger l'environnement
source ~/.cargo/env
# Ajouter la clé GPG Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# 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
# Vérifier l'installation
rustc --version
cargo --version
```
#### CentOS/RHEL
#### Windows
```bash
# Installer les dépendances
sudo yum install -y yum-utils
# Ajouter le repository Docker
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
# Télécharger et installer rustup-init.exe depuis
# https://rustup.rs/
# Puis exécuter dans PowerShell :
rustup-init.exe
```
### 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
# 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
ssh-add ~/.ssh/id_ed25519_4nk
ssh-add ~/.ssh/id_ed25519_sdk_common
# 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
cat ~/.ssh/id_ed25519_4nk.pub
# Afficher la clé publique pour Gitea
cat ~/.ssh/id_ed25519_sdk_common.pub
```
**Ajouter la clé publique à GitLab :**
1. Aller sur GitLab > Settings > SSH Keys
**Ajouter la clé publique à Gitea :**
1. Aller sur Gitea > Settings > SSH Keys
2. Coller la clé publique
3. Cliquer sur "Add key"
### 3. Clonage du Repository
### 4. Clonage du Repository
```bash
# Cloner avec SSH (recommandé)
git clone git@git.4nkweb.com:4nk/4NK_node.git
cd 4NK_node
git clone git@git.4nkweb.com:4nk/sdk_common.git
cd sdk_common
# Ou avec HTTPS (si SSH non configuré)
# git clone https://git.4nkweb.com/4nk/4NK_node.git
# cd 4NK_node
# Ou cloner avec HTTPS
git clone https://git.4nkweb.com/4nk/sdk_common.git
cd sdk_common
```
### 4. Vérification de l'Installation
### 5. Configuration de l'Environnement
```bash
# Vérifier Docker
docker --version
docker-compose --version
# Créer le fichier de configuration
cp .env.example .env
# Vérifier la connectivité GitLab
ssh -T git@git.4nkweb.com
# Vérifier les permissions
ls -la
# Éditer les variables d'environnement
nano .env
```
## 🔧 Configuration Initiale
### 1. Configuration des Variables d'Environnement
**Variables d'environnement principales :**
```bash
# Créer le fichier d'environnement
cat > .env << EOF
# Configuration 4NK Node
PROJECT_NAME=4NK Node
NETWORK_NAME=4nk_node_btcnet
# Configuration Rust
RUST_LOG=info
RUST_BACKTRACE=1
# Logs
RUST_LOG=debug,bitcoincore_rpc=trace
# Configuration de build
CARGO_PROFILE_RELEASE_OPT_LEVEL=3
CARGO_PROFILE_RELEASE_LTO=true
# Bitcoin
BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie
# Configuration des tests
TEST_TIMEOUT=300
TEST_PARALLEL=true
# Synchronisation
ENABLE_SYNC_TEST=1
# 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
# Configuration WASM
WASM_PACK_TARGET=web
WASM_PACK_PROFILE=release
```
### 2. Configuration Bitcoin Core
### 6. Installation des Dépendances
```bash
# Vérifier la configuration Bitcoin
cat bitcoin/bitcoin.conf
# Mettre à jour Rust
rustup update
# Modifier si nécessaire
nano bitcoin/bitcoin.conf
```
# Installer les dépendances Rust
cargo build
**Configuration recommandée :**
```ini
# Configuration Bitcoin Core Signet
signet=1
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
# Installer les dépendances de développement
cargo install cargo-audit
cargo install cargo-tarpaulin
cargo install cargo-watch
```
## 🧪 Tests Post-Installation
### 1. Tests de Connectivité
### 1. Tests de Compilation
```bash
# Test de base
./test_final_sync.sh
# Test de compilation en mode debug
cargo build
# Test de synchronisation
./test_sync_logs.sh
# Test de compilation en mode release
cargo build --release
# Test des messages WebSocket
python3 test_websocket_messages.py
# Test de compilation avec toutes les features
cargo build --all-features
```
### 2. Tests de Performance
### 2. Tests Unitaires
```bash
# Vérifier l'utilisation des ressources
docker stats
# Tests unitaires de base
cargo test
# Test de charge
python3 test_websocket_messages.py --load-test
# Tests avec output détaillé
cargo test -- --nocapture
# Monitoring de la synchronisation
./monitor_sync.sh
# Tests avec couverture
cargo tarpaulin --out Html
```
### 3. Tests de Sécurité
### 3. Tests d'Intégration
```bash
# Vérifier les ports exposés
netstat -tlnp | grep -E "(18443|8000|9050|8090)"
# Tests d'intégration
cargo test --test integration
# Vérifier les permissions
ls -la sdk_relay/.conf*
ls -la bitcoin/bitcoin.conf
ls -la blindbit/blindbit.toml
# Tests de performance
cargo test --test performance
# 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
### 1. Configuration Réseau
### Configuration Cargo
```bash
# Créer un réseau Docker personnalisé
docker network create 4nk-network --subnet=172.20.0.0/16
**`Cargo.toml` - Configuration de base :**
# Modifier docker-compose.yml
sed -i 's/4nk_default/4nk-network/g' docker-compose.yml
```toml
[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
# Générer un certificat auto-signé
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
**Optimisations de performance :**
# Configurer nginx comme proxy SSL
cat > nginx.conf << EOF
server {
listen 443 ssl;
server_name your-domain.com;
```toml
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = "abort"
strip = true
ssl_certificate cert.pem;
ssl_certificate_key key.pem;
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
[profile.dev]
opt-level = 0
debug = true
```
### 3. Configuration de Pare-feu
### Configuration des Tests
```bash
# 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
**Configuration des tests dans `Cargo.toml` :**
# Vérifier les règles
sudo ufw status numbered
```toml
[[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
### Problèmes Courants
#### 1. Docker Non Installé
#### Erreur de Compilation Rust
```bash
# Vérifier l'installation Docker
docker --version
# Mettre à jour Rust
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
# Vérifier les permissions
docker ps
# Mettre à jour wasm-pack
cargo install wasm-pack --force
# Si erreur de permission
sudo usermod -aG docker $USER
newgrp docker
# Nettoyer le build WASM
rm -rf pkg/
# Recompiler WASM
wasm-pack build --target web
```
#### 3. Ports Déjà Utilisés
#### Erreur de Dépendances
```bash
# Vérifier les ports utilisés
sudo netstat -tlnp | grep -E "(18443|8000|9050|8090)"
# Mettre à jour les dépendances
cargo update
# Arrêter les services conflictuels
sudo docker-compose down
# Vérifier les vulnérabilités
cargo audit
# Nettoyer et recompiler
cargo clean && cargo build
```
#### 4. Problèmes de Synchronisation Bitcoin
#### Problèmes de Performance
```bash
# Vérifier les logs Bitcoin
docker logs bitcoin-signet
# Compiler en mode release
cargo build --release
# Vérifier l'espace disque
df -h
# Activer les optimisations
export RUSTFLAGS="-C target-cpu=native"
# Redémarrer Bitcoin Core
docker restart bitcoin-signet
# Utiliser LTO
export RUSTFLAGS="-C lto=fat"
```
### Logs Utiles
### Logs et Debug
```bash
# Logs de tous les services
docker-compose logs -f
# Activer les logs détaillés
export RUST_LOG=debug
# Logs d'un service spécifique
docker logs bitcoin-signet
docker logs blindbit-oracle
docker logs sdk_relay_1
# Activer le backtrace
export RUST_BACKTRACE=1
# Logs avec timestamps
docker-compose logs -t
# Exécuter avec logs
cargo run --bin sdk_common
```
# Logs depuis une date
docker-compose logs --since="2024-01-01T00:00:00"
## 🔒 Sécurité
### 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
### 1. Monitoring de Base
### Métriques de Build
```bash
# Statut des conteneurs
docker ps
# Taille du binaire
ls -lh target/release/libsdk_common.*
# Utilisation des ressources
docker stats
# Taille WASM
ls -lh pkg/sdk_common_bg.wasm
# Espace disque
docker system df
# Temps de compilation
time cargo build --release
```
### 2. Monitoring Avancé
### Métriques de Performance
```bash
# Surveillance de la synchronisation
./monitor_sync.sh
# Benchmarks
cargo bench
# Monitoring en continu
while true; do
echo "=== $(date) ==="
docker stats --no-stream | grep -E "(sdk_relay|bitcoin)"
sleep 30
done
# Profiling
cargo install flamegraph
cargo flamegraph --bin sdk_common
# Couverture de code
cargo tarpaulin --out Html
```
### 3. Alertes
## 🎯 Prochaines Étapes
```bash
# 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
### 1. Intégration
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
# Sauvegarder la configuration
cp -r . ../4NK_node_backup_$(date +%Y%m%d)
### 3. Intégration avec 4NK_node
# Mettre à jour le code
git pull origin main
# 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)
- [Intégration 4NK_node](INTEGRATION_4NK_NODE.md) - Intégrer avec l'infrastructure
- [Configuration SSH](SSH_SETUP.md) - Configurer SSH pour l'automatisation
- [Push SSH Automatisé](AUTO_SSH_PUSH.md) - Automatiser les déploiements
---
**📦 Installation réussie ! La bibliothèque sdk_common est maintenant prête à être utilisée.** 🚀

900
docs/USAGE.md
View File

File diff suppressed because it is too large Load Diff