khadhroony-solana-project/docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md

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 :

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

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

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

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

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 :

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 :

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 :

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é :

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.

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 :

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

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é :

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

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 :

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é.