From f2a3ec62aaffaba853729d58ee9506859c67bd05 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sun, 23 Aug 2026 14:08:12 +0200 Subject: [PATCH] v0.2.8-pre.004 --- .env.example | 8 +- Cargo.toml | 4 +- config/examples/std.transport.example.json | 8 +- config/schemas/std.transport.schema.json | 3 +- crates/ksp-config-lib/USAGE.md | 6 +- crates/ksp-config-lib/src/transport.rs | 3 +- .../unit_tests/fixtures/std.transport.json | 8 + crates/ksp-config-lib/unit_tests/transport.rs | 51 ++++- deltas/0.2.8/pre.004.md | 174 ++++++++++++++++++ ...0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md | 70 +++---- ...011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md | 75 +++++--- 11 files changed, 335 insertions(+), 75 deletions(-) create mode 100644 deltas/0.2.8/pre.004.md diff --git a/.env.example b/.env.example index 753bdab..a848739 100644 --- a/.env.example +++ b/.env.example @@ -1,5 +1,5 @@ # file: .env.example -# version: 5 +# version: 6 # KSP Logging root directory. Used by config/std.logging.json for relative log output paths. # The current Config document fallback is "logs" when neither the process environment nor .env defines this variable. @@ -34,9 +34,9 @@ KSP_PUBLIC_SOLANA_MAINNET_WS_URL=wss://api.mainnet-beta.solana.com # Keep provider credentials in a KSP_SECRET_* variable; do not copy a real credential-bearing URL into committed JSON. # KSP_SECRET_SOLANA_HTTP_URL=https://provider.example/?api-key=replace-me -# Optional complete private-provider WebSocket endpoint URL used only by the Transport example when explicitly selected. -# Keep provider credentials in a KSP_SECRET_* variable; do not copy a real credential-bearing URL into committed JSON. -# KSP_SECRET_SOLANA_WS_URL=wss://provider.example/?api-key=replace-me +# Helius API key used by the LaserStream WebSocket endpoint in config/examples/std.transport.example.json. +# Keep the real credential only in the process environment or local .env; never commit it. +# KSP_SECRET_HELIUS_API_KEY=replace-me # Fade-in duration in milliseconds used by the common KSP desk splash lifecycle. KSP_DESK_SPLASH_FADE_IN_MS=300 diff --git a/Cargo.toml b/Cargo.toml index c2414a6..a4bf98c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 220 +# version: 221 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.2.8-pre.3" +version = "0.2.8-pre.4" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/config/examples/std.transport.example.json b/config/examples/std.transport.example.json index 76f9cff..2c4cf73 100644 --- a/config/examples/std.transport.example.json +++ b/config/examples/std.transport.example.json @@ -90,12 +90,12 @@ "url": "${KSP_PUBLIC_SOLANA_MAINNET_WS_URL:-wss://api.mainnet-beta.solana.com}" }, { - "name": "mainnet_private_ws", + "name": "mainnet_helius_ws", "enabled": true, - "provider": "private-provider", + "provider": "helius", "cluster": "mainnet-beta", - "kind": "solana_standard", - "url": "${KSP_SECRET_SOLANA_WS_URL:-wss://example.invalid}", + "kind": "helius_laserstream", + "url": "wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me}", "session": { "notification_queue_capacity": 512, "max_active_subscriptions": 2048 diff --git a/config/schemas/std.transport.schema.json b/config/schemas/std.transport.schema.json index 3b45cf2..a7251c9 100644 --- a/config/schemas/std.transport.schema.json +++ b/config/schemas/std.transport.schema.json @@ -335,7 +335,8 @@ }, "kind": { "enum": [ - "solana_standard" + "solana_standard", + "helius_laserstream" ] }, "url": { diff --git a/crates/ksp-config-lib/USAGE.md b/crates/ksp-config-lib/USAGE.md index 4ce2c7c..a91434c 100644 --- a/crates/ksp-config-lib/USAGE.md +++ b/crates/ksp-config-lib/USAGE.md @@ -1,5 +1,5 @@ - + # Utilisation de ksp-config-lib @@ -140,7 +140,9 @@ let ws_settings = transport.ws_settings(); let _ = (http_settings, ws_settings); ``` -`std.transport` V2 conserve `retry` et `profiles[].endpoints[]` pour HTTP, ajoute `ws_defaults` et `profiles[].ws_endpoints[]`, puis exige actuellement `kind = "solana_standard"`. Un `ws_endpoints[].session` optionnel surcharge seulement les paramètres génériques de `WsSessionSettings`. +`std.transport` V2 conserve `retry` et `profiles[].endpoints[]` pour HTTP, ajoute `ws_defaults` et `profiles[].ws_endpoints[]`, puis accepte les protocoles WebSocket `kind = "solana_standard"` et `kind = "helius_laserstream"`. Ce second discriminateur appartient exclusivement au namespace WebSocket et mappe vers `WsProtocolKind::HeliusLaserStream`; il ne préfigure aucun contrat LaserStream gRPC. Un `ws_endpoints[].session` optionnel surcharge seulement les paramètres génériques de `WsSessionSettings`. + +Pour Helius LaserStream WebSocket, l'exemple versionné compose l'URL provider avec `${KSP_SECRET_HELIUS_API_KEY:-replace-me}`. Config reste l'unique propriétaire de cette variable : il résout la clé dans l'URL effective, transmet au Transport un `WsEndpointUrl` utilisable au runtime et redige la valeur dans la projection sûre et les représentations `Debug`. Transport ne lit jamais directement l'environnement. Le même schema enregistré conserve la lecture stricte du V1 historique : dans ce cas `http_settings()` reste disponible et `ws_settings()` retourne `None`. Aucun `WsTransportSettings` vide n'est inventé pour simuler l'absence de WebSocket. diff --git a/crates/ksp-config-lib/src/transport.rs b/crates/ksp-config-lib/src/transport.rs index 4a6e3a1..c6085af 100644 --- a/crates/ksp-config-lib/src/transport.rs +++ b/crates/ksp-config-lib/src/transport.rs @@ -1,5 +1,5 @@ // file: crates/ksp-config-lib/src/transport.rs -// version: 3 +// version: 4 /// Effective standard on-chain Transport configuration resolved from Config and mapped to HTTP and optional WebSocket runtime contracts. #[derive(Clone, Eq, PartialEq)] @@ -443,6 +443,7 @@ fn map_ws_protocol_kind( ) -> ksp_core_lib::Result { return match value { "solana_standard" => std::result::Result::Ok(ksp_onchain_transport_lib::WsProtocolKind::SolanaStandard), + "helius_laserstream" => std::result::Result::Ok(ksp_onchain_transport_lib::WsProtocolKind::HeliusLaserStream), _ => std::result::Result::Err( effective_error(profile, "effective WebSocket protocol kind is unsupported") .with_context("endpoint_name", endpoint_name) diff --git a/crates/ksp-config-lib/unit_tests/fixtures/std.transport.json b/crates/ksp-config-lib/unit_tests/fixtures/std.transport.json index 324243a..16256fc 100644 --- a/crates/ksp-config-lib/unit_tests/fixtures/std.transport.json +++ b/crates/ksp-config-lib/unit_tests/fixtures/std.transport.json @@ -71,6 +71,14 @@ "notification_queue_capacity": 48, "max_pending_requests": 24 } + }, + { + "name": "fixture_helius_ws", + "enabled": true, + "provider": "helius", + "cluster": "mainnet-beta", + "kind": "helius_laserstream", + "url": "wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-fixture-helius-key}" } ] } diff --git a/crates/ksp-config-lib/unit_tests/transport.rs b/crates/ksp-config-lib/unit_tests/transport.rs index 5a4863e..10d86d7 100644 --- a/crates/ksp-config-lib/unit_tests/transport.rs +++ b/crates/ksp-config-lib/unit_tests/transport.rs @@ -1,5 +1,5 @@ // file: crates/ksp-config-lib/unit_tests/transport.rs -// version: 4 +// version: 5 #[test] fn fixture_transport_profile_maps_complete_runtime_contract() { @@ -44,7 +44,7 @@ fn fixture_transport_profile_maps_complete_runtime_contract() { let ws = resolved.ws_settings(); assert!(ws.is_some(), "V2 fixture should expose WebSocket settings"); if let std::option::Option::Some(ws) = ws { - assert_eq!(ws.endpoints().len(), 1); + assert_eq!(ws.endpoints().len(), 2); let endpoint = &ws.endpoints()[0]; assert_eq!(endpoint.name(), "fixture_private_ws"); assert_eq!(endpoint.provider().as_str(), "fixture-provider"); @@ -64,6 +64,13 @@ fn fixture_transport_profile_maps_complete_runtime_contract() { assert_eq!(endpoint.session().max_message_size_bytes(), 33_554_432); assert_eq!(endpoint.session().max_frame_size_bytes(), 8_388_608); assert_eq!(endpoint.session().max_write_buffer_size_bytes(), 524_288); + let helius = &ws.endpoints()[1]; + assert_eq!(helius.name(), "fixture_helius_ws"); + assert_eq!(helius.provider().as_str(), "helius"); + assert_eq!(helius.cluster().as_str(), "mainnet-beta"); + assert_eq!(helius.protocol(), ksp_onchain_transport_lib::WsProtocolKind::HeliusLaserStream); + assert_eq!(helius.url().as_str(), "wss://mainnet.helius-rpc.com/?api-key=fixture-helius-key"); + let _connect_future = ksp_onchain_transport_lib::HeliusLaserStreamWsSession::connect(helius.clone()); } } @@ -259,6 +266,46 @@ fn secret_websocket_url_is_runtime_available_but_safe_projection_is_redacted() { assert!(debug.contains(crate::REDACTED_CONFIG_VALUE)); } +#[test] +fn helius_laserstream_secret_api_key_maps_to_provider_protocol_and_safe_redaction() { + let engine = fixture_engine(); + let engine = match engine { + std::result::Result::Ok(value) => value, + std::result::Result::Err(_) => return, + }; + let canary = "helius-api-key-canary"; + let mut process = std::collections::BTreeMap::::new(); + process.insert("KSP_SECRET_HELIUS_API_KEY".to_owned(), canary.to_owned()); + let environment = crate::ConfigEnvironment::from_maps(process, std::collections::BTreeMap::new()); + let resolved = engine.load_resolved_transport_config(std::option::Option::None, &environment); + assert!(resolved.is_ok(), "Helius LaserStream WebSocket endpoint should map without exposing its API key: {resolved:?}"); + let resolved = match resolved { + std::result::Result::Ok(value) => value, + std::result::Result::Err(_) => return, + }; + let ws = resolved.ws_settings(); + assert!(ws.is_some(), "V2 fixture should expose WebSocket settings"); + if let std::option::Option::Some(ws) = ws { + assert_eq!(ws.endpoints().len(), 2); + let endpoint = &ws.endpoints()[1]; + assert_eq!(endpoint.provider().as_str(), "helius"); + assert_eq!(endpoint.protocol(), ksp_onchain_transport_lib::WsProtocolKind::HeliusLaserStream); + assert_eq!(endpoint.url().as_str(), "wss://mainnet.helius-rpc.com/?api-key=helius-api-key-canary"); + } + let safe_url = resolved.effective().safe_value().pointer("/ws_endpoints/1/url").and_then(serde_json::Value::as_str); + assert_eq!(safe_url, std::option::Option::Some(crate::REDACTED_CONFIG_VALUE)); + let provenance = resolved.effective().provenance_at("/ws_endpoints/1/url"); + assert!(provenance.is_some(), "Helius endpoint URL should retain secret environment provenance"); + if let std::option::Option::Some(provenance) = provenance { + assert_eq!(provenance.len(), 1); + assert_eq!(provenance[0].environment_source(), std::option::Option::Some(crate::ConfigEnvironmentSource::Process)); + assert_eq!(provenance[0].variable_name(), std::option::Option::Some("KSP_SECRET_HELIUS_API_KEY")); + } + let debug = format!("{resolved:?}"); + assert!(!debug.contains(canary)); + assert!(debug.contains(crate::REDACTED_CONFIG_VALUE)); +} + #[test] fn transport_secret_url_provenance_uses_process_and_process_beats_dotenv() { let engine = fixture_engine(); diff --git a/deltas/0.2.8/pre.004.md b/deltas/0.2.8/pre.004.md new file mode 100644 index 0000000..ef48aaf --- /dev/null +++ b/deltas/0.2.8/pre.004.md @@ -0,0 +1,174 @@ + + + +# Delta `0.2.8-pre.004` — Config V2 Helius LaserStream WebSocket + +## 1. Objet + +Cette tranche ouvre Config V2 au protocole WebSocket `helius_laserstream`, matérialise son mapping vers `WsProtocolKind::HeliusLaserStream` et prouve la résolution/redaction de la clé Helius sans modifier le moteur WebSocket ni commencer `transactionSubscribe`. + +Le checkpoint opérateur de `pre.003` est intégralement vert. + +Version workspace : + +```text +0.2.8-pre.4 +``` + +Livraison / commit attendu : + +```text +0.2.8-pre.004 +v0.2.8-pre.004 +``` + +Aucun tag prerelease. + +## 2. Discriminateur Config WebSocket + +Le JSON Schema V2 accepte désormais exactement : + +```text +solana_standard +helius_laserstream +``` + +L'adapter `ksp-config-lib` mappe : + +```text +solana_standard -> WsProtocolKind::SolanaStandard +helius_laserstream -> WsProtocolKind::HeliusLaserStream +``` + +Le discriminateur reste possédé par `profiles[].ws_endpoints[].kind`; aucun alias ou contrat gRPC n'est introduit. + +## 3. Fixture et exemple Helius + +La fixture `ksp-config-lib` ajoute un second endpoint WebSocket : + +```text +name = fixture_helius_ws +provider = helius +cluster = mainnet-beta +kind = helius_laserstream +url = wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-fixture-helius-key} +``` + +`config/examples/std.transport.example.json` remplace l'ancien second endpoint WebSocket provider générique par un exemple Helius explicite : + +```text +name = mainnet_helius_ws +provider = helius +kind = helius_laserstream +url = wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me} +``` + +Le document canonique `config/std.transport.json` reste volontairement inchangé et standard-only : la configuration par défaut ne doit pas embarquer un endpoint provider nécessitant une credential factice. + +## 4. Secret Helius et redaction + +`.env.example` inventorie : + +```text +KSP_SECRET_HELIUS_API_KEY +``` + +sous forme commentée avec placeholder non secret. + +Un nouveau test Config injecte une clé canari et prouve : + +```text +l'URL runtime contient la clé résolue +le protocol runtime vaut HeliusLaserStream +la projection safe_value redige /ws_endpoints/1/url +ResolvedTransportConfig Debug ne contient pas la clé +``` + +Config reste l'unique propriétaire de l'environnement. Transport ne lit pas `std::env`. + +## 5. Composition Config -> Transport + +La fixture principale vérifie maintenant deux endpoints WebSocket : + +```text +fixture_private_ws -> SolanaStandard +fixture_helius_ws -> HeliusLaserStream +``` + +Le second endpoint est également passé au constructeur public `HeliusLaserStreamWsSession::connect` sans polling afin de verrouiller la compatibilité de types Config -> Transport. Les guards runtime du protocole restent propriétaires de Transport. + +## 6. Documentation ciblée + +`ksp-config-lib/USAGE.md` documente les deux valeurs `kind`, le namespace WebSocket du discriminateur Helius et l'ownership/redaction de `KSP_SECRET_HELIUS_API_KEY`. + +Le plan reste propriétaire du forecast ; la validation reste propriétaire des critères et preuves. Aucun nouveau document/fichier fourre-tout n'est créé. + +## 7. Hors périmètre préservé + +Cette tranche ne modifie pas : + +```text +config/std.transport.json +WsSession / actor / reconnect / queues +les six wrappers Helius standard acquis en pre.003 +WsSubscriptionKind +transactionSubscribe / transactionUnsubscribe +transactionNotification +heartbeat provider +HTTP 52/14 +Wallet / Store / Program +``` + +Aucune dépendance Rust n'est ajoutée. + +## 8. Preuve opérateur héritée + +Le checkpoint `pre.003` fourni le 2026-08-23 est : + +```text +cargo fmt --all OK +python3 scripts/audit_rust_workspace_rules.py clean +cargo check --workspace OK +cargo clippy --workspace --all-targets OK +cargo test -p ksp-onchain-transport-lib OK +cargo test --workspace OK +``` + +Les preuves spécifiques Helius standard sont également vertes : 314 tests unitaires Transport, 38 public API, 26 release-completeness et 4 doctests compile-fail. + +## 9. Fichiers de la livraison + +Nouveau : + +```text +deltas/0.2.8/pre.004.md +``` + +Modifiés : + +```text +Cargo.toml +.env.example +config/examples/std.transport.example.json +config/schemas/std.transport.schema.json +crates/ksp-config-lib/src/transport.rs +crates/ksp-config-lib/unit_tests/fixtures/std.transport.json +crates/ksp-config-lib/unit_tests/transport.rs +crates/ksp-config-lib/USAGE.md +docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md +docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md +``` + +## 10. Validation à exécuter + +```bash +cargo fmt --all +python3 scripts/audit_rust_workspace_rules.py +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-config-lib +cargo test -p ksp-onchain-transport-lib +cargo test --workspace +``` + +`pre.004` reste `PREPARED` jusqu'à réception de ce checkpoint. diff --git a/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md b/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md index cf9d04e..b27fe3d 100644 --- a/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md +++ b/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md @@ -1,9 +1,9 @@ - + # Plan `0.2.8` — Helius LaserStream WebSocket -> **Statut : `0.2.8-pre.002` + `pre.002-fix.001` sont validés ; `0.2.8-pre.003` est préparé.** La façade `HeliusLaserStreamWsSession` expose désormais uniquement les six familles standard documentées comme supportées par Helius (`account`, `logs`, `program`, `root`, `signature`, `slot`) en réutilisant le wire standard existant. `block`, `slotsUpdates` et `vote` restent absents de la façade Helius. Le checkpoint Cargo opérateur de `pre.003` reste à exécuter. +> **Statut : `0.2.8-pre.003` est validé ; `0.2.8-pre.004` est préparé.** La façade `HeliusLaserStreamWsSession` possède désormais sa surface standard 6/6 validée. `pre.004` étend uniquement Config V2 au discriminateur WebSocket `helius_laserstream`, ajoute la fixture/exemple Helius et verrouille la résolution/redaction de `KSP_SECRET_HELIUS_API_KEY`, sans ouvrir `transactionSubscribe`. ## 1. Objet, base et état courant @@ -26,14 +26,15 @@ pre.001-fix.001 séparation des façades + fermeture gate Cargo pre.001-fix.002 forecast compact + namespace LaserStream WS/gRPC pre.002 socle protocolaire validé pre.002-fix.001 correction Clippy + normalisation structure documentaire validées -pre.003 six familles standard Helius préparées ; checkpoint opérateur pending +pre.003 six familles standard Helius validées +pre.004 Config V2 Helius + secret/redaction préparés -workspace.package.version courant = 0.2.8-pre.3 -commit attendu = v0.2.8-pre.003 +workspace.package.version courant = 0.2.8-pre.4 +commit attendu = v0.2.8-pre.004 aucun tag prerelease ``` -Le checkpoint opérateur de `pre.002-fix.001` est intégralement vert : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace`. `pre.003` peut donc ouvrir la surface standard Helius sans reporter de dette de gate. +Le checkpoint opérateur de `pre.003` est intégralement vert : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace`. Les six familles standard Helius sont donc acquises sans dette de gate avant l'ouverture de Config Helius en `pre.004`. ## 2. Forecast souple courant @@ -47,9 +48,9 @@ pre.001 DONE — audit Helius actuel + matrice + architecture + threat model + pre.002 DONE — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius + connexion physique partagée + guards, sans duplication de l'actor fix.001 DONE — correction Clippy `implicit_return` + audit/normalisation structure docs -pre.003 PREPARED — surface Helius standard supportée : account/logs/program/root/signature/slot +pre.003 DONE — surface Helius standard supportée : account/logs/program/root/signature/slot + absence typée de block/slotsUpdates/vote sur Helius + non-régression standard 9/9 -pre.004 Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport +pre.004 PREPARED — Config V2 helius_laserstream + schema/fixtures + mapping Config -> Transport + stratégie de secret Helius et redaction URL pre.005 transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe + bounds 50k + maxSupportedTransactionVersion conditionnel @@ -241,12 +242,15 @@ profiles[].endpoints[] profiles[].ws_endpoints[].kind ``` -Le schema et l'adapter n'acceptent actuellement que : +Après `pre.004`, le schema V2 et l'adapter acceptent : ```text solana_standard +helius_laserstream ``` +Le document canonique `config/std.transport.json` reste volontairement une baseline publique Solana sans credential provider. La représentation Helius est portée par la fixture Config et `config/examples/std.transport.example.json`, afin de prouver le contrat sans introduire une fausse clé Helius dans le profil runtime par défaut. + ## 5. Audit Helius officiel du 2026-08-23 ### 5.1 Sources primaires utilisées @@ -592,7 +596,7 @@ La façade standard délègue déjà les neuf familles existantes sans recopier account block logs program root signature slot slotsUpdates vote ``` -La façade Helius ne recevra les six délégations communes qu'en `pre.003`, afin de garder la tranche actuelle limitée au socle protocolaire et aux guards. +La façade Helius a reçu les six délégations communes en `pre.003`, après que `pre.002` a volontairement limité son scope au socle protocolaire et aux guards. ### 7.7 Réalisation de `pre.003` @@ -695,25 +699,27 @@ budget reconnect = fini, inchangé ### 7.12 Config V2 -Évolution : +Contrat matérialisé par `pre.004` : ```text profiles[].ws_endpoints[].kind: solana_standard helius_laserstream + +helius_laserstream -> WsProtocolKind::HeliusLaserStream ``` -Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config. +La fixture Config contient un endpoint Helius typé et l'exemple versionné montre la composition de l'URL mainnet. `config/std.transport.json` reste standard-only pour ne pas imposer de provider/credential dans la configuration par défaut. Les paramètres de `transactionSubscribe` restent runtime et n'appartiennent pas au profil endpoint Config. ### 7.13 Credentials L'api-key reste uniquement dans l'URL résolue : ```text -wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY} +wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY:-replace-me} ``` -Le nom final du secret est matérialisé avec Config. Transport ne lit jamais `std::env` et reçoit un `WsEndpointUrl` redacted. +`KSP_SECRET_HELIUS_API_KEY` est inventorié dans `.env.example` sous forme commentée/placeholder. Config résout la clé au sein de l'URL effective, marque la valeur comme `Secret`, conserve l'URL réelle uniquement pour le runtime légitime et redige la projection sûre ainsi que `Debug`. Transport ne lit jamais `std::env` et reçoit uniquement un `WsEndpointUrl`. ## 8. Threat model provider @@ -884,12 +890,11 @@ validation finale fermée prompt 0.2.9 prêt ``` -## 13. Checkpoint `pre.003` +## 13. Checkpoint `pre.004` -Le checkpoint précédent est fermé par preuve opérateur : +Le checkpoint `pre.003` est fermé par preuve opérateur : ```text -pre.002 + pre.002-fix.001 cargo fmt --all OK python3 scripts/audit_rust_workspace_rules.py clean cargo check --workspace OK @@ -898,31 +903,34 @@ cargo test -p ksp-onchain-transport-lib OK cargo test --workspace OK ``` -`pre.003` prépare maintenant : +Les preuves spécifiques `pre.003` sont acquises : fixture Helius 6/6, 38 tests public API, 26 release-completeness et 4 doctests `compile_fail`, tous verts. + +`pre.004` prépare uniquement : ```text -HeliusLaserStreamWsSession::account_subscribe -HeliusLaserStreamWsSession::program_subscribe -HeliusLaserStreamWsSession::logs_subscribe -HeliusLaserStreamWsSession::signature_subscribe -HeliusLaserStreamWsSession::slot_subscribe -HeliusLaserStreamWsSession::root_subscribe - -block / slotsUpdates / vote -> toujours absents de la façade Helius -transactionSubscribe -> toujours absent -moteur/actor -> inchangé et partagé -new dependency -> aucune +WsProtocolKind Config mapping helius_laserstream -> HeliusLaserStream +JSON Schema V2 kind accepte solana_standard + helius_laserstream +fixture Config endpoint Helius avec interpolation d'api-key +example Config endpoint Helius mainnet explicite +secret KSP_SECRET_HELIUS_API_KEY +safe projection / Debug credential Helius redacted +Config -> Transport endpoint typé HeliusLaserStream +canonical std.transport.json inchangé, standard-only +transactionSubscribe toujours absent +heartbeat toujours absent +new dependency aucune ``` -La validation locale disponible au moment de préparer l'overlay est l'audit Rust workspace, qui reste `clean`. Le checkpoint opérateur requis avant de déclarer `pre.003` `DONE` est : +Le checkpoint opérateur requis avant de déclarer `pre.004` `DONE` est : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets +cargo test -p ksp-config-lib cargo test -p ksp-onchain-transport-lib cargo test --workspace ``` -Si ce checkpoint est vert, `pre.004` ouvre uniquement Config V2 `helius_laserstream`, schema/fixtures, mapping Config -> Transport et stratégie de secret/redaction. +Si ce checkpoint est vert, `pre.005` peut ouvrir la requête typed `transactionSubscribe` / `transactionUnsubscribe`, ses filtres/options et validations déterministes. diff --git a/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md b/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md index ae7a8b5..c803cb1 100644 --- a/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md +++ b/docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md @@ -1,9 +1,9 @@ - + # Validation `0.2.8` — Helius LaserStream WebSocket -> **Statut : `pre.002` + `pre.002-fix.001` validés ; `pre.003` préparé.** La façade Helius contient les six wrappers standard supportés sans DTO/wire provider parallèle. Les nouvelles fixtures et canaries doivent encore passer le checkpoint Cargo opérateur avant que `pre.003` soit marqué `DONE`. +> **Statut : `pre.003` validé ; `pre.004` préparé.** Les six wrappers standard Helius, leurs exact-wire fixtures, canaries publiques/release-completeness et compile-fail sont verts. La tranche courante ajoute uniquement le mapping Config V2 `helius_laserstream`, une fixture/exemple Helius et les preuves de résolution/redaction du secret provider. ## 1. Références @@ -87,7 +87,7 @@ Verdict : doublons transitifs, aucune nouvelle dépendance Helius, aucune anomal [x] doublons ciblés analysés comme transitifs/non bloquants ``` -Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `pre.002-fix.001` sont entièrement verts et fermés. `pre.003` est ouvert.** +Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `fix.001` et `pre.003` sont entièrement verts et fermés. `pre.004` est ouvert.** ## 3. Matrice provider normative @@ -135,16 +135,16 @@ Verdict : **gate `0.2.8-pre.001` positif ; `pre.002` + `pre.002-fix.001` sont en | actor physique | un seul `WsSession` actor partagé | source/runtime canary | pre.002 implémenté | | façade standard | `SolanaStandardWsSession` | public API canary | pre.002 implémenté | | façade Helius | `HeliusLaserStreamWsSession` | public API canary | pre.002 implémenté | -| namespace LaserStream WS | `WsProtocolKind` + `ws_endpoints` possèdent `helius_laserstream` | API/Config/docs canary | décidé | +| namespace LaserStream WS | `WsProtocolKind` + `ws_endpoints` possèdent `helius_laserstream` | API/Config/docs canary | pre.004 préparé | | LaserStream gRPC | backend/type/Config distincts, hors `0.2.8` | absence de réutilisation WS | décidé | | escape hatch Helius | aucun `inner()`/`into_inner()` public | compile-fail/source canary | pre.002 implémenté | | generic Helius `WsSession::connect` | ne doit pas permettre de contourner la façade | invalid protocol pre-I/O canary | pre.002 implémenté | -| Helius unsupported | absent de la façade | compile-fail/API absence canary | pre.003 implémenté, checkpoint pending | -| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 implémenté, checkpoint pending | +| Helius unsupported | absent de la façade | compile-fail/API absence canary | pre.003 validé | +| standard Helius commun | délégation vers le même wire/actor | exact fixture | pre.003 validé | | DTO duplication | seulement si wire/sémantique divergent | public/source audit | décidé | -| Config direction | Config -> Transport uniquement | ownership tests | décidé | +| Config direction | Config -> Transport uniquement | ownership tests | pre.004 préparé | | heartbeat | Helius-only, actor commun | deterministic timers | décidé | -| secret | query URL derrière `WsEndpointUrl` | redaction canaries | décidé | +| secret | query URL derrière `WsEndpointUrl` | redaction canaries | pre.004 préparé | | new Rust dependency | aucune | manifest/tree audit | décidé | ## 5. Contrat `transactionSubscribe` à valider @@ -202,7 +202,7 @@ aucun payload brut dans logs/snapshots [x] SolanaStandard facade n'expose pas transactionSubscribe [x] Helius facade n'expose aucun escape hatch vers le handle générique [x] protocol mismatch rejeté avant I/O — fixture opérateur verte -[ ] 6 familles standard Helius utilisent le wire standard exact — implémenté en `pre.003`, fixture opérateur pending +[x] 6 familles standard Helius utilisent le wire standard exact — fixture `pre.003` opérateur verte [ ] transaction subscribe/ack exact [ ] transaction unsubscribe/result exact [ ] transaction notification dispatch exact @@ -232,6 +232,8 @@ aucun payload brut dans logs/snapshots [x] KSP-TRANSPORT-007 inchangé — tests Transport/workspace verts [x] Config V1 HTTP-only backward readable — tests Config workspace verts [x] Config V2 solana_standard backward readable — tests Config workspace verts +[ ] Config V2 helius_laserstream mappe vers WsProtocolKind::HeliusLaserStream — pre.004 test ajouté, pending +[ ] schema V2 accepte helius_laserstream sans relâcher les autres contraintes — pre.004 fixture pending [x] no Transport -> Config/Wallet/Store/Program/tracing direct — audits/tests ownership verts ``` @@ -239,6 +241,8 @@ aucun payload brut dans logs/snapshots ```text [x] api-key absente de Debug WsEndpointUrl — canaries héritées + pre.002 vert +[ ] KSP_SECRET_HELIUS_API_KEY redacted dans safe_value Config — pre.004 test ajouté, pending +[ ] KSP_SECRET_HELIUS_API_KEY absente de ResolvedTransportConfig Debug — pre.004 test ajouté, pending [ ] api-key absente de Debug settings/session/subscription [ ] api-key absente des KspError safe contexts [ ] URL complète absente des snapshots @@ -255,9 +259,9 @@ Statut initial : **non exécuté**. Contrat cible : opt-in, Config résout l'api-key, Transport ne lit pas l'environnement. Aucun secret n'est versionné ou affiché. Un échec lié au plan/credential provider doit rester distinguable d'une panne du moteur. -## 10. Preuves `pre.002` / `fix.001` et préparation `pre.003` +## 10. Preuves `pre.003` et préparation `pre.004` -Checkpoint `pre.002-fix.001` reçu : +Checkpoint `pre.003` reçu : ```text cargo fmt --all OK @@ -268,25 +272,40 @@ cargo test -p ksp-onchain-transport-lib OK cargo test --workspace OK ``` -Surface `pre.003` préparée : +Preuves spécifiques acquises : ```text -[ ] Helius accountSubscribe/accountUnsubscribe — wrapper présent, fixture pending -[ ] Helius programSubscribe/programUnsubscribe — wrapper présent, fixture pending -[ ] Helius logsSubscribe/logsUnsubscribe — wrapper présent, fixture pending -[ ] Helius signatureSubscribe/signatureUnsubscribe — wrapper présent, fixture pending -[ ] Helius slotSubscribe/slotUnsubscribe — wrapper présent, fixture pending -[ ] Helius rootSubscribe/rootUnsubscribe — wrapper présent, fixture pending -[ ] compile-fail Helius blockSubscribe — doctest ajouté, exécution pending -[ ] compile-fail Helius slotsUpdatesSubscribe — doctest ajouté, exécution pending -[ ] compile-fail Helius voteSubscribe — doctest ajouté, exécution pending -[ ] public API canary des six wrappers — ajouté, exécution pending -[ ] release completeness canary — ajouté, exécution pending +[x] Helius accountSubscribe/accountUnsubscribe +[x] Helius programSubscribe/programUnsubscribe +[x] Helius logsSubscribe/logsUnsubscribe +[x] Helius signatureSubscribe/signatureUnsubscribe +[x] Helius slotSubscribe/slotUnsubscribe +[x] Helius rootSubscribe/rootUnsubscribe +[x] compile-fail Helius blockSubscribe +[x] compile-fail Helius slotsUpdatesSubscribe +[x] compile-fail Helius voteSubscribe +[x] public API canary des six wrappers +[x] release completeness canary ``` -La fixture Helius locale vérifie les noms de méthodes, paramètres, remote IDs et méthodes d'unsubscribe pour les six familles. Elle réutilise volontairement les DTOs Solana standard ; les tests historiques `ws_accounts`, `ws_transactions` et `ws_cluster` restent la preuve du décodage exact des notifications et de leurs variantes. +La fixture Transport rapporte 314 tests unitaires verts, 38 tests public API verts, 26 tests release-completeness verts et 4 doctests compile-fail verts. `pre.003` est donc `DONE`. -Aucun `transactionSubscribe`, changement Config, heartbeat ou nouvelle dépendance n'est introduit dans cette tranche. +Surface `pre.004` préparée : + +```text +[ ] schema `ws_endpoints[].kind` accepte `helius_laserstream` +[ ] adapter Config mappe `helius_laserstream` vers `WsProtocolKind::HeliusLaserStream` +[ ] fixture Config matérialise un endpoint Helius typé +[ ] exemple Transport matérialise Helius mainnet sans credential réel +[ ] `.env.example` inventorie `KSP_SECRET_HELIUS_API_KEY` +[ ] interpolation du secret produit l'URL runtime Helius attendue +[ ] safe_value redige l'URL contenant l'api-key +[ ] Debug de `ResolvedTransportConfig` n'expose pas la clé +[ ] Config produit un endpoint composable avec `HeliusLaserStreamWsSession` +[ ] `config/std.transport.json` canonique reste standard-only +``` + +Aucun `transactionSubscribe`, heartbeat, changement du moteur WebSocket ou nouvelle dépendance n'est introduit dans cette tranche. ## 11. Audit structurel des documents actifs @@ -314,16 +333,16 @@ Constats `pre.002-fix.001` : Aucun split en fichiers supplémentaires n'est retenu : les plans historiques `0.2.5`–`0.2.7` sont de taille comparable ou supérieure, et le contenu du plan `015` reste entièrement centré sur une seule release. Le problème identifié était **l'ordre interne et la duplication de responsabilités**, pas la nécessité d'un nouveau type de document. - -## 12. Gate opérateur `pre.003` +## 12. Gate opérateur `pre.004` ```text [ ] cargo fmt --all [ ] python3 scripts/audit_rust_workspace_rules.py = clean [ ] cargo check --workspace [ ] cargo clippy --workspace --all-targets +[ ] cargo test -p ksp-config-lib [ ] cargo test -p ksp-onchain-transport-lib [ ] cargo test --workspace ``` -Verdict courant : **`pre.003` préparé, non déclaré `DONE` avant ce checkpoint.** +Verdict courant : **`pre.003` DONE ; `pre.004` préparé, non déclaré `DONE` avant ce checkpoint.**