sdk_client/docs/USAGE.md

## Guide d’utilisation — sdk_client

Ce guide décrit les parcours d’utilisation sans inclure d’exemples exécutables. Les appels concrets et signatures sont référencés dans `docs/API.md`.

## 🚀 Compilation et build

### 1. Build de Développement

Étapes usuelles côté Rust: build de développement, build optimisé, vérification statique. Voir `Cargo.toml` et `CHANGELOG.md` pour les évolutions de dépendances.

### 2. Compilation WASM

Le module cible l’environnement WebAssembly. La compilation produit un artefact WASM et des bindings JS/TS selon l’outillage choisi.

### 3. Vérification du build

La vérification consiste à confirmer la génération des artefacts et la cohérence des types.

## 🔧 Intégration dans les projets

L’intégration cible JS/TS via WASM. Le chargement et l’initialisation dépendent de l’outillage de bundling. Les fonctions exportées et leurs contrats sont décrits dans `docs/API.md`.

## 💰 Utilisation fonctionnelle

- Gestion d’appareil: création/restauration, appairage/désappairage, export neuter.
- Fonds: récupération d’adresse, consultation du solde disponible, création et signature de transactions.
- Processus: création/évolution d’états, génération de diffs, validations et commits associés.
- Événements réseau: traitement de transactions entrantes et messages chiffrés, production des artefacts à persister ou relayer.

## 🧪 Tests et validation

- Tests Rust: unité et intégration selon la pyramide décrite dans `docs/TESTING.md`.
- Linting/format: outillage Rust standard, avertissements promus en erreurs.
- WASM: tests ciblés en environnement headless selon l’outillage retenu.

## 🔧 Configuration et maintenance

### 1. Configuration des Features

La configuration de build et les variantes de profils sont décrites dans `docs/CONFIGURATION.md`.

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

Paramètres d’export, profil et cibles à adapter selon la chaîne de build; se référer à `docs/CONFIGURATION.md`.

## 📊 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

Les mises à jour de dépendances et impacts sont retracés dans `CHANGELOG.md` et `docs/ARCHITECTURE.md`.

### 2. Mise à jour du code

Les changements de contrats sont systématiquement répercutés dans `docs/API.md`.

### 3. Migration des données

Les migrations de structures sont documentées dans `docs/MIGRATION.md` si applicables.

---

**Références complémentaires: `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`.**