## Architecture Technique - sdk_common

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

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   │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   sdk_client    │    │   sdk_relay     │    │   Applications  │
│   (WASM/JS)     │    │   (Rust)        │    │   (Rust/JS)     │
│                 │    │                 │    │                 │
│ • Frontend      │    │ • Backend       │    │ • Intégration   │
│ • WebAssembly   │    │ • WebSocket     │    │ • API           │
│ • TypeScript    │    │ • HTTP API      │    │ • CLI           │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## Composants Principaux

### 1. Module Types

**Rôle :** Définition des structures de données fondamentales pour les Silent Payments.

**Structures principales :**

```rust
// 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>,
}
```

**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)

### 2. Module Traits

**Rôle :** Définition des interfaces et contrats pour les opérations communes.

**Traits principaux :**

```rust
// 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;
}
```

**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
// 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>;
}
```

## Architecture des Silent Payments

### 1. Génération de Paiement Silencieux

```rust
pub struct SilentPaymentGenerator {
    wallet: Wallet,
    network: Network,
}

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(())
}

// 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())
}
```

### 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. Cache et Mémoire

```rust
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);
    }
}
```

## Architecture de Monitoring

### 1. Métriques de Performance

```rust
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()
    }
}
```

### 2. Logs et Debug

```rust
pub struct Logger {
    level: LogLevel,
    output: Box<dyn LogOutput>,
}

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);
    }
}
```

## Architecture de Déploiement

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

### 2. Features Conditionnelles

```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;
}
```

### 3. Intégration CI/CD

```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
    }
}
```

## Évolutions Futures

### 1. Extensions Planifiées

- **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

### 2. Améliorations de Performance

- **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

### 3. Sécurité Renforcée

- **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

---

**🏗️ Architecture sdk_common - Fondation solide pour les Silent Payments** 🚀