# Architecture du Système de Processus et Updates

## Vue d'ensemble

Le système de processus est un **système générique et réutilisable** pour créer des "contrats" entre des membres avec des niveaux d'accès différents aux champs de données. C'est la fondation qui permet d'implémenter des fonctionnalités comme le pairing, mais aussi n'importe quel autre type de contrat décentralisé.

## Concepts Fondamentaux

### 1. Processus (Process)

Un **processus** est un contrat décentralisé entre plusieurs membres, commité sur la blockchain. Il représente un accord ou une entité partagée avec :

- **Identifiant unique** : `process_id`
- **États successifs** : Historique des modifications
- **Membres** : Participants au processus
- **Rôles et permissions** : Définition des accès

### 2. État (State)

Chaque processus contient une liste d'**états** représentant l'évolution du processus dans le temps. Chaque état contient :

#### Données Publiques (`public_data`)
- **Accessibles à tous** les membres du processus
- **Inchangées** dans tous les nouveaux états (portées automatiquement)
- **Encodées** mais non chiffrées (encodage JSON/Binary)
- **Exemple** : Nom du processus, adresses appairées, métadonnées

#### Données Privées (via `pcd_commitment`)
- **Chiffrées** et accessibles uniquement aux membres autorisés
- **Commitment** : Hash des données privées (`pcd_commitment[field]`)
- **Clés de déchiffrement** : Stockées dans `state.keys[field]` pour chaque membre autorisé
- **Exemple** : Secrets, clés privées, données sensibles

#### Rôles (`roles`)
- **Définition des permissions** par rôle
- **Validation rules** : Quorum et champs accessibles par rôle
- **Membres** : Liste des IDs de pairing process pour chaque rôle

#### Métadonnées d'État
- `state_id` : Identifiant unique de l'état
- `validation_tokens` : Tokens nécessaires pour la validation
- `validation_result` : Résultat de la validation

### 3. Rôles et Permissions (`RoleDefinition`)

Un rôle définit qui peut accéder à quels champs et comment :

```typescript
interface RoleDefinition {
  members: string[];              // IDs de pairing process (identifiants des membres)
  validation_rules: ValidationRule[];  // Règles de validation
}

interface ValidationRule {
  quorum: number;                 // Quorum requis (ex: 1.0 = tous, 0.5 = 50%)
  fields: string[];                // Champs accessibles pour ce rôle
}
```

**Exemples de rôles** :
- **Administrateur** : Quorum 1.0, accès à tous les champs
- **Membre** : Quorum 0.5, accès aux champs non critiques
- **Lecteur** : Quorum 0, accès en lecture seule aux champs publics

### 4. Membres

