v0.3.10-pre.008

crates/ksp-raw-transaction-lib/USAGE.md

@@ -0,0 +1,153 @@
+<!-- file: crates/ksp-raw-transaction-lib/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de ksp-raw-transaction-lib
+
+Cette page décrit la façade publique durable de `ksp-raw-transaction-lib`. Les consumers utilisent uniquement les exports du crate-root.
+
+## Parser une signature transactionnelle
+
+Lorsqu'une source fournit une signature Base58 textuelle, la convertir avec le parser commun plutôt que de dupliquer le décodage :
+
+```rust
+fn parse_signature(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransactionSignature> {
+    return ksp_raw_transaction_lib::parse_raw_transaction_signature(value);
+}
+```
+
+Le résultat contient exactement 64 bytes canoniques. Les entrées vides, hors bornes, Base58 invalides ou de longueur décodée incorrecte sont rejetées sans recopier la valeur hostile dans l'erreur.
+
+Lorsqu'un wire Base64 complet contient déjà son tableau de signatures, utiliser :
+
+```rust
+fn embedded_signature(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransactionSignature> {
+    return ksp_raw_transaction_lib::extract_raw_transaction_signature_from_binary_base64(value);
+}
+```
+
+## Construire et sérialiser un wire Solana source-neutral
+
+Le producer peut projeter son DTO Transport/protobuf vers les types `RawSolana*`, puis utiliser le sérialiseur commun. Exemple V1 minimal :
+
+```rust
+fn serialize_v1() -> ksp_core_lib::Result<std::string::String> {
+    let message = ksp_raw_transaction_lib::RawSolanaTransactionMessage::new(
+        ksp_raw_transaction_lib::RawSolanaMessageVersion::V1,
+        ksp_raw_transaction_lib::RawSolanaMessageHeader::new(1, 0, 0),
+        vec![[1_u8; 32]],
+        [2_u8; 32],
+        vec![ksp_raw_transaction_lib::RawSolanaCompiledInstruction::new(0, vec![0], vec![3])],
+        vec![],
+        std::option::Option::Some(ksp_raw_transaction_lib::RawSolanaTransactionConfig::default()),
+    );
+    let wire = ksp_raw_transaction_lib::RawSolanaTransactionWire::new(vec![[4_u8; 64]], message);
+    return ksp_raw_transaction_lib::serialize_solana_transaction_wire_base64(&wire);
+}
+```
+
+Pour Legacy ou V0, choisir `RawSolanaMessageVersion::Legacy` ou `V0` et fournir uniquement les éléments admis par cette version. Le sérialiseur valide les invariants structurels avant de produire les bytes.
+
+`RawSolanaAddressTableLookup` représente les lookups V0. `RawSolanaTransactionConfig` représente la configuration inline V1 ; le cas explicite où toutes ses options valent `None` reste sémantiquement présent.
+
+## Construire le matériau RAW canonique
+
+Une fois le wire transactionnel Base64 et les métadonnées source-neutral disponibles, construire `RawTransactionMaterial`. Les états wire doivent conserver la différence entre champ absent, `null` explicite et valeur :
+
+```rust
+fn material(
+    network: ksp_store_api::RawNetworkId,
+    signature: ksp_store_api::RawTransactionSignature,
+    transaction_base64: std::string::String,
+) -> ksp_raw_transaction_lib::RawTransactionMaterial {
+    return ksp_raw_transaction_lib::RawTransactionMaterial::binary_base64(
+        network,
+        signature,
+        42,
+        std::option::Option::None,
+        transaction_base64,
+        ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
+        ksp_raw_transaction_lib::RawTransactionWireField::Value(ksp_raw_transaction_lib::RawTransactionVersion::Legacy),
+        ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
+    );
+}
+```
+
+Pour une source où la signature doit être extraite du wire lui-même, `RawTransactionMaterial::binary_base64_with_embedded_signature` évite un second parser producer-owned.
+
+## Canonicaliser vers RawTransaction
+
+La canonicalisation est déterministe pour un même matériau complet :
+
+```rust
+fn canonicalize(
+    material: ksp_raw_transaction_lib::RawTransactionMaterial,
+) -> ksp_core_lib::Result<ksp_store_api::RawTransaction> {
+    return ksp_raw_transaction_lib::canonicalize_raw_transaction(material);
+}
+```
+
+La crate :
+
+- canonicalise les sous-arbres JSON significatifs ;
+- conserve les états omission / `null` / valeur ;
+- construit le payload au format KSP RAW Transaction ;
+- calcule son SHA-256 ;
+- applique les bornes communes avant construction du modèle Store.
+
+Elle ne persiste pas la transaction et ne choisit aucune politique de retry, endpoint ou source.
+
+## Associer l'observation du producer
+
+Le producer construit sa provenance avec les types Store API, puis assemble l'entité et l'observation :
+
+```rust
+fn acquisition(
+    transaction: ksp_store_api::RawTransaction,
+) -> ksp_core_lib::Result<ksp_raw_transaction_lib::RawTransactionAcquisition> {
+    let provider = match ksp_store_api::RawProvenanceCode::new("example") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let protocol = match ksp_store_api::RawProvenanceCode::new("solana.http") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let method = match ksp_store_api::RawProvenanceCode::new("get_transaction") {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let received_at = match ksp_store_api::RawTimestamp::from_unix_millis(1_700_000_000_000) {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let provenance = ksp_store_api::RawAcquisitionProvenance::new(
+        provider,
+        protocol,
+        method,
+        ksp_store_api::RawAcquisitionOrigin::Live,
+        received_at,
+    );
+    return std::result::Result::Ok(ksp_raw_transaction_lib::assemble_raw_transaction_acquisition(
+        transaction,
+        ksp_store_api::RawObservationKey::new([7_u8; 32]),
+        provenance,
+    ));
+}
+```
+
+La clé d'observation doit être déterministe selon la politique du producer. Plusieurs sources peuvent produire des observations différentes pour la même identité canonique `(network, signature)`.
+
+## Persister depuis un Job ou un Worker
+
+La common crate ne dépend pas du Store runtime. Le lifecycle host concret récupère les deux parties puis appelle la façade Store appropriée :
+
+```rust
+let (transaction, observation) = acquisition.into_parts();
+// Le Job/Worker concret transmet ensuite transaction + observation à ksp-store-lib.
+```
+
+Ne pas introduire `ksp-store-lib`, Transport, Config, Job ou Worker dans `ksp-raw-transaction-lib` pour simplifier cet appel. La direction de dépendance reste du producer vers la common RAW, puis du producer vers le Store runtime.
+
+## Frontière avec STRUCTURAL
+
+Ne pas utiliser cette crate pour décoder des Programs ou pour produire directement des unités STRUCTURAL. Son résultat reste D1 RAW. La décomposition `RAW -> STRUCTURAL` appartient à une couche ultérieure et réutilise le RAW durable comme input.