16 KiB
16 KiB
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 :
// 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 :
// 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 :
// 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
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
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
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
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
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
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
// 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
#[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
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
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
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
// 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
// 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
// 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 🚀