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

v0.2.9-pre.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-24 08:37:36 +02:00
parent d70c3a1672
commit bdcab1e1a7
8 changed files with 1849 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Cargo.toml
View File

@@ -1,12 +1,12 @@
# file: Cargo.toml
# version: 236
# version: 237
[workspace]
resolver = "3"
members = ["crates/ksp-app-config-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"]
[workspace.package]
version = "0.2.8"
version = "0.2.9-pre.1"
edition = "2024"
license = "MIT"
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

377
deltas/0.2.9/pre.001.md Normal file
View File

@@ -0,0 +1,377 @@
<!-- 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`.

10
docs/000-README.md
View File

File diff suppressed because one or more lines are too long

3
docs/plans/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/000-README.md -->
<!-- version: 59 -->
<!-- version: 60 -->
# Plans KSP
@@ -24,6 +24,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
- [`013-V0_2_6_WALLET_DESK_PLAN.md`](013-V0_2_6_WALLET_DESK_PLAN.md) — plan historique clôturé de la release stable `0.2.6 — Wallet Desk`, ouvert par `pre.001`, étendu en `pre.015`–`pre.017` au wire binaire `.kspwallet` V2, aux APIs multi-version et à la migration V1 -> V2, puis fermé par `pre.018`/`fix.001` avec le runtime Tauri packagé et le build final vert avant publication `rel.001`.
- [`014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md`](014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md) — plan historique clôturé de la release stable `0.2.7 — WebSocket Solana standard`, ouvert par `pre.001`, exécuté jusqu’à `pre.014`, corrigé documentairement par `pre.014-fix.001` puis publié par `rel.001`; il conserve l’inventaire officiel 18 méthodes, le modèle session/subscription, le threat model, les preuves de compliance/smoke/dépendances et la préparation de `0.2.8`.
- [`015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md`](015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md) — plan historique clôturé de la release stable `0.2.8 — Helius LaserStream WebSocket`, ouvert par `pre.001`, fermé techniquement/documentairement par `pre.011` puis publié par `rel.001`; il conserve la surface finale Helius `7 standard + transaction`, heartbeat/Config/secrets, l’historique des fixes heartbeat, la stratégie live architecture-safe, les graphes Cargo finaux et la préparation du prompt `0.2.9`.
- [`016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) — plan actif de `0.2.9 — Yellowstone gRPC standard/provider-neutral`, ouvert par `pre.001`; il fixe la stratégie `yellowstone-grpc-proto + Tonic KSP`, la surface `Subscribe + 7 unary`, l’exclusion de `SubscribeDeshred`, Config V3, les règles replay/backpressure et les smokes gratuits PublicNode puis OrbitFlare.
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.

10
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 85 -->
<!-- version: 86 -->
# Séquence des releases fonctionnelles KSP
@@ -473,11 +473,13 @@ Le réaudit final Helius du 23 août 2026 retient `helius_laserstream` comme pro
### `0.2.9` — Yellowstone gRPC standard
Mission : introduire un backend Yellowstone standard/provider-neutral.
Mission active : introduire un backend Yellowstone standard/provider-neutral dans `ksp-onchain-transport-lib`, distinct de HTTP et WebSocket. Le gate `pre.001` est conservé dans [`016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) et sa matrice dans [`../validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](../validation/012-V0_2_9_YELLOWSTONE_GRPC.md).
Le `pre.001` est un gate de sizing : inventorier toute la surface normative cible et scinder la release avant implémentation si sa clôture dans une session paraît incertaine.
Le réaudit du 23 août 2026 corrige le snapshot du prompt : la release GitHub courante observée est `v15.1.2+solana.4.2.0`, tandis que les crates publiées restent `yellowstone-grpc-client 13.3.0` et `yellowstone-grpc-proto 12.6.0`. `0.2.9` retient la stratégie `yellowstone-grpc-proto` Apache-2.0 + client/lifecycle KSP autour de Tonic, et couvre `Subscribe`, les sept RPC unary standard retenus, les filtres Cuckoo/token actuels et les neuf variantes `SubscribeUpdate`. `SubscribeDeshred` reste hors scope comme extension Triton/pré-exécution.
Les profiles/adapters Helius/Triton/ERPC/Chainstack/Shyft sont reportés après les priorités fondatrices.
La Config cible une V3 séparant `grpc_endpoints` de HTTP/WS tout en conservant V1/V2 backward-readable. PublicNode/Allnodes-backed entre dans la release comme premier environnement live standard gratuit Mainnet/Testnet ; OrbitFlare suit comme smoke Devnet gratuit authentifié. Aucun adapter public provider-specific n'est créé pour eux. Tatum reste un fallback opérateur Mainnet à quota lifetime ; les offres gRPC payantes Helius/Shyft/Alchemy/NodeFlare ne deviennent pas des dépendances de validation.
Forecast recalibré : `pre.002` deps/settings, `pre.003` TLS/metadata+unary, `pre.004` Subscribe commun, `pre.005` accounts/slots, `pre.006` transactions, `pre.007` blocks/meta/entry, `pre.008` lifecycle/backpressure, `pre.009` reconnect/replay, `pre.010` Config V3, `pre.011` live/compliance, `pre.012` clôture candidate/prompt suivant. Chaque tranche reste nominalement 15–20 minutes et peut être scindée si le wire transaction/block, le replay ou le graphe de dépendances l'exige.
### `0.2.10` / `0.2.11` — Off-chain price + app

