470 lines
8.1 KiB
Markdown
470 lines
8.1 KiB
Markdown
# 📖 Guide d'Utilisation - sdk_client
|
|
|
|
Guide complet pour utiliser le SDK client pour les Silent Payments au quotidien.
|
|
|
|
## 🚀 Compilation et Build
|
|
|
|
### 1. Build de Développement
|
|
|
|
```bash
|
|
# Build de développement
|
|
cargo build
|
|
|
|
# Build avec optimisations
|
|
cargo build --release
|
|
|
|
# Vérifier le build
|
|
cargo check
|
|
```
|
|
|
|
### 2. Compilation WASM
|
|
|
|
```bash
|
|
# Compilation WASM pour le web
|
|
wasm-pack build --target web
|
|
|
|
# Compilation WASM pour Node.js
|
|
wasm-pack build --target nodejs
|
|
|
|
# Compilation WASM avec optimisations
|
|
wasm-pack build --target web --release
|
|
```
|
|
|
|
### 3. Vérification du Build
|
|
|
|
```bash
|
|
# Vérifier les fichiers générés
|
|
ls -la pkg/
|
|
|
|
# Vérifier la taille du WASM
|
|
ls -lh pkg/sdk_client_bg.wasm
|
|
|
|
# Vérifier les types TypeScript
|
|
cat pkg/sdk_client.d.ts
|
|
```
|
|
|
|
## 🔧 Intégration dans les Projets
|
|
|
|
### 1. Intégration JavaScript/TypeScript
|
|
|
|
```javascript
|
|
// Import du module WASM
|
|
import init, { generate_sp_wallet, lock_freezed_utxos } from './pkg/sdk_client.js';
|
|
|
|
// Initialisation
|
|
await init();
|
|
|
|
// Utilisation des fonctions
|
|
const wallet = generate_sp_wallet();
|
|
const success = lock_freezed_utxos(wallet, utxos);
|
|
```
|
|
|
|
### 2. Intégration Rust
|
|
|
|
```rust
|
|
use sdk_client::{generate_sp_wallet, lock_freezed_utxos};
|
|
|
|
// Utilisation directe
|
|
let wallet = generate_sp_wallet();
|
|
let success = lock_freezed_utxos(&wallet, &utxos);
|
|
```
|
|
|
|
### 3. Intégration Web
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<script type="module">
|
|
import init, { generate_sp_wallet } from './pkg/sdk_client.js';
|
|
|
|
async function main() {
|
|
await init();
|
|
const wallet = generate_sp_wallet();
|
|
console.log('Wallet généré:', wallet);
|
|
}
|
|
|
|
main();
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<h1>SDK Client Test</h1>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
## 💰 Utilisation des Silent Payments
|
|
|
|
### 1. Génération de Wallet
|
|
|
|
```rust
|
|
// Génération d'un nouveau wallet Silent Payment
|
|
let wallet = generate_sp_wallet();
|
|
|
|
// Propriétés du wallet
|
|
println!("Address: {}", wallet.address);
|
|
println!("Public Key: {}", wallet.public_key);
|
|
```
|
|
|
|
### 2. Verrouillage d'UTXOs
|
|
|
|
```rust
|
|
// Liste des UTXOs à verrouiller
|
|
let utxos = vec![
|
|
UTXO {
|
|
txid: "abc123...",
|
|
vout: 0,
|
|
amount: 100000,
|
|
script_pubkey: "script...",
|
|
}
|
|
];
|
|
|
|
// Verrouillage des UTXOs
|
|
let success = lock_freezed_utxos(&wallet, &utxos);
|
|
if success {
|
|
println!("UTXOs verrouillés avec succès");
|
|
}
|
|
```
|
|
|
|
### 3. Scan de Blocs
|
|
|
|
```rust
|
|
// Scan de blocs pour les Silent Payments
|
|
let blocks = vec![800000, 800001, 800002];
|
|
let results = scan_blocks(&wallet, &blocks);
|
|
|
|
for result in results {
|
|
println!("Transaction trouvée: {}", result.txid);
|
|
println!("Montant: {} sats", result.amount);
|
|
}
|
|
```
|
|
|
|
## 🧪 Tests et Validation
|
|
|
|
### 1. Tests Unitaires
|
|
|
|
```bash
|
|
# Exécuter tous les tests
|
|
cargo test
|
|
|
|
# Tests avec output détaillé
|
|
cargo test -- --nocapture
|
|
|
|
# Tests spécifiques
|
|
cargo test test_wallet_generation
|
|
```
|
|
|
|
### 2. Tests d'Intégration
|
|
|
|
```bash
|
|
# Tests d'intégration
|
|
cargo test --test integration
|
|
|
|
# Tests de performance
|
|
cargo test --test performance
|
|
```
|
|
|
|
### 3. Tests WASM
|
|
|
|
```bash
|
|
# Tests WASM avec Firefox
|
|
wasm-pack test --headless --firefox
|
|
|
|
# Tests WASM avec Chrome
|
|
wasm-pack test --headless --chrome
|
|
|
|
# Tests WASM avec Node.js
|
|
wasm-pack test --node
|
|
```
|
|
|
|
### 4. Tests de Linting
|
|
|
|
```bash
|
|
# Clippy (linter Rust)
|
|
cargo clippy -- -D warnings
|
|
|
|
# Formatage du code
|
|
cargo fmt -- --check
|
|
|
|
# Audit de sécurité
|
|
cargo audit
|
|
```
|
|
|
|
## 🔧 Configuration et Maintenance
|
|
|
|
### 1. Configuration des Features
|
|
|
|
```toml
|
|
# Cargo.toml
|
|
[dependencies]
|
|
sdk_client = { git = "https://git.4nkweb.com/4nk/sdk_client.git", features = ["wasm", "web"] }
|
|
```
|
|
|
|
### 2. Configuration de Build
|
|
|
|
```toml
|
|
# Cargo.toml
|
|
[profile.release]
|
|
opt-level = 3
|
|
lto = true
|
|
codegen-units = 1
|
|
panic = "abort"
|
|
|
|
[profile.dev]
|
|
opt-level = 0
|
|
debug = true
|
|
```
|
|
|
|
### 3. Configuration WASM
|
|
|
|
```bash
|
|
# Variables d'environnement pour WASM
|
|
export WASM_PACK_TARGET=web
|
|
export WASM_PACK_PROFILE=release
|
|
export CARGO_PROFILE_RELEASE_OPT_LEVEL=3
|
|
```
|
|
|
|
## 📊 Optimisations de Performance
|
|
|
|
### 1. Optimisations Rust
|
|
|
|
```rust
|
|
// Utilisation de types optimisés
|
|
use std::collections::HashMap;
|
|
|
|
// Pool de connexions
|
|
use tokio::sync::Semaphore;
|
|
|
|
// Cache en mémoire
|
|
use lru::LruCache;
|
|
```
|
|
|
|
### 2. Optimisations WASM
|
|
|
|
```bash
|
|
# Build optimisé
|
|
wasm-pack build --target web --release
|
|
|
|
# Optimisation de la taille
|
|
wasm-opt -O4 pkg/sdk_client_bg.wasm -o pkg/sdk_client_bg_opt.wasm
|
|
|
|
# Compression gzip
|
|
gzip -9 pkg/sdk_client_bg_opt.wasm
|
|
```
|
|
|
|
### 3. Optimisations JavaScript
|
|
|
|
```javascript
|
|
// Chargement lazy du WASM
|
|
const loadWASM = async () => {
|
|
if (!wasmModule) {
|
|
wasmModule = await import('./pkg/sdk_client.js');
|
|
await wasmModule.default();
|
|
}
|
|
return wasmModule;
|
|
};
|
|
|
|
// Cache des résultats
|
|
const cache = new Map();
|
|
const getCachedResult = (key, computeFn) => {
|
|
if (!cache.has(key)) {
|
|
cache.set(key, computeFn());
|
|
}
|
|
return cache.get(key);
|
|
};
|
|
```
|
|
|
|
## 🔒 Sécurité
|
|
|
|
### 1. Validation des Entrées
|
|
|
|
```rust
|
|
// Validation des adresses
|
|
pub fn validate_address(address: &str) -> Result<(), Error> {
|
|
if address.len() != 62 || !address.starts_with("sp1") {
|
|
return Err(Error::InvalidAddress);
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
// Validation des montants
|
|
pub fn validate_amount(amount: u64) -> Result<(), Error> {
|
|
if amount == 0 || amount > MAX_AMOUNT {
|
|
return Err(Error::InvalidAmount);
|
|
}
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### 2. Gestion de la Mémoire
|
|
|
|
```rust
|
|
// Nettoyage sécurisé
|
|
impl Drop for Wallet {
|
|
fn drop(&mut self) {
|
|
// Nettoyer les données sensibles
|
|
self.private_key.zeroize();
|
|
}
|
|
}
|
|
|
|
// Utilisation de types sécurisés
|
|
use zeroize::Zeroize;
|
|
```
|
|
|
|
### 3. Protection contre les Attaques
|
|
|
|
```rust
|
|
// Protection contre les attaques par timing
|
|
use subtle::ConstantTimeEq;
|
|
|
|
// Protection contre les attaques par débordement
|
|
use checked_add::CheckedAdd;
|
|
```
|
|
|
|
## 🚨 Dépannage
|
|
|
|
### 1. Problèmes de Compilation
|
|
|
|
```bash
|
|
# Nettoyer et recompiler
|
|
cargo clean
|
|
cargo build
|
|
|
|
# Vérifier les dépendances
|
|
cargo update
|
|
cargo check
|
|
|
|
# Vérifier les features
|
|
cargo build --features wasm
|
|
```
|
|
|
|
### 2. Problèmes WASM
|
|
|
|
```bash
|
|
# Nettoyer WASM
|
|
rm -rf pkg/
|
|
wasm-pack build --target web
|
|
|
|
# Vérifier la compatibilité
|
|
wasm-pack test --headless --firefox
|
|
|
|
# Debug WASM
|
|
RUST_LOG=debug wasm-pack build --target web
|
|
```
|
|
|
|
### 3. Problèmes de Performance
|
|
|
|
```bash
|
|
# Profiling Rust
|
|
cargo build --release
|
|
perf record ./target/release/sdk_client
|
|
perf report
|
|
|
|
# Profiling WASM
|
|
wasm-pack build --target web --profiling
|
|
```
|
|
|
|
### 4. Logs et Debugging
|
|
|
|
```bash
|
|
# Logs détaillés
|
|
RUST_LOG=debug cargo test
|
|
|
|
# Logs spécifiques
|
|
RUST_LOG=sdk_client::wallet=debug cargo test
|
|
|
|
# Backtrace
|
|
RUST_BACKTRACE=1 cargo test
|
|
```
|
|
|
|
## 📈 Monitoring
|
|
|
|
### 1. Métriques de Performance
|
|
|
|
```rust
|
|
// Métriques de compilation
|
|
use std::time::Instant;
|
|
|
|
let start = Instant::now();
|
|
let wallet = generate_sp_wallet();
|
|
let duration = start.elapsed();
|
|
println!("Génération wallet: {:?}", duration);
|
|
```
|
|
|
|
### 2. Métriques d'Utilisation
|
|
|
|
```rust
|
|
// Compteurs d'utilisation
|
|
static mut WALLET_COUNT: AtomicU64 = AtomicU64::new(0);
|
|
|
|
unsafe {
|
|
WALLET_COUNT.fetch_add(1, Ordering::Relaxed);
|
|
}
|
|
```
|
|
|
|
### 3. Monitoring en Production
|
|
|
|
```javascript
|
|
// Métriques JavaScript
|
|
const metrics = {
|
|
walletGenerationTime: 0,
|
|
utxoLockTime: 0,
|
|
scanTime: 0,
|
|
errorCount: 0
|
|
};
|
|
|
|
// Envoi des métriques
|
|
fetch('/metrics', {
|
|
method: 'POST',
|
|
body: JSON.stringify(metrics)
|
|
});
|
|
```
|
|
|
|
## 🔄 Mise à Jour
|
|
|
|
### 1. Mise à Jour des Dépendances
|
|
|
|
```bash
|
|
# Mettre à jour les dépendances
|
|
cargo update
|
|
|
|
# Vérifier les vulnérabilités
|
|
cargo audit
|
|
|
|
# Mettre à jour wasm-pack
|
|
cargo install wasm-pack --force
|
|
```
|
|
|
|
### 2. Mise à Jour du Code
|
|
|
|
```bash
|
|
# Pull des dernières modifications
|
|
git pull origin main
|
|
|
|
# Recompiler
|
|
cargo build --release
|
|
wasm-pack build --target web --release
|
|
|
|
# Tester
|
|
cargo test --all
|
|
```
|
|
|
|
### 3. Migration des Données
|
|
|
|
```rust
|
|
// Migration des wallets
|
|
pub fn migrate_wallet_v1_to_v2(wallet_v1: WalletV1) -> WalletV2 {
|
|
WalletV2 {
|
|
address: wallet_v1.address,
|
|
public_key: wallet_v1.public_key,
|
|
// Nouveaux champs
|
|
version: 2,
|
|
created_at: SystemTime::now(),
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
**🎯 SDK client - Prêt pour une utilisation en production !** ✨
|