Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
df95f2f5582a8fb9a93b8f38c88f52bfad474c38
khadhroony-solana-project/docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md

34 KiB
Raw Blame History

Plan 0.2.8 — Helius LaserStream WebSocket

Statut : gate 0.2.8-pre.001 positif, architecture rectifiée par 0.2.8-pre.001-fix.001. Le moteur physique WsSession de 0.2.7 reste unique et partagé, mais les surfaces publiques de protocole sont désormais séparées : SolanaStandardWsSession expose la surface Solana standard, tandis que HeliusLaserStreamWsSession n'expose que les opérations réellement supportées par Helius et les extensions Helius retenues. Le fix est documentaire et conserve workspace.package.version = 0.2.8-pre.1.

1. Objet, base et état du gate

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 :

archive fournie : khadhroony-solana-project-v0.2.7-full-from-gitea.zip
workspace.package.version avant ouverture = 0.2.7
delta stable présent = deltas/0.2.7/rel.001.md
prompt actif présent = prompts/013-V0_2_8_START_PROMPT.md
Git metadata dans l'archive = absente ; le tag n'est donc pas revalidable localement avec git

0.2.8-pre.001 a ouvert techniquement :

workspace.package.version = 0.2.8-pre.1
livraison                 = 0.2.8-pre.001

Le correctif documentaire courant est :

livraison                 = 0.2.8-pre.001-fix.001
workspace.package.version = 0.2.8-pre.1  # inchangé : documentation uniquement
commit attendu            = v0.2.8-pre.001-fix.001
aucun tag prerelease

Les deux graphes Cargo manquants lors de la préparation initiale ont été fournis par l'opérateur le 2026-08-23 :

cargo tree -p ksp-onchain-transport-lib               exécuté
cargo tree -p ksp-onchain-transport-lib --duplicates  exécuté

Constat : aucune dépendance Helius/SDK ajoutée ; les doublons visibles sont transitifs (syn 2/3 et webpki-roots 0.26/1.0) et ne constituent pas une anomalie bloquante de pre.001.

Verdict courant : gate pre.001 positif. pre.002 peut commencer après commit de ce fix.

2. Décision structurante de pre.001-fix.001 — séparer les surfaces, pas le moteur

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.

2.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.

2.2 Surface HeliusLaserStreamWsSession

La façade Helius expose uniquement :

account
logs
program
root
signature
slot
transaction

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é.

2.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.

2.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.

2.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.

3. Prévision souple courante — vue immédiate

Cette section est la source visible du forecast courant. Elle est mise à jour à chaque recalibrage important. Les détails de progression restent dans les deltas ; ce tableau n'est ni une deadline ni un changelog.

Livraison Objectif principal Preuves/gates attendus Budget nominal Split si…
pre.001 Audit Helius, matrice, threat model, dépendances, sizing sources actuelles rapprochées ; baseline ; Cargo trees ; plan/validation 15–20 min audit normatif non fermable
pre.001-fix.001 Corriger l'architecture : façades séparées + forecast visible plan/validation corrigés ; gate Cargo fermé ; aucun runtime doc-only —
pre.002 Socle protocolaire : HeliusLaserStream, façades standard/Helius, connexion physique partagée, guards un seul actor ; constructeurs protocolaires ; compatibilité WsSession ; API canaries 15–20 min extraction du connect/lifecycle devient indépendante
pre.003 Surface Helius standard réellement supportée : 6 familles communes, absence des 3 unsupported 6 wrappers Helius exacts ; block/slotsUpdates/vote absents de la façade ; standard 9/9 intact 15–20 min une famille commune diverge réellement du wire standard
pre.004 Config V2 helius_laserstream + schema/fixtures + secret mapping V1/V2 backward ; Config -> façade correcte ; URL secret redacted ; aucune dépendance inverse 15–20 min stratégie secret/config exige un changement transversal
pre.005 transactionSubscribe request typed + filters/options/tokenAccounts + unsubscribe wire exact ; limites 50k ; max version conditionnel ; ack/error ; API typed 15–20 min filtres/options cachent plusieurs contrats indépendants
pre.006 transactionNotification + actor integration + reconnect/resubscribe/unsubscribe races formes prouvées ; remapping ; late notifications ; backpressure ciblée 15–20 min plusieurs modes de notification exigent un audit séparé
pre.007 Heartbeat Helius/idle + interaction reconnect/control frames/shutdown timer déterministe ; cancellation ; échec Ping -> lifecycle existant ; budget reconnect fini 15–20 min timer/lifecycle révèle une modification générique du moteur
pre.008 Adversarial provider/security/backpressure provider errors isolées ; oversized ; queue overflow ; secret/filter redaction 15–20 min un défaut générique WsSession mérite un fix/tranche propre
pre.009 Compliance Helius + non-régressions WS standard/HTTP/Config/API matrice finale rapprochée ; standard 18/18 ; HTTP 52/14 ; firewall dépendances 15–20 min surface Helius change pendant la release
pre.010 Smoke Helius opt-in si sûr + README/USAGE + dependency audit aucun secret versionné ; docs version-neutral ; cargo tree direct/duplicates 15–20 min surface d'intégration live sûre manque encore
pre.011 Validation workspace finale + fermeture docs/indexes + prompt 0.2.9 workspace vert ; validation fermée ; prompt suivant autonome 15–20 min un gate reste rouge
rel.001 Publication stable stricte tous critères de clôture verts n/a jamais forcé par le numéro

