575 lines
16 KiB
Markdown
575 lines
16 KiB
Markdown
## 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** 🚀
|
|
|
|
|