# Prompt de démarrage `0.2.9` — Yellowstone gRPC standard/provider-neutral ## 1. Identité de la release et base exacte requise La base attendue est **exclusivement** la release stable : ```text v0.2.8 ``` Ne pas ouvrir `0.2.9` depuis `0.2.8-pre.*`, depuis une archive intermédiaire, depuis un ancien ZIP de travail ou depuis un souvenir de session. Si une archive opérateur de `v0.2.8` est fournie au démarrage, **cette archive réelle devient la première autorité** devant les snippets, prompts historiques, anciens ZIP et mémoire de conversation. Une divergence entre cette base et le présent prompt déclenche un audit explicite ; elle ne se résout jamais par supposition. La release à ouvrir est : ```text 0.2.9 — Yellowstone gRPC standard/provider-neutral ``` La première tranche est : ```text 0.2.9-pre.001 ``` `pre.001` est obligatoirement une tranche **lecture + audit + brainstorming + threat model + dépendances/licences + sizing + planification**. Elle ne doit pas commencer par l'implémentation lourde d'un client gRPC ou par l'ajout opportuniste de crates Yellowstone/Tonic. À l'ouverture, vérifier au minimum : ```text git describe / tag stable si metadata Git disponible workspace.package.version = 0.2.8 deltas/0.2.8/rel.001.md présent prompts/014-V0_2_9_START_PROMPT.md présent ``` État fonctionnel attendu depuis `v0.2.8` : ```text HTTP Solana 52/52 current typed HTTP historiques 14/14 Deprecated/Removed conservées KSP-TRANSPORT-007 appliqué WebSocket Solana standard 9 familles / 18 subscribe-unsubscribe stable WS account/logs/program/root/signature/slot unstable WS block/slotsUpdates/vote Helius LaserStream WebSocket account/logs/program/root/signature/slot/slotsUpdates Helius provider-specific transactionSubscribe / transactionUnsubscribe Helius absent block/vote Helius heartbeat WebSocket Ping control frame, 60 s, actor-owned Config Transport V1 HTTP backward-readable + V2 WS Config -> Transport autorisé Transport -> Config interdit LaserStream gRPC toujours distinct du namespace WebSocket ``` --- ## 2. Mission et résultat attendu `0.2.9` introduit dans `ksp-onchain-transport-lib` une **première fondation Yellowstone gRPC standard et provider-neutral**. La release ne doit pas devenir un SDK Helius, Triton, ERPC, Chainstack, Shyft ou autre fournisseur commercial. Un provider peut servir à une validation réseau si nécessaire, mais il reste un **environnement d'exécution**, jamais le propriétaire du contrat public KSP. Résultat attendu à la clôture : ```text un backend gRPC Yellowstone explicitement distinct de HTTP et WebSocket une surface publique KSP bornée et provider-neutral connexion/TLS/auth metadata générique sans secret exposé contrats typed pour la surface normative effectivement retenue stream/subscription lifecycle borné filtres et updates wire utiles préservés sans perte arbitraire reconnect/continuity semantics explicites, sans promesse lossless implicite Config -> Transport seulement si la shape est validée par le gate README/USAGE et matrice de compliance synchronisés non-régressions HTTP + WebSocket standard + Helius aucune dépendance provider-specific dans les exécutables ``` Le terme **foundation** est important : `pre.001` doit d'abord déterminer quelle part de la surface Yellowstone actuelle peut raisonnablement être livrée dans une release concrète clôturable dans la session. Si la surface normative s'est élargie au point de rendre `0.2.9` surdimensionnée, elle est **scindée avant implémentation lourde**. --- ## 3. Sources de vérité internes obligatoires — ordre de lecture ### 3.1 Entrées et règles globales Lire d'abord, dans cet ordre : ```text RULES.md docs/000-README.md docs/rules/RULES_GENERAL.md docs/rules/RULES_KSP.md docs/rules/RULES_RUST.md docs/rules/RULES_DEPENDENCIES.md docs/rules/RULES_DOCUMENTATION.md docs/rules/FILE_CONTRACTS.md docs/rules/VERSION_WORKFLOW.md docs/rules/PROMPT_STRUCTURE.md ``` Le présent prompt est autonome mais ne remplace pas les règles normatives. Rappels qui conditionnent directement cette session : ```text Rust 2024 unsafe / unwrap / expect / panic interdits en production ? interdit en production retours explicites ; clippy::implicit_return deny #![warn(missing_docs)] #![deny(unreachable_pub)] #![forbid(unsafe_code)] pas de pub mod pub/pub(crate) consommés crate-wide via reexports crate-root private testé depuis unit_tests via super::Item visibilité jamais élargie seulement pour tester unit tests sous unit_tests/ integration tests sous tests/ ksp-logging-lib = propriétaire tracing KSP Config = propriétaire config/env/secrets Transport ne lit jamais std::env pour les secrets runtime ``` Après toute modification Rust : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Une commande non exécutée n'est jamais déclarée réussie. ### 3.2 Architecture à préserver Lire ensuite : ```text docs/architecture/000-README.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/009-ACQUISITION_WORKERS_AND_JOBS.md docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md ``` Points déjà acquis : ```text ksp-onchain-transport-lib possède HTTP + WS + Yellowstone gRPC aucune crate ksp-onchain-transport-api séparée Transport -X-> Config / Store / Program Config -> Transport autorisé providers Yellowstone spécifiques = extensions futures contrat Yellowstone initial = standard/provider-neutral pool/scheduler automatique de sessions = seulement si besoin démontré ``` ### 3.3 Séquence fonctionnelle et héritage Transport Lire : ```text docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md docs/plans/007-V0_2_0_SERIES_PLANNING.md docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md docs/validation/003-V0_2_1_ONCHAIN_HTTP.md docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md deltas/0.2.8/rel.001.md ``` L'objectif est de réutiliser les règles éprouvées de Transport sans forcer HTTP, WebSocket et gRPC dans une abstraction commune artificielle. ### 3.4 Contrats publics réels à réauditer Inspecter le code réel de la base stable, au minimum : ```text Cargo.toml crates/ksp-onchain-transport-lib/Cargo.toml crates/ksp-onchain-transport-lib/README.md crates/ksp-onchain-transport-lib/USAGE.md crates/ksp-onchain-transport-lib/src/lib.rs crates/ksp-onchain-transport-lib/src/constants.rs crates/ksp-onchain-transport-lib/src/settings.rs crates/ksp-onchain-transport-lib/src/ws_settings.rs crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs crates/ksp-onchain-transport-lib/src/ws_session.rs crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs crates/ksp-onchain-transport-lib/tests/public_api.rs crates/ksp-onchain-transport-lib/tests/release_completeness.rs crates/ksp-config-lib/Cargo.toml crates/ksp-config-lib/src/transport.rs crates/ksp-config-lib/unit_tests/transport.rs config/std.transport.json config/schemas/std.transport.schema.json .env.example ``` Ne pas décider une API gRPC à partir d'un ancien prompt si le code stable a déjà évolué. ### 3.5 Références historiques utiles Relire au moins les prompts : ```text prompts/006-V0_2_1_START_PROMPT.md prompts/012-V0_2_7_START_PROMPT.md prompts/013-V0_2_8_START_PROMPT.md ``` Le premier rappelle le gate de sizing Transport, le second le lifecycle streaming standard et le troisième les contraintes provider/secrets/forecast récentes. --- ## 4. Sources externes normatives à réauditer en `pre.001` La fraîcheur est obligatoire. Les versions, RPCs et messages Yellowstone changent activement. Sources primaires à relire depuis leur état courant : ```text https://github.com/rpcpool/yellowstone-grpc https://github.com/rpcpool/yellowstone-grpc/blob/master/README.md https://github.com/rpcpool/yellowstone-grpc/blob/master/CHANGELOG.md https://github.com/rpcpool/yellowstone-grpc/releases https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/geyser.proto https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/solana-storage.proto https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-client https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/rust https://crates.io/crates/yellowstone-grpc-client https://crates.io/crates/yellowstone-grpc-proto ``` Puis vérifier les crates génériques réellement nécessaires si cette stratégie est retenue : ```text tonic prost prost-types tokio-stream futures / futures-util bytes ``` Ne jamais traiter les versions historiques du présent prompt comme des pins. ### Snapshot informatif au 2026-08-23 — à ne pas figer Au moment où ce prompt est préparé, le `geyser.proto` upstream observé expose notamment : ```text Subscribe SubscribeDeshred SubscribeReplayInfo Ping GetLatestBlockhash GetBlockHeight GetSlot IsBlockhashValid GetVersion ``` Le `SubscribeRequest` observé contient notamment : ```text accounts slots transactions transactions_status blocks blocks_meta entry commitment accounts_data_slice ping from_slot ``` L'upstream courant contient aussi des évolutions telles que : ```text CuckooFilter / filtres account/block compressés TokenAccountExpansionControlFlag SubscribeDeshred / deshred transactions reconnect/replay évolué côté client upstream ``` **Ces éléments ne sont pas automatiquement dans le scope `0.2.9`.** `pre.001` doit déterminer leur statut : standard upstream, extension Triton, capacité nouvelle, expérimental, hors fondation ou report explicite. Le `Cargo.toml` master observé le 2026-08-23 montre notamment : ```text workspace license AGPL-3.0 yellowstone-grpc-client (workspace) 13.3.0 yellowstone-grpc-proto (workspace) 12.6.0 tonic / prost / prost-types 0.14 release GitHub observée v14.2.2+solana.4.1.0 (2026-07-27) ``` Ce snapshot est **informatif uniquement** : les numéros du workspace `master`, des crates publiées et des releases GitHub ne suivent pas nécessairement le même rythme. La licence du repository/proto doit en outre être traitée comme un **gate explicite** avant toute copie, génération vendored ou incorporation de source/proto dans KSP MIT ; ne pas déduire la licence d'une crate publiée uniquement de la licence du repository. Vérifier séparément au démarrage de `pre.001` : ```text release GitHub réellement courante crate crates.io réellement courante et sa licence publiée version proto compatible licence du proto/source réellement utilisé MSRV / Rust requis features activées build dependencies / protoc éventuel ``` ### Sources provider — secondaires pour `0.2.9` Les docs Helius/Triton/ERPC/Chainstack/Shyft peuvent servir à comprendre interop, headers, quotas et smokes, mais **elles ne définissent pas à elles seules le contrat standard KSP**. Toute divergence `upstream proto/release` vs `provider documentation` doit être enregistrée explicitement. --- ## 5. État validé à préserver depuis `v0.2.8` ### 5.1 HTTP Ne pas régresser : ```text 52 méthodes courantes typed 14 historiques Deprecated/Removed KSP-TRANSPORT-007 no-resend après dispatch ambigu pour WriteSubmission pool/rôles/capabilities/limites/retry existants ``` Aucun refactor gRPC ne justifie de casser le contrat HTTP. ### 5.2 WebSocket Solana standard Conserver : ```text 9 familles / 18 opérations sessions physiques explicites subscriptions logiques typées local IDs stables remote IDs internes/remappables reconnect/resubscribe/backpressure/shutdown bornés continuity_gap_count signature one-shot Config V2 solana_standard ``` Le gRPC ne doit pas être représenté comme un nouveau `WsProtocolKind`. ### 5.3 Helius LaserStream WebSocket Conserver : ```text HeliusLaserStreamWsSession 7 familles standard supportées transactionSubscribe/unsubscribe typed block/vote absents slotsUpdates unstable heartbeat Helius-only Ping 60 s credentials Helius Config-owned/redacted ``` Helius LaserStream **gRPC** reste conceptuellement un provider Yellowstone futur, pas une extension de cette façade WebSocket. ### 5.4 Config et ownership Conserver : ```text ksp-config-lib = propriétaire documents/env/secrets Config -> Transport Transport -X-> Config Transport -X-> std::env KSP_* .env.example = inventaire canonique des variables runtime ``` Une éventuelle extension `std.transport` pour gRPC doit être décidée par audit. Ne pas supposer automatiquement `format_version = 3` ni réutiliser `ws_endpoints`. ### 5.5 Logging et erreurs Conserver : ```text ksp-core-lib = Error/Result commun ksp-logging-lib = façade tracing Transport n'utilise pas tracing directement secrets/payloads provider absents de Debug/Display/context/logs ``` Les erreurs Tonic/HTTP2/TLS/metadata devront être mappées dans le domaine KSP sans rendre de token ou payload arbitraire. --- ## 6. Frontières architecturales et règles de dépendances ### 6.1 Propriétaire `ksp-onchain-transport-lib` reste propriétaire de Yellowstone gRPC. Ne pas créer sans preuve : ```text ksp-yellowstone-lib ksp-grpc-lib ksp-onchain-transport-api ``` ### 6.2 Provider-neutral obligatoire Le contrat public initial ne doit pas s'appeler : ```text HeliusGrpc... TritonGrpc... ERPC... Chainstack... Shyft... ``` Le provider peut apparaître dans des settings descriptifs ou tests, mais les types protocole/filtres/updates doivent représenter Yellowstone standard lorsque c'est réellement leur sémantique. ### 6.3 Séparation des transports Ne pas réutiliser artificiellement : ```text WsProtocolKind WsEndpointSettings WsSession WsSubscription HeliusLaserStreamWsSession ``` pour représenter gRPC. Le gRPC peut partager des DTOs Solana déjà publics **uniquement lorsque leur sémantique et leur wire sont réellement compatibles**. Une duplication claire et bornée vaut mieux qu'une abstraction fausse. ### 6.4 Firewall des exécutables Les applications/workers/jobs ne doivent pas dépendre directement de : ```text yellowstone-grpc-client yellowstone-grpc-proto tonic/prost pour un besoin protocolaire Yellowstone ``` Ils consomment l'API KSP propriétaire. ### 6.5 Dépendances Cargo Toute nouvelle dépendance externe : ```text déclarée une fois au workspace root consommée .workspace = true features activées localement et minimalement version caret normalisée cargo tree inspecté ``` Les doublons de générations `prost/tonic/http/tower/bytes/rustls` sont particulièrement à surveiller. --- ## 7. Décisions acquises et questions réellement ouvertes ### 7.1 Décisions acquises — ne pas redébattre sans contradiction réelle ```text 0.2.9 cible Yellowstone gRPC standard/provider-neutral la surface vit dans ksp-onchain-transport-lib aucun provider commercial ne devient propriétaire du contrat Helius/Triton/ERPC/Chainstack/Shyft adapters = futur shred/deshred/pré-exécution = hors scope initial sauf reclassification normative explicite Transport ne dépend pas de Config Config peut adapter vers Transport WebSocket et gRPC restent des backends distincts pre.001 = audit/sizing obligatoire une release surdimensionnée est scindée avant implémentation lourde ``` ### 7.2 Questions ouvertes à trancher pendant `pre.001` #### Dépendances / génération wire Comparer au minimum : ```text A. yellowstone-grpc-client + yellowstone-grpc-proto B. yellowstone-grpc-proto + client KSP autour de tonic C. proto/génération KSP minimale bornée D. autre composition démontrée par l'audit ``` Critères : ```text licence compatibilité MIT KSP MSRV versions tonic/prost poids transitif features exposition de types upstream dans l'API publique stabilité/breaking cadence besoin réel de code generation/build.rs/protoc facilité de contrôle redaction/lifecycle/backpressure ``` **Ne pas copier des fichiers source/proto upstream sous licence sans audit licence explicite.** #### Surface RPC exacte Décider si `0.2.9` couvre dans cette release : ```text Subscribe SubscribeReplayInfo Ping GetLatestBlockhash GetBlockHeight GetSlot IsBlockhashValid GetVersion ``` et classifier explicitement : ```text SubscribeDeshred extensions provider/Triton méthodes nouvelles apparues depuis ce prompt ``` #### Subscribe filters Auditer : ```text accounts slots transactions transactions_status blocks blocks_meta entry commitment accounts_data_slice ping from_slot account memcmp/dataSize/token state/lamports filters compressed/Cuckoo filters si encore standards TokenAccountExpansionControlFlag si encore standard ``` #### Updates Auditer toutes les variantes réellement présentes : ```text account slot transaction transaction_status block block_meta entry ping pong ``` ainsi que les champs/oneofs/optional actuels. #### Lifecycle Décider : ```text un stream bidirectionnel par session ? plusieurs logical filter groups dans un SubscribeRequest ? modification dynamique des subscriptions sur le même stream ? close/drop semantics reconnect automatique ou explicite resubscribe déterministe from_slot/replay ownership continuity gap / duplicate observability backpressure et bounded queues ``` #### Auth metadata Décider une shape provider-neutral : ```text aucun header commercial hardcodé dans le contrat standard sans nécessité secrets jamais dans Debug/Display metadata sensible séparée des metadata publiques Config propriétaire des valeurs de secret ``` #### Config Décider seulement après audit : ```text nouveau grpc_endpoints ? nouveau kind/descriptor ? version de document à incrémenter ou non ? TLS/timeout/message-size/reconnect defaults ? références de secrets par placeholders Config ? ``` #### Smoke réseau Déterminer si un endpoint provider accessible permet un smoke sans introduire : ```text secret versionné provider-specific API dans Transport Transport -> Config test cross-crates placé dans Config par facilité ``` Si aucune surface d'intégration KSP dédiée n'existe encore, documenter la limite au lieu de violer l'architecture. --- ## 8. Objectifs et livrables de `0.2.9` Sous réserve du sizing `pre.001`, la release vise : ```text 1. plan Yellowstone gRPC dédié 2. matrice protocolaire/compliance dédiée 3. stratégie dépendances/licence documentée 4. settings gRPC runtime bornés et redacted 5. endpoint/session/client gRPC provider-neutral 6. typed requests/filters/updates pour la surface retenue 7. unary RPCs retenus dans la matrice 8. stream lifecycle borné 9. reconnect/continuity semantics explicites 10. erreurs et observabilité KSP 11. Config adapter si scope confirmé 12. tests déterministes et adversariaux 13. smoke live opt-in si architecture-safe 14. README/USAGE 15. non-régressions HTTP/WS/Helius 16. cargo tree final 17. prompt 0.2.10 ``` Les documents de release attendus à l'ouverture sont normalement : ```text docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md deltas/0.2.9/pre.001.md ``` Le numéro exact peut être ajusté seulement si la base stable contient déjà un nouveau document occupant ces indices. --- ## 9. Hors périmètre explicite Sauf décision de split/reclassification documentée à `pre.001` : ```text Helius LaserStream gRPC adapter spécifique Triton-specific adapter/auth/capabilities ERPC-specific adapter Chainstack-specific adapter Shyft-specific adapter shred delivery SubscribeDeshred / pré-exécution provider extension RabbitStream ou équivalent serveur Geyser/plugin validator Store/persistence workers/jobs d'acquisition backfill historique replay lossless garanti scheduler/pool automatique complexe de sessions gRPC refonte HTTP refonte WebSocket prix offchain Wallet/Wallet Desk Program/Interface ``` `0.2.10 — off-chain price transport` ne doit pas être anticipée ici. --- ## 10. Contraintes sécurité, ressources, lifecycle et API ### 10.1 Credentials / metadata Threat model minimal : ```text token/header provider dans metadata gRPC endpoint potentiellement sensible message d'erreur TLS/tonic contenant metadata ou URI Debug automatique d'un request contenant filtres/adresses provider Status avec message/details arbitraires ``` Exigences : ```text aucun secret dans Debug/Display/KspError/log/snapshot aucune metadata secrète dans DTO public safe Config reste propriétaire des valeurs issues de KSP_SECRET_* Transport reçoit un contrat résolu/opaque ``` ### 10.2 Bornes de ressources Auditer et borner : ```text connect timeout request timeout si unary max inbound message size max outbound message size stream channel capacity logical subscription/filter count nombre de noms de filters longueur des filter names nombre d'accounts/owners/include/exclude/required nombre de memcmp/data slices payload account/block/transaction reconnect attempts/backoff ``` Ne pas recopier aveuglément un quota provider dans le contrat standard KSP. ### 10.3 Backpressure Le stream doit avoir une politique explicite : ```text pas de queue non bornée pas de blocage global silencieux pas de drop silencieux présenté comme lossless état terminal/overflow observable ``` ### 10.4 Reconnect, replay et continuité Ne pas promettre : ```text exactly-once lossless historical replay complet ordre global sans gap ``` sans preuve protocolaire. `from_slot`, `SubscribeReplayInfo` et toute feature client upstream de replay/reconnect doivent être audités séparément : leur présence ne signifie pas automatiquement que KSP peut garantir une continuité parfaite entre providers/nodes. ### 10.5 API publique Favoriser : ```text types KSP stables façade crate-root explicite raw upstream types cachés si leur stabilité est insuffisante #[non_exhaustive] lorsque l'évolution wire le justifie Unknown/bounded fallback seulement si compatible avec KSP-TRANSPORT-007 ``` Ne pas exposer un client Tonic brut permettant de contourner les capabilities ou l'observabilité KSP sans justification. --- ## 11. Première mission `0.2.9-pre.001` — gate obligatoire ### 11.1 Reprise de la base et baseline avant modification Avant changement significatif : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets cargo test --workspace cargo tree -p ksp-onchain-transport-lib cargo tree -p ksp-onchain-transport-lib --duplicates ``` Enregistrer : ```text version Cargo stable versions directes Transport principaux doublons transitifs état tests état docs/plan/validation 0.2.8 ``` ### 11.2 Audit normatif Yellowstone actuel Produire une matrice exhaustive avec, pour chaque RPC/message/capacité : ```text nom source normative présence release stable / master statut standard vs extension request fields response/update variants optional/oneof semantics limites documentées provider-neutral oui/non cible 0.2.9 oui/non/report raison du report preuve/test prévu ``` Inventorier explicitement le service `Geyser` courant et les messages `SubscribeRequest` / `SubscribeUpdate`. ### 11.3 Audit dépendances et licences Avant d'ajouter quoi que ce soit : ```text version stable yellowstone-grpc-client version stable yellowstone-grpc-proto versions tonic/prost nécessaires MSRV features par défaut build dependencies/protoc licences de chaque crate et du repo/proto compatibilité avec la distribution MIT de KSP transitifs Solana/Agave imposés ou non ``` Comparer les stratégies A/B/C de la section 7. Produire les `cargo tree` hypothétiques ou réels nécessaires avant de valider la stratégie. ### 11.4 Audit architecture KSP Décider et documenter : ```text noms des settings/types gRPC séparation HTTP/WS/gRPC ownership du client/session shape public vs wire interne metadata/auth contract Config shape éventuelle error mapping logging target lifecycle/reconnect/backpressure smoke ownership ``` ### 11.5 Threat model Brainstormer au minimum : ```text credential metadata leak URI leak provider Status message/details leak malicious oversized message stream flood/backpressure filter explosion filter-name collision/untrusted names unknown enum/oneof value server half-close client half-close reconnect loop reconnect to different node with divergent slot history duplicate/gap after replay/from_slot late updates after local subscription mutation TLS/certificate failures unary call timeout ``` ### 11.6 Sizing et prévision souple obligatoire Avant implémentation lourde, produire : ```text surface exacte retenue surface explicitement reportée stratégie dependencies/license nombre prévisionnel de prereleases objectif précis de chaque tranche fichiers/contrats principaux attendus preuves/tests/gates par tranche budget nominal <= environ 15–20 min par tranche risques et critères de split ``` La prévision de la section 12 est un **forecast initial**, pas une obligation. Si l'audit démontre que `Subscribe + toutes variantes + unary + replay + Config + lifecycle` ne tient pas raisonnablement dans la release, **scinder avant d'ajouter le client lourd**. Exemple acceptable : conserver `0.2.9` comme foundation connexion + subset canonique et reporter une extension Yellowstone suivante explicitement dans la séquence. ### 11.7 Documents de sortie du gate Créer/mettre à jour au minimum : ```text docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md deltas/0.2.9/pre.001.md ``` ainsi que les index concernés. ### Critères de sortie de `pre.001` Gate positif seulement si : ```text base stable v0.2.8 confirmée baseline opérateur enregistrée sources upstream actuelles relues surface service/proto exhaustive inventoriée standard vs provider-extension classifié SubscribeDeshred explicitement classifié unary RPCs explicitement classifiés replay/from_slot semantics audités strategy dependency choisie ou reportée avec raison licence auditée avant ajout de crate/proto MSRV/features/transitifs audités architecture gRPC distincte de WS décidée metadata/auth strategy provider-neutral décidée Config shape décidée ou explicitement reportée resource/backpressure bounds décidées smoke ownership décidé release dimensionnée forecast recalibré critères de split écrits aucune implémentation lourde non justifiée déjà introduite ``` --- ## 12. Prévision souple initiale des prereleases Prévision de départ, **obligatoirement recalibrée par `pre.001`** : ```text pre.001 audit Yellowstone actuel + service/proto matrix + licences/dependencies + architecture + threat model + sizing preuve : plan + validation matrix + dependency decision + forecast recalibré ; pas de client lourd avant gate pre.002 stratégie proto/client matérialisée + settings/errors gRPC runtime + façade provider-neutral minimale preuve : Cargo/features justifiés + API/settings tests + redaction ; aucun Config coupling pre.003 connexion/TLS/metadata générique + lifecycle session minimal + unary canaries retenus preuve : serveur gRPC local/fixture + timeout/TLS/error mapping + metadata secret-safe pre.004 SubscribeRequest foundation : filter maps + commitment + ping/from_slot + validation/bounds communs preuve : wire exact + omitted/empty semantics + bounds avant I/O + Debug safe pre.005 Accounts + Slots : filtres, data slices et updates typed retenus preuve : account/slot fixtures exactes + malformed/unknown/adversarial cases pre.006 Transactions + transaction_status : filtres et updates typed retenus preuve : account include/exclude/required + vote/failed/signature + status/meta lossless utile pre.007 Blocks + block_meta + entry et autres variantes standard retenues preuve : fixtures exactes + optional/oneof + payload bounds ; split si tranche trop large pre.008 stream bidirectionnel : mutation request, Ping/Pong, close/half-close, backpressure et shutdown bornés preuve : actor/session tests locaux + bounded queues + cleanup déterministe pre.009 reconnect/resubscribe + from_slot/replay semantics + gaps/duplicates + adversarial lifecycle preuve : reconnect local déterministe + continuité explicitement non-lossless si non prouvée pre.010 Config Transport gRPC si retenue + schema/fixtures + mapping Config -> Transport + secret provenance preuve : backward Config + no Transport -> Config + redaction + profile/provider-neutral pre.011 compliance Yellowstone + non-régressions HTTP 52/14 + Standard WS 18/18 + Helius + API/firewall/security preuve : release-completeness + dependency boundaries + workspace ciblé pre.012 smoke live opt-in si stratégie architecture-safe + README/USAGE + cargo tree direct/duplicates final preuve : aucune credential versionnée + provider test-only + docs version-neutral pre.013 validation workspace finale + fermeture plan/matrice/indexes + prompt 0.2.10 preuve : workspace final vert + docs cohérentes + prompt suivant autonome rel.001 publication stable stricte ``` Règles : ```text chaque tranche vise nominalement 15–20 min de travail effectif pre.001 peut fusionner/scinder/déplacer/ajouter des prereleases un fix peut être inséré après n'importe quelle tranche pre.013 n'est pas une deadline le numéro final n'est jamais un critère de clôture une extension normative découverte tardivement peut créer pre.014+ une release trop large doit être scindée avant implémentation lourde ``` Le forecast détaillé vit dans le plan de release. `ROADMAP.md` reste global et `CHANGELOG.md` reste principalement réservé à la clôture stable. --- ## 13. Versionnement, deltas, commits, archives et tags Convention : ```text 0.2.9-pre.001 -> Cargo 0.2.9-pre.1 0.2.9-pre.002 -> Cargo 0.2.9-pre.2 0.2.9-pre.NNN-fix.MMM -> Cargo 0.2.9-pre.N.fix.M si code/build/runtime/config change 0.2.9-rel.001 -> Cargo 0.2.9 ``` Une prerelease non-fix synchronise toujours `workspace.package.version`, même si elle est surtout documentaire. Un fix purement documentaire suit `VERSION_WORKFLOW.md` et ne force pas une version Cargo si aucun artefact code/build/runtime/config/migration n'est modifié. Deltas : ```text deltas/0.2.9/pre.001.md ... deltas/0.2.9/pre.NNN-fix.MMM.md deltas/0.2.9/rel.001.md ``` Commits : ```text v0.2.9-pre.001 v0.2.9-pre.001-fix.001 ... v0.2.9-rel.001 ``` Archives : ```text ksp-general-0.2.9-pre.001.zip ksp-general-0.2.9-pre.NNN-fix.MMM.zip ksp-general-0.2.9-rel.001.zip ``` Les archives delta contiennent uniquement les fichiers ajoutés/modifiés, avec leurs chemins workspace. Aucun tag Git prerelease. Le tag stable attendu est seulement : ```text v0.2.9 ``` Les deltas déjà publiés sont immuables ; un correctif crée un nouveau `fix.MMM`. --- ## 14. Validation opérateur et application Après application d'une tranche Rust : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Puis tests ciblés pertinents : ```bash cargo test -p ksp-onchain-transport-lib cargo test -p ksp-config-lib # si Config modifiée ``` À la fermeture d'une prerelease technique : ```bash cargo test --workspace ``` Quand le graphe gRPC est ajouté/modifié : ```bash cargo tree -p ksp-onchain-transport-lib cargo tree -p ksp-onchain-transport-lib --duplicates cargo tree --duplicates ``` Inspecter explicitement : ```text yellowstone-grpc-* directes éventuelles tonic/prost/prost-types tower/http/hyper/bytes rustls/tokio-rustls Solana/Agave transitifs inattendus versions dupliquées features activées ``` Un doublon transitif peut être accepté s'il est inévitable et documenté. Ne pas dégrader une dépendance moderne uniquement pour forcer une unification artificielle. ### Tests gRPC attendus Selon le scope final : ```text settings validation endpoint/TLS validation metadata redaction connection errors safe unary request/response exact Subscribe request wire filter validation/bounds update oneof decode unknown enum/oneof behavior stream open/send/receive/close server half-close client close Ping/Pong backpressure oversized inbound/outbound provider Status safe mapping reconnect budget resubscribe ordering from_slot/replay semantics duplicate/gap observability shutdown during reconnect public API crate-root release completeness ``` ### Smoke live Le smoke live est **opt-in**. Il ne peut pas justifier : ```text secret versionné std::env lu dans Transport provider API publique hardcodée nouveau smoke cross-crates ajouté à Config par facilité ``` Si une future surface d'intégration/orchestration KSP n'existe toujours pas, documenter la stratégie opérateur au lieu de casser les frontières. ### Frontend/Tauri Aucun build Tauri n'est requis par défaut pour une release Transport pure si aucune application n'est modifiée. --- ## 15. Critères de clôture de `0.2.9` La release ne peut devenir stable que si : ```text surface Yellowstone actuelle réauditée standard vs extension provider explicitement classifié scope final documenté sans dette silencieuse strategy licence/dependencies justifiée backend gRPC distinct de HTTP/WS provider-neutral public API secrets/metadata redacted resource bounds explicites stream lifecycle borné backpressure/shutdown testés reconnect/replay semantics documentés honnêtement aucune promesse lossless non prouvée Config -> Transport seulement aucun Transport -> Config/Store/Program aucun tracing direct dans Transport aucun provider commercial propriétaire du contrat HTTP 52 current + 14 historical non régressé Standard WebSocket 18/18 non régressé Helius WebSocket non régressé public API canaries verts release-completeness vert workspace complet vert cargo tree final inspecté README/USAGE synchronisés matrice Yellowstone fermée forecast réalisé ou recalibré explicitement prompt 0.2.10 préparé ``` Le numéro de la dernière prerelease n'est jamais un critère de clôture. Si les gates ne sont pas verts à `pre.013`, continuer avec `pre.014+` ou des fixes. `CHANGELOG.md` et le statut stable du `ROADMAP.md` sont finalisés à `rel.001`, pas artificiellement avant. --- ## 16. Release/session suivante envisagée La release suivante prévue est : ```text 0.2.10 — off-chain price transport ``` Mission pressentie : ```text introduire ksp-offchain-transport-lib premier besoin réel = prix au minimum SOL/USD et SOL/EUR provider interchangeable derrière un contrat KSP erreurs/timeouts/observabilité ``` Ne pas anticiper `0.2.10` dans Yellowstone en ajoutant des dépendances prix ou une abstraction réseau globale commune on-chain/off-chain. `0.2.11` reste la Price Desk + intégration prix dans Wallet Desk, après validation du composant off-chain spécialisé. --- ## 17. Instruction d'ouverture Au début de la session `0.2.9` : 1. confirmer la base stable `v0.2.8` ou l'archive stable autoritaire ; 2. vérifier `workspace.package.version = 0.2.8` et `deltas/0.2.8/rel.001.md` ; 3. lire les sources internes obligatoires dans l'ordre de la section 3 ; 4. relire les plans/validations HTTP, WebSocket standard et Helius ; 5. inspecter le code réel de Transport/Config avant de proposer les types gRPC ; 6. exécuter et enregistrer la baseline avant modification ; 7. réauditer **immédiatement** l'upstream Yellowstone courant : release, changelog, `geyser.proto`, `solana-storage.proto`, client/proto crates ; 8. dresser la matrice exacte des RPCs, filtres, updates, replay et extensions ; 9. séparer standard Yellowstone, extensions Triton/provider et pré-exécution/deshred ; 10. auditer licences, MSRV, versions `yellowstone-grpc-*`, `tonic` et `prost` avant toute dépendance ; 11. comparer les stratégies client/proto A/B/C ; 12. brainstormer credentials, message bounds, backpressure, reconnect, replay/gaps et smoke ownership ; 13. dimensionner chaque tranche à environ 15–20 minutes et **recalibrer explicitement la prévision souple de la section 12** ; 14. créer le plan, la validation et `deltas/0.2.9/pre.001.md` avec le forecast recalibré ; 15. exécuter les validations de gate disponibles ; 16. **ne pas ajouter `yellowstone-grpc-client`, `yellowstone-grpc-proto`, `tonic`, `prost`, un `grpc_endpoint` Config ou un client gRPC de production avant que le gate dependencies/licence/architecture/sizing soit cohérent**. La première réponse de travail de la nouvelle session doit donc être un **audit/sizing `0.2.9-pre.001` complet avec matrice et forecast recalibré**, pas une implémentation prématurée.