sdk: reduce runtime checks and panics in FinalTransaction builder

* enforce compile time checks by using sealed trait implementations

Author: ikripaka

Cargo.lock

@@ -20,6 +20,7 @@ serde = { workspace = true }
 hex = { workspace = true }
 
 serde_json = { version = "1.0" }
+sealed = { version = "0.6.0" }
 elements-miniscript = { version = "0.4", features = ["base64", "serde"] }
 bip39 = { version = "2.0.0", features = ["rand"] }
 dyn-clone = { version = "1.0.20" }

crates/sdk/Cargo.toml

@@ -28,15 +28,15 @@ use elements_miniscript::{
     slip77::MasterBlindingKey,
 };
 
+use super::error::SignerError;
 use crate::constants::MIN_FEE;
 use crate::program::ProgramTrait;
 use crate::program::logger::ProgramLogger;
 use crate::provider::ProviderTrait;
 use crate::provider::SimplicityNetwork;
 use crate::signer::wtns_injector::WtnsInjector;
-use crate::transaction::{FinalTransaction, PartialInput, PartialOutput, RequiredSignature, TxReceipt, UTXO};
-
-use super::error::SignerError;
+use crate::transaction::partial_input::{NativeEcdsaSig, RequiredSignature};
+use crate::transaction::{FinalTransaction, PartialInput, PartialOutput, TxReceipt, UTXO};
 
 /// A placeholder dummy fee amount used during transaction estimation.
 pub const PLACEHOLDER_FEE: u64 = 1;
@@ -209,7 +209,7 @@ impl Signer {
                 }
             }
 
-            fee_tx.add_input(PartialInput::new(utxo), RequiredSignature::NativeEcdsa);
+            fee_tx.add_input(PartialInput::new(utxo), NativeEcdsaSig);
         }
 
         // need to try one more time after the loop

crates/sdk/src/signer/core.rs

@@ -9,6 +9,8 @@ use simplicityhl::elements::{
 };
 
 use crate::provider::SimplicityNetwork;
+use crate::transaction::partial_input::{IssuanceSig, ProgramSig};
+use crate::transaction::{ProgramIssuanceSig, RegularSig};
 use crate::utils;
 
 use super::partial_input::{IssuanceInput, PartialInput, ProgramInput, RequiredSignature};
@@ -157,79 +159,51 @@ impl FinalTransaction {
     }
 
     /// Adds a new input to the transaction.
