v0.2.9-pre.001
This commit is contained in:
377
deltas/0.2.9/pre.001.md
Normal file
377
deltas/0.2.9/pre.001.md
Normal 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`.
|
||||
Reference in New Issue
Block a user