silent_payments_receive/

scanner.rs

//! Block-level transaction scanner for Silent Payments.
//!
//! [`BlockScanner`] wraps bdk-sp's receive primitives with type-safe
//! `silent-payments-core` newtypes and explicit error handling.
//!
//! # Usage
//!
//! ```no_run
//! # use silent_payments_receive::{BlockScanner, LabelManager};
//! # use silent_payments_core::keys::{ScanSecretKey, SpendSecretKey, SpendPublicKey};
//! # use bitcoin::secp256k1::Secp256k1;
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # let secp = Secp256k1::new();
//! # let scan_secret = ScanSecretKey::from_slice(&[0x01; 32])?;
//! # let spend_secret = SpendSecretKey::from_slice(&[0x02; 32])?;
//! # let spend_pubkey = spend_secret.public_key(&secp);
//! # let labels = LabelManager::new();
//! let scanner = BlockScanner::new(scan_secret, spend_pubkey, labels);
//! // for tx in block.txdata {
//! //     let detected = scanner.scan_transaction(&tx, &prevouts, &secp)?;
//! //     for output in detected {
//! //         let spend_key = output.derive_spend_key(&spend_secret, &secp)?;
//! //         // sign with spend_key, then erase it
//! //     }
//! // }
//! # Ok(())
//! # }
//! ```

use bitcoin::secp256k1::Secp256k1;
use bitcoin::{Transaction, TxOut};

use crate::detected::DetectedOutput;
use crate::error::ReceiveError;
use crate::label::LabelManager;
use silent_payments_core::keys::{ScanSecretKey, SpendPublicKey};

/// Scans transactions for Silent Payment outputs addressed to the receiver.
///
/// Holds the receiver's scan secret key, spend public key, and optional
/// labels. For each transaction, computes the ECDH shared secret and
/// checks P2TR outputs for matches.
///
/// Non-SP transactions (no P2TR outputs, no eligible inputs) return an
/// empty `Vec` without error -- the receiver simply skips them.
pub struct BlockScanner {
    scan_secret: ScanSecretKey,
    spend_pubkey: SpendPublicKey,
    labels: LabelManager,
}

impl BlockScanner {
    /// Create a new scanner for the given receiver keys and labels.
    pub fn new(
        scan_secret: ScanSecretKey,
        spend_pubkey: SpendPublicKey,
        labels: LabelManager,
    ) -> Self {
        Self {
            scan_secret,
            spend_pubkey,
            labels,
        }
    }

    /// Scan a single transaction for SP payments addressed to this receiver.
    ///
    /// Returns detected outputs with their tweaks and optional label indices.
    /// Returns an empty `Vec` for non-SP transactions (no P2TR outputs or
    /// no eligible inputs). This is not an error -- receivers scan all
    /// transactions and skip non-matching ones.
    ///
    /// # Arguments
    ///
    /// * `tx` -- The transaction to scan.
    /// * `prevouts` -- Previous outputs for each input (same order as `tx.input`).
    /// * `secp` -- Secp256k1 context for EC operations.
    ///
    /// # Errors
    ///
    /// Returns [`ReceiveError::Scanning`] if bdk-sp's output scanning fails
    /// (should not happen with well-formed transactions).
    pub fn scan_transaction(
        &self,
        tx: &Transaction,
        prevouts: &[TxOut],
        secp: &Secp256k1<bitcoin::secp256k1::All>,
    ) -> Result<Vec<DetectedOutput>, ReceiveError> {
        // Quick check: skip transactions without P2TR outputs
        let has_p2tr = tx.output.iter().any(|out| out.script_pubkey.is_p2tr());
        if !has_p2tr {
            return Ok(Vec::new());
        }

        // Step 1: Compute tweak data (A_sum * input_hash)
        // If no eligible inputs, return empty -- not an error for receivers
        let tweak_data = match bdk_sp::receive::compute_tweak_data(tx, prevouts) {
            Ok(td) => td,
            Err(_) => return Ok(Vec::new()),
        };

        // Step 2: ECDH shared secret: b_scan * tweak_data
        let ecdh_shared_secret =
            bdk_sp::compute_shared_secret(self.scan_secret.as_inner(), &tweak_data);

        // Step 3: Convert labels to BTreeMap for bdk-sp
        let labels_btree = self.labels.to_btree();

        // Step 4: Scan outputs for matches
        let sp_outs = bdk_sp::receive::scan_txouts(
            *self.spend_pubkey.as_inner(),
            &labels_btree,
            tx,
            ecdh_shared_secret,
        )
        .map_err(|e| ReceiveError::Scanning(e.to_string()))?;

        // Step 5: Convert SpOut -> DetectedOutput
        let detected = sp_outs
            .into_iter()
            .map(|sp_out| {
                DetectedOutput::new(
                    sp_out.outpoint,
                    sp_out.amount,
                    sp_out.script_pubkey,
                    sp_out.tweak,
                    sp_out.label,
                )
            })
            .collect();

        // SEC-01: ecdh_shared_secret is a PublicKey (not secret material)
        // tweak_data is a PublicKey (not secret material)
        // The intermediate secrets (t_k) are contained in bdk-sp's scan_txouts
        // and erased when it returns.
        let _ = secp; // Used by caller for derive_spend_key, not needed here

        Ok(detected)
    }

