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

# 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

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

# 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

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

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

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

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

# 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

# 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

# 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

# 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

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

// Compteurs d'utilisation
static mut WALLET_COUNT: AtomicU64 = AtomicU64::new(0);

unsafe {
    WALLET_COUNT.fetch_add(1, Ordering::Relaxed);
}

3. Monitoring en Production

// 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.