# Delta `0.2.9-pre.002` — moteur Yellowstone : dépendances + settings/errors + channel minimal ## 1. Objet Cette tranche matérialise uniquement la première fondation **N1 moteur Yellowstone gRPC** validée par `pre.001` : ```text proto Yellowstone publié + dépendances Tonic minimales + settings runtime bornés/redacted + error code initial gRPC + channel Tonic lazy privé ``` Elle ne commence pas encore N2 fonctionnel : aucun unary Yellowstone, aucune metadata/auth, aucune fixture serveur gRPC, aucun `Subscribe`, aucun lifecycle bidi et aucune intégration PublicNode ne sont introduits ici. Version workspace : ```text 0.2.9-pre.2 ``` Commit attendu après validation opérateur : ```text v0.2.9-pre.002 ``` ## 2. Dépendances matérialisées Stratégie B conservée, mais avec le feature set le plus étroit utile à cette tranche : ```text workspace root: tonic = ^0.14, default-features = false yellowstone-grpc-proto = ^12.6, default-features = false ksp-onchain-transport-lib: tonic workspace = true, features = ["channel"] yellowstone-grpc-proto workspace = true, aucune feature locale ``` Explicitement absents : ```text yellowstone-grpc-client tonic-prost direct KSP prost direct KSP prost-types direct KSP tokio-stream nouveau feature tonic du proto feature tonic-compression du proto TLS Tonic ``` La crate publiée `yellowstone-grpc-proto` fournit les messages Protobuf générés utiles sans que KSP copie les `.proto`. Son build utilise son outillage `protoc` vendored ; aucun `protoc` système ni `build.rs` KSP n'est ajouté. Le feature optionnel `tonic` de la crate proto n'est pas activé en `pre.002` : le moteur ne consomme encore aucun client RPC généré. `pre.003` devra justifier explicitement toute feature/dependency supplémentaire nécessaire aux unary, TLS et metadata. ## 3. Settings Yellowstone N1 Ajout de `grpc_settings.rs` avec les contrats publics crate-root : ```text YellowstoneGrpcEndpointUrl YellowstoneGrpcProviderName YellowstoneGrpcClusterName YellowstoneGrpcReconnectSettings YellowstoneGrpcSessionSettings YellowstoneGrpcEndpointSettings YellowstoneGrpcTransportSettings ``` Principes : ```text Transport-owned aucun Config/env aucun WsProtocolKind/WsEndpointSettings URL http/https distincte de HTTP/WS et Debug redacted provider/cluster = descripteurs ouverts, pas des enums commerciaux fermés URL/descripteurs/nombre d’endpoints bornés connect/unary/close timeouts bornés reconnect attempts/backoff bornés request/update channel capacities bornées max inbound/outbound message sizes bornées au moins un endpoint configuré et enabled endpoint names uniques ``` Les defaults servent uniquement de runtime defaults N1 ; ils ne deviennent pas des quotas provider. ## 4. Channel minimal Ajout de `YellowstoneGrpcChannel` dans `grpc_channel.rs`. `prepare()` : ```text valide les settings avant I/O refuse un endpoint disabled construit tonic::transport::Endpoint depuis l'URL sensible applique connect timeout / unary timeout / request buffer utilise connect_lazy() ne réalise aucune connexion réseau ne configure encore ni TLS ni metadata ne recopie pas les erreurs URI Tonic arbitraires dans KspError ``` Le `tonic::transport::Channel` réel est un champ privé et n'a aucun getter public. `Debug` n'expose ni URL, ni channel brut, ni credential potentiel. Cette surface ne constitue pas encore `YellowstoneGrpcSession` : elle prépare seulement la ressource physique minimale qui sera utilisée par `pre.003+`. ## 5. Erreurs et observabilité Nouveau code : ```text onchain_transport/grpc_channel_failed ``` Les erreurs de préparation conservent uniquement des contexts allowlistés sûrs (`endpoint_name`) et n'injectent pas le message d'erreur Tonic/URI dans le contrat KSP. Les logs passent exclusivement par `ksp-logging-lib` et n'émettent que : ```text endpoint_name provider cluster bornes numériques non sensibles ``` Aucune URL n'est loggée. ## 6. Canaries ajoutés Unit tests Transport : ```text gRPC URL http/https + Debug redacted gRPC URL non-http ou surdimensionnée rejetée sans secret echo descripteurs et endpoint inventory plafonnés defaults session bornés zero/excessive/reversed runtime settings rejetés endpoint inventory unique/enabled channel lazy préparé sans réseau channel Debug sans URL/secret endpoint disabled rejeté avant I/O raw proto disponible uniquement côté interne/test ``` Public API : ```text settings N1 constructibles depuis crate root YellowstoneGrpcChannel constructible sans Config nouvel error code public KSP aucun raw client Tonic requis par le consumer ``` Release completeness / workspace dependency canaries : ```text dépendances root/member exactes yellowstone-grpc-client absent Transport -X-> Config aucun couplage Ws* aucun pub use tonic/yellowstone_grpc_proto channel = from_shared + connect_lazy TLS/metadata explicitement absents de pre.002 ``` ## 7. Documentation Les versions opérateur alignées de : ```text docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md ``` sont conservées comme base de mise en forme et avancées pour enregistrer : ```text feature set réellement matérialisé séparation stricte pre.002 / pre.003 surface N1 réellement ouverte état des canaries Cargo gates encore opérateur ``` Le forecast reste inchangé en nombre de tranches : `pre.003` porte toujours TLS/metadata + fixture locale + 7 unary. ## 8. Validation exécutée dans l'environnement de préparation Exécuté réellement : ```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 possède pas Cargo/Rust. Les commandes Cargo ci-dessous ne sont donc **pas déclarées réussies**. ## 9. Gate opérateur requis avant commit Après application du delta : ```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 cargo tree -p ksp-onchain-transport-lib cargo tree -p ksp-onchain-transport-lib --duplicates cargo tree --duplicates ``` Inspecter particulièrement : ```text yellowstone-grpc-proto 12.6.x réellement résolu tonic 0.14.x réellement résolu prost / prost-types / tonic-prost transitifs bytes / http / hyper / hyper-util / tower rustls / tokio-rustls solana-pubkey unifié ou doublons justifiés aucune arrivée de yellowstone-grpc-client features Tonic réellement activées ``` Si la compilation démontre que `yellowstone-grpc-proto` sans feature `tonic` ou Tonic `channel` ne suffit pas à la tranche actuelle, ne pas élargir silencieusement : produire un `pre.002-fix.001` avec la dépendance minimale démontrée. ## 10. Fichiers ajoutés/modifiés ```text Cargo.toml crates/ksp-core-lib/tests/workspace_dependencies.rs crates/ksp-onchain-transport-lib/Cargo.toml crates/ksp-onchain-transport-lib/src/error.rs crates/ksp-onchain-transport-lib/src/grpc_channel.rs crates/ksp-onchain-transport-lib/src/grpc_settings.rs 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 crates/ksp-onchain-transport-lib/unit_tests/grpc_channel.rs crates/ksp-onchain-transport-lib/unit_tests/grpc_settings.rs docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md deltas/0.2.9/pre.002.md ```