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

v0.2.9-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-24 09:54:14 +02:00
parent 21de590aea
commit 835de48cb7
14 changed files with 1302 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
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: 4 -->
<!-- version: 5 -->
# Plan `0.2.9` — moteur Yellowstone gRPC + standard Solana + PublicNode
> **Statut : `0.2.9-pre.001-fix.002` — gate audit/sizing corrigé. `0.2.9` est 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.002` — première matérialisation N1 préparée : dépendances Yellowstone/Tonic minimales, settings runtime bornés, error mapping initial et channel Tonic lazy privé. Les gates Cargo restent à exécuter par l’opérateur avant commit. `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
@@ -298,14 +298,20 @@ https://docs.rs/crate/yellowstone-grpc-proto/latest
KSP suit la **Rust stable courante de l'opérateur** et ne documente pas de numéro Rust upstream comme objectif de projet. Le seul gate utile est opérationnel : les dépendances finalement retenues doivent compiler avec la stable courante utilisée par le workspace.
Éléments build à vérifier en `pre.002` :
Résultat de matérialisation `pre.002` :
```text
proto crate crate publiée/pré-générée ; pas de vendoring de .proto KSP
client KSP autour de Tonic features client/TLS minimales
protoc/build.rs aucun outil système ajouté sauf besoin démontré
yellowstone-grpc-proto ^12.6 workspace dependency, default-features = false, aucune feature KSP activée
tonic ^0.14 workspace dependency, default-features = false ; Transport active seulement `channel`
yellowstone-grpc-client absent
prost/prost-types aucune dépendance KSP directe
tonic-prost aucune dépendance KSP directe à ce stade
proto crate publiée/générée ; aucun .proto copié dans KSP
protoc aucun outil système KSP ajouté ; la crate proto publiée utilise son build vendored
```
Le feature `tonic` optionnel de `yellowstone-grpc-proto` n'est **pas** activé en `pre.002`. KSP n'a besoin à ce stade que des messages Protobuf générés bruts ; le channel physique est construit directement avec Tonic. Cette décision évite de tirer prématurément la surface client/serveur Tonic générée et laisse `pre.003` choisir explicitement les features supplémentaires réellement nécessaires aux unary/TLS/metadata.
Un minimum Rust déclaré par une dépendance n'est enregistré que s'il devient un **blocage réel** lors de la compilation ; il n'est pas suivi comme métrique de release.
## 6. Matrice du service `Geyser` courant
@@ -529,16 +535,19 @@ Avantages :
**Décision : stratégie cible retenue.**
Matérialisation attendue en `pre.002` :
Matérialisation réalisée en `pre.002` :
```text
yellowstone-grpc-proto ^12.6 workspace dependency, features minimales
tonic ^0.14 workspace dependency, features client/TLS minimales
prost/prost-types pas de direct dependency KSP sauf besoin démontré
tokio-stream/futures seulement si nécessaire et sans doublon gratuit
yellowstone-grpc-proto ^12.6 root : default-features = false ; Transport : .workspace = true sans feature
tonic ^0.14 root : default-features = false ; Transport : features = ["channel"]
yellowstone-grpc-client absent
prost/prost-types pas de dépendance KSP directe
tonic-prost pas de dépendance KSP directe en pre.002
tokio-stream pas ajouté
futures-util dépendance existante inchangée
```
L'exacte feature set sera déterminée par compilation et `cargo tree`, pas par anticipation documentaire.
Le choix est volontairement plus étroit que le forecast initial : `pre.002` matérialise les messages wire publiés et le channel HTTP/2 lazy, mais **pas encore le client RPC généré, TLS, metadata ou compression**. Les éventuelles features/dependencies supplémentaires doivent être justifiées par `pre.003` et vérifiées par `cargo tree`; elles ne sont pas activées par anticipation.
### C. proto/génération KSP minimale bornée
@@ -582,11 +591,17 @@ pas de façade provider vide uniquement pour renommer le même protocole
Noms cibles, affinables sans casser le principe :
```text
# N1 — moteur Yellowstone
# N1 — moteur Yellowstone matérialisé en pre.002
YellowstoneGrpcEndpointUrl
YellowstoneGrpcProviderName
YellowstoneGrpcClusterName
YellowstoneGrpcReconnectSettings
YellowstoneGrpcEndpointSettings
YellowstoneGrpcSessionSettings
YellowstoneGrpcTransportSettings
YellowstoneGrpcChannel # channel Tonic lazy privé, sans I/O réseau en pre.002
# N1 — étapes ultérieures
YellowstoneGrpcSession
YellowstoneSubscriptionHandle<T>
@@ -880,8 +895,8 @@ Prévision courante :
pre.001 DONE — audit upstream/service/proto + providers gratuits + licences/deps + architecture + threat model + sizing
budget : 15–20 min nominal ; preuve : plan + matrice + stratégie B + forecast recalibré
pre.002 moteur Yellowstone : proto/dependencies + settings/errors + channel minimal
budget : 15–20 min ; preuve : features minimales + compile/tests + redaction + cargo tree
pre.002 IMPLEMENTED — moteur Yellowstone : proto/dependencies + settings/errors + channel minimal
budget : 15–20 min ; preuve locale : audit statique KSP clean + redaction/API canaries ajoutés ; compile/tests/cargo tree = gate opérateur
pre.003 moteur Yellowstone : TLS/metadata générique + fixture locale + 7 unary RPCs
budget : 15–20 min ; preuve : connect/TLS/timeouts/Status safe + wire unary exact
@@ -936,10 +951,16 @@ et le reste est replanifié explicitement ; aucune capacité n'est abandonnée s
## 18. Fichiers attendus par tranche
Cibles probables, sans imposer artificiellement le découpage source :
Cibles réelles ouvertes par `pre.002`, puis cibles probables suivantes :
```text
# pre.002
crates/ksp-onchain-transport-lib/src/grpc_settings.rs
crates/ksp-onchain-transport-lib/src/grpc_channel.rs
crates/ksp-onchain-transport-lib/unit_tests/grpc_settings.rs
crates/ksp-onchain-transport-lib/unit_tests/grpc_channel.rs
# pre.003+
crates/ksp-onchain-transport-lib/src/grpc_session.rs
crates/ksp-onchain-transport-lib/src/grpc_protocol.rs
crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs

