Move effective_value to Amount and rename

Effective value uses the amount parameter which can be eliminated if it's
moved to a method on Amount.  Furthermore, moving to Amount gives access
to Amount error type OutOfRange which is added on the next commit.

Author: yancyribbens

bitcoin/src/blockdata/transaction.rs

@@ -773,6 +773,8 @@ impl Decodable for Transaction {
 ///
 /// * `fee_rate` - the fee rate of the transaction being created.
 /// * `input_weight_prediction` - the predicted input weight.
+#[deprecated(since = "TBD", note = "use `Amount.to_effective_value()` instead")]
+// removes SignedAmount import from transaction once this is deprecated function is removed.
 pub fn effective_value(
     fee_rate: FeeRate,
     weight: Weight,
@@ -1647,28 +1649,6 @@ mod tests {
         assert!(result.is_err());
     }
 
-    #[test]
-    fn effective_value_happy_path() {
-        let value = "1 cBTC".parse::<Amount>().unwrap();
-        let fee_rate = FeeRate::from_sat_per_kwu(10);
-        let effective_value =
-            effective_value(
-                fee_rate, InputWeightPrediction::P2WPKH_MAX.total_weight(), value
-            ).unwrap();
-
-        // 10 sat/kwu * 272 wu = 4 sats (rounding up)
-        let expected_fee = "3 sats".parse::<SignedAmount>().unwrap();
-        let expected_effective_value = (value.to_signed() - expected_fee).unwrap();
-        assert_eq!(effective_value, expected_effective_value);
-    }
-
-    #[test]
-    fn effective_value_fee_rate_does_not_overflow() {
-        let eff_value =
-            effective_value(FeeRate::MAX, InputWeightPrediction::P2WPKH_MAX.total_weight(), Amount::ZERO);
-        assert!(eff_value.is_none());
-    }
-
     #[test]
     fn txin_txout_weight() {
         // [(is_segwit, tx_hex, expected_weight)]

units/src/amount/tests.rs

@@ -1461,3 +1461,22 @@ fn math_op_errors() {
         panic!("Expected a division by zero error, but got a valid result");
     }
 }
+
+#[test]
+fn to_effective_value() {
+    let amt = "1 cBTC".parse::<Amount>().unwrap();
+    let fee_rate = FeeRate::from_sat_per_kwu(10);
+    let effective_value =
+        amt.to_effective_value(fee_rate, Weight::from_wu(272)).unwrap();
+
+    // 10 sat/kwu * 272 wu = 4 sats (rounding up)
+    let expected_fee = "3 sats".parse::<SignedAmount>().unwrap();
+    let expected_effective_value = (amt.to_signed() - expected_fee).unwrap();
+    assert_eq!(effective_value, expected_effective_value);
+}
+
+#[test]
+fn effective_value_fee_rate_does_not_overflow() {
+    let eff_value =Amount::ZERO.to_effective_value(FeeRate::MAX, Weight::from_wu(272));
+    assert!(eff_value.is_none());
+}

units/src/amount/unsigned.rs

@@ -15,6 +15,7 @@ use super::{
     parse_signed_to_satoshi, split_amount_and_denomination, Denomination, Display, DisplayStyle,
     OutOfRangeError, ParseAmountError, ParseError, SignedAmount,
 };
+use crate::{FeeRate, Weight};
 
 mod encapsulate {
     use super::OutOfRangeError;
@@ -234,6 +235,28 @@ impl Amount {
     #[cfg(feature = "alloc")]
     pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
 
+    /// Computes the effective value of an [`Amount`].
+    ///
+    /// The effective value is the value of an output value minus the amount to spend it. That is, the
+    /// effective_value can be calculated as: value - (fee_rate * weight).
+    ///
+    /// Note: the effective value of a [`Transaction`] may increase less than the effective value of
+    /// a [`TxOut`] when adding another [`TxOut`] to the transaction. This happens when the new
+    /// [`TxOut`] added causes the output length `VarInt` to increase its encoding length.
+    ///
+    /// # Parameters
+    ///
+    /// * `fee_rate` - the fee rate of the transaction being created.
+    /// * `input_weight_prediction` - the predicted input weight.
+    pub fn to_effective_value(
+        &self,
+        fee_rate: FeeRate,
+        weight: Weight,
+    ) -> Option<SignedAmount> {
+        let signed_input_fee = fee_rate.to_fee(weight)?.to_signed();
+        self.to_signed().checked_sub(signed_input_fee)
+    }
+
     /// Converts this [`Amount`] in floating-point notation in the given [`Denomination`].
     ///
     /// # Errors