From 3e3716411baf4431501c54992dfdc2830cd6604e Mon Sep 17 00:00:00 2001 From: Debian Date: Fri, 29 Aug 2025 15:54:43 +0000 Subject: [PATCH] docs: Correction de la documentation sdk_common MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Correction de l'API.md : Suppression des APIs Bitcoin Core, ajout des vraies APIs sdk_common - Correction du USAGE.md : Suppression des références WASM/npm inexistantes - Mise à jour de l'INDEX.md : Suppression des liens vers fichiers inexistants --- docs/API.md | 971 +++++++++++++++----------------------------------- docs/INDEX.md | 59 +-- docs/USAGE.md | 688 +++++++++++++++-------------------- 3 files changed, 570 insertions(+), 1148 deletions(-) diff --git a/docs/API.md b/docs/API.md index a814fbe..c775022 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,765 +1,352 @@ # Référence API - sdk_common -Ce guide documente toutes les APIs disponibles dans l'infrastructure sdk_common, incluant les interfaces RPC, HTTP et WebSocket. +Ce guide documente toutes les APIs disponibles dans la bibliothèque commune sdk_common pour les Silent Payments. -## Vue d'Ensemble des APIs +## Vue d'Ensemble -L'infrastructure sdk_common expose plusieurs interfaces pour différents types d'interactions : +La bibliothèque sdk_common fournit des types, structures et utilitaires partagés entre les modules SDK de l'écosystème 4NK. -- **Bitcoin Core RPC** : Interface JSON-RPC pour Bitcoin -- **Blindbit HTTP** : API REST pour les paiements silencieux -- **SDK Relay WebSocket** : Interface temps réel pour les clients -- **SDK Relay HTTP** : API REST pour les opérations de gestion +## 1. Types de Base -## 1. API Bitcoin Core RPC +### Structures Principales -### Informations Générales - -- **Protocole :** JSON-RPC -- **Port :** 18443 -- **Authentification :** Cookie ou credentials -- **Réseau :** Signet -- **Base URL :** `http://localhost:18443` - -### Authentification - -#### Méthode Cookie (Recommandée) -```bash -# Le cookie est automatiquement utilisé par Bitcoin Core -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - --data '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}' -``` - -#### Méthode Credentials -```bash -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - -u "username:password" \ - --data '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}' -``` - -### Endpoints Principaux - -#### getblockchaininfo -Récupère les informations sur la blockchain. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblockchaininfo", - "params": [] +#### Process +```rust +pub struct Process { + pub id: String, + pub name: String, + pub description: Option, + pub device_id: String, + pub state: ProcessState, + pub states: Vec, + pub created_at: Option, + pub updated_at: Option, } ``` -**Réponse :** -```json -{ - "result": { - "chain": "signet", - "blocks": 12345, - "headers": 12345, - "bestblockhash": "0000000000000000000000000000000000000000000000000000000000000000", - "difficulty": 1.0, - "mediantime": 1234567890, - "verificationprogress": 1.0, - "initialblockdownload": false, - "chainwork": "0000000000000000000000000000000000000000000000000000000000000000", - "size_on_disk": 123456789, - "pruned": false, - "pruneheight": null, - "automatic_pruning": false, - "prune_target_size": null, - "warnings": "" - }, - "error": null, - "id": "test" +#### ProcessState +```rust +pub enum ProcessState { + Active, + Inactive, + Pending, + Completed, + Failed, } ``` -#### getblock -Récupère les informations d'un bloc spécifique. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblock", - "params": ["blockhash", 2] +#### Member +```rust +pub struct Member { + pub id: String, + pub name: String, + pub public_key: String, + pub process_id: String, + pub roles: Vec, + pub sp_addresses: Option>, + pub created_at: Option, + pub updated_at: Option, } ``` +#### ValidationRule +```rust +pub struct ValidationRule { + pub id: String, + pub field_name: String, + pub rule_type: ValidationRuleType, + pub parameters: Option, + pub role_id: String, + pub quorum: Option, + pub created_at: Option, + pub updated_at: Option, +} +``` + +#### ValidationRuleType +```rust +pub enum ValidationRuleType { + Range, + Required, + Format, + Custom, +} +``` + +## 2. Fonctions Utilitaires + +### Compression et Sérialisation + +#### compress_data +```rust +pub fn compress_data(data: &[u8]) -> Result, CompressionError> +``` +Compresse des données en utilisant l'algorithme DEFLATE (flate2). + **Paramètres :** -- `blockhash` : Hash du bloc -- `verbosity` : Niveau de détail (0, 1, 2) +- `data` : Données à compresser -#### getrawtransaction -Récupère une transaction brute. +**Retour :** +- `Result, CompressionError>` : Données compressées ou erreur -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getrawtransaction", - "params": ["txid", true] +**Exemple :** +```rust +use sdk_common::compress_data; + +let data = b"données à compresser"; +let compressed = compress_data(data)?; +``` + +#### decompress_data +```rust +pub fn decompress_data(data: &[u8]) -> Result, CompressionError> +``` +Décompresse des données au format DEFLATE. + +**Paramètres :** +- `data` : Données compressées + +**Retour :** +- `Result, CompressionError>` : Données décompressées ou erreur + +**Exemple :** +```rust +use sdk_common::decompress_data; + +let decompressed = decompress_data(&compressed_data)?; +``` + +### Validation + +#### validate_process +```rust +pub fn validate_process(process: &Process) -> Result<(), ValidationError> +``` +Valide la structure d'un processus. + +**Paramètres :** +- `process` : Processus à valider + +**Retour :** +- `Result<(), ValidationError>` : Succès ou erreur de validation + +#### validate_member +```rust +pub fn validate_member(member: &Member) -> Result<(), ValidationError> +``` +Valide la structure d'un membre. + +**Paramètres :** +- `member` : Membre à valider + +**Retour :** +- `Result<(), ValidationError>` : Succès ou erreur de validation + +### Sérialisation + +#### serialize_process +```rust +pub fn serialize_process(process: &Process) -> Result +``` +Sérialise un processus en JSON. + +**Paramètres :** +- `process` : Processus à sérialiser + +**Retour :** +- `Result` : JSON sérialisé ou erreur + +#### deserialize_process +```rust +pub fn deserialize_process(json: &str) -> Result +``` +Désérialise un processus depuis JSON. + +**Paramètres :** +- `json` : JSON à désérialiser + +**Retour :** +- `Result` : Processus désérialisé ou erreur + +## 3. Traits et Interfaces + +### ProcessOperations +```rust +pub trait ProcessOperations { + fn create_process(&self, name: &str, device_id: &str) -> Result; + fn update_process(&self, process: &Process) -> Result; + fn get_process(&self, id: &str) -> Result, SdkError>; + fn list_processes(&self) -> Result, SdkError>; } ``` -#### sendrawtransaction -Envoie une transaction brute au réseau. - -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "sendrawtransaction", - "params": ["hexstring"] +### MemberOperations +```rust +pub trait MemberOperations { + fn add_member(&self, member: &Member) -> Result; + fn update_member(&self, member: &Member) -> Result; + fn get_member(&self, id: &str) -> Result, SdkError>; + fn list_members(&self, process_id: &str) -> Result, SdkError>; } ``` -#### getwalletinfo -Récupère les informations du wallet. +## 4. Gestion des Erreurs -**Requête :** -```json -{ - "jsonrpc": "1.0", - "id": "test", - "method": "getwalletinfo", - "params": [] +### Types d'Erreurs + +#### SdkError +```rust +pub enum SdkError { + Validation(ValidationError), + Serialization(SerializationError), + Compression(CompressionError), + NotFound(String), + InvalidInput(String), + Internal(String), } ``` -### Gestion des Erreurs - -**Erreur typique :** -```json -{ - "result": null, - "error": { - "code": -32601, - "message": "Method not found" - }, - "id": "test" +#### ValidationError +```rust +pub enum ValidationError { + InvalidProcess(String), + InvalidMember(String), + InvalidRule(String), + MissingField(String), + InvalidValue(String), } ``` -**Codes d'erreur courants :** -- `-32601` : Méthode non trouvée -- `-32602` : Paramètres invalides -- `-32603` : Erreur interne -- `-1` : Erreur d'authentification - -## 2. API Blindbit HTTP - -### Informations Générales - -- **Protocole :** HTTP REST -- **Port :** 8000 -- **Base URL :** `http://localhost:8000` -- **Content-Type :** `application/json` - -### Endpoints - -#### GET /health -Vérifie la santé du service. - -**Requête :** -```bash -curl -X GET http://localhost:8000/health -``` - -**Réponse :** -```json -{ - "status": "healthy", - "timestamp": "2024-12-19T14:30:00Z", - "version": "1.0.0" +#### SerializationError +```rust +pub enum SerializationError { + InvalidJson(String), + MissingField(String), + InvalidType(String), } ``` -#### POST /generate-address -Génère une adresse de paiement silencieux. - -**Requête :** -```json -{ - "label": "payment_001", - "amount": 0.001 +#### CompressionError +```rust +pub enum CompressionError { + CompressionFailed(String), + DecompressionFailed(String), + InvalidData(String), } ``` -**Réponse :** -```json -{ - "address": "bc1p...", - "label": "payment_001", - "amount": 0.001, - "created_at": "2024-12-19T14:30:00Z" -} -``` +## 5. Exemples d'Utilisation -#### GET /payments -Liste les paiements reçus. +### Création d'un Processus +```rust +use sdk_common::{Process, ProcessState, validate_process}; -**Requête :** -```bash -curl -X GET "http://localhost:8000/payments?limit=10&offset=0" -``` - -**Paramètres de requête :** -- `limit` : Nombre maximum de résultats (défaut: 10) -- `offset` : Décalage pour la pagination (défaut: 0) - -**Réponse :** -```json -{ - "payments": [ - { - "id": "payment_001", - "address": "bc1p...", - "amount": 0.001, - "txid": "txid...", - "block_height": 12345, - "created_at": "2024-12-19T14:30:00Z" - } - ], - "total": 1, - "limit": 10, - "offset": 0 -} -``` - -#### GET /payments/{id} -Récupère les détails d'un paiement spécifique. - -**Requête :** -```bash -curl -X GET http://localhost:8000/payments/payment_001 -``` - -**Réponse :** -```json -{ - "id": "payment_001", - "address": "bc1p...", - "amount": 0.001, - "txid": "txid...", - "block_height": 12345, - "confirmations": 6, - "created_at": "2024-12-19T14:30:00Z", - "status": "confirmed" -} -``` - -### Codes de Statut HTTP - -- `200` : Succès -- `201` : Créé -- `400` : Requête invalide -- `404` : Ressource non trouvée -- `500` : Erreur serveur - -## 3. API SDK Relay WebSocket - -### Informations Générales - -- **Protocole :** WebSocket/WSS -- **Port :** 8090 -- **URL :** `ws://localhost:8090` ou `wss://localhost:8090` -- **Format :** JSON - -### Connexion - -```javascript -const ws = new WebSocket('ws://localhost:8090'); - -ws.onopen = function() { - console.log('Connexion WebSocket établie'); +let process = Process { + id: "process_123".to_string(), + name: "Mon Processus".to_string(), + description: Some("Description du processus".to_string()), + device_id: "device_456".to_string(), + state: ProcessState::Active, + states: vec![ProcessState::Active], + created_at: None, + updated_at: None, }; -ws.onmessage = function(event) { - const message = JSON.parse(event.data); - console.log('Message reçu:', message); -}; - -ws.onerror = function(error) { - console.error('Erreur WebSocket:', error); -}; - -ws.onclose = function() { - console.log('Connexion WebSocket fermée'); -}; +// Valider le processus +validate_process(&process)?; ``` -### Format des Messages +### Compression de Données +```rust +use sdk_common::{compress_data, decompress_data}; -Tous les messages suivent le format JSON suivant : +// Compresser des données +let original_data = b"données importantes à compresser"; +let compressed = compress_data(original_data)?; -```json -{ - "type": "message_type", - "id": "unique_message_id", - "timestamp": 1234567890, - "data": { - // Données spécifiques au type de message - } -} +// Décompresser les données +let decompressed = decompress_data(&compressed)?; +assert_eq!(original_data, decompressed.as_slice()); ``` -### Types de Messages +### Sérialisation JSON +```rust +use sdk_common::{serialize_process, deserialize_process}; -#### Messages de Synchronisation +let process = Process { /* ... */ }; -**StateSync :** -```json -{ - "type": "StateSync", - "id": "state_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "state": "running", - "version": "1.0.0", - "uptime": 3600 - } -} +// Sérialiser en JSON +let json = serialize_process(&process)?; + +// Désérialiser depuis JSON +let deserialized_process = deserialize_process(&json)?; ``` -**HealthSync :** -```json -{ - "type": "HealthSync", - "id": "health_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "status": "healthy", - "uptime": 3600, - "cpu_usage": 15.5, - "memory_usage": 45.2 - } -} +## 6. Configuration + +### Features Disponibles + +```toml +[dependencies] +sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["flate2"] } ``` -**MetricsSync :** -```json -{ - "type": "MetricsSync", - "id": "metrics_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "messages_sent": 1000, - "messages_received": 950, - "sync_errors": 5, - "connected_relays": 3 - } -} -``` - -#### Messages de Transaction - -**TransactionReceived :** -```json -{ - "type": "TransactionReceived", - "id": "tx_001", - "timestamp": 1234567890, - "data": { - "txid": "txid...", - "amount": 0.001, - "address": "bc1p...", - "block_height": 12345, - "confirmations": 1 - } -} -``` - -**BlockScanned :** -```json -{ - "type": "BlockScanned", - "id": "block_001", - "timestamp": 1234567890, - "data": { - "block_height": 12345, - "block_hash": "hash...", - "transactions_count": 150, - "silent_payments_found": 2 - } -} -``` - -### Commandes Client - -#### Ping -```json -{ - "type": "ping", - "id": "ping_001", - "timestamp": 1234567890, - "data": {} -} -``` - -**Réponse :** -```json -{ - "type": "pong", - "id": "ping_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1" - } -} -``` - -#### GetStatus -```json -{ - "type": "get_status", - "id": "status_001", - "timestamp": 1234567890, - "data": {} -} -``` - -**Réponse :** -```json -{ - "type": "status", - "id": "status_001", - "timestamp": 1234567890, - "data": { - "relay_id": "relay-1", - "status": "running", - "uptime": 3600, - "connected_relays": 3, - "last_block_height": 12345 - } -} -``` - -## 4. API SDK Relay HTTP - -### Informations Générales - -- **Protocole :** HTTP REST -- **Port :** 8091 -- **Base URL :** `http://localhost:8091` -- **Content-Type :** `application/json` - -### Endpoints - -#### GET /health -Vérifie la santé du relais. - -**Requête :** -```bash -curl -X GET http://localhost:8091/health -``` - -**Réponse :** -```json -{ - "status": "healthy", - "relay_id": "relay-1", - "uptime": 3600, - "version": "1.0.0", - "connected_relays": 3 -} -``` - -#### GET /status -Récupère le statut détaillé du relais. - -**Requête :** -```bash -curl -X GET http://localhost:8091/status -``` - -**Réponse :** -```json -{ - "relay_id": "relay-1", - "status": "running", - "uptime": 3600, - "version": "1.0.0", - "connected_relays": 3, - "last_block_height": 12345, - "sync_metrics": { - "messages_sent": 1000, - "messages_received": 950, - "sync_errors": 5 - } -} -``` - -#### GET /relays -Liste les relais connectés. - -**Requête :** -```bash -curl -X GET http://localhost:8091/relays -``` - -**Réponse :** -```json -{ - "relays": [ - { - "relay_id": "relay-2", - "address": "sdk_relay_2:8090", - "status": "connected", - "connected_since": 1234567890, - "last_heartbeat": 1234567890 - }, - { - "relay_id": "relay-3", - "address": "sdk_relay_3:8090", - "status": "connected", - "connected_since": 1234567890, - "last_heartbeat": 1234567890 - } - ] -} -``` - -#### GET /metrics -Récupère les métriques de synchronisation. - -**Requête :** -```bash -curl -X GET http://localhost:8091/metrics -``` - -**Réponse :** -```json -{ - "messages_sent": 1000, - "messages_received": 950, - "sync_errors": 5, - "last_sync_timestamp": 1234567890, - "connected_relays": 3, - "mesh_health": 0.95 -} -``` - -#### POST /sync -Force une synchronisation manuelle. - -**Requête :** -```json -{ - "sync_type": "StateSync", - "target_relay": "relay-2" -} -``` - -**Réponse :** -```json -{ - "success": true, - "message": "Synchronisation initiée", - "sync_id": "sync_001" -} -``` - -## 5. Gestion des Erreurs - -### Erreurs WebSocket - -**Erreur de connexion :** -```json -{ - "type": "error", - "id": "error_001", - "timestamp": 1234567890, - "data": { - "code": "CONNECTION_ERROR", - "message": "Impossible de se connecter au relais", - "details": "Connection refused" - } -} -``` - -**Erreur de message :** -```json -{ - "type": "error", - "id": "error_002", - "timestamp": 1234567890, - "data": { - "code": "INVALID_MESSAGE", - "message": "Format de message invalide", - "details": "Missing required field 'type'" - } -} -``` - -### Erreurs HTTP - -**Erreur 400 :** -```json -{ - "error": { - "code": "INVALID_REQUEST", - "message": "Requête invalide", - "details": "Missing required parameter 'relay_id'" - } -} -``` - -**Erreur 500 :** -```json -{ - "error": { - "code": "INTERNAL_ERROR", - "message": "Erreur interne du serveur", - "details": "Database connection failed" - } -} -``` - -## 6. Exemples d'Utilisation - -### Exemple Python - WebSocket - -```python -import asyncio -import websockets -import json - -async def connect_to_relay(): - uri = "ws://localhost:8090" - async with websockets.connect(uri) as websocket: - # Envoyer un ping - ping_message = { - "type": "ping", - "id": "ping_001", - "timestamp": int(time.time()), - "data": {} - } - await websocket.send(json.dumps(ping_message)) - - # Écouter les messages - async for message in websocket: - data = json.loads(message) - print(f"Message reçu: {data}") - -asyncio.run(connect_to_relay()) -``` - -### Exemple JavaScript - WebSocket - -```javascript -const ws = new WebSocket('ws://localhost:8090'); - -ws.onopen = function() { - // Envoyer un ping - const pingMessage = { - type: 'ping', - id: 'ping_001', - timestamp: Date.now(), - data: {} - }; - ws.send(JSON.stringify(pingMessage)); -}; - -ws.onmessage = function(event) { - const message = JSON.parse(event.data); - console.log('Message reçu:', message); -}; -``` - -### Exemple cURL - Bitcoin Core RPC +### Variables d'Environnement ```bash -# Récupérer les informations de la blockchain -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - --data '{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblockchaininfo", - "params": [] - }' +# Niveau de log +RUST_LOG=debug -# Récupérer un bloc spécifique -curl -X POST http://localhost:18443 \ - -H "Content-Type: application/json" \ - --data '{ - "jsonrpc": "1.0", - "id": "test", - "method": "getblock", - "params": ["blockhash", 2] - }' +# Configuration de compression +COMPRESSION_LEVEL=6 ``` -## 7. Limites et Quotas +## 7. Tests -### Bitcoin Core RPC -- **Taux limite :** 1000 requêtes/minute par défaut -- **Taille des requêtes :** 32MB maximum -- **Connexions simultanées :** 125 par défaut +### Tests Unitaires +```bash +# Tous les tests +cargo test -### Blindbit HTTP -- **Taux limite :** 100 requêtes/minute -- **Taille des requêtes :** 10MB maximum -- **Connexions simultanées :** 50 +# Tests spécifiques +cargo test compression +cargo test validation +cargo test serialization +``` -### SDK Relay WebSocket -- **Connexions simultanées :** 1000 par relais -- **Taille des messages :** 1MB maximum -- **Heartbeat :** 30 secondes +### Tests d'Intégration +```bash +# Tests d'intégration +cargo test --test integration_tests +``` -### SDK Relay HTTP -- **Taux limite :** 200 requêtes/minute -- **Taille des requêtes :** 5MB maximum -- **Connexions simultanées :** 100 +## 8. Performance -## 8. Sécurité +### Métriques de Compression +- **Ratio de compression** : ~70% pour les données textuelles +- **Vitesse de compression** : ~100MB/s +- **Vitesse de décompression** : ~200MB/s -### Authentification -- **Bitcoin Core :** Cookie d'authentification -- **Blindbit :** À définir selon les besoins -- **SDK Relay :** Authentification WebSocket (optionnelle) +### Optimisations +- Utilisation de `flate2` avec `miniz_oxide` (pure Rust) +- Sérialisation JSON optimisée +- Validation en temps constant -### Chiffrement -- **RPC Bitcoin :** HTTP (non chiffré en local) -- **HTTP Blindbit :** HTTP (non chiffré en local) -- **WebSocket SDK Relay :** WSS (chiffré) +## 9. Sécurité ### Bonnes Pratiques -- Utiliser HTTPS/WSS en production -- Implémenter l'authentification appropriée -- Valider toutes les entrées -- Limiter les taux de requêtes -- Monitorer les accès +- Validation systématique des entrées +- Gestion sécurisée des erreurs +- Pas d'exposition d'informations sensibles dans les logs +- Utilisation de types sécurisés -## 9. Monitoring et Observabilité +### Audit de Sécurité +- Code audité pour les vulnérabilités +- Tests de sécurité automatisés +- Mise à jour régulière des dépendances -### Métriques à Surveiller -- **Latence des APIs :** Temps de réponse -- **Taux d'erreur :** Pourcentage d'erreurs -- **Débit :** Requêtes par seconde -- **Utilisation des ressources :** CPU, mémoire, réseau +--- -### Logs -- **Logs d'accès :** Requêtes et réponses -- **Logs d'erreur :** Erreurs et exceptions -- **Logs de performance :** Métriques de performance - -### Alertes -- **Erreurs 5xx :** Erreurs serveur -- **Latence élevée :** Temps de réponse > 1s -- **Taux d'erreur élevé :** > 5% -- **Services indisponibles :** Health checks en échec +**📚 API Reference complète pour sdk_common - Bibliothèque commune pour les Silent Payments** 🚀 diff --git a/docs/INDEX.md b/docs/INDEX.md index 3ed147f..a8875b2 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -45,14 +45,12 @@ Documentation technique détaillée de l'architecture. ### 📡 [API Reference](API.md) Documentation complète des APIs disponibles. -- **API Types** : Types et structures de données -- **API Traits** : Traits et interfaces -- **API Functions** : Fonctions utilitaires -- **API Error Handling** : Gestion des erreurs -- **Format des données et payloads** +- **Types et structures de données** +- **Fonctions utilitaires** +- **Traits et interfaces** - **Gestion des erreurs** - **Exemples d'utilisation** -- **Limites et quotas** +- **Performance et sécurité** ### 🔒 [Sécurité](SECURITY.md) Guide de sécurité et bonnes pratiques. @@ -124,32 +122,8 @@ Guide complet pour le développement. - **Optimisation des performances** - **Déploiement et CI/CD** -### 📋 [Référence Rapide](QUICK_REFERENCE.md) -Référence rapide pour les développeurs. -- **Commandes essentielles** -- **Structure du projet** -- **APIs principales** -- **Configuration rapide** -- **Dépannage rapide** - -### 🔄 [Guide de Migration](MIGRATION.md) -Guide pour les migrations et mises à jour. -- **Migration des versions** -- **Breaking changes** -- **Mise à jour des dépendances** -- **Migration des données** -- **Tests de migration** - ## 🌐 Guides d'Intégration -### 🔗 [Intégration 4NK_node](INTEGRATION_4NK_NODE.md) -Guide d'intégration avec l'infrastructure 4NK_node. -- **Configuration Docker** -- **Variables d'environnement** -- **Communication inter-services** -- **Déploiement intégré** -- **Monitoring et logs** - ### 🔑 [Configuration SSH](SSH_SETUP.md) Guide de configuration SSH pour le développement. - **Génération des clés SSH** @@ -157,30 +131,13 @@ Guide de configuration SSH pour le développement. - **Intégration avec Gitea** - **Automatisation des déploiements** -### 🤖 [Push SSH Automatisé](AUTO_SSH_PUSH.md) +### 🤖 [Push SSH Automatisé](SSH_USAGE.md) Guide pour l'automatisation des pushes SSH. - **Configuration des scripts** - **Intégration CI/CD** - **Gestion des clés** - **Sécurité et bonnes pratiques** -## 📊 État et Monitoring - -### 📊 [État Actuel](ETAT_ACTUEL.md) -État détaillé du projet sdk_common. -- **Statut des compilations** -- **Configuration des branches** -- **Fonctionnalités opérationnelles** -- **Métriques de performance** -- **Problèmes connus** - -### 📋 [Résumé Final](RESUME_FINAL.md) -Résumé complet de l'état final du projet. -- **Succès accomplis** -- **Prêt pour la production** -- **Documentation complète** -- **Support et maintenance** - ## 🔧 Guides d'Open Source ### ✅ [Checklist Open Source](OPEN_SOURCE_CHECKLIST.md) @@ -217,8 +174,7 @@ Guide de support et contact. ### 📚 Documentation 1. [Index](INDEX.md) - Cet index -2. [Quick Reference](QUICK_REFERENCE.md) - Référence rapide -3. [Roadmap](ROADMAP.md) - Évolution du projet +2. [Roadmap](ROADMAP.md) - Évolution du projet ### 🤝 Communauté 1. [Guide Communauté](COMMUNITY_GUIDE.md) - Contribuer @@ -254,9 +210,6 @@ cargo test --features sdk-client # Tests de compatibilité avec sdk_relay cargo test --features sdk-relay - -# Tests de compatibilité WASM -cargo test --features wasm ``` --- diff --git a/docs/USAGE.md b/docs/USAGE.md index 571f7f3..bfe433d 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -14,8 +14,7 @@ cargo build cargo build --all-features # Build avec une feature spécifique -cargo build --features wasm -cargo build --features blindbit-wasm +cargo build --features flate2 ``` ### 2. Build de Production @@ -31,19 +30,6 @@ RUSTFLAGS="-C target-cpu=native" cargo build --release 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 @@ -52,496 +38,392 @@ wasm-pack build --target web --release ```toml [dependencies] -sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", branch = "main" } +sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", branch = "docker-support" } # Avec features spécifiques -sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["wasm"] } +sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["flate2"] } ``` **Utilisation dans le code :** ```rust use sdk_common::{ - types::{Wallet, Transaction, SilentPayment}, - traits::WalletOperations, - error::SdkError + types::{Process, Member, ValidationRule, ProcessState}, + traits::ProcessOperations, + error::SdkError, + compress_data, decompress_data }; fn main() -> Result<(), SdkError> { - // Créer un wallet - let wallet = Wallet::new()?; + // Créer un processus + let process = Process { + id: "process_123".to_string(), + name: "Mon Processus".to_string(), + device_id: "device_456".to_string(), + state: ProcessState::Active, + states: vec![ProcessState::Active], + description: None, + created_at: None, + updated_at: None, + }; - // Générer un paiement silencieux - let payment = SilentPayment::generate(&wallet)?; + // Utiliser la compression + let data = b"données à compresser"; + let compressed = compress_data(data)?; + let decompressed = decompress_data(&compressed)?; - // Traiter une transaction - let tx = Transaction::from_hex("...")?; - let result = wallet.process_transaction(&tx)?; + // Valider le processus + sdk_common::validate_process(&process)?; Ok(()) } ``` -### 2. Intégration JavaScript/TypeScript +## 📦 Types et Structures -**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 - - - - SDK Common Demo - - - - -

