24 KiB
Prompt de démarrage 0.2.1 — ksp-onchain-transport-lib HTTP Solana foundation
Statut : consommé par
0.2.1-pre.001. Le gate de sizing du 2026-08-17 a conclu que le périmètre monolithique décrit ci-dessous n'était pas clôturable raisonnablement dans une seule session. Le plan actifdocs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.mdle remplace pour l'exécution :0.2.1devient la foundation + 4 canaris, et la couverture HTTP typée exhaustive est répartie sur0.2.1–0.2.6. Le présent document reste la trace du cahier des charges ayant ouvert l'audit ; ne pas le réutiliser comme prompt d'implémentation monolithique.
1. Contexte de reprise
La base attendue est la release stable v0.2.0 de khadhroony-solana-project.
0.2.0 a audité khadhroony-bot3, refondu la roadmap et décidé que la première capacité fonctionnelle de 0.2.x doit être le transport HTTP Solana, car les capacités suivantes — en particulier ksp-wallet-lib puis ksp-app-wallet-desk — doivent pouvoir interroger réellement le réseau, par exemple pour lire le solde d'un wallet.
Les fondations stables à préserver sont :
ksp-core-lib
ksp-logging-lib
ksp-config-lib
ksp-app-config-desk
La release à ouvrir est :
0.2.1 — ksp-onchain-transport-lib / Solana HTTP foundation
La première tranche est :
0.2.1-pre.001
pre.001 est une tranche d'audit, conception, inventaire exhaustif et dimensionnement. Elle ne doit pas devenir automatiquement une grosse implémentation.
2. Mission de 0.2.1
Créer la première version stable de ksp-onchain-transport-lib pour le transport HTTP JSON-RPC Solana, avec une API publique KSP indépendante de Config, du Store et des futures couches Program.
La release doit fournir :
- transport HTTP async ;
- JSON-RPC 2.0 ;
- settings runtime publics possédés par le transport ;
- endpoints nommés ;
- metadata provider/cluster ;
- pools logiques d'endpoints ;
- rôles/capabilities/request kinds ;
- priorités ;
- limites de débit/burst/concurrence lorsque configurées ;
- timeout ;
- retry/backoff transport borné ;
- observabilité via
ksp-logging-lib; - toutes les méthodes HTTP exposées par la documentation normative Solana ciblée par la release ;
- méthodes read et méthodes write/execution technique ;
- classification centralisée des méthodes selon leur statut documentaire ;
- warnings runtime pour méthodes deprecated/obsolete encore fonctionnelles et unstable/experimental ;
- premier document Config standard Transport dans
ksp-config-libet adapter Config -> settings publics Transport ; - tests, fixtures, documentation
README.md/USAGE.mdet preuve de complétude de la surface.
0.2.1 doit être un transport générique KSP utilisable directement par une bibliothèque, une application, un job ou un worker. Il ne doit pas être conçu uniquement pour Wallet Desk.
3. Sources de vérité internes obligatoires
Avant toute modification, relire au minimum :
ROADMAP.md
docs/000-README.md
docs/IDEAS.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/007-V0_2_0_SERIES_PLANNING.md
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
docs/architecture/003-COMPONENT_CONTRACTS.md
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/rules/RULES_KSP.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_RUST.md
docs/rules/PROMPT_STRUCTURE.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/FILE_CONTRACTS.md
Relire également les contrats publics actuels de :
crates/ksp-core-lib
crates/ksp-logging-lib
crates/ksp-config-lib
Ne pas supposer leurs APIs à partir de bot3.
4. Référence historique bot3
Auditer la dernière archive bot3 fournie disponible, en particulier :
ks-onchain-transport/
ks-config/src/transport.rs
ks-config/src/settings.rs
kb-app-demo-desktop/src/demo_http.rs
kb-app-demo-desktop/src/demo_transport.rs
Sur ks-onchain-transport, examiner au minimum :
client.rs
endpoint_role.rs
execution_rpc.rs
get_signatures_for_address.rs
get_transaction.rs
http_client.rs
http_pool.rs
json_rpc.rs
standard_http.rs
standard_http_accounts.rs
standard_http_blocks.rs
standard_http_cluster.rs
standard_http_economics.rs
standard_http_tokens.rs
standard_http_transactions.rs
standard_methods.rs
validation.rs
README.md
USAGE.md
TODO.md
Bot3 est une source fonctionnelle et historique, pas une source normative d'architecture.
Reprendre les besoins/invariants utiles ; ne pas reproduire :
- dépendance publique Transport -> Config ;
- dépendance vers
ks-lib/modèles canoniques ; - appels directs
tracing; - DTOs couplés au futur Store ;
- anciens stacks de dépendances uniquement parce qu'ils existent ;
- duplication inutile de modèles ou de codecs.
5. Sources externes normatives
Au début de pre.001, consulter la documentation officielle et actuelle de Solana pour JSON-RPC HTTP et identifier précisément la surface normative de la release.
L'inventaire doit couvrir explicitement :
- l'index HTTP courant ;
- la section officielle
Deprecated Methodsmême lorsqu'elle est séparée de l'index courant ; - toute surface HTTP
unstable/experimentalofficiellement documentée ; - la disponibilité runtime réelle d'une méthode deprecated/obsolete avant de décider qu'elle reste supportable.
Le spot-check documentaire de clôture de 0.2.0 a observé 52 méthodes dans l'index HTTP courant du 2026-08-17 et 14 noms dans la section officielle Deprecated Methods. Ces nombres ne sont pas un contrat : 0.2.1-pre.001 doit refaire l'inventaire depuis les sources officielles du jour.
Ne pas utiliser une liste mémorisée ou la liste bot3 comme vérité.
Pour chaque méthode HTTP documentée, relever au minimum :
nom RPC
catégorie
paramètres
config/commitment/encoding éventuels
forme du résultat
erreurs/nullable/optional importants
statut documentaire
stable | deprecated/obsolete | unstable/experimental
notes/version minimum éventuelles
lien/source normative
tests nécessaires
Vérifier également les spécifications/projets officiels nécessaires pour JSON-RPC et les crates externes retenues.
Lorsque la documentation officielle Solana et une implementation/provider divergent, documenter l'écart au lieu de modifier silencieusement le contrat standard.
6. Règle de couverture exhaustive
0.2.1 ne se limite pas aux méthodes actuellement utilisées par Wallet ou bot3.
Pour la surface Solana HTTP officiellement ciblée :
toute méthode exposée par la documentation normative doit être implémentée, sauf impossibilité technique explicitement documentée et validée.
Le pre.001 doit créer une matrice de conformité durable, par exemple dans le plan 0.2.1 ou un document de validation dédié, permettant de vérifier qu'aucune méthode n'a été oubliée.
Une méthode ne peut pas être déclarée couverte uniquement parce qu'un appel JSON générique existe : la release doit décider quelle surface publique typée/générique KSP est réellement promise et tester ce contrat.
7. Méthodes deprecated, obsolete et unstable
Chaque méthode possède une metadata de statut centralisée, conceptuellement :
Stable
Deprecated
Unstable
Les noms Rust exacts sont décidés en pre.001.
Deprecated / obsolete mais encore fonctionnelle
- implémenter/conserver la méthode ;
- ne pas la masquer ;
- émettre un
warnviaksp-logging-liblorsqu'elle est utilisée ; - inclure méthode, statut et contexte sûr dans le log ;
- ne jamais logguer de secrets/tokens/provider credentials.
Unstable / experimental
- implémenter la méthode lorsqu'elle appartient à la documentation ciblée ;
- émettre un
warnviaksp-logging-libà l'utilisation ; - documenter que son contrat externe peut évoluer.
Méthode réellement supprimée/non fonctionnelle
Ne pas simuler un succès. Documenter l'historique et l'absence de support runtime si la méthode n'existe plus dans la surface normative actuelle.
Les warnings ne doivent pas être dispersés à la main dans chaque méthode si une metadata/descripteur commun permet de garantir le comportement de manière centralisée.
8. Frontière Config / Transport
Règle absolue
ksp-onchain-transport-lib -X-> ksp-config-lib
Le transport doit pouvoir être construit et testé sans Config.
Il possède ses settings publics, conceptuellement :
HttpTransportSettings
HttpEndpointSettings
EndpointRoleSettings
RetrySettings
PoolSettings
...
Les noms/types exacts ne sont pas imposés par ce prompt.
Document standard Config
0.2.1 doit également introduire dans ksp-config-lib le premier document standard Transport HTTP et son schema, selon le moteur Config déjà stabilisé.
Direction :
config/std.transport.json
config/schemas/std.transport.schema.json
config/examples/std.transport.example.json # si la convention Config l'exige/retient
Les file_id exacts suivent les conventions ksp-config-lib et sont décidés après audit des documents existants.
Le document Config :
- peut contenir plusieurs profils ;
- sélectionne/configure endpoints, rôles et paramètres HTTP ;
- utilise les placeholders d'environnement KSP pour URLs/tokens seulement selon le mécanisme Config existant ;
- ne lit jamais directement l'environnement dans Transport ;
- doit être extensible plus tard à WS/gRPC sans préremplir aujourd'hui des champs sans implementation ;
- reste manageable par Config Desk grâce au moteur générique existant, sans développer une UI Transport dédiée dans
0.2.1.
Adapter :
ksp-config-lib -> ksp-onchain-transport-lib public settings
La dépendance inverse reste interdite.
Toute nouvelle variable d'environnement réellement utilisée est ajoutée à .env.example dans la même tranche, avec commentaire et namespace correct.
9. Pools, rôles et capabilities
Reprendre/refondre l'idée utile de bot3 sans figer ses structures exactes.
Un endpoint HTTP doit pouvoir déclarer :
- identité/name ;
- enabled ;
- provider ;
- cluster/network ;
- URL ;
- timeout/settings connexion ;
- rôles/capabilities ;
- priorités ;
- limites applicables.
Un rôle peut porter selon le design retenu :
- request kinds/méthodes supportées ;
- priorité ;
- requests per second ;
- burst ;
- max concurrent requests ;
- pause après rate-limit ;
- autres limites réellement justifiées.
Ne pas créer une enum centrale fermée si des rôles configurables/string descriptors permettent une extension plus propre.
Le pool HTTP sélectionne un endpoint/client logique, pas une socket brute.
Le client HTTP sous-jacent reste propriétaire de son propre pooling de connexions réseau.
Le pre.001 doit décider explicitement :
- stratégie de sélection ;
- comportement si aucun endpoint ne satisfait le rôle/méthode ;
- comportement sur endpoint disabled ;
- round-robin/priority/fallback éventuel ;
- gestion d'un endpoint rate-limited ;
- health/snapshot nécessaires ;
- thread-safety/concurrence.
10. Retry, timeout et erreurs
Distinguer strictement :
Retry transport
Peut concerner une requête HTTP qui n'a pas obtenu de résultat exploitable en raison d'un problème transport/provider clairement retryable.
Retry d'exécution métier
N'appartient pas à 0.2.1 et ne doit pas être inventé dans Transport.
Le transport ne doit jamais décider de renvoyer une transaction Solana sur la seule base d'une erreur métier ou d'un timeout ambigu.
Définir une classification d'erreurs KSP suffisamment précise pour distinguer au minimum :
- invalid settings ;
- endpoint selection ;
- connection/HTTP ;
- timeout ;
- rate-limit ;
- JSON encode/decode ;
- JSON-RPC protocol ;
- RPC application error ;
- unsupported/deprecated status si nécessaire ;
- invalid response/invariant.
Utiliser le type d'erreur KSP existant ; ne pas créer une deuxième hiérarchie publique incompatible.
11. Modèles et ownership des types
0.2.1 ne doit pas dépendre du futur Store, de ksp-program-api ou de modèles DECODE/SPECIALIZED.
Les réponses du transport appartiennent au domaine Transport ou utilisent les primitives KSP/bas niveau explicitement admises.
Ne pas reproduire le couplage bot3 :
getTransaction -> ks_lib::MdCanonicalTransaction
Le transport doit préserver les informations nécessaires à la future persistence RAW et à la normalisation CORE sans effectuer lui-même ces transformations.
Le pre.001 doit inventorier les méthodes dont les réponses nécessitent une décision de représentation importante, notamment transactions/messages/accounts/blocks/token amounts/statuses, et fixer l'ownership avant code massif.
Éviter solana-client ou un SDK haut niveau uniquement pour obtenir des DTOs si cela réintroduit un graphe massif et empêche KSP de posséder son contrat transport. Toute dépendance Solana supplémentaire doit être justifiée par un besoin précis et compatible avec le firewall KSP.
12. Dépendances externes
Toutes les dépendances tierces communes sont déclarées au Cargo.toml racine sous [workspace.dependencies], puis consommées avec .workspace = true.
Avant ajout, pre.001 doit vérifier les versions actuelles et le graphe de dépendances des candidates.
Bot3 utilisait notamment :
reqwest
serde
serde_json
tokio
base64
bs58
Cette liste est une référence d'audit, pas une décision automatique.
Ne pas ajouter dans 0.2.1 les dépendances WebSocket/gRPC réservées aux releases suivantes, sauf nécessité technique démontrée pour le build HTTP.
Exécuter les cargo tree pertinents après ajout :
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib -d
cargo tree -p ksp-onchain-transport-lib -e features
cargo tree -p ksp-onchain-transport-lib -e normal
et auditer les doublons réellement significatifs.
13. Logging et observabilité
ksp-onchain-transport-lib utilise ksp-logging-lib et ne dépend pas directement de tracing pour ses événements KSP.
Target attendu : nom Cargo de la crate.
Événements utiles à couvrir :
- création client/pool ;
- sélection endpoint/role ;
- start/end d'une requête aux niveaux debug/trace appropriés ;
- retry ;
- timeout ;
- rate-limit/backoff ;
- endpoint unavailable/degraded ;
- RPC error ;
- méthode deprecated/unstable utilisée ;
- snapshots/health importants.
Ne jamais logguer :
- API key ;
- token provider ;
- URL contenant un secret non redacted ;
- transaction/signature payload sensible sans raison explicite ;
- contenu massif de réponses par défaut.
Les informations provenant de reqwest ou d'autres dépendances sont réémises sous le target KSP lorsque réellement utiles ; ne pas ouvrir globalement leurs targets.
14. Tests obligatoires
Tests unitaires
Prévoir au minimum :
- validation settings ;
- endpoint/role matching ;
- pool selection ;
- priority/fallback ;
- limiter/concurrence ;
- retry/backoff borné ;
- JSON-RPC request/response ;
- RPC error mapping ;
- nullable/optional responses ;
- method status metadata ;
- warning path deprecated/unstable ;
- aucune fuite de secret dans Debug/loggable snapshots.
Tests par méthodes
Chaque méthode documentée doit être couverte par au moins une preuve adaptée :
- request serialization ;
- response deserialization ;
- paramètres/configs ;
- cas optional/null/error importants.
Utiliser des fixtures déterministes lorsque le réseau n'apporte aucune valeur au test.
Tests réseau opt-in
Prévoir un petit nombre de smoke tests Devnet/Mainnet non destructifs si nécessaire pour démontrer l'interop réelle, sans rendre la suite par défaut dépendante d'Internet ou d'une clé provider.
Les tests réseau nécessitant un provider/secret doivent être opt-in et utiliser Config/env via les mécanismes KSP, jamais des secrets versionnés.
Canaries architecturales
Ajouter des tests/audits empêchant au minimum :
ksp-onchain-transport-lib -> ksp-config-lib
ksp-onchain-transport-lib -> ksp-store-*
ksp-onchain-transport-lib -> ksp-program-*
direct tracing ownership
et vérifiant la complétude de la matrice de méthodes si elle peut être automatisée.
15. Hors périmètre strict de 0.2.1
Ne pas ouvrir :
- WebSocket Solana —
0.2.9; - Helius LaserStream WebSocket —
0.2.10; - Yellowstone gRPC —
0.2.11; - providers gRPC avancés ;
- Wallet —
0.2.7; - Wallet Desk —
0.2.8; - Store/persistence RAW —
0.3.1; - decoders Program ;
ksp-interface-libfonctionnel complet ;- materializers ;
- execution policy ;
- orchestration d'exécution métier ;
- worker/job d'acquisition ;
- Tauri app Transport dédiée ;
- trading/DEX/ML.
Une méthode HTTP permettant techniquement sendTransaction, simulateTransaction, requestAirdrop ou autre opération write peut appartenir au transport standard et doit être implémentée si documentée ; cela ne signifie pas que 0.2.1 construit l'orchestration d'exécution KSP.
16. Première mission : 0.2.1-pre.001
pre.001 doit livrer un plan détaillé de 0.2.1, candidat :
docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
Il doit contenir au minimum :
- audit exact de la base stable
v0.2.0; - audit détaillé de
ks-onchain-transportbot3 ; - inventaire exhaustif des méthodes HTTP Solana documentées actuellement, y compris les index current/deprecated/unstable séparés ;
- comparaison nom par nom avec l'inventaire bot3 afin d'identifier ajouts, suppressions, méthodes historiques non reprises et niveau de contrat réel (
typedvs raw/generic) ; - statut
stable/deprecated/unstablede chaque méthode ; - matrice méthode -> module/API KSP -> request -> response -> tests -> prerelease candidate ;
- inventaire des contrats bot3 utiles à reprendre/adapter/refondre/abandonner ;
- décision exacte sur les settings publics Transport ;
- décision exacte pools/rôles/capabilities/priority/rate-limit/concurrence ;
- stratégie retry/backoff/timeout ;
- stratégie d'erreurs ;
- ownership des modèles de réponse difficiles ;
- dépendances externes retenues après vérification de versions/features ;
- design du document
std.transportet de l'adapter Config -> Transport ; - nouvelles variables
.env.exampleréellement nécessaires, sans secret concret ; - architecture de tests/fixtures/smoke tests ;
- canaries de dépendances/ownership ;
- hors-périmètre confirmés ;
- critères de clôture ;
- prévision souple des prereleases ;
- gate de sizing de la release entière.
Gate de sizing obligatoire
À la fin de pre.001, répondre explicitement :
La release 0.2.1 peut-elle raisonnablement être entièrement clôturée dans cette session de chat
avec des prereleases de ~15–20 minutes ?
Si la réponse est non ou incertaine, ne pas commencer la grosse implémentation. Scinder immédiatement le périmètre en plusieurs releases 0.2.x, mettre à jour ROADMAP/plan/prompt, puis seulement commencer la première release réduite.
La contrainte de couverture documentaire exhaustive ne doit jamais être contournée en masquant des méthodes pour faire tenir artificiellement la release.
17. Prévision souple recalibrée après le gate pre.001
Le gate a refusé la grosse release HTTP monolithique. La 0.2.1 réduite suit désormais la prévision active du plan 008 :
pre.001 — audit, matrice exhaustive, architecture et sizing
Tranche actuelle, sans grosse implémentation.
pre.002 — crate foundation + settings + JSON-RPC + descriptors
- package/workspace ;
- erreurs KSP ;
- settings/validation ;
- JSON-RPC ;
- metadata méthode/statut/runtime/request-form/retry ;
- base Logging.
pre.003 — client/pool/routing
- endpoint client ;
- pool logique ;
- rôles/capabilities ;
- priorité/fairness/fallback ;
- snapshots redacted.
pre.004 — résilience
- rate-limit/burst ;
- concurrence ;
- cooldown ;
- timeout ;
- retry/backoff borné ;
- classification no-resend des writes futures.
pre.005 — méthodes canari typées
getBalance;getGenesisHash;getHealth;getVersion;- fixtures/tests déterministes.
pre.006 — Config standard
- schema/document/example
std.transport; - registry/file IDs ;
- adapter Config -> Transport ;
- sensibilité/env ;
- integration tests.
pre.007 — clôture
- canaries et matrice 52 current + 14 deprecated historiques ;
- tests ciblés/workspace ;
- cargo tree audits ;
- README/USAGE ;
- documentation durable ;
- cleanup/TODO ;
- prompt
0.2.2 — HTTP Accounts + Tokens; - préparation
rel.001.
Les méthodes typées restantes sont réparties sur 0.2.2–0.2.6 et restent toutes présentes dans la matrice du plan 008.
18. Validation de chaque tranche Rust
Après toute modification Rust :
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
Pendant le développement :
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-config-lib # lorsque Config est modifié
cargo test --workspace est exécuté aux frontières globales prévues par les règles, notamment ouverture/fermeture de version et validation finale.
Exécuter les cargo tree pertinents pour les crates modifiées.
Ne jamais déclarer une commande réussie si elle n'a pas été exécutée.
19. Critères de clôture 0.2.1 après split
La release ne peut pas être déclarée stable tant que :
ksp-onchain-transport-libexiste comme crate KSP propre ;- aucune dépendance Transport -> Config/Store/Program/tracing direct n'existe ;
- les settings publics sont documentés ;
- JSON-RPC, erreurs et descriptors centraux fonctionnent ;
- le registre contient exactement les 52 méthodes courantes et les 14 méthodes Deprecated historiques auditées ;
- le statut runtime
Removedempêche de présenter les 14 anciennes méthodes comme supportées ; - le mécanisme de warning centralisé sait couvrir les contrats deprecated/unstable supportés, notamment les formes legacy documentées ;
- pools/rôles/priority/limites/timeouts/retry retenus sont testés ;
- les réponses restent transport/raw-compatible et ne produisent pas des modèles Program/Store ;
- aucun secret/provider token n'est loggué ;
getBalance,getGenesisHash,getHealthetgetVersionsont exposés par une API typée et testés ;- le document Config Transport + adapter fonctionnent sans inverser l'ownership ;
- les tests ciblés passent ;
- les validations workspace finales passent ;
- le graphe de dépendances est audité ;
README.mdetUSAGE.mdsont complets ;- TODO/hors scope sont fermés ou reportés explicitement ;
- le prompt final
0.2.2 — HTTP Accounts + Tokensest prêt ; - les 48 méthodes courantes reportées restent affectées explicitement à
0.2.2–0.2.6; - la release entière a été clôturée dans la session qui l'a ouverte.
20. Release suivante après split
La release suivante prévue est :
0.2.2 — ksp-onchain-transport-lib / HTTP Accounts + Tokens
Elle doit compléter les 5 méthodes Accounts restantes et les 5 méthodes Tokens, après revérification de la documentation officielle actuelle.
La suite HTTP reste :
0.2.3 Transactions
0.2.4 Blocks
0.2.5 Cluster
0.2.6 Economics + compliance finale
Wallet passe à 0.2.7 et Wallet Desk à 0.2.8. Le cœur cryptographique/format de Wallet restera indépendant du transport ; Wallet Desk composera ensuite Wallet et la surface HTTP stabilisée.
Instruction d'ouverture
Commencer 0.2.1-pre.001 par la relecture des sources internes, l'audit exact du transport bot3 et la consultation de la documentation officielle Solana HTTP actuelle.
Construire ensuite la matrice exhaustive des méthodes et le plan 008 avant toute grosse migration/implémentation.
Ne pas copier ks-onchain-transport tel quel, ne pas introduire WebSocket/Yellowstone par anticipation, ne pas coupler Transport à Config, et ne pas commencer une release dont le sizing ne garantit pas raisonnablement la clôture dans cette même session.