128
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: 4 -->
<!-- version: 5 -->
# Validation `0.2.9` — moteur Yellowstone + standard Solana + PublicNode
> **Statut : matrice ouverte par `0.2.9-pre.001` et corrigée par `pre.001-fix.002`. Le scope distingue moteur Yellowstone, façade Solana standard et première intégration PublicNode. OrbitFlare et Helius sont les seules releases provider suivantes actuellement planifiées ; les autres providers restent en TODO/IDEAS sans numéro réservé.**
> **Statut : matrice ouverte par `0.2.9-pre.001`, corrigée par `pre.001-fix.002` et avancée par `pre.002`. N1 possède désormais une première matérialisation settings/error/channel lazy ; la validation Cargo de cette tranche reste un gate opérateur. Le scope distingue moteur Yellowstone, façade Solana standard et première intégration PublicNode. OrbitFlare et Helius sont les seules releases provider suivantes actuellement planifiées ; les autres providers restent en TODO/IDEAS sans numéro réservé.**
## 1. Autorités du gate
@@ -207,17 +207,21 @@ Preuve cible : fixtures issues du wire Protobuf + cas old/current + malformed/ov
## 8. Dépendances / licence
| Gate | Décision `pre.001` | Preuve suivante |
|-----------------------------|--------------------------------|-------------------------|
| repository default | AGPL-3.0-only | `LICENSING.md` |
| client subtree | Apache-2.0 | `LICENSING.md` |
| proto subtree | Apache-2.0 | `LICENSING.md` |
| strategy A client+proto | rejetée comme default | documenté |
| strategy B proto+Tonic KSP | **retenue** | `pre.002` compile/tree |
| strategy C vendored proto | fallback seulement | aucun vendoring pre.001 |
| system protoc | non attendu avec crate publiée | vérifier build réel |
| raw upstream types public | interdit par défaut | public API canary |
| executable Yellowstone deps | interdit | dependency firewall |
| Gate | Décision / matérialisation `pre.002` | Preuve / état |
|--------------------------------|---------------------------------------------------------------|---------------------------------|
| repository default | AGPL-3.0-only | `LICENSING.md` |
| client subtree | Apache-2.0 | `LICENSING.md` |
| proto subtree | Apache-2.0 | `LICENSING.md` |
| strategy A client+proto | rejetée comme default | documenté |
| strategy B proto+Tonic KSP | **retenue et matérialisée** | source PASS / Cargo pending |
| `yellowstone-grpc-proto` | `^12.6`, `default-features = false`, aucune feature KSP | Cargo tree pending |
| `tonic` | `^0.14`, `default-features = false`, feature `channel` locale | Cargo tree pending |
| `yellowstone-grpc-client` | absent | manifest canary ajouté |
| `prost/prost-types` direct KSP | absent | manifest / Cargo tree pending |
| strategy C vendored proto | fallback seulement | aucun vendoring |
| system protoc | aucun outil système KSP ajouté | proto publié/build vendored |
| raw upstream types public | interdit ; aucun reexport Tonic/Yellowstone | public API canary ajouté |
| executable Yellowstone deps | interdit | dependency firewall à revalider |
Versions observées :
@@ -230,52 +234,53 @@ prost/prost-types 0.14.x (0.14.4 latest observé)
## 9. Architecture / ownership
| Invariant | Preuve cible | État |
|--------------------------------------------------------------------------------|--------------------------------|------|
| backend gRPC distinct HTTP/WS | source/API canary | TODO |
| aucun `WsProtocolKind` gRPC | source scan | TODO |
| Transport owns gRPC | dependency graph | TODO |
| Config -> Transport seulement | ownership test | TODO |
| Transport -X-> Config | ownership test | TODO |
| Transport -X-> std::env KSP_* | ownership test | TODO |
| Logging façade KSP only | logging ownership | TODO |
| no raw Tonic client escape hatch | public API canary | TODO |
| moteur Yellowstone partagé sans duplication provider | source/API canary | TODO |
| façade Solana Yellowstone standard distincte du moteur | public API canary | TODO |
| PublicNode représenté comme provider/capabilities, pas comme nouveau protocole | public API/config canary | TODO |
| provider peut réutiliser, restreindre ou étendre N2 sans dupliquer N1 | capability/completeness review | TODO |
| aucune équivalence provider/standard présumée sans preuve | provider matrix/tests | TODO |
| façade provider spécialisée seulement si delta réel | completeness review | TODO |
| Invariant | Preuve cible | État `pre.002` |
|--------------------------------------------------------------------------------|--------------------------------|---------------------------------|
| backend gRPC distinct HTTP/WS | source/API canary | IMPLEMENTED / Cargo pending |
| aucun `WsProtocolKind` gRPC | source scan | SOURCE PASS |
| Transport owns gRPC | dependency graph | IMPLEMENTED / tree pending |
| Config -> Transport seulement | ownership test | hérité / final TODO |
| Transport -X-> Config | ownership test | SOURCE PASS / Cargo pending |
| Transport -X-> std::env KSP_* | ownership test | SOURCE PASS |
| Logging façade KSP only | logging ownership | SOURCE PASS |
| no raw Tonic client escape hatch | public API canary | IMPLEMENTED / Cargo pending |
| moteur Yellowstone partagé sans duplication provider | source/API canary | N1 FOUNDATION IMPLEMENTED |
| façade Solana Yellowstone standard distincte du moteur | public API canary | TODO `pre.003+` |
| PublicNode représenté comme provider/capabilities, pas comme nouveau protocole | public API/config canary | TODO `pre.010/011` |
| provider peut réutiliser, restreindre ou étendre N2 sans dupliquer N1 | capability/completeness review | architecture conservée |
| aucune équivalence provider/standard présumée sans preuve | provider matrix/tests | architecture conservée |
| façade provider spécialisée seulement si delta réel | completeness review | TODO provider integration |
## 10. Settings, bounds et redaction
À fermer par tests :
État après `pre.002` :
```text
endpoint schemes TLS/non-TLS explicitement validés
connect timeout > 0
unary timeout > 0
close timeout > 0
max inbound/outbound > 0 et plafonnés
request/update queue capacities > 0 et plafonnées
reconnect attempt/backoff bornés
filter-group count
filter-name length/uniqueness
metadata key/value count/size
account/owner/include/exclude/required counts
memcmp/data slice bounds
Cuckoo dimensions/data bounds
DONE/source+tests ajoutés endpoint schemes http/https validés ; TLS réel reporté pre.003
DONE/source+tests ajoutés endpoint URL, descripteurs et nombre d’endpoints plafonnés
DONE/source+tests ajoutés connect timeout > 0 et plafonné
DONE/source+tests ajoutés unary timeout > 0 et plafonné
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
TODO pre.003 metadata key/value count/size
TODO pre.005+ account/owner/include/exclude/required counts
TODO pre.004+ memcmp/data slice bounds
TODO pre.005+ Cuckoo dimensions/data bounds
```
Security canaries :
```text
endpoint URL Debug redacted
secret metadata Debug/Display absent
Status message/details distants non recopiés aveuglément en context
TLS/connect error sans credential/URI sensible
request/update Debug sans payload arbitraire sensible
snapshot sans endpoint secret ni remote internals inutiles
DONE/source+tests ajoutés endpoint URL Debug redacted
TODO pre.003 secret metadata Debug/Display absent
TODO pre.003 Status message/details distants non recopiés aveuglément en context
PARTIAL pre.002 URI Tonic invalide mappée sans recopier l'erreur ; TLS/connect réel pre.003
TODO pre.004+ request/update Debug sans payload arbitraire sensible
PARTIAL pre.002 channel Debug ne contient ni URL ni raw Tonic ; snapshot lifecycle ultérieur
```
## 11. Lifecycle / backpressure / replay
@@ -397,7 +402,7 @@ 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 TODO moteur: deps/settings/errors/channel 15–20 min
pre.002 IMPLEMENTED / CARGO GATE moteur: deps/settings/errors/channel 15–20 min
pre.003 TODO moteur: TLS/metadata + fixture + 7 unary 15–20 min
pre.004 TODO standard: Subscribe common/from_slot/bounds 15–20 min
pre.005 TODO standard: accounts + slots 15–20 min
@@ -440,3 +445,26 @@ Gate de sizing : une prerelease estimée à plus de 20 minutes est scindée ; si
| aucune implémentation lourde prématurée | PASS |
**Verdict `pre.001` : gate positif ; `pre.002` peut matérialiser la stratégie B sous validation Cargo.**
## 17. Gate `pre.002`
| Critère de tranche | Verdict local |
|---------------------------------------------------------|------------------------------------------------|
| workspace version `0.2.9-pre.2` | PASS source |
| stratégie B matérialisée sans `yellowstone-grpc-client` | PASS source |
| proto `12.6` sans default/features KSP | PASS manifest |
| Tonic `0.14` limité à `channel` | PASS manifest |
| aucun Config/env dans Transport gRPC | PASS source/audit |
| aucun couplage WebSocket | PASS source |
| settings runtime bornés | PASS source/tests ajoutés |
| URL/channel diagnostics redacted | PASS source/tests ajoutés |
| channel Tonic lazy privé | PASS source/API canary ajouté |
| raw Tonic/Yellowstone absent de l'API publique | PASS source/API canary ajouté |
| audit `scripts/audit_rust_workspace_rules.py` | PASS / clean |
| `cargo fmt --all` | PENDING opérateur |
| `cargo check --workspace` | PENDING opérateur |
| `cargo clippy --workspace --all-targets` | PENDING opérateur |
| tests Transport/Core/workspace | PENDING opérateur |
| `cargo tree` direct/duplicates | PENDING opérateur |
**Verdict `pre.002` local : implémentation candidate prête pour validation opérateur. La tranche n'est déclarée fermée qu'après les gates Cargo réels.**