v0.2.7-pre.014
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: prompts/000-README.md -->
|
||||
<!-- version: 21 -->
|
||||
<!-- version: 22 -->
|
||||
|
||||
# Prompts KSP
|
||||
|
||||
@@ -32,4 +32,5 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par
|
||||
- [`009-V0_2_4_START_PROMPT.md`](009-V0_2_4_START_PROMPT.md) — prompt préparé par `0.2.3-pre.009`, destiné à ouvrir `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale` après publication stable de `0.2.3`; il cible les 15 wrappers restants et impose `KSP-TRANSPORT-007` ainsi qu'un nouvel audit/sizing à `pre.001`.
|
||||
- [`010-V0_2_5_START_PROMPT.md`](010-V0_2_5_START_PROMPT.md) — prompt préparé par `0.2.4-pre.009` puis finalisé en version 2 par `pre.009-fix.001`, destiné à ouvrir `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`; il impose audit/threat-model/sizing avant choix cryptographiques et cadre `.kspwallet` interopérable, capacités indépendantes VIEW/OWNER, metadata protégées, key slots/rotations, signature, persistence atomique et import/export extensible sans `WalletPolicy`.
|
||||
- [`011-V0_2_6_START_PROMPT.md`](011-V0_2_6_START_PROMPT.md) — prompt préparé par `0.2.5-pre.010` puis renforcé pendant `pre.010-fix.001`–`fix.003`, prompt historique consommé pour ouvrir `0.2.6 — Wallet Desk` après le tag stable `v0.2.5`; il impose une première tranche audit/sizing, rappelle les règles Rust/audit structurel, cadre Config composite + Wallet + HTTP `getBalance`, lifecycle VIEW/OWNER, sécurité password/export, validation frontend/Tauri et conserve le TODO `0.2.11` d’intégration des prix offchain dans Wallet Desk après validation de la Price Desk spécialisée.
|
||||
- [`012-V0_2_7_START_PROMPT.md`](012-V0_2_7_START_PROMPT.md) — prompt réaligné par `0.2.6-pre.015` puis renforcé en contrat de reprise autonome par `0.2.6-pre.018-fix.002`; il est le prochain prompt actif et ouvre `0.2.7 — WebSocket Solana standard` depuis `v0.2.6`, impose les lectures/règles ordonnées, l’audit officiel et historique, le threat-model session/subscription/reconnect/backpressure, la matrice de compliance, un gate `pre.001` strict et une prévision souple de prereleases avant toute implémentation lourde.
|
||||
- [`012-V0_2_7_START_PROMPT.md`](012-V0_2_7_START_PROMPT.md) — prompt réaligné par `0.2.6-pre.015` puis renforcé en contrat de reprise autonome par `0.2.6-pre.018-fix.002`; prompt historique consommé pour ouvrir `0.2.7 — WebSocket Solana standard` depuis `v0.2.6`, avec lectures/règles ordonnées, audit officiel et historique, threat-model session/subscription/reconnect/backpressure, matrice de compliance, gate `pre.001` strict et prévision souple de prereleases avant toute implémentation lourde.
|
||||
- [`013-V0_2_8_START_PROMPT.md`](013-V0_2_8_START_PROMPT.md) — prochain prompt actif, préparé par `0.2.7-pre.014` et utilisable uniquement après publication stable de `v0.2.7` pour ouvrir `0.2.8 — Helius LaserStream WebSocket`; il impose la relecture des règles et de la surface WebSocket finale, un réaudit Helius actuel, un gate `pre.001` strict audit/brainstorming/sizing, la réutilisation du moteur actor standard sans second client, des frontières provider/Config/secrets explicites et une prévision souple avant toute implémentation lourde.
|
||||
|
||||
951
prompts/013-V0_2_8_START_PROMPT.md
Normal file
951
prompts/013-V0_2_8_START_PROMPT.md
Normal file
@@ -0,0 +1,951 @@
|
||||
<!-- file: prompts/013-V0_2_8_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Prompt de démarrage `0.2.8` — Helius LaserStream WebSocket
|
||||
|
||||
## 1. Identité de la release et base exacte requise
|
||||
|
||||
La release à ouvrir est :
|
||||
|
||||
```text
|
||||
0.2.8 — Helius LaserStream WebSocket
|
||||
```
|
||||
|
||||
Elle doit démarrer **uniquement après publication stable de `0.2.7`**.
|
||||
|
||||
Base Git attendue :
|
||||
|
||||
```text
|
||||
v0.2.7
|
||||
```
|
||||
|
||||
La base stable doit contenir au minimum :
|
||||
|
||||
```text
|
||||
deltas/0.2.7/rel.001.md
|
||||
prompts/013-V0_2_8_START_PROMPT.md
|
||||
```
|
||||
|
||||
Si une archive complète du workspace `v0.2.7` est fournie au démarrage de session, **cette archive est autoritaire** par rapport aux souvenirs, snippets, copies de prereleases ou artefacts antérieurs. Vérifier l'état réel avant toute modification.
|
||||
|
||||
Signal Cargo initial attendu :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.2.7"
|
||||
```
|
||||
|
||||
La première livraison de la release sera :
|
||||
|
||||
```text
|
||||
0.2.8-pre.001
|
||||
Cargo = 0.2.8-pre.1
|
||||
```
|
||||
|
||||
Aucun code fonctionnel lourd ne doit être commencé avant la sortie positive du gate `pre.001` décrit plus bas.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mission et résultat attendu
|
||||
|
||||
`0.2.8` doit étendre le moteur WebSocket déjà stabilisé dans `ksp-onchain-transport-lib` avec la **surface Helius LaserStream WebSocket réellement documentée et supportée au moment de l'audit**, sans dupliquer le client/session actor standard et sans transformer Transport en SDK Helius généraliste.
|
||||
|
||||
Le résultat attendu est une extension provider-specific qui :
|
||||
|
||||
```text
|
||||
réutilise le moteur physique WsSession acquis en 0.2.7
|
||||
préserve les wrappers Solana standard existants
|
||||
ajoute uniquement les capacités Helius WebSocket réellement auditées
|
||||
conserve les paramètres/filtres/options Helius utiles sans perte
|
||||
modélise explicitement les méthodes standard non supportées par Helius
|
||||
respecte les limites/reconnect/backpressure/shutdown KSP existants
|
||||
ne fuite jamais api-key, URL complète, query credentials ou payload massif
|
||||
reste compatible avec Config -> Transport sans dépendance inverse
|
||||
ne crée aucune dépendance Store/Program/Wallet dans Transport
|
||||
ne confond jamais LaserStream WebSocket et LaserStream gRPC
|
||||
```
|
||||
|
||||
Le nom produit Helius a évolué : les anciennes « Enhanced WebSockets » sont désormais présentées dans la documentation Helius comme faisant partie de **LaserStream WebSocket**. La session doit donc réauditer la terminologie actuelle au lieu de reprendre mécaniquement les anciens noms.
|
||||
|
||||
---
|
||||
|
||||
## 3. Sources de vérité internes obligatoires — ordre de lecture
|
||||
|
||||
### 3.1 Entrées et règles globales
|
||||
|
||||
Lire d'abord, dans cet ordre :
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
Ne pas reconstituer ces règles depuis la mémoire de conversation. Le contenu présent dans la base stable est normatif.
|
||||
|
||||
### 3.2 Architecture à préserver
|
||||
|
||||
Lire ensuite :
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
Points d'attention :
|
||||
|
||||
```text
|
||||
Transport possède le réseau et ses settings runtime
|
||||
Config adapte vers Transport, jamais l'inverse
|
||||
Store/RAW persistence n'appartient pas à Transport
|
||||
Program decode/materialization n'appartient pas à Transport
|
||||
un provider WebSocket ne doit pas créer un second moteur session/subscription
|
||||
```
|
||||
|
||||
### 3.3 Séquence fonctionnelle et héritage Transport
|
||||
|
||||
Lire :
|
||||
|
||||
```text
|
||||
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/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md
|
||||
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
|
||||
```
|
||||
|
||||
`docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` porte la numérotation courante. Les anciens plans restent historiques et ne doivent pas réintroduire une numérotation dépassée.
|
||||
|
||||
### 3.4 Contrats publics réels à réauditer
|
||||
|
||||
Inspecter directement :
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
En particulier, vérifier les contrats réels de :
|
||||
|
||||
```text
|
||||
WsProtocolKind
|
||||
WsEndpointSettings
|
||||
WsTransportSettings
|
||||
WsSessionSettings
|
||||
WsSession
|
||||
WsSubscription<T>
|
||||
WsSubscriptionKind
|
||||
WsSessionSnapshot / WsSubscriptionSnapshot
|
||||
```
|
||||
|
||||
Ne jamais supposer qu'une API imaginée pendant `0.2.7-pre.001` est celle finalement publiée : **le code stable `v0.2.7` prime**.
|
||||
|
||||
### 3.5 Clôture `0.2.7`
|
||||
|
||||
Lire obligatoirement :
|
||||
|
||||
```text
|
||||
deltas/0.2.7/rel.001.md
|
||||
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
|
||||
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
|
||||
```
|
||||
|
||||
Le but est de reprendre exactement le moteur final, les limitations documentées et les preuves de clôture, pas de rouvrir les décisions standard déjà validées.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sources externes normatives à réauditer en `pre.001`
|
||||
|
||||
La documentation Helius est une surface vivante. **Toutes les informations de cette section sont des pointeurs d'audit, pas des versions figées.** Les pages officielles courantes doivent être relues au début de `pre.001`.
|
||||
|
||||
Auditer au minimum les sources Helius officielles suivantes ou leurs remplaçantes actuelles :
|
||||
|
||||
```text
|
||||
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/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/faqs/websockets
|
||||
https://www.helius.dev/docs/llms.txt
|
||||
```
|
||||
|
||||
Utiliser l'index `llms.txt` et la navigation officielle pour retrouver les pages unsubscribe et toute extension/filter provider-specific encore documenté (`notifyOn`, `tokenAccounts` ou remplaçant actuel). Une URL déplacée n'annule pas le gate : retrouver la page officielle remplaçante et enregistrer la source effective dans le plan/matrice `0.2.8`.
|
||||
|
||||
Snapshot documentaire connu lors de la préparation de ce prompt, **à réauditer** :
|
||||
|
||||
```text
|
||||
les endpoints WebSocket standard et Helius extensions sont unifiés par réseau
|
||||
le produit anciennement appelé Enhanced WebSockets est désormais présenté dans la famille LaserStream WebSocket
|
||||
transactionSubscribe est une extension Helius avec filtres riches
|
||||
la référence transactionSubscribe documente transactionUnsubscribe, tandis que l'index méthodes ne l'énumère pas séparément
|
||||
les méthodes standard block/slotsUpdates/vote sont actuellement annoncées non supportées par Helius
|
||||
la FAQ annonce un idle timeout de 10 minutes et recommande des pings périodiques
|
||||
les documents d'indexing distinguent WebSocket sans garantie de replay historique du produit LaserStream gRPC
|
||||
notifyOn et tokenAccounts ont été observés dans des références Helius pendant la préparation ; leur présence, leur portée et leur forme exactes doivent être reconfirmées au gate
|
||||
```
|
||||
|
||||
Le gate doit relever la **surface exacte du jour** : méthodes, unsubscribe associés, paramètres, limites, notifications, statuts et divergences entre index, guides et références.
|
||||
|
||||
Si deux pages Helius se contredisent, ne pas choisir arbitrairement : documenter la divergence, rechercher une source Helius plus primaire/récente, puis tester localement ou contre Helius uniquement si cela peut être fait sans violer les règles de secrets/configuration.
|
||||
|
||||
Réauditer aussi les versions courantes des dépendances externes concernées. La résolution observée à la fin de `0.2.7-pre.013` était notamment :
|
||||
|
||||
```text
|
||||
futures-util 0.3.34
|
||||
tokio 1.53.1
|
||||
tokio-tungstenite 0.30.0
|
||||
reqwest 0.13.4
|
||||
```
|
||||
|
||||
Ces versions sont un **snapshot sans lockfile versionné**, pas une contrainte à recopier si Cargo résout plus récent au démarrage de `0.2.8`.
|
||||
|
||||
---
|
||||
|
||||
## 5. État validé à préserver depuis `v0.2.7`
|
||||
|
||||
### 5.1 HTTP
|
||||
|
||||
La surface HTTP reste un contrat stable :
|
||||
|
||||
```text
|
||||
52/52 méthodes HTTP courantes typées
|
||||
14/14 méthodes historiques Deprecated/Removed conservées
|
||||
KSP-TRANSPORT-007 appliqué à toute la surface typed
|
||||
retry/no-resend write submissions déjà centralisé
|
||||
```
|
||||
|
||||
`0.2.8` ne doit pas régresser cette surface.
|
||||
|
||||
### 5.2 WebSocket Solana standard
|
||||
|
||||
La release `0.2.7` publie exactement neuf familles standard :
|
||||
|
||||
```text
|
||||
account
|
||||
block
|
||||
logs
|
||||
program
|
||||
root
|
||||
signature
|
||||
slot
|
||||
slotsUpdates
|
||||
vote
|
||||
```
|
||||
|
||||
soit :
|
||||
|
||||
```text
|
||||
9 subscribe + 9 unsubscribe = 18 opérations standard
|
||||
```
|
||||
|
||||
Partition stable/unstable héritée :
|
||||
|
||||
```text
|
||||
stable : account, logs, program, root, signature, slot
|
||||
unstable : block, slotsUpdates, vote
|
||||
```
|
||||
|
||||
Les trois familles unstable ont un warning KSP centralisé dans le moteur standard.
|
||||
|
||||
### 5.3 Session, subscriptions et cardinalité
|
||||
|
||||
Contrat acquis :
|
||||
|
||||
```text
|
||||
1 WsEndpointSettings
|
||||
-> 0..N sessions physiques explicitement créées
|
||||
-> 0..N logical subscriptions
|
||||
```
|
||||
|
||||
Identités :
|
||||
|
||||
```text
|
||||
WsSessionId = local et stable
|
||||
WsSubscriptionId = local et stable pendant reconnect/resubscribe
|
||||
remote subscription id = interne, transitoire, remappable
|
||||
```
|
||||
|
||||
Aucun pool/scheduler automatique de sessions n'est imposé.
|
||||
|
||||
### 5.4 Lifecycle/reconnect/backpressure
|
||||
|
||||
Préserver les invariants suivants :
|
||||
|
||||
```text
|
||||
actor unique propriétaire du socket
|
||||
command queue bornée
|
||||
pending JSON-RPC borné + timeout
|
||||
notification queue bornée par subscription
|
||||
max active subscriptions borné
|
||||
reconnect fini + backoff exponentiel borné
|
||||
budget reconnect reset après retour complet à Active
|
||||
resubscribe ActiveSubscriptions déterministe par local id
|
||||
remote IDs invalidés après reconnect
|
||||
continuity_gap_count observable
|
||||
unsubscribe local gagne les races reconnect/late ack
|
||||
overflow d'une subscription ne tue pas les autres
|
||||
shutdown explicite borné via WsSession::close().await
|
||||
Drop best-effort seulement
|
||||
```
|
||||
|
||||
`signatureSubscribe` reste one-shot après notification terminale et ne doit pas être resubscribed après fermeture normale.
|
||||
|
||||
### 5.5 Sécurité/observabilité
|
||||
|
||||
Safe metadata autorisée :
|
||||
|
||||
```text
|
||||
endpoint logical name
|
||||
provider
|
||||
cluster
|
||||
protocol kind
|
||||
local session/subscription ids
|
||||
subscription kind
|
||||
states
|
||||
counts
|
||||
reconnect attempt
|
||||
continuity gaps
|
||||
overflow count
|
||||
safe error codes
|
||||
```
|
||||
|
||||
Interdit dans logs/Debug/Display/snapshots :
|
||||
|
||||
```text
|
||||
URL complète
|
||||
query api-key
|
||||
authorization secret
|
||||
headers sensibles
|
||||
remote subscription id
|
||||
raw notification arbitraire
|
||||
payload massif
|
||||
```
|
||||
|
||||
### 5.6 Config V2
|
||||
|
||||
Contrat stable :
|
||||
|
||||
```text
|
||||
format_version = 2
|
||||
retry
|
||||
ws_defaults
|
||||
default_profile
|
||||
profiles[]
|
||||
endpoints[]
|
||||
ws_endpoints[]
|
||||
kind
|
||||
```
|
||||
|
||||
À la fin de `0.2.7`, la seule valeur WebSocket Config supportée est :
|
||||
|
||||
```text
|
||||
solana_standard
|
||||
```
|
||||
|
||||
Le type Transport correspondant est `WsProtocolKind`, `#[non_exhaustive]`, précisément pour permettre une extension future sans remplacer le conteneur commun.
|
||||
|
||||
---
|
||||
|
||||
## 6. Frontières architecturales et règles de dépendances
|
||||
|
||||
Direction autorisée :
|
||||
|
||||
```text
|
||||
ksp-config-lib -> ksp-onchain-transport-lib
|
||||
```
|
||||
|
||||
Interdictions durables :
|
||||
|
||||
```text
|
||||
ksp-onchain-transport-lib -X-> ksp-config-lib
|
||||
ksp-onchain-transport-lib -X-> ksp-wallet-lib
|
||||
ksp-onchain-transport-lib -X-> ksp-store-api
|
||||
ksp-onchain-transport-lib -X-> ksp-store-lib
|
||||
ksp-onchain-transport-lib -X-> ksp-program-api
|
||||
ksp-onchain-transport-lib -X-> ksp-program-lib
|
||||
ksp-onchain-transport-lib -X-> tracing direct
|
||||
```
|
||||
|
||||
Transport peut dépendre seulement des crates KSP basses autorisées et des crates réseau/serde/async strictement nécessaires.
|
||||
|
||||
Toutes les dépendances tierces restent déclarées dans le `[workspace.dependencies]` racine et consommées par les members avec `.workspace = true`.
|
||||
|
||||
Aucun client Helius SDK n'est ajouté par défaut. Une nouvelle dépendance doit démontrer un besoin que le moteur `tokio-tungstenite` existant ne satisfait pas.
|
||||
|
||||
---
|
||||
|
||||
## 7. Décisions acquises et questions réellement ouvertes
|
||||
|
||||
### 7.1 Décisions déjà acquises — ne pas les redébattre sans contradiction réelle
|
||||
|
||||
```text
|
||||
Helius WebSocket réutilise le moteur/session actor de 0.2.7
|
||||
pas de second client WebSocket provider-specific
|
||||
les wrappers Solana standard restent valides pour la surface standard
|
||||
aucune API raw provider-extension publique par défaut
|
||||
pas de LaserStream gRPC dans 0.2.8
|
||||
pas de Yellowstone gRPC dans 0.2.8
|
||||
pas de Store/RAW persistence dans 0.2.8
|
||||
pas de Program decode/materialization dans 0.2.8
|
||||
pas de metering/billing provider dans 0.2.8
|
||||
pas de promesse lossless/historical replay pour WebSocket
|
||||
credentials Helius = Secret Config, jamais loggés
|
||||
fixtures déterministes = gate principal ; réseau réel = opt-in uniquement
|
||||
```
|
||||
|
||||
La piste de metering/observabilité réseau est suivie séparément dans `docs/IDEAS.md`; elle ne doit pas être introduite opportunistement dans cette release.
|
||||
|
||||
### 7.2 Questions ouvertes à trancher pendant `pre.001`
|
||||
|
||||
Le gate doit décider, avec preuves :
|
||||
|
||||
```text
|
||||
nom/public descriptor exact du nouveau WsProtocolKind éventuel
|
||||
Helius endpoint = SolanaStandard + provider helius, HeliusLaserStream, ou combinaison explicitement justifiée
|
||||
surface Helius exacte du jour
|
||||
transactionSubscribe + transactionUnsubscribe : existence, noms et wire exacts
|
||||
notification transaction exacte et réutilisation possible des DTOs HTTP/WS existants
|
||||
filtres transaction exacts et limites courantes
|
||||
extension tokenAccounts : valeurs, cardinalité, interactions
|
||||
notifyOn account/program : valeurs et comportement serveur
|
||||
autres extensions Helius actuellement documentées éventuelles
|
||||
méthodes Solana standard supportées/non supportées sur Helius
|
||||
comportement KSP pour block/slotsUpdates/vote sur endpoint Helius
|
||||
capability validation avant I/O vs erreur RPC provider
|
||||
heartbeat/ping provider : nécessaire, cadence, ownership et interaction avec control frames existants
|
||||
idle timeout Helius et stratégie de reconnect
|
||||
interaction entre heartbeat et shutdown/reconnect/backpressure
|
||||
Config : discriminateur, provider metadata, endpoint/auth shape
|
||||
faut-il de nouveaux settings provider-specific distincts de WsSessionSettings commun
|
||||
comment éviter d'injecter notifyOn/tokenAccounts dans les DTOs Solana standard
|
||||
warning/info provider-specific éventuel et metadata sûre
|
||||
stratégie de smoke Helius nécessitant une api-key sans lecture directe d'environnement par Transport
|
||||
besoin réel ou non d'une nouvelle dépendance Rust
|
||||
```
|
||||
|
||||
Une décision peut être de **ne pas exposer** une capacité Helius insuffisamment documentée. Elle doit alors être explicitement reportée, pas silencieusement oubliée.
|
||||
|
||||
---
|
||||
|
||||
## 8. Objectifs et livrables de `0.2.8`
|
||||
|
||||
Le plan créé par `pre.001` doit au minimum prévoir :
|
||||
|
||||
1. une matrice normative Helius WebSocket actuelle et sourcée ;
|
||||
2. un inventaire explicite standard supporté / standard non supporté / extension Helius ;
|
||||
3. le choix d'extension de `WsProtocolKind` et du Config V2 ;
|
||||
4. la réutilisation du `WsSession` actor existant ;
|
||||
5. `transactionSubscribe`/unsubscribe si toujours supportés et documentés ;
|
||||
6. les filtres/options Helius réellement utiles et documentés ;
|
||||
7. les extensions Helius de `accountSubscribe`/`programSubscribe` si toujours présentes ;
|
||||
8. une politique provider capability sans contamination de la surface standard ;
|
||||
9. heartbeat/idle handling si réellement requis ;
|
||||
10. fixtures locales déterministes de toutes les extensions ;
|
||||
11. tests de reconnect/resubscribe/unsubscribe/backpressure sur les nouvelles familles ;
|
||||
12. redaction credentials Helius et erreurs sûres ;
|
||||
13. adaptation Config -> Transport correspondante ;
|
||||
14. canaries de non-régression 18/18 standard + 52/14 HTTP ;
|
||||
15. documentation README/USAGE durable et version-neutral ;
|
||||
16. stratégie de smoke live opt-in compatible avec les règles Config/secret ;
|
||||
17. audit final des dépendances et prompt `0.2.9`.
|
||||
|
||||
Créer normalement :
|
||||
|
||||
```text
|
||||
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
|
||||
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
|
||||
```
|
||||
|
||||
Si ces numéros sont déjà occupés dans la base réellement fournie, prendre les prochains numéros disponibles et mettre à jour les index correspondants.
|
||||
|
||||
---
|
||||
|
||||
## 9. Hors périmètre explicite
|
||||
|
||||
```text
|
||||
LaserStream gRPC / helius-laserstream SDK -> hors 0.2.8
|
||||
Yellowstone gRPC standard -> 0.2.9
|
||||
providers Yellowstone commerciaux spécifiques -> après foundation 0.2.9 selon sizing
|
||||
Gatekeeper beta -> hors scope sauf décision explicite après audit
|
||||
Shred Delivery / shreds UDP -> plus tard
|
||||
preconfirmations / Sender -> autres surfaces futures
|
||||
HTTP Helius provider extensions non WebSocket -> hors 0.2.8
|
||||
ksp-offchain-transport-lib / prix -> 0.2.10
|
||||
Price Desk / Wallet Desk price integration -> 0.2.11
|
||||
Store / RAW persistence -> série 0.3.x
|
||||
Program decode / materialization -> plus tard
|
||||
metering / coût / billing provider -> IDEAS/future crate dédiée
|
||||
pool/scheduler automatique complexe de WsSession -> différé sans besoin démontré
|
||||
historical replay WebSocket inventé -> interdit
|
||||
```
|
||||
|
||||
Ne pas importer dans `0.2.8` les capacités gRPC de LaserStream sous prétexte qu'elles portent le même nom produit.
|
||||
|
||||
---
|
||||
|
||||
## 10. Contraintes sécurité, provider et API
|
||||
|
||||
### 10.1 Credentials Helius
|
||||
|
||||
Une api-key Helius est un Secret.
|
||||
|
||||
Elle ne doit jamais apparaître dans :
|
||||
|
||||
```text
|
||||
Debug
|
||||
Display
|
||||
KspError context arbitraire
|
||||
logs
|
||||
panic output volontaire
|
||||
snapshots runtime
|
||||
nom d'endpoint
|
||||
fixtures versionnées
|
||||
commandes documentées avec vraie valeur
|
||||
```
|
||||
|
||||
Les URLs contenant `?api-key=...` doivent rester derrière `WsEndpointUrl` et ses garanties de redaction.
|
||||
|
||||
### 10.2 Provider-specific sans pollution standard
|
||||
|
||||
Une option Helius ne doit pas être ajoutée à un DTO standard Solana simplement parce qu'elle réutilise le même nom JSON-RPC.
|
||||
|
||||
Le design doit distinguer explicitement :
|
||||
|
||||
```text
|
||||
contrat Solana standard
|
||||
extension Helius du même method name
|
||||
nouvelle méthode Helius
|
||||
```
|
||||
|
||||
Les wrappers standards de `0.2.7` ne doivent pas changer de wire lorsqu'ils sont utilisés avec `WsProtocolKind::SolanaStandard`.
|
||||
|
||||
### 10.3 Heartbeat
|
||||
|
||||
`0.2.7` n'impose aucun heartbeat applicatif périodique : il répond correctement aux control frames WebSocket reçues.
|
||||
|
||||
Si Helius exige/recommande un ping périodique pour éviter son inactivity timeout, `pre.001` doit décider si cela devient :
|
||||
|
||||
```text
|
||||
une capability provider-specific
|
||||
un setting explicite
|
||||
un comportement automatique borné
|
||||
ou une responsabilité caller
|
||||
```
|
||||
|
||||
Toute solution automatique doit :
|
||||
|
||||
```text
|
||||
être annulable au shutdown
|
||||
ne pas masquer un socket réellement mort
|
||||
ne pas créer une boucle de reconnexion infinie
|
||||
ne pas bloquer l'actor
|
||||
ne pas logguer de secret
|
||||
être couverte par test temporel déterministe local
|
||||
```
|
||||
|
||||
### 10.4 Continuité
|
||||
|
||||
Même si Helius annonce une infrastructure de failover, WebSocket ne doit pas être documenté comme lossless.
|
||||
|
||||
Le contrat KSP reste :
|
||||
|
||||
```text
|
||||
reconnect possible
|
||||
resubscribe possible
|
||||
continuity_gap_count observable
|
||||
aucun backfill automatique dans Transport
|
||||
aucune garantie de replay historique WebSocket
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Première mission `0.2.8-pre.001` — gate obligatoire
|
||||
|
||||
La première tranche est **audit + brainstorming + sizing**, pas une tranche d'implémentation lourde.
|
||||
|
||||
Elle doit exécuter dans l'ordre :
|
||||
|
||||
### 11.1 Reprise de la base
|
||||
|
||||
```text
|
||||
vérifier base/tag v0.2.7 ou archive stable autoritaire
|
||||
lire les règles obligatoires
|
||||
lire plan + validation + rel.001 de 0.2.7
|
||||
inventorier le code WsSession/WsSubscription/Config réellement publié
|
||||
vérifier l'état Cargo et le graphe actuel
|
||||
```
|
||||
|
||||
### 11.2 Audit Helius officiel actuel
|
||||
|
||||
Construire une matrice contenant au minimum :
|
||||
|
||||
```text
|
||||
method
|
||||
subscribe/unsubscribe pair
|
||||
standard ou Helius extension
|
||||
support Helius actuel
|
||||
params obligatoires
|
||||
options
|
||||
filters
|
||||
limits/cardinality
|
||||
notification method
|
||||
notification wire
|
||||
nullable/optional states
|
||||
idle/heartbeat requirement
|
||||
credential requirement
|
||||
source officielle
|
||||
strategy de test
|
||||
```
|
||||
|
||||
Le gate doit spécialement résoudre :
|
||||
|
||||
```text
|
||||
transactionUnsubscribe exact
|
||||
notifyOn exact
|
||||
programSubscribe + notifyOn exact
|
||||
tokenAccounts exact
|
||||
autres filtres transaction actuels
|
||||
liste des méthodes unstable explicitement non supportées
|
||||
endpoints mainnet/devnet réellement courants
|
||||
ancien atlas-* vs endpoints unifiés actuels
|
||||
nom actuel Enhanced WebSockets vs LaserStream WebSocket
|
||||
```
|
||||
|
||||
### 11.3 Audit architecture KSP
|
||||
|
||||
Comparer la matrice Helius avec :
|
||||
|
||||
```text
|
||||
WsProtocolKind
|
||||
WsEndpointSettings
|
||||
WsSessionSettings
|
||||
WsSubscriptionKind
|
||||
subscribe_typed interne
|
||||
registry/remapping remote/local
|
||||
reconnect/resubscribe
|
||||
Config V2 kind
|
||||
```
|
||||
|
||||
Décider quelles parties sont :
|
||||
|
||||
```text
|
||||
réutilisées telles quelles
|
||||
étendues provider-specific
|
||||
interdites avant I/O
|
||||
laissées à l'erreur provider
|
||||
reportées
|
||||
```
|
||||
|
||||
### 11.4 Audit dépendances
|
||||
|
||||
Exécuter au minimum :
|
||||
|
||||
```bash
|
||||
cargo tree -p ksp-onchain-transport-lib
|
||||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||||
```
|
||||
|
||||
Vérifier les versions stables courantes des crates réseau utilisées. Ne pas ajouter un SDK Helius sans justification mesurable.
|
||||
|
||||
### 11.5 Threat model provider
|
||||
|
||||
Brainstormer au minimum :
|
||||
|
||||
```text
|
||||
api-key dans query URL
|
||||
endpoint redaction
|
||||
provider idle timeout
|
||||
heartbeat concurrent avec reconnect/close
|
||||
rate/capability errors
|
||||
subscription ids et late notifications
|
||||
in-flight notifications après unsubscribe
|
||||
provider-specific unknown fields
|
||||
payload volumineux transactionSubscribe
|
||||
50k-address style filters et coût mémoire/serialization
|
||||
data gaps après reconnect
|
||||
mismatch standard method support
|
||||
```
|
||||
|
||||
### 11.6 Sizing
|
||||
|
||||
Produire :
|
||||
|
||||
```text
|
||||
liste exacte des capacités à implémenter
|
||||
questions reportées
|
||||
nombre estimé de prereleases
|
||||
budget de chaque tranche <= environ 15–20 minutes de travail effectif
|
||||
ordre des tranches
|
||||
validations associées
|
||||
risques de split
|
||||
```
|
||||
|
||||
Si la surface Helius actuelle est plus large que prévu et menace la règle « une release concrète clôturable dans une session », **scinder avant implémentation lourde**.
|
||||
|
||||
### 11.7 Documents de sortie du gate
|
||||
|
||||
`pre.001` doit créer/mettre à jour au minimum :
|
||||
|
||||
```text
|
||||
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
|
||||
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
|
||||
deltas/0.2.8/pre.001.md
|
||||
```
|
||||
|
||||
ainsi que les index documentaires concernés.
|
||||
|
||||
### Critères de sortie de `pre.001`
|
||||
|
||||
Le gate est positif seulement si :
|
||||
|
||||
```text
|
||||
base stable confirmée
|
||||
sources Helius actuelles réauditées
|
||||
surface exacte inventoriée
|
||||
terminologie provider clarifiée
|
||||
frontières standard/provider décidées
|
||||
heartbeat/idle ownership décidé ou explicitement reporté
|
||||
Config shape décidée
|
||||
strategy de credentials sûre
|
||||
strategy de tests/smoke décidée
|
||||
aucune nouvelle dépendance non justifiée
|
||||
release dimensionnée et forecast recalibré
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Prévision souple initiale des prereleases
|
||||
|
||||
Prévision de départ, à recalibrer après `pre.001` :
|
||||
|
||||
```text
|
||||
pre.001 audit Helius actuel + matrice + architecture + threat model + sizing
|
||||
pre.002 protocol/provider settings + Config V2 extension + capability model
|
||||
pre.003 transactionSubscribe/unsubscribe + DTOs/filters/options + fixtures
|
||||
pre.004 extensions account/program et autres filtres Helius retenus + fixtures
|
||||
pre.005 heartbeat/idle/reconnect/capability failures + adversarial lifecycle tests
|
||||
pre.006 compliance provider + non-régressions standard/HTTP + smoke strategy + dependency audit + docs
|
||||
pre.007 validation workspace finale + documentation/indexes + prompt 0.2.9
|
||||
rel.001 publication stable stricte
|
||||
```
|
||||
|
||||
Cette prévision est **souple**. Des tranches ou fixes peuvent être insérés si l'audit réel le justifie. La fermeture ne doit jamais être forcée pour respecter `pre.007`.
|
||||
|
||||
---
|
||||
|
||||
## 13. Versionnement, deltas, commits et tags
|
||||
|
||||
Convention de livraison :
|
||||
|
||||
```text
|
||||
0.2.8-pre.001 -> Cargo 0.2.8-pre.1
|
||||
0.2.8-pre.002 -> Cargo 0.2.8-pre.2
|
||||
0.2.8-pre.NNN-fix.MMM -> Cargo 0.2.8-pre.N.fix.M seulement si code/build/runtime/config/migration change
|
||||
0.2.8-rel.001 -> Cargo 0.2.8
|
||||
```
|
||||
|
||||
Une prerelease non-fix synchronise toujours `workspace.package.version`, même si son contenu final est principalement documentaire. Un fix purement documentaire/de référence non consommée par le runtime conserve la version Cargo de sa base directe, conformément à `VERSION_WORKFLOW.md`.
|
||||
|
||||
Deltas :
|
||||
|
||||
```text
|
||||
deltas/0.2.8/pre.001.md
|
||||
deltas/0.2.8/pre.002.md
|
||||
...
|
||||
deltas/0.2.8/pre.NNN-fix.MMM.md
|
||||
deltas/0.2.8/rel.001.md
|
||||
```
|
||||
|
||||
Commits :
|
||||
|
||||
```text
|
||||
v0.2.8-pre.001
|
||||
v0.2.8-pre.001-fix.001
|
||||
...
|
||||
v0.2.8-rel.001
|
||||
```
|
||||
|
||||
Aucun tag Git pour les prereleases.
|
||||
|
||||
Après validation de `rel.001` :
|
||||
|
||||
```text
|
||||
tag stable = v0.2.8
|
||||
```
|
||||
|
||||
Une livraison publiée est immutable. Une correction produit un nouveau `fix`; elle ne remplace jamais l'archive précédente.
|
||||
|
||||
Pendant les prereleases :
|
||||
|
||||
```text
|
||||
ROADMAP.md = statut global seulement
|
||||
CHANGELOG.md = principalement clôture stable
|
||||
progression détaillée = plan + validation + deltas
|
||||
pas de Cargo.lock / package-lock.json versionné
|
||||
```
|
||||
|
||||
Tout fichier modifié incrémente son header `version:` selon les règles KSP.
|
||||
|
||||
---
|
||||
|
||||
## 14. Application et validation opérateur
|
||||
|
||||
L'assistant prépare normalement un overlay minimal ne contenant que les fichiers ajoutés/modifiés de la livraison.
|
||||
|
||||
Après application d'une prerelease Rust :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Puis tests ciblés pertinents, par exemple :
|
||||
|
||||
```bash
|
||||
cargo test -p ksp-onchain-transport-lib
|
||||
cargo test -p ksp-config-lib
|
||||
```
|
||||
|
||||
À la fermeture d'une tranche technique importante et de la release :
|
||||
|
||||
```bash
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Lorsque le graphe de dépendances change ou constitue un gate :
|
||||
|
||||
```bash
|
||||
cargo tree -p ksp-onchain-transport-lib
|
||||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||||
cargo tree --duplicates
|
||||
```
|
||||
|
||||
Ne jamais déclarer une commande réussie si elle n'a pas été exécutée. L'environnement de préparation peut ne pas disposer de Cargo/rustfmt ; dans ce cas, le delta doit le dire explicitement et l'opérateur exécute les gates.
|
||||
|
||||
### Tests provider attendus
|
||||
|
||||
Les preuves déterministes doivent couvrir au minimum, selon la surface retenue :
|
||||
|
||||
```text
|
||||
subscribe/unsubscribe exacts
|
||||
notification method exact
|
||||
transaction filters/options complets
|
||||
cardinalités/limites avant I/O lorsqu'elles sont déterministes
|
||||
notifyOn/tokenAccounts ou extensions retenues
|
||||
standard vs provider capability mismatch
|
||||
provider RPC errors sans session failure injustifiée
|
||||
late notification après unsubscribe
|
||||
reconnect/resubscribe
|
||||
heartbeat timer borné si ajouté
|
||||
shutdown pendant heartbeat/reconnect
|
||||
message/frame oversized
|
||||
queue overflow d'une subscription
|
||||
secret URL redaction
|
||||
public API canaries
|
||||
Config -> Transport mapping
|
||||
HTTP 52+14 non régressé
|
||||
Solana standard 18/18 non régressé
|
||||
```
|
||||
|
||||
### Smoke live Helius
|
||||
|
||||
Un smoke live Helius ne doit **jamais** justifier :
|
||||
|
||||
```text
|
||||
std::env direct dans Transport
|
||||
api-key hardcodée
|
||||
secret dans fixture
|
||||
secret dans commande/delta/log
|
||||
nouvelle dépendance Transport -> Config
|
||||
```
|
||||
|
||||
`pre.001` doit décider une stratégie compatible avec l'architecture. Si aucune surface d'intégration sûre n'existe encore, il est acceptable de garder la compliance provider principalement déterministe et de documenter un smoke opérateur séparé au lieu de violer les frontières KSP.
|
||||
|
||||
---
|
||||
|
||||
## 15. Critères de clôture de `0.2.8`
|
||||
|
||||
La release ne peut passer stable que si :
|
||||
|
||||
```text
|
||||
surface Helius WebSocket actuelle auditée et rapprochée
|
||||
chaque capacité ciblée a un statut explicite
|
||||
aucune méthode/options Helius retenue n'est perdue
|
||||
standard Solana 18/18 non régressé
|
||||
HTTP 52 current + 14 historical non régressé
|
||||
moteur WsSession unique réutilisé
|
||||
aucun second client WebSocket provider-specific
|
||||
Config -> Transport reste la seule direction d'adaptation
|
||||
credentials Helius redacted partout
|
||||
heartbeat/idle behavior audité et testé si implémenté
|
||||
reconnect/resubscribe/backpressure/shutdown restent bornés
|
||||
aucune fausse promesse lossless/replay WebSocket
|
||||
aucune dépendance Store/Program/Wallet/Config/tracing direct dans Transport
|
||||
dépendances directes et doublons transitifs inspectés
|
||||
fixtures déterministes vertes
|
||||
workspace complet vert
|
||||
README/USAGE synchronisés et version-neutral
|
||||
matrice finale de validation fermée
|
||||
prompt 0.2.9 préparé
|
||||
```
|
||||
|
||||
`CHANGELOG.md` et le statut stable du ROADMAP ne sont finalisés qu'à la publication `rel.001`.
|
||||
|
||||
---
|
||||
|
||||
## 16. Release/session suivante envisagée
|
||||
|
||||
La release suivante prévue est :
|
||||
|
||||
```text
|
||||
0.2.9 — Yellowstone gRPC standard/provider-neutral
|
||||
```
|
||||
|
||||
Elle doit partir du moteur Transport stabilisé mais **ne doit pas être anticipée dans `0.2.8`** par l'ajout de dépendances gRPC, de protobufs Yellowstone ou du SDK LaserStream gRPC.
|
||||
|
||||
Le prompt `0.2.9` devra imposer un nouvel audit normatif de la surface Yellowstone actuelle et un sizing complet avant implémentation.
|
||||
|
||||
---
|
||||
|
||||
## 17. Instruction d'ouverture
|
||||
|
||||
Au début de la nouvelle session `0.2.8` :
|
||||
|
||||
1. vérifier que la base est réellement `v0.2.7` ou l'archive stable autoritaire fournie ;
|
||||
2. lire les sources internes obligatoires dans l'ordre indiqué ;
|
||||
3. relire `deltas/0.2.7/rel.001.md`, le plan et la matrice finale WebSocket standard ;
|
||||
4. inspecter le code public/réel de `WsSession`, `WsSubscription`, `WsProtocolKind` et Config V2 ;
|
||||
5. réauditer immédiatement la documentation officielle Helius LaserStream WebSocket du jour ;
|
||||
6. produire la matrice standard/supporté/extension/non-supporté ;
|
||||
7. brainstormer provider credentials, heartbeat, capabilities, reconnect et tests ;
|
||||
8. dimensionner/recalibrer la release et écrire `pre.001` ;
|
||||
9. exécuter les validations de gate disponibles ;
|
||||
10. **ne pas commencer `transactionSubscribe`, modifier Config ou ajouter une dépendance avant que ce gate soit cohérent**.
|
||||
|
||||
La première réponse de travail doit donc être un **audit/sizing `0.2.8-pre.001`**, pas une implémentation prématurée.
|
||||
Reference in New Issue
Block a user