Merge pull request #940 from TheBlueMatt/2021-06-fix-docs
authorMatt Corallo <649246+TheBlueMatt@users.noreply.github.com>
Tue, 8 Jun 2021 02:28:46 +0000 (02:28 +0000)
committerGitHub <noreply@github.com>
Tue, 8 Jun 2021 02:28:46 +0000 (02:28 +0000)
Clean up docs on public chan_utils methods to be more useful

lightning-background-processor/src/lib.rs
lightning-invoice/src/de.rs
lightning-invoice/src/lib.rs
lightning-invoice/src/ser.rs
lightning/src/chain/channelmonitor.rs
lightning/src/chain/mod.rs
lightning/src/ln/channel.rs
lightning/src/ln/channelmanager.rs
lightning/src/ln/functional_tests.rs
lightning/src/util/events.rs

index e9ca316afbedbe6843887f9122ae1dc368fc8500..dd13a35b46f6055807add340b88c41f41dcb7d6d 100644 (file)
@@ -180,7 +180,7 @@ mod tests {
        use lightning::chain::keysinterface::{InMemorySigner, KeysInterface, KeysManager};
        use lightning::chain::transaction::OutPoint;
        use lightning::get_event_msg;
-       use lightning::ln::channelmanager::{BestBlock, ChainParameters, ChannelManager, SimpleArcChannelManager};
+       use lightning::ln::channelmanager::{BREAKDOWN_TIMEOUT, BestBlock, ChainParameters, ChannelManager, SimpleArcChannelManager};
        use lightning::ln::features::InitFeatures;
        use lightning::ln::msgs::ChannelMessageHandler;
        use lightning::ln::peer_handler::{PeerManager, MessageHandler, SocketDescriptor};
@@ -303,8 +303,8 @@ mod tests {
                }}
        }
 
