v0.3.12-pre.004

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

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-raw-transaction-lib/README.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # ksp-raw-transaction-lib
 
@@ -26,6 +26,7 @@ La canonicalisation produit un `ksp_store_api::RawTransaction` avec payload KSP
 ### 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.
 

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

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-raw-transaction-lib/USAGE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Utilisation de ksp-raw-transaction-lib
 
@@ -17,6 +17,16 @@ fn parse_signature(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransa
 
 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 consumer possède déjà les 64 bytes canoniques et doit appeler une API textuelle Solana, utiliser l'encodeur commun plutôt que d'implémenter Base58 localement :
+
+```rust
+fn format_signature(value: &ksp_store_api::RawTransactionSignature) -> std::string::String {
+    return ksp_raw_transaction_lib::format_raw_transaction_signature(value);
+}
+```
+
+Le texte produit respecte les bornes publiques de signature et effectue un round-trip exact avec `parse_raw_transaction_signature`.
+
 Lorsqu'un wire Base64 complet contient déjà son tableau de signatures, utiliser :
 
 ```rust

crates/ksp-raw-transaction-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/src/lib.rs
-// version: 3
+// version: 4
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -7,7 +7,7 @@
 
 //! Source-neutral canonicalization of complete Solana transactions into KSP RAW transaction v1.
 //!
-//! This lower layer owns the frozen RAW transaction format, textual signature parsing, canonical
+//! This lower layer owns the frozen RAW transaction format, textual signature parsing/formatting, canonical
 //! JSON construction, content hashing and assembly of one canonical transaction with one
 //! producer-owned observation. It owns no Transport, Config, Job, Worker, async runtime or Store
 //! backend behavior.
@@ -46,6 +46,8 @@ pub use self::signature::MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES;
 pub use self::signature::MIN_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES;
 /// Extracts the first canonical 64-byte Solana signature from one complete Base64 transaction wire.
 pub use self::signature::extract_raw_transaction_signature_from_binary_base64;
+/// Encodes one canonical 64-byte Solana transaction signature as bounded Base58 text.
+pub use self::signature::format_raw_transaction_signature;
 /// Parses one bounded Base58 Solana transaction signature to exactly 64 canonical bytes.
 pub use self::signature::parse_raw_transaction_signature;
 /// One source-neutral v0 address-table lookup.

crates/ksp-raw-transaction-lib/src/signature.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/src/signature.rs
-// version: 3
+// version: 4
 
 use base64::Engine; // rust-rules: trait-import
 
@@ -8,6 +8,35 @@ pub const MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES: usize = 88;
 /// Minimum UTF-8 byte length admitted for one textual Base58 Solana transaction signature.
 pub const MIN_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES: usize = 64;
 
+/// Encodes one canonical 64-byte Solana transaction signature as bounded Base58 text.
+#[must_use]
+pub fn format_raw_transaction_signature(signature: &ksp_store_api::RawTransactionSignature) -> std::string::String {
+    const ALPHABET: &[u8; 58] = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    let bytes = signature.as_bytes();
+    let leading_zeroes = bytes.iter().take_while(|byte| return **byte == 0).count();
+    let mut digits = std::vec::Vec::with_capacity(crate::MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES);
+    for byte in bytes {
+        let mut carry = u32::from(*byte);
+        for digit in &mut digits {
+            let expanded = (u32::from(*digit) * 256) + carry;
+            *digit = (expanded % 58) as u8;
+            carry = expanded / 58;
+        }
+        while carry != 0 {
+            digits.push((carry % 58) as u8);
+            carry /= 58;
+        }
+    }
+    let mut output = std::string::String::with_capacity(leading_zeroes + digits.len());
+    for _ in 0..leading_zeroes {
+        output.push('1');
+    }
+    for digit in digits.iter().rev() {
+        output.push(char::from(ALPHABET[usize::from(*digit)]));
+    }
+    return output;
+}
+
 /// Parses one bounded Base58 Solana transaction signature to exactly 64 canonical bytes.
 pub fn parse_raw_transaction_signature(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransactionSignature> {
     let text = value.as_bytes();

crates/ksp-raw-transaction-lib/tests/public_api.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/tests/public_api.rs
-// version: 4
+// version: 5
 
 //! Integration canaries for the public common RAW Transaction crate-root surface.
 
@@ -120,3 +120,16 @@ fn pre_006_source_neutral_wire_contract_is_available_from_crate_root() {
     }
     return;
 }
+
+#[test]
+fn pre_004_signature_formatter_is_consumable_from_crate_root() {
+    let signature = ksp_store_api::RawTransactionSignature::new([0_u8; 64]);
+    let text = ksp_raw_transaction_lib::format_raw_transaction_signature(&signature);
+    assert_eq!(text, "1".repeat(64));
+    let parsed = ksp_raw_transaction_lib::parse_raw_transaction_signature(text.as_str());
+    assert!(parsed.is_ok());
+    if let std::result::Result::Ok(parsed) = parsed {
+        assert_eq!(parsed, signature);
+    }
+    return;
+}

crates/ksp-raw-transaction-lib/unit_tests/signature.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-raw-transaction-lib/unit_tests/signature.rs
-// version: 3
+// version: 4
 
 use base64::Engine; // rust-rules: trait-import
 
@@ -79,3 +79,19 @@ fn pre_006_embedded_signature_extracts_terminal_v1_signature_and_rejects_trailin
         assert!(crate::extract_raw_transaction_signature_from_binary_base64(trailing.as_str()).is_err());
     }
 }
+
+#[test]
+fn pre_004_base58_formatter_round_trips_canonical_signatures() {
+    for bytes in [[0_u8; 64], [1_u8; 64], [0xAB_u8; 64]] {
+        let signature = ksp_store_api::RawTransactionSignature::new(bytes);
+        let text = crate::format_raw_transaction_signature(&signature);
+        assert!((crate::MIN_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES..=crate::MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES).contains(&text.len()));
+        let parsed = crate::parse_raw_transaction_signature(text.as_str());
+        assert!(parsed.is_ok());
+        if let std::result::Result::Ok(parsed) = parsed {
+            assert_eq!(parsed, signature);
+        }
+    }
+    assert_eq!(crate::format_raw_transaction_signature(&ksp_store_api::RawTransactionSignature::new([0_u8; 64])), "1".repeat(64));
+    return;
+}