khadhroony-solana-project/deltas/0.2.9/pre.001.md

<!-- file: deltas/0.2.9/pre.001.md -->
<!-- version: 1 -->

# Delta `0.2.9-pre.001` — audit/sizing Yellowstone gRPC standard

## 1. Base requise et vérifiée

Archive autoritaire fournie :

```text
khadhroony-solana-project-v0.2.8-full-from-gitea.zip
```

État vérifié :

```text
workspace.package.version = 0.2.8
deltas/0.2.8/rel.001.md présent
prompts/014-V0_2_9_START_PROMPT.md présent
prompt fourni = byte-identique au prompt embarqué
metadata .git absente de l'archive
```

Cette livraison ouvre :

```text
workspace.package.version = 0.2.9-pre.1
commit attendu            = v0.2.9-pre.001
aucun tag prerelease
```

## 2. Objet

`pre.001` exécute le gate obligatoire :

```text
lecture base/règles/architecture
baseline stable
réaudit Yellowstone actuel
matrice service/proto
licences/dependencies/MSRV
architecture provider-neutral
threat model/resources/backpressure/replay
sizing et forecast
récensement des providers gRPC gratuits durables
```

Aucune implémentation gRPC lourde n'est ajoutée.

## 3. Baseline opérateur acquise

Preuve fournie sur `v0.2.8` :

```text
cargo fmt --all                               OK
python3 scripts/audit_rust_workspace_rules.py OK / clean
cargo check --workspace                       OK
cargo clippy --workspace --all-targets        OK
cargo test --workspace                        OK
cargo tree -p ksp-onchain-transport-lib        fourni
cargo tree --duplicates                        fourni
```

Transport pendant le workspace test :

```text
335 unit
41 public_api
34 release_completeness
4 doctests
```

Les live smokes restent opt-in/ignored par défaut.

## 4. Réaudit Yellowstone du 2026-08-23

Divergence importante par rapport au snapshot du start prompt :

```text
prompt snapshot release = v14.2.2+solana.4.1.0
release GitHub courante = v15.1.2+solana.4.2.0, publiée 2026-08-18, Rust 1.96.1
client crate courant     = yellowstone-grpc-client 13.3.0
proto crate courant      = yellowstone-grpc-proto 12.6.0
```

Service Geyser courant inventorié :

```text
Subscribe                 IN
SubscribeDeshred          OUT — Triton extension / pre-execution
SubscribeReplayInfo       IN
Ping                      IN
GetLatestBlockhash        IN
GetBlockHeight            IN
GetSlot                   IN
IsBlockhashValid          IN
GetVersion                IN
```

`SubscribeRequest` standard retenu :

```text
accounts
slots
transactions
transactions_status
blocks
blocks_meta
entry
commitment
accounts_data_slice
ping
from_slot
```

Capacités nouvelles/actuelles retenues car présentes dans le proto publié standard :

```text
CuckooFilter account/block/transaction include
TokenAccountExpansionControlFlag ALL/BALANCE_CHANGED
lamports eq/ne/lt/gt
slot interslot updates
```

`SubscribeUpdate` :

```text
account
slot
transaction
transaction_status
block
ping
pong
block_meta
entry
```

## 5. Licence et dépendances

Upstream :

```text
repository default = AGPL-3.0-only
client subtree      = Apache-2.0
proto subtree       = Apache-2.0
```

Stratégies comparées :

```text
A client upstream + proto  -> rejetée comme default
B proto publié + client KSP autour de Tonic -> RETENUE
C proto vendored KSP       -> fallback seulement
```

Raisons de B :

```text
pas de copie proto
wire officiel disponible
licence Apache compatible MIT
reconnect/backpressure/redaction KSP-owned
upstream raw types cachés
stack tonic 0.14 cohérente avec HTTP/2 moderne existant
```

Aucune dependency n'est ajoutée dans `pre.001`. `pre.002` doit matérialiser les features minimales et produire les graphes Cargo.

## 6. Replay/continuity

L'upstream a corrigé en juillet 2026 un cas où `from_slot` pour blocks pouvait être accepté puis reprendre live avec un **state gap** ; l'autoreconnect upstream a aussi été renforcé pour traiter l'equivocation entre nodes.

KSP ferme donc :

```text
reconnect/resubscribe = oui, borné et KSP-owned
from_slot             = oui
ReplayInfo            = oui
exactly-once          = non garanti
lossless              = non garanti
gaps/duplicates       = observables
node divergence       = couverture explicite seulement si prouvée
```

## 7. Config / architecture

Décisions :

```text
backend gRPC distinct de HTTP/WS
pas de WsProtocolKind gRPC
pas de raw Tonic client public
Transport owns Yellowstone
Config -> Transport seulement
metadata publique et metadata sensible séparées
Transport ne lit aucun env
```

