256 lines
7.1 KiB
Markdown
256 lines
7.1 KiB
Markdown
<!-- file: deltas/0.3.12/pre.003.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.12-pre.003` — signaux privés Yellowstone Transaction + TransactionStatus
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.3.12-pre.002
|
|
workspace.package.version = 0.3.12-pre.2
|
|
```
|
|
|
|
Le gate opérateur communiqué pour `pre.002` est vert sur :
|
|
|
|
```text
|
|
cargo fmt --all
|
|
Rust rule audit
|
|
Markdown table audit
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test -p ksp-worker-raw-transaction-ingest-lib : 41 PASS
|
|
cargo tree Worker normal/features
|
|
cargo tree --duplicates exécuté pour inspection
|
|
```
|
|
|
|
Le graphe confirme que `reqwest`, `tonic` et `yellowstone-grpc-proto` restent transitifs via `ksp-onchain-transport-lib`, jamais directs dans le Worker.
|
|
|
|
## Objectif
|
|
|
|
Matérialiser uniquement les deux adapters déterministes prévus :
|
|
|
|
```text
|
|
YellowstoneTransactionUpdate -> signal Worker privé
|
|
YellowstoneTransactionStatusUpdate -> signal Worker privé
|
|
```
|
|
|
|
sans ouvrir de session Yellowstone, sans HTTP et sans persistence réseau.
|
|
|
|
## Version
|
|
|
|
```text
|
|
workspace.package.version = 0.3.12-pre.3
|
|
```
|
|
|
|
## Signal Worker privé
|
|
|
|
Le signal est strictement privé à `runtime_resources.rs`. Sa forme contient :
|
|
|
|
```text
|
|
RawNetworkId
|
|
RawTransactionSignature
|
|
slot u64
|
|
transaction_index Option<u64>
|
|
family Transaction | TransactionStatus
|
|
route sûre provider + endpoint_id
|
|
matched_filter_count
|
|
matched_filter_fingerprint [u8; 32]
|
|
created_at Option<seconds+nanos>
|
|
```
|
|
|
|
Il ne contient volontairement pas :
|
|
|
|
```text
|
|
transaction body Yellowstone
|
|
transaction meta Yellowstone
|
|
is_vote
|
|
TransactionStatus.error
|
|
raw/provider payload
|
|
HTTP material
|
|
Store acquisition
|
|
```
|
|
|
|
La signature Yellowstone `[u8; 64]` est convertie directement vers `RawTransactionSignature`; aucune Base58 intermédiaire n'est introduite.
|
|
|
|
## Adapter `Transaction`
|
|
|
|
Le mapping utilise exactement :
|
|
|
|
```text
|
|
update.slot()
|
|
update.transaction().signature()
|
|
update.transaction().index()
|
|
update.filters()
|
|
update.created_at()
|
|
```
|
|
|
|
Le body et la meta présents dans `YellowstoneTransactionInfo` restent ignorés jusqu'à l'hydration HTTP qualifiée de `pre.004`.
|
|
|
|
## Adapter `TransactionStatus`
|
|
|
|
Le mapping utilise exactement :
|
|
|
|
```text
|
|
update.slot()
|
|
update.signature()
|
|
update.index()
|
|
update.filters()
|
|
update.created_at()
|
|
```
|
|
|
|
`update.error()` n'est pas consulté. Le remote error opaque n'est donc ni copié dans le signal, ni transformé en contexte Worker, ni loggé.
|
|
|
|
## Fingerprint des filtres
|
|
|
|
Le fingerprint est Worker-owned, SHA-256 et domain-separated :
|
|
|
|
```text
|
|
ksp.raw_transaction_ingest.yellowstone.filters.v1\0
|
|
```
|
|
|
|
Les noms sont triés puis dédupliqués avant hashing ; chaque élément est length-prefixed par un `u64` big-endian. Le résultat est donc déterministe pour le même ensemble de filtres, même si l'ordre d'enveloppe diffère.
|
|
|
|
Le golden de fixture `filter-a + filter-b` est :
|
|
|
|
```text
|
|
20831dc8378b6070f91d9de6d3a1d2b3d77298e3ada76c01faa30826ffabcd84
|
|
```
|
|
|
|
Les noms eux-mêmes ne sont pas conservés dans le signal et n'apparaissent pas dans son `Debug`.
|
|
|
|
## Route source sûre
|
|
|
|
La source Yellowstone convertit dès construction :
|
|
|
|
```text
|
|
cluster -> RawNetworkId
|
|
provider -> RawProvenanceCode
|
|
logical endpoint name -> RawProvenanceCode
|
|
```
|
|
|
|
Une valeur impossible à représenter selon les bornes Store est rejetée par `worker_raw_transaction_ingest.runtime_invalid` avec une condition statique. Il n'y a ni troncature ni fuite de valeur.
|
|
|
|
Cela prépare `pre.004`, où le provider/endpoint HTTP gagnant sera combiné avec cette identité Yellowstone dans la provenance composite retenue par le plan.
|
|
|
|
## Absence volontaire de comportement live
|
|
|
|
Toujours absents en `pre.003` :
|
|
|
|
```text
|
|
open_standard_subscribe
|
|
next_update
|
|
get_transaction_observed
|
|
get_block_observed
|
|
source task Yellowstone
|
|
HTTP hydration
|
|
RawTransactionIngress issue du réseau
|
|
Store write issue du réseau
|
|
coalescence hydration
|
|
frontier / reconnect / replay
|
|
```
|
|
|
|
L'activation productive de la session reste `pre.006`.
|
|
|
|
## Tests et hardening ajoutés
|
|
|
|
```text
|
|
Transaction fixture -> identité source-neutral exacte
|
|
TransactionStatus fixture -> même forme sans payload/error
|
|
fingerprint golden exact
|
|
fingerprint order/duplicate insensitive
|
|
signal Debug redacted
|
|
route provider/endpoint non représentable rejetée
|
|
source-scan des deux adapters Transport
|
|
TransactionStatus.error absent du mapping
|
|
signal non public
|
|
aucun I/O live prématuré
|
|
```
|
|
|
|
## Décisions prises
|
|
|
|
```text
|
|
un seul signal privé commun aux deux familles
|
|
signature canonique conservée en bytes fixes
|
|
transaction_index toujours Some pour ces deux DTOs mais champ du signal reste optionnel pour les familles suivantes
|
|
filter fingerprint canonique indépendant de l'ordre
|
|
gRPC route identity validée tôt pour la future provenance
|
|
remote TransactionStatus.error ignoré au boundary Worker
|
|
```
|
|
|
|
## Questions ouvertes
|
|
|
|
Aucune question ouverte n'est bloquante pour `pre.003`. Les choix HTTP missing/mismatch, provenance composite finale et fan-out/coalescence restent volontairement dans `pre.004`, conformément au plan.
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
deltas/0.3.12/pre.003.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/runtime_resources.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/runtime_resources.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs
|
|
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
Aucun.
|
|
|
|
## Validations exécutées dans l'environnement d'assemblage
|
|
|
|
```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'audit Markdown final est exécuté après création de ce delta.
|
|
|
|
`cargo`, `rustc` et `rustfmt` ne sont pas installés dans l'environnement d'assemblage. Aucun gate Cargo local n'est déclaré PASS.
|
|
|
|
## Gate opérateur demandé
|
|
|
|
```bash
|
|
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
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test -p ksp-worker-raw-transaction-ingest-lib
|
|
cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal
|
|
cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
## Non-claims
|
|
|
|
Cette tranche ne revendique pas :
|
|
|
|
```text
|
|
session Yellowstone ouverte
|
|
update réseau réellement consommée
|
|
hydration HTTP
|
|
conversion réseau vers Common RAW
|
|
provenance composite finale
|
|
persistence réseau
|
|
Block / BlockMeta / Slot
|
|
coalescence
|
|
processing frontier
|
|
from_slot / ReplayInfo
|
|
smoke live Worker
|
|
réconciliation README/USAGE/architecture finale
|
|
```
|
|
|
|
## Suite
|
|
|
|
Après gate opérateur vert, `pre.004` ferme `signal -> get_transaction_observed -> Common RAW -> RawTransactionIngress`, avec `missing`, mismatches et provenance Yellowstone + HTTP observée. Block et la continuité/replay restent hors scope.
|