silent_payments_core/

input.rs

//! Transaction input classification and public key extraction for BIP 352.
//!
//! Wraps `bdk_sp::tag_txin` and `bdk_sp::receive::extract_pubkey` with
//! type-safe error handling. Ineligible inputs ALWAYS produce an explicit
//! [`InputError`] -- they are never silently filtered (SEC-03).
//!
//! # Input types
//!
//! BIP 352 recognizes four eligible input types:
//! - **P2TR** -- Taproot key-path spend (excludes NUMS internal key)
//! - **P2WPKH** -- Native SegWit v0
//! - **P2SH-P2WPKH** -- Nested SegWit (P2WPKH inside P2SH)
//! - **P2PKH** -- Legacy pay-to-pubkey-hash
//!
//! Everything else (SegWit v2+, P2SH multisig, P2PK, NUMS-point P2TR
//! script-path spends) is ineligible and produces [`InputError::IneligibleInput`].

use bitcoin::secp256k1::PublicKey;
use bitcoin::{ScriptBuf, TxIn, TxOut};

use crate::error::InputError;

/// The type of a transaction input eligible for Silent Payments.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[allow(non_camel_case_types)]
pub enum SpInputType {
    /// Taproot key-path spend (P2TR).
    P2TR,
    /// Native SegWit v0 (P2WPKH).
    P2WPKH,
    /// Nested SegWit (P2SH wrapping P2WPKH).
    P2SH_P2WPKH,
    /// Legacy pay-to-pubkey-hash (P2PKH).
    P2PKH,
}

impl std::fmt::Display for SpInputType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::P2TR => f.write_str("P2TR"),
            Self::P2WPKH => f.write_str("P2WPKH"),
            Self::P2SH_P2WPKH => f.write_str("P2SH-P2WPKH"),
            Self::P2PKH => f.write_str("P2PKH"),
        }
    }
}

/// A classified transaction input with its extracted public key.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ClassifiedInput {
    /// The BIP 352 input type.
    pub input_type: SpInputType,
    /// The public key extracted from the input (used for ECDH).
    pub public_key: PublicKey,
}

/// An input that was skipped during batch classification, with the reason.
#[derive(Debug, Clone)]
pub struct SkippedInput {
    /// Zero-based index of the input in the transaction.
    pub index: usize,
    /// The error describing why the input was skipped.
    pub error: InputError,
}

/// The result of batch input classification.
#[derive(Debug)]
pub struct ClassificationResult {
    /// Inputs that were successfully classified as eligible.
    pub eligible: Vec<ClassifiedInput>,
    /// Inputs that were skipped with explicit reasons (SEC-03).
    pub skipped: Vec<SkippedInput>,
}

/// Map `bdk_sp::SpInputs` to our [`SpInputType`].
fn map_input_type(sp: bdk_sp::SpInputs) -> SpInputType {
    match sp {
        bdk_sp::SpInputs::Tr => SpInputType::P2TR,
        bdk_sp::SpInputs::Wpkh => SpInputType::P2WPKH,
        bdk_sp::SpInputs::ShWpkh => SpInputType::P2SH_P2WPKH,
        bdk_sp::SpInputs::Pkh => SpInputType::P2PKH,
    }
}

/// Infer a human-readable script type description from the previous output script.
///
/// Used to provide meaningful error messages for ineligible inputs.
fn infer_script_type(script_pubkey: &ScriptBuf) -> String {
    if script_pubkey.is_p2tr() {
        "P2TR (script-path/NUMS)".to_string()
    } else if script_pubkey.is_p2wpkh() {
        "P2WPKH".to_string()
    } else if script_pubkey.is_p2sh() {
        "P2SH".to_string()
    } else if script_pubkey.is_p2pkh() {
        "P2PKH".to_string()
    } else if script_pubkey.is_p2wsh() {
        "P2WSH".to_string()
    } else if script_pubkey.is_witness_program() {
        "SegWit (unknown version)".to_string()
    } else {
        "unknown".to_string()
    }
}

/// Classify a single transaction input and extract its public key.
///
/// Delegates to `bdk_sp::tag_txin` for classification and
/// `bdk_sp::receive::extract_pubkey` for key extraction. If the input
/// is ineligible (e.g., SegWit v2+, NUMS-point P2TR, multisig),
/// returns [`InputError::IneligibleInput`] with a descriptive reason.
///
/// # Arguments
///
/// * `txin` - The transaction input to classify.
/// * `prev_script_pubkey` - The scriptPubKey of the previous output being spent.
///
/// # Errors
///
/// - [`InputError::IneligibleInput`] -- input type not supported by BIP 352.
/// - [`InputError::PubKeyExtraction`] -- eligible type but key extraction failed.
pub fn classify_input(
    txin: &TxIn,
    prev_script_pubkey: &ScriptBuf,
) -> Result<ClassifiedInput, InputError> {
    // Step 1: Tag the input type via bdk-sp.
    let sp_tag = bdk_sp::tag_txin(txin, prev_script_pubkey).ok_or_else(|| {
        let script_type = infer_script_type(prev_script_pubkey);
        InputError::IneligibleInput {
            script_type,
            reason: "input type not eligible for BIP 352 Silent Payments".to_string(),
        }
    })?;

    let input_type = map_input_type(sp_tag);

    // Step 2: Extract the public key via bdk-sp.
    // extract_pubkey takes ownership of TxIn, so we clone.
    let (_, pubkey) = bdk_sp::receive::extract_pubkey(txin.clone(), prev_script_pubkey)
        .ok_or_else(|| InputError::PubKeyExtraction {
            input_type: input_type.to_string(),
            reason: "bdk-sp could not extract a valid compressed public key".to_string(),
        })?;

    Ok(ClassifiedInput {
        input_type,
        public_key: pubkey,
    })
}

/// Classify all inputs in a transaction, reporting both eligible and skipped inputs.
///
/// SEC-03: Nothing is silently filtered. Every ineligible input appears in
/// `ClassificationResult::skipped` with an explicit reason.
///
/// # Arguments
///
/// * `inputs` - The transaction inputs.
/// * `prev_outputs` - The previous outputs being spent (must match inputs 1:1).
///
/// # Errors
///
/// Returns [`InputError::NoEligibleInputs`] if zero inputs are classified
/// as eligible (and none produced extraction errors).
pub fn collect_eligible_inputs(
    inputs: &[TxIn],
    prev_outputs: &[TxOut],
) -> Result<ClassificationResult, InputError> {
    let mut eligible = Vec::new();
    let mut skipped = Vec::new();

    for (index, (txin, prev_out)) in inputs.iter().zip(prev_outputs.iter()).enumerate() {
        match classify_input(txin, &prev_out.script_pubkey) {
            Ok(classified) => eligible.push(classified),
            Err(err) => skipped.push(SkippedInput { index, error: err }),
        }
    }

    if eligible.is_empty() {
        return Err(InputError::NoEligibleInputs);
    }

    Ok(ClassificationResult { eligible, skipped })
}