<!-- file: crates/ksp-raw-transaction-lib/README.md -->
<!-- version: 2 -->

# ksp-raw-transaction-lib

`ksp-raw-transaction-lib` fournit la lower-layer KSP source-neutral commune aux producteurs de `RawTransaction`.

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

```text
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 :

```text
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`](USAGE.md) — utilisation durable de la façade publique ;
- [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — frontières RAW / STRUCTURAL / DECODED / DOMAIN ;
- [`../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`](../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md) — qualification des sources `RawTransaction`.