Merge branch 'pox-wf-integration' into feat/wf-signer-set

Author: aaronb-stacks

changelog.d/7179-bitcoin-clarity-builtins.added

@@ -0,0 +1 @@
+Adds two new Clarity 6 native functions: `verify-merkle-proof`, which checks a Bitcoin-style merkle inclusion proof against a known root using double-SHA-256, and `get-bitcoin-tx-output?`, which parses a serialized Bitcoin transaction (with or without SegWit witness data) and returns the output at a given index along with the canonical, witness-stripped txid in internal byte order

clarity-types/src/types/signatures.rs

@@ -830,6 +830,8 @@ impl TypeSignature {
     pub const BUFFER_64: TypeSignature = Self::type_buffer_const(64);
     /// Buffer type with length 65.
     pub const BUFFER_65: TypeSignature = Self::type_buffer_const(65);
+    /// Buffer type with length 1024.
+    pub const BUFFER_1024: TypeSignature = Self::type_buffer_const(1024);
 
     /// String ASCII type with minimum length (`1`).
     pub const STRING_ASCII_MIN: TypeSignature = Self::type_ascii_const(1);

clarity/src/vm/analysis/arithmetic_checker/mod.rs

@@ -210,7 +210,9 @@ impl ArithmeticOnlyChecker<'_> {
                 Err(Error::FunctionNotPermitted(function))
             }
             Sha512 | Sha512Trunc256 | Secp256k1Recover | Secp256k1Verify | Secp256r1Verify
-            | Hash160 | Sha256 | Keccak256 => Err(Error::FunctionNotPermitted(function)),
+            | Hash160 | Sha256 | Keccak256 | VerifyMerkleProof | GetBitcoinTxOutput => {
+                Err(Error::FunctionNotPermitted(function))
+            }
             Add | Subtract | Divide | Multiply | CmpGeq | CmpLeq | CmpLess | CmpGreater
             | Modulo | Power | Sqrti | Log2 | BitwiseXor | And | Or | Not | Equals | If
             | ConsSome | ConsOkay | ConsError | DefaultTo | UnwrapRet | UnwrapErrRet | IsOkay

clarity/src/vm/analysis/errors.rs

@@ -1108,6 +1108,23 @@ pub fn check_arguments_at_most<T>(expected: usize, args: &[T]) -> Result<(), Com
     }
 }
 