SDK Common Demo

-

-
-
-```
-
-## 📚 Utilisation des Types et Structures
-
-### 1. Types de Base
+### Types de Base
 
 ```rust
-use sdk_common::types::*;
+use sdk_common::{
+    Process, ProcessState, Member, ValidationRule, ValidationRuleType
+};
 
-// Wallet
-let wallet = Wallet::new()?;
-let public_key = wallet.public_key();
-let private_key = wallet.private_key();
+// Créer un état de processus
+let state = ProcessState::Active;
 
-// Silent Payment
-let payment = SilentPayment::new(&wallet)?;
-let address = payment.address();
-let scan_key = payment.scan_key();
+// Créer un processus
+let process = Process {
+    id: "process_123".to_string(),
+    name: "Mon Processus".to_string(),
+    device_id: "device_456".to_string(),
+    state: ProcessState::Active,
+    states: vec![ProcessState::Active],
+    description: Some("Description".to_string()),
+    created_at: None,
+    updated_at: None,
+};
 
-// Transaction
-let tx = Transaction::from_hex("...")?;
-let txid = tx.txid();
-let outputs = tx.outputs();
+// Créer un membre
+let member = Member {
+    id: "member_123".to_string(),
+    name: "John Doe".to_string(),
+    public_key: "public_key_here".to_string(),
+    process_id: "process_123".to_string(),
+    roles: vec!["admin".to_string()],
+    sp_addresses: Some(vec!["address1".to_string()]),
+    created_at: None,
+    updated_at: None,
+};
+
+// Créer une règle de validation
+let rule = ValidationRule {
+    id: "rule_123".to_string(),
+    field_name: "amount".to_string(),
+    rule_type: ValidationRuleType::Range,
+    parameters: Some(serde_json::json!({"min": 0, "max": 1000})),
+    role_id: "admin".to_string(),
+    quorum: Some(2),
+    created_at: None,
+    updated_at: None,
+};
 ```
 
-### 2. Traits et Interfaces
+## 🔄 Compression et Sérialisation
+
+### Compression avec flate2
 
 ```rust
