khadhroony-solana-project/docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md

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 :

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

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 :

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

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

cargo : indisponible dans l’environnement d’assemblage

Par conséquent :

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.

2.4 Gate opérateur après livraison de pre.001

Le 6 septembre 2026, l’opérateur a exécuté sur workspace.package.version = 0.3.10-pre.1 :

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

Résultats communiqués :

General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (339 table(s), 753 file(s))
cargo check --workspace : terminé sans erreur
cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé sans erreur

Ce gate opérateur ferme les contrôles demandés pour passer à pre.002. Aucun cargo test de pre.001 n’a été fourni dans ce message et il n’est pas inventé.

3. Preuves de conception fermées en pre.001

3.1 Common RAW

Décisions prouvées par inspection du code courant :

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é
`DEP-PIPE-006` impose les modèles `ksp-store-api` à la lower-layer RAW réutilisable ; la décision `ksp-store-lib` de `pre.001` est corrigée en `pre.002`
Backfill conversion mélange actuellement canonicalisation commune et metadata Job-owned

Canari RAW v1 recalculé :

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 :

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 :

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 :

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 :

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 :

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 :

same fixture identity
same canonical bytes
same SHA-256
same slot
same block_time semantics
same version/index semantics

Familles à prouver séparément :

HTTP getTransaction
HTTP getBlock transaction
WS blockSubscribe transaction
Helius transactionSubscribe full
Yellowstone transaction
Yellowstone block transaction
Transaction V1

En cas d’échec de parité :

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

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

N sources simultanées
bounded channels seulement
slow source isolation
queue saturation observable
aucun drop silencieux
degraded/unhealthy/fault policy explicite

6.3 Persistence

new entity + new observation
idempotent entity + new source observation
idempotent observation
content conflict terminal
aucun backend physique dans Worker

6.4 Continuité

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é

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 :

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 :

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

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

11. Gate pre.002 — common RAW foundation

État : matérialisé ; gate Cargo opérateur requis.

11.1 Crate et frontière

crate = ksp-raw-transaction-lib
workspace.package.version = 0.3.10-pre.2
runtime async = aucun
Transport / Config / Job / Worker = absents
backend Store = absent

La dépendance exacte retenue après contrôle normatif est :

ksp-raw-transaction-lib
    -> ksp-core-lib
    -> ksp-store-api
    -> serde_json
    -> sha2

Cette correction remplace la proposition ksp-store-lib(default-features=false) de pre.001 car DEP-PIPE-006 est plus spécifique : le pipeline RAW partagé peut dépendre de ksp-store-api, pas de ksp-store-lib.

11.2 Surface matérialisée

RAW_TRANSACTION_FORMAT_ID = ksp.solana.raw_transaction
RAW_TRANSACTION_FORMAT_VERSION = 1
MIN_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES = 64
MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES = 88

RawTransactionMaterial
RawTransactionWireField<T>
RawTransactionVersion
RawTransactionAcquisition

parse_raw_transaction_signature(...)
canonicalize_raw_transaction(...)
assemble_raw_transaction_acquisition(...)

ERROR_CODE_RAW_TRANSACTION_CANONICALIZATION_INVALID
ERROR_CODE_RAW_TRANSACTION_MATERIAL_INVALID
ERROR_CODE_RAW_TRANSACTION_SIGNATURE_INVALID

RawObservationKey reste fournie par le producteur. La common crate ne contient aucun domaine de clé Backfill/Worker.

11.3 Preuves déterministes ajoutées

signature Base58 : bornes texte + alphabet + overflow + exactement 64 octets
RAW v1 golden : 112 bytes exacts
RAW v1 SHA-256 : 220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3
meta/version/index : omitted != null != value
JSON : clés objet triées récursivement, arrays conservés, strings échappées, nombres conservés
block_time : négatif/overflow/max Store
payload : borne MAX_RAW_PAYLOAD_BYTES
Debug/error : aucune signature, transaction body ou meta hostile recopiée
acquisition : observation key producer-owned et référence exactement égale à la transaction
public API : consommation par crate-root
firewall : absence Store runtime/Transport/Config/Job/Worker/backend

11.4 Validation locale d’assemblage

Exécuté dans l’environnement d’assemblage :

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 (339 table(s), 754 file(s))

manifest TOML : 20 membres workspace, ksp-raw-transaction-lib présent
manifest common : 4 dépendances exactes, aucune feature/dev/build dependency

cargo, rustc et rustfmt ne sont pas présents dans cet environnement. Les gates Cargo de la nouvelle crate restent donc NON EXÉCUTÉS LOCALEMENT.

11.5 Gate opérateur demandé

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-raw-transaction-lib
cargo tree -p ksp-raw-transaction-lib --edges normal
cargo tree -p ksp-raw-transaction-lib -e features

pre.003 ne doit migrer le Backfill qu’après ce gate vert.