4nk/4NK_env
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs/4NK_IDENTITY_AND_PROCESS_SPEC.md

Browse Source 
First reading, add some details and fixed some mistakes/typos
This commit is contained in:
sosthene 2025-10-02 09:24:02 +00:00
parent 7222ae6fbc
commit a3269e67e9
1 changed files with 32 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/4NK_IDENTITY_AND_PROCESS_SPEC.md
View File

@ -2,7 +2,8 @@
**Version:** 1.0 **Version:** 1.0
**Date:** 1 octobre 2025 **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 ## Table des matières
@ -21,16 +22,16 @@
### 1.1 Philosophie du système ### 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 ### 1.2 Principes fondamentaux
- **Identité décentralisée** : Basée sur des adresses Silent Payment Bitcoin - **Identité décentralisée** : Basée sur des adresses Silent Payment Bitcoin
- **Device-centric** : Chaque appareil possède sa propre clé cryptographique - **Device-centric** : Chaque appareil possède sa propre clé cryptographique
- **Multi-device** : Un utilisateur peut gérer plusieurs appareils via le pairing - **Multi-device** : Un utilisateur peut gérer plusieurs appareils via le pairing
- **Processus à états** : Évolution contrôlée par des commitments Bitcoin - **Processus à états** : Évolution contrôlée par des commitments dans des transactions Bitcoin
- **Validation distribuée** : Signatures cryptographiques multiples requises - **Validation distribuée** : Signatures cryptographiques multiples requises pour chaque changement d'état
- **Communication P2P** : Relais WebSocket pour synchronisation temps réel - **Tout dans le browser** : Connexions WebSocket avec des relais pour synchronisation temps réel
### 1.3 Composants principaux ### 1.3 Composants principaux
@ -80,7 +81,7 @@ pub struct Device {
2. **Pairing** : `device.pair(commitment_outpoint, member)` 2. **Pairing** : `device.pair(commitment_outpoint, member)`
- Associe le device à un processus de pairing - 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()` 3. **Unpairing** : `device.unpair()`
- Réinitialise à l'état local unique - Réinitialise à l'état local unique
@ -195,14 +196,14 @@ Un **Process** est une machine à états distribuée, commitée sur la blockchai
``` ```
Process Process
└─ states: Vec<ProcessState> └─ states: Vec<ProcessState>
├─ State 0 (initial empty) ├─ State 0 (premier commit)
├─ State 1 (premier commit) ├─ State 1 (update 1)
├─ State 2 (update) ├─ 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` ### 3.2 Structure `ProcessState`
@ -224,13 +225,13 @@ pub struct ProcessState {
1. **`commited_in`** : UTXO Bitcoin qui "porte" cet état 1. **`commited_in`** : UTXO Bitcoin qui "porte" cet état
- Permet de lier l'état à la blockchain - 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 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)` - 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)` - 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 - Identifiant unique de l'état
- Utilisé pour les signatures de validation - Utilisé pour les signatures de validation
@ -239,12 +240,13 @@ pub struct ProcessState {
- Type: `Proof` (signature Schnorr sur `state_id`) - Type: `Proof` (signature Schnorr sur `state_id`)
5. **`public_data`** : Données non chiffrées 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 - Exemple: `"pairedAddresses"` pour le pairing
6. **`roles`** : Définition des rôles et permissions 6. **`roles`** : Définition des rôles et permissions
- Map `role_name -> RoleDefinition` - Map `role_name -> RoleDefinition`
- Contrôle qui peut modifier quels champs - 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 ### 3.3 Cycle de vie d'un processus
@ -321,13 +323,13 @@ fn remove_all_concurrent_states(&mut self) -> Vec<ProcessState>
- **Rôle:** `"pairing"` - **Rôle:** `"pairing"`
- **Champ public:** `"pairedAddresses"` - **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) #### 3.5.2 Oblitération (Termination)
- **État:** `state_id = [0u8; 32]` - **État:** `state_id = [0u8; 32]`
- **Rôle:** `"apophis"` (défini dans l'état précédent) - **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) - **Fichier:** `sdk_common/src/process.rs` (lignes 133-159)
```rust ```rust
@ -352,6 +354,7 @@ fn handle_obliteration(&self, apophis: &RoleDefinition, members_list: &OutPointM
ValidationRule::new(1.0, all_keys, 1.0) ValidationRule::new(1.0, all_keys, 1.0)
``` ```
- **Fichier:** `sdk_common/src/process.rs` (lignes 103-130) - **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:** **Caractéristiques:**
- **members** : Utilise des `OutPoint` (process IDs) plutôt que des adresses - **members** : Utilise des `OutPoint` (IDs des processus de pairing) plutôt que des adresses
- Permet d'ajouter des devices sans modifier les rôles - 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 - Résolu via `OutPointMemberMap` au moment de la validation
- **validation_rules** : Définit quels champs peuvent être modifiés - **validation_rules** : Définissent quels champs peuvent être modifiés
- Quorum requis - Quorum requis (n/total membres dans le rôle)
- Signatures minimales par membre - 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` ### 4.3 Structure `ValidationRule`
@ -410,7 +413,7 @@ pub struct ValidationRule {
**Exemple concret:** **Exemple concret:**
```rust ```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 { ValidationRule {
quorum: 0.5, quorum: 0.5,
fields: vec!["contract".to_string(), "amount".to_string()], fields: vec!["contract".to_string(), "amount".to_string()],
@ -420,7 +423,7 @@ ValidationRule {
**Interprétation:** **Interprétation:**
- 50% des membres du rôle doivent approuver - 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"` - S'applique aux modifications de `"contract"` et `"amount"`
### 4.4 Processus de validation ### 4.4 Processus de validation
@ -639,7 +642,7 @@ pub enum AnkFlag {
NewTx, // Nouvelle transaction détectée NewTx, // Nouvelle transaction détectée
Cipher, // Données chiffrées Cipher, // Données chiffrées
Commit, // Demande de commit on-chain Commit, // Demande de commit on-chain
Faucet, // Demande de fonds (testnet) Faucet, // Demande de fonds
Sync, // Synchronisation d'état Sync, // Synchronisation d'état
} }
``` ```