Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.7-pre.001-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-22 16:00:56 +02:00
parent 9e8fd53291
commit cf4b28df2b
3 changed files with 310 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Validation `0.2.7` — WebSocket Solana standard
@@ -70,26 +70,83 @@ Pour une paire unstable, l'unsubscribe associé est classé `Unstable pair` dans
Les contexts WebSocket documentés omettent `apiVersion`. `SolanaRpcContext.api_version: Option<String>` est compatible avec cette omission.
## 4. Source Agave ciblée pour ambiguïtés
## 4. Baselines Git Agave et SIMD
Les pages officielles WebSocket du 2026-08-22 lient actuellement Agave `v3.1.8` pour les handlers PubSub :
### 4.1 Hiérarchie de contrôle
La compliance applique le même modèle que la compliance HTTP finale :
```text
https://github.com/anza-xyz/agave/blob/v3.1.8/rpc/src/rpc_pubsub.rs
https://github.com/anza-xyz/agave/blob/v3.1.8/rpc/src/rpc_subscriptions.rs
documentation Solana actuelle
-> surface publique annoncée
Git Agave tag courant audité v4.2.1
-> implémentation réelle et types wire
SIMD main
-> évolutions Activated, Review, Draft ou Idea à surveiller
```
Les pages Solana peuvent lier une révision Agave plus ancienne. KSP ne confond donc pas le lien source embarqué dans une page documentaire avec la baseline Git courante. Au 2026-08-22, **Agave `v4.2.1`** est disponible sur Git et devient la baseline d'implémentation de `0.2.7`.
Sources Agave ciblées :
```text
https://github.com/anza-xyz/agave/blob/v4.2.1/rpc/src/rpc_pubsub.rs
https://github.com/anza-xyz/agave/blob/v4.2.1/rpc/src/rpc_subscriptions.rs
https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/response.rs
```
### 4.2 Constats Agave `v4.2.1`
Le cross-check du tag courant confirme les **9 subscribe + 9 unsubscribe** déjà inventoriés par la documentation publique et ne révèle aucune opération PubSub standard supplémentaire.
Constats ciblés :
- `accountSubscribe` : le type partagé `RpcAccountInfoConfig` expose `min_context_slot`, mais le handler PubSub `v3.1.8` le destructure en `_ // ignored`. KSP ne le compte donc pas comme option WebSocket effective ;
- `programSubscribe` : `RpcProgramAccountsConfig.with_context` est lu dans `ProgramSubscriptionParams`, le trait exposé dans `rpc_pubsub.rs` utilise `Subscriber<RpcResponse<RpcKeyedAccount>>`, le helper `check_commitment_and_notify` construit un `RpcResponse` avec contexte, et aucune consommation `with_context` n'a été retrouvée dans `rpc_subscriptions.rs` lors de l'audit ;
- `accountSubscribe` : le type partagé `RpcAccountInfoConfig` expose `min_context_slot`, mais le handler PubSub `v4.2.1` le destructure en `_ // ignored`. KSP ne le compte donc pas comme option WebSocket effective ;
- `programSubscribe` : `RpcProgramAccountsConfig.with_context` est lu et doit rester dans le contrat KSP ; la tolérance contexted/non-contexted reste requise pour ne pas convertir les divergences docs/source/provider en perte wire ;
- `logsSubscribe` : le handler accepte `all`, `allWithVotes` ou `mentions` et rejette un filtre `mentions` contenant autre chose qu'exactement une adresse ;
- `signatureSubscribe` : le handler utilise la signature, `commitment` et `enable_received_notification`, sans option WebSocket supplémentaire ;
- `blockSubscribe` : le handler consomme le jeu d'options documenté et impose un commitment au moins `confirmed` ;
- `*Unsubscribe` : un ID serveur inconnu produit `InvalidParams` dans le handler audité ;
- `voteSubscribe` : `RpcVote.timestamp` est `Option<i64>`, ce qui justifie de préserver l'optionalité wire sans valeur inventée.
- `voteSubscribe` : `RpcVote.timestamp` est `Option<UnixTimestamp>`, donc optionnel au niveau wire ;
- `slotsUpdatesSubscribe` : `SlotUpdate` possède toujours les sept variantes courantes `FirstShredReceived`, `Completed`, `CreatedBank`, `Frozen`, `Dead`, `OptimisticConfirmation` et `Root`.
Décisions compliance : transmettre `programSubscribe.withContext` malgré l'écart observé et accepter les formes contextée/non-contextée ; ne pas promettre `accountSubscribe.minContextSlot` tant qu'il est ignoré upstream ; conserver `vote.timestamp` comme champ optionnel/tolérant.
Décisions compliance : transmettre `programSubscribe.withContext`, accepter les formes contextée/non-contextée, ne pas promettre `accountSubscribe.minContextSlot` tant qu'il est ignoré upstream, conserver `vote.timestamp` optionnel et garder un fallback borné pour toute future variante `SlotUpdate` inconnue.
### 4.3 Audit SIMD ciblé
Aucun SIMD audité n'ajoute actuellement une dixième famille de subscription standard à la surface Agave `v4.2.1`. Ils modifient en revanche des hypothèses que KSP doit éviter de figer.
| SIMD | Statut au 2026-08-22 | Conséquence WebSocket KSP |
|-----------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `0118` Partitioned Epoch Rewards Distribution | Activated | conserver les DTOs bloc/rewards HTTP déjà lossless, dont `numRewardPartitions` omitted, `null` ou valeur |
| `0291` Commission Rate in Basis Points | Review | conserver les représentations de commission upstream indépendantes lorsqu'elles sont présentes |
| `0296` Larger Transaction Size | Review | proposition jusqu'à 4096 octets : ne pas déduire les limites WS de l'ancienne taille transaction 1232 ; surveiller `blockSubscribe` |
| `0298` Bank Hash in Block Footer | Idea | aucun `bankHash` spéculatif dans le wire courant ; surveiller le DTO bloc partagé |
| `0301` parent bank hash | PR fermé, non mergé | aucun `parentBankHash` spéculatif ; même conclusion que la compliance HTTP |
| `0307` Add Block Footer | Review | aucun `footer` spéculatif ; réauditer `blockSubscribe` lorsque l'upstream l'expose réellement |
| `0326` Alpenglow | Review | ne pas figer les sémantiques TowerBFT de `voteSubscribe` ou `optimisticConfirmation` dans un contrat durable |
| `0337` Alpenglow Fast Leader Handover Markers | Review | nouveaux block markers futurs : surveiller shape et taille, sans ajout WS anticipé |
| `0384` Alpenglow migration | Review | des notifications RPC commitment/optimistic confirmation peuvent être suspendues pendant migration ; aucune hypothèse de séquence exhaustive |
| `0385` Transaction V1 | Review | `maxSupportedTransactionVersion` et les versions transaction restent génériques ; ne pas caper KSP à v0 |
Sources SIMD :
```text
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0118-partitioned-epoch-reward-distribution.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0291-commission-rate-in-basis-points.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0296-larger-transactions.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0298-bank-hash-in-block-footer.md
https://github.com/solana-foundation/solana-improvement-documents/pull/301
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0307-add-block-footer.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0326-alpenglow.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0337-parent-ready-update-marker.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0384-alpenglow-migration.md
https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0385-transaction-v1.md
```
Les limites WebSocket sont donc des bornes KSP configurables et finies, jamais une transposition en dur de l'ancienne limite transaction de 1232 octets.
## 5. Méthodes unstable
@@ -132,20 +189,20 @@ Les votes observés sont gossip/pre-consensus ; aucune garantie d'entrée dans l
## 6. Lifecycle compliance initiale
| Contrat | Décision `pre.001` | Gate cible |
|---|---|---|
| plusieurs sessions / même URL | création physique explicite ; aucun singleton/pool automatique | `pre.004`, `pre.012` |
| plusieurs subs / session | registry actor par session | `pre.006` |
| ID public subscription | local KSP stable | `pre.006` |
| ID serveur | éphémère interne et remappé | `pre.006`/`pre.007` |
| session states | Disconnected/Connecting/Active/Reconnecting/Closing/Closed/Failed | `pre.002` |
| subscription states | Requested/Active/Resubscribing/Cancelling/Closed/Failed | `pre.002` |
| reconnect | physique uniquement, budget/backoff finis | `pre.007` |
| resubscribe | policy `Never|ActiveSubscriptions`, ordre local déterministe | `pre.007` |
| continuity | gap observable, aucune promesse lossless | `pre.007` |
| backpressure | queue par sub bounded ; overflow => fail local explicite | `pre.008` |
| shutdown | explicite, bounded, annule reconnect et subscriptions | `pre.005` |
| keepalive | pas de ping applicatif périodique sans besoin démontré | `pre.005` |
| Contrat | Décision `pre.001` | Gate cible |
|-------------------------------|-------------------------------------------------------------------|----------------------|
| plusieurs sessions / même URL | création physique explicite ; aucun singleton/pool automatique | `pre.004`, `pre.012` |
| plusieurs subs / session | registry actor par session | `pre.006` |
| ID public subscription | local KSP stable | `pre.006` |
| ID serveur | éphémère interne et remappé | `pre.006`/`pre.007` |
| session states | Disconnected/Connecting/Active/Reconnecting/Closing/Closed/Failed | `pre.002` |
| subscription states | Requested/Active/Resubscribing/Cancelling/Closed/Failed | `pre.002` |
| reconnect | physique uniquement, budget/backoff finis | `pre.007` |
| resubscribe | policy `Never` ou `ActiveSubscriptions`, ordre local déterministe | `pre.007` |
| continuity | gap observable, aucune promesse lossless | `pre.007` |
| backpressure | queue par sub bounded ; overflow => fail local explicite | `pre.008` |
| shutdown | explicite, bounded, annule reconnect et subscriptions | `pre.005` |
| keepalive | pas de ping applicatif périodique sans besoin démontré | `pre.005` |
## 7. Threat/security compliance initiale
@@ -201,10 +258,14 @@ V1 actuel : HTTP-only strict. Décision :
```text
V1 -> support de lecture conservé, WS vide
V2 -> HTTP existant + ws_defaults + profiles[].ws_endpoints
profiles[].ws_endpoints[].kind -> discriminateur de famille/protocole WS
0.2.7 -> seule valeur supportée : solana_standard
Config -> WsTransportSettings
Transport -X-> Config
```
Le type Transport correspondant au discriminateur est prévu `#[non_exhaustive]`. L'objectif est de pouvoir ajouter ultérieurement une famille telle que Helius Enhanced WebSocket sans créer un nouveau conteneur Config ni injecter des options provider-specific dans les settings Solana standard. Toute valeur inconnue reste explicitement rejetée en `0.2.7`; aucun paramètre Helius n'est implémenté par anticipation.
La schema V1 n'est pas assouplie. Une schema V2 explicite remplace la fixture standard au moment où l'adapter est matérialisé.
## 10. Validation du gate `pre.001`
@@ -217,11 +278,13 @@ lecture règles/architecture/plans/validation OK
inventaire Transport/Config réel OK
archive bot3 WebSocket auditée OK
audit docs officielles WebSocket OK
cross-check Git Agave v4.2.1 OK
audit SIMD WebSocket ciblé OK
inventaire exact 18 = 9+9 OK
audit dependencies candidates OK
state machines / reconnect / resubscribe DECIDED
backpressure / cancellation / shutdown / secrets DECIDED
shape Config V2 minimal DECIDED
shape Config V2 + discriminateur famille WS DECIDED
plan/sizing OK
python3 scripts/audit_rust_workspace_rules.py baseline OK
```