blvm_consensus/

bip119.rs

//! BIP119: OP_CHECKTEMPLATEVERIFY (CTV)
//!
//! Implementation of BIP119 CheckTemplateVerify opcode for Bitcoin transaction templates.
//!
//! **Feature Flag**: This module is only available when the `ctv` feature is enabled.
//! CTV is a proposed soft fork and should be used with caution until activated on mainnet.
//!
//! Mathematical specifications from Orange Paper Section 5.4.6.
//!
//! ## Overview
//!
//! OP_CHECKTEMPLATEVERIFY (CTV) enables transaction templates that commit to specific
//! transaction structures. This enables:
//! - Congestion control (transaction batching)
//! - Vault contracts (time-locked withdrawals)
//! - Payment channels (state updates)
//! - Advanced smart contracts
//!
//! ## Security Considerations
//!
//! - **Constant-time comparison**: Template hash comparison uses constant-time operations
//!   to prevent timing attacks
//! - **Input validation**: All inputs are validated before processing to prevent
//!   out-of-bounds access and integer overflow
//! - **Cryptographic security**: Uses SHA256 (double-hashed) for template hash calculation
//! - **Feature flag**: CTV is behind a feature flag to prevent accidental use before activation
//!
//! ## Performance Optimizations
//!
//! - **Pre-allocated buffers**: Template preimage buffer is pre-allocated with estimated size
//!   to reduce allocations
//! - **Efficient serialization**: Uses direct byte operations for serialization
//! - **SIMD hash comparison**: Uses SIMD-optimized hash comparison when available (production builds)
//!
//! ## Template Hash Calculation
//!
//! Template hash = SHA256(SHA256(template_preimage))
//!
//! Template preimage includes:
//! - Transaction version (4 bytes, little-endian)
//! - Input count (varint)
//! - For each input: prevout hash, prevout index, sequence (NO scriptSig)
//! - Output count (varint)
//! - For each output: value, script length, script bytes
//! - Locktime (4 bytes, little-endian)
//! - Input index (4 bytes, little-endian) - which input is being verified
//!
//! ## Opcode Behavior
//!
//! OP_CHECKTEMPLATEVERIFY - OP_NOP4 (BIP-119):
//! - Consumes: [template_hash] (32 bytes from stack)
//! - Produces: Nothing (fails if template doesn't match)
//! - Requires: Full transaction context (tx, input_index)
//!
//! ## Usage
//!
//! ```rust,ignore
//! // Enable CTV feature in Cargo.toml:
//! // [features]
//! // ctv = []
//!
//! use blvm_consensus::bip119::calculate_template_hash;
//!
//! let tx = Transaction { /* ... */ };
//! let template_hash = calculate_template_hash(&tx, 0)?;
//! ```

use crate::error::{ConsensusError, Result};
use crate::serialization::varint::encode_varint;
use crate::types::*;
use blvm_spec_lock::spec_locked;
use sha2::{Digest, Sha256};

