# Delta `0.2.9-pre.004` — fondation `SubscribeRequest` Yellowstone standard ## 1. Base et signal de version Base obligatoire : ```text 0.2.9-pre.3.fix.1 ``` Le gate opérateur fourni ferme `pre.003-fix.001` : ```text cargo fmt --all PASS python3 scripts/audit_rust_workspace_rules.py PASS / clean cargo check --workspace PASS cargo clippy --workspace --all-targets PASS cargo test --workspace PASS Transport unit 354/354 Transport public_api 43/43 Transport release_completeness 36/36 Transport doctests 4/4 cargo tree -p ... fourni/relu cargo tree -p ... -e features fourni/relu cargo tree -p ... --duplicates fourni/relu cargo tree --duplicates fourni/relu ``` Le graphe pertinent reste unifié sur `tonic 0.14.6`, `tonic-prost 0.14.6`, `prost/prost-types 0.14.4`, `yellowstone-grpc-proto 12.6.0` et `solana-pubkey 4.3.0`. Cette tranche non-fix synchronise : ```text workspace.package.version = 0.2.9-pre.4 commit attendu = v0.2.9-pre.004 aucun tag prerelease ``` ## 2. Scope exact `pre.004` matérialise uniquement la fondation N2 du `SubscribeRequest` standard publié : ```text accounts slots transactions transactions_status blocks blocks_meta entry commitment accounts_data_slice ping from_slot ``` Le proto `yellowstone-grpc-proto 12.6.0` a été recontrôlé avant implémentation et conserve exactement ces champs top-level. Sont explicitement hors tranche : ```text champs détaillés Accounts / Slots -> pre.005 champs détaillés Transactions / transaction_status -> pre.006 champs détaillés Blocks / block_meta / entry updates -> pre.007 stream bidi / mutation / Ping-Pong runtime -> pre.008 reconnect / replay / gaps / duplicates -> pre.009 Config V3 / PublicNode -> pre.010/011 SubscribeDeshred -> OUT 0.2.9 standard ``` ## 3. Contrat KSP ajouté Nouveaux types publics : ```text YellowstoneSubscribeFilterName YellowstoneAccountsDataSlice YellowstoneSubscribePing YellowstoneSubscribeAccountFilter YellowstoneSubscribeSlotFilter YellowstoneSubscribeTransactionFilter YellowstoneSubscribeBlockFilter YellowstoneSubscribeBlocksMetaFilter YellowstoneSubscribeEntryFilter YellowstoneSubscribeRequest ``` Les quatre filtres de famille riches sont volontairement des shells typés en `pre.004`. Ils permettent de matérialiser les sept maps et les entrées nommées vides sans anticiper les champs propres aux tranches suivantes. Le wire `yellowstone_grpc_proto::geyser::SubscribeRequest` reste privé : aucun type Tonic/Prost/Yellowstone n'est réexporté au crate root. ## 4. Sémantique maps / noms KSP conserve sept maps logiques indépendantes. ```text map vide = aucun filtre actif dans la famille entrée nommée + message vide = activation explicite d'un groupe vide supporté par le proto ``` Le Protobuf ne distingue pas une map top-level omise d'une map vide ; KSP ne prétend donc pas préserver une différence wire inexistante. Les noms sont : ```text non vides trim exact sans caractère de contrôle <= 128 octets UTF-8 uniques globalement entre les sept maps ``` L'unicité globale évite l'ambiguïté lorsque Yellowstone renvoie seulement les noms correspondants dans `SubscribeUpdate.filters[]`. Le nombre total de groupes nommés est plafonné à `1024` sur l'ensemble des sept maps. ## 5. Champs communs et bounds `commitment` réutilise `SolanaCommitment` et mappe exactement : ```text Processed -> PROCESSED Confirmed -> CONFIRMED Finalized -> FINALIZED ``` `accounts_data_slice` : ```text ordre d'insertion conservé nombre <= 128 length <= 64 MiB offset + length doit rester représentable en u64 length = 0 reste représentable ``` `ping` conserve l'identifiant `i32` exact. `from_slot` conserve l'optional `u64` sans lui attribuer encore une promesse de replay/lossless ; sa sémantique lifecycle reste en `pre.009`. ## 6. Diagnostics et sécurité `Debug` de `YellowstoneSubscribeFilterName` est redacted. `Debug` de `YellowstoneSubscribeRequest` expose uniquement : ```text compteurs par famille commitment nombre de data slices ping from_slot ``` Il n'expose aucun nom de filtre ni futur payload account/transaction/block. Les erreurs déterministes utilisent `ERROR_CODE_INVALID_RPC_PARAMETERS` et n'incluent pas les valeurs de noms/payloads rejetés. ## 7. Dépendances Aucune dépendance ni feature Cargo n'est modifiée dans `pre.004`. Les graphes fournis pour `pre.003-fix.001` restent l'autorité courante ; aucun nouveau `cargo tree` n'est requis spécifiquement par ce delta sauf anomalie de compilation. ## 8. Tests/canaries ajoutés Unit tests : ```text nom vide/whitespace/control/oversized rejeté Debug nom redacted unicité globale cross-family request vide -> sept maps vides + common absent sept entrées nommées vides -> wire exact commitment/ping/from_slot exacts ordre data slices conservé zero-length slice conservée slice length/overflow/count bornés filter-group count borné request Debug sans filter name ``` Public API : construction des sept maps et champs communs depuis le crate root. Release completeness : ```text onze champs top-level présents dans l'adapter bounds communs matérialisés aucun SubscribeDeshred aucun PublicNode/OrbitFlare/Helius runtime aucun raw Tonic/Yellowstone reexport to_wire protobuf non public ``` ## 9. Fichiers ajoutés ```text crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs crates/ksp-onchain-transport-lib/unit_tests/grpc_subscribe.rs deltas/0.2.9/pre.004.md ``` ## 10. Fichiers modifiés ```text Cargo.toml crates/ksp-onchain-transport-lib/src/lib.rs crates/ksp-onchain-transport-lib/tests/public_api.rs crates/ksp-onchain-transport-lib/tests/release_completeness.rs docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md ``` ## 11. Validation de préparation ```text python3 scripts/audit_rust_workspace_rules.py General Rust rule audit: clean Rust export completeness audit: 0 candidate(s) KSP workspace Rust rule audit: clean ``` L'environnement de préparation ne fournit pas Cargo/Rust ; aucune compilation n'est déclarée réussie localement. ## 12. Gate opérateur attendu ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-onchain-transport-lib cargo test -p ksp-core-lib --test workspace_dependencies cargo test --workspace ``` Attendu si aucun fix n'est nécessaire : ```text Transport unit 359 Transport public_api 44 Transport release_completeness 37 Transport doctests 4 ``` Les live smokes restent ignored/opt-in.