Files

SinuS Von SifriduS c94a54f3e3 v0.2.8-pre.002-fix.001

2026-08-23 13:22:19 +02:00

35 KiB

Raw Blame History

Plan `0.2.8` — Helius LaserStream WebSocket

Statut : 0.2.8-pre.002 est appliqué et testé, mais son gate Clippy requiert pre.002-fix.001. Les tests Transport et workspace sont verts ; le fix corrige cinq clippy::implicit_return dans la nouvelle fixture protocolaire, passe Cargo à 0.2.8-pre.2.fix.1 et réorganise les documents actifs pour garder une séparation nette entre plan, validation et delta. Le moteur physique WsSession reste unique et partagé.

1. Objet, base et état courant

0.2.8 étend le moteur WebSocket publié par 0.2.7 avec la surface Helius LaserStream WebSocket réellement documentée, sans créer un second moteur/session actor et sans confondre WebSocket avec LaserStream gRPC.

Base autoritaire auditée à l'ouverture :

v0.2.7
workspace.package.version initial = 0.2.7
deltas/0.2.7/rel.001.md présent
prompts/013-V0_2_8_START_PROMPT.md présent

État des livraisons :

pre.001              gate audit/sizing Helius
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 appliqué ; tests verts, Clippy en échec ciblé
pre.002-fix.001      correction Clippy + audit/normalisation structure documentaire

workspace.package.version courant = 0.2.8-pre.2.fix.1
commit attendu                    = v0.2.8-pre.002-fix.001
aucun tag prerelease

Le log opérateur de pre.002 confirme : cargo fmt, audit Rust et cargo check --workspace verts ; cargo test -p ksp-onchain-transport-lib et cargo test --workspace verts ; cargo clippy --workspace --all-targets bloque uniquement sur cinq clippy::implicit_return dans unit_tests/ws_protocol_session.rs. Les résultats détaillés restent dans la matrice de validation et le delta du fix, pas dans le plan.

2. Forecast souple courant

Le forecast suit le format historique des plans KSP 0.2.5 et 0.2.7 : un bloc compact, directement révisable, qui porte aussi l'état courant des tranches. Les fix.* sont rattachés à leur prerelease d'origine au lieu d'être présentés comme des tranches planifiées autonomes.

pre.001  DONE — audit Helius actuel + matrice + architecture + threat model + dependencies + sizing
         fix.001 DONE — séparation des façades standard/Helius + moteur unique + gate Cargo fermé
         fix.002 DONE — forecast normalisé + namespace LaserStream WebSocket/gRPC clarifié

pre.002  FIX REQUIRED — socle protocolaire : WsProtocolKind::HeliusLaserStream + façades standard/Helius
         + connexion physique partagée + guards, sans duplication de l'actor
         fix.001 PREPARED — correction Clippy `implicit_return` + audit/normalisation structure docs
pre.003  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
         + stratégie de secret Helius et redaction URL
pre.005  transactionSubscribe request typed + filters/options/tokenAccounts + transactionUnsubscribe
         + bounds 50k + maxSupportedTransactionVersion conditionnel
pre.006  transactionNotification + actor integration + reconnect/resubscribe/unsubscribe races
         + late notifications + backpressure ciblée
pre.007  heartbeat Helius WebSocket/idle + timers + interaction reconnect/control frames/shutdown
pre.008  provider adversarial lifecycle + capability guards + payload/backpressure + security/redaction
pre.009  compliance Helius WebSocket + non-régressions Solana standard 18/18 + HTTP 52/14
         + Config/API/dependency-firewall canaries
pre.010  smoke Helius WebSocket live opt-in si stratégie sûre + README/USAGE
         + cargo tree direct/duplicates final
pre.011  validation workspace finale + fermeture plan/matrice/indexes + prompt 0.2.9
rel.001  publication stable stricte

Règles de lecture et de recalibrage :