Le schéma V2 actuel étant fermé, l'ajout gRPC cible :

```text
format_version = 3
globals.grpc_defaults
profiles[].grpc_endpoints[]
metadata[]
secret_metadata[]
```

V1 et V2 restent backward-readable.

## 8. Providers gRPC gratuits durables

### PublicNode / Allnodes-backed — priorité 1

Confirmé officiellement :

```text
Solana Mainnet Yellowstone GRPC
Solana Testnet GRPC
Mainnet endpoint = solana-yellowstone-grpc.publicnode.com:443
service annoncé free/public
```

Décision : **dans `0.2.9`**, mais pas sous forme d'adapter public spécifique. PublicNode sert de premier smoke live standard provider-neutral.

Le hostname Testnet exact n'est pas figé avant vérification officielle/live.

### OrbitFlare — priorité 2

Plan Free officiel :

```text
$0/mo
10 RPS
1 TPS
gRPC Devnet only
Unlimited credit limits
```

Décision : **dans `0.2.9` comme second smoke live**, via generic secret metadata Config -> Transport. Aucun type `OrbitFlareGrpc*` public.

### Tatum — tertiaire

```text
Mainnet Yellowstone gRPC
Free plan durable
3 RPS
100K lifetime credits
5 subscriptions
```

Décision : opérateur optionnel, pas gate durable principal à cause du quota lifetime.

### Vérifiés non gratuits / non applicables

```text
Helius      Free sans gRPC
Shyft       Free = No gRPC Access
Alchemy     PAYG/Enterprise requis
QuickNode   Scale/Business ou add-on payant
Chainstack  add-on Yellowstone payant, Growth+
ERPC        Geyser payant ; trial seulement 1 jour
NodeFlare   plan Yellowstone mensuel payant
Bitquery    CoreCast custom, pas Yellowstone standard ; stream free non garanti
```

Candidat à revalider :

```text
Solinfra = free tier + Yellowstone annoncés publiquement, mais accès gRPC inclus dans Free non confirmé
```

## 9. Threat model

Le plan ferme explicitement :

```text
metadata/URI credential leak
Tonic Status arbitraire
oversized messages
stream flood/backpressure
filter explosion / collisions de noms
unknown enum/oneof
server/client half-close
reconnect loop
node divergence
late updates après mutation
from_slot gaps/duplicates
TLS failures
unary timeout
```

## 10. Forecast recalibré

```text
pre.001 DONE audit/sizing/provider/deps/license
pre.002 deps + settings/errors/facade + cargo tree
pre.003 TLS/metadata + local fixture + 7 unary
pre.004 Subscribe common + Cuckoo/token/from_slot/bounds
pre.005 Accounts + Slots
pre.006 Transactions + transaction_status
pre.007 Blocks + block_meta + entry
pre.008 bidi lifecycle/backpressure/half-close/shutdown
pre.009 reconnect/replay/gaps/duplicates/equivocation
pre.010 Config V3
pre.011 PublicNode/OrbitFlare live + compliance + final cargo graphs
pre.012 docs/workspace final + prompt 0.2.10
rel.001 stable
```

Chaque tranche vise ~15–20 minutes ; `pre.012` n'est pas une deadline.

Critères de split : conflit MSRV/stack réseau, explosion DTO transaction/block, nouvelle évolution proto matérielle, replay trop large, ou comportement provider-specific contaminant le contrat standard.

## 11. Fichiers ajoutés

```text
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
deltas/0.2.9/pre.001.md
```

## 12. Fichiers modifiés

```text
Cargo.toml
docs/000-README.md
docs/plans/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/validation/000-README.md
```

## 13. Fichiers volontairement inchangés

```text
ROADMAP.md
CHANGELOG.md
.env.example
config/**
crates/**
docs/architecture/**
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
```

Aucun gRPC runtime/config/dependency n'est introduit avant le gate positif de cette tranche.

## 14. Validations du sandbox de préparation

Le sandbox a pu exécuter :

```text
inspection archive/version/rel/prompt                   OK
comparaison prompt fourni / prompt archive              OK
lecture règles/architecture/plans/code/config           OK
réaudit upstream Yellowstone/provider/dependencies      OK
python3 scripts/audit_rust_workspace_rules.py           OK / clean après overlay
```

Le sandbox ne dispose pas de Cargo ; aucun nouveau `cargo check/clippy/test/tree` n'est déclaré réussi localement après le changement de version/documentation.

## 15. Validation opérateur attendue avant commit

Comme `pre.001` ne modifie aucun Rust/dependency/config runtime, exécuter au minimum :

```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
```

Attendu : aucune nouvelle dependency gRPC avant `pre.002`.