441 lines
21 KiB
Markdown
441 lines
21 KiB
Markdown
<!-- file: docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md -->
|
|
<!-- version: 25 -->
|
|
|
|
# Validation `0.2.9` — Yellowstone gRPC standard + PublicNode
|
|
|
|
**Statut courant : `pre.011` est fermée par gate opérateur complet sans warning. `pre.012` est la candidate de fermeture technique : réaudit upstream, smoke PublicNode Mainnet opt-in, graphes Cargo finaux, documentation, audit des tableaux Markdown et prompt `0.2.10 — OrbitFlare Yellowstone gRPC`. Les logs historiques détaillés restent dans `deltas/0.2.9/`.**
|
|
|
|
## 1. Autorités et baseline courante
|
|
|
|
Autorités :
|
|
|
|
```text
|
|
RULES.md + docs/rules/*
|
|
plan 016 courant
|
|
code réel Transport/Config
|
|
prompts/014-V0_2_9_START_PROMPT.md pour les contraintes non supersédées
|
|
deltas/0.2.9/* pour l'historique immuable et les décisions postérieures au prompt
|
|
upstream Yellowstone primaire
|
|
```
|
|
|
|
Baseline opérateur immédiatement avant `pre.012` (`0.2.9-pre.011`) :
|
|
|
|
| Gate | Résultat |
|
|
|------------------------------------------|--------------------------|
|
|
| `cargo fmt --all` | PASS |
|
|
| audit Rust workspace | PASS, 0 candidate export |
|
|
| `cargo check --workspace` | PASS |
|
|
| `cargo clippy --workspace --all-targets` | PASS sans warning |
|
|
| Config unit | 113/113 PASS |
|
|
| Config public API | 15/15 PASS |
|
|
| Config ownership | 5/5 PASS |
|
|
| Transport unit | 383/383 PASS |
|
|
| Transport public API | 49/49 PASS |
|
|
| Transport release completeness | 43/43 PASS |
|
|
| Transport doctests | 4/4 PASS |
|
|
| workspace dependency canary | 3/3 PASS |
|
|
| `cargo test --workspace` | PASS |
|
|
|
|
Cette baseline est le seuil de non-régression de `pre.012`.
|
|
|
|
## 2. Gate dépendances et licence
|
|
|
|
| Exigence | Décision / preuve | État |
|
|
|--------------------------------|------------------------------------------|-------------------|
|
|
| proto officiel sans vendoring | `yellowstone-grpc-proto ^12.6` | **PASS** |
|
|
| pas de client upstream runtime | `yellowstone-grpc-client` absent | **PASS** |
|
|
| runtime Tonic KSP-owned | `tonic ^0.14` + `tonic-prost ^0.14` | **PASS** |
|
|
| proto subtree compatible | Apache-2.0 selon `LICENSING.md` upstream | **PASS** |
|
|
| source AGPL copiée | aucune | **PASS** |
|
|
| raw client Tonic public | aucun | **PASS** |
|
|
| graph final | réinspection `pre.012` | **PENDING FINAL** |
|
|
|
|
Le graphe de dépendances n'est pas modifié par `pre.012`; aucune nouvelle dépendance Cargo n'est introduite dans cette tranche.
|
|
|
|
## 3. Matrice service `Geyser`
|
|
|
|
| RPC | Classification | Cible | Preuve | Verdict |
|
|
|-----------------------|--------------------------------|-------|---------------------------------|----------|
|
|
| `Subscribe` | standard | oui | stream bidi local + lifecycle | **PASS** |
|
|
| `SubscribeDeshred` | extension/pré-exécution Triton | non | exclusion documentée | **OUT** |
|
|
| `SubscribeReplayInfo` | standard unary | oui | fixture unary + reconnect tests | **PASS** |
|
|
| `Ping` | standard unary | oui | fixture exact echo | **PASS** |
|
|
| `GetLatestBlockhash` | standard unary | oui | fixture typed | **PASS** |
|
|
| `GetBlockHeight` | standard unary | oui | fixture typed | **PASS** |
|
|
| `GetSlot` | standard unary | oui | fixture typed | **PASS** |
|
|
| `IsBlockhashValid` | standard unary | oui | fixture typed + invalid input | **PASS** |
|
|
| `GetVersion` | standard unary | oui | fixture typed | **PASS** |
|
|
|
|
## 4. `SubscribeRequest` — coverage normative
|
|
|
|
### 4.1 Top-level
|
|
|
|
| Champ | Verdict | Preuve minimale |
|
|
|-----------------------|----------|----------------------------------|
|
|
| `accounts` | **PASS** | maps typed + wire exact |
|
|
| `slots` | **PASS** | maps typed + wire exact |
|
|
| `transactions` | **PASS** | maps typed + wire exact |
|
|
| `transactions_status` | **PASS** | same filter family, separate map |
|
|
| `blocks` | **PASS** | maps typed + wire exact |
|
|
| `blocks_meta` | **PASS** | named empty marker preserved |
|
|
| `entry` | **PASS** | named empty marker preserved |
|
|
| `commitment` | **PASS** | optional wire semantics |
|
|
| `accounts_data_slice` | **PASS** | order + bounds |
|
|
| `ping` | **PASS** | optional id |
|
|
| `from_slot` | **PASS** | optional + replay mutation |
|
|
|
|
### 4.2 Accounts
|
|
|
|
```text
|
|
account[]
|
|
owner[]
|
|
filters[]
|
|
nonempty_txn_signature?
|
|
cuckoo_accounts_filter?
|
|
memcmp bytes/base58/base64
|
|
datasize
|
|
token_account_state
|
|
lamports eq/ne/lt/gt
|
|
```
|
|
|
|
Verdict : **PASS** — wire complet retenu, bounds déterministes, payload Debug redacted, malformed fixed-width rejeté.
|
|
|
|
### 4.3 Slots
|
|
|
|
```text
|
|
filter_by_commitment?
|
|
interslot_updates?
|
|
processed
|
|
confirmed
|
|
finalized
|
|
first_shred_received
|
|
completed
|
|
created_bank
|
|
dead + dead_error?
|
|
```
|
|
|
|
Verdict : **PASS**.
|
|
|
|
### 4.4 Transactions et transaction_status
|
|
|
|
```text
|
|
vote?
|
|
failed?
|
|
signature?
|
|
account_include[]
|
|
account_exclude[]
|
|
account_required[]
|
|
cuckoo_account_include?
|
|
token_accounts? = ALL | BALANCE_CHANGED
|
|
```
|
|
|
|
Verdict : **PASS** — request wire, transaction storage/meta, status error et malformed signature couverts.
|
|
|
|
### 4.5 Blocks, block_meta, entry
|
|
|
|
```text
|
|
account_include[]
|
|
include_transactions?
|
|
include_accounts?
|
|
include_entries?
|
|
cuckoo_account_include?
|
|
blocks_meta marker
|
|
entry marker
|
|
```
|
|
|
|
Verdict : **PASS** — block complet, metadata, entries et champs optional/legacy couverts.
|
|
|
|
## 5. `SubscribeUpdate` — coverage normative
|
|
|
|
| Variante | Verdict |
|
|
|--------------------------------------|----------|
|
|
| account | **PASS** |
|
|
| slot | **PASS** |
|
|
| transaction | **PASS** |
|
|
| transaction_status | **PASS** |
|
|
| block | **PASS** |
|
|
| ping | **PASS** |
|
|
| pong | **PASS** |
|
|
| block_meta | **PASS** |
|
|
| entry | **PASS** |
|
|
| top-level `filters[]` / `created_at` | **PASS** |
|
|
|
|
Les raw protobufs ne sortent pas de la façade publique. Les décodeurs rejettent les formes structurellement invalides sans copier des payloads arbitraires dans les erreurs.
|
|
|
|
## 6. Settings, bounds et redaction
|
|
|
|
| Contrôle | État |
|
|
|-----------------------------------------------|--------------------|
|
|
| URL `http/https` seulement et longueur bornée | **PASS** |
|
|
| URL Debug redacted | **PASS** |
|
|
| metadata key/value/count bornés | **PASS** |
|
|
| metadata secret/public distincte | **PASS** Transport |
|
|
| timeouts non nuls et bornés | **PASS** |
|
|
| reconnect bounds cohérents | **PASS** |
|
|
| inbound/outbound message sizes | **PASS** |
|
|
| request/update queue capacities | **PASS** |
|
|
| filter group/name bounds | **PASS** |
|
|
| account/owner/memcmp/data slice bounds | **PASS** |
|
|
| transaction/block selectors bounds | **PASS** |
|
|
| remote `Status` message/details non recopiés | **PASS** |
|
|
| Transport -> env/config | absent ou **PASS** |
|
|
|
|
## 7. Lifecycle, backpressure et replay
|
|
|
|
| Exigence | Verdict | Preuve |
|
|
|------------------------------|-----------------|------------------------------------------------|
|
|
| stream bidi unique | **PASS** | round-trip fixture |
|
|
| mutation request | **PASS** | same request channel |
|
|
| server Ping / client reply | **PASS** | actor test |
|
|
| Pong decode | **PASS** | update decode |
|
|
| server half-close | **PASS** | state terminal observable |
|
|
| explicit client close | **PASS** | half-close avant deadline |
|
|
| hostile server shutdown | **PASS** | close timeout borné |
|
|
| slow receiver | **PASS** | overflow terminal observable |
|
|
| oversized inbound | **PASS** | Tonic decoder bound |
|
|
| oversized outbound | **PASS** | reject avant queue dispatch |
|
|
| reconnect backoff | **PASS** | budget borné |
|
|
| shutdown pendant backoff | **PASS** | interruption sans nouvelle connexion |
|
|
| resubscribe déterministe | **PASS** | last accepted full request |
|
|
| reprise `from_slot` | **PASS** | dernier slot observé + demande explicite |
|
|
| ReplayInfo `first_available` | **PASS** | clamp/gap seulement si prouvé |
|
|
| duplicate observability | **PASS** | compteur borné, pas de suppression silencieuse |
|
|
| exactly-once/lossless | **NON GARANTI** | contrat explicite |
|
|
|
|
Snapshot public requis et présent :
|
|
|
|
```text
|
|
reconnect_count
|
|
replay_attempt_count
|
|
continuity_gap_count
|
|
duplicate_update_count
|
|
last_requested_from_slot
|
|
last_observed_slot
|
|
state/error code safe
|
|
```
|
|
|
|
## 8. Gate Config V3 — `pre.011`
|
|
|
|
### 8.1 Schema et backward compatibility
|
|
|
|
Le gate opérateur `pre.011` ferme les exigences suivantes :
|
|
|
|
| Exigence | Preuve | Verdict |
|
|
|------------------------------------------|-----------------------------------------|----------|
|
|
| schema `$id` V3 | `urn:ksp:schema:std.transport:v3` | **PASS** |
|
|
| branches V1/V2 conservées | fixtures V1, V2 et document committé | **PASS** |
|
|
| V1 HTTP-only | `v1_transport_fixture...` | **PASS** |
|
|
| V2 HTTP+WS | fixture V2 + compatibilité constructeur | **PASS** |
|
|
| V3 HTTP+WS+gRPC | 113 tests Config | **PASS** |
|
|
| `grpc_endpoints` optionnel par profil V3 | profil `devnet_public` sans gRPC | **PASS** |
|
|
| propriétés inconnues refusées | branches schema strictes | **PASS** |
|
|
|
|
### 8.2 Mapping runtime
|
|
|
|
V3 doit mapper :
|
|
|
|
```text
|
|
grpc_defaults -> YellowstoneGrpcSessionSettings
|
|
grpc_endpoints[].url -> YellowstoneGrpcEndpointUrl
|
|
provider -> YellowstoneGrpcProviderName
|
|
cluster -> YellowstoneGrpcClusterName
|
|
protocol = solana_yellowstone -> gate Config explicite
|
|
metadata -> YellowstoneGrpcMetadataEntry::public
|
|
secret_metadata -> YellowstoneGrpcMetadataEntry::secret
|
|
session overrides -> merge avec grpc_defaults
|
|
```
|
|
|
|
API :
|
|
|
|
| Surface | Exigence | Statut source |
|
|
|---------------------------------|-------------------------------------|---------------|
|
|
| `http_settings()` | inchangée | **OK** |
|
|
| `ws_settings()` | V1 None, V2/V3 selon profil | **OK** |
|
|
| `grpc_settings()` | V1/V2 None, V3 optionnel | **PASS** |
|
|
| `into_transport_settings()` | tuple historique HTTP + WS inchangé | **PASS** |
|
|
| `into_all_transport_settings()` | nouveau tuple HTTP + WS + gRPC | **PASS** |
|
|
|
|
### 8.3 Provenance et secrets
|
|
|
|
Règles validées :
|
|
|
|
```text
|
|
metadata publique + provenance KSP_SECRET_* -> reject
|
|
secret_metadata sans provenance secret -> reject
|
|
secret_metadata + variable KSP_PUBLIC_/KSP_* -> reject
|
|
secret_metadata + KSP_SECRET_/KSPB_SECRET_ -> accept
|
|
segments littéraux autour du secret -> accept
|
|
safe_value -> secret segment ********
|
|
Transport Debug -> URL/metadata secret absents
|
|
```
|
|
|
|
Les tests V3 démontrent le cas valide et les deux croisements invalides sans exposer les canaris.
|
|
|
|
### 8.4 PublicNode Mainnet
|
|
|
|
Profil committé et validé :
|
|
|
|
```text
|
|
profile_id = publicnode_mainnet
|
|
provider = publicnode
|
|
cluster = mainnet-beta
|
|
protocol = solana_yellowstone
|
|
url = https://solana-yellowstone-grpc.publicnode.com:443 # provider affiche host:port ; KSP ajoute le scheme TLS requis
|
|
metadata = aucune
|
|
```
|
|
|
|
Le mapping produit un endpoint TLS Yellowstone standard ; le test `committed_v3_publicnode_mainnet_maps_provider_neutral_yellowstone_grpc` passe et `Debug` ne doit pas exposer l'URL.
|
|
|
|
### 8.5 PublicNode Testnet
|
|
|
|
Verdict final documentaire : **EXTERNAL BLOCK, NOT GUESSED**.
|
|
|
|
Le réaudit officiel du 2026-08-24 confirme une capacité Solana Testnet gRPC chez PublicNode, mais l'hostname exact n'a pas été obtenu depuis une source PublicNode suffisamment autoritative. Aucun profil, aucun hostname déduit et aucun smoke Testnet ne sont versionnés.
|
|
|
|
```text
|
|
capacité Testnet gRPC confirmée
|
|
hostname exact non confirmé
|
|
profil KSP absent
|
|
smoke KSP absent
|
|
raison interdiction d'inventer un endpoint provider
|
|
```
|
|
|
|
## 9. Provider-neutrality
|
|
|
|
| Point | Verdict |
|
|
|-----------------------------------------------|------------------|
|
|
| type public `PublicNodeGrpc*` sans divergence | absent, **PASS** |
|
|
| protocol standard encodé comme provider | non, **PASS** |
|
|
| provider descriptif séparé | oui, **PASS** |
|
|
| auth PublicNode hardcodée dans Transport | non, **PASS** |
|
|
| Helius/OrbitFlare runtime gRPC dans `0.2.9` | non, **PASS** |
|
|
| provider extensions dans N2 | aucune, **PASS** |
|
|
|
|
## 10. Non-régressions obligatoires
|
|
|
|
Le gate final doit préserver :
|
|
|
|
```text
|
|
HTTP current typed 52/52
|
|
HTTP historical 14/14 Deprecated/Removed
|
|
KSP-TRANSPORT-007 vert
|
|
Standard WebSocket 9 familles / 18 opérations
|
|
Helius LaserStream WebSocket 7 familles standard + transaction + slotsUpdates, heartbeat provider-owned
|
|
Transport -> Config interdit
|
|
Transport -> std::env KSP_* interdit
|
|
tracing direct Transport interdit
|
|
```
|
|
|
|
`pre.012` ne modifie pas le runtime Transport ; elle ajoute uniquement un smoke live ignoré par défaut et de la documentation/audit. Son seuil de non-régression est la baseline `pre.011`.
|
|
|
|
## 11. Historique des gates fermé
|
|
|
|
Les détails de commandes, warnings corrigés et fichiers exacts restent dans leurs deltas immuables.
|
|
|
|
| Tranche | Gate consolidé |
|
|
|-----------------------------------|--------------------------------------|
|
|
| `pre.001` + `fix.001` + `fix.002` | audit/sizing/providers/licence fermé |
|
|
| `pre.002` + `fix.001` + `fix.002` | moteur/settings/channel fermé |
|
|
| `pre.003` + `fix.001` | TLS/metadata/unary fermé |
|
|
| `pre.004` + `fix.001` | Subscribe common fermé |
|
|
| `pre.005` + `fix.001` | Accounts/Slots fermé |
|
|
| `pre.006` | namespace HTTP fermé |
|
|
| `pre.007` | Transactions fermé |
|
|
| `pre.008` + `fix.001` | Blocks fermé |
|
|
| `pre.009` + `fix.001` | bidi/backpressure fermé |
|
|
| `pre.010` + `fix.001` | reconnect/replay fermé sans warning |
|
|
| `pre.011` | Config V3/PublicNode mapping fermé |
|
|
|
|
Cette table remplace les anciens appendices numérotés successivement `19.x`, `20`, `21`, etc. qui rendaient le document ambigu.
|
|
|
|
## 12. Gate opérateur `pre.012`
|
|
|
|
### 12.1 Preuves source déjà matérialisées
|
|
|
|
| Exigence | État candidate |
|
|
|----------------------------------------------|----------------------|
|
|
| réaudit `master` Yellowstone | **PASS SOURCE** |
|
|
| service `Geyser` et wire N2 inchangés | **PASS SOURCE** |
|
|
| licence proto Apache-2.0 toujours déclarée | **PASS SOURCE** |
|
|
| PublicNode Mainnet endpoint officiel | **PASS SOURCE** |
|
|
| PublicNode Testnet hostname exact | **EXTERNAL BLOCK** |
|
|
| smoke Mainnet programmatique sans credential | **ADDED, NOT RUN** |
|
|
| README/USAGE Yellowstone + Config V3 | **SOURCE OK** |
|
|
| règles tableaux Markdown | **ADDED** |
|
|
| audit mécanique tableaux | **ADDED** |
|
|
| prompt `0.2.10` OrbitFlare | **ADDED** |
|
|
| graphes Cargo finaux | **PENDING OPERATOR** |
|
|
| workspace final | **PENDING OPERATOR** |
|
|
|
|
Le réaudit `master` distingue explicitement le plugin courant du dernier tag GitHub indexé : `master` déclare `yellowstone-grpc-geyser 15.1.2`, `yellowstone-grpc-client 13.3.0`, `yellowstone-grpc-proto 12.6.0` et Agave `4.2.0`, alors que la page des releases indexée expose encore `v14.2.2+solana.4.1.0` comme dernière release publiée. Aucun numéro n'est fusionné artificiellement.
|
|
|
|
### 12.2 Commandes requises
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.9
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-config-lib
|
|
cargo test -p ksp-onchain-transport-lib
|
|
cargo test -p ksp-core-lib --test workspace_dependencies
|
|
cargo test --workspace
|
|
cargo tree -p ksp-onchain-transport-lib
|
|
cargo tree -p ksp-onchain-transport-lib --duplicates
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
Smoke live séparé :
|
|
|
|
```bash
|
|
cargo test -p ksp-onchain-transport-lib --test yellowstone_publicnode_smoke -- --ignored --nocapture
|
|
```
|
|
|
|
Une commande non exécutée n'est jamais déclarée réussie. Le smoke peut révéler un incident externe ; ce résultat doit être consigné sans transformer un échec réseau/provider en défaut local fictif.
|
|
|
|
## 13. Compliance finale et verdict stable
|
|
|
|
### 13.1 Inventaires à préserver
|
|
|
|
```text
|
|
HTTP current typed 52/52
|
|
HTTP historical 14/14 Deprecated/Removed
|
|
Standard WebSocket 9 familles / 18 opérations
|
|
Helius LaserStream WebSocket 7 familles standard + transaction + slotsUpdates
|
|
Yellowstone unary 7/7
|
|
Yellowstone Subscribe standard N2 + 9 updates
|
|
Config Transport V1/V2/V3 backward-readable
|
|
```
|
|
|
|
### 13.2 Documentation et règles
|
|
|
|
Le format des tableaux Markdown devient normatif dans `RULES_DOCUMENTATION.md` : aucun pipe littéral ou échappé dans une cellule, colonnes alignées sur le contenu le plus large, une seule marge d'espace autour du contenu maximal, et séparateurs dimensionnés exactement. Le canari `scripts/audit_markdown_tables.py` vérifie mécaniquement les fichiers Markdown modifiés hors blocs de code.
|
|
|
|
Le nettoyage `pre.012` a également normalisé les neuf documents modifiables qui présentaient encore des écarts connus. Le scan de préparation sur les documents KSP, crates et deltas `0.2.9` est vert sur 87 tableaux dans 116 fichiers. Les seuls écarts trouvés par un scan de tout le repository appartiennent à d'anciens deltas `0.1.4` immuables ; ils ne sont pas réécrits uniquement pour du formatage.
|
|
|
|
### 13.3 Verdict stable
|
|
|
|
`0.2.9` peut devenir stable lorsque le gate opérateur `pre.012` confirme tous les points locaux suivants :
|
|
|
|
```text
|
|
standard vs extension explicitement classifié
|
|
SubscribeDeshred OUT documenté
|
|
7 unary verts
|
|
Subscribe + 9 updates verts
|
|
resource/backpressure/lifecycle verts
|
|
reconnect/replay sans promesse lossless
|
|
Config V3 backward V1/V2
|
|
provider/protocol distincts
|
|
PublicNode Mainnet smoke exécuté avec résultat consigné
|
|
Testnet jamais inventé
|
|
HTTP/WS/Helius non régressés
|
|
dependency firewall vert
|
|
cargo graphs inspectés
|
|
README/USAGE finaux
|
|
prompt 0.2.10 prêt
|
|
workspace final vert
|
|
```
|
|
|
|
Le bloc Testnet n'est pas un faux FAIL local : l'existence du service est confirmée, mais l'endpoint exact reste indisponible dans la source officielle consultée. Il est donc fermé comme limite externe documentée, sans profil ni smoke inventé.
|