v0.3.10-pre.001
This commit is contained in:
354
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
Normal file
354
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
Normal file
@@ -0,0 +1,354 @@
|
||||
<!-- file: docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Validation v0.3.10 — RAW Transaction commune + Worker d’ingestion
|
||||
|
||||
## 1. Rôle du document
|
||||
|
||||
Ce document suit les preuves de la release `0.3.10` : extraction de la canonicalisation RAW v1 vers `ksp-raw-transaction-lib`, migration Backfill puis matérialisation du Worker continu multi-source `ksp-worker-raw-transaction-ingest-lib`.
|
||||
|
||||
Il distingue toujours :
|
||||
|
||||
```text
|
||||
preuve exécutée
|
||||
preuve seulement planifiée
|
||||
preuve live accessible
|
||||
preuve live bloquée par secret/tier
|
||||
non-claim explicite
|
||||
```
|
||||
|
||||
## 2. Gate `pre.001` — audit/sizing/plan
|
||||
|
||||
État : **fermé pour la planification**, sans claim Cargo local.
|
||||
|
||||
### 2.1 Base contrôlée
|
||||
|
||||
```text
|
||||
archive : khadhroony-solana-project-v0.3.9.zip
|
||||
SHA-256 : 41ef2589a11410aabfb329d387f0008e116006da60ada0802e5f72bc30d3466f
|
||||
bytes : 7859118
|
||||
entries : 1855
|
||||
unzip -t : PASS
|
||||
workspace members : 19
|
||||
workspace.package.version base : 0.3.9
|
||||
stable delta : deltas/0.3.9/rel.001.md
|
||||
```
|
||||
|
||||
Sécurité archive :
|
||||
|
||||
```text
|
||||
absolute/traversal entries : 0
|
||||
symlinks : 0
|
||||
.git/ : 0
|
||||
target/ : 0
|
||||
node_modules/ : 0
|
||||
Cargo.lock : 0
|
||||
.env : 0
|
||||
private-key-like files checked : 0
|
||||
```
|
||||
|
||||
Le ZIP ne contient pas `.git`; le tag n’est donc pas directement inspectable dans cet environnement.
|
||||
|
||||
### 2.2 Baseline statique exécutée avant modification
|
||||
|
||||
```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
|
||||
|
||||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
|
||||
Markdown table audit: clean (332 table(s), 750 file(s))
|
||||
```
|
||||
|
||||
### 2.3 Cargo local
|
||||
|
||||
```text
|
||||
cargo : indisponible dans l’environnement d’assemblage
|
||||
```
|
||||
|
||||
Par conséquent :
|
||||
|
||||
```text
|
||||
cargo fmt : NON EXÉCUTÉ ici
|
||||
cargo check : NON EXÉCUTÉ ici
|
||||
cargo clippy: NON EXÉCUTÉ ici
|
||||
cargo test : NON EXÉCUTÉ ici
|
||||
cargo tree : NON EXÉCUTÉ ici
|
||||
Tauri build : NON EXÉCUTÉ ici
|
||||
```
|
||||
|
||||
Aucun de ces gates n’est déclaré PASS par cette session. Le journal opérateur fourni pour la stable `0.3.9` montre un gate complet antérieur ; il reste une preuve externe de la base stable, pas une exécution `pre.001` locale.
|
||||
|
||||
## 3. Preuves de conception fermées en `pre.001`
|
||||
|
||||
### 3.1 Common RAW
|
||||
|
||||
Décisions prouvées par inspection du code courant :
|
||||
|
||||
```text
|
||||
format_id courant = ksp.solana.raw_transaction
|
||||
format_version courant = 1
|
||||
RawObservationKey est explicitement producer-owned dans Store
|
||||
RawTransaction identity = network + signature
|
||||
RawTransactionObservation est séparée de l’entité
|
||||
ksp-store-lib reexporte les primitives nécessaires
|
||||
Backfill conversion mélange actuellement canonicalisation commune et metadata Job-owned
|
||||
```
|
||||
|
||||
Canari RAW v1 recalculé :
|
||||
|
||||
```text
|
||||
bytes = {"transaction":["AQID","base64"],"meta":{"a":{"x":null,"y":true},"z":1},"version":"legacy","transactionIndex":7}
|
||||
len = 112
|
||||
sha256 = 220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3
|
||||
```
|
||||
|
||||
Le plan interdit tout déplacement de `job_id`, `scope_fingerprint`, lifecycle, checkpoint ou observation-key algorithm dans common.
|
||||
|
||||
### 3.2 Transport
|
||||
|
||||
Inventaire confirmé dans `ksp-onchain-transport-lib` :
|
||||
|
||||
```text
|
||||
HttpObservedValue<T>
|
||||
get_transaction_observed
|
||||
get_block / get_blocks / get_blocks_with_limit
|
||||
logsSubscribe
|
||||
signatureSubscribe
|
||||
blockSubscribe
|
||||
Helius transactionSubscribe
|
||||
Yellowstone transactions
|
||||
Yellowstone transactions_status
|
||||
Yellowstone blocks
|
||||
Yellowstone blocks_meta
|
||||
Yellowstone slots
|
||||
Yellowstone from_slot
|
||||
SubscribeReplayInfo / reconnect snapshot
|
||||
```
|
||||
|
||||
Gaps requalifiés :
|
||||
|
||||
```text
|
||||
TR-B confirmé : get_block_observed
|
||||
TR-C confirmé/scindé : common material + adapters Worker + Transport seulement si DTO insuffisant
|
||||
TR-D confirmé : provenance durable full-material + runtime source projection
|
||||
TR-E confirmé : réutiliser from_slot/replay existant, aucun second moteur
|
||||
TR-F réservé : aucun EARLY sans protocole+accès+rôle RAW prouvés
|
||||
```
|
||||
|
||||
### 3.3 Config
|
||||
|
||||
Constats :
|
||||
|
||||
```text
|
||||
std.transport format_version = 3
|
||||
mainnet logique déjà canonique
|
||||
profils OrbitFlare Devnet et PublicNode Mainnet/Testnet déjà présents
|
||||
gRPC metadata publique/secrète déjà typée et redacted
|
||||
HTTP roles/priorities/limits déjà supportés
|
||||
WS protocol/session déjà supportés
|
||||
```
|
||||
|
||||
Décision : pas d’edge Worker -> Config et pas de nouveau document métier Worker imposé dans `0.3.10`. Une adaptation Config n’est admise que pour un manque Transport concret découvert pendant l’implémentation.
|
||||
|
||||
## 4. Fraîcheur externe `pre.001`
|
||||
|
||||
### 4.1 Yellowstone
|
||||
|
||||
Vérifié le 5 septembre 2026 :
|
||||
|
||||
```text
|
||||
yellowstone-grpc-proto latest = 12.7.0
|
||||
publication = 2026-08-29
|
||||
workspace KSP = ^12.7
|
||||
```
|
||||
|
||||
Décision : aucun bump en ouverture.
|
||||
|
||||
Canaris imposés par changements upstream récents :
|
||||
|
||||
```text
|
||||
Transaction V1/config doit survivre à la projection
|
||||
block replay from_slot doit avoir un smoke dédié
|
||||
```
|
||||
|
||||
### 4.2 Providers
|
||||
|
||||
| Source | Fait revalidé | Type de preuve `0.3.10` |
|
||||
|:-----------------|:-------------------------------------------------------------------------------------|:---------------------------------------|
|
||||
| Solana public | HTTP/WS standard accessibles ; blockSubscribe unstable | live opt-in + fixtures |
|
||||
| PublicNode | Yellowstone Mainnet/Testnet affiché ; archive access proposé | live opt-in si token/config disponible |
|
||||
| OrbitFlare | Devnet gRPC Free/Developer ; Yellowstone full-fidelity | live opt-in avec x-token opérateur |
|
||||
| Helius | transactionSubscribe courant ; blockSubscribe non supporté ; LaserStream replay 24 h | fixture + live si tier/key |
|
||||
| QuickNode | gRPC Scale+ ; port 443/x-token ; 10000 sunset 2026-10-01 | tier-bloqué |
|
||||
| Alchemy | PAYG/Enterprise ; docs replay 6000 vs 432000 slots contradictoires | tier-bloqué, aucune constante |
|
||||
| Jito ShredStream | shutdown annoncé 2026-09-05 | exclu TR-F |
|
||||
|
||||
## 5. Gates de parité RAW obligatoires
|
||||
|
||||
Une source dite full n’obtient le statut `direct canonical producer` qu’après :
|
||||
|
||||
```text
|
||||
same fixture identity
|
||||
same canonical bytes
|
||||
same SHA-256
|
||||
same slot
|
||||
same block_time semantics
|
||||
same version/index semantics
|
||||
```
|
||||
|
||||
Familles à prouver séparément :
|
||||
|
||||
```text
|
||||
HTTP getTransaction
|
||||
HTTP getBlock transaction
|
||||
WS blockSubscribe transaction
|
||||
Helius transactionSubscribe full
|
||||
Yellowstone transaction
|
||||
Yellowstone block transaction
|
||||
Transaction V1
|
||||
```
|
||||
|
||||
En cas d’échec de parité :
|
||||
|
||||
```text
|
||||
pas de RAW v2 automatique
|
||||
pas de first-provider-wins
|
||||
pas de content normalization ad hoc non documentée
|
||||
source utilisée comme discovery + hydration HTTP jusqu’à résolution
|
||||
```
|
||||
|
||||
## 6. Gates Worker à fermer pendant la release
|
||||
|
||||
### 6.1 Lifecycle/runtime
|
||||
|
||||
```text
|
||||
Created -> Starting -> Running -> Stopping -> Stopped
|
||||
Faulted terminal
|
||||
stop idempotent
|
||||
caller-owned Tokio runtime
|
||||
Worker-owned spawned tasks
|
||||
aucun JoinHandle public
|
||||
shutdown borné
|
||||
aucune tâche source survivante
|
||||
```
|
||||
|
||||
### 6.2 Sources et backpressure
|
||||
|
||||
```text
|
||||
N sources simultanées
|
||||
bounded channels seulement
|
||||
slow source isolation
|
||||
queue saturation observable
|
||||
aucun drop silencieux
|
||||
degraded/unhealthy/fault policy explicite
|
||||
```
|
||||
|
||||
### 6.3 Persistence
|
||||
|
||||
```text
|
||||
new entity + new observation
|
||||
idempotent entity + new source observation
|
||||
idempotent observation
|
||||
content conflict terminal
|
||||
aucun backend physique dans Worker
|
||||
```
|
||||
|
||||
### 6.4 Continuité
|
||||
|
||||
```text
|
||||
run frontier borné
|
||||
reconnect != replay
|
||||
transaction replay from_slot
|
||||
block replay from_slot
|
||||
redundant-source repair
|
||||
HTTP block repair
|
||||
hydration repair
|
||||
unresolved gap reste visible
|
||||
aucun historical caller parameter
|
||||
```
|
||||
|
||||
### 6.5 Observabilité
|
||||
|
||||
```text
|
||||
WorkerSnapshot commun
|
||||
RawTransactionIngestSnapshot concret
|
||||
latest-value indépendamment des lecteurs
|
||||
source health/counters/gaps/frontiers sûrs
|
||||
aucun payload/signature/URL/secret
|
||||
```
|
||||
|
||||
## 7. Matrice de types de preuve
|
||||
|
||||
| Preuve | Déterministe | Réseau externe | Secret/tier | Gate release |
|
||||
|:------------------------------|:------------:|:--------------:|:---------------:|:--------------------------------------------------|
|
||||
| common golden RAW v1 | oui | non | non | obligatoire |
|
||||
| cross-source parity fixtures | oui | non | non | obligatoire |
|
||||
| Worker fake multi-source | oui | non | non | obligatoire |
|
||||
| Store façade fake | oui | non | non | obligatoire |
|
||||
| HTTP/WS Solana public smoke | non | oui | non | opt-in, pertinent |
|
||||
| PublicNode Yellowstone | non | oui | possible | opt-in si accès |
|
||||
| OrbitFlare Devnet Yellowstone | non | oui | x-token | opt-in si accès |
|
||||
| Helius transactionSubscribe | non | oui | key/tier | opt-in, non bloquant si tier absent |
|
||||
| QuickNode Yellowstone | non | oui | tier | bloqué, fixture suffit |
|
||||
| Alchemy Yellowstone | non | oui | PAYG/Enterprise | bloqué, fixture suffit |
|
||||
| PostgreSQL Store proof | non | local/externe | URI dédiée | opt-in gate technique si environnement disponible |
|
||||
|
||||
## 8. Commands de gate cible
|
||||
|
||||
À exécuter dès que Rust est modifié puis au gate technique final :
|
||||
|
||||
```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 --workspace --all-targets --all-features
|
||||
cargo tree -p ksp-raw-transaction-lib --edges normal
|
||||
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
|
||||
```
|
||||
|
||||
Ne jamais remplacer un gate non exécuté par un ancien log stable.
|
||||
|
||||
## 9. Non-claims `pre.001`
|
||||
|
||||
À ce stade il n’est **pas** affirmé que :
|
||||
|
||||
```text
|
||||
Yellowstone full produit déjà des bytes RAW v1 identiques à HTTP
|
||||
Helius full produit déjà des bytes RAW v1 identiques à HTTP
|
||||
PublicNode/OrbitFlare replay est disponible à une profondeur donnée
|
||||
Alchemy a une profondeur replay stable
|
||||
une source WS reconnectée est lossless
|
||||
une source EARLY est implémentée
|
||||
le Worker concret existe déjà
|
||||
la common crate existe déjà
|
||||
un test Cargo de pre.001 a été exécuté localement
|
||||
```
|
||||
|
||||
Ces points deviennent des gates ou restent explicitement bloqués.
|
||||
|
||||
## 10. Trajectoire de validation
|
||||
|
||||
```text
|
||||
pre.002 common golden + dependency firewall
|
||||
pre.003 Backfill migration parity
|
||||
pre.004 observed block
|
||||
pre.005 WS/Helius parity
|
||||
pre.006 Yellowstone parity
|
||||
pre.007 Worker runtime foundation
|
||||
pre.008 Yellowstone live/replay
|
||||
pre.009 WS/HTTP live
|
||||
pre.010 multi-source Store/hardening
|
||||
pre.011 gap repair
|
||||
pre.012 Config/profiles + provider smokes
|
||||
pre.013 EARLY ou consolidation
|
||||
pre.014 final technical/live gate
|
||||
pre.015 final docs reconciliation
|
||||
pre.016 publication preparation
|
||||
rel.001 stable publication
|
||||
```
|
||||
Reference in New Issue
Block a user