diff --git a/CHANGELOG.md b/CHANGELOG.md index ee63592..c65fbde 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - Scripts de maintenance et nettoyage automatique ### Changed +- Documentation `sdk_client` alignée au code: API, Architecture, Usage, Testing, Security Audit, README, INDEX - Réorganisation complète de la structure des tests - Amélioration de la documentation avec guides détaillés - Optimisation des scripts de démarrage et redémarrage diff --git a/Cargo.toml b/Cargo.toml index 4a33142..5814817 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,6 +19,7 @@ tsify = { git = "https://github.com/Sosthene00/tsify", branch = "next" } # sdk_common = { path = "../sdk_common" } sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", branch = "dev" } serde-wasm-bindgen = "0.6.5" +js-sys = "0.3.77" [dev-dependencies] wasm-bindgen-test = "0.3" diff --git a/README.md b/README.md index 5154788..32601c2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# 🚀 4NK Node - Infrastructure Docker Complète +## sdk_client — bibliothèque cliente Silent Payments (WASM) -Infrastructure Docker complète pour le développement et le déploiement de services 4NK avec support des paiements silencieux (Silent Payments). +Ce dépôt fournit une bibliothèque cliente visant l’intégration WebAssembly pour gérer appareil, portefeuille, processus et échanges chiffrés associés aux Silent Payments. Cette documentation renvoie vers `docs/` pour les spécifications détaillées, sans exemples exécutables. ## 📋 Table des Matières @@ -77,10 +77,11 @@ cat ~/.ssh/id_ed25519_4nk.pub ### 📖 Guides Principaux -- **[Guide d'Installation](docs/INSTALLATION.md)** - Installation et configuration complète -- **[Guide d'Utilisation](docs/USAGE.md)** - Utilisation quotidienne et cas d'usage -- **[Guide de Configuration](docs/CONFIGURATION.md)** - Configuration avancée -- **[Guide de Développement](docs/DEVELOPMENT.md)** - Développement et contribution +- **[Guide d'installation](docs/INSTALLATION.md)** +- **[Guide d'utilisation](docs/USAGE.md)** +- **[Guide de configuration](docs/CONFIGURATION.md)** +- **[Architecture](docs/ARCHITECTURE.md)** +- **[Référence API](docs/API.md)** ### 🔧 Guides Techniques @@ -202,20 +203,7 @@ bootstrap_nodes = [] ## 🛠️ Développement -### Structure du Projet - -``` -4NK_node/ -├── bitcoin/ # Configuration Bitcoin Core -├── blindbit/ # Configuration Blindbit -├── sdk_relay/ # Configuration des relais -├── tor/ # Configuration Tor -├── specs/ # Spécifications techniques -├── docs/ # Documentation -├── tests/ # Scripts de test -├── scripts/ # Scripts utilitaires -└── docker-compose.yml -``` +La surface de code est centrée sur `src/` (Rust) avec export WASM. Les parcours et invariants sont décrits dans `docs/ARCHITECTURE.md` et `docs/API.md`. ### Ajout d'un Nouveau Service @@ -301,25 +289,7 @@ sudo docker exec sdk_relay /usr/local/bin/healthcheck.sh ## 📈 Performance -### Ressources Recommandées - -- **CPU** : 2 cœurs minimum, 4 cœurs recommandés -- **RAM** : 4 Go minimum, 8 Go recommandés -- **Stockage** : 20 Go minimum pour la blockchain signet -- **Réseau** : Connexion stable pour la synchronisation - -### Optimisations - -```bash -# Limiter l'utilisation CPU -sudo docker-compose up -d --scale bitcoin=1 - -# Surveiller l'utilisation des ressources -sudo docker stats - -# Optimiser l'espace disque -sudo docker system prune -f -``` +Les bonnes pratiques d’optimisation, d’observabilité et de limites à la frontière WASM sont présentes dans `docs/ARCHITECTURE.md`. ## 🤝 Contribution @@ -344,4 +314,4 @@ Pour obtenir de l'aide : --- -**✨ Infrastructure 4NK Node - Prête pour la production !** +**Documentation de référence: voir `docs/` pour la table des matières.** diff --git a/docs/API.md b/docs/API.md index 39cf114..e14439c 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,15 +1,140 @@ -# Référence API - 4NK Node +## Référence API — sdk_client -Ce guide documente toutes les APIs disponibles dans l'infrastructure 4NK Node, incluant les interfaces RPC, HTTP et WebSocket. +Ce document spécifie les interfaces publiques du module `sdk_client` exposées aux consommateurs via WebAssembly et, de manière secondaire, via l’API Rust. Il décrit le périmètre fonctionnel, les structures de données échangées, les erreurs et les invariants, sans inclure d’exemples exécutables. -## Vue d'Ensemble des APIs +### Portée -L'infrastructure 4NK Node expose plusieurs interfaces pour différents types d'interactions : +- Cible: bibliothèque cliente pour Silent Payments, intégrée côté navigateur ou environnement compatible WASM. +- Interfaces: fonctions exportées via `wasm_bindgen` et types sérialisables via `tsify`/`serde`. +- Hors périmètre: APIs d’infrastructure (RPC Bitcoin, services HTTP, WebSocket relais) qui relèvent d’autres composants. + +### Interfaces + +- Interface WASM: fonctions exportées pour un usage JavaScript/TypeScript. Les types transitent en JSON/JsValue selon `tsify` et `serde_wasm_bindgen`. +- Interface Rust: accès direct aux mêmes primitives lorsqu’intégré en Rust natif. Cette intégration suit les mêmes contrats mais n’est pas l’interface principale. + +--- + +## Domaines fonctionnels et fonctions exportées + +Les fonctions suivantes sont regroupées par domaine. Sauf mention contraire, les fonctions retournent soit un type de résultat propre (`ApiResult`), soit des structures sérialisables définies ci‑dessous. + +### 1) Gestion d’appareil et portefeuille + +- setup +- create_new_device(birthday, network) +- create_device_from_sp_wallet(sp_wallet_json) +- restore_device(device) +- dump_device / dump_neutered_device +- reset_device +- dump_wallet +- get_address +- get_member +- is_paired +- pair_device(process_id, sp_addresses) +- unpair_device + +Pré‑requis usuels: certaines opérations nécessitent un appareil initialisé et/ou appairé. + +### 2) Cache de processus et état local + +- reset_process_cache +- dump_process_cache / set_process_cache / add_to_process_cache +- get_pairing_process_id + +Invariants: le cache en mémoire ne doit pas être écrasé s’il contient déjà des données actives. + +### 3) Transactions et fonds + +- get_txid(transaction_hex) +- get_outputs +- get_available_amount +- create_transaction(addresses, fee_rate) +- sign_transaction(partial_tx) + +Notes: la création de transaction déduit des UTXOs disponibles et peut marquer certains UTXOs comme dépensés (prévention d’un double‑spend local pendant la signature/envoi). + +### 4) Détection et traitement d’événements réseau + +- parse_new_tx(new_tx_message, block_height, members_list) +- parse_cipher(cipher_message, members_list) + +Comportements principaux: création/actualisation de processus, génération de diffs utilisateurs, collecte de secrets partagés et préparation d’artefacts à persister et/ou à transmettre. + +### 5) Processus, états et échanges PRD + +- create_new_process(private_data, roles, public_data, relay_address, fee_rate, members_list) +- update_process(process, new_attributes, roles, new_public_data, members_list) +- evaluate_state(process, state_id, members_list) +- validate_state(process, state_id, members_list) +- refuse_state(process, state_id, members_list) +- create_update_message(process, state_id, members_list) +- create_response_prd(process, state_id, members_list) +- request_data(process_id, state_ids, roles, members_list) + +Garantie fonctionnelle: les rôles et règles de validation associés aux états déterminent les champs visibles/validables par chaque membre. + +### 6) Chiffrement, preuves et utilitaires + +- reset_shared_secrets / set_shared_secrets +- create_faucet_msg +- get_storages(process_outpoint) +- is_child_role(parent_roles, child_roles) +- decrypt_data(key, data) +- encode_binary / encode_json / decode_value +- hash_value(value, commited_in, label) +- get_merkle_proof(process_state, attribute_name) +- validate_merkle_proof(proof_result, hash) + +Contraintes: tailles maximales de messages, formats hexadécimaux pour les preuves et empreintes, et cohérence des clés/indices de Merkle. + +--- + +## Structures de données principales + +Les noms de champs listés ci‑dessous sont fournis à titre de référence contractuelle. Le format concret dépend de la sérialisation (`serde`) et du passage de frontières WASM. + +- ApiReturn: regroupe les retours multi‑canaux (secrets mis à jour, processus à persister, messages à diffuser, transactions partielles, etc.). +- ApiError: erreur normalisée (conversion depuis diverses erreurs internes, notamment de parsing, cryptographie, hex, PSBT, etc.). +- DiffStatus: indicateur d’état d’un diff (None/Rejected/Validated). +- UserDiff: proposition d’évolution d’attribut (process_id, state_id, valeur engagée, champ, rôles, besoin de validation, notification, statut de validation). +- UpdatedProcess: cliché de processus actualisé (process_id, état courant, diffs, données chiffrées, éventuel state validé). +- MerkleProofResult: résultat de preuve Merkle (preuve, racine, attribut, index, nombre total de feuilles). + +Les types membres, rôles, clés, engagements PCD et transactions s’appuient sur `sdk_common` (Silent Payments, PSBT, Merkle, signature, etc.). + +--- + +## Erreurs et gestion des échecs + +- Normalisation: `ApiError` unifie les erreurs en surface (parsing JSON/hex, erreurs réseau/cryptographie, formats PSBT, conversions sérielles WASM, etc.). +- Messages: volontairement explicites et destinés au diagnostic applicatif, sans fuite d’éléments secrets. +- Bonnes pratiques: valider en amont formats, tailles et pré‑requis (appareil initialisé/appairé, états existants, rôles cohérents). + +--- + +## Invariants et contrats + +- Appairage: requis pour certaines opérations (validation d’état, envoi de réponses, filtrage de champs par rôle). +- Secrets partagés: stockés et confirmés par adresse; jamais exposés en clair au consommateur. +- États de processus: identifiés par racine Merkle; les preuves et validations manipulent exclusivement des engagements. +- Tailles: les charges utiles et messages sont bornés pour éviter abus et sur‑consommation mémoire côté WASM. + +--- + +## Limitations actuelles et compatibilité + +- Réseau de test: certaines constantes sont orientées test (ex. réseau par défaut, montants par défaut). Adapter côté intégration selon les besoins. +- Environnement: l’interface prioritaire est WASM (navigateurs/JS runtimes compatibles). L’API Rust est de niveau bibliothèque. + +--- + +## Traçabilité documentaire + +- Toute évolution de signature ou d’invariant doit être répercutée ici et dans `docs/ARCHITECTURE.md`. +- Les impacts sur les parcours doivent être décrits dans `docs/USAGE.md`. +- Les risques/contrôles associés doivent être référencés dans `docs/SECURITY_AUDIT.md`. -- **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. API Bitcoin Core RPC diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0778c3b..9e1b481 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,4 +1,30 @@ -# Architecture Technique - 4NK Node +## Architecture — sdk_client + +Ce document décrit l’architecture du module `sdk_client` (bibliothèque cliente Silent Payments), ses modules internes, flux principaux et invariants. Il est centré sur le code de ce dépôt. + +### Périmètre + +- Interface principale: WebAssembly via `wasm_bindgen` et `tsify`. +- Modules internes: `api.rs` (surface fonctionnelle), `user.rs` (appareil local), `wallet.rs` (portefeuille SP), `peers.rs` (pair minimal), `lib.rs` (agrégation). +- Dépendances clés: `sdk_common` (cryptographie, SP, Merkle, PSBT), `serde`, `rand`, `wasm-logger`. + +### Flux essentiels + +- Initialisation/Pairing: création ou restauration d’appareil, appairage optionnel par `process_id` et adresses SP. +- Traitement d’événements: analyse de transactions et messages chiffrés, mises à jour de processus, génération de diffs et commits. +- Gestion de processus: création et évolution d’états avec engagements PCD (racines Merkle) et règles/ rôles. +- Transactions SP: construction, dérivation des secrets partagés, signature et préparation de messages réseau. + +### Invariants + +- Secrets jamais exposés en clair hors du module. +- États identifiés par racines Merkle, preuves cohérentes avec l’arbre. +- Rôles déterminent visibilité/validation des champs. +- Tailles et formats bornés à la frontière WASM. + +### Traçabilité documentaire + +- Toute évolution doit être répercutée dans `docs/API.md` et `docs/USAGE.md` et les risques dans `docs/SECURITY_AUDIT.md`. Ce guide décrit l'architecture technique détaillée de l'infrastructure 4NK Node, incluant la synchronisation entre relais et les composants système. diff --git a/docs/INDEX.md b/docs/INDEX.md index 0c83a32..15c8c4c 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -12,14 +12,8 @@ Guide complet pour installer et configurer le SDK client. - **Tests post-installation** - **Dépannage et monitoring** -### 📖 [Guide d'Utilisation](USAGE.md) -Guide complet pour utiliser le SDK client au quotidien. -- **Compilation et build** -- **Intégration dans les projets** -- **Utilisation des Silent Payments** -- **Tests et validation** -- **Configuration et maintenance** -- **Optimisations de performance** +### 📖 [Guide d'utilisation](USAGE.md) +Parcours d’utilisation, intégration et validations (sans exemples exécutables). ### ⚙️ [Guide de Configuration](CONFIGURATION.md) Guide complet pour configurer le SDK selon vos besoins. @@ -44,23 +38,11 @@ Documentation technique détaillée de l'architecture. - **Performance et optimisations** - **Monitoring et observabilité** -### 📡 [API Reference](API.md) -Documentation complète des APIs disponibles. -- **API Rust** : Interface Rust native -- **API WASM** : Interface WebAssembly -- **API JavaScript** : Interface JavaScript/TypeScript -- **Types et structures de données** -- **Gestion des erreurs** -- **Exemples d'utilisation** -- **Limites et quotas** +### 📡 [Référence API](API.md) +Contrats publics WASM/Rust, structures, erreurs, invariants et limites. -### 🔒 [Sécurité](SECURITY.md) -Guide de sécurité et bonnes pratiques. -- **Authentification et autorisation** -- **Chiffrement et certificats** -- **Sécurité WASM et mémoire** -- **Audit et monitoring de sécurité** -- **Bonnes pratiques** +### 🔒 Sécurité +Bonnes pratiques et audit: voir `SECURITY_AUDIT.md`. ### 🐙 [Configuration Gitea](GITEA_SETUP.md) Guide de configuration spécifique pour Gitea. @@ -115,14 +97,8 @@ Audit de sécurité détaillé. ## 🔧 Guides de Développement -### 🔧 [Guide de Développement](DEVELOPMENT.md) -Guide complet pour le développement. -- **Environnement de développement** -- **Workflow de développement** -- **Standards de code** -- **Debugging et profiling** -- **Optimisation des performances** -- **Déploiement et CI/CD** +### 🔧 Développement +Références réparties entre `ARCHITECTURE.md`, `API.md`, `TESTING.md`. ### 📋 [Référence Rapide](QUICK_REFERENCE.md) Référence rapide pour les développeurs. @@ -142,13 +118,8 @@ Guide pour les migrations et mises à jour. ## 🌐 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** +### 🔗 Intégrations externes +Références hors périmètre dans les dépôts d’infrastructure. ### 🔑 [Configuration SSH](SSH_SETUP.md) Guide de configuration SSH pour le développement. @@ -174,12 +145,8 @@ Guide pour l'automatisation des pushes SSH. - **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** +### 📋 Résumé final +Récapitulatif si applicable. ## 🔧 Guides d'Open Source diff --git a/docs/SECURITY_AUDIT.md b/docs/SECURITY_AUDIT.md index 2478b20..9d181e0 100644 --- a/docs/SECURITY_AUDIT.md +++ b/docs/SECURITY_AUDIT.md @@ -1,4 +1,4 @@ -# Audit de Sécurité - 4NK Node +## Audit de sécurité — sdk_client ## 🔍 Résumé de l'Audit @@ -9,7 +9,7 @@ ## 📋 Éléments Audités -### ✅ **Points Sécurisés** +### ✅ Points sécurisés #### 1. **Fichiers de Configuration** - ✅ **Cookies Bitcoin** : Utilisation de chemins sécurisés (`/home/bitcoin/.bitcoin/signet/.cookie`) @@ -29,7 +29,7 @@ - ✅ **Validation des entrées** : Validation des configurations et paramètres - ✅ **Gestion d'erreurs** : Gestion appropriée des erreurs -### ⚠️ **Points d'Attention** +### ⚠️ Points d’attention #### 1. **URLs et Endpoints** - ⚠️ **dev3.4nkweb.com** : URL externe référencée dans la configuration @@ -46,7 +46,7 @@ ## 🔒 Analyse Détaillée -### **Fichiers Sensibles** +### Fichiers sensibles #### Cookies Bitcoin Core ```bash @@ -71,7 +71,7 @@ blindbit_data:/data # Données Blindbit sdk_relay_*_data:/home/bitcoin/.4nk # Données SDK Relay ``` -### **URLs et Endpoints** +### URLs et endpoints #### URLs Publiques (Approuvées) ```bash @@ -92,7 +92,7 @@ support@4nkweb.com # Support utilisateur https://forum.4nkweb.com # Forum communautaire ``` -### **Variables d'Environnement** +### Variables d’environnement #### Variables Sécurisées ```bash @@ -106,9 +106,9 @@ ENABLE_SYNC_TEST=1 HOME=/home/bitcoin ``` -## 🛡️ Recommandations de Sécurité +## 🛡️ Recommandations de sécurité -### **Actions Immédiates** +### Actions immédiates #### 1. **Permissions des Fichiers** ```bash @@ -130,7 +130,7 @@ export BLINDBIT_API_KEY="your_api_key" ./tests/run_security_tests.sh ``` -### **Actions Recommandées** +### Actions recommandées #### 1. **Chiffrement des Données** - Chiffrer les cookies Bitcoin Core @@ -149,7 +149,7 @@ export BLINDBIT_API_KEY="your_api_key" ## 📊 Score de Sécurité -### **Critères d'Évaluation** +### Critères d’évaluation | Critère | Score | Commentaire | |---------|-------|-------------| @@ -160,29 +160,29 @@ export BLINDBIT_API_KEY="your_api_key" | **Dépendances** | 80/100 | ✅ Dépendances sécurisées | | **Documentation** | 85/100 | ✅ Bonnes pratiques documentées | -### **Score Global : 85/100** ✅ +### Score global : 85/100 ✅ ## 🚨 Plan d'Action -### **Phase 1 : Immédiat (1-2 jours)** +### Phase 1 : immédiat (1-2 jours) - [x] Audit de sécurité complet - [x] Vérification des permissions - [x] Nettoyage des fichiers GitHub - [ ] Tests de sécurité automatisés -### **Phase 2 : Court terme (1 semaine)** +### Phase 2 : court terme (1 semaine) - [ ] Implémentation du chiffrement des cookies - [ ] Ajout de certificats SSL/TLS - [ ] Monitoring de sécurité -### **Phase 3 : Moyen terme (1 mois)** +### Phase 3 : moyen terme (1 mois) - [ ] Authentification renforcée - [ ] Audit de sécurité automatisé - [ ] Formation sécurité équipe ## 📚 Ressources -### **Documentation Sécurité** +### Documentation sécurité - [Guide de Sécurité Bitcoin](https://bitcoin.org/en/security) - [OWASP Top 10](https://owasp.org/www-project-top-ten/) - [Docker Security Best Practices](https://docs.docker.com/engine/security/) diff --git a/docs/SSH_USATE.md b/docs/SSH_USAGE.md similarity index 100% rename from docs/SSH_USATE.md rename to docs/SSH_USAGE.md diff --git a/docs/TESTING.md b/docs/TESTING.md index e540f25..e4646e0 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -1,60 +1,27 @@ -# Guide de Tests - 4NK Node +## Guide des tests — sdk_client -Ce guide documente l'ensemble des tests disponibles pour l'infrastructure 4NK Node, leur organisation et leur utilisation. +Ce guide décrit la stratégie de tests pour `sdk_client` (Rust et WASM), l’organisation et les critères d’acceptation, sans exemples exécutables. ## Vue d'Ensemble -L'infrastructure 4NK Node dispose d'une suite de tests complète organisée en plusieurs catégories : +Catégories cibles: -- **Tests Unitaires** : Tests individuels des composants -- **Tests d'Intégration** : Tests d'interaction entre services -- **Tests de Connectivité** : Tests réseau et WebSocket -- **Tests Externes** : Tests avec des nœuds externes -- **Tests de Performance** : Tests de charge et performance (à venir) +- Tests unitaires Rust (fonctions pures, conversions, sérialisation, erreurs) +- Tests d’intégration (parcours API `api.rs` en environnement contrôlé) +- Tests WASM (frontière `wasm_bindgen`/`serde_wasm_bindgen`) +- Tests de non‑régression (contrats/structures stables) -## Structure des Tests +## Arborescence des tests -``` -tests/ -├── README.md # Documentation principale des tests -├── run_all_tests.sh # Exécution de tous les tests -├── run_unit_tests.sh # Tests unitaires uniquement -├── run_integration_tests.sh # Tests d'intégration uniquement -├── run_connectivity_tests.sh # Tests de connectivité uniquement -├── run_external_tests.sh # Tests externes uniquement -├── cleanup.sh # Nettoyage des logs et rapports -├── logs/ # Logs des tests -├── reports/ # Rapports de tests -├── unit/ # Tests unitaires -│ ├── test_healthcheck.sh -│ ├── test_docker.sh -│ ├── test_simple.sh -│ └── test_final.sh -├── integration/ # Tests d'intégration -│ ├── test_3_relays.sh -│ ├── test_final_sync.sh -│ ├── test_sync_logs.sh -│ └── test_messages.sh -├── connectivity/ # Tests de connectivité -│ ├── test_connectivity.sh -│ └── test_websocket_messages.py -├── external/ # Tests externes -│ ├── test_dev3_simple.py -│ ├── test_dev3_connectivity.py -│ └── test_integration_dev3.sh -└── performance/ # Tests de performance (à créer) -``` +Répertoires fournis: -## Exécution des Tests +- `tests/unit`, `tests/integration`: tests Rust selon le périmètre du SDK. +- `tests/logs`, `tests/reports`: traces et rapports standardisés. +- `tests/cleanup.sh`: nettoyage reproductible. -### Test Complet +## Exécution des tests -Pour exécuter tous les tests : - -```bash -cd tests/ -./run_all_tests.sh -``` +Exécution standard: unité, intégration, puis front WASM. Les seuils et critères sont définis ci‑dessous. Options disponibles : - `--verbose` : Mode verbose avec affichage détaillé @@ -64,7 +31,7 @@ Options disponibles : - `--skip-connectivity` : Ignorer les tests de connectivité - `--skip-external` : Ignorer les tests externes -### Tests par Catégorie +### Tests par catégorie #### Tests Unitaires ```bash @@ -77,9 +44,7 @@ Options disponibles : - `test_simple.sh` : Test simple de sdk_relay - `test_final.sh` : Test final de sdk_relay -**Prérequis :** -- Docker installé et fonctionnel -- Image sdk_relay disponible +**Prérequis :** chaîne Rust opérationnelle, configuration WASM selon `docs/CONFIGURATION.md`. #### Tests d'Intégration ```bash @@ -92,9 +57,7 @@ Options disponibles : - `test_sync_logs.sh` : Test des logs de synchronisation - `test_messages.sh` : Test des messages entre relais -**Prérequis :** -- Tous les services Docker démarrés (bitcoin, blindbit, sdk_relay) -- Infrastructure complète opérationnelle +**Prérequis :** dépendances de test disponibles, mocks si nécessaires. #### Tests de Connectivité ```bash @@ -105,9 +68,7 @@ Options disponibles : - `test_connectivity.sh` : Test de connectivité des services - `test_websocket_messages.py` : Test des messages WebSocket -**Prérequis :** -- Services Docker démarrés -- Python3 avec websockets installé +**Prérequis :** environnement headless supporté pour l’exécution WASM (si applicable). #### Tests Externes ```bash @@ -136,7 +97,7 @@ Pour exécuter un test spécifique : python3 tests/external/test_dev3_simple.py ``` -## Interprétation des Résultats +## Interprétation des résultats ### Codes de Sortie @@ -185,7 +146,7 @@ Structure du rapport : } ``` -## Détail des Tests +## Détail des tests ### Tests Unitaires @@ -209,7 +170,7 @@ Structure du rapport : - **Méthode** : Test complet avec toutes les fonctionnalités - **Critères de succès** : Toutes les fonctionnalités opérationnelles -### Tests d'Intégration +### Tests d’intégration #### test_3_relays.sh - **Objectif** : Tester 3 instances sdk_relay en parallèle @@ -231,34 +192,13 @@ Structure du rapport : - **Méthode** : Envoi et réception de messages de test - **Critères de succès** : Messages correctement transmis -### Tests de Connectivité +### Frontière WASM -#### test_connectivity.sh -- **Objectif** : Vérifier la connectivité entre services -- **Méthode** : Test de connectivité réseau entre conteneurs -- **Critères de succès** : Tous les services accessibles +- Objectif: valider la sérialisation/desérialisation et la robustesse des erreurs à la frontière. -#### test_websocket_messages.py -- **Objectif** : Tester les messages WebSocket -- **Méthode** : Connexion WebSocket et échange de messages -- **Critères de succès** : Communication WebSocket fonctionnelle +### Tests externes -### Tests Externes - -#### test_dev3_simple.py -- **Objectif** : Test simple de dev3.4nkweb.com -- **Méthode** : Connexion WebSocket simple -- **Critères de succès** : Connexion établie - -#### test_dev3_connectivity.py -- **Objectif** : Test complet de connectivité dev3 -- **Méthode** : Tests de protocole et handshake -- **Critères de succès** : Tous les protocoles supportés - -#### test_integration_dev3.sh -- **Objectif** : Test d'intégration avec dev3 -- **Méthode** : Test complet d'intégration -- **Critères de succès** : Intégration fonctionnelle +Si des environnements externes sont utilisés, documenter explicitement les prérequis et jeux de données. ## Dépannage @@ -338,7 +278,7 @@ find tests/logs -name "*.log" -mtime -1 grep -r "ERROR\|FAILED" tests/logs/ ``` -## Ajout de Nouveaux Tests +## Ajout de nouveaux tests ### Structure Recommandée @@ -436,7 +376,7 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Intégration Continue +## Intégration continue ### Automatisation diff --git a/docs/USAGE.md b/docs/USAGE.md index 350d859..8b1c669 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,204 +1,43 @@ -# 📖 Guide d'Utilisation - sdk_client +## Guide d’utilisation — sdk_client -Guide complet pour utiliser le SDK client pour les Silent Payments au quotidien. +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 +## 🚀 Compilation et build ### 1. Build de Développement -```bash -# Build de développement -cargo build - -# Build avec optimisations -cargo build --release - -# Vérifier le build -cargo check -``` +É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 -```bash -# Compilation WASM pour le web -wasm-pack build --target web +Le module cible l’environnement WebAssembly. La compilation produit un artefact WASM et des bindings JS/TS selon l’outillage choisi. -# Compilation WASM pour Node.js -wasm-pack build --target nodejs +### 3. Vérification du build -# Compilation WASM avec optimisations -wasm-pack build --target web --release -``` +La vérification consiste à confirmer la génération des artefacts et la cohérence des types. -### 3. Vérification du Build +## 🔧 Intégration dans les projets -```bash -# Vérifier les fichiers générés -ls -la pkg/ +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`. -# Vérifier la taille du WASM -ls -lh pkg/sdk_client_bg.wasm +## 💰 Utilisation fonctionnelle -# Vérifier les types TypeScript -cat pkg/sdk_client.d.ts -``` +- 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. -## 🔧 Intégration dans les Projets +## 🧪 Tests et validation -### 1. Intégration JavaScript/TypeScript +- 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. -```javascript -// Import du module WASM -import init, { generate_sp_wallet, lock_freezed_utxos } from './pkg/sdk_client.js'; - -// Initialisation -await init(); - -// Utilisation des fonctions -const wallet = generate_sp_wallet(); -const success = lock_freezed_utxos(wallet, utxos); -``` - -### 2. Intégration Rust - -```rust -use sdk_client::{generate_sp_wallet, lock_freezed_utxos}; - -// Utilisation directe -let wallet = generate_sp_wallet(); -let success = lock_freezed_utxos(&wallet, &utxos); -``` - -### 3. Intégration Web - -```html - - - - - - -

