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

v0.2.9-pre.009

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-24 17:26:27 +02:00
parent 433e69272a
commit a9fb6a7ac8
12 changed files with 1498 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md -->
<!-- version: 17 -->
<!-- version: 18 -->
# Plan `0.2.9` — moteur Yellowstone gRPC + standard Solana + PublicNode
> **Statut : `0.2.9-pre.008` est fonctionnellement verte sur gate opérateur : fmt/audit/check/tests/workspace PASS, Transport 370 unit + 47 public API + 41 completeness + 4 doctests. Clippy passe mais émet un unique warning `field_reassign_with_default` dans la fixture `unit_tests/grpc_subscribe.rs`. `0.2.9-pre.008-fix.001` est candidate et corrige uniquement cette hygiène de fixture ; aucun changement runtime Blocks ni bidi.**
> **Statut : `0.2.9-pre.008-fix.001` est fermée sur gate opérateur sans warning : fmt/audit/check/Clippy/workspace PASS, Transport 370 unit + 47 public API + 41 completeness + 4 doctests. `0.2.9-pre.009` est candidate : stream bidi standard réel, mutation request, Ping/Pong, backpressure, half-close et shutdown borné ; reconnect/replay restent `pre.010`.**
## 1. Objet, base et état d'ouverture
@@ -931,11 +931,11 @@ pre.006 DONE — structure Transport : namespace privé HTTP explicite
pre.007 DONE — standard Solana : Transactions + transaction_status
budget : 15–20 min ; preuve : include/exclude/required/Cuckoo/token expansion + tx/meta + TransactionConfig V1
pre.008 FIX.001 CANDIDATE — standard Solana : Blocks + block_meta + entry
budget : 15–20 min ; gate fonctionnel PASS 370/47/41/4 + workspace ; fix fixture Clippy warning-only
pre.008 DONE — standard Solana : Blocks + block_meta + entry
budget : 15–20 min ; gate final fix.001 : fmt/audit/check/Clippy/workspace PASS sans warning + Transport 370/47/41/4
pre.009 moteur partagé : bidi mutation + Ping/Pong + half-close + backpressure + shutdown
budget : 15–20 min ; preuve : actor/session local + bounded queues + cleanup déterministe
pre.009 CANDIDATE — moteur partagé : bidi mutation + Ping/Pong + half-close + backpressure + shutdown
budget : 15–20 min ; preuve : fixture locale bidi + bounded queues + half-close/drop/timeout déterministes
pre.010 moteur partagé : reconnect/resubscribe + from_slot/ReplayInfo + gaps/duplicates
budget : 15–20 min ; preuve : reconnect local déterministe + aucune promesse lossless
@@ -1342,5 +1342,32 @@ Le premier gate opérateur de `pre.008` confirme l'intégralité du contrat Bloc
Le fix remplace la construction `TransactionStatusMeta::default()` suivie de `meta.fee = 5_000` par un initialiseur struct avec `fee: 5_000` et `..Default::default()`. Aucun `allow`, aucune API, aucun DTO, aucun wire et aucune logique runtime ne changent.
**Gate attendu :** même gate opérateur, sans warning Clippy. Le bidi reste strictement `pre.009`.
**Gate final :** fmt/audit/check/Clippy/workspace PASS sans warning. `pre.008-fix.001` est fermée ; le bidi reste strictement `pre.009`.
## 26. `pre.009` — stream bidi standard + lifecycle borné candidate
`pre.009` ouvre pour la première fois le RPC `/geyser.Geyser/Subscribe` en runtime KSP, sans `yellowstone-grpc-client` et sans second moteur physique. `YellowstoneGrpcChannel::open_standard_subscribe()` construit une `SolanaYellowstoneGrpcSubscribeSession` sur le channel Tonic déjà possédé par N1.
Contrat de la tranche :
```text
request initial validé + taille protobuf bornée
file request mpsc bornée et directement consommée par Tonic
try_update() non bloquant : validation + encoded_len + Full/Closed explicites
file update mpsc bornée ; slow receiver => terminal backpressure overflow
SubscribeUpdate complet : Account/Slot/Transaction/TransactionStatus/Block/Ping/Pong/BlockMeta/Entry
server Ping => réponse automatique ping-only id=1
Pong => update KSP observable
server half-close => terminal normal Ok(None)
client close => drop des senders request + half-close + attente close_timeout
Drop session => signal best-effort de half-close borné
Status/malformed/overflow => terminal Failed avec KspError sûr
inbound/outbound max message sizes => Tonic + validation locale outbound
```
Les conversions request et décodeurs update introduits sous `#[cfg(test)]` en `pre.004–008` deviennent ici des helpers runtime privés réellement consommés. Aucun type Tonic/protobuf n'est exposé dans l'API publique.
Le reconnect est volontairement absent de `pre.009` : un server half-close est normal et terminal pour cette tranche ; un `Status` ou une erreur de protocole termine la session. `from_slot`, ReplayInfo, resubscribe, gaps/duplicates et changement de node restent `pre.010`. `SubscribeDeshred`, PublicNode et Config V3 restent hors scope.
**Gate candidat :** audit statique clean ; fixture locale couvre round-trip, mutation, Ping/Pong, server half-close, client half-close, shutdown hostile borné, Drop best-effort, update overflow, Status distant sûr, update malformed et rejet outbound oversized. Compilation/Clippy/tests opérateur requis avant fermeture.

