feat: add script_to_address and transaction_get_output_script FFI helpers

Adds two general-purpose FFI functions so downstream Swift consumers
can decode output addresses on demand without requiring redundant
fields in OutputDetail / FFIOutputDetail:

- script_to_address(script_bytes, script_len, network) -> char*
  Wraps Address::from_script(). Returns a heap-allocated address
  string (freed via existing address_free) or null for non-standard
  scripts (OP_RETURN, bare multisig, etc.).

- transaction_get_output_script(tx_bytes, tx_len, output_index,
    script_out, script_len_out, value_out) -> bool
  Deserializes raw tx bytes and extracts the script_pubkey + value
  at the given output index. Caller frees script bytes via
  transaction_output_script_free.

This approach (per review feedback) keeps OutputDetail and
FFIOutputDetail as { index, role } with no type divergence, while
giving Swift the tools to resolve addresses from tx_data + index.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: llbartekll

key-wallet-ffi/FFI_API.md

@@ -4,7 +4,7 @@ This document provides a comprehensive reference for all FFI (Foreign Function I
 
 **Auto-generated**: This documentation is automatically generated from the source code. Do not edit manually.
 
-**Total Functions**: 260
+**Total Functions**: 263
 
 ## Table of Contents
 
@@ -256,7 +256,7 @@ Functions: 109
 
 ### Address Management
 
-Functions: 10
+Functions: 11
 
 | Function | Description | Module |
 |----------|-------------|--------|
@@ -270,10 +270,11 @@ Functions: 10
 | `address_pool_get_addresses_in_range` | Get a range of addresses from the pool  Returns an array of FFIAddressInfo... | address_pool |
 | `address_to_pubkey_hash` | Extract public key hash from P2PKH address  # Safety - `address` must be a... | transaction |
 | `address_validate` | Validate an address  # Safety  - `address` must be a valid null-terminated C... | address |
+| `script_to_address` | Convert a script_pubkey to a human-readable address string | address |
 
 ### Transaction Management
 
-Functions: 14
+Functions: 16
 
 | Function | Description | Module |
 |----------|-------------|--------|
@@ -285,8 +286,10 @@ Functions: 14
 | `transaction_create` | Create a new empty transaction  # Returns - Pointer to FFITransaction on... | transaction |
 | `transaction_deserialize` | Deserialize a transaction  # Safety - `data` must be a valid pointer to... | transaction |
 | `transaction_destroy` | Destroy a transaction  # Safety - `tx` must be a valid pointer to an... | transaction |
+| `transaction_get_output` | Extract output script_pubkey bytes and value at a given index from raw... | transaction |
 | `transaction_get_txid` | Get the transaction ID  # Safety - `tx` must be a valid pointer to an... | transaction |
 | `transaction_get_txid_from_bytes` | Get transaction ID from raw transaction bytes  # Safety - `tx_bytes` must be... | transaction |
+| `transaction_output_free` | Free script bytes returned by `transaction_get_output` | transaction |
 | `transaction_serialize` | Serialize a transaction  # Safety - `tx` must be a valid pointer to an... | transaction |
 | `transaction_sighash` | Calculate signature hash for an input  # Safety - `tx` must be a valid... | transaction |
 | `transaction_sign_input` | Sign a transaction input  # Safety - `tx` must be a valid pointer to an... | transaction |
@@ -3567,6 +3570,22 @@ Validate an address  # Safety  - `address` must be a valid null-terminated C str
 
 ---
 
+#### `script_to_address`
+
+```c
+script_to_address(script_bytes: *const u8, script_len: usize, network: FFINetwork,) -> *mut c_char
+```
+
+**Description:**
+Convert a script_pubkey to a human-readable address string.  Returns a heap-allocated C string that the caller must free with `address_free`, or null if the script cannot be decoded (e.g. OP_RETURN, bare multisig).  # Safety  - `script_bytes` must be a valid pointer to `script_len` bytes - `script_len` must be the exact length of the script
+
+**Safety:**
+- `script_bytes` must be a valid pointer to `script_len` bytes - `script_len` must be the exact length of the script
+
+**Module:** `address`
+
+---
+
 ### Transaction Management - Detailed
 
 #### `transaction_add_input`
@@ -3694,6 +3713,22 @@ Destroy a transaction  # Safety - `tx` must be a valid pointer to an FFITransact
 
 ---
 
+#### `transaction_get_output`
+
+```c
+transaction_get_output(tx_bytes: *const u8, tx_len: usize, output_index: u32, script_out: *mut *mut u8, script_len_out: *mut usize, value_out: *mut u64,) -> bool
+```
+
+**Description:**
+Extract output script_pubkey bytes and value at a given index from raw consensus-serialized transaction bytes.  Returns false if tx parsing fails or index is out of bounds. On success, `script_out` receives a heap-allocated byte array that the caller must free with `transaction_output_free`, `script_len_out` receives its length, and `value_out` receives the output value in satoshis.  # Safety  - `tx_bytes` must be a valid pointer to `tx_len` bytes - `script_out`, `script_len_out`, `value_out` must be valid non-null pointers
+
+**Safety:**
+- `tx_bytes` must be a valid pointer to `tx_len` bytes - `script_out`, `script_len_out`, `value_out` must be valid non-null pointers
+
+**Module:** `transaction`
+
+---
+
 #### `transaction_get_txid`
 
 ```c
@@ -3726,6 +3761,22 @@ Get transaction ID from raw transaction bytes  # Safety - `tx_bytes` must be a v
 
 ---
 
+#### `transaction_output_free`
+
+```c
+transaction_output_free(script: *mut u8, len: usize) -> ()
+```
+
+**Description:**
+Free script bytes returned by `transaction_get_output`.  # Safety  - `script` must be a pointer returned by `transaction_get_output` - `len` must be the length returned alongside it - Must only be called once per allocation
+
+**Safety:**
+- `script` must be a pointer returned by `transaction_get_output` - `len` must be the length returned alongside it - Must only be called once per allocation
+
+**Module:** `transaction`
+
+---
+
 #### `transaction_serialize`
 
 ```c

key-wallet-ffi/src/address.rs

@@ -113,6 +113,38 @@ pub unsafe extern "C" fn address_validate(
     }
 }
 