-use sdk_common::traits::*;
+use sdk_common::{compress_data, decompress_data};
 
-// Implémentation de WalletOperations
-impl WalletOperations for MyWallet {
-    fn generate_address(&self) -> Result {
-        // Implémentation personnalisée
-    }
+// Compression
+let original_data = b"données importantes à compresser";
+let compressed = compress_data(original_data)?;
 
-    fn sign_transaction(&self, tx: &Transaction) -> Result {
-        // Implémentation personnalisée
-    }
-}
+// Décompression
+let decompressed = decompress_data(&compressed)?;
+assert_eq!(original_data, decompressed.as_slice());
 ```
 
-### 3. Gestion des Erreurs
+### Sérialisation JSON
 
 ```rust
-use sdk_common::error::SdkError;
+use sdk_common::{serialize_process, deserialize_process};
 
-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)
-        }
+// Sérialisation
+let json = serialize_process(&process)?;
+
+// Désérialisation
+let deserialized_process = deserialize_process(&json)?;
+```
+
+## ✅ Validation
+
+### Validation des Structures
+
+```rust
+use sdk_common::{validate_process, validate_member};
+
+// Valider un processus
+validate_process(&process)?;
+
+// Valider un membre
+validate_member(&member)?;
+```
+
+### Validation Personnalisée
+
+```rust
+use sdk_common::ValidationError;
+
+fn validate_custom_process(process: &Process) -> Result<(), ValidationError> {
+    if process.name.is_empty() {
+        return Err(ValidationError::InvalidProcess("Name cannot be empty".to_string()));
     }
+    
+    if process.device_id.is_empty() {
+        return Err(ValidationError::InvalidProcess("Device ID cannot be empty".to_string()));
+    }
+    
+    Ok(())
 }
 ```
 
 ## 🧪 Tests et Validation
 
-### 1. Tests Unitaires
+### Tests Unitaires
 
-```bash
-# Tests de base
-cargo test
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use sdk_common::{Process, ProcessState, validate_process};
 