-       fn confirm_transaction(node: &mut Node, tx: &Transaction) {
-               for i in 1..=ANTI_REORG_DELAY {
+       fn confirm_transaction_depth(node: &mut Node, tx: &Transaction, depth: u32) {
+               for i in 1..=depth {
                        let prev_blockhash = node.best_block.block_hash();
                        let height = node.best_block.height() + 1;
                        let header = BlockHeader { version: 0x20000000, prev_blockhash, merkle_root: Default::default(), time: height, bits: 42, nonce: 42 };
@@ -315,7 +315,7 @@ mod tests {
                                        node.node.transactions_confirmed(&header, &txdata, height);
                                        node.chain_monitor.transactions_confirmed(&header, &txdata, height);
                                },
-                               ANTI_REORG_DELAY => {
+                               x if x == depth => {
                                        node.node.best_block_updated(&header, height);
                                        node.chain_monitor.best_block_updated(&header, height);
                                },
@@ -323,6 +323,9 @@ mod tests {
                        }
                }
        }
+       fn confirm_transaction(node: &mut Node, tx: &Transaction) {
+               confirm_transaction_depth(node, tx, ANTI_REORG_DELAY);
+       }
 
        #[test]
        fn test_background_processor() {
@@ -454,7 +457,7 @@ mod tests {
                // Force close the channel and check that the SpendableOutputs event was handled.
                nodes[0].node.force_close_channel(&nodes[0].node.list_channels()[0].channel_id).unwrap();
                let commitment_tx = nodes[0].tx_broadcaster.txn_broadcasted.lock().unwrap().pop().unwrap();
-               confirm_transaction(&mut nodes[0], &commitment_tx);
+               confirm_transaction_depth(&mut nodes[0], &commitment_tx, BREAKDOWN_TIMEOUT as u32);
                let event = receiver
                        .recv_timeout(Duration::from_secs(EVENT_DEADLINE))
                        .expect("SpendableOutputs not handled within deadline");
index 3610bc4b67fab01f11283aed957c1fe71ccb4731..47557665b4bf4b473a90657280c9b807ebadbfdc 100644 (file)
@@ -185,6 +185,7 @@ impl FromStr for super::Currency {
                        "tb" => Ok(Currency::BitcoinTestnet),
                        "bcrt" => Ok(Currency::Regtest),
                        "sb" => Ok(Currency::Simnet),
+                       "tbs" => Ok(Currency::Signet),
                        _ => Err(ParseError::UnknownCurrency)
                }
        }
@@ -774,6 +775,7 @@ mod test {
                assert_eq!("tb".parse::<Currency>(), Ok(Currency::BitcoinTestnet));
                assert_eq!("bcrt".parse::<Currency>(), Ok(Currency::Regtest));
                assert_eq!("sb".parse::<Currency>(), Ok(Currency::Simnet));
+               assert_eq!("tbs".parse::<Currency>(), Ok(Currency::Signet));
                assert_eq!("something_else".parse::<Currency>(), Err(ParseError::UnknownCurrency))
        }
 
index 29c093dec95925f19f86d745ecdf54bd98856851..064b3626537c2d93b753e6dd9095522010131a77 100644 (file)
@@ -328,8 +328,11 @@ pub enum Currency {
        /// Bitcoin regtest
        Regtest,
 
-       /// Bitcoin simnet/signet
+       /// Bitcoin simnet
        Simnet,
+
+       /// Bitcoin signet
+       Signet,
 }
 
 /// Tagged field which may have an unknown tag
index 8811926782348a263735b55824ea74fb65d662cb..885ea2684f2295665ebd0ac8800b90e08f7685ed 100644 (file)
@@ -153,6 +153,7 @@ impl Display for Currency {
                        Currency::BitcoinTestnet => "tb",
                        Currency::Regtest => "bcrt",
                        Currency::Simnet => "sb",
+                       Currency::Signet => "tbs",
                };
                write!(f, "{}", currency_code)
        }
@@ -473,6 +474,7 @@ mod test {
                assert_eq!("tb", Currency::BitcoinTestnet.to_string());
                assert_eq!("bcrt", Currency::Regtest.to_string());
                assert_eq!("sb", Currency::Simnet.to_string());
+               assert_eq!("tbs", Currency::Signet.to_string());
        }
 
        #[test]
index fe581ac65adcfeb0e4936ad32024bd01a19b6396..a0f5eb71d7b3fdf69ef076183fdb1ccc76ff0fc4 100644 (file)
@@ -362,7 +362,15 @@ struct OnchainEventEntry {
 
 impl OnchainEventEntry {
        fn confirmation_threshold(&self) -> u32 {
-               self.height + ANTI_REORG_DELAY - 1
+               let mut conf_threshold = self.height + ANTI_REORG_DELAY - 1;
+               if let OnchainEvent::MaturingOutput {
+                       descriptor: SpendableOutputDescriptor::DelayedPaymentOutput(ref descriptor)
+               } = self.event {
+                       // A CSV'd transaction is confirmable in block (input height) + CSV delay, which means
+                       // it's broadcastable when we see the previous block.
+                       conf_threshold = cmp::max(conf_threshold, self.height + descriptor.to_self_delay as u32 - 1);
+               }
+               conf_threshold
        }
 
        fn has_reached_confirmation_threshold(&self, height: u32) -> bool {
index e4bb66c7e755905058fa7b0f44520046773b5601..8f27e40baeaf1e3b5d43dade8a05da0bb08dfdcb 100644 (file)
@@ -239,6 +239,7 @@ pub trait Filter {
 ///
 /// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
 /// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected
+#[derive(Clone, PartialEq, Hash)]
 pub struct WatchedOutput {
        /// First block where the transaction output may have been spent.
        pub block_hash: Option<BlockHash>,
index 07293a102ea2ea7df99b9a1514c875b4cd98976f..f8c8c15be95ad660f2803125092a6bcac288f8ee 100644 (file)
@@ -1428,9 +1428,6 @@ impl<Signer: Sign> Channel<Signer> {
                if msg.channel_reserve_satoshis > self.channel_value_satoshis {
                        return Err(ChannelError::Close(format!("Bogus channel_reserve_satoshis ({}). Must not be greater than ({})", msg.channel_reserve_satoshis, self.channel_value_satoshis)));
                }
-               if msg.dust_limit_satoshis > msg.channel_reserve_satoshis {
-                       return Err(ChannelError::Close(format!("Bogus channel_reserve ({}) and dust_limit ({})", msg.channel_reserve_satoshis, msg.dust_limit_satoshis)));
-               }
                if msg.channel_reserve_satoshis < self.holder_dust_limit_satoshis {
                        return Err(ChannelError::Close(format!("Peer never wants payout outputs? channel_reserve_satoshis was ({}). dust_limit is ({})", msg.channel_reserve_satoshis, self.holder_dust_limit_satoshis)));
                }
index c3fe8090ae483b9bf23bed19284ef3593a60f8c8..13a993fd965596dc41e12a387bc178ea31372b35 100644 (file)
@@ -498,6 +498,7 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 /// Typically, the block-specific parameters are derived from the best block hash for the network,
 /// as a newly constructed `ChannelManager` will not have created any channels yet. These parameters
 /// are not needed when deserializing a previously constructed `ChannelManager`.
+#[derive(Clone, Copy, PartialEq)]
 pub struct ChainParameters {
        /// The network for determining the `chain_hash` in Lightning messages.
        pub network: Network,
@@ -509,7 +510,7 @@ pub struct ChainParameters {
 }
 
 /// The best known block as identified by its hash and height.
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, PartialEq)]
 pub struct BestBlock {
        block_hash: BlockHash,
        height: u32,
index eb4f6054b7842ec2953c5004cb499c6ebf7ee97e..95d114aab5b6b2b563fb60b2656879b56221adb9 100644 (file)
@@ -4875,11 +4875,13 @@ fn test_claim_sizeable_push_msat() {
        assert_eq!(node_txn[0].output.len(), 2); // We can't force trimming of to_remote output as channel_reserve_satoshis block us to do so at channel opening
 
        mine_transaction(&nodes[1], &node_txn[0]);
-       connect_blocks(&nodes[1], ANTI_REORG_DELAY - 1);
+       connect_blocks(&nodes[1], BREAKDOWN_TIMEOUT as u32 - 1);
 
        let spend_txn = check_spendable_outputs!(nodes[1], 1, node_cfgs[1].keys_manager, 100000);
        assert_eq!(spend_txn.len(), 1);
+       assert_eq!(spend_txn[0].input.len(), 1);
        check_spends!(spend_txn[0], node_txn[0]);
+       assert_eq!(spend_txn[0].input[0].sequence, BREAKDOWN_TIMEOUT as u32);
 }
 
 #[test]
@@ -5507,12 +5509,14 @@ fn test_dynamic_spendable_outputs_local_htlc_success_tx() {
        };
 
        mine_transaction(&nodes[1], &node_tx);
-       connect_blocks(&nodes[1], ANTI_REORG_DELAY - 1);
+       connect_blocks(&nodes[1], BREAKDOWN_TIMEOUT as u32 - 1);
 
        // Verify that B is able to spend its own HTLC-Success tx thanks to spendable output event given back by its ChannelMonitor
        let spend_txn = check_spendable_outputs!(nodes[1], 1, node_cfgs[1].keys_manager, 100000);
        assert_eq!(spend_txn.len(), 1);
+       assert_eq!(spend_txn[0].input.len(), 1);
        check_spends!(spend_txn[0], node_tx);
+       assert_eq!(spend_txn[0].input[0].sequence, BREAKDOWN_TIMEOUT as u32);
 }
 
 fn do_test_fail_backwards_unrevoked_remote_announce(deliver_last_raa: bool, announce_latest: bool) {
@@ -5802,15 +5806,20 @@ fn test_dynamic_spendable_outputs_local_htlc_timeout_tx() {
        };
 
        mine_transaction(&nodes[0], &htlc_timeout);
-       connect_blocks(&nodes[0], ANTI_REORG_DELAY - 1);
+       connect_blocks(&nodes[0], BREAKDOWN_TIMEOUT as u32 - 1);
        expect_payment_failed!(nodes[0], our_payment_hash, true);
 
        // Verify that A is able to spend its own HTLC-Timeout tx thanks to spendable output event given back by its ChannelMonitor
        let spend_txn = check_spendable_outputs!(nodes[0], 1, node_cfgs[0].keys_manager, 100000);
        assert_eq!(spend_txn.len(), 3);
        check_spends!(spend_txn[0], local_txn[0]);
+       assert_eq!(spend_txn[1].input.len(), 1);
        check_spends!(spend_txn[1], htlc_timeout);
+       assert_eq!(spend_txn[1].input[0].sequence, BREAKDOWN_TIMEOUT as u32);
+       assert_eq!(spend_txn[2].input.len(), 2);
        check_spends!(spend_txn[2], local_txn[0], htlc_timeout);
+       assert!(spend_txn[2].input[0].sequence == BREAKDOWN_TIMEOUT as u32 ||
+               spend_txn[2].input[1].sequence == BREAKDOWN_TIMEOUT as u32);
 }
 
 #[test]
@@ -5877,7 +5886,7 @@ fn test_key_derivation_params() {
        };
 
        mine_transaction(&nodes[0], &htlc_timeout);
-       connect_blocks(&nodes[0], ANTI_REORG_DELAY - 1);
+       connect_blocks(&nodes[0], BREAKDOWN_TIMEOUT as u32 - 1);
        expect_payment_failed!(nodes[0], our_payment_hash, true);
 
        // Verify that A is able to spend its own HTLC-Timeout tx thanks to spendable output event given back by its ChannelMonitor
@@ -5885,8 +5894,13 @@ fn test_key_derivation_params() {
        let spend_txn = check_spendable_outputs!(nodes[0], 1, new_keys_manager, 100000);
        assert_eq!(spend_txn.len(), 3);
        check_spends!(spend_txn[0], local_txn_1[0]);
+       assert_eq!(spend_txn[1].input.len(), 1);
        check_spends!(spend_txn[1], htlc_timeout);
+       assert_eq!(spend_txn[1].input[0].sequence, BREAKDOWN_TIMEOUT as u32);
+       assert_eq!(spend_txn[2].input.len(), 2);
        check_spends!(spend_txn[2], local_txn_1[0], htlc_timeout);
+       assert!(spend_txn[2].input[0].sequence == BREAKDOWN_TIMEOUT as u32 ||
+               spend_txn[2].input[1].sequence == BREAKDOWN_TIMEOUT as u32);
 }
 
 #[test]
index a5d223c338dfb7a6f2c4bfe1d8efd5801bb873d1..c8c7ad496e4dd3a62ec6e02ee046d89cf03a62f5 100644 (file)
@@ -126,7 +126,8 @@ pub enum Event {
                /// now + 5*time_forwardable).
                time_forwardable: Duration,
        },
-       /// Used to indicate that an output was generated on-chain which you should know how to spend.
+       /// Used to indicate that an output which you should know how to spend was confirmed on chain
+       /// and is now spendable.
        /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
        /// counterparty spending them due to some kind of timeout. Thus, you need to store them
        /// somewhere and spend them when you create on-chain transactions.