62 lines
4.4 KiB
Markdown
62 lines
4.4 KiB
Markdown
<!-- file: docs/architecture/PIPELINE_ARCHITECTURE.md -->
|
||
<!-- version: 7 -->
|
||
|
||
# Architecture du pipeline
|
||
|
||
## 1. Responsabilité
|
||
|
||
`ks-pipeline` coordonne des opérations généralistes qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution. Il ne dépend d’aucun scénario, wallet ou actif propre à un réseau de démonstration.
|
||
|
||
## 2. Familles de traitements
|
||
|
||
### 2.1 Backfill
|
||
|
||
Le backfill sélectionne des signatures ou transactions selon une adresse, un programme, un rôle d’endpoint et des bornes explicites. Il gère progression, reprise, annulation et résultats partiels selon les contrats exposés par le pipeline.
|
||
|
||
### 2.2 Extraction Core
|
||
|
||
L’extraction Core transforme les transactions stockées en représentations d’instructions contextualisées nécessaires aux décodeurs. Elle constitue une phase distincte du replay de décodage.
|
||
|
||
### 2.3 Replay de décodage
|
||
|
||
Le replay sélectionne des candidats, applique les décodeurs compatibles de `ks-lib`, conserve diagnostics et preuves, puis déclenche les matérialisateurs demandés. La reprise doit préserver l’idempotence et les frontières de campagne.
|
||
|
||
### 2.4 Traitements stateful
|
||
|
||
Les modules stateful corrèlent instructions, comptes, états précédents et résultats de transaction lorsque le protocole l’exige. Les surfaces SPL Token, ATA, Token-2022, registre ElGamal et les trois domaines Metadata de `0.4.8` disposent de traitements spécialisés lorsque leur contrat l’exige.
|
||
|
||
### 2.5 Préflight et exécution
|
||
|
||
Le pipeline assemble les contrôles préalables, plans préparés, signataires, preuves, simulation et validation postérieure. Les exécuteurs restent définis dans `ks-lib` ; le pipeline orchestre leur utilisation.
|
||
|
||
## 3. Dépendances fonctionnelles
|
||
|
||
```text
|
||
ks-onchain-transport -> acquisition et appels RPC
|
||
ks-store -> lecture/écriture canonique et replay
|
||
ks-lib -> contrats et implémentations métier
|
||
ks-config -> compositions binaires, profils partagés et paramètres opérationnels
|
||
ks-logging -> observabilité
|
||
ks-wallet -> signataires lorsque requis
|
||
```
|
||
|
||
## 4. Scénarios de démonstration
|
||
|
||
`ks-pipeline-demo-scenarios` contient les fixtures, aides de campagne et scénarios réutilisables spécifiques à Devnet ou Testnet. Le desktop doit appeler ces scénarios lorsqu’ils existent plutôt que maintenir une seconde implémentation métier du même parcours.
|
||
|
||
Cette crate peut préparer des wallets temporaires, demander des airdrops, créer des mints ou comptes de test, enchaîner plusieurs opérations et réunir les preuves d’une campagne réseau. Ces responsabilités spécifiques aux validations réseau ne doivent pas remonter dans `ks-pipeline`.
|
||
|
||
Le binaire `ks-pipeline-demo-scenarios-cli` est actuellement un outil ciblé de préparation des fixtures SPL Token-2022 réutilisées par les démonstrations Devnet. Son existence ne signifie pas que chaque scénario doit être exposé par un CLI ni que le desktop doit consommer ses scénarios.
|
||
|
||
`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et d’exécution de campagne appartient à `ks-pipeline-demo-scenarios`, renommée `ks-pipeline-demo-scenarios` en `0.5.1`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `ks-pipeline` vers les scénarios reste interdite et cette règle se conserve après migration vers `ks-pipeline`.
|
||
|
||
## 5. Contrats de preuve
|
||
|
||
Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contract-matrices/` participent à la preuve contractuelle. Une matrice peut être à la fois une référence lisible et une fixture chargée par le code de test ; elle ne doit pas être dupliquée sous `docs/`.
|
||
|
||
## 6. Limites connues
|
||
|
||
- Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
|
||
- La réconciliation finale des scénarios encore dupliqués entre desktop et la future `ks-pipeline-demo-scenarios` est planifiée en `0.5.4`.
|
||
- Après `0.5.1`, les futurs protocoles doivent conserver cette frontière : orchestration généraliste dans `ks-pipeline`, scénarios réseau réutilisables dans `ks-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop.
|