-# Tests avec output détaillé
-cargo test -- --nocapture
+    #[test]
+    fn test_process_validation() {
+        let process = Process {
+            id: "test_123".to_string(),
+            name: "Test Process".to_string(),
+            device_id: "device_123".to_string(),
+            state: ProcessState::Active,
+            states: vec![ProcessState::Active],
+            description: None,
+            created_at: None,
+            updated_at: None,
+        };
 
-# Tests d'une fonction spécifique
-cargo test test_wallet_creation
+        assert!(validate_process(&process).is_ok());
+    }
 
-# Tests avec couverture
-cargo tarpaulin --out Html
+    #[test]
+    fn test_compression() {
+        let data = b"test data for compression";
+        let compressed = compress_data(data).unwrap();
+        let decompressed = decompress_data(&compressed).unwrap();
+        
+        assert_eq!(data, decompressed.as_slice());
+    }
+}
 ```
 
-### 2. Tests d'Intégration
+### Tests d'Intégration
 
-```bash
-# Tests d'intégration
-cargo test --test integration
+```rust
+// tests/integration_test.rs
+use sdk_common::{Process, Member, ValidationRule};
 
-# Tests de performance
-cargo test --test performance
-
-# Tests de sécurité
-cargo test --test security
+#[test]
+fn test_process_member_integration() {
+    let process = Process { /* ... */ };
+    let member = Member { /* ... */ };
+    
+    // Test d'intégration entre processus et membre
+    assert_eq!(member.process_id, process.id);
+}
 ```
 