1008
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md Normal file
View File

File diff suppressed because it is too large Load Diff

3
docs/validation/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/000-README.md -->
<!-- version: 23 -->
<!-- version: 24 -->
# Validations KSP
@@ -20,3 +20,4 @@ Documents :
- [`009-V0_2_6_WALLET_DESK_COMPLIANCE.md`](009-V0_2_6_WALLET_DESK_COMPLIANCE.md) — matrice finale validée de la release stable `0.2.6`, couvrant Wallet Desk, les wires V1/V2, la migration explicite, le runtime Tauri packagé, les frontières sécurité/ownership et le gate opérateur `pre.018-fix.001` avec build final Linux vert.
- [`010-V0_2_7_ONCHAIN_WEBSOCKET.md`](010-V0_2_7_ONCHAIN_WEBSOCKET.md) — matrice finale validée de la release stable `0.2.7`, ouverte par `pre.001`, fermée techniquement par `pre.014` puis publiée par `rel.001` : inventaire 9 subscribe + 9 unsubscribe, lifecycle borné, statuts unstable, compliance 18/18, non-régression HTTP 52+14, composition Config V2, smoke WebSocket Devnet et audit de dépendances.
- [`011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md`](011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md) — matrice finale validée de la release stable `0.2.8`, ouverte par `pre.001`, consolidée jusqu’à `pre.011` puis publiée par `rel.001` : Helius `account/logs/program/root/signature/slot/slotsUpdates + transaction`, `block/vote` absents, heartbeat provider, sécurité/redaction, lifecycle adversarial, non-régressions HTTP/WS, stratégie smoke live et graphes Cargo finaux.
- [`012-V0_2_9_YELLOWSTONE_GRPC.md`](012-V0_2_9_YELLOWSTONE_GRPC.md) — matrice active ouverte par `0.2.9-pre.001` : service Geyser courant, `Subscribe` standard, 7 unary, filtres/updates, dépendances/licence, replay/backpressure, Config V3 et interopérabilité PublicNode/OrbitFlare.

446
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md Normal file
View File

