mirrors/rust-lightning
1
0
Fork 0
mirror of https://github.com/lightningdevkit/rust-lightning.git synced 2025-03-03 18:47:47 +01:00
Code Issues Projects Releases Packages Wiki Activity

Drop all HTML-relative links since rustdoc now supports resolution

Browse source
This commit is contained in:
Matt Corallo 2021-03-17 15:53:29 -04:00
parent 2c7c1a6a7a
commit 836985a5e5
7 changed files with 45 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
background-processor/src/lib.rs
View file

@ -48,18 +48,21 @@ impl BackgroundProcessor {
/// Start a background thread that takes care of responsibilities enumerated in the top-level /// Start a background thread that takes care of responsibilities enumerated in the top-level
/// documentation. /// documentation.
/// ///
/// If `persist_manager` returns an error, then this thread will return said error (and `start()` /// If `persist_manager` returns an error, then this thread will return said error (and
/// will need to be called again to restart the `BackgroundProcessor`). Users should wait on /// `start()` will need to be called again to restart the `BackgroundProcessor`). Users should
/// [`thread_handle`]'s `join()` method to be able to tell if and when an error is returned, or /// wait on [`thread_handle`]'s `join()` method to be able to tell if and when an error is
/// implement `persist_manager` such that an error is never returned to the `BackgroundProcessor` /// returned, or implement `persist_manager` such that an error is never returned to the
/// `BackgroundProcessor`
/// ///
/// `persist_manager` is responsible for writing out the `ChannelManager` to disk, and/or uploading /// `persist_manager` is responsible for writing out the [`ChannelManager`] to disk, and/or
/// to one or more backup services. See [`ChannelManager::write`] for writing out a `ChannelManager`. /// uploading to one or more backup services. See [`ChannelManager::write`] for writing out a
/// See [`FilesystemPersister::persist_manager`] for Rust-Lightning's provided implementation. /// [`ChannelManager`]. See [`FilesystemPersister::persist_manager`] for Rust-Lightning's
/// provided implementation.
/// ///
/// [`thread_handle`]: struct.BackgroundProcessor.html#structfield.thread_handle /// [`thread_handle`]: BackgroundProcessor::thread_handle
/// [`ChannelManager::write`]: ../lightning/ln/channelmanager/struct.ChannelManager.html#method.write /// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
/// [`FilesystemPersister::persist_manager`]: ../lightning_persister/struct.FilesystemPersister.html#impl /// [`ChannelManager::write`]: lightning::ln::channelmanager::ChannelManager#impl-Writeable
/// [`FilesystemPersister::persist_manager`]: lightning_persister::FilesystemPersister::persist_manager
pub fn start<PM, Signer, M, T, K, F, L>(persist_manager: PM, manager: Arc<ChannelManager<Signer, Arc<M>, Arc<T>, Arc<K>, Arc<F>, Arc<L>>>, logger: Arc<L>) -> Self pub fn start<PM, Signer, M, T, K, F, L>(persist_manager: PM, manager: Arc<ChannelManager<Signer, Arc<M>, Arc<T>, Arc<K>, Arc<F>, Arc<L>>>, logger: Arc<L>) -> Self
where Signer: 'static + Sign, where Signer: 'static + Sign,
M: 'static + chain::Watch<Signer>, M: 'static + chain::Watch<Signer>,

12
lightning-block-sync/src/lib.rs
View file

@ -12,9 +12,6 @@
//! //!
//! Both features support either blocking I/O using `std::net::TcpStream` or, with feature `tokio`, //! Both features support either blocking I/O using `std::net::TcpStream` or, with feature `tokio`,
//! non-blocking I/O using `tokio::net::TcpStream` from inside a Tokio runtime. //! non-blocking I/O using `tokio::net::TcpStream` from inside a Tokio runtime.
//!
//! [`SpvClient`]: struct.SpvClient.html
//! [`BlockSource`]: trait.BlockSource.html
#![deny(broken_intra_doc_links)] #![deny(broken_intra_doc_links)]
#![deny(missing_docs)] #![deny(missing_docs)]
@ -73,8 +70,7 @@ pub trait BlockSource : Sync + Send {
/// When polling a block source, [`Poll`] implementations may pass the height to [`get_header`] /// When polling a block source, [`Poll`] implementations may pass the height to [`get_header`]
/// to allow for a more efficient lookup. /// to allow for a more efficient lookup.
/// ///
/// [`Poll`]: poll/trait.Poll.html /// [`get_header`]: Self::get_header
/// [`get_header`]: #tymethod.get_header
fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)>; fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)>;
} }
@ -180,8 +176,6 @@ where L::Target: chain::Listen {
/// Implementations may define how long to retain headers such that it's unlikely they will ever be /// Implementations may define how long to retain headers such that it's unlikely they will ever be
/// needed to disconnect a block. In cases where block sources provide access to headers on stale /// needed to disconnect a block. In cases where block sources provide access to headers on stale
/// forks reliably, caches may be entirely unnecessary. /// forks reliably, caches may be entirely unnecessary.
///
/// [`ChainNotifier`]: struct.ChainNotifier.html
pub trait Cache { pub trait Cache {
/// Retrieves the block header keyed by the given block hash. /// Retrieves the block header keyed by the given block hash.
fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>; fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>;
@ -222,7 +216,7 @@ impl<'a, P: Poll, C: Cache, L: Deref> SpvClient<'a, P, C, L> where L::Target: ch
/// * `header_cache` is used to look up and store headers on the best chain /// * `header_cache` is used to look up and store headers on the best chain
/// * `chain_listener` is notified of any blocks connected or disconnected /// * `chain_listener` is notified of any blocks connected or disconnected
/// ///
/// [`poll_best_tip`]: struct.SpvClient.html#method.poll_best_tip /// [`poll_best_tip`]: SpvClient::poll_best_tip
pub fn new( pub fn new(
chain_tip: ValidatedBlockHeader, chain_tip: ValidatedBlockHeader,
chain_poller: P, chain_poller: P,
@ -277,7 +271,7 @@ impl<'a, P: Poll, C: Cache, L: Deref> SpvClient<'a, P, C, L> where L::Target: ch
/// Notifies [listeners] of blocks that have been connected or disconnected from the chain. /// Notifies [listeners] of blocks that have been connected or disconnected from the chain.
/// ///
/// [listeners]: ../../lightning/chain/trait.Listen.html /// [listeners]: lightning::chain::Listen
pub struct ChainNotifier<'a, C: Cache, L: Deref> where L::Target: chain::Listen { pub struct ChainNotifier<'a, C: Cache, L: Deref> where L::Target: chain::Listen {
/// Cache for looking up headers before fetching from a block source. /// Cache for looking up headers before fetching from a block source.
header_cache: &'a mut C, header_cache: &'a mut C,

31
lightning/src/chain/chainmonitor.rs
View file

@ -13,21 +13,15 @@
//! update [`ChannelMonitor`]s accordingly. If any on-chain events need further processing, it will //! update [`ChannelMonitor`]s accordingly. If any on-chain events need further processing, it will
//! make those available as [`MonitorEvent`]s to be consumed. //! make those available as [`MonitorEvent`]s to be consumed.
//! //!
//! `ChainMonitor` is parameterized by an optional chain source, which must implement the //! [`ChainMonitor`] is parameterized by an optional chain source, which must implement the
//! [`chain::Filter`] trait. This provides a mechanism to signal new relevant outputs back to light //! [`chain::Filter`] trait. This provides a mechanism to signal new relevant outputs back to light
//! clients, such that transactions spending those outputs are included in block data. //! clients, such that transactions spending those outputs are included in block data.
//! //!
//! `ChainMonitor` may be used directly to monitor channels locally or as a part of a distributed //! [`ChainMonitor`] may be used directly to monitor channels locally or as a part of a distributed
//! setup to monitor channels remotely. In the latter case, a custom `chain::Watch` implementation //! setup to monitor channels remotely. In the latter case, a custom [`chain::Watch`] implementation
//! would be responsible for routing each update to a remote server and for retrieving monitor //! would be responsible for routing each update to a remote server and for retrieving monitor
//! events. The remote server would make use of `ChainMonitor` for block processing and for //! events. The remote server would make use of [`ChainMonitor`] for block processing and for
//! servicing `ChannelMonitor` updates from the client. //! servicing [`ChannelMonitor`] updates from the client.
//!
//! [`ChainMonitor`]: struct.ChainMonitor.html
//! [`chain::Filter`]: ../trait.Filter.html
//! [`chain::Watch`]: ../trait.Watch.html
//! [`ChannelMonitor`]: ../channelmonitor/struct.ChannelMonitor.html
//! [`MonitorEvent`]: ../channelmonitor/enum.MonitorEvent.html
use bitcoin::blockdata::block::{Block, BlockHeader}; use bitcoin::blockdata::block::{Block, BlockHeader};
@ -53,9 +47,8 @@ use std::ops::Deref;
/// or used independently to monitor channels remotely. See the [module-level documentation] for /// or used independently to monitor channels remotely. See the [module-level documentation] for
/// details. /// details.
/// ///
/// [`chain::Watch`]: ../trait.Watch.html /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
/// [`ChannelManager`]: ../../ln/channelmanager/struct.ChannelManager.html /// [module-level documentation]: crate::chain::chainmonitor
/// [module-level documentation]: index.html
pub struct ChainMonitor<ChannelSigner: Sign, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref> pub struct ChainMonitor<ChannelSigner: Sign, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref>
where C::Target: chain::Filter, where C::Target: chain::Filter,
T::Target: BroadcasterInterface, T::Target: BroadcasterInterface,
@ -88,10 +81,6 @@ where C::Target: chain::Filter,
/// calls must not exclude any transactions matching the new outputs nor any in-block /// calls must not exclude any transactions matching the new outputs nor any in-block
/// descendants of such transactions. It is not necessary to re-fetch the block to obtain /// descendants of such transactions. It is not necessary to re-fetch the block to obtain
/// updated `txdata`. /// updated `txdata`.
///
/// [`ChannelMonitor::block_connected`]: ../channelmonitor/struct.ChannelMonitor.html#method.block_connected
/// [`chain::Watch::release_pending_monitor_events`]: ../trait.Watch.html#tymethod.release_pending_monitor_events
/// [`chain::Filter`]: ../trait.Filter.html
pub fn block_connected(&self, header: &BlockHeader, txdata: &TransactionData, height: u32) { pub fn block_connected(&self, header: &BlockHeader, txdata: &TransactionData, height: u32) {
let monitors = self.monitors.read().unwrap(); let monitors = self.monitors.read().unwrap();
for monitor in monitors.values() { for monitor in monitors.values() {
@ -110,8 +99,6 @@ where C::Target: chain::Filter,
/// Dispatches to per-channel monitors, which are responsible for updating their on-chain view /// Dispatches to per-channel monitors, which are responsible for updating their on-chain view
/// of a channel based on the disconnected block. See [`ChannelMonitor::block_disconnected`] for /// of a channel based on the disconnected block. See [`ChannelMonitor::block_disconnected`] for
/// details. /// details.
///
/// [`ChannelMonitor::block_disconnected`]: ../channelmonitor/struct.ChannelMonitor.html#method.block_disconnected
pub fn block_disconnected(&self, header: &BlockHeader, disconnected_height: u32) { pub fn block_disconnected(&self, header: &BlockHeader, disconnected_height: u32) {
let monitors = self.monitors.read().unwrap(); let monitors = self.monitors.read().unwrap();
for monitor in monitors.values() { for monitor in monitors.values() {
@ -126,8 +113,6 @@ where C::Target: chain::Filter,
/// pre-filter blocks or only fetch blocks matching a compact filter. Otherwise, clients may /// pre-filter blocks or only fetch blocks matching a compact filter. Otherwise, clients may
/// always need to fetch full blocks absent another means for determining which blocks contain /// always need to fetch full blocks absent another means for determining which blocks contain
/// transactions relevant to the watched channels. /// transactions relevant to the watched channels.
///
/// [`chain::Filter`]: ../trait.Filter.html
pub fn new(chain_source: Option<C>, broadcaster: T, logger: L, feeest: F, persister: P) -> Self { pub fn new(chain_source: Option<C>, broadcaster: T, logger: L, feeest: F, persister: P) -> Self {
Self { Self {
monitors: RwLock::new(HashMap::new()), monitors: RwLock::new(HashMap::new()),
@ -174,8 +159,6 @@ where C::Target: chain::Filter,
/// ///
/// Note that we persist the given `ChannelMonitor` while holding the `ChainMonitor` /// Note that we persist the given `ChannelMonitor` while holding the `ChainMonitor`
/// monitors lock. /// monitors lock.
///
/// [`chain::Filter`]: ../trait.Filter.html
fn watch_channel(&self, funding_outpoint: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr> { fn watch_channel(&self, funding_outpoint: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr> {
let mut monitors = self.monitors.write().unwrap(); let mut monitors = self.monitors.write().unwrap();
let entry = match monitors.entry(funding_outpoint) { let entry = match monitors.entry(funding_outpoint) {

20
lightning/src/chain/channelmonitor.rs
View file

@ -19,8 +19,6 @@
//! ChannelMonitors should do so). Thus, if you're building rust-lightning into an HSM or other //! ChannelMonitors should do so). Thus, if you're building rust-lightning into an HSM or other
//! security-domain-separated system design, you should consider having multiple paths for //! security-domain-separated system design, you should consider having multiple paths for
//! ChannelMonitors to get out of the HSM and onto monitoring devices. //! ChannelMonitors to get out of the HSM and onto monitoring devices.
//!
//! [`chain::Watch`]: ../trait.Watch.html
use bitcoin::blockdata::block::{Block, BlockHeader}; use bitcoin::blockdata::block::{Block, BlockHeader};
use bitcoin::blockdata::transaction::{TxOut,Transaction}; use bitcoin::blockdata::transaction::{TxOut,Transaction};
@ -75,8 +73,6 @@ pub struct ChannelMonitorUpdate {
/// The only instance where update_id values are not strictly increasing is the case where we /// The only instance where update_id values are not strictly increasing is the case where we
/// allow post-force-close updates with a special update ID of [`CLOSED_CHANNEL_UPDATE_ID`]. See /// allow post-force-close updates with a special update ID of [`CLOSED_CHANNEL_UPDATE_ID`]. See
/// its docs for more details. /// its docs for more details.
///
/// [`CLOSED_CHANNEL_UPDATE_ID`]: constant.CLOSED_CHANNEL_UPDATE_ID.html
pub update_id: u64, pub update_id: u64,
} }
@ -193,8 +189,6 @@ pub enum MonitorEvent {
/// Simple structure sent back by `chain::Watch` when an HTLC from a forward channel is detected on /// Simple structure sent back by `chain::Watch` when an HTLC from a forward channel is detected on
/// chain. Used to update the corresponding HTLC in the backward channel. Failing to pass the /// chain. Used to update the corresponding HTLC in the backward channel. Failing to pass the
/// preimage claim backward will lead to loss of funds. /// preimage claim backward will lead to loss of funds.
///
/// [`chain::Watch`]: ../trait.Watch.html
#[derive(Clone, PartialEq)] #[derive(Clone, PartialEq)]
pub struct HTLCUpdate { pub struct HTLCUpdate {
pub(crate) payment_hash: PaymentHash, pub(crate) payment_hash: PaymentHash,
@ -1187,8 +1181,6 @@ impl<Signer: Sign> ChannelMonitor<Signer> {
/// Get the list of HTLCs who's status has been updated on chain. This should be called by /// Get the list of HTLCs who's status has been updated on chain. This should be called by
/// ChannelManager via [`chain::Watch::release_pending_monitor_events`]. /// ChannelManager via [`chain::Watch::release_pending_monitor_events`].
///
/// [`chain::Watch::release_pending_monitor_events`]: ../trait.Watch.html#tymethod.release_pending_monitor_events
pub fn get_and_clear_pending_monitor_events(&self) -> Vec<MonitorEvent> { pub fn get_and_clear_pending_monitor_events(&self) -> Vec<MonitorEvent> {
self.inner.lock().unwrap().get_and_clear_pending_monitor_events() self.inner.lock().unwrap().get_and_clear_pending_monitor_events()
} }
@ -2450,11 +2442,8 @@ pub trait Persist<ChannelSigner: Sign>: Send + Sync {
/// stored channel data). Note that you **must** persist every new monitor to /// stored channel data). Note that you **must** persist every new monitor to
/// disk. See the `Persist` trait documentation for more details. /// disk. See the `Persist` trait documentation for more details.
/// ///
/// See [`ChannelMonitor::serialize_for_disk`] for writing out a `ChannelMonitor`, /// See [`ChannelMonitor::write`] for writing out a `ChannelMonitor`,
/// and [`ChannelMonitorUpdateErr`] for requirements when returning errors. /// and [`ChannelMonitorUpdateErr`] for requirements when returning errors.
///
/// [`ChannelMonitor::serialize_for_disk`]: struct.ChannelMonitor.html#method.serialize_for_disk
/// [`ChannelMonitorUpdateErr`]: enum.ChannelMonitorUpdateErr.html
fn persist_new_channel(&self, id: OutPoint, data: &ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>; fn persist_new_channel(&self, id: OutPoint, data: &ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>;
/// Update one channel's data. The provided `ChannelMonitor` has already /// Update one channel's data. The provided `ChannelMonitor` has already
@ -2476,14 +2465,9 @@ pub trait Persist<ChannelSigner: Sign>: Send + Sync {
/// them in batches. The size of each monitor grows `O(number of state updates)` /// them in batches. The size of each monitor grows `O(number of state updates)`
/// whereas updates are small and `O(1)`. /// whereas updates are small and `O(1)`.
/// ///
/// See [`ChannelMonitor::serialize_for_disk`] for writing out a `ChannelMonitor`, /// See [`ChannelMonitor::write`] for writing out a `ChannelMonitor`,
/// [`ChannelMonitorUpdate::write`] for writing out an update, and /// [`ChannelMonitorUpdate::write`] for writing out an update, and
/// [`ChannelMonitorUpdateErr`] for requirements when returning errors. /// [`ChannelMonitorUpdateErr`] for requirements when returning errors.
///
/// [`ChannelMonitor::update_monitor`]: struct.ChannelMonitor.html#impl-1
/// [`ChannelMonitor::serialize_for_disk`]: struct.ChannelMonitor.html#method.serialize_for_disk
/// [`ChannelMonitorUpdate::write`]: struct.ChannelMonitorUpdate.html#method.write
/// [`ChannelMonitorUpdateErr`]: enum.ChannelMonitorUpdateErr.html
fn update_persisted_channel(&self, id: OutPoint, update: &ChannelMonitorUpdate, data: &ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>; fn update_persisted_channel(&self, id: OutPoint, update: &ChannelMonitorUpdate, data: &ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>;
} }

23
lightning/src/chain/mod.rs
View file

@ -25,8 +25,6 @@ pub mod transaction;
pub mod keysinterface; pub mod keysinterface;
/// An error when accessing the chain via [`Access`]. /// An error when accessing the chain via [`Access`].
///
/// [`Access`]: trait.Access.html
#[derive(Clone)] #[derive(Clone)]
pub enum AccessError { pub enum AccessError {
/// The requested chain is unknown. /// The requested chain is unknown.
@ -77,9 +75,9 @@ pub trait Listen {
/// funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle /// funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle
/// multiple instances. /// multiple instances.
/// ///
/// [`ChannelMonitor`]: channelmonitor/struct.ChannelMonitor.html /// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
/// [`ChannelMonitorUpdateErr`]: channelmonitor/enum.ChannelMonitorUpdateErr.html /// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr
/// [`PermanentFailure`]: channelmonitor/enum.ChannelMonitorUpdateErr.html#variant.PermanentFailure /// [`PermanentFailure`]: channelmonitor::ChannelMonitorUpdateErr::PermanentFailure
pub trait Watch<ChannelSigner: Sign>: Send + Sync { pub trait Watch<ChannelSigner: Sign>: Send + Sync {
/// Watches a channel identified by `funding_txo` using `monitor`. /// Watches a channel identified by `funding_txo` using `monitor`.
/// ///
@ -87,9 +85,9 @@ pub trait Watch<ChannelSigner: Sign>: Send + Sync {
/// with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means /// with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
/// calling [`block_connected`] and [`block_disconnected`] on the monitor. /// calling [`block_connected`] and [`block_disconnected`] on the monitor.
/// ///
/// [`get_outputs_to_watch`]: channelmonitor/struct.ChannelMonitor.html#method.get_outputs_to_watch /// [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
/// [`block_connected`]: channelmonitor/struct.ChannelMonitor.html#method.block_connected /// [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
/// [`block_disconnected`]: channelmonitor/struct.ChannelMonitor.html#method.block_disconnected /// [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>; fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>;
/// Updates a channel identified by `funding_txo` by applying `update` to its monitor. /// Updates a channel identified by `funding_txo` by applying `update` to its monitor.
@ -97,8 +95,8 @@ pub trait Watch<ChannelSigner: Sign>: Send + Sync {
/// Implementations must call [`update_monitor`] with the given update. See /// Implementations must call [`update_monitor`] with the given update. See
/// [`ChannelMonitorUpdateErr`] for invariants around returning an error. /// [`ChannelMonitorUpdateErr`] for invariants around returning an error.
/// ///
/// [`update_monitor`]: channelmonitor/struct.ChannelMonitor.html#method.update_monitor /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
/// [`ChannelMonitorUpdateErr`]: channelmonitor/enum.ChannelMonitorUpdateErr.html /// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr
fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> Result<(), ChannelMonitorUpdateErr>; fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> Result<(), ChannelMonitorUpdateErr>;
/// Returns any monitor events since the last call. Subsequent calls must only return new /// Returns any monitor events since the last call. Subsequent calls must only return new
@ -120,11 +118,10 @@ pub trait Watch<ChannelSigner: Sign>: Send + Sync {
/// ///
/// Note that use as part of a [`Watch`] implementation involves reentrancy. Therefore, the `Filter` /// Note that use as part of a [`Watch`] implementation involves reentrancy. Therefore, the `Filter`
/// should not block on I/O. Implementations should instead queue the newly monitored data to be /// should not block on I/O. Implementations should instead queue the newly monitored data to be
/// processed later. Then, in order to block until the data has been processed, any `Watch` /// processed later. Then, in order to block until the data has been processed, any [`Watch`]
/// invocation that has called the `Filter` must return [`TemporaryFailure`]. /// invocation that has called the `Filter` must return [`TemporaryFailure`].
/// ///
/// [`Watch`]: trait.Watch.html /// [`TemporaryFailure`]: channelmonitor::ChannelMonitorUpdateErr::TemporaryFailure
/// [`TemporaryFailure`]: channelmonitor/enum.ChannelMonitorUpdateErr.html#variant.TemporaryFailure
/// [BIP 157]: https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki /// [BIP 157]: https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki
/// [BIP 158]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki /// [BIP 158]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki
pub trait Filter: Send + Sync { pub trait Filter: Send + Sync {

17
lightning/src/ln/features.rs
View file

@ -12,8 +12,7 @@
//! Lightning nodes advertise a supported set of operation through feature flags. Features are //! Lightning nodes advertise a supported set of operation through feature flags. Features are
//! applicable for a specific context as indicated in some [messages]. [`Features`] encapsulates //! applicable for a specific context as indicated in some [messages]. [`Features`] encapsulates
//! behavior for specifying and checking feature flags for a particular context. Each feature is //! behavior for specifying and checking feature flags for a particular context. Each feature is
//! defined internally by a trait specifying the corresponding flags (i.e., even and odd bits). A //! defined internally by a trait specifying the corresponding flags (i.e., even and odd bits).
//! [`Context`] is used to parameterize [`Features`] and defines which features it can support.
//! //!
//! Whether a feature is considered "known" or "unknown" is relative to the implementation, whereas //! Whether a feature is considered "known" or "unknown" is relative to the implementation, whereas
//! the term "supports" is used in reference to a particular set of [`Features`]. That is, a node //! the term "supports" is used in reference to a particular set of [`Features`]. That is, a node
@ -21,9 +20,7 @@
//! And the implementation can interpret a feature if the feature is known to it. //! And the implementation can interpret a feature if the feature is known to it.
//! //!
//! [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md //! [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md
//! [messages]: ../msgs/index.html //! [messages]: crate::ln::msgs
//! [`Features`]: struct.Features.html
//! [`Context`]: sealed/trait.Context.html
use std::{cmp, fmt}; use std::{cmp, fmt};
use std::marker::PhantomData; use std::marker::PhantomData;
@ -36,8 +33,6 @@ mod sealed {
/// The context in which [`Features`] are applicable. Defines which features are required and /// The context in which [`Features`] are applicable. Defines which features are required and
/// which are optional for the context. /// which are optional for the context.
///
/// [`Features`]: ../struct.Features.html
pub trait Context { pub trait Context {
/// Features that are known to the implementation, where a required feature is indicated by /// Features that are known to the implementation, where a required feature is indicated by
/// its even bit and an optional feature is indicated by its odd bit. /// its even bit and an optional feature is indicated by its odd bit.
@ -51,8 +46,6 @@ mod sealed {
/// Defines a [`Context`] by stating which features it requires and which are optional. Features /// Defines a [`Context`] by stating which features it requires and which are optional. Features
/// are specified as a comma-separated list of bytes where each byte is a pipe-delimited list of /// are specified as a comma-separated list of bytes where each byte is a pipe-delimited list of
/// feature identifiers. /// feature identifiers.
///
/// [`Context`]: trait.Context.html
macro_rules! define_context { macro_rules! define_context {
($context: ident { ($context: ident {
required_features: [$( $( $required_feature: ident )|*, )*], required_features: [$( $( $required_feature: ident )|*, )*],
@ -156,8 +149,6 @@ mod sealed {
/// Defines a feature with the given bits for the specified [`Context`]s. The generated trait is /// Defines a feature with the given bits for the specified [`Context`]s. The generated trait is
/// useful for manipulating feature flags. /// useful for manipulating feature flags.
///
/// [`Context`]: trait.Context.html
macro_rules! define_feature { macro_rules! define_feature {
($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr, $optional_setter: ident, ($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr, $optional_setter: ident,
$required_setter: ident) => { $required_setter: ident) => {
@ -413,9 +404,7 @@ impl<T: sealed::Context> Features<T> {
} }
} }
/// Creates features known by the implementation as defined by [`T::KNOWN_FEATURE_FLAGS`]. /// Creates a Features with the bits set which are known by the implementation
///
/// [`T::KNOWN_FEATURE_FLAGS`]: sealed/trait.Context.html#associatedconstant.KNOWN_FEATURE_FLAGS
pub fn known() -> Self { pub fn known() -> Self {
Self { Self {
flags: T::KNOWN_FEATURE_FLAGS.to_vec(), flags: T::KNOWN_FEATURE_FLAGS.to_vec(),

24
lightning/src/ln/wire.rs
View file

@ -9,27 +9,20 @@
//! Wire encoding/decoding for Lightning messages according to [BOLT #1]. //! Wire encoding/decoding for Lightning messages according to [BOLT #1].
//! //!
//! Messages known by this module can be read from the wire using [`read`]. //! Messages known by this module can be read from the wire using [`read()`].
//! The [`Message`] enum returned by [`read`] wraps the decoded message or the message type (if //! The [`Message`] enum returned by [`read()`] wraps the decoded message or the message type (if
//! unknown) to use with pattern matching. //! unknown) to use with pattern matching.
//! //!
//! Messages implementing the [`Encode`] trait define a message type and can be sent over the wire //! Messages implementing the [`Encode`] trait define a message type and can be sent over the wire
//! using [`write`]. //! using [`write()`].
//! //!
//! [BOLT #1]: https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md //! [BOLT #1]: https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md
//! [`read`]: fn.read.html
//! [`write`]: fn.write.html
//! [`Encode`]: trait.Encode.html
//! [`Message`]: enum.Message.html
use ln::msgs; use ln::msgs;
use util::ser::{Readable, Writeable, Writer}; use util::ser::{Readable, Writeable, Writer};
/// A Lightning message returned by [`read`] when decoding bytes received over the wire. Each /// A Lightning message returned by [`read()`] when decoding bytes received over the wire. Each
/// variant contains a message from [`ln::msgs`] or otherwise the message type if unknown. /// variant contains a message from [`msgs`] or otherwise the message type if unknown.
///
/// [`read`]: fn.read.html
/// [`ln::msgs`]: ../msgs/index.html
#[allow(missing_docs)] #[allow(missing_docs)]
pub enum Message { pub enum Message {
Init(msgs::Init), Init(msgs::Init),
@ -230,16 +223,13 @@ pub fn write<M: Encode + Writeable, W: Writer>(message: &M, buffer: &mut W) -> R
/// Defines a type-identified encoding for sending messages over the wire. /// Defines a type-identified encoding for sending messages over the wire.
/// ///
/// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write`]. /// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write()`].
///
/// [`Writeable`]: ../../util/ser/trait.Writeable.html
/// [`write`]: fn.write.html
pub trait Encode { pub trait Encode {
/// The type identifying the message payload. /// The type identifying the message payload.
const TYPE: u16; const TYPE: u16;
/// Returns the type identifying the message payload. Convenience method for accessing /// Returns the type identifying the message payload. Convenience method for accessing
/// [`TYPE`](TYPE). /// [`Self::TYPE`].
fn type_id(&self) -> MessageType { fn type_id(&self) -> MessageType {
MessageType(Self::TYPE) MessageType(Self::TYPE)
} }