251 lines
6.9 KiB
Markdown
251 lines
6.9 KiB
Markdown
<!-- file: deltas/0.2.9/pre.004.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.9-pre.004` — fondation `SubscribeRequest` Yellowstone standard
|
|
|
|
## 1. Base et signal de version
|
|
|
|
Base obligatoire :
|
|
|
|
```text
|
|
0.2.9-pre.3.fix.1
|
|
```
|
|
|
|
Le gate opérateur fourni ferme `pre.003-fix.001` :
|
|
|
|
```text
|
|
cargo fmt --all PASS
|
|
python3 scripts/audit_rust_workspace_rules.py PASS / clean
|
|
cargo check --workspace PASS
|
|
cargo clippy --workspace --all-targets PASS
|
|
cargo test --workspace PASS
|
|
Transport unit 354/354
|
|
Transport public_api 43/43
|
|
Transport release_completeness 36/36
|
|
Transport doctests 4/4
|
|
cargo tree -p ... fourni/relu
|
|
cargo tree -p ... -e features fourni/relu
|
|
cargo tree -p ... --duplicates fourni/relu
|
|
cargo tree --duplicates fourni/relu
|
|
```
|
|
|
|
Le graphe pertinent reste unifié sur `tonic 0.14.6`, `tonic-prost 0.14.6`, `prost/prost-types 0.14.4`, `yellowstone-grpc-proto 12.6.0` et `solana-pubkey 4.3.0`.
|
|
|
|
Cette tranche non-fix synchronise :
|
|
|
|
```text
|
|
workspace.package.version = 0.2.9-pre.4
|
|
commit attendu = v0.2.9-pre.004
|
|
aucun tag prerelease
|
|
```
|
|
|
|
## 2. Scope exact
|
|
|
|
`pre.004` matérialise uniquement la fondation N2 du `SubscribeRequest` standard publié :
|
|
|
|
```text
|
|
accounts
|
|
slots
|
|
transactions
|
|
transactions_status
|
|
blocks
|
|
blocks_meta
|
|
entry
|
|
commitment
|
|
accounts_data_slice
|
|
ping
|
|
from_slot
|
|
```
|
|
|
|
Le proto `yellowstone-grpc-proto 12.6.0` a été recontrôlé avant implémentation et conserve exactement ces champs top-level.
|
|
|
|
Sont explicitement hors tranche :
|
|
|
|
```text
|
|
champs détaillés Accounts / Slots -> pre.005
|
|
champs détaillés Transactions / transaction_status -> pre.006
|
|
champs détaillés Blocks / block_meta / entry updates -> pre.007
|
|
stream bidi / mutation / Ping-Pong runtime -> pre.008
|
|
reconnect / replay / gaps / duplicates -> pre.009
|
|
Config V3 / PublicNode -> pre.010/011
|
|
SubscribeDeshred -> OUT 0.2.9 standard
|
|
```
|
|
|
|
## 3. Contrat KSP ajouté
|
|
|
|
Nouveaux types publics :
|
|
|
|
```text
|
|
YellowstoneSubscribeFilterName
|
|
YellowstoneAccountsDataSlice
|
|
YellowstoneSubscribePing
|
|
YellowstoneSubscribeAccountFilter
|
|
YellowstoneSubscribeSlotFilter
|
|
YellowstoneSubscribeTransactionFilter
|
|
YellowstoneSubscribeBlockFilter
|
|
YellowstoneSubscribeBlocksMetaFilter
|
|
YellowstoneSubscribeEntryFilter
|
|
YellowstoneSubscribeRequest
|
|
```
|
|
|
|
Les quatre filtres de famille riches sont volontairement des shells typés en `pre.004`. Ils permettent de matérialiser les sept maps et les entrées nommées vides sans anticiper les champs propres aux tranches suivantes.
|
|
|
|
Le wire `yellowstone_grpc_proto::geyser::SubscribeRequest` reste privé : aucun type Tonic/Prost/Yellowstone n'est réexporté au crate root.
|
|
|
|
## 4. Sémantique maps / noms
|
|
|
|
KSP conserve sept maps logiques indépendantes.
|
|
|
|
```text
|
|
map vide = aucun filtre actif dans la famille
|
|
entrée nommée + message vide = activation explicite d'un groupe vide supporté par le proto
|
|
```
|
|
|
|
Le Protobuf ne distingue pas une map top-level omise d'une map vide ; KSP ne prétend donc pas préserver une différence wire inexistante.
|
|
|
|
Les noms sont :
|
|
|
|
```text
|
|
non vides
|
|
trim exact
|
|
sans caractère de contrôle
|
|
<= 128 octets UTF-8
|
|
uniques globalement entre les sept maps
|
|
```
|
|
|
|
L'unicité globale évite l'ambiguïté lorsque Yellowstone renvoie seulement les noms correspondants dans `SubscribeUpdate.filters[]`.
|
|
|
|
Le nombre total de groupes nommés est plafonné à `1024` sur l'ensemble des sept maps.
|
|
|
|
## 5. Champs communs et bounds
|
|
|
|
`commitment` réutilise `SolanaCommitment` et mappe exactement :
|
|
|
|
```text
|
|
Processed -> PROCESSED
|
|
Confirmed -> CONFIRMED
|
|
Finalized -> FINALIZED
|
|
```
|
|
|
|
`accounts_data_slice` :
|
|
|
|
```text
|
|
ordre d'insertion conservé
|
|
nombre <= 128
|
|
length <= 64 MiB
|
|
offset + length doit rester représentable en u64
|
|
length = 0 reste représentable
|
|
```
|
|
|
|
`ping` conserve l'identifiant `i32` exact.
|
|
|
|
`from_slot` conserve l'optional `u64` sans lui attribuer encore une promesse de replay/lossless ; sa sémantique lifecycle reste en `pre.009`.
|
|
|
|
## 6. Diagnostics et sécurité
|
|
|
|
`Debug` de `YellowstoneSubscribeFilterName` est redacted.
|
|
|
|
`Debug` de `YellowstoneSubscribeRequest` expose uniquement :
|
|
|
|
```text
|
|
compteurs par famille
|
|
commitment
|
|
nombre de data slices
|
|
ping
|
|
from_slot
|
|
```
|
|
|
|
Il n'expose aucun nom de filtre ni futur payload account/transaction/block.
|
|
|
|
Les erreurs déterministes utilisent `ERROR_CODE_INVALID_RPC_PARAMETERS` et n'incluent pas les valeurs de noms/payloads rejetés.
|
|
|
|
## 7. Dépendances
|
|
|
|
Aucune dépendance ni feature Cargo n'est modifiée dans `pre.004`.
|
|
|
|
Les graphes fournis pour `pre.003-fix.001` restent l'autorité courante ; aucun nouveau `cargo tree` n'est requis spécifiquement par ce delta sauf anomalie de compilation.
|
|
|
|
## 8. Tests/canaries ajoutés
|
|
|
|
Unit tests :
|
|
|
|
```text
|
|
nom vide/whitespace/control/oversized rejeté
|
|
Debug nom redacted
|
|
unicité globale cross-family
|
|
request vide -> sept maps vides + common absent
|
|
sept entrées nommées vides -> wire exact
|
|
commitment/ping/from_slot exacts
|
|
ordre data slices conservé
|
|
zero-length slice conservée
|
|
slice length/overflow/count bornés
|
|
filter-group count borné
|
|
request Debug sans filter name
|
|
```
|
|
|
|
Public API : construction des sept maps et champs communs depuis le crate root.
|
|
|
|
Release completeness :
|
|
|
|
```text
|
|
onze champs top-level présents dans l'adapter
|
|
bounds communs matérialisés
|
|
aucun SubscribeDeshred
|
|
aucun PublicNode/OrbitFlare/Helius runtime
|
|
aucun raw Tonic/Yellowstone reexport
|
|
to_wire protobuf non public
|
|
```
|
|
|
|
## 9. Fichiers ajoutés
|
|
|
|
```text
|
|
crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/grpc_subscribe.rs
|
|
deltas/0.2.9/pre.004.md
|
|
```
|
|
|
|
## 10. Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/src/lib.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
|
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
|
|
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
|
|
```
|
|
|
|
## 11. Validation de préparation
|
|
|
|
```text
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
General Rust rule audit: clean
|
|
Rust export completeness audit: 0 candidate(s)
|
|
KSP workspace Rust rule audit: clean
|
|
```
|
|
|
|
L'environnement de préparation ne fournit pas Cargo/Rust ; aucune compilation n'est déclarée réussie localement.
|
|
|
|
## 12. Gate opérateur attendu
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-onchain-transport-lib
|
|
cargo test -p ksp-core-lib --test workspace_dependencies
|
|
cargo test --workspace
|
|
```
|
|
|
|
Attendu si aucun fix n'est nécessaire :
|
|
|
|
```text
|
|
Transport unit 359
|
|
Transport public_api 44
|
|
Transport release_completeness 37
|
|
Transport doctests 4
|
|
```
|
|
|
|
Les live smokes restent ignored/opt-in.
|