diff --git a/docs/4NK_IDENTITY_AND_PROCESS_SPEC.md b/docs/4NK_IDENTITY_AND_PROCESS_SPEC.md index 473222a..56b4713 100644 --- a/docs/4NK_IDENTITY_AND_PROCESS_SPEC.md +++ b/docs/4NK_IDENTITY_AND_PROCESS_SPEC.md @@ -2,7 +2,8 @@ **Version:** 1.0 **Date:** 1 octobre 2025 -**Auteur:** Analyse complète des composants sdk_client, sdk_common, sdk_relay, sdk_storage, ihm_client, rust-silentPayments +**Auteur:** Nicolas Cantu +**Description:** Analyse complète des composants sdk_client, sdk_common, sdk_relay, sdk_storage, ihm_client, rust-silentPayments ## Table des matières @@ -21,16 +22,16 @@ ### 1.1 Philosophie du système -4NK est un système décentralisé de gestion de processus collaboratifs basé sur la blockchain Bitcoin, utilisant les **Silent Payments (BIP352)** pour l'identité et le chiffrement. Le système permet à plusieurs parties de collaborer sur des processus avec des états vérifiables, des rôles définis et des règles de validation cryptographiques. +4NK est un système décentralisé de gestion de processus collaboratifs basé sur la blockchain Bitcoin, utilisant **Silent Payments ([BIP352](https://bips.dev/352/))** pour l'identité et le partage de secrets de chiffrement. Le système permet à plusieurs parties de collaborer sur des processus dont les états successifs sont vérifiables, avec des permissions (lecture, modification) granulaires définies pour différents rôles et utilisateurs. ### 1.2 Principes fondamentaux - **Identité décentralisée** : Basée sur des adresses Silent Payment Bitcoin - **Device-centric** : Chaque appareil possède sa propre clé cryptographique - **Multi-device** : Un utilisateur peut gérer plusieurs appareils via le pairing -- **Processus à états** : Évolution contrôlée par des commitments Bitcoin -- **Validation distribuée** : Signatures cryptographiques multiples requises -- **Communication P2P** : Relais WebSocket pour synchronisation temps réel +- **Processus à états** : Évolution contrôlée par des commitments dans des transactions Bitcoin +- **Validation distribuée** : Signatures cryptographiques multiples requises pour chaque changement d'état +- **Tout dans le browser** : Connexions WebSocket avec des relais pour synchronisation temps réel ### 1.3 Composants principaux @@ -80,7 +81,7 @@ pub struct Device { 2. **Pairing** : `device.pair(commitment_outpoint, member)` - Associe le device à un processus de pairing - - Lie plusieurs adresses Silent Payment ensemble + - D'autres adresses Silent Payment peuvent être ajoutées à ce processus 3. **Unpairing** : `device.unpair()` - Réinitialise à l'état local unique @@ -195,14 +196,14 @@ Un **Process** est une machine à états distribuée, commitée sur la blockchai ``` Process └─ states: Vec - ├─ State 0 (initial empty) - ├─ State 1 (premier commit) - ├─ State 2 (update) + ├─ State 0 (premier commit) + ├─ State 1 (update 1) + ├─ State 2 (update 2) ├─ ... - └─ State n (dernier = toujours empty) + └─ State n (dernier = toujours vide) ``` -**Règle fondamentale:** Le dernier état est toujours vide, représentant le prochain UTXO à dépenser. +**Règle fondamentale:** Le dernier état est toujours vide, représentant le prochain UTXO à dépenser. Cela permet d'annoncer publiquement et sans équivoque où se trouvera le prochain état valide de notre processus, voir le principe du [single-use seal](https://docs.rgb.info/distributed-computing-concepts/single-use-seals) ### 3.2 Structure `ProcessState` @@ -224,13 +225,13 @@ pub struct ProcessState { 1. **`commited_in`** : UTXO Bitcoin qui "porte" cet état - Permet de lier l'état à la blockchain - - Forme l'identifiant du processus (premier `commited_in`) + - Forme l'identifiant du processus (`commited_in` du 1er `ProcessState`) -2. **`pcd_commitment`** : Commitments Merkle des données privées - - Map `field_name -> hash(compressed_value)` - - Hash taggé: `AnkPcdHash::from_pcd_value(data, field, outpoint)` +2. **`pcd_commitment`** : Map contenant en clé le nom des attributs contenu dans l'état (privés + publics yc `roles`) et en valeur le sha256 de la donnée + - Map `field_name -> hash(compressed_value)` La donnée est compressée avant d'être hashé + - Hash taggé: `AnkPcdHash::from_pcd_value(data, field, outpoint)` Le hash contient en plus de la donnée le nom de l'attribut (deux attributs différents avec la même valeur ont ainsi 2 hash différents) ainsi que l'outpoint (la même valeur sur 2 commitments successifs produira 2 hashs différents aussi) -3. **`state_id`** : Racine Merkle de tous les commitments + rôles +3. **`state_id`** : Racine de Merkle de tous les commitments - Identifiant unique de l'état - Utilisé pour les signatures de validation @@ -239,12 +240,13 @@ pub struct ProcessState { - Type: `Proof` (signature Schnorr sur `state_id`) 5. **`public_data`** : Données non chiffrées - - Lisibles par tous les participants + - Lisibles par tous les participants, yc ceux qui ne font pas partie du processus - Exemple: `"pairedAddresses"` pour le pairing 6. **`roles`** : Définition des rôles et permissions - Map `role_name -> RoleDefinition` - Contrôle qui peut modifier quels champs + - Information publique (Cela permet à n'importe qui de valider un processus même sans en faire partie) ### 3.3 Cycle de vie d'un processus @@ -321,13 +323,13 @@ fn remove_all_concurrent_states(&mut self) -> Vec - **Rôle:** `"pairing"` - **Champ public:** `"pairedAddresses"` -- **Règle:** Membres vides, validation par adresses existantes +- **Règle:** Membres vides, les adresses sont contenues dans `pairedAddresses` #### 3.5.2 Oblitération (Termination) - **État:** `state_id = [0u8; 32]` - **Rôle:** `"apophis"` (défini dans l'état précédent) -- **Effet:** Termine définitivement le processus +- **Effet:** Termine définitivement le processus (Plus possible d'ajouter des états supplémentaires) - **Fichier:** `sdk_common/src/process.rs` (lignes 133-159) ```rust @@ -352,6 +354,7 @@ fn handle_obliteration(&self, apophis: &RoleDefinition, members_list: &OutPointM ValidationRule::new(1.0, all_keys, 1.0) ``` - **Fichier:** `sdk_common/src/process.rs` (lignes 103-130) +- **Commentaire:** Ce rôle peut être utile si l'une des parties prenantes doit initialiser le processus sans cependant avoir un rôle qui lui donne toutes les autorisations nécessaires. Ce rôle est ensuite ignoré dans les commitments suivants et peut être retiré si nécessaire. --- @@ -385,15 +388,15 @@ pub struct RoleDefinition { **Caractéristiques:** -- **members** : Utilise des `OutPoint` (process IDs) plutôt que des adresses - - Permet d'ajouter des devices sans modifier les rôles +- **members** : Utilise des `OutPoint` (IDs des processus de pairing) plutôt que des adresses + - Permet de modifier les devices d'un membre sans modifier les rôles dans tous les processus auxquels il prend part - Résolu via `OutPointMemberMap` au moment de la validation -- **validation_rules** : Définit quels champs peuvent être modifiés - - Quorum requis - - Signatures minimales par membre +- **validation_rules** : Définissent quels champs peuvent être modifiés + - Quorum requis (n/total membres dans le rôle) + - Signatures minimales par membre (n/total de devices enregistrés par membre) -- **storages** : Liste des storages où les données peuvent être déposées +- **storages** : Liste d'url des storages où les données peuvent être déposées ### 4.3 Structure `ValidationRule` @@ -410,7 +413,7 @@ pub struct ValidationRule { **Exemple concret:** ```rust -// Règle : 50% des membres, chacun avec au moins 1 device +// Règle : 50% des membres, chacun avec au moins la moitié de leurs devices enregistrés ValidationRule { quorum: 0.5, fields: vec!["contract".to_string(), "amount".to_string()], @@ -420,7 +423,7 @@ ValidationRule { **Interprétation:** - 50% des membres du rôle doivent approuver -- Chaque membre approuvant doit fournir au moins 50% de ses devices +- Chaque membre approuvant doit signer avec au moins 50% de ses devices pairés - S'applique aux modifications de `"contract"` et `"amount"` ### 4.4 Processus de validation @@ -639,7 +642,7 @@ pub enum AnkFlag { NewTx, // Nouvelle transaction détectée Cipher, // Données chiffrées Commit, // Demande de commit on-chain - Faucet, // Demande de fonds (testnet) + Faucet, // Demande de fonds Sync, // Synchronisation d'état } ``` @@ -857,7 +860,7 @@ pub struct RoleDefinition { **Cas d'usage:** 1. **Données chiffrées volumineuses** : Documents, images -2. **Partage de clés** : Clés de déchiffrement AES +2. **Partage de clés** : Clés de déchiffrement AES 3. **Coordination** : États temporaires avant commit ### 6.3 Données sur blockchain