v0.0.3-pre.001

2026-08-14 00:03:57 +02:00
parent 4032298589
commit 5a86808376
23 changed files with 1845 additions and 102 deletions
--- a/docs/architecture/000-README.md
+++ b/docs/architecture/000-README.md
@@ -0,0 +1,24 @@
+<!-- file: docs/architecture/000-README.md -->
+<!-- version: 2 -->
+
+# Architecture KSP
+
+Ce répertoire contient les documents d'architecture et de périmètre durable de Khadhroony Solana Project.
+
+Les documents d'architecture distinguent explicitement :
+
+- les décisions déjà retenues ;
+- les directions fortes encore à valider par l'implémentation ;
+- les hypothèses de travail ;
+- les questions ouvertes ;
+- les conséquences attendues sur les futurs composants.
+
+Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
+
+## Ordre initial
+
+1. [`001-PROJECT_OBJECTIVES.md`](001-PROJECT_OBJECTIVES.md) — finalité, objectifs produits et non-objectifs architecturaux ;
+2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ;
+3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants, contrats à définir tôt et responsabilités déjà acquises.
+
+Les futurs documents prioritaires peuvent continuer avec `004-`, `005-`, etc. lorsqu'un ordre de lecture explicite apporte une valeur réelle.
--- a/docs/architecture/001-PROJECT_OBJECTIVES.md
+++ b/docs/architecture/001-PROJECT_OBJECTIVES.md
@@ -0,0 +1,68 @@
+<!-- file: docs/architecture/001-PROJECT_OBJECTIVES.md -->
+<!-- version: 1 -->
+
+# Objectifs de Khadhroony Solana Project
+
+## Positionnement
+
+Khadhroony Solana Project est un umbrella project consacré à la blockchain Solana.
+
+Sa fonction n'est pas de construire une seule application monolithique, mais de fournir des bibliothèques KSP cohérentes, réutilisables, interconnectables et, lorsque leur contrat le permet, utilisables indépendamment.
+
+## Capacités générales visées
+
+KSP doit progressivement fournir des capacités permettant notamment de :
+
+- représenter les primitives et contrats KSP/Solana communs ;
+- posséder les interfaces wire nécessaires aux programmes on-chain pris en charge ;
+- acquérir des données Solana en temps réel ou historiquement ;
+- décoder transactions, instructions, comptes, événements et autres formats pertinents ;
+- construire des opérations compatibles avec les programmes supportés ;
+- signer, simuler, soumettre et suivre des opérations lorsque les frontières correspondantes auront été définies ;
+- gérer les wallets et signers nécessaires aux usages KSP ;
+- matérialiser les données décodées vers des faits canoniques ;
+- stocker, rejouer, reconstruire et interroger les données ;
+- composer ces capacités dans des applications, workers et demos spécialisés.
+
+## Objectif court terme
+
+L'objectif produit prioritaire est une application de trading Solana monoposte.
+
+Cette priorité ne transforme pas les bibliothèques fondamentales en bibliothèques spécifiques au trading. Les données, interfaces, transports, décodages et modèles généraux doivent rester réutilisables par les autres produits KSP.
+
+## Objectifs moyen et long terme
+
+KSP doit permettre de construire notamment :
+
+### Explorer Solana
+
+Une application générale comparable dans son domaine à `explorer.solana.com` ou Solscan, capable d'exploiter les données et contrats KSP sans créer une seconde pile de décodage/stockage.
+
+### Explorer et analyse DEX
+
+Une application comparable dans son principe à DexScreener, avec une couverture plus complète des DEX et des modèles de marché Solana lorsque les données KSP le permettent.
+
+## Non-objectifs architecturaux
+
+KSP ne doit pas :
+
+- devenir un monolithe centré sur une seule application ;
+- dupliquer la même connaissance Solana dans plusieurs produits ;
+- transformer les applications/demos en propriétaires de logique bas niveau ou protocolaire ;
+- utiliser automatiquement une crate externe de protocole simplement parce qu'elle fournit les structures wire nécessaires ;
+- forcer chaque application à dépendre de toutes les couches KSP ;
+- créer des bibliothèques spécifiques à un produit lorsque la responsabilité est générale à Solana ou à KSP.
+
+## Conséquence structurante
+
+Les produits finaux doivent partager les mêmes bibliothèques fondamentales :
+
+```text
+bibliothèques KSP
+    ├── application de trading
+    ├── explorer Solana
+    ├── explorer/analyse DEX
+    └── autres applications spécialisées
+```
+
+La première utilisation d'une capacité dans un produit ne détermine donc pas automatiquement son propriétaire architectural.
--- a/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
+++ b/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
@@ -0,0 +1,196 @@
+<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
+<!-- version: 2 -->
+
+# 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.
+
+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` — fondations communes de logging/tracing.
+
+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 future bibliothèque propriétaire du traitement des programmes : décodage et opérations techniquement constructibles/exécutables. 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 consommateurs des notifications W1 décident eux-mêmes s'ils doivent décoder, matérialiser ou effectuer un autre traitement.
+
+### W2
+
+W2 est réservé à une phase ultérieure de processing. Son contrat précis sera défini après stabilisation du décodage, de la matérialisation et du store. Il ne doit pas être confondu avec W1.
+
+## 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 :
+
+```text
+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 peuvent être spécialisés et séparés. Un orchestrateur global sera introduit ultérieurement lorsque plusieurs workers/managers justifieront réellement cette abstraction.
+
+## Firewall des dépendances externes
+
+Les exécutables KSP dépendent des bibliothèques KSP pour les capacités Solana.
+
+```text
+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 :
+
+```text
+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 ;
+- executors/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 ;
+- découpage interne précis de `ksp-program-lib` ;
+- politique de sécurité/exécution située au-dessus de `ksp-program-lib` ;
+- position précise du pipeline et du futur orchestrateur ;
+- méthode de conformité wire contre les projets externes ;
+- graphe de dépendances précis crate par crate.
--- a/docs/architecture/003-COMPONENT_CONTRACTS.md
+++ b/docs/architecture/003-COMPONENT_CONTRACTS.md
@@ -0,0 +1,127 @@
+<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
+<!-- version: 3 -->
+
+# Contrats initiaux des composants KSP
+
+## Convention API / implémentation
+
+Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP sépare :
+
+```text
+ksp-<domain>-api
+ksp-<domain>-lib
+```
+
+La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`. Elle expose principalement des traits, types, enums et contrats publics ; elle peut être consommée par plusieurs implémentations et n'est pas, à elle seule, une implémentation fonctionnelle destinée aux exécutables.
+
+La crate `ksp-<domain>-lib` contient l'implémentation officielle KSP correspondante lorsqu'une telle implémentation existe.
+
+Cette séparation n'est pas automatique pour tous les domaines. Elle est utilisée lorsqu'une vraie frontière d'extension ou de backend justifie une API indépendante.
+
+Premiers couples retenus :
+
+- `ksp-program-api` + `ksp-program-lib` ;
+- `ksp-materializer-api` + `ksp-materializer-lib` ;
+- `ksp-store-api` + `ksp-store-lib`.
+
+Un unique `ksp-api-lib` monolithique est rejeté.
+
+## `ksp-program-api` / `ksp-program-lib`
+
+`ksp-program-api` possède les contrats publics communs de décodage/exécution. Une crate séparée doit pouvoir implémenter et tester ces contrats sans dépendre de `ksp-program-lib`.
+
+`ksp-program-lib` contient les implémentations officielles intégrées des Program IDs supportés.
+
+Le decoder vise toute surface techniquement décodable dont la définition est connue. Le statut `deprecated` concerne l'exécution, pas le décodage. Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
+
+L'executor expose les opérations techniquement exécutables connues ; une opération obsolète mais encore identifiable/exécutable peut rester implémentée et être marquée `deprecated`. La politique de sécurité appartient à une couche supérieure.
+
+## `ksp-materializer-api` / `ksp-materializer-lib`
+
+`ksp-materializer-api` possède les contrats publics/extensibles de matérialisation. Une crate externe doit pouvoir implémenter un materializer contre cette API sans dépendre de `ksp-materializer-lib`.
+
+`ksp-materializer-lib` contient les materializers officiels intégrés KSP.
+
+## `ksp-store-api` / `ksp-store-lib`
+
+`ksp-store-api` possède les contrats backend-agnostic de persistance et d'accès aux données KSP.
+
+`ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence : configuration/connexion, migrations, repositories, queries et mécanismes backend nécessaires.
+
+Les applications, workers, jobs et materializers consomment les contrats KSP et ne contournent pas le store pour accéder directement au backend.
+
+## Notifications de données
+
+Une notification de donnée décrit la donnée disponible, pas son producteur.
+
+Le même type de donnée doit utiliser le même contrat de notification qu'elle provienne :
+
+- de W1 ;
+- d'un job de backfill ;
+- d'un import ;
+- d'une autre source future.
+
+`ksp-store-api` est le propriétaire candidat des références/événements canoniques indiquant qu'une donnée persistée est disponible, par exemple conceptuellement `RawDataRef` / `RawDataAvailable`.
+
+Le contrat de notification reste distinct du mécanisme de transport concret : channel in-process, PostgreSQL LISTEN/NOTIFY, IPC, broker ou autre mécanisme futur.
+
+## Workers
+
+Les workers sont des services continus/live. Leurs contrats communs appartiennent à :
+
+```text
+ksp-worker-api
+```
+
+Cette API ne contient aucun contrat de job.
+
+Une future implémentation commune de gouvernance/contrôle des workers peut vivre dans :
+
+```text
+ksp-worker-control-lib
+```
+
+W1 reste un worker d'acquisition raw live/quasi-live : configuration, transport, persistance raw, reconfiguration à chaud et notification de disponibilité. Il ne décode pas, ne matérialise pas et ne réalise aucun replay/backfill historique.
+
+## Jobs
+
+Les jobs sont des travaux déclenchés à la demande, suivables et terminables. Leurs contrats communs appartiennent à :
+
+```text
+ksp-job-api
+```
+
+Cette API ne contient aucun contrat de worker.
+
+Les implémentations concrètes utilisent le préfixe `ksp-job-`.
+
+Premier candidat retenu :
+
+```text
+ksp-job-backfill
+```
+
+D'autres jobs pourront être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel existe.
+
+Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers, même si certaines opérations semblent similaires.
+
+## Pipelines
+
+KSP ne prévoit pas de `ksp-pipeline-lib` monolithique. Lorsqu'un pipeline réutilisable devient nécessaire, il est introduit séparément avec un périmètre concret et borné.
+
+## Demos et scénarios
+
+Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
+
+Les scénarios sont organisés en crates spécialisées par domaine cohérent, par exemple :
+
+```text
+ksp-scenario-memo-lib
+ksp-scenario-token-lib
+ksp-scenario-ata-lib
+ksp-scenario-token-2022-lib
+ksp-scenario-metadata-lib
+ksp-scenario-spm-lib
+```
+
+Les metadata d'assets/tokens peuvent regrouper Metaplex Token Metadata et Token-2022 Metadata. Solana Program Metadata reste séparé.