Les membres sont identifiés par leur **pairing process ID** (l'identité numérique vérifiable créée lors du pairing).

- Un membre peut participer à plusieurs processus
- Un processus peut avoir plusieurs membres
- Les adresses SP (Silent Payment) sont associées aux membres pour la communication

## Cycle de Vie d'un Processus

### Phase 1 : Création

```typescript
createProcess(
  privateData: Record<string, any>,    // Données privées initiales
  publicData: Record<string, any>,      // Données publiques initiales
  roles: Record<string, RoleDefinition>  // Définition des rôles
): Promise<ApiReturn>
```

**Étapes** :
1. Encodage des données (JSON/Binary)
2. Création du processus via SDK (WebAssembly)
3. Génération du premier état (state 0)
4. Établissement des connexions avec les membres

### Phase 2 : Mise à Jour

```typescript
updateProcess(
  process: Process,
  privateData: Record<string, any>,    // Nouvelles données privées
  publicData: Record<string, any>,      // Nouvelles données publiques
  roles: Record<string, RoleDefinition> | null  // Nouveaux rôles (optionnel)
): Promise<ApiReturn>
```

**Logique de classification des champs** :

Le système détermine automatiquement si un champ est public ou privé :

1. **Champ existant dans `public_data`** → Reste public
2. **Champ nouveau dans `privateFields`** → Privé
3. **Champ existant dans `pcd_commitment`** → Reste privé
4. **Sinon** → Nouveau champ public

```typescript
// Logique dans handleUpdateProcess (router.ts:811-846)
for (const field of Object.keys(newData)) {
  // 1. Vérifier si c'est déjà public
  if (lastState.public_data[field]) {
    publicData[field] = newData[field];
    continue;
  }

  // 2. Vérifier si c'est un nouveau champ privé
  if (privateFields.includes(field)) {
    privateData[field] = newData[field];
    continue;
  }

  // 3. Vérifier si c'était privé dans un état précédent
  for (let i = lastStateIndex; i >= 0; i--) {
    if (process.states[i].pcd_commitment[field]) {
      privateData[field] = newData[field];
      break;
    }
  }

  // 4. Sinon, c'est un nouveau champ public
  if (!privateData[field]) {
    publicData[field] = newData[field];
  }
}
```

### Phase 3 : Synchronisation (PRD Update)

**PRD** = Private Data Relay

```typescript
createPrdUpdate(
  processId: string,
  stateId: string
): Promise<ApiReturn>
```

**Objectif** :
- Synchroniser les **clés de déchiffrement** des données privées avec tous les membres autorisés
- Distribuer les données privées aux membres qui ont les permissions
- Mettre à jour les `state.keys[field]` pour chaque membre autorisé

**Processus** :
1. Création d'un message de mise à jour PRD
2. Transmission via les relais aux membres autorisés
3. Chaque membre reçoit les clés pour les champs auxquels il a accès

### Phase 4 : Validation (Approbation)

```typescript
approveChange(
  processId: string,
  stateId: string
): Promise<ApiReturn>
```

**Objectif** :
- Valider un état du processus selon le **quorum requis**
- S'assurer que suffisamment de membres ont approuvé le changement
- Marquer l'état comme validé

**Quorum** :
- Si quorum = 1.0 → Tous les membres du rôle doivent approuver
- Si quorum = 0.5 → 50% des membres doivent approuver
- Si quorum = 0 → Auto-approbation (pas de validation requise)

### Phase 5 : Commit sur Blockchain

Une fois validé, l'état est **committé sur la blockchain** :

- Création d'une transaction Bitcoin commitant l'état
- Le `pcd_commitment` est inclut dans la transaction
- L'état devient **immuable** et vérifiable

### Phase 6 : Accès aux Données

#### Données Publiques

Accessibles directement depuis `state.public_data` après décodage :

```typescript
const publicData = service.getPublicData(process);
const decodedValue = service.decodeValue(publicData['fieldName']);
```

#### Données Privées

Nécessitent :
1. **Permission** : Vérifier que le membre a accès au champ
2. **Clé de déchiffrement** : Récupérer `state.keys[field]`
3. **Commitment** : Vérifier `state.pcd_commitment[field]`
4. **Déchiffrement** : Décrypter avec la clé

```typescript
async decryptAttribute(
  processId: string,
  state: ProcessState,
  attribute: string
): Promise<any | null>
```

**Vérification des permissions** :
```typescript
// Vérifier si le membre a accès au champ
for (const role of Object.values(state.roles)) {
  for (const rule of Object.values(role.validation_rules)) {
    if (rule.fields.includes(attribute)) {
      if (role.members.includes(pairingProcessId)) {
        // Le membre a accès
      }
    }
  }
}
```

Si la clé est manquante, le système demande automatiquement aux autres membres via `requestDataFromPeers()`.

## Flux Complet d'un Update

```
1. Mise à jour demandée
   ↓
2. Classification automatique des champs (public/privé)
   ↓
3. updateProcess() → Création d'un nouvel état
   ↓
4. createPrdUpdate() → Synchronisation des clés privées
   ↓
5. approveChange() → Validation selon quorum
   ↓
6. Commit sur blockchain → État immuable
   ↓
7. Accès aux données via getPublicData() / decryptAttribute()
```

## Exemples d'Utilisation

### Exemple 1 : Pairing (Identité Multi-Appareils)

```typescript
// Création d'un processus de pairing
const pairingProcess = await service.createPairingProcess(
  '',                           // memberPublicName (vide pour pairing)
  [creatorAddress]              // pairedAddresses (liste des appareils)
);

// Données publiques : Liste des adresses appairées
// Données privées : Secrets Silent Payment partagés
// Rôles : Tous les appareils ont le même niveau d'accès (quorum 1.0)
```

### Exemple 2 : Contrat de Partage avec Niveaux d'Accès

```typescript
// Création d'un contrat avec différents niveaux
const contract = await service.createProcess(
  {
    secretKey: '...',           // Privé : Clé secrète
    internalNotes: '...'        // Privé : Notes internes
  },
  {
    contractName: 'Mon Contrat',  // Public : Nom
    description: '...'             // Public : Description
  },
  {
    admin: {
      members: [adminPairingId],
      validation_rules: [
        { quorum: 1.0, fields: ['secretKey', 'internalNotes', 'contractName'] }
      ]
    },
    member: {
      members: [memberPairingId1, memberPairingId2],
      validation_rules: [
        { quorum: 0.5, fields: ['contractName', 'description'] }  // Lecture seule des publics
      ]
    }
  }
);
```

### Exemple 3 : Vote Décisionnel

```typescript
const voteProcess = await service.createProcess(
  {
    votes: {}                   // Privé : Votes individuels
  },
  {
    proposal: 'Proposition...',  // Public : Proposition
    result: null                 // Public : Résultat
  },
  {
    voter: {
      members: [...voterIds],
      validation_rules: [
        { quorum: 0.5, fields: ['votes'] }  // 50% des votants doivent valider
      ]
    }
  }
);
```

## Points Importants

### 1. Immutabilité

Une fois qu'un état est **committé**, il devient immuable. Les nouveaux états ajoutent des modifications mais ne modifient jamais les états précédents.

### 2. Portage des Données Publiques

Les données publiques sont **automatiquement portées** dans chaque nouvel état. Pas besoin de les réenvoyer à chaque update.

### 3. Synchronisation Automatique

Le système gère automatiquement la **distribution des clés privées** aux membres autorisés via les relais.

### 4. Quorum Flexible

Le système supporte différents niveaux de quorum selon les besoins :
- **Sécurisé** : Quorum 1.0 (tous doivent approuver)
- **Démocratique** : Quorum 0.5 (majorité)
- **Auto** : Quorum 0 (auto-approbation)

### 5. Extensibilité

Ce système peut être utilisé pour **n'importe quel type de contrat** :
- Gestion documentaire
- Votes décisionnels
- Partage de fichiers
- Contrats intelligents décentralisés
- etc.

## Méthodes Utilitaires

### Récupération des Processus

```typescript
// Récupérer un processus spécifique
getProcess(processId: string): Promise<Process | null>

// Récupérer tous les processus
getProcesses(): Promise<Record<string, Process>>

// Récupérer mes processus (où je suis membre)
getMyProcesses(): Promise<string[] | null>
```

### État Commité

```typescript
// Récupérer le dernier état commité
getLastCommitedState(process: Process): ProcessState | null

// Récupérer l'index du dernier état commité
getLastCommitedStateIndex(process: Process): number | null
```

**Important** : Les états non commités sont des "pending states" qui attendent validation.

### Rôles et Membres

```typescript
// Récupérer les rôles d'un processus (depuis le dernier état commité)
getRoles(process: Process): Record<string, RoleDefinition> | null

// Vérifier si je suis membre d'un processus
rolesContainsUs(roles: Record<string, RoleDefinition>): boolean

// Vérifier si un membre spécifique fait partie des rôles
rolesContainsMember(roles: Record<string, RoleDefinition>, pairingProcessId: string): boolean

// Récupérer tous les membres connus
getAllMembers(): Record<string, Member>
```

### Données Publiques

```typescript
// Récupérer les données publiques (depuis le dernier état commité)
getPublicData(process: Process): Record<string, any> | null

// Décoder une valeur encodée
decodeValue(value: number[]): any | null
```

### Données Privées

```typescript
// Déchiffrer un attribut privé
async decryptAttribute(
  processId: string,
  state: ProcessState,
  attribute: string
): Promise<any | null>
```

Cette méthode :
1. Vérifie les permissions (rôles)
2. Récupère la clé de déchiffrement (`state.keys[attribute]`)
3. Demande aux autres membres si la clé est manquante
4. Déchiffre la donnée

## Gestion du Cache et Synchronisation

### Cache des Processus

Les processus sont mis en cache localement pour améliorer les performances :

```typescript
processesCache: Record<string, Process>
```

### Synchronisation avec les Relais

Les relais synchronisent :
- Les nouveaux processus
- Les mises à jour d'états
- Les clés privées (PRD updates)
- Les validations

### Connexion entre Membres

Avant de créer ou mettre à jour un processus, le système établit des **connexions** (secrets partagés) entre tous les membres :

```typescript
checkConnections(process: Process, stateId?: string): Promise<void>
```

Cela crée des secrets Silent Payment entre les membres pour permettre la communication chiffrée.

## Avantages du Système

1. **Décentralisé** : Pas de tiers de confiance, tout sur la blockchain
2. **Vérifiable** : Chaque état est commité et vérifiable
3. **Flexible** : Permissions granulaires par champ et par rôle
4. **Sécurisé** : Chiffrement des données privées, distribution via relais
5. **Générique** : Réutilisable pour n'importe quel type de contrat
6. **Sans tiers** : Les utilisateurs contrôlent leurs propres processus

## Cas d'Usage Avancés

### Gestion Documentaire Collaborative

```typescript
const documentProcess = await service.createProcess(
  {
    documentContent: encryptedContent,  // Privé : Contenu chiffré
    versionHistory: []                    // Privé : Historique des versions
  },
  {
    documentTitle: 'Document Important',  // Public : Titre
    lastModified: timestamp,               // Public : Dernière modification
    author: authorAddress                  // Public : Auteur
  },
  {
    owner: {
      members: [ownerPairingId],
      validation_rules: [
        { quorum: 1.0, fields: ['documentContent', 'documentTitle'] }
      ]
    },
    editor: {
      members: [...editorPairingIds],
      validation_rules: [
        { quorum: 0.5, fields: ['documentContent'] }  // 50% des éditeurs doivent valider
      ]
    },
    viewer: {
      members: [...viewerPairingIds],
      validation_rules: [
        { quorum: 0, fields: ['documentTitle'] }  // Lecture seule, pas de validation
      ]
    }
  }
);
```

### Système de Votation

```typescript
const votingProcess = await service.createProcess(
  {
    votes: {},                    // Privé : Votes individuels
    voterIds: []                 // Privé : Liste des votants
  },
  {
    question: 'Question...',     // Public : Question
    options: ['A', 'B', 'C'],    // Public : Options
    deadline: timestamp,          // Public : Deadline
    result: null                  // Public : Résultat (mis à jour après)
  },
  {
    voter: {
      members: [...allVoterIds],
      validation_rules: [
        { quorum: 0.5, fields: ['votes'] }  // 50% des votants doivent valider
      ]
    },
    organizer: {
      members: [organizerPairingId],
      validation_rules: [
        { quorum: 1.0, fields: ['question', 'options', 'deadline', 'result'] }
      ]
    }
  }
);
```

### Contrat Intelligent Décentralisé

Le système peut implémenter n'importe quel type de contrat intelligent décentralisé avec :
- Conditions de validation personnalisées (quorum)
- Permissions granulaires par champ
- Audit trail complet (historique des états)
- Vérifiabilité sur la blockchain