v0.2.8-pre.004
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -335,7 +335,8 @@
|
||||
},
|
||||
"kind": {
|
||||
"enum": [
|
||||
"solana_standard"
|
||||
"solana_standard",
|
||||
"helius_laserstream"
|
||||
]
|
||||
},
|
||||
"url": {
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/ksp-config-lib/USAGE.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
@@ -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<ksp_onchain_transport_lib::WsProtocolKind> {
|
||||
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)
|
||||
|
||||
@@ -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}"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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::<String, String>::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();
|
||||
|
||||
174
deltas/0.2.8/pre.004.md
Normal file
174
deltas/0.2.8/pre.004.md
Normal file
@@ -0,0 +1,174 @@
|
||||
<!-- file: deltas/0.2.8/pre.004.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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.
|
||||
@@ -1,9 +1,9 @@
|
||||
<!-- file: docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 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.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
<!-- file: docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 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.**
|
||||
|
||||
Reference in New Issue
Block a user