85
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
View File

@@ -1,9 +1,9 @@
<!-- file: docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# Validation `0.2.9` — moteur Yellowstone + standard Solana + PublicNode
> **Statut : `pre.008` est fonctionnellement verte : fmt/audit/check/tests/workspace PASS, Transport 370 unit + 47 public API + 41 completeness + 4 doctests. Clippy passe avec un unique warning `field_reassign_with_default` dans la fixture Blocks. `pre.008-fix.001` corrige uniquement ce warning ; bidi reste `pre.009`.**
> **Statut : `pre.008-fix.001` est fermée sur gate opérateur sans warning : fmt/audit/check/Clippy/workspace PASS, Transport 370 unit + 47 public API + 41 completeness + 4 doctests. `pre.009` est candidate pour le bidi standard, mutation request, Ping/Pong, backpressure, half-close et shutdown borné ; reconnect/replay restent `pre.010`.**
## 1. Autorités du gate
@@ -55,17 +55,17 @@ crate proto : 12.6.0
## 3. Matrice service `Geyser`
| RPC | Forme | Classification | Scope | Preuve cible | État |
|-----------------------|-------|------------------------------------------------------|-------|-----------------------|-------------------------------------------------------|
| `Subscribe` | bidi | standard | IN | fixture locale + live | PARTIAL pre.008 filters/updates / stream TODO pre.009 |
| `SubscribeDeshred` | bidi | Triton extension/pré-exécution malgré présence proto | OUT | canari d'absence/API | OUT |
| `SubscribeReplayInfo` | unary | standard | IN | fixture unary | DONE pre.003 |
| `Ping` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetLatestBlockhash` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetBlockHeight` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetSlot` | unary | standard | IN | fixture unary | DONE pre.003 |
| `IsBlockhashValid` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetVersion` | unary | standard | IN | fixture unary | DONE pre.003 |
| RPC | Forme | Classification | Scope | Preuve cible | État |
|-----------------------|-------|------------------------------------------------------|-------|-----------------------|--------------------------------|
| `Subscribe` | bidi | standard | IN | fixture locale + live | CANDIDATE pre.009 runtime bidi |
| `SubscribeDeshred` | bidi | Triton extension/pré-exécution malgré présence proto | OUT | canari d'absence/API | OUT |
| `SubscribeReplayInfo` | unary | standard | IN | fixture unary | DONE pre.003 |
| `Ping` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetLatestBlockhash` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetBlockHeight` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetSlot` | unary | standard | IN | fixture unary | DONE pre.003 |
| `IsBlockhashValid` | unary | standard | IN | fixture unary | DONE pre.003 |
| `GetVersion` | unary | standard | IN | fixture unary | DONE pre.003 |
## 4. `SubscribeRequest` — coverage normative
@@ -289,15 +289,15 @@ DONE pre.003 source/tests channel/client Debug sans URL, metadata value ni raw
| Cas | Attendu | État |
|--------------------------------------------|------------------------------------------|-----------------------------------|
| stream open | session bornée | TODO |
| request mutation | ordre déterministe | TODO |
| server Ping -> client request ping -> Pong | explicite | TODO |
| server half-close | terminal/reconnect selon policy | TODO |
| client close | cleanup borné | TODO |
| receiver drop | cleanup capacité | TODO |
| slow subscription | pas de queue infinie | TODO |
| inbound oversized | rejet avant allocation excessive | TODO |
| outbound oversized | rejet avant write | TODO |
| stream open | session bornée | CANDIDATE pre.009 |
| request mutation | ordre déterministe | CANDIDATE pre.009 |
| server Ping -> client request ping -> Pong | explicite | CANDIDATE pre.009 |
| server half-close | terminal normal avant reconnect | CANDIDATE pre.009 |
| client close | half-close + cleanup borné | CANDIDATE pre.009 |
| receiver drop | Drop session => cleanup best-effort | CANDIDATE pre.009 |
| slow subscription | pas de queue infinie | CANDIDATE pre.009 |
| inbound oversized | limite Tonic avant payload KSP | CANDIDATE pre.009 |
| outbound oversized | encoded_len avant queue/write | CANDIDATE pre.009 |
| reconnect budget | borné | TODO |
| resubscribe order | déterministe | TODO |
| `from_slot` | utilisé sans promesse lossless | TODO |
@@ -410,8 +410,8 @@ pre.004 DONE standard: Subscribe common/from_slot/bounds 15
pre.005 DONE standard: accounts + slots 15–20 min ; gate final fix.001 PASS
pre.006 DONE structure: namespace privé HTTP `http_*` 15–20 min ; gate PASS
pre.007 DONE standard: transactions + transaction_status 15–20 min ; gate PASS
pre.008 FIX.001 CANDIDATE standard: blocks + block_meta + entry 15–20 min ; gate fonctionnel PASS, 1 warning Clippy fixture
pre.009 TODO moteur: bidi/backpressure/half-close/shutdown 15–20 min
pre.008 DONE standard: blocks + block_meta + entry 15–20 min ; gate final fix.001 PASS sans warning
pre.009 CANDIDATE moteur: bidi/backpressure/half-close/shutdown 15–20 min ; fixture locale adversariale
pre.010 TODO moteur: reconnect/replay/gap/duplicate 15–20 min
pre.011 TODO Config V3 + protocol/provider + profils PublicNode 15–20 min
pre.012 TODO PublicNode live + compliance + docs/prompt 0.2.10 15–20 min
@@ -882,5 +882,40 @@ Les helpers wire/decode restent test-only jusqu’au premier consommateur runtim
Le warning provient uniquement de `minimal_transaction_info()` dans `unit_tests/grpc_subscribe.rs`. `fix.001` initialise `TransactionStatusMeta.fee` directement dans le literal struct et conserve `..Default::default()`. Aucun `allow`, aucun changement runtime, aucune dépendance et aucun élargissement vers le bidi.
**Verdict `fix.001` : candidate warning-only ; fermeture de `pre.008` après gate opérateur sans warning.**
**Verdict `fix.001` : PASS sans warning ; `pre.008` fermée.**
## 27. Gate `pre.009` — bidi standard + backpressure + half-close + shutdown candidate
| Surface / invariant | État candidate |
|-------------------------------------------------|----------------|
| workspace version | `0.2.9-pre.9` |
| `/geyser.Geyser/Subscribe` bidi | SOURCE+TEST |
| request initial dans queue bornée | SOURCE+TEST |
| mutation `try_update()` ordonnée/non bloquante | SOURCE+TEST |
| aucune `unbounded_channel` | CANARY |
| decode des 9 variantes standard | SOURCE+TEST |
| server Ping -> ping-only id=1 | SOURCE+TEST |
| Pong observable | SOURCE+TEST |
| server half-close => `Ok(None)` | SOURCE+TEST |
| client close => request half-close | SOURCE+TEST |
| shutdown hostile borné par `close_timeout` | SOURCE+TEST |
| Drop session => half-close best-effort | SOURCE+TEST |
| slow receiver => terminal backpressure overflow | SOURCE+TEST |
| Status distant sans message/details secrets | SOURCE+TEST |
| update malformed => invalid response | SOURCE+TEST |
| max inbound Tonic | SOURCE+TEST |
| outbound encoded_len avant dispatch | SOURCE+TEST |
| reconnect/resubscribe/replay | OUT pre.009 |
| `SubscribeDeshred` | OUT 0.2.9 |
| PublicNode / Config V3 | OUT pre.009 |
| audit Rust workspace local | PASS / clean |
| fmt/check/Clippy/tests/workspace | opérateur TODO |
Les helpers protobuf qui étaient test-only jusqu'à `pre.008` sont maintenant compilés en runtime parce que `grpc_stream` les consomme effectivement. Aucun helper raw n'est public : les frontières restent `YellowstoneSubscribeRequest` et `YellowstoneSubscribeUpdate`.
Le flux sortant utilise la même `mpsc` bornée que celle fournie à `tonic::client::Grpc::streaming`; aucune queue cachée non bornée n'est interposée. Le Ping de keepalive serveur provoque une mutation ping-only actor-owned avec `id=1`, puis le Pong reste visible dans la file d'updates KSP.
`pre.009` ne tente aucun reconnect. Un half-close serveur est terminal normal ; `Status`, decode invalide et overflow sont terminaux en erreur. Le budget de reconnect, l'ordre de resubscribe, `from_slot`/ReplayInfo, gaps, duplicates et node divergence restent exclusivement `pre.010`.
**Verdict candidat :** source/fixture/audit statique prêts ; gate Cargo opérateur requis.