Release descriptor policy review v0.3

Author: josediegorobles

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "btc-risk-lab"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 authors = ["Jose Robles"]
 description = "A Rust CLI for explainable Bitcoin transaction, PSBT, and script risk reports."

Cargo.toml

@@ -0,0 +1,223 @@
+use std::str::FromStr;
+
+use anyhow::{bail, Context, Result};
+use bitcoin::PublicKey;
+use miniscript::{descriptor::DescriptorType, Descriptor};
+
+use super::{
+    common_limitations, complexity, summary, warning, ArtifactType, DescriptorAnalysis, RiskLevel,
+    RiskReport, ScriptSignals,
+};
+use crate::analyzer::script::{analyze_script_bytes, classify_script};
+
+pub fn analyze_descriptor_input(input: &str) -> Result<RiskReport> {
+    let descriptor = input.trim();
+    if descriptor.is_empty() {
+        bail!("descriptor cannot be empty");
+    }
+
+    let descriptor = Descriptor::<PublicKey>::from_str(descriptor)
+        .context("descriptor input is not a valid public-key output descriptor")?;
+
+    Ok(analyze_descriptor(&descriptor))
+}
+
+fn analyze_descriptor(descriptor: &Descriptor<PublicKey>) -> RiskReport {
+    let descriptor_type = descriptor_type_name(descriptor.desc_type()).to_owned();
+    let script_pubkey = descriptor.script_pubkey();
+    let script_type = classify_script(&script_pubkey);
+    let sanity_check = descriptor.sanity_check().is_ok();
+    let max_satisfaction_weight_wu = descriptor
+        .max_weight_to_satisfy()
+        .ok()
+        .map(|weight| weight.to_wu());
+    let signals = descriptor_signals(descriptor);
+
+    let mut warnings = Vec::new();
+    let missing_data = Vec::new();
+
+    if !sanity_check {
+        warnings.push(warning(
+            "descriptor-sanity-check",
+            RiskLevel::Medium,
+            "Descriptor sanity check failed",
+            "Miniscript parsed the descriptor, but its safety checks did not pass. Review spend paths, malleability, and standardness assumptions before operational use.",
+        ));
+    }
+
+    if signals.multisig || signals.threshold {
+        warnings.push(warning(
+            "threshold-policy",
+            RiskLevel::Low,
+            "Threshold or multisig policy detected",
+            "The descriptor includes threshold-like signing policy. Review signer count, quorum, backup paths, and key origin documentation.",
+        ));
+    }
+
+    if signals.timelock || signals.relative_timelock {
+        warnings.push(warning(
+            "timelock-signal",
+            RiskLevel::Medium,
+            "Timelock signal detected",
+            "The descriptor contains absolute or relative timelock policy. Confirm block height, median time, and sequence assumptions before relying on it.",
+        ));
+    }
+
+    let complexity = descriptor_complexity(&descriptor_type, &signals);
+    let mut summary_items = vec![
+        summary("descriptor_type", &descriptor_type),
+        summary("script_type", &script_type),
+        summary("sanity_check", sanity_check),
+    ];
+    if let Some(weight) = max_satisfaction_weight_wu {
+        summary_items.push(summary("max_satisfaction_weight_wu", weight));
+    }
+
+    let risk = RiskLevel::from_warnings(&warnings, &missing_data);
+    RiskReport {
+        schema_version: super::REPORT_SCHEMA_VERSION.to_owned(),
+        artifact_type: ArtifactType::Descriptor,
+        risk,
+        summary: summary_items,
+        warnings,
+        missing_data,
+        limitations: common_limitations(),
+        transaction: None,
+        psbt: None,
+        script: None,
+        descriptor: Some(DescriptorAnalysis {
+            descriptor_type,
+            script_type,
+            sanity_check,
+            max_satisfaction_weight_wu,
+            signals,
+            complexity,
+        }),
+    }
+}
+
+fn descriptor_signals(descriptor: &Descriptor<PublicKey>) -> ScriptSignals {
+    let normalized = descriptor.to_string();
+    let mut signals = descriptor
+        .explicit_script()
+        .map(|script| analyze_script_bytes(script.as_bytes()).signals)
+        .unwrap_or_default();
+
+    signals.multisig |= has_any(&normalized, &["multi(", "sortedmulti(", "multi_a("]);
+    signals.threshold |= has_any(
+        &normalized,
+        &["thresh(", "multi(", "sortedmulti(", "multi_a("],
+    );
+    signals.timelock |= normalized.contains("after(");
+    signals.relative_timelock |= normalized.contains("older(");
+    signals
+}
+
+fn has_any(input: &str, needles: &[&str]) -> bool {
+    needles.iter().any(|needle| input.contains(needle))
+}
+
+fn descriptor_complexity(descriptor_type: &str, signals: &ScriptSignals) -> super::Complexity {
+    let mut score = 0;
+    let mut factors = vec![format!("descriptor type {descriptor_type}")];
+
+    if descriptor_type.contains("wsh") || descriptor_type.contains("sh_") {
+        score += 1;
+        factors.push("wrapped or witness script descriptor".to_owned());
+    }
+
+    if signals.multisig || signals.threshold {
+        score += 2;
+        factors.push("threshold policy detected".to_owned());
+    }
+
+    if signals.timelock || signals.relative_timelock {
+        score += 2;
+        factors.push("timelock policy detected".to_owned());
+    }
+
+    complexity(score, factors)
+}
+
+fn descriptor_type_name(descriptor_type: DescriptorType) -> &'static str {
+    match descriptor_type {
+        DescriptorType::Bare => "bare",
+        DescriptorType::Sh => "sh",
+        DescriptorType::Pkh => "pkh",
+        DescriptorType::Wpkh => "wpkh",
+        DescriptorType::Wsh => "wsh",
+        DescriptorType::ShWsh => "sh_wsh",
+        DescriptorType::ShWpkh => "sh_wpkh",
+        DescriptorType::ShSortedMulti => "sh_sortedmulti",
+        DescriptorType::WshSortedMulti => "wsh_sortedmulti",
+        DescriptorType::ShWshSortedMulti => "sh_wsh_sortedmulti",
+        DescriptorType::Tr => "tr",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn analyzes_simple_descriptor_fixture() {
+        let report =
+            analyze_descriptor_input(include_str!("../../tests/fixtures/descriptors/simple.txt"))
+                .unwrap();
+        let analysis = report.descriptor.unwrap();
+
+        assert_eq!(report.schema_version, "0.3");
+        assert_eq!(analysis.descriptor_type, "wpkh");
+        assert_eq!(analysis.script_type, "p2wpkh");
+        assert!(analysis.sanity_check);
+        assert!(analysis.max_satisfaction_weight_wu.is_some());
+        assert!(!analysis.signals.multisig);
+        assert_eq!(report.risk, RiskLevel::Low);
+    }
+
+    #[test]
+    fn analyzes_sortedmulti_descriptor_fixture() {
+        let report = analyze_descriptor_input(include_str!(
+            "../../tests/fixtures/descriptors/sortedmulti.txt"
+        ))
+        .unwrap();
+        let analysis = report.descriptor.unwrap();
+
+        assert_eq!(analysis.descriptor_type, "wsh_sortedmulti");
+        assert_eq!(analysis.script_type, "p2wsh");
+        assert!(analysis.signals.multisig);
+        assert!(analysis.signals.threshold);
+        assert!(report
+            .warnings
+            .iter()
+            .any(|warning| warning.code == "threshold-policy"));
+    }
+
+    #[test]
+    fn analyzes_timelock_descriptor_fixture() {
+        let report = analyze_descriptor_input(include_str!(
+            "../../tests/fixtures/descriptors/timelock.txt"
+        ))
+        .unwrap();
+        let analysis = report.descriptor.unwrap();
+
+        assert_eq!(analysis.descriptor_type, "wsh");
+        assert!(analysis.signals.relative_timelock);
+        assert_eq!(report.risk, RiskLevel::Medium);
+        assert!(report
+            .warnings
+            .iter()
+            .any(|warning| warning.code == "timelock-signal"));
+    }
+
+    #[test]
+    fn rejects_invalid_descriptor_fixture() {
+        let err =
+            analyze_descriptor_input(include_str!("../../tests/fixtures/descriptors/invalid.txt"))
+                .unwrap_err();
+
+        assert!(err
+            .to_string()
+            .contains("descriptor input is not a valid public-key output descriptor"));
+    }
+}