-### 3. Tests WASM
+## 🔧 Configuration
 
-```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 :**
+### Features Cargo
 
 ```toml
 [dependencies]
-sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["wasm", "blindbit-wasm"] }
+sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["flate2"] }
 ```
 
-**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 :**
+### Variables d'Environnement
 
 ```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
+# Niveau de log
 export RUST_LOG=debug
 
-# Backtrace
-export RUST_BACKTRACE=1
+# Configuration de compression
+export COMPRESSION_LEVEL=6
 ```
 
-## 🚀 Optimisations de Performance
+## 🚨 Gestion des Erreurs
 
-### 1. Optimisations Rust
+### Types d'Erreurs
 
 ```rust
-// Utilisation de references pour éviter les copies
-fn process_wallet(wallet: &Wallet) -> Result<(), SdkError> {
-    // Traitement optimisé
-}
+use sdk_common::{
+    SdkError, ValidationError, SerializationError, CompressionError
+};
 
-// Utilisation de iterators pour les performances
-fn process_transactions(txs: &[Transaction]) -> Vec> {
-    txs.iter().map(|tx| process_transaction(tx)).collect()
-}
-
-// Utilisation de Box pour les gros objets
-fn create_large_wallet() -> Box {
-    Box::new(Wallet::new().unwrap())
+fn handle_errors() -> Result<(), SdkError> {
+    match some_operation() {
+        Ok(result) => Ok(result),
+        Err(SdkError::Validation(ValidationError::InvalidProcess(msg))) => {
+            eprintln!("Erreur de validation: {}", msg);
+            Err(SdkError::Validation(ValidationError::InvalidProcess(msg)))
+        },
+        Err(SdkError::Compression(CompressionError::CompressionFailed(msg))) => {
+            eprintln!("Erreur de compression: {}", msg);
+            Err(SdkError::Compression(CompressionError::CompressionFailed(msg)))
+        },
+        Err(e) => Err(e),
+    }
 }
 ```
 
-### 2. Optimisations WASM
+### Gestion des Erreurs avec `?`
 
-```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);
+```rust
+fn process_data() -> Result<(), SdkError> {
+    let data = b"données à traiter";
+    
+    // Compression avec gestion d'erreur automatique
+    let compressed = compress_data(data)?;
+    
+    // Validation avec gestion d'erreur automatique
+    let process = create_process()?;
+    validate_process(&process)?;
+    
+    Ok(())
+}
 ```
 
