/// Start a background thread that takes care of responsibilities enumerated in the top-level
/// documentation.
///
- /// If `persist_manager` returns an error, then this thread will return said error (and `start()`
- /// will need to be called again to restart the `BackgroundProcessor`). Users should wait on
- /// [`thread_handle`]'s `join()` method to be able to tell if and when an error is returned, or
- /// implement `persist_manager` such that an error is never returned to the `BackgroundProcessor`
+ /// If `persist_manager` returns an error, then this thread will return said error (and
+ /// `start()` will need to be called again to restart the `BackgroundProcessor`). Users should
+ /// wait on [`thread_handle`]'s `join()` method to be able to tell if and when an error is
+ /// 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
- /// to one or more backup services. See [`ChannelManager::write`] for writing out a `ChannelManager`.
- /// See [`FilesystemPersister::persist_manager`] for Rust-Lightning's provided implementation.
+ /// `persist_manager` is responsible for writing out the [`ChannelManager`] to disk, and/or
+ /// uploading to one or more backup services. See [`ChannelManager::write`] for writing out a
+ /// [`ChannelManager`]. See [`FilesystemPersister::persist_manager`] for Rust-Lightning's
+ /// provided implementation.
///
- /// [`thread_handle`]: struct.BackgroundProcessor.html#structfield.thread_handle
- /// [`ChannelManager::write`]: ../lightning/ln/channelmanager/struct.ChannelManager.html#method.write
- /// [`FilesystemPersister::persist_manager`]: ../lightning_persister/struct.FilesystemPersister.html#impl
+ /// [`thread_handle`]: BackgroundProcessor::thread_handle
+ /// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
+ /// [`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
where Signer: 'static + Sign,
M: 'static + chain::Watch<Signer>,
//!
//! 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.
-//!
-//! [`SpvClient`]: struct.SpvClient.html
-//! [`BlockSource`]: trait.BlockSource.html
#![deny(broken_intra_doc_links)]
#![deny(missing_docs)]
/// When polling a block source, [`Poll`] implementations may pass the height to [`get_header`]
/// to allow for a more efficient lookup.
///
- /// [`Poll`]: poll/trait.Poll.html
- /// [`get_header`]: #tymethod.get_header
+ /// [`get_header`]: Self::get_header
fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)>;
}
/// 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
/// forks reliably, caches may be entirely unnecessary.
-///
-/// [`ChainNotifier`]: struct.ChainNotifier.html
pub trait Cache {
/// Retrieves the block header keyed by the given block hash.
fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>;
/// * `header_cache` is used to look up and store headers on the best chain
/// * `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(
chain_tip: ValidatedBlockHeader,
chain_poller: P,
/// 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 {
/// Cache for looking up headers before fetching from a block source.
header_cache: &'a mut C,
//! update [`ChannelMonitor`]s accordingly. If any on-chain events need further processing, it will
//! 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
//! 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
-//! setup to monitor channels remotely. In the latter case, a custom `chain::Watch` implementation
+//! [`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
//! 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
-//! 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
+//! events. The remote server would make use of [`ChainMonitor`] for block processing and for
+//! servicing [`ChannelMonitor`] updates from the client.
use bitcoin::blockdata::block::{Block, BlockHeader};
/// or used independently to monitor channels remotely. See the [module-level documentation] for
/// details.
///
-/// [`chain::Watch`]: ../trait.Watch.html
-/// [`ChannelManager`]: ../../ln/channelmanager/struct.ChannelManager.html
-/// [module-level documentation]: index.html
+/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+/// [module-level documentation]: crate::chain::chainmonitor
pub struct ChainMonitor<ChannelSigner: Sign, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref>
where C::Target: chain::Filter,
T::Target: BroadcasterInterface,
/// 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
/// 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) {
let monitors = self.monitors.read().unwrap();
for monitor in monitors.values() {
/// 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
/// details.
- ///
- /// [`ChannelMonitor::block_disconnected`]: ../channelmonitor/struct.ChannelMonitor.html#method.block_disconnected
pub fn block_disconnected(&self, header: &BlockHeader, disconnected_height: u32) {
let monitors = self.monitors.read().unwrap();
for monitor in monitors.values() {
/// 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
/// 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 {
Self {
monitors: RwLock::new(HashMap::new()),
///
/// Note that we persist the given `ChannelMonitor` while holding the `ChainMonitor`
/// monitors lock.
- ///
- /// [`chain::Filter`]: ../trait.Filter.html
fn watch_channel(&self, funding_outpoint: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr> {
let mut monitors = self.monitors.write().unwrap();
let entry = match monitors.entry(funding_outpoint) {
//! 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
//! 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::transaction::{TxOut,Transaction};
/// 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
/// its docs for more details.
- ///
- /// [`CLOSED_CHANNEL_UPDATE_ID`]: constant.CLOSED_CHANNEL_UPDATE_ID.html
pub update_id: u64,
}
/// 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
/// preimage claim backward will lead to loss of funds.
-///
-/// [`chain::Watch`]: ../trait.Watch.html
#[derive(Clone, PartialEq)]
pub struct HTLCUpdate {
pub(crate) payment_hash: PaymentHash,
/// 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`].
- ///
- /// [`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> {
self.inner.lock().unwrap().get_and_clear_pending_monitor_events()
}
/// stored channel data). Note that you **must** persist every new monitor to
/// 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.
- ///
- /// [`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>;
/// Update one channel's data. The provided `ChannelMonitor` has already
/// them in batches. The size of each monitor grows `O(number of state updates)`
/// 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
/// [`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>;
}
pub mod keysinterface;
/// An error when accessing the chain via [`Access`].
-///
-/// [`Access`]: trait.Access.html
#[derive(Clone)]
pub enum AccessError {
/// The requested chain is unknown.
/// funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle
/// multiple instances.
///
-/// [`ChannelMonitor`]: channelmonitor/struct.ChannelMonitor.html
-/// [`ChannelMonitorUpdateErr`]: channelmonitor/enum.ChannelMonitorUpdateErr.html
-/// [`PermanentFailure`]: channelmonitor/enum.ChannelMonitorUpdateErr.html#variant.PermanentFailure
+/// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
+/// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr
+/// [`PermanentFailure`]: channelmonitor::ChannelMonitorUpdateErr::PermanentFailure
pub trait Watch<ChannelSigner: Sign>: Send + Sync {
/// Watches a channel identified by `funding_txo` using `monitor`.
///
/// with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
/// calling [`block_connected`] and [`block_disconnected`] on the monitor.
///
- /// [`get_outputs_to_watch`]: channelmonitor/struct.ChannelMonitor.html#method.get_outputs_to_watch
- /// [`block_connected`]: channelmonitor/struct.ChannelMonitor.html#method.block_connected
- /// [`block_disconnected`]: channelmonitor/struct.ChannelMonitor.html#method.block_disconnected
+ /// [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
+ /// [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
+ /// [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
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.
/// Implementations must call [`update_monitor`] with the given update. See
/// [`ChannelMonitorUpdateErr`] for invariants around returning an error.
///
- /// [`update_monitor`]: channelmonitor/struct.ChannelMonitor.html#method.update_monitor
- /// [`ChannelMonitorUpdateErr`]: channelmonitor/enum.ChannelMonitorUpdateErr.html
+ /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
+ /// [`ChannelMonitorUpdateErr`]: channelmonitor::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
///
/// 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
-/// 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`].
///
-/// [`Watch`]: trait.Watch.html
-/// [`TemporaryFailure`]: channelmonitor/enum.ChannelMonitorUpdateErr.html#variant.TemporaryFailure
+/// [`TemporaryFailure`]: channelmonitor::ChannelMonitorUpdateErr::TemporaryFailure
/// [BIP 157]: https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki
/// [BIP 158]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki
pub trait Filter: Send + Sync {
//! 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
//! 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
-//! [`Context`] is used to parameterize [`Features`] and defines which features it can support.
+//! defined internally by a trait specifying the corresponding flags (i.e., even and odd bits).
//!
//! 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
//! 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
-//! [messages]: ../msgs/index.html
-//! [`Features`]: struct.Features.html
-//! [`Context`]: sealed/trait.Context.html
+//! [messages]: crate::ln::msgs
use std::{cmp, fmt};
use std::marker::PhantomData;
/// The context in which [`Features`] are applicable. Defines which features are required and
/// which are optional for the context.
- ///
- /// [`Features`]: ../struct.Features.html
pub trait Context {
/// 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.
/// 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
/// feature identifiers.
- ///
- /// [`Context`]: trait.Context.html
macro_rules! define_context {
($context: ident {
required_features: [$( $( $required_feature: ident )|*, )*],
/// Defines a feature with the given bits for the specified [`Context`]s. The generated trait is
/// useful for manipulating feature flags.
- ///
- /// [`Context`]: trait.Context.html
macro_rules! define_feature {
($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr, $optional_setter: ident,
$required_setter: ident) => {
}
}
- /// Creates features known by the implementation as defined by [`T::KNOWN_FEATURE_FLAGS`].
- ///
- /// [`T::KNOWN_FEATURE_FLAGS`]: sealed/trait.Context.html#associatedconstant.KNOWN_FEATURE_FLAGS
+ /// Creates a Features with the bits set which are known by the implementation
pub fn known() -> Self {
Self {
flags: T::KNOWN_FEATURE_FLAGS.to_vec(),
//! Wire encoding/decoding for Lightning messages according to [BOLT #1].
//!
-//! 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
+//! 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
//! unknown) to use with pattern matching.
//!
//! 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
-//! [`read`]: fn.read.html
-//! [`write`]: fn.write.html
-//! [`Encode`]: trait.Encode.html
-//! [`Message`]: enum.Message.html
use ln::msgs;
use util::ser::{Readable, Writeable, Writer};
-/// 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.
-///
-/// [`read`]: fn.read.html
-/// [`ln::msgs`]: ../msgs/index.html
+/// A Lightning message returned by [`read()`] when decoding bytes received over the wire. Each
+/// variant contains a message from [`msgs`] or otherwise the message type if unknown.
#[allow(missing_docs)]
pub enum Message {
Init(msgs::Init),
/// 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`].
-///
-/// [`Writeable`]: ../../util/ser/trait.Writeable.html
-/// [`write`]: fn.write.html
+/// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write()`].
pub trait Encode {
/// The type identifying the message payload.
const TYPE: u16;
/// Returns the type identifying the message payload. Convenience method for accessing
- /// [`TYPE`](TYPE).
+ /// [`Self::TYPE`].
fn type_id(&self) -> MessageType {
MessageType(Self::TYPE)
}
projects / rust-lightning / commitdiff