547 lines
11 KiB
Markdown
547 lines
11 KiB
Markdown
# 📖 Guide d'Utilisation - sdk_common
|
|
|
|
Guide complet pour utiliser la bibliothèque commune sdk_common pour les Silent Payments.
|
|
|
|
## 🚀 Compilation et Build
|
|
|
|
### 1. Build de Développement
|
|
|
|
```bash
|
|
# Build de base
|
|
cargo build
|
|
|
|
# Build avec toutes les features
|
|
cargo build --all-features
|
|
|
|
# Build avec une feature spécifique
|
|
cargo build --features wasm
|
|
cargo build --features blindbit-wasm
|
|
```
|
|
|
|
### 2. Build de Production
|
|
|
|
```bash
|
|
# Build optimisé
|
|
cargo build --release
|
|
|
|
# Build avec optimisations avancées
|
|
RUSTFLAGS="-C target-cpu=native" cargo build --release
|
|
|
|
# Build avec LTO
|
|
RUSTFLAGS="-C lto=fat" cargo build --release
|
|
```
|
|
|
|
### 3. Build WASM
|
|
|
|
```bash
|
|
# Build WASM pour le web
|
|
wasm-pack build --target web
|
|
|
|
# Build WASM pour Node.js
|
|
wasm-pack build --target nodejs
|
|
|
|
# Build WASM avec optimisations
|
|
wasm-pack build --target web --release
|
|
```
|
|
|
|
## 🔧 Intégration dans les Projets
|
|
|
|
### 1. Intégration Rust
|
|
|
|
**Dans `Cargo.toml` :**
|
|
|
|
```toml
|
|
[dependencies]
|
|
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", branch = "main" }
|
|
|
|
# Avec features spécifiques
|
|
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["wasm"] }
|
|
```
|
|
|
|
**Utilisation dans le code :**
|
|
|
|
```rust
|
|
use sdk_common::{
|
|
types::{Wallet, Transaction, SilentPayment},
|
|
traits::WalletOperations,
|
|
error::SdkError
|
|
};
|
|
|
|
fn main() -> Result<(), SdkError> {
|
|
// Créer un wallet
|
|
let wallet = Wallet::new()?;
|
|
|
|
// Générer un paiement silencieux
|
|
let payment = SilentPayment::generate(&wallet)?;
|
|
|
|
// Traiter une transaction
|
|
let tx = Transaction::from_hex("...")?;
|
|
let result = wallet.process_transaction(&tx)?;
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### 2. Intégration JavaScript/TypeScript
|
|
|
|
**Installation :**
|
|
|
|
```bash
|
|
npm install @4nk/sdk-common
|
|
```
|
|
|
|
**Utilisation :**
|
|
|
|
```javascript
|
|
import { init, Wallet, SilentPayment } from '@4nk/sdk-common';
|
|
|
|
async function main() {
|
|
// Initialiser le module WASM
|
|
await init();
|
|
|
|
// Créer un wallet
|
|
const wallet = new Wallet();
|
|
|
|
// Générer un paiement silencieux
|
|
const payment = SilentPayment.generate(wallet);
|
|
|
|
console.log('Payment:', payment);
|
|
}
|
|
|
|
main().catch(console.error);
|
|
```
|
|
|
|
### 3. Intégration Web
|
|
|
|
**HTML :**
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>SDK Common Demo</title>
|
|
</head>
|
|
<body>
|
|
<script type="module">
|
|
import init, { Wallet, SilentPayment } from './pkg/sdk_common.js';
|
|
|
|
async function main() {
|
|
await init();
|
|
|
|
const wallet = new Wallet();
|
|
const payment = SilentPayment.generate(wallet);
|
|
|
|
document.getElementById('result').textContent =
|
|
JSON.stringify(payment, null, 2);
|
|
}
|
|
|
|
main();
|
|
</script>
|
|
|
|
<h1>SDK Common Demo</h1>
|
|
<pre id="result"></pre>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
## 📚 Utilisation des Types et Structures
|
|
|
|
### 1. Types de Base
|
|
|
|
```rust
|
|
use sdk_common::types::*;
|
|
|
|
// Wallet
|
|
let wallet = Wallet::new()?;
|
|
let public_key = wallet.public_key();
|
|
let private_key = wallet.private_key();
|
|
|
|
// Silent Payment
|
|
let payment = SilentPayment::new(&wallet)?;
|
|
let address = payment.address();
|
|
let scan_key = payment.scan_key();
|
|
|
|
// Transaction
|
|
let tx = Transaction::from_hex("...")?;
|
|
let txid = tx.txid();
|
|
let outputs = tx.outputs();
|
|
```
|
|
|
|
### 2. Traits et Interfaces
|
|
|
|
```rust
|
|
use sdk_common::traits::*;
|
|
|
|
// Implémentation de WalletOperations
|
|
impl WalletOperations for MyWallet {
|
|
fn generate_address(&self) -> Result<Address, SdkError> {
|
|
// Implémentation personnalisée
|
|
}
|
|
|
|
fn sign_transaction(&self, tx: &Transaction) -> Result<Signature, SdkError> {
|
|
// Implémentation personnalisée
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Gestion des Erreurs
|
|
|
|
```rust
|
|
use sdk_common::error::SdkError;
|
|
|
|
fn process_payment(payment_data: &str) -> Result<(), SdkError> {
|
|
match SilentPayment::from_json(payment_data) {
|
|
Ok(payment) => {
|
|
// Traitement réussi
|
|
Ok(())
|
|
}
|
|
Err(SdkError::InvalidFormat) => {
|
|
eprintln!("Format de paiement invalide");
|
|
Err(SdkError::InvalidFormat)
|
|
}
|
|
Err(SdkError::NetworkError) => {
|
|
eprintln!("Erreur réseau");
|
|
Err(SdkError::NetworkError)
|
|
}
|
|
Err(e) => {
|
|
eprintln!("Erreur inattendue: {:?}", e);
|
|
Err(e)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🧪 Tests et Validation
|
|
|
|
### 1. Tests Unitaires
|
|
|
|
```bash
|
|
# Tests de base
|
|
cargo test
|
|
|
|
# Tests avec output détaillé
|
|
cargo test -- --nocapture
|
|
|
|
# Tests d'une fonction spécifique
|
|
cargo test test_wallet_creation
|
|
|
|
# Tests avec couverture
|
|
cargo tarpaulin --out Html
|
|
```
|
|
|
|
### 2. Tests d'Intégration
|
|
|
|
```bash
|
|
# Tests d'intégration
|
|
cargo test --test integration
|
|
|
|
# Tests de performance
|
|
cargo test --test performance
|
|
|
|
# Tests de sécurité
|
|
cargo test --test security
|
|
```
|
|
|
|
### 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 Compatibilité
|
|
|
|
```bash
|
|
# Tests de compatibilité avec sdk_client
|
|
cargo test --features sdk-client
|
|
|
|
# Tests de compatibilité avec sdk_relay
|
|
cargo test --features sdk-relay
|
|
|
|
# Tests de compatibilité WASM
|
|
cargo test --features wasm
|
|
```
|
|
|
|
## ⚙️ Configuration et Maintenance
|
|
|
|
### 1. Configuration des Features
|
|
|
|
**Activation des features :**
|
|
|
|
```toml
|
|
[dependencies]
|
|
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["wasm", "blindbit-wasm"] }
|
|
```
|
|
|
|
**Features disponibles :**
|
|
|
|
- `std` : Support standard (par défaut)
|
|
- `wasm` : Support WebAssembly
|
|
- `blindbit-wasm` : Support Blindbit en WASM
|
|
- `sdk-client` : Compatibilité avec sdk_client
|
|
- `sdk-relay` : Compatibilité avec sdk_relay
|
|
|
|
### 2. Configuration de Build
|
|
|
|
**Optimisations de performance :**
|
|
|
|
```bash
|
|
# Compilation optimisée
|
|
RUSTFLAGS="-C target-cpu=native -C lto=fat" cargo build --release
|
|
|
|
# Compilation avec sanitizers
|
|
RUSTFLAGS="-Z sanitizer=address" cargo test
|
|
|
|
# Compilation avec vérifications
|
|
RUSTFLAGS="-C overflow-checks=on" cargo build
|
|
```
|
|
|
|
### 3. Configuration des Tests
|
|
|
|
**Variables d'environnement pour les tests :**
|
|
|
|
```bash
|
|
# Timeout des tests
|
|
export TEST_TIMEOUT=300
|
|
|
|
# Tests parallèles
|
|
export TEST_PARALLEL=true
|
|
|
|
# Logs détaillés
|
|
export RUST_LOG=debug
|
|
|
|
# Backtrace
|
|
export RUST_BACKTRACE=1
|
|
```
|
|
|
|
## 🚀 Optimisations de Performance
|
|
|
|
### 1. Optimisations Rust
|
|
|
|
```rust
|
|
// Utilisation de references pour éviter les copies
|
|
fn process_wallet(wallet: &Wallet) -> Result<(), SdkError> {
|
|
// Traitement optimisé
|
|
}
|
|
|
|
// Utilisation de iterators pour les performances
|
|
fn process_transactions(txs: &[Transaction]) -> Vec<Result<(), SdkError>> {
|
|
txs.iter().map(|tx| process_transaction(tx)).collect()
|
|
}
|
|
|
|
// Utilisation de Box pour les gros objets
|
|
fn create_large_wallet() -> Box<Wallet> {
|
|
Box::new(Wallet::new().unwrap())
|
|
}
|
|
```
|
|
|
|
### 2. Optimisations WASM
|
|
|
|
```javascript
|
|
// Initialisation asynchrone
|
|
const sdk = await init();
|
|
|
|
// Utilisation de Web Workers pour les calculs lourds
|
|
const worker = new Worker('sdk-worker.js');
|
|
worker.postMessage({ type: 'process_payment', data: paymentData });
|
|
|
|
// Utilisation de SharedArrayBuffer pour les gros datasets
|
|
const sharedBuffer = new SharedArrayBuffer(1024 * 1024);
|
|
```
|
|
|
|
### 3. Optimisations de Build
|
|
|
|
```bash
|
|
# Build avec optimisations avancées
|
|
RUSTFLAGS="-C target-cpu=native -C lto=fat -C codegen-units=1" cargo build --release
|
|
|
|
# Build WASM optimisé
|
|
wasm-pack build --target web --release -- --no-default-features
|
|
|
|
# Minification WASM
|
|
wasm-opt -O4 -o pkg/sdk_common_bg.wasm pkg/sdk_common_bg.wasm
|
|
```
|
|
|
|
## 🔒 Sécurité
|
|
|
|
### 1. Validation des Entrées
|
|
|
|
```rust
|
|
use sdk_common::validation::*;
|
|
|
|
// Validation des adresses
|
|
fn validate_address(address: &str) -> Result<(), SdkError> {
|
|
if !is_valid_bitcoin_address(address) {
|
|
return Err(SdkError::InvalidAddress);
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
// Validation des transactions
|
|
fn validate_transaction(tx_hex: &str) -> Result<(), SdkError> {
|
|
if !is_valid_transaction_hex(tx_hex) {
|
|
return Err(SdkError::InvalidTransaction);
|
|
}
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### 2. Gestion de la Mémoire
|
|
|
|
```rust
|
|
// Utilisation de zeroize pour les données sensibles
|
|
use zeroize::Zeroize;
|
|
|
|
struct SecureWallet {
|
|
private_key: Vec<u8>,
|
|
}
|
|
|
|
impl Drop for SecureWallet {
|
|
fn drop(&mut self) {
|
|
self.private_key.zeroize();
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Protection contre les Attaques
|
|
|
|
```rust
|
|
// Protection contre les attaques par timing
|
|
use subtle::ConstantTimeEq;
|
|
|
|
fn verify_signature(sig1: &[u8], sig2: &[u8]) -> bool {
|
|
sig1.ct_eq(sig2).unwrap_u8() == 1
|
|
}
|
|
|
|
// Protection contre les attaques par déni de service
|
|
fn process_with_timeout<F, T>(f: F, timeout: Duration) -> Result<T, SdkError>
|
|
where
|
|
F: FnOnce() -> Result<T, SdkError>,
|
|
{
|
|
// Implémentation avec timeout
|
|
}
|
|
```
|
|
|
|
## 📊 Monitoring
|
|
|
|
### 1. Métriques de Performance
|
|
|
|
```rust
|
|
use std::time::Instant;
|
|
|
|
fn benchmark_operation() {
|
|
let start = Instant::now();
|
|
|
|
// Opération à mesurer
|
|
let result = perform_operation();
|
|
|
|
let duration = start.elapsed();
|
|
println!("Opération terminée en {:?}", duration);
|
|
}
|
|
```
|
|
|
|
### 2. Logs et Debug
|
|
|
|
```rust
|
|
use log::{info, warn, error, debug};
|
|
|
|
fn process_payment(payment: &SilentPayment) -> Result<(), SdkError> {
|
|
debug!("Traitement du paiement: {:?}", payment);
|
|
|
|
match payment.process() {
|
|
Ok(_) => {
|
|
info!("Paiement traité avec succès");
|
|
Ok(())
|
|
}
|
|
Err(e) => {
|
|
error!("Erreur lors du traitement: {:?}", e);
|
|
Err(e)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Métriques de Build
|
|
|
|
```bash
|
|
# Taille du binaire
|
|
ls -lh target/release/libsdk_common.*
|
|
|
|
# Taille WASM
|
|
ls -lh pkg/sdk_common_bg.wasm
|
|
|
|
# Temps de compilation
|
|
time cargo build --release
|
|
|
|
# Analyse des dépendances
|
|
cargo tree
|
|
```
|
|
|
|
## 🔄 Mises à Jour
|
|
|
|
### 1. Mise à Jour de la Bibliothèque
|
|
|
|
```bash
|
|
# Mettre à jour les dépendances
|
|
cargo update
|
|
|
|
# Vérifier les vulnérabilités
|
|
cargo audit
|
|
|
|
# Tester après mise à jour
|
|
cargo test --all
|
|
```
|
|
|
|
### 2. Migration des Versions
|
|
|
|
```rust
|
|
// Gestion des breaking changes
|
|
#[cfg(feature = "v2")]
|
|
use sdk_common::v2::{Wallet, SilentPayment};
|
|
|
|
#[cfg(not(feature = "v2"))]
|
|
use sdk_common::v1::{Wallet, SilentPayment};
|
|
```
|
|
|
|
### 3. Migration des Données
|
|
|
|
```rust
|
|
// Migration des wallets
|
|
fn migrate_wallet_v1_to_v2(wallet_v1: V1Wallet) -> Result<V2Wallet, SdkError> {
|
|
// Logique de migration
|
|
let wallet_v2 = V2Wallet::from_v1(wallet_v1)?;
|
|
Ok(wallet_v2)
|
|
}
|
|
```
|
|
|
|
## 🎯 Prochaines Étapes
|
|
|
|
### 1. Intégration
|
|
|
|
- [Guide de Configuration](CONFIGURATION.md) - Configurer selon vos besoins
|
|
- [API Reference](API.md) - Consulter les APIs détaillées
|
|
- [Architecture](ARCHITECTURE.md) - Comprendre l'architecture
|
|
|
|
### 2. Développement
|
|
|
|
- [Guide de Développement](DEVELOPMENT.md) - Contribuer au développement
|
|
- [Guide des Tests](TESTING.md) - Écrire et exécuter des tests
|
|
- [Quick Reference](QUICK_REFERENCE.md) - Référence rapide
|
|
|
|
### 3. Intégration avec 4NK_node
|
|
|
|
- [Intégration 4NK_node](INTEGRATION_4NK_NODE.md) - Intégrer avec l'infrastructure
|
|
- [Configuration SSH](SSH_SETUP.md) - Configurer SSH pour l'automatisation
|
|
- [Push SSH Automatisé](AUTO_SSH_PUSH.md) - Automatiser les déploiements
|
|
|
|
---
|
|
|
|
**📖 La bibliothèque sdk_common est maintenant prête à être utilisée dans vos projets !** 🚀
|
|
|