+/// Convert a script_pubkey to a human-readable address string.
+///
+/// Returns a heap-allocated C string that the caller must free with `address_free`,
+/// or null if the script cannot be decoded (e.g. OP_RETURN, bare multisig).
+///
+/// # Safety
+///
+/// - `script_bytes` must be a valid pointer to `script_len` bytes
+/// - `script_len` must be the exact length of the script
+#[no_mangle]
+pub unsafe extern "C" fn script_to_address(
+    script_bytes: *const u8,
+    script_len: usize,
+    network: FFINetwork,
+) -> *mut c_char {
+    if script_bytes.is_null() || script_len == 0 {
+        return std::ptr::null_mut();
+    }
+
+    let script_slice = std::slice::from_raw_parts(script_bytes, script_len);
+    let script = dashcore::ScriptBuf::from(script_slice.to_vec());
+    let network_rust: key_wallet::Network = network.into();
+
+    match key_wallet::Address::from_script(&script, network_rust) {
+        Ok(addr) => match CString::new(addr.to_string()) {
+            Ok(cstr) => cstr.into_raw(),
+            Err(_) => std::ptr::null_mut(),
+        },
+        Err(_) => std::ptr::null_mut(),
+    }
+}
+
 /// Get address type
 ///
 /// Returns:

key-wallet-ffi/src/transaction.rs

@@ -497,6 +497,74 @@ pub unsafe extern "C" fn transaction_bytes_free(tx_bytes: *mut u8) {
     }
 }
 
+// MARK: - Transaction Output Introspection
+
+/// Extract output script_pubkey bytes and value at a given index from raw
+/// consensus-serialized transaction bytes.
+///
+/// Returns false if tx parsing fails or index is out of bounds.
+/// On success, `script_out` receives a heap-allocated byte array that the
+/// caller must free with `transaction_output_free`, `script_len_out`
+/// receives its length, and `value_out` receives the output value in satoshis.
+///
+/// # Safety
+///
+/// - `tx_bytes` must be a valid pointer to `tx_len` bytes
+/// - `script_out`, `script_len_out`, `value_out` must be valid non-null pointers
+#[no_mangle]
+pub unsafe extern "C" fn transaction_get_output(
+    tx_bytes: *const u8,
+    tx_len: usize,
+    output_index: u32,
+    script_out: *mut *mut u8,
+    script_len_out: *mut usize,
+    value_out: *mut u64,
+) -> bool {
+    if tx_bytes.is_null() || script_out.is_null() || script_len_out.is_null() || value_out.is_null()
+    {
+        return false;
+    }
+
+    // Initialize out-params to safe defaults so callers never read stale
+    // values on early-return (false) paths.
+    *script_out = std::ptr::null_mut();
+    *script_len_out = 0;
+    *value_out = 0;
+
+    let tx_slice = slice::from_raw_parts(tx_bytes, tx_len);
+    let tx: Transaction = match consensus::deserialize(tx_slice) {
+        Ok(tx) => tx,
+        Err(_) => return false,
+    };
+
+    let output = match tx.output.get(output_index as usize) {
+        Some(o) => o,
+        None => return false,
+    };
+
+    let script_bytes = output.script_pubkey.as_bytes();
+    let mut boxed = script_bytes.to_vec().into_boxed_slice();
+    *script_len_out = boxed.len();
+    *script_out = boxed.as_mut_ptr();
+    std::mem::forget(boxed);
+    *value_out = output.value;
+    true
+}
+
+/// Free script bytes returned by `transaction_get_output`.
+///
+/// # Safety
+///
+/// - `script` must be a pointer returned by `transaction_get_output`
+/// - `len` must be the length returned alongside it
+/// - Must only be called once per allocation
+#[no_mangle]
+pub unsafe extern "C" fn transaction_output_free(script: *mut u8, len: usize) {
+    if !script.is_null() && len > 0 {
+        let _ = Vec::from_raw_parts(script, len, len);
+    }
+}
+
 // MARK: - Transaction Creation
 
 /// Create a new empty transaction