/// Calculate transaction template hash for BIP119 CTV
///
/// Template hash is SHA256(SHA256(template_preimage)) where template_preimage
/// includes version, inputs, outputs, locktime, and input index.
///
/// Mathematical specification: Orange Paper Section 5.4.6
///
/// **TemplateHash**: 𝒯𝒳 × ℕ → ℍ
///
/// For transaction tx and input index i:
/// - TemplateHash(tx, i) = SHA256(SHA256(TemplatePreimage(tx, i)))
///
/// # Arguments
///
/// * `tx` - The transaction to calculate template hash for
/// * `input_index` - The index of the input being verified (0-based)
///
/// # Returns
///
/// The 32-byte template hash, or an error if calculation fails
///
/// # Errors
///
/// Returns `ConsensusError` if:
/// - Input index is out of bounds
/// - Transaction has no inputs
/// - Transaction has no outputs
/// - Serialization fails
#[spec_locked("5.4.6")]
pub fn calculate_template_hash(tx: &Transaction, input_index: usize) -> Result<Hash> {
    // Validate inputs
    if input_index >= tx.inputs.len() {
        return Err(ConsensusError::TransactionValidation(
            format!(
                "Input index {} out of bounds (transaction has {} inputs)",
                input_index,
                tx.inputs.len()
            )
            .into(),
        ));
    }

    if tx.inputs.is_empty() {
        return Err(ConsensusError::TransactionValidation(
            "Transaction must have at least one input for CTV".into(),
        ));
    }

    if tx.outputs.is_empty() {
        return Err(ConsensusError::TransactionValidation(
            "Transaction must have at least one output for CTV".into(),
        ));
    }

    // Build template preimage with pre-allocated capacity for performance
    // Estimate: 4 (version) + 9 (varint max) + inputs*(32+4+4) + 9 (varint max) + outputs*(8+9+script) + 4 (locktime) + 4 (index)
    let estimated_size = 4
        + 9
        + (tx.inputs.len() * 40)
        + 9
        + (tx
            .outputs
            .iter()
            .map(|o| 8 + 9 + o.script_pubkey.len())
            .sum::<usize>())
        + 4
        + 4;
    let mut preimage = Vec::with_capacity(estimated_size);

    // 1. Transaction version (4 bytes, little-endian)
    preimage.extend_from_slice(&(tx.version as u32).to_le_bytes());

    // 2. Input count (varint)
    preimage.extend_from_slice(&encode_varint(tx.inputs.len() as u64));

    // 3. For each input: prevout hash, prevout index, sequence (NO scriptSig)
    for input in &tx.inputs {
        // Previous output hash (32 bytes)
        preimage.extend_from_slice(&input.prevout.hash);
        // Previous output index (4 bytes, little-endian)
        preimage.extend_from_slice(&input.prevout.index.to_le_bytes());
        // Sequence (4 bytes, little-endian)
        preimage.extend_from_slice(&(input.sequence as u32).to_le_bytes());
        // Note: scriptSig is NOT included in template (key difference from sighash)
    }

    // 4. Output count (varint)
    preimage.extend_from_slice(&encode_varint(tx.outputs.len() as u64));

    // 5. For each output: value, script length, script bytes
    for output in &tx.outputs {
        // Value (8 bytes, little-endian)
        preimage.extend_from_slice(&output.value.to_le_bytes());
        // Script length (varint)
        preimage.extend_from_slice(&encode_varint(output.script_pubkey.len() as u64));
        // Script bytes
        preimage.extend_from_slice(&output.script_pubkey);
    }

    // 6. Locktime (4 bytes, little-endian)
    preimage.extend_from_slice(&(tx.lock_time as u32).to_le_bytes());

    // 7. Input index (4 bytes, little-endian) - which input is being verified
    preimage.extend_from_slice(&(input_index as u32).to_le_bytes());

    // 8. Double SHA256: SHA256(SHA256(preimage))
    // Security: Use SHA256 which is cryptographically secure and constant-time
    let hash1 = Sha256::digest(&preimage);
    let hash2 = Sha256::digest(hash1);

    // Convert to Hash type (32 bytes)
    let mut template_hash = [0u8; 32];
    template_hash.copy_from_slice(&hash2);

    Ok(template_hash)
}

/// Validate template hash for CTV
///
/// Checks if the provided template hash matches the transaction's template hash.
///
/// # Arguments
///
/// * `tx` - The transaction to validate
/// * `input_index` - The index of the input being verified
/// * `expected_hash` - The expected template hash (32 bytes)
///
/// # Returns
///
/// `true` if template hash matches, `false` otherwise
#[spec_locked("5.4.6")]
pub fn validate_template_hash(
    tx: &Transaction,
    input_index: usize,
    expected_hash: &[u8],
) -> Result<bool> {
    // Template hash must be exactly 32 bytes
    if expected_hash.len() != 32 {
        return Ok(false);
    }

    // Calculate actual template hash
    let actual_hash = calculate_template_hash(tx, input_index)?;

    // Compare hashes
    Ok(actual_hash == expected_hash)
}

