Khadhroony Solana Project

khadhroony-solana-project (KSP) est un umbrella project consacré à la blockchain Solana. Il regroupe des bibliothèques, APIs de contrats, workers, jobs, outils et applications construits autour de contrats KSP communs.

Finalité

KSP doit fournir des bibliothèques réutilisables, interconnectables mais également exploitables indépendamment, permettant de lire, décoder, interpréter, construire, signer, exécuter, acquérir, stocker, reconstruire et matérialiser des données et opérations Solana.

Les applications, workers et jobs sont construits au-dessus des contrats et bibliothèques KSP. La connaissance bas niveau de Solana et des protocoles doit rester dans les composants KSP qui en sont propriétaires, et ne doit pas être dupliquée dans les interfaces utilisateur ou les exécutables.

Objectifs produits

À court terme, KSP doit fournir les fondations nécessaires à une future application de trading Solana monoposte s'appuyant sur les mêmes bibliothèques générales que le reste du projet.

Avant cette application, KSP doit construire progressivement les données, statistiques, signaux et capacités de Trading Intelligence nécessaires pour évaluer correctement les décisions de trading.

À moyen et long terme, KSP doit permettre de construire notamment :

• un explorer Solana comparable dans son domaine à explorer.solana.com ou Solscan, tout en s'appuyant sur les contrats et données KSP ;
• une application d'exploration et d'analyse DEX comparable dans son principe à DexScreener, avec une couverture Solana/DEX plus complète ;
• d'autres applications spécialisées réutilisant les mêmes capacités sans réimplémenter la compréhension de Solana.

Les besoins du trading constituent une priorité produit à court terme mais ne doivent pas rendre les bibliothèques fondamentales spécifiques au trading.

Principes structurants

• Les bibliothèques d'implémentation réutilisables utilisent le préfixe ksp- et le suffixe -lib.
• Les crates de contrats/API publics extensibles utilisent la forme ksp-<domain>-api et ne portent volontairement pas le suffixe -lib, même si elles sont techniquement des bibliothèques Rust.
• Une crate *-api expose des contrats/types/traits et n'est pas un exécutable directement utilisable sans implémentation appropriée.
• Les applications utilisent le préfixe ksp-app-.
• Les workers utilisent le préfixe ksp-worker-.
• Les jobs utilisent le préfixe ksp-job-.
• Une application ou un outil de démonstration se termine par -demo.
• Les crates Rust sont placées directement sous crates/, sans sous-répertoires de catégories.
• Les applications Tauri, workers, jobs et autres packages Rust KSP sont des crates workspace placées directement sous crates/; leur nom encode leur rôle (ksp-app-*, ksp-worker-*, ksp-job-*).
• Les composants réutilisables restent séparés de leurs applications de manipulation ou de démonstration.
• Les applications et demos restent des interfaces/compositions ; les opérations réutilisables appartiennent aux composants KSP de niveau approprié.
• Les exécutables KSP ne dépendent pas directement de crates externes relatives à Solana ou à un protocole Solana.
• Les contrats publics réutilisables doivent pouvoir être implémentés par des crates séparées lorsque cela apporte de la valeur.
• Les contrats communs des workers et ceux des jobs restent séparés.
• Les notifications de données utilisent un format canonique indépendant du fait que la donnée ait été produite par un worker, un job ou une autre source.
• Les dépendances sont maintenues aussi récentes que possible ; les contraintes nécessaires sont documentées explicitement.
• Les lockfiles de dépendances ne sont pas versionnés.
• Aucun rust-toolchain.toml n'est utilisé.
• Les environnements et contraintes des démonstrations doivent être visibles dans leur nomenclature lorsqu'ils ne sont pas sélectionnables.

Fondations opérationnelles actuelles

La couche RAW dispose d'une façade Store backend-neutral et d'un premier job historique concret. ksp-job-api porte les contrats passifs communs des jobs bornés ; ksp-job-backfill-lib compose Transport observé et Store pour découvrir, hydrater et persister des transactions historiques RAW avec concurrence bornée, checkpoint contigu caller-owned, annulation coopérative et snapshots latest-value.

ksp-app-backfill-desk fournit la surface desktop spécialisée de composition de ce runtime : sélection d'un scope historique et d'un rôle HTTP logique, validation backend des bornes, Start single-run, monitoring latest-value, Cancel ciblé et Resume in-session sur checkpoint Rust-only. L'application ouvre Transport et Store via leurs façades KSP, ne dépend d'aucun backend Store concret et n'expose ni URL/credential, ni payload RAW, ni checkpoint opaque au frontend.

ksp-app-store-desk fournit l'inspection desktop read-only du Store RAW via ksp-store-lib : health/runtime backend-neutral, tables server-side RawTransaction et RawAccountState, observations associées, détails avec previews bornées et lecture des états de rétention/tombstones. DataTables possède l'unique pagination visible de l'inspection random-access ; la pagination cursor/keyset des consumers machine reste distincte et intacte.

ksp-worker-api fournit désormais la fondation générique des services continus : identité Worker, lifecycle borné, health/activity, intention de stop coopératif et observation latest-value. Cette API reste Core-only, runtime-neutral et sans connaissance Solana, Transport, Store ou Job. Elle ne démarre ni n'arrête elle-même un runtime concret.

ksp-worker-raw-transaction-ingest-lib est le premier Worker concret distinct du Job Backfill. Il conserve sa fondation Start/Stop, admission bornée, Common RAW, Store backend-neutral, shutdown borné et snapshots latest-value. Ses sources productives couvrent maintenant Yellowstone + hydration HTTP getTransaction, Standard WS logsSubscribe + hydration, Standard WS blockSubscribe RAW-direct, Helius transactionSubscribe + hydration et Solana HTTP live block polling. Le polling HTTP démarre au getSlot observé du run, découvre uniquement les blocs live via getBlocksWithLimit puis matérialise les slots listés via getBlock observed; il n'est jamais utilisé comme Backfill implicite. Les signaux hydratés de même (network, signature, commitment) convergent vers le même coordinator, tandis que les voies block RAW-direct passent par la même admission Common RAW. Le reconnect/replay reste propriétaire de Transport, la frontier de traitement reste run-local et un gap de rétention prouvé provoque un fault au lieu de lancer une campagne historique. ksp-job-backfill-lib conserve son rôle historique paramétré et borné ; les deux producteurs restent indépendants et convergent uniquement vers les mêmes contrats RAW/Store.

Points d'entrée

• RULES.md — index des règles normatives ;
• ROADMAP.md — trajectoire globale du projet ;
• CHANGELOG.md — synthèse des releases stables ;
• docs/000-README.md — point d'entrée de la documentation ;
• docs/IDEAS.md — idées et sujets à explorer ;
• prompts/000-README.md — prompts de reprise ;
• deltas/ — historique détaillé des livraisons.