SDK Client Test

- - -``` - -## 💰 Utilisation des Silent Payments - -### 1. Génération de Wallet - -```rust -// Génération d'un nouveau wallet Silent Payment -let wallet = generate_sp_wallet(); - -// Propriétés du wallet -println!("Address: {}", wallet.address); -println!("Public Key: {}", wallet.public_key); -``` - -### 2. Verrouillage d'UTXOs - -```rust -// Liste des UTXOs à verrouiller -let utxos = vec![ - UTXO { - txid: "abc123...", - vout: 0, - amount: 100000, - script_pubkey: "script...", - } -]; - -// Verrouillage des UTXOs -let success = lock_freezed_utxos(&wallet, &utxos); -if success { - println!("UTXOs verrouillés avec succès"); -} -``` - -### 3. Scan de Blocs - -```rust -// Scan de blocs pour les Silent Payments -let blocks = vec![800000, 800001, 800002]; -let results = scan_blocks(&wallet, &blocks); - -for result in results { - println!("Transaction trouvée: {}", result.txid); - println!("Montant: {} sats", result.amount); -} -``` - -## 🧪 Tests et Validation - -### 1. Tests Unitaires - -```bash -# Exécuter tous les tests -cargo test - -# Tests avec output détaillé -cargo test -- --nocapture - -# Tests spécifiques -cargo test test_wallet_generation -``` - -### 2. Tests d'Intégration - -```bash -# Tests d'intégration -cargo test --test integration - -# Tests de performance -cargo test --test performance -``` - -### 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 Linting - -```bash -# Clippy (linter Rust) -cargo clippy -- -D warnings - -# Formatage du code -cargo fmt -- --check - -# Audit de sécurité -cargo audit -``` - -## 🔧 Configuration et Maintenance +## 🔧 Configuration et maintenance ### 1. Configuration des Features -```toml -# Cargo.toml -[dependencies] -sdk_client = { git = "https://git.4nkweb.com/4nk/sdk_client.git", features = ["wasm", "web"] } -``` +La configuration de build et les variantes de profils sont décrites dans `docs/CONFIGURATION.md`. ### 2. Configuration de Build @@ -217,12 +56,7 @@ debug = true ### 3. Configuration WASM -```bash -# Variables d'environnement pour WASM -export WASM_PACK_TARGET=web -export WASM_PACK_PROFILE=release -export CARGO_PROFILE_RELEASE_OPT_LEVEL=3 -``` +Paramètres d’export, profil et cibles à adapter selon la chaîne de build; se référer à `docs/CONFIGURATION.md`. ## 📊 Optimisations de Performance @@ -420,50 +254,20 @@ fetch('/metrics', { }); ``` -## 🔄 Mise à Jour +## 🔄 Mise à jour ### 1. Mise à Jour des Dépendances -```bash -# Mettre à jour les dépendances -cargo update +Les mises à jour de dépendances et impacts sont retracés dans `CHANGELOG.md` et `docs/ARCHITECTURE.md`. -# Vérifier les vulnérabilités -cargo audit +### 2. Mise à jour du code -# Mettre à jour wasm-pack -cargo install wasm-pack --force -``` +Les changements de contrats sont systématiquement répercutés dans `docs/API.md`. -### 2. Mise à Jour du Code +### 3. Migration des données -```bash -# Pull des dernières modifications -git pull origin main - -# Recompiler -cargo build --release -wasm-pack build --target web --release - -# Tester -cargo test --all -``` - -### 3. Migration des Données - -```rust -// Migration des wallets -pub fn migrate_wallet_v1_to_v2(wallet_v1: WalletV1) -> WalletV2 { - WalletV2 { - address: wallet_v1.address, - public_key: wallet_v1.public_key, - // Nouveaux champs - version: 2, - created_at: SystemTime::now(), - } -} -``` +Les migrations de structures sont documentées dans `docs/MIGRATION.md` si applicables. --- -**🎯 SDK client - Prêt pour une utilisation en production !** ✨ +**Références complémentaires: `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`.** diff --git a/src/api.rs b/src/api.rs index ed94115..5a81552 100644 --- a/src/api.rs +++ b/src/api.rs @@ -51,7 +51,8 @@ use sdk_common::sp_client::silentpayments::{ SilentPaymentAddress, Error as SpError, }; -use sdk_common::{js_sys::{Object, Reflect, Uint8Array}, signature, MutexExt, MAX_PRD_PAYLOAD_SIZE}; +use js_sys::{Object, Reflect, Uint8Array}; +use sdk_common::{signature, MutexExt, MAX_PRD_PAYLOAD_SIZE}; use serde_json::{json, Error as SerdeJsonError, Map, Value}; use serde::{de, Deserialize, Serialize}; @@ -73,7 +74,7 @@ use sdk_common::sp_client::{FeeRate, OutputSpendStatus, OwnedOutput, Recipient, use sdk_common::secrets::SecretsStore; use crate::user::{lock_local_device, set_new_device, LOCAL_DEVICE}; -use crate::wallet::{generate_sp_wallet, lock_freezed_utxos, scan_blocks}; +use crate::wallet::{generate_sp_wallet, lock_freezed_utxos}; const EMPTYSTATEID: &str = "0000000000000000000000000000000000000000000000000000000000000000"; @@ -692,7 +693,7 @@ fn handle_prd_connect(prd: Prd, secret: AnkSharedSecretHash) -> AnyhowResult AnyhowResult ApiResult { } fn get_shared_secrets_in_transaction( - unsigned_transaction: &SilentPaymentUnsignedTransaction, + unsigned_transaction: &SilentPaymentUnsignedTransaction, sp_addresses: &[SilentPaymentAddress] ) -> anyhow::Result> { let mut new_secrets = HashMap::new(); @@ -1036,8 +1037,8 @@ fn get_shared_secrets_in_transaction( fn create_transaction_for_addresses( device: &Device, - freezed_utxos: &HashSet, - sp_addresses: &[SilentPaymentAddress], + freezed_utxos: &HashSet, + sp_addresses: &[SilentPaymentAddress], fee_rate: FeeRate ) -> anyhow::Result { let mut recipients = Vec::with_capacity(sp_addresses.len()); @@ -1080,7 +1081,7 @@ fn create_transaction_for_addresses( /// We send a transaction that pays at least one output to each address /// The goal can be to establish a shared_secret to be used as an encryption key for further communication /// or if the recipient is a relay it can be the init transaction for a new process -pub fn create_transaction(addresses: Vec, fee_rate: u32) -> ApiResult { +pub fn create_transaction(addresses: Vec, fee_rate: u32) -> ApiResult { if addresses.is_empty() { return Err(ApiError::new("No addresses to connect to".to_owned())); } @@ -1207,8 +1208,8 @@ pub fn create_new_process( } let commit_msg = CommitMessage::new( - process_id, - pcd_commitment, + process_id, + pcd_commitment, roles, public_data, vec![], @@ -1250,8 +1251,8 @@ pub fn update_process( } let mut new_state = ProcessState::new( - process.get_process_tip()?, - new_attributes.clone(), + process.get_process_tip()?, + new_attributes.clone(), prev_public_data, roles.clone() )?; @@ -1303,8 +1304,8 @@ pub fn update_process( }; let commit_msg = CommitMessage::new( - process_id, - new_state.pcd_commitment, + process_id, + new_state.pcd_commitment, roles, new_state.public_data, vec![] @@ -1353,8 +1354,8 @@ pub fn request_data(process_id: String, state_ids_str: Vec, roles: JsVal } let prd_request = Prd::new_request( - process_id, - members_list.0.get(&sender_pairing_id).unwrap().clone(), + process_id, + members_list.0.get(&sender_pairing_id).unwrap().clone(), state_ids ); @@ -1409,7 +1410,7 @@ pub fn create_update_message( }; // Check that we have a shared_secret with all members if let Some(no_secret_address) = member.get_addresses().iter() - .find(|a| shared_secrets.get_secret_for_address(a.as_str().try_into().unwrap()).is_none()) + .find(|a| shared_secrets.get_secret_for_address(a.as_str().try_into().unwrap()).is_none()) { // We ignore it if we don't have a secret with ourselves if *no_secret_address != local_address { @@ -1485,8 +1486,8 @@ pub fn evaluate_state(process: Process, state_id: String, members_list: OutPoint // We create a commit msg with the valid state let commit_msg = CommitMessage::new( - process_id, - process_state.pcd_commitment.clone(), + process_id, + process_state.pcd_commitment.clone(), process_state.roles.clone(), process_state.public_data.clone(), vec![] @@ -1518,7 +1519,7 @@ fn add_validation_token(mut process: Process, state_id: String, approval: bool, let mut commit_msg = CommitMessage::new( process_id, - update_state.pcd_commitment.clone(), + update_state.pcd_commitment.clone(), update_state.roles.clone(), update_state.public_data.clone(), update_state.validation_tokens.clone() @@ -1576,7 +1577,7 @@ fn new_response_prd(process_id: OutPoint, update_state: &ProcessState, members_l }; // Check that we have a shared_secret with all members if let Some(no_secret_address) = member.get_addresses().iter() - .find(|a| shared_secrets.get_secret_for_address(a.as_str().try_into().unwrap()).is_none()) + .find(|a| shared_secrets.get_secret_for_address(a.as_str().try_into().unwrap()).is_none()) { // We ignore it if we don't have a secret with ourselves if *no_secret_address != local_address { @@ -1601,7 +1602,7 @@ fn new_response_prd(process_id: OutPoint, update_state: &ProcessState, members_l let response_prd = Prd::new_response( process_id, sender, - vec![*proof], + vec![*proof], update_state.pcd_commitment.clone(), ); let prd_msg = response_prd.to_network_msg(local_device.get_sp_client())?; @@ -1650,7 +1651,7 @@ pub fn create_faucet_msg() -> ApiResult { #[wasm_bindgen] pub fn get_storages(process_outpoint: String) -> ApiResult> { let outpoint = OutPoint::from_str(&process_outpoint)?; - + Ok(vec![]) } @@ -1753,15 +1754,15 @@ pub struct MerkleProofResult { #[wasm_bindgen] /// Generate a merkle proof for a specific attribute in a process state. -/// +/// /// This function creates a merkle proof that proves the existence of a specific attribute /// in a given state of a process. The proof can be used to verify that the attribute /// was indeed part of the state without revealing the entire state. -/// +/// /// # Arguments /// * `process_state` - The process state object as a JavaScript value /// * `attribute_name` - The name of the attribute to generate a proof for -/// +/// /// # Returns /// A MerkleProofResult object containing: /// * `proof` - The merkle proof as a hex string @@ -1769,7 +1770,7 @@ pub struct MerkleProofResult { /// * `attribute` - The attribute name that was proven /// * `attribute_index` - The index of the attribute in the merkle tree /// * `total_leaves_count` - The total number of leaves in the merkle tree -/// +/// /// # Errors /// * "Failed to deserialize process state" - If the process state cannot be deserialized from JsValue /// * "Attribute not found in state" - If the attribute doesn't exist in the state @@ -1777,21 +1778,21 @@ pub fn get_merkle_proof(process_state: JsValue, attribute_name: String) -> ApiRe // Deserialize the process state from JsValue let state: ProcessState = serde_wasm_bindgen::from_value(process_state) .map_err(|_| ApiError::new("Failed to deserialize process state".to_owned()))?; - + // Create merkle tree from the PCD commitments let merkle_tree = state.pcd_commitment.create_merkle_tree()?; - + // Find the index of the attribute in the commitments let attribute_index = state.pcd_commitment.find_index_of(&attribute_name) .ok_or(ApiError::new("Attribute not found in state".to_owned()))?; // Generate the merkle proof for the attribute let proof = merkle_tree.proof(&[attribute_index]); - + // Convert the proof to a format that can be serialized to JavaScript let proof_bytes = proof.to_bytes(); let proof_hex = proof_bytes.to_lower_hex_string(); - + Ok(MerkleProofResult { proof: proof_hex, root: state.state_id.to_lower_hex_string(), @@ -1803,18 +1804,18 @@ pub fn get_merkle_proof(process_state: JsValue, attribute_name: String) -> ApiRe #[wasm_bindgen] /// Validate a merkle proof for a specific attribute. -/// +/// /// This function verifies that a merkle proof is valid and proves the existence /// of a specific attribute in a given state. It checks that the proof correctly /// leads to the claimed root when combined with the attribute hash. -/// +/// /// # Arguments /// * `proof_result` - a JsValue expected to contain a MerkleProofResult with the proof and metadata /// * `hash` - The hash of the attribute data as a hex string (the leaf value) -/// +/// /// # Returns /// A boolean indicating whether the proof is valid -/// +/// /// # Errors /// * "serde_wasm_bindgen deserialization error" - If the proof is not a valid MerkleProofResult /// * "Invalid proof format" - If the proof cannot be parsed @@ -1825,7 +1826,7 @@ pub fn validate_merkle_proof(proof_result: JsValue, hash: String) -> ApiResult ApiResult