miniscript_core_sys/

lib.rs

//! # miniscript-core-sys
//!
//! FFI bindings to Bitcoin Core's miniscript implementation.
//!
//! This crate provides low-level bindings for cross-verification between
//! Bitcoin Core's C++ miniscript and other implementations like rust-miniscript.
//!
//! ## Example
//!
//! ```rust,no_run
//! use miniscript_core_sys::{Miniscript, Context};
//!
//! let ms = Miniscript::from_str("and_v(v:pk(A),pk(B))", Context::Wsh)
//!     .expect("valid miniscript");
//!
//! assert!(ms.is_valid());
//! println!("Type: {}", ms.get_type().unwrap());
//! println!("String: {}", ms.to_string().unwrap());
//! ```

#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]

// Include the generated bindings
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

use std::ffi::{CStr, CString};
use std::fmt;
use std::ptr;

/// Script context for miniscript parsing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Context {
    /// P2WSH context (SegWit v0)
    Wsh,
    /// Tapscript context (SegWit v1)
    Tapscript,
}

impl From<Context> for MiniscriptContext {
    fn from(ctx: Context) -> Self {
        match ctx {
            Context::Wsh => MiniscriptContext::MINISCRIPT_CONTEXT_WSH,
            Context::Tapscript => MiniscriptContext::MINISCRIPT_CONTEXT_TAPSCRIPT,
        }
    }
}

/// Error type for miniscript operations.
#[derive(Debug)]
pub struct Error {
    message: String,
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl std::error::Error for Error {}

/// A parsed miniscript node.
///
/// This is a safe wrapper around the C++ miniscript implementation.
pub struct Miniscript {
    ptr: *mut MiniscriptNode,
    context: Context,
}

// SAFETY: The underlying C++ object is self-contained and doesn't use thread-local storage.
// The node is immutable after creation, so it's safe to send between threads.
unsafe impl Send for Miniscript {}

// SAFETY: All methods on Miniscript take &self and the underlying object is immutable.
unsafe impl Sync for Miniscript {}

impl Miniscript {
    /// Parse a miniscript from a string.
    ///
    /// # Arguments
    ///
    /// * `input` - The miniscript string (e.g., "and_v(v:pk(A),pk(B))")
    /// * `context` - The script context (WSH or Tapscript)
    ///
    /// # Errors
    ///
    /// Returns an error if parsing fails.
    pub fn from_str(input: &str, context: Context) -> Result<Self, Error> {
        let c_input = CString::new(input).map_err(|_| Error {
            message: "input contains null byte".to_string(),
        })?;

        let mut node_ptr: *mut MiniscriptNode = ptr::null_mut();

        // SAFETY: We're passing valid pointers and the C code handles null checks.
        let result =
            unsafe { miniscript_from_string(c_input.as_ptr(), context.into(), &mut node_ptr) };

        if result.success {
            Ok(Miniscript {
                ptr: node_ptr,
                context,
            })
        } else {
            let message = if !result.error_message.is_null() {
                // SAFETY: error_message is a valid C string if not null
                let msg = unsafe { CStr::from_ptr(result.error_message) }
                    .to_string_lossy()
                    .into_owned();
                unsafe { miniscript_free_string(result.error_message) };
                msg
            } else {
                "unknown error".to_string()
            };
            Err(Error { message })
        }
    }

    /// Convert the miniscript back to a string.
    pub fn to_string(&self) -> Option<String> {
        // SAFETY: self.ptr is valid while self exists
        let c_str = unsafe { miniscript_to_string(self.ptr) };
        if c_str.is_null() {
            return None;
        }

        // SAFETY: c_str is a valid C string
        let result = unsafe { CStr::from_ptr(c_str) }
            .to_string_lossy()
            .into_owned();
        unsafe { miniscript_free_string(c_str) };

        Some(result)
    }

    /// Check if the miniscript is valid (type-checks correctly).
    pub fn is_valid(&self) -> bool {
        // SAFETY: self.ptr is valid while self exists
        unsafe { miniscript_is_valid(self.ptr) }
    }

    /// Check if the miniscript is sane.
    ///
    /// This includes checks for:
    /// - No duplicate keys
    /// - No timelock mixing
    /// - Within resource limits
    pub fn is_sane(&self) -> bool {
        // SAFETY: self.ptr is valid while self exists
        unsafe { miniscript_is_sane(self.ptr) }
    }

    /// Get the type properties of the miniscript.
    ///
    /// Returns a string like "Bdems" where each letter indicates a property.
    pub fn get_type(&self) -> Option<String> {
        // SAFETY: self.ptr is valid while self exists
        let c_str = unsafe { miniscript_get_type(self.ptr) };
        if c_str.is_null() {
            return None;
        }

        // SAFETY: c_str is a valid C string
        let result = unsafe { CStr::from_ptr(c_str) }
            .to_string_lossy()
            .into_owned();
        unsafe { miniscript_free_string(c_str) };

        Some(result)
    }

    /// Get the maximum witness size for satisfying this miniscript.
    pub fn max_satisfaction_size(&self) -> Option<usize> {
        let mut size: usize = 0;
        // SAFETY: self.ptr is valid while self exists
        if unsafe { miniscript_max_satisfaction_size(self.ptr, &mut size) } {
            Some(size)
        } else {
            None
        }
    }

    /// Get the context this miniscript was parsed with.
    pub fn context(&self) -> Context {
        self.context
    }
}

impl Drop for Miniscript {
    fn drop(&mut self) {
        if !self.ptr.is_null() {
            // SAFETY: ptr was allocated by miniscript_from_string
            unsafe { miniscript_node_free(self.ptr) };
        }
    }
}

impl fmt::Debug for Miniscript {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Miniscript")
            .field("context", &self.context)
            .field("string", &self.to_string())
            .field("type", &self.get_type())
            .finish()
    }
}

/// Get the library version string.
pub fn version() -> &'static str {
    // SAFETY: miniscript_version returns a static string
    unsafe {
        CStr::from_ptr(miniscript_version())
            .to_str()
            .unwrap_or("unknown")
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_version() {
        let v = version();
        assert!(!v.is_empty());
        println!("Version: {}", v);
    }

    // These tests require the library to be built with Bitcoin Core
    // They're ignored by default since CI might not have the sources
    #[test]
    #[ignore]
    fn test_parse_simple() {
        let ms = Miniscript::from_str("pk(A)", Context::Wsh).expect("should parse");
        assert!(ms.is_valid());
        assert_eq!(ms.to_string(), Some("pk(A)".to_string()));
    }

    #[test]
    #[ignore]
    fn test_parse_and_v() {
        let ms = Miniscript::from_str("and_v(v:pk(A),pk(B))", Context::Wsh).expect("should parse");
        assert!(ms.is_valid());
    }

    #[test]
    #[ignore]
    fn test_invalid_miniscript() {
        let result = Miniscript::from_str("invalid", Context::Wsh);
        assert!(result.is_err());
    }

    #[test]
    #[ignore]
    fn test_type_properties() {
        let ms = Miniscript::from_str("pk(A)", Context::Wsh).expect("should parse");
        let type_str = ms.get_type().expect("should have type");
        // pk should be type B (base) with various modifiers
        assert!(type_str.contains('B'));
    }
}