4nk/sdk_common

Fork 0

Your Name b3a6c4fd34 chore(template): adapter .gitea depuis template et synchroniser docs pour sdk_common

2025-08-27 11:52:08 +02:00

11 KiB

Raw Blame History

📖 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

# 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

# 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

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

[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 :

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 :

npm install @4nk/sdk-common

Utilisation :

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 :

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

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

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

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

# 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

# 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

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

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

[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 :

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

# 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

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

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

# 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

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

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

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

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

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

# 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

# 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

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

// 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 - Configurer selon vos besoins
API Reference - Consulter les APIs détaillées
Architecture - Comprendre l'architecture

2. Développement

Guide de Développement - Contribuer au développement
Guide des Tests - Écrire et exécuter des tests
Quick Reference - Référence rapide

3. Intégration avec 4NK_node

Intégration 4NK_node - Intégrer avec l'infrastructure
Configuration SSH - Configurer SSH pour l'automatisation
Push SSH Automatisé - Automatiser les déploiements

📖 La bibliothèque sdk_common est maintenant prête à être utilisée dans vos projets ! 🚀

11 KiB Raw Blame History