La crate transforme un matériau transactionnel complet déjà acquis en représentation RAW canonique KSP, fournit les primitives de parsing de signature et de sérialisation wire Solana nécessaires aux voies qualifiées, puis permet d'associer la transaction canonique à une observation/provenance possédée par le producer.

Elle ne possède aucun Transport, Config, Job, Worker, runtime async, Store runtime ou backend physique.

Responsabilités

La façade crate-root expose quatre familles de contrats.

Canonicalisation RAW Transaction

RawTransactionMaterial ;
RawTransactionWireField<T> pour préserver distinctement omission, null explicite et valeur ;
RawTransactionVersion ;
canonicalize_raw_transaction ;
RAW_TRANSACTION_FORMAT_ID et RAW_TRANSACTION_FORMAT_VERSION.

La canonicalisation produit un ksp_store_api::RawTransaction avec payload KSP déterministe et SHA-256 de contenu. Le producer reste responsable de fournir un matériau source-neutral complet ; la crate n'effectue aucune I/O réseau.

Signature Solana

parse_raw_transaction_signature valide et décode une signature Base58 bornée vers exactement 64 bytes ;
format_raw_transaction_signature encode exactement 64 bytes canoniques vers la forme Base58 bornée correspondante ;
extract_raw_transaction_signature_from_binary_base64 extrait la première signature canonique d'un wire transactionnel Base64 complet ;
les bornes textuelles publiques permettent l'admission avant décodage.

Les diagnostics ne recopient pas la signature hostile.

Wire transactionnel source-neutral

La surface RawSolana* représente et sérialise les messages transactionnels Solana Legacy, V0 et V1 nécessaires à la common RAW :

RawSolanaMessageVersion ;
RawSolanaMessageHeader ;
RawSolanaCompiledInstruction ;
RawSolanaAddressTableLookup ;
RawSolanaTransactionConfig ;
RawSolanaTransactionMessage ;
RawSolanaTransactionWire ;
serialize_solana_transaction_wire et serialize_solana_transaction_wire_base64.

Cette surface est un contrat de wire commun, pas un decoder Program et pas une façade Transport.

Acquisition canonique + observation

assemble_raw_transaction_acquisition associe une transaction canonique à :

une RawObservationKey déterministe possédée par le producer ;
une RawAcquisitionProvenance sûre possédée par le producer.

Le résultat RawTransactionAcquisition contient exactement une entité canonique et une observation liée. Il ne persiste rien lui-même.

Frontières

Transport / fixture / import / producer
              |
              v
      matériau source-neutral
              |
              v
   ksp-raw-transaction-lib
       |              |
       |              +-> exact Solana wire helpers
       v
RawTransaction + RawTransactionObservation
       |
       v
producer runtime -> ksp-store-lib / capability Store appropriée

Interdictions structurelles :

ksp-raw-transaction-lib -X-> ksp-onchain-transport-lib
ksp-raw-transaction-lib -X-> ksp-config-lib
ksp-raw-transaction-lib -X-> ksp-job-api / ksp-job-backfill-lib
ksp-raw-transaction-lib -X-> ksp-worker-api / worker concret
ksp-raw-transaction-lib -X-> ksp-store-lib / backend physique

Le graphe normal reste limité à ksp-core-lib, ksp-store-api, base64, serde_json et sha2.

Relation avec STRUCTURAL

Cette crate appartient à RAW. Elle ne réalise pas la décomposition Store D2 RAW -> STRUCTURAL. La future couche STRUCTURAL consommera le RAW persistant et le décomposera en unités Solana génériques plus fines avant tout décodage Program.

Documentation

USAGE.md — utilisation durable de la façade publique ;
../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md — frontières RAW / STRUCTURAL / DECODED / DOMAIN ;
../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md — qualification des sources RawTransaction.