Merge pull request #38 from TheBlueMatt/main

[ldk-c-bindings] / lightning-c-bindings / src / lightning / ln / chan_utils.rs

diff --git a/lightning-c-bindings/src/lightning/ln/chan_utils.rs b/lightning-c-bindings/src/lightning/ln/chan_utils.rs
index 529beacb5afd8c9fc45ef1c8d3b6dde17f8172ee..5cf8b63069a6870372c370ff85ef4e49b7b9b922 100644 (file)
--- a/lightning-c-bindings/src/lightning/ln/chan_utils.rs
+++ b/lightning-c-bindings/src/lightning/ln/chan_utils.rs
@@ -617,10 +617,16 @@ pub extern "C" fn make_funding_redeemscript(mut broadcaster: crate::c_types::Pub
        ret.into_bytes().into()
 }
 
-/// panics if htlc.transaction_output_index.is_none()!
+/// Builds an unsigned HTLC-Success or HTLC-Timeout transaction from the given channel and HTLC
+/// parameters. This is used by [`TrustedCommitmentTransaction::get_htlc_sigs`] to fetch the
+/// transaction which needs signing, and can be used to construct an HTLC transaction which is
+/// broadcastable given a counterparty HTLC signature.
+///
+/// Panics if htlc.transaction_output_index.is_none() (as such HTLCs do not appear in the
+/// commitment transaction).
 #[no_mangle]
-pub extern "C" fn build_htlc_transaction(prev_hash: *const [u8; 32], mut feerate_per_kw: u32, mut contest_delay: u16, htlc: &crate::lightning::ln::chan_utils::HTLCOutputInCommitment, mut broadcaster_delayed_payment_key: crate::c_types::PublicKey, mut revocation_key: crate::c_types::PublicKey) -> crate::c_types::Transaction {
-       let mut ret = lightning::ln::chan_utils::build_htlc_transaction(&::bitcoin::hash_types::Txid::from_slice(&unsafe { &*prev_hash }[..]).unwrap(), feerate_per_kw, contest_delay, unsafe { &*htlc.inner }, &broadcaster_delayed_payment_key.into_rust(), &revocation_key.into_rust());
+pub extern "C" fn build_htlc_transaction(commitment_txid: *const [u8; 32], mut feerate_per_kw: u32, mut contest_delay: u16, htlc: &crate::lightning::ln::chan_utils::HTLCOutputInCommitment, mut broadcaster_delayed_payment_key: crate::c_types::PublicKey, mut revocation_key: crate::c_types::PublicKey) -> crate::c_types::Transaction {
+       let mut ret = lightning::ln::chan_utils::build_htlc_transaction(&::bitcoin::hash_types::Txid::from_slice(&unsafe { &*commitment_txid }[..]).unwrap(), feerate_per_kw, contest_delay, unsafe { &*htlc.inner }, &broadcaster_delayed_payment_key.into_rust(), &revocation_key.into_rust());
        crate::c_types::Transaction::from_bitcoin(&ret)
 }
 
@@ -710,6 +716,8 @@ pub extern "C" fn ChannelTransactionParameters_set_is_outbound_from_holder(this_
 }
 /// The late-bound counterparty channel transaction parameters.
 /// These parameters are populated at the point in the protocol where the counterparty provides them.
+///
+/// Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 #[no_mangle]
 pub extern "C" fn ChannelTransactionParameters_get_counterparty_parameters(this_ptr: &ChannelTransactionParameters) -> crate::lightning::ln::chan_utils::CounterpartyChannelTransactionParameters {
        let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.counterparty_parameters;
@@ -718,12 +726,16 @@ pub extern "C" fn ChannelTransactionParameters_get_counterparty_parameters(this_
 }
 /// The late-bound counterparty channel transaction parameters.
 /// These parameters are populated at the point in the protocol where the counterparty provides them.
+///
+/// Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None
 #[no_mangle]
 pub extern "C" fn ChannelTransactionParameters_set_counterparty_parameters(this_ptr: &mut ChannelTransactionParameters, mut val: crate::lightning::ln::chan_utils::CounterpartyChannelTransactionParameters) {
        let mut local_val = if val.inner.is_null() { None } else { Some( { *unsafe { Box::from_raw(val.take_inner()) } }) };
        unsafe { &mut *this_ptr.inner }.counterparty_parameters = local_val;
 }
 /// The late-bound funding outpoint
+///
+/// Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 #[no_mangle]
 pub extern "C" fn ChannelTransactionParameters_get_funding_outpoint(this_ptr: &ChannelTransactionParameters) -> crate::lightning::chain::transaction::OutPoint {
        let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.funding_outpoint;
@@ -731,6 +743,8 @@ pub extern "C" fn ChannelTransactionParameters_get_funding_outpoint(this_ptr: &C
        local_inner_val
 }
 /// The late-bound funding outpoint
+///
+/// Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None
 #[no_mangle]
 pub extern "C" fn ChannelTransactionParameters_set_funding_outpoint(this_ptr: &mut ChannelTransactionParameters, mut val: crate::lightning::chain::transaction::OutPoint) {
        let mut local_val = if val.inner.is_null() { None } else { Some( { *unsafe { Box::from_raw(val.take_inner()) } }) };
@@ -1494,7 +1508,12 @@ pub extern "C" fn TrustedCommitmentTransaction_get_htlc_sigs(this_arg: &TrustedC
        local_ret
 }
 
-/// Get the transaction number obscure factor
+/// Commitment transaction numbers which appear in the transactions themselves are XOR'd with a
+/// shared secret first. This prevents on-chain observers from discovering how many commitment
+/// transactions occurred in a channel before it was closed.
+///
+/// This function gets the shared secret from relevant channel public keys and can be used to
+/// \"decrypt\" the commitment transaction number given a commitment transaction on-chain.
 #[no_mangle]
 pub extern "C" fn get_commitment_transaction_number_obscure_factor(mut broadcaster_payment_basepoint: crate::c_types::PublicKey, mut countersignatory_payment_basepoint: crate::c_types::PublicKey, mut outbound_from_broadcaster: bool) -> u64 {
        let mut ret = lightning::ln::chan_utils::get_commitment_transaction_number_obscure_factor(&broadcaster_payment_basepoint.into_rust(), &countersignatory_payment_basepoint.into_rust(), outbound_from_broadcaster);