+/// Check if the supplied arguments are exactly N in length, and if so, return
+///  a fixed array with pointers to the arguments. Otherwise, return an IncorrectArgumentCount
+pub fn get_arguments_exact<T, const N: usize>(args: &[T]) -> Result<&[T; N], CommonCheckErrorKind> {
+    args.try_into()
+        .map_err(|_| CommonCheckErrorKind::IncorrectArgumentCount(N, args.len()))
+}
+
+/// Check if the supplied arguments are at least N in length, and if so, return
+///  a fixed array of size N with pointers to the arguments and a slice with the excess.
+/// Otherwise, return an IncorrectArgumentCount
+pub fn get_arguments_at_least<T, const N: usize>(
+    args: &[T],
+) -> Result<(&[T; N], &[T]), CommonCheckErrorKind> {
+    args.split_first_chunk::<N>()
+        .ok_or_else(|| CommonCheckErrorKind::RequiresAtLeastArguments(N, args.len()))
+}
+
 fn formatted_expected_types(expected_types: &[TypeSignature]) -> String {
     let mut expected_types_joined = format!("'{}'", expected_types[0]);
 

clarity/src/vm/analysis/read_only_checker/mod.rs

@@ -381,7 +381,9 @@ impl<'a, 'b> ReadOnlyChecker<'a, 'b> {
             | AllowanceWithFt
             | AllowanceWithNft
             | AllowanceWithStacking
-            | AllowanceAll => {
+            | AllowanceAll
+            | VerifyMerkleProof
+            | GetBitcoinTxOutput => {
                 // Check all arguments.
                 self.check_each_expression_is_read_only(args)
             }

clarity/src/vm/analysis/type_checker/v2_05/natives/mod.rs

@@ -839,7 +839,9 @@ impl TypedNativeFunction {
             | AllowanceWithNft
             | AllowanceWithStacking
             | AllowanceAll
-            | Secp256r1Verify => {
+            | Secp256r1Verify
+            | VerifyMerkleProof
+            | GetBitcoinTxOutput => {
                 return Err(StaticCheckErrorKind::Unreachable(
                     "Clarity 2+ keywords should not show up in 2.05".into(),
                 ));

clarity/src/vm/analysis/type_checker/v2_1/natives/mod.rs

@@ -20,10 +20,13 @@ use super::{
     TypeChecker, TypingContext, check_argument_count, check_arguments_at_least,
     check_arguments_at_most, compute_typecheck_cost, no_type,
 };
-use crate::vm::analysis::errors::{StaticCheckError, StaticCheckErrorKind, SyntaxBindingErrorType};
+use crate::vm::analysis::errors::{
+    StaticCheckError, StaticCheckErrorKind, SyntaxBindingErrorType, get_arguments_exact,
+};
 use crate::vm::costs::cost_functions::ClarityCostFunction;
 use crate::vm::costs::{CostErrors, CostTracker, analysis_typecheck_cost, runtime_cost};
 use crate::vm::diagnostic::DiagnosableError;
+use crate::vm::functions::bitcoin::VERIFY_MERKLE_PROOF_MAX_DEPTH;
 use crate::vm::functions::{NativeFunctions, handle_binding_list};
 use crate::vm::types::signatures::{
     CallableSubtype, FunctionArgSignature, FunctionReturnsSignature, SequenceSubtype,
@@ -868,6 +871,63 @@ fn check_get_tenure_info(
     Ok(TypeSignature::new_option(block_info_prop.type_result())?)
 }
 
+fn check_verify_merkle_proof(
+    checker: &mut TypeChecker,
+    args: &[SymbolicExpression],
+    context: &TypingContext,
+) -> Result<TypeSignature, StaticCheckError> {
+    let [leaf_hash, root_hash, tx_index, tx_count, sibling_hashes] =
+        get_arguments_exact::<_, 5>(args)?;
+
+    check_argument_count(5, args)?;
+    checker.type_check_expects(leaf_hash, context, &TypeSignature::BUFFER_32)?;
+    checker.type_check_expects(root_hash, context, &TypeSignature::BUFFER_32)?;
+    checker.type_check_expects(tx_index, context, &TypeSignature::UIntType)?;
+    checker.type_check_expects(tx_count, context, &TypeSignature::UIntType)?;
+    let siblings_type = TypeSignature::list_of(
+        TypeSignature::BUFFER_32,
+        VERIFY_MERKLE_PROOF_MAX_DEPTH,
+    )
+    .map_err(|_| {
+        StaticCheckErrorKind::Unreachable("FATAL: failed to build (list 24 (buff 32)) type".into())
+    })?;
+    checker.type_check_expects(sibling_hashes, context, &siblings_type)?;
+    Ok(TypeSignature::BoolType)
+}
+
+fn check_get_bitcoin_tx_output(
+    checker: &mut TypeChecker,
+    args: &[SymbolicExpression],
+    context: &TypingContext,
+) -> Result<TypeSignature, StaticCheckError> {
+    let [tx_bytes, vout_index] = get_arguments_exact::<_, 2>(args)?;
+
+    checker.type_check_expects(tx_bytes, context, &TypeSignature::BUFFER_MAX)?;
+    checker.type_check_expects(vout_index, context, &TypeSignature::UIntType)?;
+
+    let ok_type: TypeSignature = TupleTypeSignature::try_from(vec![
+        (
+            ClarityName::from_literal("script"),
+            TypeSignature::BUFFER_1024,
+        ),
+        (ClarityName::from_literal("amount"), TypeSignature::UIntType),
+        (ClarityName::from_literal("txid"), TypeSignature::BUFFER_32),
+    ])
+    .map_err(|_| {
+        StaticCheckErrorKind::Unreachable(
+            "FATAL: failed to build get-bitcoin-tx-output? ok-tuple type".into(),
+        )
+    })?
+    .into();
+
+    TypeSignature::new_response(ok_type, TypeSignature::UIntType).map_err(|_| {
+        StaticCheckErrorKind::Unreachable(
+            "FATAL: failed to build get-bitcoin-tx-output? response type".into(),
+        )
+        .into()
+    })
+}
+
 impl TypedNativeFunction {
     pub fn type_check_application(
         &self,
@@ -1272,6 +1332,8 @@ impl TypedNativeFunction {
             | AllowanceWithStacking
             | AllowanceAll => Special(SpecialNativeFunction(&post_conditions::check_allowance_err)),
             Secp256r1Verify => Special(SpecialNativeFunction(&check_secp256r1_verify)),
+            VerifyMerkleProof => Special(SpecialNativeFunction(&check_verify_merkle_proof)),
+            GetBitcoinTxOutput => Special(SpecialNativeFunction(&check_get_bitcoin_tx_output)),
         };
 
         Ok(out)

clarity/src/vm/callables.rs

@@ -37,17 +37,33 @@ use crate::vm::{LocalContext, Value, eval};
 
 #[allow(clippy::type_complexity, clippy::large_enum_variant)]
 pub enum CallableType {
+    /// A function defined in a Clarity contract via `define-public`,
+    /// `define-read-only`, or `define-private`. Arguments are evaluated by
+    /// the caller and then bound into a fresh `LocalContext` before the
+    /// body is interpreted.
     UserFunction(DefinedFunction),
+    /// A built-in function implemented in Rust. The string is the function's
+    /// Clarity name (used for identifier construction and diagnostics), the
+    /// [`NativeHandle`] dispatches on arity, and the [`ClarityCostFunction`]
+    /// is charged with the argument count as its input size.
     NativeFunction(&'static str, NativeHandle, ClarityCostFunction),
-    /// These native functions have a new method for calculating input size in 2.05
-    /// If the global context's epoch is >= 2.05, the fn field is applied to obtain
-    /// the input to the cost function.
+    /// A built-in function whose runtime-cost input size is computed from
+    /// the actual argument values rather than just their count. Introduced
+    /// in epoch 2.05: when the current epoch is >= 2.05, the trailing
+    /// closure is applied to the evaluated arguments to obtain the input
+    /// passed to the cost function. In earlier epochs this variant behaves
+    /// like [`Self::NativeFunction`].
     NativeFunction205(
         &'static str,
         NativeHandle,
         ClarityCostFunction,
         &'static dyn Fn(&[Value]) -> Result<u64, VmExecutionError>,
     ),
+    /// A built-in form that needs control over how (or whether) its
+    /// arguments are evaluated — e.g. `if`, `let`, `match`, `contract-call?`.
+    /// The closure receives the raw [`SymbolicExpression`]s along with the
+    /// execution and local contexts, and is responsible for cost tracking,
+    /// arity checking, and argument evaluation itself.
     SpecialFunction(
         &'static str,
         &'static dyn Fn(

clarity/src/vm/costs/cost_functions.rs

@@ -161,6 +161,8 @@ define_named_enum!(ClarityCostFunction {
     RestrictAssets("cost_restrict_assets"),
     AsContractSafe("cost_as_contract_safe"),
     Secp256r1verify("cost_secp256r1verify"),
+    VerifyMerkleProof("cost_verify_merkle_proof"),
+    GetBitcoinTxOutput("cost_get_bitcoin_tx_output"),
     Unimplemented("cost_unimplemented"),
 });
 
@@ -339,6 +341,8 @@ pub trait CostValues {
     fn cost_restrict_assets(n: u64) -> Result<ExecutionCost, VmExecutionError>;
     fn cost_as_contract_safe(n: u64) -> Result<ExecutionCost, VmExecutionError>;
     fn cost_secp256r1verify(n: u64) -> Result<ExecutionCost, VmExecutionError>;
+    fn cost_verify_merkle_proof(n: u64) -> Result<ExecutionCost, VmExecutionError>;
+    fn cost_get_bitcoin_tx_output(n: u64) -> Result<ExecutionCost, VmExecutionError>;
 }
 
 impl ClarityCostFunction {
@@ -496,6 +500,8 @@ impl ClarityCostFunction {
             ClarityCostFunction::RestrictAssets => C::cost_restrict_assets(n),
             ClarityCostFunction::AsContractSafe => C::cost_as_contract_safe(n),
             ClarityCostFunction::Secp256r1verify => C::cost_secp256r1verify(n),
+            ClarityCostFunction::VerifyMerkleProof => C::cost_verify_merkle_proof(n),
+            ClarityCostFunction::GetBitcoinTxOutput => C::cost_get_bitcoin_tx_output(n),
             ClarityCostFunction::Unimplemented => Err(RuntimeError::NotImplemented.into()),
         }
     }

clarity/src/vm/costs/costs_1.rs

@@ -765,4 +765,12 @@ impl CostValues for Costs1 {
     fn cost_secp256r1verify(n: u64) -> Result<ExecutionCost, VmExecutionError> {
         Err(RuntimeError::NotImplemented.into())
     }
+
+    fn cost_verify_merkle_proof(_n: u64) -> Result<ExecutionCost, VmExecutionError> {
+        Err(RuntimeError::NotImplemented.into())
+    }
+
+    fn cost_get_bitcoin_tx_output(_n: u64) -> Result<ExecutionCost, VmExecutionError> {
+        Err(RuntimeError::NotImplemented.into())
+    }
 }