269 lines
8.1 KiB
Markdown
269 lines
8.1 KiB
Markdown
<!-- file: deltas/0.2.8/pre.001.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.2.8-pre.001` — audit/sizing Helius LaserStream WebSocket
|
||
|
||
## 1. Base requise et vérifiée
|
||
|
||
Archive autoritaire fournie :
|
||
|
||
```text
|
||
khadhroony-solana-project-v0.2.7-full-from-gitea.zip
|
||
```
|
||
|
||
État vérifié :
|
||
|
||
```text
|
||
workspace.package.version = 0.2.7
|
||
deltas/0.2.7/rel.001.md présent
|
||
prompts/013-V0_2_8_START_PROMPT.md présent
|
||
metadata .git absente de l'archive
|
||
```
|
||
|
||
Cette livraison ouvre :
|
||
|
||
```text
|
||
workspace.package.version = 0.2.8-pre.1
|
||
commit attendu = v0.2.8-pre.001
|
||
aucun tag prerelease
|
||
```
|
||
|
||
## 2. Objet
|
||
|
||
`pre.001` est strictement le gate **audit + brainstorming + sizing** de `0.2.8 — Helius LaserStream WebSocket`.
|
||
|
||
Il ne modifie :
|
||
|
||
```text
|
||
aucun fichier Rust
|
||
aucun schema/config runtime
|
||
aucune dependency
|
||
aucun README/USAGE Transport
|
||
aucun secret/environment runtime
|
||
```
|
||
|
||
Il crée le plan durable, ouvre la matrice de validation, synchronise les index et recalcule la prévision souple.
|
||
|
||
## 3. Baseline acquise
|
||
|
||
Preuve opérateur jointe avant ouverture :
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
Le sandbox de préparation a aussi exécuté :
|
||
|
||
```text
|
||
python3 scripts/audit_rust_workspace_rules.py OK
|
||
```
|
||
|
||
mais ne contient pas `cargo`; il ne déclare donc aucun gate Cargo local réussi.
|
||
|
||
Les graphes requis n'étaient pas présents dans le log opérateur et restent à exécuter avant commit :
|
||
|
||
```bash
|
||
cargo tree -p ksp-onchain-transport-lib
|
||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||
```
|
||
|
||
## 4. Résultat de l'audit Helius du 2026-08-23
|
||
|
||
Terminologie/endpoints :
|
||
|
||
```text
|
||
produit courant = LaserStream WebSocket
|
||
Enhanced WebSockets = ancien nom intégré au produit courant
|
||
mainnet = wss://mainnet.helius-rpc.com/?api-key=...
|
||
devnet = wss://devnet.helius-rpc.com/?api-key=...
|
||
api-key = Secret query credential
|
||
LaserStream gRPC / Gatekeeper beta = hors scope
|
||
```
|
||
|
||
Surface retenue :
|
||
|
||
```text
|
||
Helius supporte les paires standard :
|
||
account, logs, program, root, signature, slot
|
||
|
||
Helius ne supporte pas d'après l'index exhaustif :
|
||
block, slotsUpdates, vote
|
||
|
||
Helius extension :
|
||
transactionSubscribe
|
||
transactionUnsubscribe
|
||
notification = transactionNotification
|
||
```
|
||
|
||
La documentation Helius diverge sur `slotsUpdates`; l'index exhaustif `LaserStream WebSocket Methods` le classe explicitement parmi les méthodes unstable non supportées, tandis que `websocket/llms.txt` le place aussi dans une section « stable ». Le gate retient **non supporté** et exige un rejet KSP avant I/O pour `HeliusLaserStream`.
|
||
|
||
`transactionSubscribe` expose actuellement :
|
||
|
||
```text
|
||
vote
|
||
failed
|
||
signature
|
||
accountInclude <= 50_000
|
||
accountExclude <= 50_000
|
||
accountRequired <= 50_000
|
||
tokenAccounts = none | balanceChanged | all
|
||
commitment
|
||
encoding = base58 | base64 | jsonParsed
|
||
transactionDetails = full | signatures | accounts | none
|
||
showRewards
|
||
maxSupportedTransactionVersion
|
||
```
|
||
|
||
`maxSupportedTransactionVersion` est requis par la référence lorsque `transactionDetails` vaut `accounts` ou `full`.
|
||
|
||
`notifyOn` est toujours visible dans les références account/program mais est désormais **deprecated et no-op depuis Agave 4.2**. Il ne sera pas ajouté à KSP.
|
||
|
||
La documentation continue de parler d'« enhanced/filtered accountSubscribe » sans publier, dans les références courantes auditées, un wire provider supplémentaire assez exact pour une API typed. Cette capacité est reportée explicitement au lieu d'être inventée.
|
||
|
||
## 5. Décisions du gate
|
||
|
||
```text
|
||
WsProtocolKind cible = HeliusLaserStream
|
||
wire/config string = helius_laserstream
|
||
provider metadata = helius
|
||
session actor = WsSession existant, aucun second client
|
||
new subscription kind = HeliusTransaction
|
||
provider capability = validation déterministe avant I/O
|
||
Helius standard support = Account Logs Program Root Signature Slot
|
||
Helius standard reject = Block SlotsUpdates Vote
|
||
notifyOn = non exposé
|
||
tokenAccounts = enum provider typed
|
||
heartbeat = actor Helius-only, cible 60 s
|
||
Config = ajout kind V2, même ws_endpoints[]
|
||
credential = URL résolue par Config derrière WsEndpointUrl
|
||
new dependency = aucune
|
||
WebSocket historical replay= aucune promesse
|
||
```
|
||
|
||
## 6. Threat model retenu
|
||
|
||
Points couverts par le plan :
|
||
|
||
```text
|
||
api-key dans query URL et erreurs handshake
|
||
heartbeat concurrent avec reconnect/close
|
||
late messages après transactionUnsubscribe
|
||
remote ids transitoires
|
||
provider capability mismatch
|
||
provider RPC errors sans session death automatique
|
||
transaction payload volumineux
|
||
3 listes de filtres jusqu'à 50k chacune
|
||
queue/frame/message bounds
|
||
unknown provider fields/modes de notification
|
||
continuity gaps après reconnect
|
||
```
|
||
|
||
## 7. Forecast recalibré
|
||
|
||
Le forecast initial `pre.001 -> pre.011` est resserré car `notifyOn` n'est pas une capacité utile et aucun wire account/program provider additionnel précis n'est actuellement publiable.
|
||
|
||
Forecast courant :
|
||
|
||
```text
|
||
pre.001 audit/sizing/matrice
|
||
pre.002 protocol descriptor + subscription kind + capability/redaction
|
||
pre.003 Config V2 helius_laserstream + secret strategy
|
||
pre.004 transactionSubscribe/unsubscribe request/filter/options
|
||
pre.005 transactionNotification + reconnect/resubscribe/unsubscribe races
|
||
pre.006 heartbeat/idle lifecycle
|
||
pre.007 adversarial provider/security/backpressure
|
||
pre.008 compliance + WS 18/18 + HTTP 52/14 + Config canaries
|
||
pre.009 live smoke opt-in si sûr + README/USAGE + cargo graphs
|
||
pre.010 workspace final + docs/matrix + prompt 0.2.9
|
||
rel.001 stable
|
||
```
|
||
|
||
Chaque tranche vise ~15–20 minutes. Le forecast peut être scindé/étendu si une ambiguïté normative ou une difficulté de lifecycle le justifie. `pre.010` n'est pas une deadline.
|
||
|
||
## 8. Fichiers ajoutés
|
||
|
||
```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
|
||
```
|
||
|
||
## 9. Fichiers modifiés
|
||
|
||
```text
|
||
Cargo.toml
|
||
docs/000-README.md
|
||
docs/plans/000-README.md
|
||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||
docs/validation/000-README.md
|
||
```
|
||
|
||
## 10. Fichiers volontairement inchangés
|
||
|
||
```text
|
||
ROADMAP.md
|
||
CHANGELOG.md
|
||
.env.example
|
||
config/**
|
||
crates/**
|
||
docs/architecture/**
|
||
crates/ksp-onchain-transport-lib/README.md
|
||
crates/ksp-onchain-transport-lib/USAGE.md
|
||
```
|
||
|
||
`ROADMAP.md` possède déjà l'entrée globale `0.2.8`. Les documents/runtime Config/Transport ne changent pas avant le gate positif.
|
||
|
||
## 11. Validations réellement exécutées dans le sandbox de préparation
|
||
|
||
Avant modification :
|
||
|
||
```text
|
||
inspection archive/version/rel/prompt OK
|
||
lecture règles/architecture/plans/validation/code OK
|
||
réaudit officiel Helius actuel OK
|
||
inspection versions publiques dépendances OK
|
||
python3 scripts/audit_rust_workspace_rules.py OK
|
||
```
|
||
|
||
Après génération de l'overlay, l'audit Python a été réexécuté :
|
||
|
||
```text
|
||
General Rust rule audit: clean
|
||
Rust export completeness audit: 0 candidate(s)
|
||
KSP workspace Rust rule audit: clean
|
||
```
|
||
|
||
## 12. Validations impossibles dans le sandbox
|
||
|
||
```text
|
||
cargo fmt --all
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets
|
||
cargo test --workspace
|
||
cargo tree -p ksp-onchain-transport-lib
|
||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||
```
|
||
|
||
Cause : binaire `cargo` absent.
|
||
|
||
## 13. Validation opérateur requise avant commit
|
||
|
||
Appliquer l'overlay puis exécuter :
|
||
|
||
```bash
|
||
cargo fmt --all
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets
|
||
cargo tree -p ksp-onchain-transport-lib
|
||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||
```
|
||
|
||
`cargo test --workspace` a déjà été fourni vert sur la base `v0.2.7`; `pre.001` ne change aucun code/runtime, mais il peut être rejoué si l'opérateur souhaite un checkpoint complet de la nouvelle version Cargo.
|
||
|
||
Le gate `pre.001` ne devient entièrement positif qu'après revue des deux graphes Cargo. Aucun `pre.002` runtime ne doit commencer avant cela.
|