    /// Access the scan secret key (for testing/debugging).
    pub fn scan_secret(&self) -> &ScanSecretKey {
        &self.scan_secret
    }

    /// Access the spend public key (for testing/debugging).
    pub fn spend_pubkey(&self) -> &SpendPublicKey {
        &self.spend_pubkey
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use bitcoin::secp256k1::{Secp256k1, SecretKey};
    use bitcoin::{Amount, OutPoint, ScriptBuf, Sequence, Transaction, TxIn, TxOut, Witness};
    use silent_payments_core::keys::{ScanSecretKey, SpendSecretKey};

    const SCAN_SK_BYTES: [u8; 32] = [
        0xea, 0xdc, 0x78, 0x16, 0x5f, 0xf1, 0xf8, 0xea, 0x94, 0xad, 0x7c, 0xfd, 0xc5, 0x49, 0x90,
        0x73, 0x8a, 0x4c, 0x53, 0xf6, 0xe0, 0x50, 0x7b, 0x42, 0x15, 0x42, 0x01, 0xb8, 0xe5, 0xdf,
        0xf3, 0xb1,
    ];

    const SPEND_SK_BYTES: [u8; 32] = [
        0x93, 0xf5, 0xed, 0x90, 0x7a, 0xd5, 0xb2, 0xbd, 0xbb, 0xdc, 0xb5, 0xd9, 0x11, 0x6e, 0xbc,
        0x0a, 0x4e, 0x1f, 0x92, 0xf9, 0x10, 0xd5, 0x26, 0x02, 0x37, 0xfa, 0x45, 0xa9, 0x40, 0x8a,
        0xad, 0x16,
    ];

    fn test_scanner() -> BlockScanner {
        let secp = Secp256k1::new();
        let scan_sk = ScanSecretKey::from_slice(&SCAN_SK_BYTES).unwrap();
        let spend_sk = SpendSecretKey::from_slice(&SPEND_SK_BYTES).unwrap();
        let spend_pk = spend_sk.public_key(&secp);
        BlockScanner::new(scan_sk, spend_pk, LabelManager::new())
    }

    #[test]
    fn test_no_p2tr_outputs_returns_empty() {
        let secp = Secp256k1::new();
        let scanner = test_scanner();

        // Create a tx with only a P2WPKH output (not P2TR)
        let tx = Transaction {
            version: bitcoin::transaction::Version::TWO,
            lock_time: bitcoin::absolute::LockTime::ZERO,
            input: vec![TxIn {
                previous_output: OutPoint::null(),
                script_sig: ScriptBuf::new(),
                sequence: Sequence::MAX,
                witness: Witness::new(),
            }],
            output: vec![TxOut {
                value: Amount::from_sat(50_000),
                // P2WPKH script (not P2TR)
                script_pubkey: ScriptBuf::from_hex("001453d9c40342ee880e766522c3e2b854d37f2b3cbf")
                    .unwrap(),
            }],
        };

        let prevouts = vec![TxOut {
            value: Amount::from_sat(100_000),
            script_pubkey: ScriptBuf::from_hex("001453d9c40342ee880e766522c3e2b854d37f2b3cbf")
                .unwrap(),
        }];

        let result = scanner.scan_transaction(&tx, &prevouts, &secp).unwrap();
        assert!(result.is_empty(), "non-P2TR tx should return empty vec");
    }

    #[test]
    fn test_no_eligible_inputs_returns_empty() {
        let secp = Secp256k1::new();
        let scanner = test_scanner();

        // P2TR output but no valid input (null input with no witness/script)
        let dummy_sk = SecretKey::from_slice(&[0x42; 32]).unwrap();
        let (xonly, _) = dummy_sk.public_key(&secp).x_only_public_key();
        let tweaked = bitcoin::key::TweakedPublicKey::dangerous_assume_tweaked(xonly);
        let p2tr_script = ScriptBuf::new_p2tr_tweaked(tweaked);

        let tx = Transaction {
            version: bitcoin::transaction::Version::TWO,
            lock_time: bitcoin::absolute::LockTime::ZERO,
            input: vec![TxIn {
                previous_output: OutPoint::null(),
                script_sig: ScriptBuf::new(),
                sequence: Sequence::MAX,
                witness: Witness::new(),
            }],
            output: vec![TxOut {
                value: Amount::from_sat(50_000),
                script_pubkey: p2tr_script,
            }],
        };

        // Prevout with a script type that won't extract a pubkey
        let prevouts = vec![TxOut {
            value: Amount::from_sat(100_000),
            // P2WSH script -- not eligible for SP
            script_pubkey: ScriptBuf::from_hex(
                "0020000000000000000000000000000000000000000000000000000000000000dead",
            )
            .unwrap(),
        }];

        let result = scanner.scan_transaction(&tx, &prevouts, &secp).unwrap();
        assert!(
            result.is_empty(),
            "tx with no eligible inputs should return empty vec"
        );
    }

    #[test]
    fn accessors_return_correct_references() {
        let scanner = test_scanner();
        // Just verify the accessors don't panic
        let _scan = scanner.scan_secret();
        let _spend = scanner.spend_pubkey();
    }
}