une ligne pre.NNN représente une tranche de travail planifiée ; ses fix.MMM éventuels sont regroupés dessous et n'augmentent pas artificiellement le forecast initial ;
l'état (DONE, puis si utile un état intermédiaire explicite) peut être mis à jour directement dans ce bloc lorsque la tranche évolue ;
chaque nouvelle prerelease vise nominalement environ 15–20 minutes de travail effectif ;
un fix reste insérable après n'importe quelle prerelease ;
une tranche qui cache plusieurs problèmes indépendants ou dépasse réellement le budget est scindée ;
une nouvelle ambiguïté normative peut ajouter une prerelease ;
pre.011 n'est ni une deadline ni un critère de clôture : pre.012+ reste autorisé ;
les détails d'exécution restent dans les deltas ; ce bloc sert de forecast courant et de vue d'état, pas de changelog détaillé.

Critères de split déjà identifiés : notification decoding multiforme non documenté, refactor générique du lifecycle nécessaire, évolution Helius normative en cours de release, ou stratégie live nécessitant une surface d'intégration séparée.

3. Sources, baseline et preuves d'ouverture

3.1 Sources internes relues

Les sources internes obligatoires du prompt ont été relues depuis la base stable, notamment :

RULES.md
docs/000-README.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/PROMPT_STRUCTURE.md

docs/architecture/000-README.md
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
docs/architecture/003-COMPONENT_CONTRACTS.md
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md

docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
docs/validation/003-V0_2_1_ONCHAIN_HTTP.md
docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md
docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md

deltas/0.2.7/rel.001.md
docs/IDEAS.md

crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/**
crates/ksp-onchain-transport-lib/tests/**
crates/ksp-config-lib/Cargo.toml
crates/ksp-config-lib/src/transport.rs
crates/ksp-config-lib/unit_tests/transport.rs
config/std.transport.json
config/schemas/std.transport.schema.json
.env.example

Décisions de workflow conservées :

pre.001 reste audit + brainstorming + sizing ;
pre.002-fix.001 corrige la conformité Clippy et normalise l’organisation documentaire sans élargir le scope runtime ;
une prerelease non-fix synchronise toujours Cargo ;
un fix qui modifie du code/test consommé par le build synchronise Cargo selon VERSION_WORKFLOW.md ;
ROADMAP.md reste global ; les détails vivent dans plan/validation/deltas ;
CHANGELOG.md reste principalement réservé à la publication stable.

3.2 Baseline opérateur sur `v0.2.7`

Le log opérateur fourni avant ouverture de 0.2.8 enregistre :

cargo fmt --all                               OK
python3 scripts/audit_rust_workspace_rules.py OK / clean
cargo check --workspace                       OK
cargo clippy --workspace --all-targets        OK
cargo test --workspace                        OK

Les tests live/bench explicitement opt-in restent ignorés par défaut, conformément à leurs contrats.

3.3 Graphes fournis après application de `pre.001`

État observé :

ksp-onchain-transport-lib = 0.2.8-pre.1
futures-util              = 0.3.34
tokio                     = 1.53.1
tokio-tungstenite         = 0.30.0
reqwest                   = 0.13.4
new Helius dependency     = aucune

cargo tree --duplicates ciblé montre uniquement des doublons transitifs attendus dans le graphe courant :

syn            2.0.119 / 3.0.3
webpki-roots   0.26.11 / 1.0.9

Aucun doublon direct introduit par 0.2.8-pre.001, aucun SDK Helius et aucune inversion de dépendance KSP ne sont observés.

4. État hérité de `v0.2.7`

4.1 HTTP à ne pas régresser

52/52 méthodes HTTP courantes typées
14/14 méthodes historiques Deprecated/Removed conservées
KSP-TRANSPORT-007 appliqué
write submissions sans resend après dispatch ambigu

4.2 WebSocket standard publié

Le runtime stable expose neuf familles :

Account
Block
Logs
Program
Root
Signature
Slot
SlotsUpdates
Vote

Partition :

stable   : Account, Logs, Program, Root, Signature, Slot
unstable : Block, SlotsUpdates, Vote

Le moteur possède déjà : actor unique propriétaire du socket, pending JSON-RPC borné, queues bornées, local IDs stables, remote IDs internes/remappables, reconnect fini, resubscribe déterministe, cleanup late ACK, backpressure isolée, continuity_gap_count, one-shot Signature et close().await borné.

4.3 Contrats publics utiles

WsProtocolKind est #[non_exhaustive] et ne contient en v0.2.7 que :

SolanaStandard -> "solana_standard"

WsEndpointSettings fournit déjà :

name
enabled
provider
cluster
protocol kind
WsEndpointUrl redacted
WsSessionSettings

WsSession est un handle Clone vers un actor unique et les wrappers standard sont implémentés directement sur ce type. Cette réalité explique la correction de pre.001-fix.001 : la façade Helius ne doit pas être le même type public surchargé de méthodes incompatibles.

4.4 Config V2

format_version = 2
retry
ws_defaults
default_profile
profiles[].endpoints[]
profiles[].ws_endpoints[].kind

Le schema et l'adapter n'acceptent actuellement que :

solana_standard

5. Audit Helius officiel du 2026-08-23

5.1 Sources primaires utilisées

https://www.helius.dev/docs/rpc/websocket
https://www.helius.dev/docs/api-reference/rpc/websocket-methods
https://www.helius.dev/docs/api-reference/rpc/websocket/transactionsubscribe
https://www.helius.dev/docs/rpc/websocket/transaction-subscribe
https://www.helius.dev/docs/rpc/websocket/token-account-filtering
https://www.helius.dev/docs/api-reference/rpc/websocket/accountsubscribe
https://www.helius.dev/docs/rpc/websocket/account-subscribe
https://www.helius.dev/docs/api-reference/rpc/websocket/programsubscribe
https://www.helius.dev/docs/api-reference/rpc/websocket/slotsupdatessubscribe
https://www.helius.dev/docs/faqs/websockets
https://www.helius.dev/docs/api-reference/rpc/websocket/llms.txt
https://www.helius.dev/docs/llms.txt

Les documents llms.txt servent d'index et de source secondaire. Lorsqu'ils divergent d'une page de référence dédiée ou de la page exhaustive des méthodes, la divergence est enregistrée.

5.2 Terminologie et endpoints

nom produit courant      = LaserStream WebSocket
ancien nom               = Enhanced WebSockets, intégré à LaserStream WebSocket
mainnet                  = wss://mainnet.helius-rpc.com/?api-key=...
devnet                   = wss://devnet.helius-rpc.com/?api-key=...
credential               = api-key en query URL, Secret
Gatekeeper beta          = hors 0.2.8
LaserStream gRPC         = distinct, hors 0.2.8

5.3 Inventaire provider retenu

standard supporté : account, logs, program, root, signature, slot
Helius extension   : transactionSubscribe / transactionUnsubscribe
non supporté       : block, slotsUpdates, vote

transactionUnsubscribe est documenté dans la référence transactionSubscribe avec :

method = transactionUnsubscribe
params = [remoteSubscriptionId]
result = true

La référence précise que quelques notifications in-flight peuvent encore arriver après l'unsubscribe.

5.4 Divergence `slotsUpdatesSubscribe`

Les sources Helius se contredisent :

websocket-methods classe slotsUpdatesSubscribe/slotsUpdatesUnsubscribe parmi les méthodes unstable non supportées ;
la page individuelle indique que la méthode est unstable et peut ne pas être supportée ;
websocket/llms.txt la place aussi dans une section « Stable, Helius-supported ».

Décision KSP :

HeliusLaserStreamWsSession n'expose pas SlotsUpdates

Une validation interne garde aussi un rejet avant I/O si un descriptor incompatible atteint le moteur par un chemin interne ou de compatibilité.

5.5 `transactionSubscribe`

Filtre courant :

vote             Option<bool>
failed           Option<bool>
signature        Option<string>
accountInclude   Option<string[]>  max 50_000
accountExclude   Option<string[]>  max 50_000
accountRequired  Option<string[]>  max 50_000
tokenAccounts    none | balanceChanged | all

Options :

commitment                       processed | confirmed | finalized
encoding                         base58 | base64 | jsonParsed
transactionDetails               full | signatures | accounts | none
showRewards                      bool
maxSupportedTransactionVersion   integer

maxSupportedTransactionVersion est requis lorsque transactionDetails vaut accounts ou full.

Notification :

method = transactionNotification

La documentation ne détaille pas avec la même précision chacun des quatre modes de transactionDetails. KSP ne doit pas inventer ces formes : types précis pour les formes prouvées et fallback borné uniquement si nécessaire.

5.6 `accountSubscribe` / `programSubscribe` et `notifyOn`

notifyOn est documenté mais marqué :

deprecated
no-op depuis Agave 4.2
suppression future annoncée

Décision : ne pas l'ajouter aux DTOs KSP.

Les pages continuent à employer « enhanced/filtered accountSubscribe » sans publier un wire provider-specific supplémentaire assez précis pour une API typed. Ce point reste reporté explicitement.

6. Matrice normative Helius WebSocket

Famille	Paire	Classe	Support Helius retenu	Surface publique Helius	Paramètres/options utiles	Notification	Stratégie KSP/test
`account`	`accountSubscribe` / `accountUnsubscribe`	Solana standard	Oui	présente	contrat standard ; `notifyOn` omis	`accountNotification`	DTO/wire standard partagé
`block`	`blockSubscribe` / `blockUnsubscribe`	Solana unstable	Non	absente	aucune émission provider	théorique	façade Helius sans méthode + guard interne
`logs`	`logsSubscribe` / `logsUnsubscribe`	Solana standard	Oui	présente	contrat standard	`logsNotification`	DTO/wire standard partagé
`program`	`programSubscribe` / `programUnsubscribe`	Solana standard	Oui	présente	contrat standard ; `notifyOn` omis	`programNotification`	DTO/wire standard partagé
`root`	`rootSubscribe` / `rootUnsubscribe`	Solana standard	Oui	présente	aucun paramètre	`rootNotification`	wrapper partagé
`signature`	`signatureSubscribe` / `signatureUnsubscribe`	Solana standard	Oui	présente	one-shot conservé	`signatureNotification`	wrapper partagé + terminal close
`slot`	`slotSubscribe` / `slotUnsubscribe`	Solana standard	Oui	présente	aucun paramètre	`slotNotification`	wrapper partagé
`slotsUpdates`	`slotsUpdatesSubscribe` / `slotsUpdatesUnsubscribe`	Solana unstable	Non	absente	aucune émission provider	théorique	façade Helius sans méthode + divergence documentée
`vote`	`voteSubscribe` / `voteUnsubscribe`	Solana unstable	Non	absente	aucune émission provider	théorique	façade Helius sans méthode + guard interne
`heliusTransaction`	`transactionSubscribe` / `transactionUnsubscribe`	Helius extension	Oui	présente	filtres/options/`tokenAccounts`	`transactionNotification`	DTOs Helius + actor partagé

Statut :

SolanaStandardWsSession : 9 familles / 18 opérations standard
HeliusLaserStreamWsSession : 6 familles standard supportées + 1 famille Helius

La compliance standard KSP reste 18/18 pour SolanaStandard.

7. Architecture et frontières de protocole

La première version du plan prévoyait un unique WsSession public exposant toutes les méthodes standard et une matrice de capabilities rejetant à l'exécution les méthodes incompatibles avec Helius.

Cette approche est remplacée par une séparation plus forte : les méthodes impossibles pour un protocole doivent être absentes de sa façade publique.

Architecture cible :

                           moteur physique commun
                                  WsSession
                         actor/socket/reconnect/queues
                     pending/remapping/backpressure/close
                                    │
                    ┌───────────────┴────────────────┐
                    │                                │
                    ▼                                ▼
        SolanaStandardWsSession          HeliusLaserStreamWsSession
        façade protocole standard         façade protocole Helius
                    │                                │
          9 familles standard              6 familles communes
                                             + transaction
                                             + policy heartbeat

Principe :

ce qui est dupliqué/séparé :
  façade publique de protocole
  méthodes disponibles
  policy/capabilities du protocole
  DTOs provider-specific lorsque le wire diverge
  heartbeat/provider behavior

ce qui reste partagé :
  socket physique
  actor unique
  command queue / pending JSON-RPC
  WsSubscription<T>
  local/remote IDs et remapping
  reconnect/resubscribe machinery
  backpressure
  shutdown
  snapshots/redaction
  DTOs wire réellement identiques

Aucun HeliusWsClient, aucun second actor et aucune copie du lifecycle physique ne sont autorisés.

7.1 Surface `SolanaStandardWsSession`

La façade standard expose exactement les neuf familles acquises en 0.2.7 :

account
block
logs
program
root
signature
slot
slotsUpdates
vote

Les 18 opérations standard restent donc présentes et testées : 9 subscribe + 9 unsubscribe.

7.2 Surface cible `HeliusLaserStreamWsSession`

À partir de pre.003, la façade Helius doit exposer uniquement les familles de subscription suivantes :

account
logs
program
root
signature
slot
transaction

Même après pre.003, elle n'expose pas :

block
slotsUpdates
vote

L'objectif est qu'un appel du genre :

helius.block_subscribe(...)

soit absent de l'API Helius et donc impossible à écrire contre la façade Helius, plutôt que simplement rejeté après construction d'une requête.

La validation runtime avant I/O reste conservée en défense en profondeur pour les constructeurs, descriptors internes et chemins de compatibilité.

7.3 Compatibilité de `WsSession` publié en `0.2.7`

WsSession est déjà public et ses wrappers standard sont déjà stabilisés. 0.2.8 ne les supprime pas et ne casse pas les consommateurs existants.

Décision cible :

WsSession
  reste le handle/moteur physique partagé
  conserve la compatibilité publique standard publiée en 0.2.7
  ne devient pas l'entrée publique Helius générique

SolanaStandardWsSession
  nouvelle façade explicite/recommandée pour le protocole standard
  délègue au même WsSession

HeliusLaserStreamWsSession
  nouvelle façade Helius
  contient/délègue à un WsSession privé
  n'expose aucun getter/into_inner permettant de contourner sa surface en 0.2.8

Le chemin public historique WsSession::connect doit rester compatible avec SolanaStandard. Lors de l'introduction de HeliusLaserStream, il ne doit pas permettre d'obtenir un WsSession générique Helius puis d'appeler une méthode standard non supportée. Le socle de pre.002 doit donc extraire/réutiliser un chemin de connexion physique interne partageable, tout en gardant un garde protocolaire sur les constructeurs publics.

7.4 DTOs communs versus DTOs Helius

Les six familles communes réutilisent les DTOs standard lorsque le wire et la sémantique sont réellement identiques :

account
logs
program
root
signature
slot

Ne pas créer artificiellement HeliusAccountNotification, HeliusLogsNotification, etc. si ces types seraient des copies strictes des types standard.

Créer des types Helius distincts dès que le contrat diverge ou n'existe pas en standard :

HeliusTransactionSubscribeFilter
HeliusTokenAccountsMode
HeliusTransactionEncoding
HeliusTransactionSubscribeOptions
HeliusTransactionNotification / formes prouvées

Une option provider-specific ne doit jamais être injectée dans un DTO Solana standard pour éviter une duplication de façade.

7.5 Kind de subscription et registry interne

WsSubscriptionKind appartient au lifecycle/snapshot commun et non à la capacité d'invocation publique. Il peut être étendu de manière #[non_exhaustive] avec une variante provider-explicite pour transaction si cela minimise la rupture du snapshot existant.

Le point obligatoire n'est pas de dupliquer cet enum à tout prix ; le point obligatoire est que :

la façade Helius ne puisse pas invoquer Block/SlotsUpdates/Vote
la façade standard ne puisse pas invoquer HeliusTransaction
le registry/actor interne reste unique et provider-neutral

Si pre.002 montre qu'un descriptor interne distinct rend le snapshot plus propre sans rupture publique, cette forme peut être retenue. Aucun refactor ne doit toutefois remplacer une séparation de façade simple par une hiérarchie générique lourde.

7.6 Réalisation de `pre.002`

Le socle concret retient une séparation minimale sans dupliquer les wrappers wire ni l'actor :

WsSession::connect(endpoint)
  -> accepte uniquement WsProtocolKind::SolanaStandard
  -> compatibilité publique 0.2.7 conservée

SolanaStandardWsSession::connect(endpoint)
  -> guard SolanaStandard
  -> WsSession::connect_for_protocol(...) interne
  -> même connect_physical / même run_ws_session_actor
  -> délègue les 9 wrappers standard existants

HeliusLaserStreamWsSession::connect(endpoint)
  -> guard HeliusLaserStream
  -> WsSession::connect_for_protocol(...) interne
  -> même connect_physical / même run_ws_session_actor
  -> lifecycle seulement en pre.002
  -> aucune subscription Helius exposée avant pre.003

WsProtocolKind possède désormais :

SolanaStandard      -> solana_standard
HeliusLaserStream   -> helius_laserstream

Les mismatches de constructeur sont rejetés avec ERROR_CODE_INVALID_SETTINGS et des contextes sûrs expected_protocol / actual_protocol, avant toute tentative réseau. Aucune URL ni credential n'entre dans cette erreur.

La façade Helius conserve son WsSession interne privé et ne fournit ni inner() ni into_inner(). Des canaries compile_fail verrouillent l'absence de block_subscribe et de l'escape hatch à ce stade. Une canary source confirme aussi que le module de façade ne contient ni second tokio::spawn, ni tokio_tungstenite, ni WsSessionCommand.

La façade standard délègue déjà les neuf familles existantes sans recopier leurs encoders/decoders :

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.

7.7 Protocol kind et namespace LaserStream

Retenir pour WebSocket uniquement :

WsProtocolKind::HeliusLaserStream
as_str() = "helius_laserstream"
provider metadata attendu = "helius"
Config owner = profiles[].ws_endpoints[].kind
façade publique = HeliusLaserStreamWsSession

helius_laserstream n'est donc pas un nom de transport générique Helius : il est possédé par le namespace WebSocket (WsProtocolKind / ws_endpoints). Dans toute prose, log safe metadata, documentation ou API où ce contexte n'est pas déjà évident, employer Helius LaserStream WebSocket et non le raccourci ambigu « Helius LaserStream ».

Le futur Helius LaserStream gRPC reste un backend/provider distinct, hors 0.2.8. Il ne doit jamais être représenté par WsProtocolKind, WsEndpointSettings, HeliusLaserStreamWsSession ni ws_endpoints. Son éventuel protocol kind, discriminateur Config et façade seront décidés par l'audit de la release gRPC concernée ; ils devront porter un ownership gRPC explicite et ne pourront pas réutiliser le contrat WebSocket par simple alias de nom produit.

Cette règle permet de conserver le code court helius_laserstream dans son conteneur WS sans créer d'ambiguïté future entre les deux produits portant le nom LaserStream.

7.8 Connexion et propriété du moteur

Cible de pre.002 :

un seul code de création/spawn de l'actor physique
un seul type de socket physique
un seul registry pending/subscriptions
un seul lifecycle reconnect/backpressure/shutdown

Les façades délèguent à ce moteur commun. Le mécanisme précis d'extraction du chemin physique est choisi en pre.002 à partir du code réel, avec les invariants suivants :

pas de clone du run_ws_session_actor
pas de second WsSessionCommand
pas de second snapshot model
pas de public escape hatch Helius -> raw standard WsSession

7.9 Capability validation defense-in-depth

La séparation de façade est la première barrière. Une matrice interne reste utile :

SolanaStandard:
  Account Block Logs Program Root Signature Slot SlotsUpdates Vote -> allowed
  HeliusTransaction -> rejected

HeliusLaserStream:
  Account Logs Program Root Signature Slot HeliusTransaction -> allowed
  Block SlotsUpdates Vote -> rejected

Cette matrice sert aux guards de constructor/descriptor, aux canaries et à la protection interne ; elle ne remplace plus la séparation de l'API publique.

7.10 Heartbeat/idle ownership

Helius annonce un timeout d'inactivité de 10 minutes et recommande des pings périodiques.

Décision : heartbeat provider-owned dans l'actor existant, activé pour WsProtocolKind::HeliusLaserStream (LaserStream WebSocket), sans champ public générique ajouté à WsSessionSettings dans cette release.

Politique cible :

intervalle nominal = 60 s
frame               = WebSocket Ping control frame
actif               = session Active seulement
close/failure       = timer annulé
reconnect réussi    = timer réarmé
write failure       = chemin disconnect/reconnect existant
budget reconnect    = fini, inchangé

7.11 Config V2

Évolution :

profiles[].ws_endpoints[].kind:
  solana_standard
  helius_laserstream

Les paramètres de transactionSubscribe restent runtime et n'appartiennent pas au profil endpoint Config.

7.12 Credentials

L'api-key reste uniquement dans l'URL résolue :

wss://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY}

Le nom final du secret est matérialisé avec Config. Transport ne lit jamais std::env et reçoit un WsEndpointUrl redacted.

8. Threat model provider

8.1 Secret dans query URL

Risque : fuite par Debug, handshake error, logs tungstenite ou contexte d'erreur.

Mesures : WsEndpointUrl opaque/redacted, mapping vers metadata sûre, canaris avec secret reconnaissable.

8.2 Contournement de façade

Risque nouveau identifié par le fix : obtenir un handle générique Helius puis appeler une méthode standard non supportée.

Mesures :

HeliusLaserStreamWsSession possède son inner privé
aucun inner()/into_inner() public en 0.2.8
constructeur générique historique gardé standard-only
validation protocolaire interne avant I/O

8.3 Heartbeat concurrent avec reconnect/close

Timer détenu par l'actor, actif seulement en Active, reset/cancel avec lifecycle, test déterministe par cadence raccourcie interne/test-only.

8.4 Late notifications et IDs distants

Après transactionUnsubscribe, les messages in-flight sont possibles. L'unsubscribe local gagne ; un remote ID tardif ne réactive pas la subscription.

8.5 Payload transaction volumineux

Conserver max_message_size_bytes, max_frame_size_bytes, queue bornée par subscription et absence de payload brut dans les logs/snapshots.

8.6 Filtres 50k

Valider chaque liste avant I/O, ne pas logguer les valeurs et éviter les clones inutiles.

8.7 Continuité

reconnect              oui
resubscribe            oui
continuity_gap_count   oui
backfill               non
historical replay      non
lossless WebSocket     non

9. Dépendances

Versions observées dans le graphe opérateur :

futures-util       0.3.34
tokio              1.53.1
tokio-tungstenite  0.30.0
reqwest             0.13.4

Verdict : aucune nouvelle dépendance.

Le moteur courant sait déjà gérer TLS WebSocket, Ping/Pong, timers Tokio, futures sink/stream et JSON serde. Un SDK Helius dupliquerait des choix de lifecycle que KSP possède déjà.

10. Stratégie de validation et smoke

10.1 Architecture/façades

Prévoir :

public API canary SolanaStandardWsSession
public API canary HeliusLaserStreamWsSession
Helius facade sans block/slotsUpdates/vote
Solana facade sans transactionSubscribe
Helius facade sans escape hatch vers WsSession générique
WsSession historique standard toujours disponible
un seul actor/socket implementation path
constructeur protocolaire invalide rejeté avant I/O

L'absence d'une méthode peut être couverte par compile-fail doctest/canary sans ajouter de dépendance de test si cette forme reste compatible avec les règles Rust KSP.

10.2 Helius transaction/lifecycle

transactionSubscribe serialization exacte
transactionUnsubscribe exact
transactionNotification method exact
ack/error RPC
50k/50k/50k bounds
maxSupportedTransactionVersion requirement
tokenAccounts exact enum
late notifications après unsubscribe
remote id remapping reconnect/resubscribe
provider RPC error sans session failure
heartbeat timer + cancellation
shutdown pendant heartbeat/reconnect
oversized frame/message
queue overflow isolé
URL/api-key redaction

10.3 Non-régressions

standard WS 18/18 pour SolanaStandard
partition unstable 3/9 inchangée
signature one-shot inchangée
HTTP 52 current + 14 historical
KSP-TRANSPORT-007
Config V1 HTTP-only backward readable
Config V2 solana_standard backward readable
no Transport -> Config/Wallet/Store/Program/tracing direct

10.4 Smoke live Helius

Le live reste opt-in et secondaire par rapport aux fixtures déterministes.

Stratégie : Config résout le secret et construit l'endpoint Helius ; Transport ne lit jamais l'environnement. Si aucune surface d'intégration sûre n'est disponible, le smoke opérateur peut rester documenté plutôt que d'introduire une dépendance inverse.

11. Questions explicitement reportées

wire exact d'un éventuel enhanced/filtered accountSubscribe provider-specific
modes transactionNotification non suffisamment documentés
Gatekeeper beta
provider metering/billing
LaserStream gRPC / replay
Yellowstone gRPC
pool/scheduler automatique de sessions
configuration publique arbitraire du heartbeat
refonte générique WsSession<P> : non nécessaire en 0.2.8

Une nouvelle preuve normative peut rouvrir un point et insérer une tranche ; aucun report ne doit disparaître silencieusement.

12. Critères de split et de clôture

Créer une tranche/fix supplémentaire si :

l'extraction du chemin physique de WsSession révèle un problème générique indépendant ;
une des six familles Helius dites communes diverge réellement du standard ;
plusieurs formes de notification transaction demandent des contrats séparés ;
Helius modifie sa surface normative pendant la release ;
le smoke live impose une intégration non disponible ;
un gate final reste rouge après pre.011.

La release ne passe stable que si :

surface Helius rapprochée source par source
façades protocolaires séparées
moteur WsSession/actor unique
unsupported Helius absent de la façade publique
transaction extension sans pollution des DTOs standard
standard WS 18/18 non régressé
HTTP 52/14 non régressé
Config -> Transport uniquement
credentials redacted
heartbeat borné/testé si implémenté
reconnect/resubscribe/backpressure/shutdown bornés
aucune promesse replay/lossless WebSocket
aucune nouvelle dépendance injustifiée
workspace complet vert
README/USAGE synchronisés
validation finale fermée
prompt 0.2.9 prêt

13. Checkpoint `pre.002` / `pre.002-fix.001`

Le socle pre.002 est matériellement en place :

WsProtocolKind::HeliusLaserStream -> helius_laserstream
SolanaStandardWsSession
HeliusLaserStreamWsSession
WsSession::connect historique standard-only
connect_for_protocol / connect_physical partagés
aucun second actor/socket/registry
aucun Config Helius / transactionSubscribe / heartbeat anticipé

Preuves opérateur déjà reçues pour pre.002 :

cargo fmt --all                                OK
python3 scripts/audit_rust_workspace_rules.py  clean
cargo check --workspace                        OK
cargo clippy --workspace --all-targets         FAIL ciblé : 5 implicit_return dans ws_protocol_session.rs
cargo test -p ksp-onchain-transport-lib        OK
  313 unit tests + 37 public API + 25 release completeness + 2 doctests compile_fail
cargo test --workspace                         OK

pre.002-fix.001 corrige uniquement ce défaut Clippy dans la fixture, sans modifier le runtime protocolaire. Le fix réorganise aussi les deux documents actifs : le plan conserve décisions, audit, forecast et stratégie ; la validation conserve matrices, critères et preuves exécutées ; les détails de livraison restent dans les deltas.

Après application du fix, le gate opérateur à rejouer est :

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

Si ce checkpoint est vert, pre.002 + fix.001 peuvent être considérés DONE et pre.003 ouvre les six familles standard supportées sur HeliusLaserStreamWsSession.

35 KiB Raw Blame History Unescape Escape

Plan 0.2.8 — Helius LaserStream WebSocket