src/analyzer/descriptor.rs

@@ -1,18 +1,23 @@
+mod descriptor;
 mod psbt;
 mod script;
 mod tx;
 
 use serde::{Deserialize, Serialize};
 
+pub use descriptor::analyze_descriptor_input;
 pub use psbt::analyze_psbt_file;
 pub use script::analyze_script_input;
 pub use tx::{
     analyze_transaction_file, analyze_transaction_hex, analyze_transaction_hex_with_prevouts,
     PrevoutInput,
 };
 
+const REPORT_SCHEMA_VERSION: &str = "0.3";
+
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct RiskReport {
+    pub schema_version: String,
     pub artifact_type: ArtifactType,
     pub risk: RiskLevel,
     pub summary: Vec<SummaryItem>,
@@ -25,6 +30,8 @@ pub struct RiskReport {
     pub psbt: Option<PsbtAnalysis>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub script: Option<ScriptAnalysis>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub descriptor: Option<DescriptorAnalysis>,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
@@ -33,6 +40,7 @@ pub enum ArtifactType {
     Transaction,
     Psbt,
     Script,
+    Descriptor,
 }
 
 #[derive(Clone, Debug, Deserialize, PartialEq, Eq, PartialOrd, Ord, Serialize)]
@@ -114,6 +122,16 @@ pub struct ScriptAnalysis {
     pub complexity: Complexity,
 }
 
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct DescriptorAnalysis {
+    pub descriptor_type: String,
+    pub script_type: String,
+    pub sanity_check: bool,
+    pub max_satisfaction_weight_wu: Option<u64>,
+    pub signals: ScriptSignals,
+    pub complexity: Complexity,
+}
+
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct OutputAnalysis {
     pub index: usize,
@@ -126,6 +144,7 @@ pub struct OutputAnalysis {
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct ScriptSignals {
     pub multisig: bool,
+    pub threshold: bool,
     pub timelock: bool,
     pub relative_timelock: bool,
     pub op_return: bool,

src/analyzer/mod.rs

@@ -127,6 +127,7 @@ fn analyze_psbt(psbt: &Psbt) -> RiskReport {
 
     let risk = RiskLevel::from_warnings(&warnings, &missing_data);
     RiskReport {
+        schema_version: super::REPORT_SCHEMA_VERSION.to_owned(),
         artifact_type: ArtifactType::Psbt,
         risk,
         summary: summary_items,
@@ -145,6 +146,7 @@ fn analyze_psbt(psbt: &Psbt) -> RiskReport {
             complexity,
         }),
         script: None,
+        descriptor: None,
     }
 }
 

src/analyzer/psbt.rs

@@ -55,6 +55,7 @@ pub fn analyze_script_input(input: &str) -> Result<RiskReport> {
 
     let risk = RiskLevel::from_warnings(&warnings, &missing_data);
     Ok(RiskReport {
+        schema_version: super::REPORT_SCHEMA_VERSION.to_owned(),
         artifact_type: ArtifactType::Script,
         risk,
         summary: vec![
@@ -69,6 +70,7 @@ pub fn analyze_script_input(input: &str) -> Result<RiskReport> {
         transaction: None,
         psbt: None,
         script: Some(analysis),
+        descriptor: None,
     })
 }
 
@@ -82,6 +84,7 @@ fn analyze_script(script: &Script) -> ScriptAnalysis {
     let lock_signals = contains_timelock(bytes);
     let signals = ScriptSignals {
         multisig: contains_multisig(bytes),
+        threshold: false,
         timelock: lock_signals.absolute,
         relative_timelock: lock_signals.relative,
         op_return: bytes.first().is_some_and(|opcode| *opcode == OP_RETURN),

src/analyzer/script.rs

@@ -153,6 +153,7 @@ fn analyze_transaction(
 
     let risk = RiskLevel::from_warnings(&warnings, &missing_data);
     RiskReport {
+        schema_version: super::REPORT_SCHEMA_VERSION.to_owned(),
         artifact_type: ArtifactType::Transaction,
         risk,
         summary: summary_items,
@@ -170,6 +171,7 @@ fn analyze_transaction(
         }),
         psbt: None,
         script: None,
+        descriptor: None,
     }
 }
 

src/analyzer/tx.rs

@@ -68,6 +68,15 @@ enum Commands {
         format: CliFormat,
     },
 
+    /// Analyze an output descriptor for policy and script risk signals.
+    AnalyzeDescriptor {
+        #[arg(long)]
+        descriptor: String,
+
+        #[arg(long, value_enum, default_value_t = CliFormat::Markdown)]
+        format: CliFormat,
+    },
+
     /// Generate an optional executive summary from an existing technical JSON report.
     Summarize {
         #[arg(long)]
@@ -123,6 +132,10 @@ fn main() -> Result<()> {
             let report = analyzer::analyze_script_input(&script)?;
             println!("{}", render_report(&report, format.into())?);
         }
+        Commands::AnalyzeDescriptor { descriptor, format } => {
+            let report = analyzer::analyze_descriptor_input(&descriptor)?;
+            println!("{}", render_report(&report, format.into())?);
+        }
         Commands::Summarize { input, provider } => summarize(input, provider)?,
     }