Règles de granularité :

chaque tranche vise environ 15–20 minutes de travail effectif
une tranche > 20 minutes est normalement scindée
une ambiguïté normative nouvelle peut créer une tranche supplémentaire
un fix peut être inséré après n'importe quelle prerelease
pre.011 n'est pas une deadline
la release continue en pre.012+ si un gate l'exige

4. Sources internes relues et hiérarchie appliquée

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 ;
  • ce fix corrige uniquement le design prévu par cette tranche ;
  • une prerelease non-fix synchronise toujours Cargo ;
  • un fix documentaire conserve la version Cargo de sa base ;
  • ROADMAP.md reste global ; les détails vivent dans plan/validation/deltas ;
  • CHANGELOG.md reste principalement réservé à la publication stable.

5. Baseline de démarrage et graphes Cargo

5.1 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.

5.2 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.

6. État réel hérité de v0.2.7

6.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

6.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é.

6.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.

6.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

7. Audit Helius officiel du 2026-08-23

7.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.

7.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

7.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.

7.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é.

7.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.

7.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.

8. 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.

9. Décisions d'architecture détaillées

9.1 Protocol kind

Retenir :

WsProtocolKind::HeliusLaserStream
as_str() = "helius_laserstream"
provider metadata attendu = "helius"

Le discriminateur est nécessaire car la surface de méthodes et la policy heartbeat diffèrent du standard.

9.2 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

9.3 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.

9.4 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 HeliusLaserStream, 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é

9.5 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.

9.6 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.

10. Threat model provider

10.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.

10.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

10.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.

10.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.

10.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.

10.6 Filtres 50k

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

10.7 Continuité

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

11. Audit 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à.

12. Stratégie de tests

12.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.

12.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

12.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

13. 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.

14. 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.

15. 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

16. Verdict après pre.001-fix.001

Décisions fermées :

base stable autoritaire                    confirmé
surface Helius actuelle                    auditée
Cargo graph                                audité, non bloquant
protocol kind                              HeliusLaserStream / helius_laserstream
moteur physique                            WsSession actor unique, partagé
façade standard                            SolanaStandardWsSession
façade Helius                              HeliusLaserStreamWsSession
Helius standard exposé                     Account Logs Program Root Signature Slot
Helius standard absent                     Block SlotsUpdates Vote
Helius extension                           Transaction
DTOs communs                               réutilisés si wire identique
DTOs provider                              dédiés uniquement si divergence
capability guard                           defense-in-depth avant I/O
heartbeat                                  actor provider-owned, 60s cible
Config                                     V2 kind addition, même conteneur
credential                                 URL Secret résolue par Config
new dependency                             aucune
historical/lossless replay                 aucune promesse
forecast                                   visible et recalibré pre.001 -> pre.011

Gate pre.001 positif. Prochaine tranche : 0.2.8-pre.002 — socle protocolaire et façades séparées.

Reference in New Issue View Git Blame Copy Permalink