/// Extract template hash from script
///
/// For CTV scripts, the template hash is typically the last 32 bytes pushed
/// before OP_CHECKTEMPLATEVERIFY (0xb3).
///
/// # Arguments
///
/// * `script` - The script to extract template hash from
///
/// # Returns
///
/// The template hash if found, `None` otherwise
#[spec_locked("5.4.6")]
pub fn extract_template_hash_from_script(script: &[u8]) -> Option<Hash> {
    // Look for OP_CHECKTEMPLATEVERIFY - OP_NOP4
    use crate::opcodes::OP_CHECKTEMPLATEVERIFY;
    if let Some(ctv_pos) = script.iter().rposition(|&b| b == OP_CHECKTEMPLATEVERIFY) {
        // Find the last push operation before CTV
        // Template hash should be pushed as 32 bytes (0x20 push)
        if ctv_pos >= 33 && script[ctv_pos - 33] == 0x20 {
            // Extract 32 bytes before CTV
            let mut hash = [0u8; 32];
            hash.copy_from_slice(&script[ctv_pos - 32..ctv_pos]);
            return Some(hash);
        }
    }
    None
}

/// Check if script uses CTV
///
/// # Arguments
///
/// * `script` - The script to check
///
/// # Returns
///
/// `true` if script contains OP_CHECKTEMPLATEVERIFY (0xba)
#[spec_locked("5.4.6")]
pub fn is_ctv_script(script: &[u8]) -> bool {
    use crate::opcodes::OP_CHECKTEMPLATEVERIFY;
    script.contains(&OP_CHECKTEMPLATEVERIFY) // OP_CHECKTEMPLATEVERIFY (OP_NOP4)
}

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

    #[test]
    fn test_template_hash_basic() {
        // Create a simple transaction
        let tx = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32].into(),
                    index: 0,
                },
                script_sig: vec![0x51], // OP_1 (not included in template)
                sequence: 0xffffffff,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![0x76, 0xa9, 0x14, 0x00, 0x87].into(), // P2PKH
            }]
            .into(),
            lock_time: 0,
        };

        // Calculate template hash
        let hash = calculate_template_hash(&tx, 0).unwrap();

        // Hash should be 32 bytes
        assert_eq!(hash.len(), 32);

        // Hash should be deterministic (same inputs → same output)
        let hash2 = calculate_template_hash(&tx, 0).unwrap();
        assert_eq!(hash, hash2);
    }

    #[test]
    fn test_template_hash_determinism() {
        let tx = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [1; 32].into(),
                    index: 0,
                },
                script_sig: vec![0x52, 0x53], // Different scriptSig
                sequence: 0,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 5000,
                script_pubkey: vec![0x51].into(), // OP_1
            }]
            .into(),
            lock_time: 100,
        };

        // Calculate hash multiple times
        let hash1 = calculate_template_hash(&tx, 0).unwrap();
        let hash2 = calculate_template_hash(&tx, 0).unwrap();
        let hash3 = calculate_template_hash(&tx, 0).unwrap();

        // All should be identical
        assert_eq!(hash1, hash2);
        assert_eq!(hash2, hash3);
    }

    #[test]
    fn test_template_hash_input_index_dependency() {
        let tx = Transaction {
            version: 1,
            inputs: vec![
                TransactionInput {
                    prevout: OutPoint {
                        hash: [1; 32].into(),
                        index: 0,
                    },
                    script_sig: vec![],
                    sequence: 0,
                },
                TransactionInput {
                    prevout: OutPoint {
                        hash: [2; 32],
                        index: 1,
                    },
                    script_sig: vec![],
                    sequence: 0,
                },
            ]
            .into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![].into(),
            }]
            .into(),
            lock_time: 0,
        };

        // Different input indices should produce different hashes
        let hash0 = calculate_template_hash(&tx, 0).unwrap();
        let hash1 = calculate_template_hash(&tx, 1).unwrap();

        assert_ne!(
            hash0, hash1,
            "Different input indices must produce different template hashes"
        );
    }

    #[test]
    fn test_template_hash_script_sig_not_included() {
        // Create two transactions with different scriptSigs but same structure
        let tx1 = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32].into(),
                    index: 0,
                },
                script_sig: vec![0x51], // OP_1
                sequence: 0,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![0x51].into(),
            }]
            .into(),
            lock_time: 0,
        };

        let tx2 = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32].into(),
                    index: 0,
                },
                script_sig: vec![0x52, 0x53], // Different scriptSig
                sequence: 0,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![0x51].into(),
            }]
            .into(),
            lock_time: 0,
        };

        // Template hashes should be identical (scriptSig not included)
        let hash1 = calculate_template_hash(&tx1, 0).unwrap();
        let hash2 = calculate_template_hash(&tx2, 0).unwrap();

        assert_eq!(hash1, hash2, "Template hash should not include scriptSig");
    }

    #[test]
    fn test_template_hash_validation() {
        let tx = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32].into(),
                    index: 0,
                },
                script_sig: vec![],
                sequence: 0,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![].into(),
            }]
            .into(),
            lock_time: 0,
        };

        // Calculate correct template hash
        let correct_hash = calculate_template_hash(&tx, 0).unwrap();

        // Validation should pass with correct hash
        assert!(validate_template_hash(&tx, 0, &correct_hash).unwrap());

        // Validation should fail with wrong hash
        let wrong_hash = [1u8; 32];
        assert!(!validate_template_hash(&tx, 0, &wrong_hash).unwrap());

        // Validation should fail with wrong size
        let wrong_size = vec![0u8; 31];
        assert!(!validate_template_hash(&tx, 0, &wrong_size).unwrap());
    }

    #[test]
    fn test_template_hash_error_cases() {
        // Empty inputs
        let tx_no_inputs = Transaction {
            version: 1,
            inputs: vec![].into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![].into(),
            }]
            .into(),
            lock_time: 0,
        };
        assert!(calculate_template_hash(&tx_no_inputs, 0).is_err());

        // Empty outputs
        let tx_no_outputs = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32].into(),
                    index: 0,
                },
                script_sig: vec![],
                sequence: 0,
            }]
            .into(),
            outputs: vec![].into(),
            lock_time: 0,
        };
        assert!(calculate_template_hash(&tx_no_outputs, 0).is_err());

        // Input index out of bounds
        let tx = Transaction {
            version: 1,
            inputs: vec![TransactionInput {
                prevout: OutPoint {
                    hash: [0; 32].into(),
                    index: 0,
                },
                script_sig: vec![],
                sequence: 0,
            }]
            .into(),
            outputs: vec![TransactionOutput {
                value: 1000,
                script_pubkey: vec![].into(),
            }]
            .into(),
            lock_time: 0,
        };
        assert!(calculate_template_hash(&tx, 1).is_err()); // Index 1, but only 1 input (index 0)
    }

    #[test]
    fn test_is_ctv_script() {
        // Script with CTV: push 32 bytes (0x20) + 32 bytes of hash + OP_CHECKTEMPLATEVERIFY (0xb3)
        let mut script_with_ctv = vec![0x20]; // OP_PUSHDATA1 with length 32
        script_with_ctv.extend_from_slice(&[0x00; 32]); // 32 bytes of hash
        script_with_ctv.push(0xb3); // OP_CHECKTEMPLATEVERIFY (OP_NOP4)
        assert!(is_ctv_script(&script_with_ctv));

        // Script without CTV
        let script_without_ctv = vec![0x51, 0x87]; // OP_1, OP_EQUAL
        assert!(!is_ctv_script(&script_without_ctv));
    }
}