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

v0.2.9-pre.004

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-24 11:55:17 +02:00
parent feb9befb35
commit e4bbc78a41
9 changed files with 1163 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
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: 9 -->
<!-- version: 10 -->
# Plan `0.2.9` — moteur Yellowstone gRPC + standard Solana + PublicNode
> **Statut : `0.2.9-pre.003-fix.001` — `pre.002-fix.002` est fermée sur gate opérateur intégralement vert. Le premier gate `pre.003` confirme fmt/audit/check, les 354 unit tests Transport, 43 public API, 36 completeness, 4 doctests, le dependency canary et le workspace complet ; seul Clippy échoue sur `implicit_return` dans la fixture `#[tonic::async_trait]` et deux closures metadata. `fix.001` corrige uniquement cette conformité de test, sans changement du moteur/TLS/metadata/unary de production. `pre.003` ajoute uniquement TLS client, metadata générique redacted, connexion HTTP/2 réelle, fixture Geyser locale et les sept unary standard ; `Subscribe`, PublicNode et Config V3 restent hors tranche. `0.2.9` reste bornée à un moteur client Yellowstone partagé, une façade Solana Yellowstone standard et une première intégration concrète PublicNode. Seuls OrbitFlare puis Helius LaserStream gRPC sont actuellement planifiés comme releases provider suivantes ; les autres providers restent en TODO/IDEAS sans numéro réservé. Chaque prerelease vise 15–20 minutes de travail effectif et la release complète doit rester clôturable dans une seule session de chat.**
> **Statut : `0.2.9-pre.004` candidate. `pre.003-fix.001` est fermée sur gate opérateur intégralement vert : fmt/audit/check/Clippy/workspace PASS, Transport 354 unit + 43 public API + 36 completeness + 4 doctests, et graphes Cargo inspectés sans seconde version Tonic/Prost/Solana. `pre.004` matérialise uniquement la fondation `SubscribeRequest` standard : sept maps nommées, commitment, account-data slices ordonnées, ping, `from_slot`, bornes communes, unicité globale des noms et Debug sans payload arbitraire. Les champs détaillés Accounts/Slots/Transactions/Blocks restent réservés à `pre.005–007` et aucun stream bidi n'est encore ouvert. PublicNode et Config V3 restent hors tranche. `0.2.9` reste bornée à un moteur client Yellowstone partagé, une façade Solana Yellowstone standard et une première intégration concrète PublicNode. Seuls OrbitFlare puis Helius LaserStream gRPC sont actuellement planifiés comme releases provider suivantes ; les autres providers restent en TODO/IDEAS sans numéro réservé. Chaque prerelease vise 15–20 minutes de travail effectif et la release complète doit rester clôturable dans une seule session de chat.**
## 1. Objet, base et état d'ouverture
@@ -431,7 +431,18 @@ ping? id
from_slot? u64
```
KSP appliquera des bornes déterministes avant I/O sur les noms, cardinalités, listes de comptes/owners, memcmp, data slices et tailles de payload. Les valeurs exactes sont un contrat KSP et non une copie aveugle des quotas d'un provider ; elles seront matérialisées avec tests en `pre.004`.
KSP applique des bornes déterministes avant I/O sur les noms, cardinalités, listes de comptes/owners, memcmp, data slices et tailles de payload. Les valeurs exactes sont un contrat KSP et non une copie aveugle des quotas d'un provider. `pre.004` matérialise les bornes communes suivantes :
```text
filter groups nommés, total <= 1024 sur les sept maps
filter name non vide, trim exact, sans caractère de contrôle, <= 128 octets
filter names uniques globalement entre les sept maps
accounts_data_slice count <= 128
accounts_data_slice length <= 64 MiB
offset + length aucun overflow u64
```
Les bornes account/owner/include/exclude/required, memcmp et Cuckoo restent volontairement dans les tranches de famille `pre.005–007`.
## 8. Matrice `SubscribeUpdate`
@@ -905,11 +916,11 @@ pre.001 DONE — audit upstream/service/proto + providers gratuits + licences/d
pre.002 DONE — moteur Yellowstone : proto/dependencies + settings/errors + channel minimal
budget : 15–20 min ; gate final fix.002 : fmt/audit/check/Clippy + Transport 346/42/35/4 + dependency canary + workspace PASS
pre.003 FIX.001 CANDIDATE — moteur TLS/metadata + façade N2 unary + fixture locale + 7 unary RPCs
budget : 15–20 min ; preuve cible : connect/TLS/timeouts/Status safe + metadata redacted + wire unary exact + cargo tree
pre.003 DONE — moteur TLS/metadata + façade N2 unary + fixture locale + 7 unary RPCs
budget : 15–20 min ; gate final fix.001 : fmt/audit/check/Clippy/workspace PASS + graphes Cargo inspectés
pre.004 standard Solana : Subscribe foundation + maps/commitment/ping/from_slot/data slices/bounds
budget : 15–20 min ; preuve : omitted/empty/oneof exact + rejets avant I/O
pre.004 CANDIDATE — standard Solana : Subscribe foundation + maps/commitment/ping/from_slot/data slices/bounds
budget : 15–20 min ; preuve : map vide/entrée nommée vide/common wire exact + rejets déterministes avant I/O
pre.005 standard Solana : Accounts + Slots filters/updates
budget : 15–20 min ; preuve : fixtures exactes + enum/optional/malformed/adversarial
@@ -973,14 +984,16 @@ crates/ksp-onchain-transport-lib/unit_tests/grpc_unary.rs
crates/ksp-onchain-transport-lib/src/grpc_channel.rs
crates/ksp-onchain-transport-lib/src/grpc_settings.rs
# pre.004+
crates/ksp-onchain-transport-lib/src/grpc_session.rs
crates/ksp-onchain-transport-lib/src/grpc_protocol.rs
# pre.004
crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs
crates/ksp-onchain-transport-lib/src/grpc_updates.rs
unit_tests/ correspondants
crates/ksp-onchain-transport-lib/unit_tests/grpc_subscribe.rs
tests/public_api.rs
tests/release_completeness.rs
# pre.005+
crates/ksp-onchain-transport-lib/src/grpc_session.rs
crates/ksp-onchain-transport-lib/src/grpc_updates.rs
unit_tests/ correspondants
tests/yellowstone_grpc_*_smoke.rs
crates/ksp-config-lib/src/transport.rs
config/std.transport.json

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

@@ -3,7 +3,7 @@
# Validation `0.2.9` — moteur Yellowstone + standard Solana + PublicNode
> **Statut : `pre.002-fix.002` est fermé. Le premier gate `pre.003` confirme fmt/audit/check, Transport 354 unit + 43 public API + 36 release completeness + 4 doctests, Core dependency canary et workspace complet ; seul Clippy échoue sur 11 diagnostics `implicit_return` dans la fixture unary. `0.2.9-pre.003-fix.001` corrige uniquement ces diagnostics de test, sans changement runtime. TLS client, metadata générique redacted, connexion réelle et exactement sept unary Yellowstone standard restent la surface `pre.003` ; `Subscribe`, PublicNode et Config V3 restent hors tranche. OrbitFlare et Helius sont les seules releases provider suivantes planifiées ; les autres providers restent en TODO/IDEAS sans numéro réservé.**
> **Statut : `pre.003-fix.001` est fermé sur gate opérateur intégralement vert et graphes Cargo inspectés. `0.2.9-pre.004` est candidate et ajoute uniquement la fondation standard `SubscribeRequest` : sept maps, commitment, account-data slices, ping, `from_slot`, bornes communes et redaction Debug. Aucun stream bidi n'est encore ouvert ; les filtres détaillés Accounts/Slots/Transactions/Blocks restent réservés à `pre.005–007`. PublicNode et Config V3 restent hors tranche. OrbitFlare et Helius sont les seules releases provider suivantes planifiées ; les autres providers restent en TODO/IDEAS sans numéro réservé.**
## 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 | TODO |
| `SubscribeDeshred` | bidi | Triton extension/pré-exécution malgré présence proto | OUT | canari d'absence/API | TODO |
| `SubscribeReplayInfo` | unary | standard | IN | fixture unary | TODO |
| `Ping` | unary | standard | IN | fixture unary | TODO |
| `GetLatestBlockhash` | unary | standard | IN | fixture unary | TODO |
| `GetBlockHeight` | unary | standard | IN | fixture unary | TODO |
| `GetSlot` | unary | standard | IN | fixture unary | TODO |
| `IsBlockhashValid` | unary | standard | IN | fixture unary | TODO |
| `GetVersion` | unary | standard | IN | fixture unary | TODO |
| RPC | Forme | Classification | Scope | Preuve cible | État |
|-----------------------|-------|------------------------------------------------------|-------|-----------------------|-----------------------------------------------|
| `Subscribe` | bidi | standard | IN | fixture locale + live | PARTIAL pre.004 request / stream TODO pre.008 |
| `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
@@ -265,11 +265,11 @@ DONE/source+tests ajoutés close timeout > 0 et plafonné
DONE/source+tests ajoutés max inbound/outbound > 0 et plafonnés
DONE/source+tests ajoutés request/update queue capacities > 0 et plafonnées
DONE/source+tests ajoutés reconnect attempt/backoff bornés
TODO pre.004 filter-group count
TODO pre.004 filter-name length/uniqueness
CANDIDATE pre.004 filter-group count <= 1024 total sur les sept maps
CANDIDATE pre.004 filter-name non vide/trim/control-free <= 128 octets + unicité globale
DONE/source+tests ajoutés metadata ASCII key/value count/size + reserved/bin bounds
TODO pre.005+ account/owner/include/exclude/required counts
TODO pre.004+ memcmp/data slice bounds
CANDIDATE pre.004 data slice count <= 128, length <= 64 MiB, offset+length sans overflow ; memcmp TODO pre.005
TODO pre.005+ Cuckoo dimensions/data bounds
```
@@ -279,32 +279,32 @@ Security canaries :
DONE/source+tests ajoutés endpoint URL Debug redacted
DONE/source+tests ajoutés metadata publique/secrète redacted ; secret marqué sensitive
DONE/source+fixture Status message/details/metadata distants exclus des KspError
CANDIDATE pre.003 connect réel + TLS WebPKI configuré ; erreur connect/TLS safe, Cargo pending
TODO pre.004+ request/update Debug sans payload arbitraire sensible
DONE pre.003/fix.001 connect réel + TLS WebPKI configuré ; erreur connect/TLS safe, gate Cargo PASS
CANDIDATE pre.004 SubscribeRequest Debug sans filter names/payload arbitraire ; update Debug TODO pre.005+
DONE pre.003 source/tests channel/client Debug sans URL, metadata value ni raw Tonic ; lifecycle stream ultérieur
```
## 11. Lifecycle / backpressure / replay
| 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 |
| reconnect budget | borné | TODO |
| resubscribe order | déterministe | TODO |
| `from_slot` | utilisé sans promesse lossless | TODO |
| ReplayInfo | informatif | CANDIDATE |
| duplicates | observables | TODO |
| gaps | observables | TODO |
| divergent node history | couverture documentée | TODO |
| shutdown during reconnect | aucune nouvelle connexion après shutdown | TODO |
| 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 |
| reconnect budget | borné | TODO |
| resubscribe order | déterministe | TODO |
| `from_slot` | utilisé sans promesse lossless | TODO |
| ReplayInfo | informatif | DONE unary ; usage reconnect TODO |
| duplicates | observables | TODO |
| gaps | observables | TODO |
| divergent node history | couverture documentée | TODO |
| shutdown during reconnect | aucune nouvelle connexion après shutdown | TODO |
Claims interdits sans nouvelle preuve :
@@ -404,8 +404,8 @@ Les autres providers restent en TODO/IDEAS sans release dédiée. Aucune façade
```text
pre.001 DONE audit/sizing/architecture 15–20 min nominal
pre.002 DONE moteur: deps/settings/errors/channel 15–20 min ; gate final fix.002 PASS
pre.003 CANDIDATE TLS/metadata + fixture + 7 unary standard 15–20 min
pre.004 TODO standard: Subscribe common/from_slot/bounds 15–20 min
pre.003 DONE TLS/metadata + fixture + 7 unary standard 15–20 min ; gate final fix.001 PASS
pre.004 CANDIDATE standard: Subscribe common/from_slot/bounds 15–20 min
pre.005 TODO standard: accounts + slots 15–20 min
pre.006 TODO standard: transactions + transaction_status 15–20 min
pre.007 TODO standard: blocks + block_meta + entry 15–20 min
@@ -583,3 +583,51 @@ aucun Subscribe/PublicNode/Config V3 anticipé
```
**Verdict `pre.003-fix.001` : correctif Clippy minimal prêt ; fermeture de `pre.003` après réexécution verte des gates habituels et inspection des graphes Cargo demandée par la tranche.**
### 18.2 Gate final opérateur `pre.003-fix.001`
| Gate | Résultat final |
|-------------------------------------------|----------------|
| `cargo fmt --all` | PASS |
| audit Rust workspace | PASS / clean |
| `cargo check --workspace` | PASS |
| `cargo clippy --workspace --all-targets` | PASS |
| Transport unit | 354/354 PASS |
| Transport `public_api` | 43/43 PASS |
| Transport `release_completeness` | 36/36 PASS |
| Transport doctests | 4/4 PASS |
| `cargo test --workspace` | PASS |
| `cargo tree -p ...` | fourni/relu |
| `cargo tree -p ... -e features` | fourni/relu |
| `cargo tree -p ... --duplicates` | fourni/relu |
| `cargo tree --duplicates` | fourni/relu |
Graphe pertinent confirmé : `tonic 0.14.6`, `tonic-prost 0.14.6`, `prost/prost-types 0.14.4`, `yellowstone-grpc-proto 12.6.0`, `solana-pubkey 4.3.0`. Les features serveur/codegen et `yellowstone-grpc-proto/tonic` restent liées à la fixture dev/test ; aucune seconde version Tonic/Prost/Solana n'est introduite par la tranche.
**Verdict : `pre.003` fermée.**
## 19. Gate `pre.004` — candidate
| Surface | État candidate |
|-----------------------------------------------------|----------------|
| workspace version | `0.2.9-pre.4` |
| sept maps `SubscribeRequest` | SOURCE PASS |
| map vide / entrée nommée vide | SOURCE+TEST |
| commitment optional exact | SOURCE+TEST |
| account-data slices ordonnées | SOURCE+TEST |
| ping optional exact | SOURCE+TEST |
| `from_slot` optional exact | SOURCE+TEST |
| filter names <=128 octets / unicité globale | SOURCE+TEST |
| filter groups <=1024 total | SOURCE+TEST |
| slices <=128 / length <=64 MiB / overflow rejeté | SOURCE+TEST |
| request Debug sans noms/payloads de filtres | SOURCE+TEST |
| filtres Accounts/Slots détaillés | OUT pre.004 |
| filtres Transactions/Blocks détaillés | OUT pre.004 |
| stream bidi / lifecycle / updates | OUT pre.004 |
| PublicNode / Config V3 | OUT pre.004 |
| audit Rust workspace local | PASS / clean |
| fmt/check/Clippy/tests | opérateur TODO |
Le proto publié `yellowstone-grpc-proto 12.6.0` a été recontrôlé avant implémentation : les onze champs top-level retenus restent `accounts`, `slots`, `transactions`, `transactions_status`, `blocks`, `blocks_meta`, `entry`, `commitment`, `accounts_data_slice`, `ping`, `from_slot`. Aucun `SubscribeDeshred` n'entre dans la surface KSP.
**Verdict `pre.004` : candidate source prête ; fermeture après gate Cargo opérateur.**