8.4 KiB
Delta 0.3.10-pre.002 — fondation RAW Transaction commune
Base requise
0.3.10-pre.001
workspace.package.version = 0.3.10-pre.1
Le gate opérateur communiqué pour pre.001 passe cargo fmt --all, les audits Rust/Markdown, cargo check --workspace et Clippy workspace --all-targets --all-features -- -D warnings. Le message ne fournit pas de cargo test supplémentaire ; aucun test non communiqué n’est déclaré exécuté.
Objectif
Créer uniquement ksp-raw-transaction-lib comme lower-layer commune de canonicalisation RAW Transaction v1 : matériau source-neutral, parser de signature, canonical JSON, SHA-256 et assemblage transaction/observation. Aucun Worker et aucune migration du Backfill dans cette tranche.
Version
Cette tranche est une prerelease non-fix :
workspace.package.version = 0.3.10-pre.2
Le Cargo.toml racine passe du header 490 au header 491 et ajoute crates/ksp-raw-transaction-lib aux membres du workspace.
Correction normative du plan pre.001
Le sizing pre.001 avait retenu ksp-store-lib(default-features=false) pour la common crate. La relecture au moment de matérialiser la frontière révèle une règle plus spécifique :
DEP-PIPE-006
Le pipeline raw ingestion peut dépendre des modèles homogènes de
ksp-onchain-transport-lib et de ksp-store-api, mais pas de ksp-store-lib.
La dépendance est donc corrigée vers ksp-store-api. Cette correction ne change aucun invariant RAW ; elle retire au contraire la façade/runtime Store de la lower-layer réutilisable.
Dépendances exactes
ksp-raw-transaction-lib
-> ksp-core-lib
-> ksp-store-api
-> serde_json
-> sha2
Absents de la crate :
ksp-store-lib
ksp-store-postgres-lib
ksp-onchain-transport-lib
ksp-config-lib
ksp-job-api
ksp-job-backfill-lib
ksp-worker-api
Tokio / futures
provider SDK
Surface publique
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
Tous les modules restent privés et les éléments consommables sont réexportés au crate-root.
Contrat matérialisé
Signature
Le parser reçoit un texte Base58 borné de 64..=88 octets et n’accepte que les représentations décodant exactement vers 64 octets. Aucun Solana SDK ou codec externe n’est ajouté.
Les erreurs ne recopient jamais la signature hostile ; seules les longueurs numériques sûres peuvent apparaître en contexte.
Matériau source-neutral
RawTransactionMaterial::binary_base64(...) reçoit :
network
signature canonique 64 bytes
slot u64
block_time Option<i64>
transaction data binaire Base64 déjà obtenu de la source
meta omitted/null/value
version omitted/null/value (legacy ou u8)
transactionIndex omitted/null/value u32
Aucun type Transport/provider n’entre dans la common crate. La représentation interne peut être étendue ultérieurement pour Yellowstone uniquement lorsqu’une parité RAW v1 sera démontrée.
Canonicalisation RAW v1
La sortie conserve exactement :
ordre top-level : transaction -> meta -> version -> transactionIndex
transaction = [data, "base64"]
tri récursif des clés d’objets JSON
ordre des arrays conservé
omitted != null != value
block_time hors payload, converti en RawTimestamp
SHA-256 sur les bytes canoniques exacts
format id/version gelés
Golden verrouillé :
bytes = {"transaction":["AQID","base64"],"meta":{"a":{"x":null,"y":true},"z":1},"version":"legacy","transactionIndex":7}
byte_len = 112
sha256 = 220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3
Observation producer-owned
assemble_raw_transaction_acquisition(...) reçoit la RawObservationKey déjà choisie par le producteur et construit l’observation sur la référence exacte de la transaction. Aucun domaine de clé Backfill ou Worker n’est introduit dans common.
Tests ajoutés
Tests unitaires :
signature exacte 64 bytes
signature bornes / caractère Base58 invalide / overflow / longueur décodée non canonique
golden bytes + hash RAW v1
omitted/null/value
golden JSON récursif / arrays / escaping / nombres
block_time négatif / overflow / maximum
borne payload
Debug material/wire redacted
assemblage acquisition + observation key producer-owned
Tests d’intégration :
dependency boundary exacte
absence runtime/Transport/Config/Job/Worker/backend
consommation crate-root externe
assemblage avec modèles Store API
inventaire modules production
absence de contrat Worker/Backfill/Transport dans la façade
error codes stables
signature hostile non recopiée
Fichiers ajoutés
crates/ksp-raw-transaction-lib/Cargo.toml
crates/ksp-raw-transaction-lib/src/acquisition.rs
crates/ksp-raw-transaction-lib/src/canonical.rs
crates/ksp-raw-transaction-lib/src/error.rs
crates/ksp-raw-transaction-lib/src/lib.rs
crates/ksp-raw-transaction-lib/src/signature.rs
crates/ksp-raw-transaction-lib/unit_tests/acquisition.rs
crates/ksp-raw-transaction-lib/unit_tests/canonical.rs
crates/ksp-raw-transaction-lib/unit_tests/signature.rs
crates/ksp-raw-transaction-lib/tests/dependency_boundary.rs
crates/ksp-raw-transaction-lib/tests/public_api.rs
crates/ksp-raw-transaction-lib/tests/release_completeness.rs
crates/ksp-raw-transaction-lib/tests/security_hardening.rs
deltas/0.3.10/pre.002.md
Fichiers modifiés
Cargo.toml
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.
Documentation volontairement différée
README.md et USAGE.md de la nouvelle crate ne sont pas finalisés dans cette tranche de fondation. La réconciliation version-neutral reste réservée au couloir documentaire pre.015, après parité cross-source, migration Backfill et freeze fonctionnelle.
Validations exécutées 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))
contrôle TOML : 20 membres workspace, nouvelle crate présente
contrôle manifest common : dépendances exactes core/store-api/serde_json/sha2, aucune feature/dev/build dependency
L’environnement d’assemblage ne fournit ni cargo, ni rustc, ni rustfmt. Aucun gate Cargo de pre.002 n’est donc déclaré PASS localement.
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
Validations non exécutées localement
cargo fmt --all
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
smokes live : non pertinents pour cette tranche purement déterministe
Décisions prises
RAW v1 reste unique et inchangé
ksp-store-api remplace ksp-store-lib dans common pour conformité DEP-PIPE-006
RawObservationKey reste producer-owned
aucun type Transport dans common
aucun async/runtime dans common
aucune migration Backfill avant pre.003
aucun Worker avant pre.007 selon le plan recalibré
Questions ouvertes
Aucune question ne bloque pre.003 après un gate opérateur vert. Les projections structurées WS/Helius/Yellowstone restent volontairement différées jusqu’aux tranches de parité prévues ; elles ne doivent pas modifier RAW v1 par anticipation.