65 lines
5.1 KiB
Markdown
65 lines
5.1 KiB
Markdown
<!-- file: README.md -->
|
|
<!-- version: 8 -->
|
|
|
|
# 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.
|
|
|
|
Ces contrats restent distincts des futurs workers continus : un job borné n'est ni un service worker ni un pipeline générique imposé aux autres couches.
|
|
|
|
## Points d'entrée
|
|
|
|
- [`RULES.md`](RULES.md) — index des règles normatives ;
|
|
- [`ROADMAP.md`](ROADMAP.md) — trajectoire globale du projet ;
|
|
- [`CHANGELOG.md`](CHANGELOG.md) — synthèse des releases stables ;
|
|
- [`docs/000-README.md`](docs/000-README.md) — point d'entrée de la documentation ;
|
|
- [`docs/IDEAS.md`](docs/IDEAS.md) — idées et sujets à explorer ;
|
|
- [`prompts/000-README.md`](prompts/000-README.md) — prompts de reprise ;
|
|
- [`deltas/`](deltas/) — historique détaillé des livraisons.
|