36 KiB
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 :
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 :
0.2.9 — Yellowstone gRPC standard/provider-neutral
La première tranche est :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
Subscribe
SubscribeDeshred
SubscribeReplayInfo
Ping
GetLatestBlockhash
GetBlockHeight
GetSlot
IsBlockhashValid
GetVersion
Le SubscribeRequest observé contient notamment :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
ksp-yellowstone-lib
ksp-grpc-lib
ksp-onchain-transport-api
6.2 Provider-neutral obligatoire
Le contrat public initial ne doit pas s'appeler :
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 :
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 :
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 :
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
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 :
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 :
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 :
Subscribe
SubscribeReplayInfo
Ping
GetLatestBlockhash
GetBlockHeight
GetSlot
IsBlockhashValid
GetVersion
et classifier explicitement :
SubscribeDeshred
extensions provider/Triton
méthodes nouvelles apparues depuis ce prompt
Subscribe filters
Auditer :
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 :
account
slot
transaction
transaction_status
block
block_meta
entry
ping
pong
ainsi que les champs/oneofs/optional actuels.
Lifecycle
Décider :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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é :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
deltas/0.2.9/pre.001.md
...
deltas/0.2.9/pre.NNN-fix.MMM.md
deltas/0.2.9/rel.001.md
Commits :
v0.2.9-pre.001
v0.2.9-pre.001-fix.001
...
v0.2.9-rel.001
Archives :
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 :
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 :
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
Puis tests ciblés pertinents :
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-config-lib # si Config modifiée
À la fermeture d'une prerelease technique :
cargo test --workspace
Quand le graphe gRPC est ajouté/modifié :
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
cargo tree --duplicates
Inspecter explicitement :
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 :
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 :
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 :
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 :
0.2.10 — off-chain price transport
Mission pressentie :
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 :
- confirmer la base stable
v0.2.8ou l'archive stable autoritaire ; - vérifier
workspace.package.version = 0.2.8etdeltas/0.2.8/rel.001.md; - lire les sources internes obligatoires dans l'ordre de la section 3 ;
- relire les plans/validations HTTP, WebSocket standard et Helius ;
- inspecter le code réel de Transport/Config avant de proposer les types gRPC ;
- exécuter et enregistrer la baseline avant modification ;
- réauditer immédiatement l'upstream Yellowstone courant : release, changelog,
geyser.proto,solana-storage.proto, client/proto crates ; - dresser la matrice exacte des RPCs, filtres, updates, replay et extensions ;
- séparer standard Yellowstone, extensions Triton/provider et pré-exécution/deshred ;
- auditer licences, MSRV, versions
yellowstone-grpc-*,tonicetprostavant toute dépendance ; - comparer les stratégies client/proto A/B/C ;
- brainstormer credentials, message bounds, backpressure, reconnect, replay/gaps et smoke ownership ;
- dimensionner chaque tranche à environ 15–20 minutes et recalibrer explicitement la prévision souple de la section 12 ;
- créer le plan, la validation et
deltas/0.2.9/pre.001.mdavec le forecast recalibré ; - exécuter les validations de gate disponibles ;
- ne pas ajouter
yellowstone-grpc-client,yellowstone-grpc-proto,tonic,prost, ungrpc_endpointConfig 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.