refactor: change Material.metadata from string to Uint8Array

metadata is binary data (SCALE-encoded runtime metadata) but was stored as hex strings, requiring constant encoding/decoding. using Uint8Array eliminates this overhead and improves type safety.

changes:
- TypeScript: Material.metadata is now Uint8Array instead of string
- Rust: Material.metadata is now Vec<u8> instead of String
- MaterialJs WASM wrapper: accepts &[u8] instead of &str
- removed all decode_metadata functions (no longer needed)
- test fixtures: added hexToUint8Array() and getWestendMetadata() helpers
- added hex_or_bytes serde deserializer for backwards compatibility with JSON tests

benefits:
- eliminates hex encode/decode overhead at every use
- reduces memory usage (hex strings are 2x the size of raw bytes)
- improves type safety (Uint8Array clearly indicates binary data)
- matches wasm-utxo conventions (Uint8Array everywhere)

BTC-3085

Author: lcovar

packages/wasm-dot/js/types.ts

@@ -24,8 +24,8 @@ export interface Material {
   specVersion: number;
   /** Transaction format version */
   txVersion: number;
-  /** Runtime metadata bytes (hex encoded) - required for encoding calls */
-  metadata: string;
+  /** Runtime metadata bytes - required for encoding calls */
+  metadata: Uint8Array;
 }
 
 /**

packages/wasm-dot/src/address.rs

@@ -77,7 +77,7 @@ pub fn decode_ss58(address: &str) -> Result<(Vec<u8>, u16), WasmDotError> {
 /// Validate an SS58 address
 pub fn validate_address(address: &str, expected_prefix: Option<u16>) -> bool {
     match decode_ss58(address) {
-        Ok((_, prefix)) => expected_prefix.map_or(true, |expected| prefix == expected),
+        Ok((_, prefix)) => expected_prefix.is_none_or(|expected| prefix == expected),
         Err(_) => false,
     }
 }

packages/wasm-dot/src/builder/calls.rs

@@ -265,7 +265,7 @@ fn account_id(address: &str) -> Result<Value<()>, WasmDotError> {
             v.len()
         ))
     })?;
-    Ok(Value::from_bytes(&bytes))
+    Ok(Value::from_bytes(bytes))
 }
 
 #[cfg(test)]

packages/wasm-dot/src/builder/mod.rs

@@ -46,12 +46,9 @@ pub fn build_transaction(
     Ok(tx)
 }
 
-/// Decode metadata from hex string
-fn decode_metadata(metadata_hex: &str) -> Result<subxt_core::metadata::Metadata, WasmDotError> {
-    let bytes = hex::decode(metadata_hex.trim_start_matches("0x"))
-        .map_err(|e| WasmDotError::InvalidInput(format!("Invalid metadata hex: {}", e)))?;
-
-    subxt_core::metadata::decode_from(&bytes[..])
+/// Decode metadata from raw bytes
+fn decode_metadata(metadata_bytes: &[u8]) -> Result<subxt_core::metadata::Metadata, WasmDotError> {
+    subxt_core::metadata::decode_from(metadata_bytes)
         .map_err(|e| WasmDotError::InvalidInput(format!("Failed to decode metadata: {}", e)))
 }
 
@@ -60,7 +57,7 @@ fn compute_era(validity: &Validity) -> Era {
     if validity.max_duration == 0 {
         Era::Immortal
     } else {
-        let period = validity.max_duration.next_power_of_two().min(65536).max(4);
+        let period = validity.max_duration.next_power_of_two().clamp(4, 65536);
         let phase = validity.first_valid % period;
         Era::Mortal { period, phase }
     }

packages/wasm-dot/src/builder/types.rs

@@ -205,7 +205,7 @@ mod tests {
                 "specName": "polkadot",
                 "specVersion": 9150,
                 "txVersion": 9,
-                "metadata": "0x00"
+                "metadata": [0]
             },
             "validity": {
                 "firstValid": 1000,

packages/wasm-dot/src/parser.rs

@@ -99,12 +99,9 @@ pub fn parse_transaction(
     })
 }
 
-/// Decode metadata from hex string (same pattern as builder)
-fn decode_metadata(metadata_hex: &str) -> Result<subxt_core::metadata::Metadata, WasmDotError> {
-    let bytes = hex::decode(metadata_hex.trim_start_matches("0x"))
-        .map_err(|e| WasmDotError::InvalidInput(format!("Invalid metadata hex: {}", e)))?;
-
-    subxt_core::metadata::decode_from(&bytes[..])
+/// Decode metadata from raw bytes
+fn decode_metadata(metadata_bytes: &[u8]) -> Result<subxt_core::metadata::Metadata, WasmDotError> {
+    subxt_core::metadata::decode_from(metadata_bytes)
         .map_err(|e| WasmDotError::InvalidInput(format!("Failed to decode metadata: {}", e)))
 }
 

packages/wasm-dot/src/transaction.rs

@@ -399,12 +399,9 @@ impl Transaction {
 // Helper functions
 // =============================================================================
 
-/// Decode metadata from hex string
-fn decode_metadata(metadata_hex: &str) -> Result<Metadata, WasmDotError> {
-    let bytes = hex::decode(metadata_hex.trim_start_matches("0x"))
-        .map_err(|e| WasmDotError::InvalidInput(format!("Invalid metadata hex: {}", e)))?;
-
-    subxt_core::metadata::decode_from(&bytes[..])
+/// Decode metadata from raw bytes
+fn decode_metadata(metadata_bytes: &[u8]) -> Result<Metadata, WasmDotError> {
+    subxt_core::metadata::decode_from(metadata_bytes)
         .map_err(|e| WasmDotError::InvalidInput(format!("Failed to decode metadata: {}", e)))
 }
 
@@ -438,22 +435,22 @@ pub(crate) fn encode_era(era: &Era) -> Vec<u8> {
     }
 }
 
+/// Parsed extrinsic data: (is_signed, sender, signature, era, nonce, tip, call_data)
+type ParsedExtrinsic = (
+    bool,
+    Option<[u8; 32]>,
+    Option<[u8; 64]>,
+    Era,
+    u32,
+    u128,
+    Vec<u8>,
+);
+
 /// Parse a raw extrinsic
 fn parse_extrinsic(
     bytes: &[u8],
     metadata: Option<&Metadata>,
-) -> Result<
-    (
-        bool,
-        Option<[u8; 32]>,
-        Option<[u8; 64]>,
-        Era,
-        u32,
-        u128,
-        Vec<u8>,
-    ),
-    WasmDotError,
-> {
+) -> Result<ParsedExtrinsic, WasmDotError> {
     use parity_scale_codec::{Compact, Decode};
 
     let mut cursor = 0;

packages/wasm-dot/src/types.rs

@@ -2,6 +2,60 @@
 
 use serde::{Deserialize, Serialize};
 
+/// Helper module for deserializing binary data from hex string or byte array
+mod hex_or_bytes {
+    use serde::Deserializer;
+
+    pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        use core::fmt;
+        use serde::de::{self, Visitor};
+
+        struct BytesVisitor;
+
+        impl<'de> Visitor<'de> for BytesVisitor {
+            type Value = Vec<u8>;
+
+            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+                formatter.write_str("a hex string or byte array")
+            }
+
+            // Handle hex strings
+            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
+            where
+                E: de::Error,
+            {
+                let s = v.strip_prefix("0x").unwrap_or(v);
+                hex::decode(s).map_err(de::Error::custom)
+            }
+
+            // Handle byte arrays (from serde_json or direct Vec<u8>)
+            fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
+            where
+                A: de::SeqAccess<'de>,
+            {
+                let mut bytes = Vec::new();
+                while let Some(byte) = seq.next_element()? {
+                    bytes.push(byte);
+                }
+                Ok(bytes)
+            }
+
+            // Handle byte slices (from serde_wasm_bindgen with Uint8Array)
+            fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
+            where
+                E: de::Error,
+            {
+                Ok(v.to_vec())
+            }
+        }
+
+        deserializer.deserialize_any(BytesVisitor)
+    }
+}
+
 /// Chain material metadata required for transaction encoding/decoding
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -16,9 +70,10 @@ pub struct Material {
     pub spec_version: u32,
     /// Transaction format version
     pub tx_version: u32,
-    /// Runtime metadata bytes (hex encoded)
+    /// Runtime metadata bytes
     /// Required for encoding calls - handles runtime upgrades automatically
-    pub metadata: String,
+    #[serde(deserialize_with = "hex_or_bytes::deserialize")]
+    pub metadata: Vec<u8>,
 }
 
 /// Validity window for mortal transactions

packages/wasm-dot/src/wasm/transaction.rs

@@ -224,7 +224,7 @@ impl MaterialJs {
         spec_name: &str,
         spec_version: u32,
         tx_version: u32,
-        metadata: &str,
+        metadata: &[u8],
     ) -> MaterialJs {
         MaterialJs {
             inner: Material {
@@ -233,7 +233,7 @@ impl MaterialJs {
                 spec_name: spec_name.to_string(),
                 spec_version,
                 tx_version,
-                metadata: metadata.to_string(),
+                metadata: metadata.to_vec(),
             },
         }
     }

packages/wasm-dot/test/builder.ts

@@ -1,6 +1,6 @@
 import * as assert from "assert";
 import { buildTransaction, type TransactionIntent, type BuildContext } from "../js/index.js";
-import { westendMetadataRpc } from "./resources/westend.js";
+import { getWestendMetadata } from "./resources/westend.js";
 
 /** Convert Uint8Array to hex string (no 0x prefix) */
 function toHex(bytes: Uint8Array): string {
@@ -21,7 +21,7 @@ describe("buildTransaction", () => {
     specName: "westend",
     specVersion: 9420,
     txVersion: 16,
-    metadata: westendMetadataRpc,
+    metadata: getWestendMetadata(),
   };
 
   // Reference block (use genesis for testing)