khadhroony-solana-project/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md

Couches et dépendances KSP

Rôle des niveaux

Les niveaux N1 à N4 servent à raisonner sur les responsabilités, la stabilité et le sens des dépendances. Ils ne constituent pas une chaîne d'appels obligatoire.

Les niveaux durables de données utilisent une nomenclature distincte D1 à D4 afin de ne jamais être confondus avec les couches architecturales N1 à N4 : D1 Raw, D2 Core canonique, D3 journal de matérialisation générique et D4 projections spécialisées.

Une couche supérieure peut dépendre directement d'une bibliothèque KSP plus basse lorsque cette bibliothèque est exactement la propriétaire de la capacité recherchée.

N1 — Fondations

N1 contient les contrats et services transversaux qui doivent rester bas dans le graphe de dépendances.

Positionnement actuellement retenu :

• ksp-core-lib — primitives et contrats fondamentaux réellement transversaux, type d'erreur commun KSP et responsabilité autrefois séparée des identifiants de programmes ;
• ksp-interface-lib — façade KSP des interfaces/wire on-chain nécessaires aux autres bibliothèques ;
• ksp-config-lib — contrats, chargement/résolution et manipulation autorisée de la configuration et des profils ;
• ksp-logging-lib — façade commune de logging/tracing, propriétaire de l'initialisation et des dépendances directes tracing, tracing-appender et tracing-subscriber.

ksp-logging-lib peut dépendre de ksp-core-lib pour le contrat commun Error / Result. La relation inverse n'est pas requise : ksp-core-lib reste sans dépendance logging tant qu'aucun besoin réel ne la justifie.

Les crates KSP contenant du comportement/runtime peuvent dépendre directement de ksp-logging-lib afin de produire des logs structurés aux niveaux error, warn, info, debug et trace. Les crates *-api purement déclaratives n'ajoutent pas cette dépendance sans comportement réel à logger.

Une bibliothèque N1 ne doit pas dépendre d'une fonctionnalité métier située dans une couche supérieure.

N2 — Capacités Solana

N2 regroupe les capacités réutilisables opérant sur Solana au-dessus des fondations.

Le nom ksp-program-lib est retenu pour la bibliothèque propriétaire du traitement des programmes : décodage et préparation technique d'opérations via ProgramExecutionPreparer. Elle doit s'appuyer sur ksp-interface-lib plutôt que faire porter les contrats wire aux applications.

Les autres responsabilités N2 candidates comprennent notamment :

• ksp-onchain-transport-lib ;
• ksp-offchain-transport-lib lorsqu'un premier besoin réel justifiera son implémentation ;
• ksp-wallet-lib.

Le transport off-chain est général : il ne se limite pas aux metadata et pourra servir à des ressources telles que metadata externes, prix de référence, services de routage ou autres données hors blockchain.

N3 — Données et orchestration réutilisable

N3 doit accueillir les responsabilités qui interprètent, persistent ou orchestrent des capacités inférieures, notamment :

• matérialisation ;
• stockage ;
• replay/reconstruction ;
• pipelines ;
• scénarios réutilisables ;
• contrôle/orchestration de workers lorsqu'il sera introduit.

W1

W1 est un worker d'acquisition live/quasi-live uniquement.

Il consomme au minimum les contrats de configuration, transport on-chain et stockage nécessaires pour :

1. écouter les sources configurées ;
2. rapatrier les données ;
3. les persister sous forme raw ;
4. notifier qu'une nouvelle information raw est disponible.

W1 :

• ne décode pas ;
• ne matérialise pas ;
• ne réalise pas de replay ;
• ne décide pas de l'utilisation métier des données collectées ;
• doit pouvoir faire évoluer à chaud ce qu'il écoute, rapatrie ou stocke selon les mécanismes de configuration/commande qui seront définis.

Les notifications W1 servent de wake-up. Les workers/jobs downstream reconstruisent leur backlog depuis le Store et appliquent les pipelines spécialisés correspondant aux frontières D1 -> D2 -> D3 -> D4.

Workers de processing futurs

Le processing continu n'est plus modélisé comme un unique W2. Il sépare ksp-worker-core-processor, ksp-worker-generic-materializer et ksp-worker-domain-projector afin de respecter les frontières durables D1 Raw -> D2 Core -> D3 journal de matérialisation générique -> D4 projections de domaine. Le lifecycle, backlog, claim/lease et replay sont détaillés dans 009-ACQUISITION_WORKERS_AND_JOBS.md.

N4 — Exécutables

N4 contient les applications, demos et workers.

Dépendances directes autorisées

