PD-245 — Plan d'implémentation¶

Story : PD-245 — Format de preuve multi-chain Epic : BLOCKCHAIN (PD-187) Complexité : Low Estimé : 4-6 heures Généré par : Claude (orchestrateur) Date : 2026-02-19

1. Vue d'ensemble¶

PD-245 amende le format de preuve individuelle ProbatioVault pour inclure un champ blockchain explicite. C'est un amendment de PD-39 (TSA RFC 3161) et un prérequis pour PD-58 (Tezos fallback).

1.1 Objectif technique¶

Ajouter un champ blockchain: BlockchainIdentifier à l'interface InclusionProof et implémenter la validation dans le vérificateur de preuves.

1.2 Changements requis¶

2. Découpage en composants¶

2.1 Module : blockchain-constants¶

Responsabilité : Définir les types et constantes blockchain

Contenu : - Type BlockchainIdentifier = 'ethereum_l2' | 'tezos' - Constante ACTIVE_BLOCKCHAINS: readonly BlockchainIdentifier[] - Fonction isBlockchainActive(blockchain: BlockchainIdentifier): boolean

Invariants couverts : INV-245-05

2.2 Module : proof-errors¶

Responsabilité : Définir les codes d'erreur de preuve

Contenu : - Constante INVALID_BLOCKCHAIN_IDENTIFIER = 'PROOF_001' - Constante BLOCKCHAIN_NOT_ACTIVE = 'PROOF_002' - Exception ProofValidationException avec structure de détails

Invariants couverts : INV-245-06

2.3 Module : inclusion-proof-interface¶

Responsabilité : Définir l'interface de preuve amendée

Changement : - Ajouter champ blockchain: BlockchainIdentifier (obligatoire) - Importer BlockchainIdentifier depuis blockchain.constants.ts

Invariants couverts : INV-245-01, INV-245-02

2.4 Module : proof-service¶

Responsabilité : Émettre des preuves avec blockchain explicite

Changement : - Injecter blockchain: 'ethereum_l2' dans toute preuve produite - Pas de logique conditionnelle (toujours ethereum_l2 jusqu'à PD-58)

Invariants couverts : INV-245-01, INV-245-04

2.5 Module : proof-verifier-service¶

Responsabilité : Valider les preuves avec champ blockchain

Changements : 1. Si blockchain absent → traiter comme 'ethereum_l2' (rétrocompat) 2. Si blockchain non-string/null/vide/casse incorrecte → PROOF_001 3. Si blockchain non dans enum → PROOF_001 4. Si blockchain dans enum mais non actif → PROOF_002 5. Si blockchain valide et actif → accepter

Invariants couverts : INV-245-02, INV-245-03, INV-245-05, INV-245-06

3. Ordre d'implémentation¶

3bis. Diagrammes Mermaid¶

3bis.1 Graphe de dépendances des tâches¶

graph TD
    T01["T01: blockchain-constants<br/><i>blockchain.constants.ts</i>"]
    T02["T02: proof-errors<br/><i>proof.errors.ts</i>"]
    T03["T03: inclusion-proof-interface<br/><i>inclusion-proof.interface.ts</i>"]
    T04["T04: proof-service<br/><i>proof.service.ts</i>"]
    T05["T05: proof-verifier-service<br/><i>proof-verifier.service.ts</i>"]
    T06["T06: Tests unitaires"]

    T01 --> T03
    T01 --> T04
    T01 --> T05
    T02 --> T05
    T03 --> T04
    T03 --> T05
    T04 --> T06
    T05 --> T06

    style T01 fill:#e1f5fe
    style T02 fill:#e1f5fe
    style T03 fill:#fff3e0
    style T04 fill:#e8f5e9
    style T05 fill:#e8f5e9
    style T06 fill:#f3e5f5

3bis.2 Diagramme de séquence — Émission et vérification de preuve¶

sequenceDiagram
    participant Client
    participant ProofService as proof.service.ts
    participant Constants as blockchain.constants.ts
    participant Verifier as proof-verifier.service.ts
    participant Errors as proof.errors.ts

    Note over Client,Errors: Flux d'émission (proof.service)
    Client->>ProofService: createProof(data)
    ProofService->>Constants: blockchain = 'ethereum_l2'
    ProofService-->>Client: InclusionProof { ..., blockchain: 'ethereum_l2' }

    Note over Client,Errors: Flux de vérification (proof-verifier.service)
    Client->>Verifier: verifyProof(proof)
    alt blockchain absent
        Verifier->>Verifier: fallback 'ethereum_l2' (rétrocompat)
    else blockchain invalide (type/valeur)
        Verifier->>Errors: PROOF_001 — Invalid blockchain identifier
        Errors-->>Client: 400 Bad Request
    else blockchain valide mais non actif
        Verifier->>Constants: isBlockchainActive(blockchain)
        Constants-->>Verifier: false
        Verifier->>Errors: PROOF_002 — Blockchain not active
        Errors-->>Client: 400 Bad Request
    else blockchain valide et actif
        Verifier->>Constants: isBlockchainActive(blockchain)
        Constants-->>Verifier: true
        Verifier-->>Client: proof valide
    end

4. Mapping Invariants → Mécanismes¶

5. Mapping CA → Mécanismes → Tests¶

6. Gestion des erreurs¶

6.1 Structure d'exception¶

throw new ProofValidationException({
  statusCode: 400,
  error: 'Bad Request',
  message: `Invalid blockchain identifier: ${value}`,
  code: 'PROOF_001',
  details: {
    field: 'blockchain',
    value: value,
    allowed: ['ethereum_l2', 'tezos'],
  },
});

7. Contraintes techniques¶

7.1 Dépendances inter-PD¶

7.2 Framework de test¶

• Runner : Jest
• Tests d'intégration : avec mocks (pas de services réels)
• CI : variables standard (CI=true)

7.3 Compatibilité¶

• ESM/CJS : Pas de dépendances ESM-only
• Node.js : >= 18.x

8. Hypothèses¶

9. Points de vigilance¶

10. Fichiers de test¶

Fin du plan d'implémentation PD-245.