# Delta `0.2.7-pre.009` — wrappers WebSocket stables lot A ## Base Base requise : ```text 0.2.7-pre.008-fix.001 workspace.package.version = 0.2.7-pre.8.fix.1 ``` Le checkpoint opérateur de cette base est vert : `cargo fmt --all`, audit Python, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace`. ## Signal de version ```text livraison = 0.2.7-pre.009 workspace.package.version = 0.2.7-pre.9 commit = v0.2.7-pre.009 tag = aucun ``` ## Objectif Ouvrir les trois premiers wrappers WebSocket Solana standard publics sans exposer le moteur générique provider-extension : ```text accountSubscribe / accountUnsubscribe programSubscribe / programUnsubscribe logsSubscribe / logsUnsubscribe ``` L'unsubscribe reste porté par `WsSubscription::unsubscribe()` et traduit l'identité locale stable vers l'ID serveur courant détenu par l'actor. ## `accountSubscribe` Nouvelle configuration dédiée : ```text SolanaAccountSubscribeConfig encoding data_slice commitment ``` Les cinq encodings déjà acquis par Transport sont conservés : `binary`, `base58`, `base64`, `jsonParsed`, `base64+zstd`. `minContextSlot` n'est pas exposé sur ce config WebSocket. Le type partagé upstream le possède, mais le handler PubSub Agave `v4.2.1` l'ignore explicitement ; KSP ne transforme donc pas ce champ en promesse effective. Retour typed : ```text WsSubscription> ``` Le DTO account et le contexte RPC sont réutilisés sans couche de décodage Program/SPL supplémentaire. ## `programSubscribe` Nouvelle configuration dédiée : ```text SolanaProgramSubscribeConfig account: SolanaAccountSubscribeConfig filters with_context ``` Les filtres `dataSize`, `memcmp` et `tokenAccountState` sont conservés. Les bornes déterministes retenues par l'audit HTTP sont également appliquées à la surface WS : maximum quatre filtres et maximum 128 octets pour `SolanaMemcmpBytes::Bytes`. `withContext` conserve les états omitted/false/true et son défaut upstream `false`. `sortResults` n'est pas exposé : cette option appartient à la surface HTTP `getProgramAccounts` et n'est pas consommée par le handler PubSub audité. Le résultat est volontairement une union : ```text SolanaProgramNotification::Account(SolanaKeyedAccount) SolanaProgramNotification::Context(SolanaRpcResponse) ``` Le décodeur accepte donc la forme non contextée documentée et la forme contextée observée sans figer une hypothèse plus stricte que l'upstream. ## `logsSubscribe` Nouveau filtre public : ```text SolanaLogsSubscribeFilter::All SolanaLogsSubscribeFilter::AllWithVotes SolanaLogsSubscribeFilter::Mentions(Pubkey) ``` La forme `Mentions(Pubkey)` encode par construction exactement une adresse, conformément à la contrainte upstream actuelle. Le commitment réutilise `SolanaCommitmentConfig`. La notification typed est : ```text SolanaRpcResponse ``` `SolanaLogsNotification` conserve : ```text signature : String opaque err : null ou valeur JSON TransactionError logs : Vec ordonné ``` Aucune interprétation locale des erreurs transactionnelles ou des messages de log n'est ajoutée à Transport. ## Moteur et lifecycle Les trois wrappers utilisent exclusivement `WsSession::subscribe_typed`, qui reste `pub(crate)`. Les acquisitions précédentes restent communes : ```text IDs locaux stables remote IDs internes ACK/register atomique reconnect fini resubscribe déterministe continuity_gap_count backpressure par subscription overflow_count terminal_error_code cleanup distant best-effort ``` Les paramètres typed sérialisés sont conservés par l'actor et rejoués à l'identique après reconnect avec `ActiveSubscriptions`. ## Tests déterministes ajoutés Sept tests unitaires supplémentaires couvrent : ```text account config exact + absence minContextSlot program config filters/withContext + bornes déterministes program notification contextée et non contextée account + program end-to-end sur serveur WS local + unsubscribe exact logs filters all/allWithVotes/mentions logs notification context/signature/err/logs + err requis logs end-to-end sur serveur WS local + unsubscribe exact ``` Un canari d'API publique supplémentaire vérifie l'adresse des trois méthodes et des nouveaux DTOs depuis la racine de crate. Comptages attendus après compilation : ```text Transport unit tests = 294 Transport public API tests = 33 release completeness = 22 ``` ## Sécurité / observabilité Aucun wrapper ne journalise les paramètres, pubkeys, logs de transaction ou payloads de notification. Les URL et remote subscription IDs restent absents des DTOs et snapshots publics. `SolanaLogsNotification` rend le payload disponible au consumer par API typed, mais il n'est jamais utilisé comme metadata de tracing interne. ## Fichiers ajoutés ou modifiés ```text 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/rpc_accounts.rs crates/ksp-onchain-transport-lib/src/rpc_common.rs crates/ksp-onchain-transport-lib/src/ws_accounts.rs crates/ksp-onchain-transport-lib/src/ws_session.rs crates/ksp-onchain-transport-lib/src/ws_transactions.rs crates/ksp-onchain-transport-lib/tests/public_api.rs crates/ksp-onchain-transport-lib/unit_tests/ws_accounts.rs crates/ksp-onchain-transport-lib/unit_tests/ws_transactions.rs docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md deltas/0.2.7/pre.009.md ``` `ROADMAP.md` et `CHANGELOG.md` restent inchangés pendant cette tranche. ## Validation opérateur requise ```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 --workspace ``` ## Tranche suivante Si ce checkpoint est vert, `0.2.7-pre.010` ouvre le lot stable B : `signatureSubscribe`, `slotSubscribe` et `rootSubscribe`, avec terminaison one-shot de signature et compliance `KSP-TRANSPORT-007` associée.