N4 n'est pas obligé de traverser N3 puis N2 pour atteindre N1.

Exemples valides :

ksp-app-config-desk
    └── ksp-config-lib

ksp-app-store-desk
    ├── ksp-store-lib
    └── ksp-config-lib

Une application de configuration n'a aucune raison de dépendre de couches Solana qui ne participent pas à sa fonction.

Une application de store peut utiliser ksp-config-lib pour sélectionner/résoudre un profil et ksp-store-lib pour valider, initialiser ou reconstruire le stockage. Elle ne doit pas réimplémenter ces opérations ni appeler directement le backend propriétaire.

Applications et demos

Une application ou demo :

• recueille et présente les données ;
• effectue les conversions/validations strictement liées à son interface ;
• sélectionne les options, profils et scénarios autorisés ;
• appelle les bibliothèques KSP propriétaires ;
• affiche ou exporte les résultats.

Elle ne doit pas réécrire :

• le décodage ;
• la logique protocolaire ;
• les PDA et layouts ;
• la construction d'instructions ;
• la matérialisation ;
• les opérations de stockage ;
• les scénarios réutilisables ;
• les autres opérations appartenant à une bibliothèque inférieure.

Lorsqu'une bibliothèque de scénarios possède déjà un workflow de démonstration, l'application demo doit l'appeler.

Les demos/scénarios doivent rester séparés par responsabilité fonctionnelle cohérente. Un regroupement n'est autorisé que lorsque plusieurs interfaces représentent réellement le même domaine fonctionnel.

Exemples actuellement retenus :

• Memo : demo/scénarios séparés ;
• SPL Token classique : demo/scénarios séparés ;
• Associated Token Account : demo/scénarios séparés ;
• Token-2022 : demo/scénarios séparés ;
• metadata d'assets/tokens : Metaplex Token Metadata et Token-2022 Metadata peuvent partager une même famille de demo/scénarios ;
• Solana Program Metadata (SPM) reste séparé car il n'appartient pas à la même catégorie fonctionnelle.

Workers

Les workers sont différents des interfaces utilisateur. Ils peuvent contenir l'orchestration runtime strictement nécessaire à leur responsabilité.

Un worker doit néanmoins consommer les bibliothèques KSP propriétaires des contrats Solana et ne doit pas dépendre directement de crates Solana/protocoles externes.

Les premiers managers de workers sont spécialisés et séparés. Une application globale est un produit futur, tandis qu'un orchestrateur commun reste une abstraction à réévaluer seulement lorsqu'un besoin opérationnel concret le justifie.

Firewall des dépendances externes

Les exécutables KSP dépendent des bibliothèques KSP pour les capacités Solana.

application / demo / worker
            │
            ▼
       bibliothèques KSP
            │
            ▼
primitives externes explicitement autorisées
            │
            ▼
          Solana

Une dépendance externe Solana ou protocolaire doit être possédée par la bibliothèque KSP la plus basse et la plus cohérente avec sa responsabilité.

Sens des dépendances

Le principe recherché est :

N4 ───────► N3 / N2 / N1
N3 ───────► N2 / N1
N2 ───────► N1
N1 ───────► fondations externes explicitement autorisées

Il n'est pas permis d'introduire une dépendance vers une couche supérieure pour résoudre localement un problème. Si cela semble nécessaire, le classement des responsabilités doit être réexaminé.

Principe contract-first

Les contrats minimaux entre couches doivent être définis suffisamment tôt pour que les composants futurs puissent se construire contre une frontière KSP stable, même lorsque l'implémentation complète arrive dans une version ultérieure.

Ce principe s'applique notamment aux futurs :

• decoders ;
• ProgramExecutionPreparer / constructeurs d'opérations ;
• materializers ;
• store/repositories ;
• transports ;
• scénarios ;
• notifications et contrôle des workers ;
• orchestrateur.

Il ne signifie pas qu'il faut implémenter prématurément toutes les fonctionnalités. Les interfaces/traits peuvent évoluer légèrement lorsque l'expérience révèle un besoin réel, mais une dépendance entre couches ne doit pas être remplacée par un couplage ad hoc sous prétexte que le contrat final n'existe pas encore.

Questions encore ouvertes

• représentation interne exacte du type d'erreur commun KSP, à traiter dès 0.1.1-pre.001 ;
• types publics précis de ksp-program-api et format ouvert/persistable des résultats décodés ;
• méthode de conformité wire contre les projets externes ;
• mécanisme IPC du premier manager de worker autonome ;
• besoins de contexte des futurs DomainProjector stateful ;
• nécessité réelle d'un orchestrateur commun lorsque plusieurs services/managers existeront.