# Prompt de démarrage `0.2.2` — HTTP Accounts + Tokens + Cluster ## 1. Contexte de reprise La base attendue est la release stable : ```text v0.2.1 ``` `0.2.1` a stabilisé `ksp-onchain-transport-lib` comme foundation HTTP Solana : settings runtime, endpoints/pool/rôles, limites et résilience, JSON-RPC 2.0, registry audité, exécution HTTP générique, Config -> Transport et quatre wrappers typés canari. Les invariants à préserver sont notamment : ```text 52 méthodes HTTP courantes auditées 14 méthodes historiques Deprecated / runtime Removed 4 wrappers typés acquis : getBalance/getGenesisHash/getHealth/getVersion partition planifiée : 4 / 22 / 11 / 15 sur 0.2.1–0.2.4 Transport -X-> Config/Store/Program/tracing direct Config -> Transport autorisé no-resend après dispatch ambigu pour WriteSubmission URLs/provider credentials absents des diagnostics ordinaires ``` La release à ouvrir est : ```text 0.2.2 — HTTP Accounts + Tokens + Cluster ``` La première tranche est : ```text 0.2.2-pre.001 ``` `pre.001` commence par **audit officiel actuel + brainstorming + dimensionnement** avant implémentation lourde. ## 2. Mission Compléter la surface **typée** KSP des familles Accounts, Tokens et Cluster restantes, en réutilisant sans duplication la foundation HTTP de `0.2.1`. La cible issue du plan `0.2.1` contient actuellement 22 méthodes : ### Accounts — 5 ```text getAccountInfo getLargestAccounts getMinimumBalanceForRentExemption getMultipleAccounts getProgramAccounts ``` `getBalance` est déjà acquis en `0.2.1` et ne doit pas être réimplémenté. ### Tokens — 5 ```text getTokenAccountBalance getTokenAccountsByDelegate getTokenAccountsByOwner getTokenLargestAccounts getTokenSupply ``` ### Cluster — 12 ```text getClusterNodes getEpochInfo getEpochSchedule getHighestSnapshotSlot getIdentity getLeaderSchedule getMaxRetransmitSlot getMaxShredInsertSlot getSlot getSlotLeader getSlotLeaders getVoteAccounts ``` `getGenesisHash`, `getHealth` et `getVersion` sont déjà acquis en `0.2.1`. Ces 22 noms sont la **partition KSP actuellement planifiée**, pas une vérité externe immuable. `pre.001` doit revérifier la documentation Solana du jour avant de confirmer le périmètre. ## 3. Sources internes obligatoires Relire avant modification : ```text ROADMAP.md CHANGELOG.md RULES.md docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md docs/validation/003-V0_2_1_ONCHAIN_HTTP.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/rules/RULES_DEPENDENCIES.md docs/rules/RULES_RUST.md docs/rules/RULES_KSP.md docs/rules/FILE_CONTRACTS.md docs/rules/VERSION_WORKFLOW.md docs/rules/PROMPT_STRUCTURE.md crates/ksp-onchain-transport-lib/README.md crates/ksp-onchain-transport-lib/USAGE.md crates/ksp-onchain-transport-lib/src/ crates/ksp-onchain-transport-lib/unit_tests/ crates/ksp-onchain-transport-lib/tests/ crates/ksp-config-lib/src/transport.rs config/std.transport.json config/schemas/std.transport.schema.json ``` Les deltas `0.2.1` servent de trace historique ; ne pas les réécrire. ## 4. Sources externes normatives Au début de `pre.001`, consulter la documentation officielle **actuelle** Solana : ```text https://solana.com/docs/rpc/http ``` Pour chaque méthode cible, revérifier : - nom exact ; - catégorie ; - paramètres et ordre ; - limites de cardinalité ; - objets config ; - commitment/minContextSlot ; - encoding/dataSlice/filters ; - nullable/optional ; - forme exacte du résultat ; - champs versionnés/optionnels ; - erreurs significatives ; - statut stable/deprecated/unstable ; - éventuelle évolution depuis l'audit du 2026-08-17. Revérifier également l'index global afin de détecter une méthode ajoutée/supprimée/déplacée depuis `0.2.1`. Pour une question technique sur une crate externe, utiliser uniquement sa documentation/source primaire actuelle. ## 5. Gate de sizing obligatoire Avant implémentation, répondre explicitement : ```text Les 22 wrappers typés + DTOs partagés + tests + documentation peuvent-ils être clôturés proprement dans cette session ? ``` Si NON : - ne pas compresser artificiellement la release ; - proposer immédiatement un split cohérent de `0.2.2` avant développement lourd ; - mettre à jour la séquence sans perdre aucune méthode. Une prerelease vise environ 15–20 minutes de travail effectif. ## 6. Architecture à préserver Ne pas reconstruire un second transport par famille. Le flux reste : ```text wrapper typé -> descriptor central -> execute_standard_rpc -> pool/admission -> reqwest HTTP -> JSON-RPC validation -> decode typé ``` Réutiliser : - `HttpTransportPool` ; - `HttpRpcMethodDescriptor` ; - `HttpRpcCoverageRelease` ; - request kinds ; - retry metadata ; - JSON-RPC KSP ; - erreurs KSP ; - Logging KSP ; - redaction existante. Aucun wrapper typé ne doit bypasser le pool, la deadline, le retry ou le contrôle central de statut. ## 7. DTOs et wire HTTP Créer des types KSP dédiés à la surface HTTP lorsque cela améliore réellement le contrat public. Principes : - utiliser `ksp_core_lib::Pubkey` pour les adresses publiques ; - ne pas ajouter `solana-client` ni SDK RPC haut niveau ; - ne pas dépendre de Store ou Program ; - ne pas introduire `ksp-interface-lib` par anticipation ; - ne pas décoder des programmes/accounts métier dans Transport ; - conserver les valeurs JSON parsed/encoded à un niveau transport approprié ; - ajouter `base64`, `bs58` ou autre dépendance seulement si le contrat typé retenu en a réellement besoin après audit ; - mutualiser les objets réellement communs (`context`, account data/config, token amount, filters, epoch/leader structures) sans créer un « mega DTO » artificiel. Les types de résultats doivent conserver les `null` et options documentés au lieu d'inventer des valeurs. ## 8. Accounts Auditer et typer notamment : - account absent vs présent ; - `encoding` ; - `dataSlice` ; - `filters` de `getProgramAccounts` ; - `withContext` ; - `sortResults` si toujours documenté ; - limites documentées de `getMultipleAccounts` ; - rent exemption ; - largest accounts et filtres éventuels. Ne pas convertir une réponse account en modèle Program/décodé. ## 9. Tokens Les méthodes Token restent du **transport RPC standard Solana**, pas du decoding SPL Program. Auditer : - `TokenAmount` ; - owner/delegate ; - filtre exclusif `{mint}` ou `{programId}` ; - encodings/dataSlice ; - `minContextSlot` ; - largest accounts ; - supply. Aucune dépendance directe à une crate SPL n'est ajoutée uniquement pour représenter le JSON RPC si des DTOs KSP simples suffisent. ## 10. Cluster Auditer précisément les formes de : - node contact info ; - epoch info/schedule ; - snapshot slots ; - identity ; - leader schedule et slot leaders ; - max retransmit/shred slots ; - slot ; - vote accounts. Conserver les champs optionnels/versionnés documentés et ne pas supposer qu'un provider retourne toujours toutes les extensions. ## 11. Surface raw vs typed `execute_standard_rpc()` reste public et utile, mais : > un appel raw/générique ne compte jamais comme couverture typée de `0.2.2`. Une méthode cible est clôturée seulement lorsque son wrapper public, ses paramètres/configs, son résultat et ses tests sont présents selon la matrice de la release. ## 12. Erreurs, retry et sécurité Conserver les invariants `0.2.1` : - JSON-RPC application error distincte d'une erreur transport ; - timeout/connection/status remappés sans URL sensible ; - `reqwest::Error::without_url()` avant exposition comme source ; - aucune URL/token/body complet dans `Debug`/logs ; - retry uniquement selon descriptor/policy ; - pas de nouvelle hiérarchie d'erreurs locale parallèle à `ksp_core_lib::Error`. Toutes les nouvelles méthodes de `0.2.2` sont a priori des reads, mais `pre.001` doit vérifier leur statut/opération actuel au lieu de l'assumer silencieusement. ## 13. Logging Utiliser uniquement : ```text ksp_logging_lib crate::TRACING_TARGET ``` Le target reste : ```text ksp-onchain-transport-lib ``` Éviter les logs par méthode redondants. Préférer les événements génériques du transport avec metadata sûre : méthode, rôle, endpoint logique, tentative, statut technique. Un niveau `debug` ciblé peut être rouvert temporairement pendant le développement, puis doit revenir à `info`/`warn` dans la dernière prerelease conformément aux règles KSP. ## 14. Config Ne modifier `std.transport.json` ou son schema que si une capacité réellement nécessaire de `0.2.2` ne peut pas être exprimée par le contrat existant. La direction reste : ```text ksp-config-lib -> ksp-onchain-transport-lib ``` Transport ne lit jamais `.env` ou `std::env::var*`. ## 15. Tests Pour chaque méthode typée, couvrir au minimum : - sérialisation de la request ; - résultat success ; - nullable/optional pertinent ; - config/overload pertinent ; - erreur significative ; - invariants de cardinalité/filtre lorsque documentés. Utiliser fixtures déterministes et serveur HTTP local ; Internet est interdit aux tests par défaut. Conserver/étendre les canaries de release : ```text current == inventaire officiel confirmé historical == inventaire officiel confirmé partition de couverture exacte 0.2.1 canaries inchangés 0.2.2 exact method set aucune méthode 0.2.3/0.2.4 déclarée typed-complete prématurément ``` Un smoke Devnet opt-in peut tester un sous-ensemble représentatif, mais il ne remplace pas les fixtures. ## 16. Dépendances Cargo Rappels : - versions/default-features communes au root `[workspace.dependencies]` ; - features d'usage activées dans chaque crate consommatrice ; - toute nouvelle dépendance externe commune est d'abord déclarée au root ; - `cargo tree` normal/doublons/features est rejoué lorsqu'une dépendance ou feature change. Ne pas ajouter une dépendance uniquement parce que bot3 l'utilisait. ## 17. Documentation et clôture La dernière prerelease de `0.2.2` doit : - réauditer la matrice officielle ; - exécuter les canaries finales ; - mettre à jour README/USAGE si la surface publique change ; - mettre à jour la validation durable ; - ramener le logging temporairement élevé à sa baseline ; - préparer le prompt `0.2.3 — HTTP Transactions` ; - préparer un `rel.001` minimal. `CHANGELOG.md` reçoit l'entrée `0.2.2` au moment de la publication stable, pas comme journal de prereleases. ## 18. Prévision souple initiale À confirmer par `pre.001` : | Tranche | Objectif indicatif | |-----------|----------------------------------------------------------------------------------------| | `pre.001` | re-audit officiel, matrice exacte, DTOs communs, dépendances, sizing | | `pre.002` | primitives/configs/results communs Accounts/Token + fixtures de base | | `pre.003` | 5 méthodes Accounts typées + tests | | `pre.004` | 5 méthodes Tokens typées + tests | | `pre.005` | première moitié des 12 méthodes Cluster + tests | | `pre.006` | seconde moitié Cluster + tests | | `pre.007` | canaries de complétude, smoke opt-in, docs finales, prompt `0.2.3`, préparation stable | Ce tableau n'est pas contractuel. Scinder une tranche si elle dépasse le budget ; ne jamais compresser un groupe pour conserver artificiellement un numéro. ## 19. Validations minimales Pendant le développement : ```bash cargo fmt --all cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-onchain-transport-lib ``` À la clôture : ```bash cargo fmt --all cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-onchain-transport-lib cargo test -p ksp-config-lib cargo test -p ksp-core-lib cargo test --workspace 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 ``` Ne jamais déclarer une commande réussie si elle n'a pas été exécutée. ## 20. Critères de sortie `0.2.2` peut devenir stable seulement si : - l'inventaire officiel actuel est revérifié ; - les méthodes ciblées sont précisément celles retenues après cet audit ; - chaque méthode cible possède un contrat public typé et des tests déterministes ; - les quatre canaris `0.2.1` restent inchangés ; - la partition globale ne perd aucune méthode future ; - aucune dépendance/frontière KSP n'est violée ; - redaction/retry/logging restent conformes ; - README/USAGE sont à jour ; - validations Cargo et canaries passent ; - prompt `0.2.3` est prêt ; - `rel.001` ne contient plus de développement fonctionnel nouveau.