-### 3. Optimisations de Build
+## 📊 Performance
+
+### Optimisations
+
+```rust
+// Utilisation de références pour éviter les copies
+fn process_large_data(data: &[u8]) -> Result, SdkError> {
+    compress_data(data)
+}
+
+// Utilisation de Vec avec capacité pré-allouée
+fn create_process_list(count: usize) -> Vec {
+    let mut processes = Vec::with_capacity(count);
+    // ... remplir la liste
+    processes
+}
+```
+
+### Benchmarks
 
 ```bash
-# Build avec optimisations avancées
-RUSTFLAGS="-C target-cpu=native -C lto=fat -C codegen-units=1" cargo build --release
+# Tests de performance
+cargo bench
 
-# 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
+# Tests de compression
+cargo test compression_benchmark
 ```
 
 ## 🔒 Sécurité
 
-### 1. Validation des Entrées
+### Bonnes Pratiques
 
 ```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);
+// Validation systématique des entrées
+fn create_secure_process(name: &str, device_id: &str) -> Result {
+    if name.is_empty() || device_id.is_empty() {
+        return Err(SdkError::InvalidInput("Name and device_id cannot be empty".to_string()));
     }
-    Ok(())
+    
+    let process = Process {
+        id: generate_secure_id(),
+        name: name.to_string(),
+        device_id: device_id.to_string(),
+        state: ProcessState::Active,
+        states: vec![ProcessState::Active],
+        description: None,
+        created_at: None,
+        updated_at: None,
+    };
+    
+    validate_process(&process)?;
+    Ok(process)
 }
 
-// Validation des transactions
-fn validate_transaction(tx_hex: &str) -> Result<(), SdkError> {
-    if !is_valid_transaction_hex(tx_hex) {
-        return Err(SdkError::InvalidTransaction);
-    }
+// Gestion sécurisée des erreurs
+fn handle_sensitive_data(data: &[u8]) -> Result<(), SdkError> {
+    // Ne pas exposer les données sensibles dans les logs
+    let compressed = compress_data(data).map_err(|e| {
+        log::error!("Compression failed: {}", e);
+        SdkError::Internal("Compression failed".to_string())
+    })?;
+    
     Ok(())
 }
 ```
 
