237 lines
7.1 KiB
Markdown
237 lines
7.1 KiB
Markdown
<!-- file: deltas/0.3.10/pre.003.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.3.10-pre.003` — migration du Backfill vers la common RAW Transaction
|
||
|
||
## Base requise
|
||
|
||
```text
|
||
0.3.10-pre.002-fix.001
|
||
workspace.package.version = 0.3.10-pre.2.fix.1
|
||
```
|
||
|
||
Le gate opérateur communiqué le 2026-09-06 ferme intégralement la base : audits statiques propres, `cargo check --workspace` PASS, Clippy workspace `--all-targets --all-features -- -D warnings` PASS, `cargo test -p ksp-raw-transaction-lib` PASS avec 9 tests unitaires et 8 tests d’intégration, arbres normal/features conformes.
|
||
|
||
## Objectif
|
||
|
||
Migrer uniquement `ksp-job-backfill-lib` vers `ksp-raw-transaction-lib` sans modifier le comportement de campagne : common devient propriétaire du parser Base58, de RAW v1, du hash payload et de l’assemblage transaction/observation ; Backfill conserve Transport, provenance, observation key, Job scope et Store persistence.
|
||
|
||
Aucun Worker, aucune nouvelle source Transport et aucune extension du format RAW ne sont introduits.
|
||
|
||
## Version
|
||
|
||
```text
|
||
workspace.package.version = 0.3.10-pre.3
|
||
```
|
||
|
||
Le header du `Cargo.toml` racine passe de `492` à `493`. Le nombre de membres workspace reste `20`.
|
||
|
||
## Migration de dépendance
|
||
|
||
`ksp-job-backfill-lib` ajoute :
|
||
|
||
```text
|
||
ksp-raw-transaction-lib = { path = "../ksp-raw-transaction-lib" }
|
||
```
|
||
|
||
Le reste de son graphe runtime est conservé. `serde_json` reste nécessaire au type Transport `SolanaWireField<serde_json::Value>`. `sha2` reste nécessaire aux fingerprints et à la `RawObservationKey` Backfill ; il n’est plus utilisé pour le hash du payload RAW.
|
||
|
||
## Chemin RAW après migration
|
||
|
||
```text
|
||
BackfillSignature
|
||
-> parse_raw_transaction_signature
|
||
-> RawTransactionSignature
|
||
|
||
getTransaction observed
|
||
-> adapter SolanaEncodedTransaction/SolanaWireField
|
||
-> RawTransactionMaterial::binary_base64
|
||
-> canonicalize_raw_transaction
|
||
-> RawTransaction
|
||
|
||
Backfill provenance + Backfill RawObservationKey
|
||
-> assemble_raw_transaction_acquisition
|
||
-> BackfillRawAcquisition
|
||
-> Store persistence existante
|
||
```
|
||
|
||
Les erreurs du parser/canonicalizer common sont remappées au boundary Backfill vers :
|
||
|
||
```text
|
||
ERROR_CODE_BACKFILL_RAW_CONVERSION_INVALID
|
||
```
|
||
|
||
Le Job ne change donc pas de domaine d’erreur externe par effet de la migration.
|
||
|
||
## Code privé supprimé du Backfill
|
||
|
||
La migration retire de `conversion.rs` les implémentations locales de :
|
||
|
||
```text
|
||
base58_digit(...)
|
||
algorithme de décodage Base58 64-byte
|
||
convert_block_time(...)
|
||
canonical_payload_bytes(...)
|
||
append_wire_value(...)
|
||
append_canonical_json(...)
|
||
append_json_string(...)
|
||
RawPayload::try_new + SHA-256 du payload
|
||
construction directe RawTransactionObservation
|
||
```
|
||
|
||
`CanonicalTransactionFields` reste un adapter Transport privé ; il ne définit aucun format RAW.
|
||
|
||
## Propriété Backfill conservée
|
||
|
||
Le Backfill continue de posséder :
|
||
|
||
```text
|
||
getTransaction observed / rôle HTTP
|
||
provider gagnant
|
||
endpoint gagnant
|
||
commitment
|
||
job_id
|
||
scope_fingerprint
|
||
RawAcquisitionOrigin::Backfill
|
||
capture_session
|
||
observation contract version = 1
|
||
algorithme RawObservationKey Backfill
|
||
persistence Store
|
||
sémantique Missing
|
||
```
|
||
|
||
La common crate ne reçoit donc aucun vocabulaire de campagne.
|
||
|
||
## Parité déterministe
|
||
|
||
Le golden historique reste inchangé :
|
||
|
||
```text
|
||
format_id = ksp.solana.raw_transaction
|
||
format_version = 1
|
||
bytes = {"transaction":["AQID","base64"],"meta":{"a":{"x":null,"y":true},"z":1},"version":"legacy","transactionIndex":7}
|
||
byte_len = 112
|
||
sha256 = 220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3
|
||
```
|
||
|
||
La provenance historique reste :
|
||
|
||
```text
|
||
provider = publicnode
|
||
protocol = solana.http.json_rpc
|
||
method = getTransaction
|
||
endpoint = devnet-primary
|
||
commitment = finalized
|
||
capture_session = backfill:pre006
|
||
origin = Backfill
|
||
```
|
||
|
||
Le canari d’observation key est désormais exact :
|
||
|
||
```text
|
||
provider = provider
|
||
endpoint = endpoint-a
|
||
key = b8550f0f2165f370de918bd4fb0ec782391afdddb88c57f010743e000b136702
|
||
```
|
||
|
||
## Canaris mis à jour
|
||
|
||
```text
|
||
BackfillSignature délègue au parser common
|
||
bornes Backfill == bornes common
|
||
format id/version Backfill == common
|
||
wire omitted/null reste distinct via common
|
||
non-Base64 reste rejeté avec error code Backfill
|
||
block_time invalide reste terminal avec error code Backfill
|
||
golden bytes/hash/provenance inchangés
|
||
observation key exacte inchangée
|
||
manifest Backfill exige l’edge common
|
||
conversion.rs exige parser + canonicalizer + assembler common
|
||
conversion.rs interdit canonical JSON/Base58/RawPayload privés
|
||
lower-layer common interdit toute dépendance retour vers Job
|
||
```
|
||
|
||
## Fichiers ajoutés
|
||
|
||
```text
|
||
deltas/0.3.10/pre.003.md
|
||
```
|
||
|
||
## Fichiers modifiés
|
||
|
||
```text
|
||
Cargo.toml
|
||
crates/ksp-job-backfill-lib/Cargo.toml
|
||
crates/ksp-job-backfill-lib/README.md
|
||
crates/ksp-job-backfill-lib/src/conversion.rs
|
||
crates/ksp-job-backfill-lib/src/lib.rs
|
||
crates/ksp-job-backfill-lib/src/request.rs
|
||
crates/ksp-job-backfill-lib/tests/dependency_boundary.rs
|
||
crates/ksp-job-backfill-lib/tests/hardening.rs
|
||
crates/ksp-job-backfill-lib/unit_tests/conversion.rs
|
||
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
|
||
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.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
|
||
|
||
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), 756 file(s))
|
||
```
|
||
|
||
L’environnement d’assemblage ne fournit ni `cargo`, ni `rustc`, ni `rustfmt`.
|
||
|
||
## 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-raw-transaction-lib
|
||
cargo test -p ksp-job-backfill-lib
|
||
cargo tree -p ksp-job-backfill-lib --edges normal
|
||
cargo tree -p ksp-job-backfill-lib -e features
|
||
```
|
||
|
||
## Validations non exécutées localement
|
||
|
||
```text
|
||
cargo fmt --all
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||
cargo test -p ksp-raw-transaction-lib
|
||
cargo test -p ksp-job-backfill-lib
|
||
cargo tree -p ksp-job-backfill-lib --edges normal
|
||
cargo tree -p ksp-job-backfill-lib -e features
|
||
smokes live : non pertinents pour cette tranche de migration déterministe
|
||
```
|
||
|
||
## Décisions prises
|
||
|
||
```text
|
||
common possède parser + canonical RAW v1 + payload hash + assembly
|
||
Backfill conserve observation key/provenance/campagne
|
||
les erreurs common sont remappées vers le code Backfill historique
|
||
les constantes publiques RAW du Backfill sont des reexports common
|
||
les bornes publiques de signature Backfill suivent les constantes common
|
||
aucun changement du Store persistence path
|
||
aucun changement de source/acquisition réseau
|
||
aucun Worker avant la tranche planifiée
|
||
```
|
||
|
||
## Questions ouvertes
|
||
|
||
Aucune question ne bloque le gate de `pre.003`. `pre.004` reste strictement dédiée à `get_block_observed` et au matériau HTTP block après validation opérateur complète de cette migration.
|