@@ -0,0 +1,446 @@
<!-- file: docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md -->
<!-- version: 1 -->
# Validation `0.2.9` — Yellowstone gRPC standard/provider-neutral
> **Statut : matrice ouverte par `0.2.9-pre.001`. Les colonnes `DONE` ne seront cochées qu'après preuves réellement exécutées. Le gate d'ouverture a audité le proto/service, les licences, les dépendances et les fournisseurs live gratuits ; il n'a pas ajouté de client gRPC de production.**
## 1. Autorités du gate
Base interne :
```text
v0.2.8 / archive Gitea stable fournie
workspace.package.version initial = 0.2.8
deltas/0.2.8/rel.001.md
prompts/014-V0_2_9_START_PROMPT.md
```
Sources upstream auditées le `2026-08-23` :
```text
https://github.com/rpcpool/yellowstone-grpc/releases
https://github.com/rpcpool/yellowstone-grpc/blob/master/CHANGELOG.md
https://github.com/rpcpool/yellowstone-grpc/blob/master/LICENSING.md
https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/geyser.proto
https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/solana-storage.proto
https://docs.rs/crate/yellowstone-grpc-client/latest
https://docs.rs/crate/yellowstone-grpc-proto/latest
```
Divergence enregistrée :
```text
snapshot du prompt : GitHub release v14.2.2+solana.4.1.0
réaudit courant : GitHub release v15.1.2+solana.4.2.0 (2026-08-18)
crate client : 13.3.0
crate proto : 12.6.0
```
## 2. Baseline stable
| Gate | Preuve | État |
| --- | --- | --- |
| `cargo fmt --all` | log opérateur `v0.2.8` | DONE |
| audit Rust workspace | clean | DONE |
| `cargo check --workspace` | log opérateur | DONE |
| `cargo clippy --workspace --all-targets` | log opérateur | DONE |
| `cargo test --workspace` | log opérateur | DONE |
| Transport unit | 335 passed | DONE |
| Transport public API | 41 passed | DONE |
| Transport release completeness | 34 passed | DONE |
| Transport doctests | 4 passed | DONE |
| `cargo tree -p ksp-onchain-transport-lib` | log opérateur | DONE |
| `cargo tree --duplicates` | log opérateur | DONE |
## 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 |
## 4. `SubscribeRequest` — coverage normative
### 4.1 Top-level
| Champ | Sémantique | Scope | Preuve |
| --- | --- | --- | --- |
| `accounts` | map filter-name -> account filter | IN | exact wire + bounds |
| `slots` | map -> slot filter | IN | exact wire |
| `transactions` | map -> transaction filter | IN | exact wire + bounds |
| `transactions_status` | map -> transaction filter | IN | exact wire + bounds |
| `blocks` | map -> block filter | IN | exact wire + bounds |
| `blocks_meta` | map -> empty filter | IN | presence/empty semantics |
| `entry` | map -> empty filter | IN | presence/empty semantics |
| `commitment` | optional Processed/Confirmed/Finalized | IN | omitted/value exact |
| `accounts_data_slice` | repeated offset/length | IN | order + bounds |
| `ping` | optional id | IN | Ping/Pong lifecycle |
| `from_slot` | optional u64 | IN | reconnect/replay tests |
### 4.2 Accounts
| Capacité | Scope | Preuve |
| --- | --- | --- |
| `account[]` | IN | order/cardinality/address validation |
| `owner[]` | IN | order/cardinality/address validation |
| `filters[]` | IN | AND semantics preserved structurally |
| `nonempty_txn_signature?` | IN | omitted/false/true |
| `cuckoo_accounts_filter?` | IN | exact wire + dimension/data bounds |
| memcmp bytes | IN | exact bytes + bounds |
| memcmp base58 | IN | exact string + validation |
| memcmp base64 | IN | exact string + validation |
| `datasize` | IN | exact u64 |
| `token_account_state` | IN | bool |
| lamports `eq/ne/lt/gt` | IN | oneof exact |
### 4.3 Slots
| Capacité | Scope | Preuve |
| --- | --- | --- |
| `filter_by_commitment?` | IN | optional semantics |
| `interslot_updates?` | IN | optional semantics |
| processed/confirmed/finalized | IN | enum decode |
| first_shred_received/completed/created_bank/dead | IN | enum decode + dead_error |
### 4.4 Transactions / transaction_status
| Capacité | Scope | Preuve |
| --- | --- | --- |
| `vote?` | IN | optional semantics |
| `failed?` | IN | optional semantics |
| `signature?` | IN | exact/validated |
| `account_include[]` | IN | order/bounds |
| `account_exclude[]` | IN | order/bounds |
| `account_required[]` | IN | order/bounds |
| `cuckoo_account_include?` | IN | exact wire + bounds |
| `token_accounts? = ALL` | IN | optional enum |
| `token_accounts? = BALANCE_CHANGED` | IN | optional enum |
### 4.5 Blocks
| Capacité | Scope | Preuve |
| --- | --- | --- |
| `account_include[]` | IN | order/bounds |
| `include_transactions?` | IN | optional semantics |
| `include_accounts?` | IN | optional semantics |
| `include_entries?` | IN | optional semantics |
| `cuckoo_account_include?` | IN | exact wire + bounds |
## 5. `SubscribeUpdate` — coverage normative
| Variante | Champs structurants | Scope | Preuve |
| --- | --- | --- | --- |
| `account` | account info, slot, is_startup | IN | exact decode |
| `slot` | slot, parent?, status, dead_error? | IN | exact decode |
| `transaction` | signature, vote, transaction, meta, index, slot | IN | exact decode |
| `transaction_status` | slot, signature, vote, index, err | IN | exact decode |
| `block` | hash/rewards/time/height/parents/counts + tx/accounts/entries | IN | exact decode + bounds |
| `ping` | marker | IN | lifecycle |
| `pong` | id | IN | lifecycle |
| `block_meta` | metadata/counts | IN | exact decode |
| `entry` | slot/index/hash/counts | IN | exact decode |
Top-level à préserver :
```text
filters[]
created_at
oneof absent/inconnu -> comportement explicitement testé
```
## 6. `solana-storage.proto` — nested wire utile
Le backend doit préserver les champs nécessaires des structures imbriquées actuelles, sans exposer les types upstream comme contrat public :
```text
ConfirmedBlock
ConfirmedTransaction
Transaction
Message
MessageHeader
MessageAddressTableLookup
TransactionStatusMeta
TransactionError
InnerInstructions / InnerInstruction
CompiledInstruction
TokenBalance / UiTokenAmount
ReturnData
Reward / Rewards
UnixTimestamp
BlockHeight
NumPartitions
```
États optionnels/legacy particulièrement sensibles :
```text
compute_units_consumed?
cost_units?
inner_instructions_none
log_messages_none
return_data_none
loaded writable/readonly addresses
commission / commission_bps
```
Preuve cible : fixtures issues du wire Protobuf + cas old/current + malformed/oversized, sans conversion JSON arbitraire.
## 7. Unary RPC matrix
| RPC | Request exact | Response exact | État |
| --- | --- | --- | --- |
| ReplayInfo | empty | `first_available?` | TODO |
| Ping | `count` | `count` | TODO |
| LatestBlockhash | `commitment?` | slot/hash/last_valid_height | TODO |
| BlockHeight | `commitment?` | block_height | TODO |
| Slot | `commitment?` | slot | TODO |
| IsBlockhashValid | blockhash + `commitment?` | slot + bool | TODO |
| Version | empty | version | TODO |
## 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 |
Versions observées :
```text
yellowstone-grpc-client 13.3.0
yellowstone-grpc-proto 12.6.0
tonic 0.14.x (0.14.6 latest observé)
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 |
| no provider-specific public types | public API/completeness | TODO |
## 10. Settings, bounds et redaction
À fermer par tests :
```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
```
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
```
## 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 | 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 :
```text
exactly-once
lossless
historical replay complet
ordre global sans gap
```
## 12. Config V3
Décision de gate :
```text
V1 HTTP reste lisible
V2 HTTP+WS reste lisible
V3 ajoute gRPC explicitement
```
Shape conceptuelle à matérialiser :
```text
globals.grpc_defaults
profiles[].grpc_endpoints[]
endpoint.metadata[] # public/non-secret
endpoint.secret_metadata[] # Config-owned secret provenance
```
Canaries :
| Gate | État |
| --- | --- |
| V1 backward readable | TODO |
| V2 backward readable | TODO |
| V3 schema strict | TODO |
| gRPC endpoint mapping | TODO |
| secret provenance enforced | TODO |
| safe projection redacted | TODO |
| no Transport -> Config | TODO |
| `.env.example` inventory if new env vars | TODO |
## 13. Fournisseurs live gratuits / durables
| Provider | Cluster gRPC gratuit confirmé | Nature | Priorité `0.2.9` | Verdict |
| --- | --- | --- | --- | --- |
| **PublicNode / Allnodes-backed** | Mainnet + Testnet | endpoint public, pas de plan payant requis observé | 1 | **IN smoke** |
| **OrbitFlare** | Devnet | Free $0, 10 RPS/1 TPS, unlimited credits | 2 | **IN smoke secondaire** |
| Tatum | Mainnet | Free durable mais 100K lifetime credits, 5 subscriptions | 3 | opérateur optionnel |
| Helius | aucun sur Free | Devnet Developer, Mainnet Business | — | OUT free |
| Shyft | aucun sur Free | Free indique No gRPC Access | — | OUT free |
| Alchemy | aucun sur Free | PAYG/Enterprise requis | — | OUT free |
| QuickNode | aucun sur Free | Scale/Business ou add-on payant | — | OUT free |
| Chainstack | aucun sur Free | add-on Yellowstone payant, Growth+ | — | OUT free |
| ERPC | aucun durable | plan Geyser payant, trial 1 jour | — | OUT free |
| NodeFlare | endpoint gRPC présent | plan Yellowstone mensuel payant | — | OUT free |
| Bitquery | pas Yellowstone standard | CoreCast custom, stream gratuit non garanti | — | OUT 0.2.9 |
| Solinfra | **non confirmé** | free tier + Yellowstone annoncés, entitlement gRPC free non explicite | recheck | CANDIDAT |
Sources provider :
```text
https://publicnode.com/
https://solana-yellowstone-grpc.publicnode.com/
https://orbitflare.com/pricing
https://docs.tatum.io/reference/solana-grpc
https://tatum.io/pricing
https://www.helius.dev/pricing
https://shyft.to/solana-rpc-grpc-pricing
https://www.alchemy.com/docs/reference/yellowstone-grpc-quickstart
https://www.quicknode.com/docs/solana/solana-grpc/overview
https://chainstack.com/pricing/
https://erpc.global/en/grpc/
https://nodeflare.app/solana
https://docs.bitquery.io/docs/grpc/solana/introduction/
https://solinfra.dev/
```
### Smoke PublicNode
Cible principale officiellement affichée :
```text
solana-yellowstone-grpc.publicnode.com:443
```
Testnet GRPC est officiellement listé. L'endpoint exact doit être confirmé avant commit d'un profil durable.
### Smoke OrbitFlare
Credential : jamais versionné. La clé/header gRPC exacte doit être confirmée depuis la documentation/live au moment du smoke ; le contrat Transport reste generic secret metadata.
## 14. Non-régressions obligatoires
| Surface héritée | Attendu final | État |
| --- | --- | --- |
| HTTP current | 52 typed | TODO final |
| HTTP historical | 14 Deprecated/Removed | TODO final |
| Standard WS | 18 opérations / 9 familles | TODO final |
| Helius WS | 7 standard + transaction | TODO final |
| Helius heartbeat | Ping 60 s | TODO final |
| Config V1/V2 | backward read | TODO final |
| Wallet/Wallet Desk | aucune dépendance protocolaire Yellowstone directe | TODO final |
## 15. Forecast / preuve par tranche
```text
pre.001 DONE audit + matrices + dependencies/license + providers + sizing
pre.002 TODO deps/settings/errors/facade + cargo tree
pre.003 TODO TLS/metadata + local fixture + 7 unary
pre.004 TODO Subscribe common + Cuckoo/token/from_slot/bounds
pre.005 TODO accounts + slots
pre.006 TODO transactions + transaction_status
pre.007 TODO blocks + block_meta + entry
pre.008 TODO bidi lifecycle/backpressure/half-close/shutdown
pre.009 TODO reconnect/replay/gap/duplicate/equivocation
pre.010 TODO Config V3
pre.011 TODO live PublicNode/OrbitFlare + compliance + final cargo graphs
pre.012 TODO docs/workspace final/prompt 0.2.10
rel.001 TODO stable
```
## 16. Gate `pre.001`
| Critère du prompt | Verdict |
| --- | --- |
| base stable `v0.2.8` confirmée | PASS |
| baseline opérateur enregistrée | PASS |
| upstream courant relu | PASS |
| divergence snapshot/latest enregistrée | PASS |
| service/proto exhaustif inventorié | PASS |
| standard vs provider extension classifié | PASS |
| `SubscribeDeshred` classifié | PASS / OUT |
| unary RPCs classifiés | PASS / 7 IN |
| replay/from_slot audités | PASS |
| strategy dependency choisie | PASS / B |
| licence auditée avant ajout | PASS |
| features/MSRV/transitifs audit initial | PASS / materialisation pre.002 |
| architecture distincte WS | PASS |
| metadata/auth neutral | PASS |
| Config shape décidée | PASS / V3 |
| resource/backpressure policy décidée | PASS |
| smoke ownership décidé | PASS |
| providers gratuits audités | PASS |
| release dimensionnée | PASS |
| forecast recalibré | PASS |
| split criteria écrits | PASS |
| 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.**