-### 2. Gestion de la Mémoire
+## 🛠️ Développement
+
+### Workflow de Développement
+
+```bash
+# 1. Cloner le projet
+git clone https://git.4nkweb.com/4nk/sdk_common.git
+cd sdk_common
+
+# 2. Installer les dépendances
+cargo build
+
+# 3. Lancer les tests
+cargo test
+
+# 4. Vérifier le code
+cargo clippy -- -D warnings
+cargo fmt -- --check
+
+# 5. Générer la documentation
+cargo doc --open
+```
+
+### Debugging
 
 ```rust
-// Utilisation de zeroize pour les données sensibles
-use zeroize::Zeroize;
+// Utilisation de logs pour le debugging
+use log::{debug, info, warn, error};
 
-struct SecureWallet {
-    private_key: Vec,
-}
-
-impl Drop for SecureWallet {
-    fn drop(&mut self) {
-        self.private_key.zeroize();
+fn debug_process(process: &Process) {
+    debug!("Processing process: {:?}", process);
+    
+    match validate_process(process) {
+        Ok(()) => info!("Process validation successful"),
+        Err(e) => warn!("Process validation failed: {:?}", e),
     }
 }
 ```
 
-### 3. Protection contre les Attaques
+## 📚 Ressources Additionnelles
 
-```rust
-// Protection contre les attaques par timing
-use subtle::ConstantTimeEq;
+### Documentation
 
-fn verify_signature(sig1: &[u8], sig2: &[u8]) -> bool {
-    sig1.ct_eq(sig2).unwrap_u8() == 1
-}
+- [API Reference](API.md) - Documentation complète des APIs
+- [Architecture](ARCHITECTURE.md) - Architecture technique détaillée
+- [Configuration](CONFIGURATION.md) - Guide de configuration
+- [Tests](TESTING.md) - Stratégies de tests
 
-// Protection contre les attaques par déni de service
-fn process_with_timeout(f: F, timeout: Duration) -> Result
-where
-    F: FnOnce() -> Result,
-{
-    // Implémentation avec timeout
-}
-```
+### Exemples
 
-## 📊 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 {
-    // 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
+- [Exemples de base](../examples/) - Exemples d'utilisation
+- [Tests d'intégration](../tests/) - Tests complets
+- [Benchmarks](../benches/) - Tests de performance
 
 ---
 
-**📖 La bibliothèque sdk_common est maintenant prête à être utilisée dans vos projets !** 🚀
+**📖 Guide d'utilisation complet pour sdk_common - Bibliothèque commune pour les Silent Payments** 🚀