X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fln%2Fchannelmanager.rs;h=bcb928cca8f025ceb484b1a5dcaf594fe3158850;hb=8d706789e717797ff37fdf8c999c14a09d2ac9a5;hp=fd156a9ae3166779f05baaed97e9b176bf37a8b3;hpb=8c460c123977b1ab3b6992994811d217693b3343;p=rust-lightning diff --git a/src/ln/channelmanager.rs b/src/ln/channelmanager.rs index fd156a9a..bcb928cc 100644 --- a/src/ln/channelmanager.rs +++ b/src/ln/channelmanager.rs @@ -1,3 +1,13 @@ +//! The top-level channel management and payment tracking stuff lives here. +//! +//! The ChannelManager is the main chunk of logic implementing the lightning protocol and is +//! responsible for tracking which channels are open, HTLCs are in flight and reestablishing those +//! upon reconnect to the relevant peer(s). +//! +//! It does not manage routing logic (see ln::router for that) nor does it manage constructing +//! on-chain transactions (it only monitors the chain to watch for any force-closes that might +//! imply it needs to fail HTLCs/payments/channels it manages). + use bitcoin::blockdata::block::BlockHeader; use bitcoin::blockdata::transaction::Transaction; use bitcoin::blockdata::constants::genesis_block; @@ -16,10 +26,10 @@ use ln::channel::{Channel, ChannelKeys}; use ln::channelmonitor::ManyChannelMonitor; use ln::router::{Route,RouteHop}; use ln::msgs; -use ln::msgs::{HandleError,ChannelMessageHandler,MsgEncodable}; +use ln::msgs::{HandleError,ChannelMessageHandler}; use util::{byte_utils, events, internal_traits, rng}; use util::sha2::Sha256; -use util::ser::Readable; +use util::ser::{Readable, Writeable}; use util::chacha20poly1305rfc::ChaCha20; use util::logger::Logger; use util::errors::APIError; @@ -80,23 +90,6 @@ mod channel_held_info { Fail(HTLCFailureMsg), } - #[cfg(feature = "fuzztarget")] - impl PendingHTLCStatus { - pub fn dummy() -> Self { - let secp_ctx = ::secp256k1::Secp256k1::signing_only(); - PendingHTLCStatus::Forward(PendingForwardHTLCInfo { - onion_packet: None, - incoming_shared_secret: SharedSecret::new(&secp_ctx, - &::secp256k1::key::PublicKey::from_secret_key(&secp_ctx, &SecretKey::from_slice(&secp_ctx, &[1; 32]).unwrap()), - &SecretKey::from_slice(&secp_ctx, &[1; 32]).unwrap()), - payment_hash: [0; 32], - short_channel_id: 0, - amt_to_forward: 0, - outgoing_cltv_value: 0, - }) - } - } - /// Tracks the inbound corresponding to an outbound HTLC #[derive(Clone)] pub struct HTLCPreviousHopData { @@ -114,7 +107,7 @@ mod channel_held_info { session_priv: SecretKey, }, } - #[cfg(any(test, feature = "fuzztarget"))] + #[cfg(test)] impl HTLCSource { pub fn dummy() -> Self { HTLCSource::OutboundRoute { @@ -125,7 +118,7 @@ mod channel_held_info { } #[derive(Clone)] // See Channel::revoke_and_ack for why, tl;dr: Rust bug - pub enum HTLCFailReason { + pub(crate) enum HTLCFailReason { ErrorPacket { err: msgs::OnionErrorPacket, }, @@ -134,20 +127,8 @@ mod channel_held_info { data: Vec, } } - - #[cfg(feature = "fuzztarget")] - impl HTLCFailReason { - pub fn dummy() -> Self { - HTLCFailReason::Reason { - failure_code: 0, data: Vec::new(), - } - } - } } -#[cfg(feature = "fuzztarget")] -pub use self::channel_held_info::*; -#[cfg(not(feature = "fuzztarget"))] -pub(crate) use self::channel_held_info::*; +pub(super) use self::channel_held_info::*; struct MsgHandleErrInternal { err: msgs::HandleError, @@ -244,6 +225,7 @@ const ERR: () = "You need at least 32 bit pointers (well, usize, but we'll assum /// Manager which keeps track of a number of channels and sends messages to the appropriate /// channel, also tracking HTLC preimages and forwarding onion packets appropriately. +/// /// Implements ChannelMessageHandler, handling the multi-channel parts and passing things through /// to individual Channels. pub struct ChannelManager { @@ -287,6 +269,7 @@ struct OnionKeys { mu: [u8; 32], } +/// Details of a channel, as returned by ChannelManager::list_channels and ChannelManager::list_usable_channels pub struct ChannelDetails { /// The channel's ID (prior to funding transaction generation, this is a random 32 bytes, /// thereafter this is the txid of the funding transaction xor the funding transaction output). @@ -296,17 +279,23 @@ pub struct ChannelDetails { /// The position of the funding transaction in the chain. None if the funding transaction has /// not yet been confirmed and the channel fully opened. pub short_channel_id: Option, + /// The node_id of our counterparty pub remote_network_id: PublicKey, + /// The value, in satoshis, of this channel as appears in the funding output pub channel_value_satoshis: u64, /// The user_id passed in to create_channel, or 0 if the channel was inbound. pub user_id: u64, } impl ChannelManager { - /// Constructs a new ChannelManager to hold several channels and route between them. This is - /// the main "logic hub" for all channel-related actions, and implements ChannelMessageHandler. + /// Constructs a new ChannelManager to hold several channels and route between them. + /// + /// This is the main "logic hub" for all channel-related actions, and implements + /// ChannelMessageHandler. + /// /// fee_proportional_millionths is an optional fee to charge any payments routed through us. /// Non-proportional fees are fixed according to our risk using the provided fee estimator. + /// /// panics if channel_value_satoshis is >= `MAX_FUNDING_SATOSHIS`! pub fn new(our_network_key: SecretKey, fee_proportional_millionths: u32, announce_channels_publicly: bool, network: Network, feeest: Arc, monitor: Arc, chain_monitor: Arc, tx_broadcaster: Arc, logger: Arc) -> Result, secp256k1::Error> { let secp_ctx = Secp256k1::new(); @@ -342,12 +331,15 @@ impl ChannelManager { } /// Creates a new outbound channel to the given remote node and with the given value. + /// /// user_id will be provided back as user_channel_id in FundingGenerationReady and /// FundingBroadcastSafe events to allow tracking of which events correspond with which /// create_channel call. Note that user_channel_id defaults to 0 for inbound channels, so you /// may wish to avoid using 0 for user_id here. + /// /// If successful, will generate a SendOpenChannel event, so you should probably poll /// PeerManager::process_events afterwards. + /// /// Raises APIError::APIMisuseError when channel_value_satoshis > 2**24 or push_msat being greater than channel_value_satoshis * 1k pub fn create_channel(&self, their_network_key: PublicKey, channel_value_satoshis: u64, push_msat: u64, user_id: u64) -> Result<(), APIError> { let chan_keys = if cfg!(feature = "fuzztarget") { @@ -373,9 +365,15 @@ impl ChannelManager { let channel = Channel::new_outbound(&*self.fee_estimator, chan_keys, their_network_key, channel_value_satoshis, push_msat, self.announce_channels_publicly, user_id, Arc::clone(&self.logger))?; let res = channel.get_open_channel(self.genesis_hash.clone(), &*self.fee_estimator); let mut channel_state = self.channel_state.lock().unwrap(); - match channel_state.by_id.insert(channel.channel_id(), channel) { - Some(_) => panic!("RNG is bad???"), - None => {} + match channel_state.by_id.entry(channel.channel_id()) { + hash_map::Entry::Occupied(_) => { + if cfg!(feature = "fuzztarget") { + return Err(APIError::APIMisuseError { err: "Fuzzy bad RNG" }); + } else { + panic!("RNG is bad???"); + } + }, + hash_map::Entry::Vacant(entry) => { entry.insert(channel); } } let mut events = self.pending_events.lock().unwrap(); @@ -425,6 +423,7 @@ impl ChannelManager { /// Begins the process of closing a channel. After this call (plus some timeout), no new HTLCs /// will be accepted on the given channel, and after additional timeout/the closing of all /// pending HTLCs, the channel will be closed on chain. + /// /// May generate a SendShutdown event on success, which should be relayed. pub fn close_channel(&self, channel_id: &[u8; 32]) -> Result<(), HandleError> { let (mut res, node_id, chan_option) = { @@ -824,7 +823,7 @@ impl ChannelManager { match msgs::OnionHopData::read(&mut Cursor::new(&decoded[..])) { Err(err) => { let error_code = match err { - msgs::DecodeError::UnknownRealmByte => 0x4000 | 1, + msgs::DecodeError::UnknownVersion => 0x4000 | 1, // unknown realm byte _ => 0x2000 | 2, // Should never happen }; return_err!("Unable to decode our hop data", error_code, &[0;0]); @@ -965,16 +964,19 @@ impl ChannelManager { } /// Sends a payment along a given route. + /// /// Value parameters are provided via the last hop in route, see documentation for RouteHop /// fields for more info. + /// /// Note that if the payment_hash already exists elsewhere (eg you're sending a duplicative /// payment), we don't do anything to stop you! We always try to ensure that if the provided /// next hop knows the preimage to payment_hash they can claim an additional amount as /// specified in the last hop in the route! Thus, you should probably do your own /// payment_preimage tracking (which you should already be doing as they represent "proof of /// payment") and prevent double-sends yourself. - /// See-also docs on Channel::send_htlc_and_commit. + /// /// May generate a SendHTLCs event on success, which should be relayed. + /// /// Raises APIError::RoutError when invalid route or forward parameter /// (cltv_delta, fee, node public key) is specified pub fn send_payment(&self, route: Route, payment_hash: [u8; 32]) -> Result<(), APIError> { @@ -1051,7 +1053,9 @@ impl ChannelManager { } /// Call this upon creation of a funding transaction for the given channel. + /// /// Panics if a funding transaction has already been provided for this channel. + /// /// May panic if the funding_txo is duplicative with some other channel (note that this should /// be trivially prevented by using unique funding transaction keys per-channel). pub fn funding_transaction_generated(&self, temporary_channel_id: &[u8; 32], funding_txo: OutPoint) { @@ -1125,6 +1129,7 @@ impl ChannelManager { } /// Processes HTLCs which are pending waiting on random forward delay. + /// /// Should only really ever be called in response to an PendingHTLCsForwardable event. /// Will likely generate further events. pub fn process_pending_htlc_forwards(&self) { @@ -1341,6 +1346,7 @@ impl ChannelManager { /// Provides a payment preimage in response to a PaymentReceived event, returning true and /// generating message events for the net layer to claim the payment, if possible. Thus, you /// should probably kick the net layer to go send messages if this returns true! + /// /// May panic if called except in response to a PaymentReceived event. pub fn claim_funds(&self, payment_preimage: [u8; 32]) -> bool { let mut sha = Sha256::new(); @@ -2252,11 +2258,12 @@ mod tests { use ln::channelmanager::{ChannelManager,OnionKeys}; use ln::router::{Route, RouteHop, Router}; use ln::msgs; - use ln::msgs::{MsgEncodable,ChannelMessageHandler,RoutingMessageHandler}; + use ln::msgs::{ChannelMessageHandler,RoutingMessageHandler}; use util::test_utils; use util::events::{Event, EventsProvider}; - use util::logger::Logger; use util::errors::APIError; + use util::logger::Logger; + use util::ser::Writeable; use bitcoin::util::hash::Sha256dHash; use bitcoin::blockdata::block::{Block, BlockHeader}; @@ -2455,9 +2462,11 @@ mod tests { } impl Drop for Node { fn drop(&mut self) { - // Check that we processed all pending events - assert_eq!(self.node.get_and_clear_pending_events().len(), 0); - assert_eq!(self.chan_monitor.added_monitors.lock().unwrap().len(), 0); + if !::std::thread::panicking() { + // Check that we processed all pending events + assert_eq!(self.node.get_and_clear_pending_events().len(), 0); + assert_eq!(self.chan_monitor.added_monitors.lock().unwrap().len(), 0); + } } }