-    ///
-    /// # Panics
-    /// Panics if the requested signature is not `NativeEcdsa` or `None`.
-    /// (i.e. if `required_sig` is `RequiredSignature::Witness` or `RequiredSignature::WitnessWithPath`)
-    pub fn add_input(&mut self, partial_input: PartialInput, required_sig: RequiredSignature) {
-        match required_sig {
-            RequiredSignature::Witness(_) | RequiredSignature::WitnessWithPath(_, _) => {
-                panic!("Requested signature is not NativeEcdsa or None")
-            }
-            _ => {}
-        }
-
-        self.push_new_input(FinalInput::new(partial_input, required_sig));
+    pub fn add_input<S: RegularSig>(&mut self, partial_input: PartialInput, required_sig: S) {
+        self.push_new_input(FinalInput::new(partial_input, required_sig.into_required_sig()));
     }
 
     /// Adds a new program input to the transaction.
-    ///
-    /// # Panics
-    /// The function will panic if the `required_sig` parameter is of type `RequiredSignature::NativeEcdsa`,
-    /// as this type of signature is not applicable for program inputs.
-    pub fn add_program_input(
+    pub fn add_program_input<S: ProgramSig>(
         &mut self,
         partial_input: PartialInput,
         program_input: ProgramInput,
-        required_sig: RequiredSignature,
+        required_sig: S,
     ) {
-        if let RequiredSignature::NativeEcdsa = required_sig {
-            panic!("Requested signature is not Witness or None");
-        }
-
-        self.push_new_input(FinalInput::new(partial_input, required_sig).with_program(program_input));
+        self.push_new_input(
+            FinalInput::new(partial_input, required_sig.into_required_sig()).with_program(program_input),
+        );
     }
 
     /// Adds an issuance (or reissuance) input to the transaction.
     ///
     /// # Panics
-    /// This function panics if the `required_sig` is of type `Witness` or
-    /// `WitnessWithPath`, as these signature types are not allowed in the current context.
-    pub fn add_issuance_input(
+    /// Panics if the populated input fails to return valid issuance details.
+    pub fn add_issuance_input<S: IssuanceSig>(
         &mut self,
         partial_input: PartialInput,
         issuance_input: IssuanceInput,
-        required_sig: RequiredSignature,
+        required_sig: S,
     ) -> IssuanceDetails {
-        match required_sig {
-            RequiredSignature::Witness(_) | RequiredSignature::WitnessWithPath(_, _) => {
-                panic!("Requested signature is not NativeEcdsa or None")
-            }
-            _ => {}
-        }
-
-        self.push_new_input(FinalInput::new(partial_input, required_sig).with_issuance(issuance_input))
-            .unwrap()
+        self.push_new_input(
+            FinalInput::new(partial_input, required_sig.into_required_sig()).with_issuance(issuance_input),
+        )
+        .unwrap()
     }
 
     /// Adds an issuance program input to the transaction with the specified parameters.
     ///
     /// # Panics
-    /// Panics if the `required_sig` parameter is of type `RequiredSignature::NativeEcdsa`.
-    /// Also panics if the populated input fails to return valid issuance details.
-    pub fn add_program_issuance_input(
+    /// Panics if the populated input fails to return valid issuance details.
+    pub fn add_program_issuance_input<S: ProgramIssuanceSig>(
         &mut self,
         partial_input: PartialInput,
         program_input: ProgramInput,
         issuance_input: IssuanceInput,
-        required_sig: RequiredSignature,
+        required_sig: S,
     ) -> IssuanceDetails {
-        if let RequiredSignature::NativeEcdsa = required_sig {
-            panic!("Requested signature is not Witness or None");
-        }
-
         self.push_new_input(
-            FinalInput::new(partial_input, required_sig)
+            FinalInput::new(partial_input, required_sig.into_required_sig())
                 .with_program(program_input)
                 .with_issuance(issuance_input),
         )
@@ -417,7 +391,7 @@ mod tests {
 
     use simplicityhl::elements::{OutPoint, Script, TxOut, Txid};
 
-    use crate::transaction::UTXO;
+    use crate::transaction::{NoneSig, UTXO};
 
     use super::*;
 
@@ -460,7 +434,7 @@ mod tests {
         let partial_output = PartialOutput::new(Script::new(), 4000, policy);
 
         let mut ft = FinalTransaction::new();
-        ft.add_input(partial_input.clone(), RequiredSignature::None);
+        ft.add_input(partial_input.clone(), NoneSig);
         ft.add_output(partial_output.clone());
 
         let mut expected_pst = PartiallySignedTransaction::new_v2();
@@ -487,7 +461,7 @@ mod tests {
         let partial_output = PartialOutput::new(Script::new(), 2000, policy);
 
         let mut ft = FinalTransaction::new();
-        ft.add_input(partial_input.clone(), RequiredSignature::None);
+        ft.add_input(partial_input.clone(), NoneSig);
         ft.add_output(partial_output.clone());
 
         let mut expected_pst = PartiallySignedTransaction::new_v2();
@@ -520,8 +494,8 @@ mod tests {
         let output_b = PartialOutput::new(Script::new(), 800, other);
 
         let mut ft = FinalTransaction::new();
-        ft.add_input(explicit_partial.clone(), RequiredSignature::None);
-        ft.add_input(conf_partial.clone(), RequiredSignature::None);
+        ft.add_input(explicit_partial.clone(), NoneSig);
+        ft.add_input(conf_partial.clone(), NoneSig);
         ft.add_output(output_a.clone());
         ft.add_output(output_b.clone());
 
@@ -560,7 +534,7 @@ mod tests {
         let partial_output = PartialOutput::new(Script::new(), 4000, policy);
 
         let mut ft = FinalTransaction::new();
-        ft.add_issuance_input(partial_input.clone(), issuance.clone(), RequiredSignature::None);
+        ft.add_issuance_input(partial_input.clone(), issuance.clone(), NoneSig);
         ft.add_output(partial_output.clone());
 
         // build expected pst, merge partial_input and issuance manually
@@ -598,7 +572,7 @@ mod tests {
         let partial_output = PartialOutput::new(Script::new(), 1000, policy);
 
         let mut ft = FinalTransaction::new();
-        ft.add_issuance_input(partial_input.clone(), reissuance_input.clone(), RequiredSignature::None);
+        ft.add_issuance_input(partial_input.clone(), reissuance_input.clone(), NoneSig);
         ft.add_output(partial_output.clone());
 
         // build expected pst, merge partial_input and issuance manually

crates/sdk/src/transaction/final_transaction.rs

@@ -10,7 +10,13 @@ pub mod tx_receipt;
 pub mod utxo;
 
 pub use final_transaction::{FinalInput, FinalTransaction, IssuanceDetails};
-pub use partial_input::{PartialInput, ProgramInput, RequiredSignature};
+pub use partial_input::{
+    PartialInput, ProgramInput, RequiredSignature,
+    {
+        IssuanceSig, NativeEcdsaSig, NoneSig, ProgramIssuanceSig, ProgramSig, RegularSig, Signature, WitnessSig,
+        WitnessWithPathSig,
+    },
+};
 pub use partial_output::PartialOutput;
 pub use tx_receipt::TxReceipt;
 pub use utxo::UTXO;

crates/sdk/src/transaction/mod.rs

@@ -221,3 +221,102 @@ impl IssuanceInput {
         }
     }
 }
+
+pub use sealed::*;
+mod sealed {
+    use crate::transaction::RequiredSignature;
+
+    /// A trait for signature types, sealed to prevent external implementations.
+    #[sealed::sealed]
+    pub trait Signature {
+        /// Converts the signature requirement into the standard `RequiredSignature` enum.
+        fn into_required_sig(self) -> RequiredSignature;
+    }
+
+    /// A marker trait representing signatures allowed for non-program inputs (ECDSA or None).
+    pub trait RegularSig: Signature {}
+
+    /// A marker trait representing signatures allowed for program inputs (Witness or None).
+    pub trait ProgramSig: Signature {}
+
+    /// A marker trait representing signatures allowed for non-program inputs (ECDSA or None).
+    pub trait IssuanceSig: Signature {}
+
+    /// A marker trait representing signatures allowed for program inputs (Witness or None).
+    pub trait ProgramIssuanceSig: Signature {}
+
+    /// Represents no signature requirement.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+    pub struct NoneSig;
+
+    #[sealed::sealed]
+    impl Signature for NoneSig {
+        fn into_required_sig(self) -> RequiredSignature {
+            RequiredSignature::None
+        }
+    }
+    impl RegularSig for NoneSig {}
+    impl ProgramIssuanceSig for NoneSig {}
+    impl IssuanceSig for NoneSig {}
+    impl ProgramSig for NoneSig {}
+
+    /// Represents a standard Native ECDSA (WPKH) signature requirement.
+    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+    pub struct NativeEcdsaSig;
+
+    #[sealed::sealed]
+    impl Signature for NativeEcdsaSig {
+        fn into_required_sig(self) -> RequiredSignature {
+            RequiredSignature::NativeEcdsa
+        }
+    }
+    impl RegularSig for NativeEcdsaSig {}
+    impl IssuanceSig for NativeEcdsaSig {}
+
+    /// Represents a generic witness payload associated with an external name.
+    #[derive(Debug, Clone, PartialEq, Eq)]
+    pub struct WitnessSig(pub String);
+
+    impl WitnessSig {
+        /// Creates a `WitnessSig` requirement using an iterator of path segments.
+        #[must_use]
+        pub fn new(name: &str) -> Self {
+            WitnessSig(name.to_string())
+        }
+    }
+    #[sealed::sealed]
+    impl Signature for WitnessSig {
+        fn into_required_sig(self) -> RequiredSignature {
+            RequiredSignature::Witness(self.0)
+        }
+    }
+    impl ProgramIssuanceSig for WitnessSig {}
+    impl ProgramSig for WitnessSig {}
+
+    /// Represents a witness payload requiring traversal through a specified path hierarchy.
+    #[derive(Debug, Clone, PartialEq, Eq)]
+    pub struct WitnessWithPathSig(pub String, pub Vec<String>);
+
+    impl WitnessWithPathSig {
+        /// Creates a `WitnessWithPathSig` requirement using an iterator of path segments.
+        pub fn new<I>(name: &str, path: I) -> Self
+        where
+            I: IntoIterator,
+            I::Item: AsRef<str>,
+        {
+            Self(
+                name.to_string(),
+                path.into_iter().map(|s| s.as_ref().to_string()).collect(),
+            )
+        }
+    }
+
+    #[sealed::sealed]
+    impl Signature for WitnessWithPathSig {
+        fn into_required_sig(self) -> RequiredSignature {
+            RequiredSignature::WitnessWithPath(self.0, self.1)
+        }
+    }
+    impl ProgramIssuanceSig for WitnessWithPathSig {}
+    impl ProgramSig for WitnessWithPathSig {}
+}

crates/sdk/src/transaction/partial_input.rs

@@ -1,6 +1,6 @@
 use simplex::simplicityhl::elements::Script;
 
-use simplex::transaction::{FinalTransaction, PartialInput, ProgramInput, RequiredSignature, TxReceipt};
+use simplex::transaction::{FinalTransaction, PartialInput, ProgramInput, TxReceipt, WitnessSig};
 
 use simplex_example::artifacts::p2pk::P2pkProgram;
 use simplex_example::artifacts::p2pk::derived_p2pk::{P2pkArguments, P2pkWitness};
@@ -44,7 +44,7 @@ fn spend_p2pk(context: &simplex::TestContext) -> anyhow::Result<TxReceipt<'_>> {
     ft.add_program_input(
         PartialInput::new(p2pk_utxos[0].clone()),
         ProgramInput::new(Box::new(p2pk.as_ref().clone()), Box::new(witness.clone())),
-        RequiredSignature::Witness("SIGNATURE".to_string()),
+        WitnessSig("SIGNATURE".to_string()),
     );
 
     let tx_receipt = signer.broadcast(&ft)?;