documentation fixes

Author: valentinewallace

lightning/src/ln/data_persister.rs

@@ -1,4 +1,4 @@
-//! Logic for persisting data from ChannelMonitors on-disk. Per-platform data
+//! Logic for persisting data from ChannelMonitors on-disk. Sample data
 //! persisters are separated into the lightning-persist-data crate. These
 //! objects mainly interface with the ChainMonitor when a channel monitor is
 //! added or updated, and when they are all synced on startup.
@@ -8,7 +8,7 @@ use chain::transaction::OutPoint;
 use std::collections::HashMap;
 
 /// ChannelDataPersister is responsible for persisting channel data: this could
-/// mean writing once to disk, and/or uploading to several backup services.
+/// mean writing once to disk, and/or uploading to one or more backup services.
 ///
 /// Note that for every new monitor, you **must** persist the new ChannelMonitor
 /// to disk/backups. And, on every update, you **must** persist either the
@@ -19,33 +19,22 @@ use std::collections::HashMap;
 /// are toxic, so it's important that whatever channel state is persisted is
 /// kept up-to-date.
 ///
-/// Upon calls to update_channel_data, implementers of this trait should either
-/// persist the ChannelMonitorUpdate or the ChannelMonitor. If an implementer
-/// chooses to persist the updates only, they need to make sure that all the
-/// updates are applied to the ChannelMonitors *before* the set of channel
-/// monitors is given to the ChainMonitor at startup time (e.g., all monitors
-/// returned by `load_channel_data` must be up-to-date). If full ChannelMonitors
-/// are persisted, then there is no need to persist individual updates.
-///
-/// Note that there could be a performance tradeoff between persisting complete
-/// channel monitors on every update vs. persisting only updates and applying
-/// them in batches.
-///
 /// Given multiple backups, situations may arise where one or more backup sources
 /// have fallen behind or disagree on the current state. Because these backup
 /// sources don't have any transaction signing/broadcasting duties and are only
 /// supposed to be persisting bytes of data, backup sources may be considered
 /// "in consensus" if a majority of them agree on the current state and are on
-/// the highest known commitment number. See individual methods for more info.
+/// the highest known commitment number.
 pub trait ChannelDataPersister: Send + Sync {
 	/// The concrete type which signs for transactions and provides access to our channel public
 	/// keys.
 	type Keys: ChannelKeys;
 
-	/// Persist a new channel's data. The majority of backups should agree on a
-	/// channel's state and be on the latest [`update_id`]. The data
-	/// can be stored with any file name/path, but the identifier provided is the
-	/// channel's outpoint.
+	/// Persist a new channel's data. The data can be stored with any file
+	/// name/path, but the identifier provided is the channel's outpoint.
+	/// Note that you **must** persist every new monitor to disk. See the
+	/// ChannelDataPersister trait documentation for more details, and for
+	/// information on consensus between backups.
 	///
 	/// See [`ChannelMonitor::write_for_disk`] for writing out a ChannelMonitor.
 	///
@@ -58,11 +47,8 @@ pub trait ChannelDataPersister: Send + Sync {
 	///
 	/// Note that on every update, you **must** persist either the
 	/// ChannelMonitorUpdate or the updated monitor itself to disk/backups.
-	/// Otherwise, there is risk of situations such as revoking a transaction,
-	/// then crashing before this revocation can be persisted, then
-	/// unintentionally broadcasting a revoked transaction and losing money. This
-	/// is a risk because previous channel states are toxic, so it's important
-	/// that whatever channel state is persisted is kept up-to-date.
+	/// See the ChannelDataPersister trait documentation for more details, and
+	/// for information on consensus between backups.
 	///
 	/// If an implementer chooses to persist the updates only, they need to make
 	/// sure that all the updates are applied to the ChannelMonitors *before* the
@@ -71,23 +57,24 @@ pub trait ChannelDataPersister: Send + Sync {
 	/// If full ChannelMonitors are persisted, then there is no need to persist
 	/// individual updates.
 	///
-	/// In the case where one or more backups fail, it's likely safe to only
-	/// require that the majority of backups succeed and agree on the latest
-	/// [`update_id`] to succeed this method.
+	/// Note that there could be a performance tradeoff between persisting complete
+	/// channel monitors on every update vs. persisting only updates and applying
+	/// them in batches.
 	///
 	/// See [`ChannelMonitor::write_for_disk`] for writing out a ChannelMonitor
 	/// and [`ChannelMonitorUpdate::write`] for writing out an update.
 	///
 	/// [`load_channel_data`]: trait.ChannelDataPersister.html#tymethod.load_channel_data
-	/// [`update_id`]: struct.ChannelMonitorUpdate.html#structfield.update_id
 	/// [`ChannelMonitor::write_for_disk`]: struct.ChannelMonitor.html#method.write_for_disk
 	/// [`ChannelMonitorUpdate::write`]: struct.ChannelMonitorUpdate.html#method.write
 	fn update_channel_data(&self, id: OutPoint, update: &ChannelMonitorUpdate, data: &ChannelMonitor<Self::Keys>) -> Result<(), ChannelMonitorUpdateErr>;
 
 	/// Load the data for all channels. Generally only called on startup. You must
 	/// ensure that the ChannelMonitors returned are on the latest [`update_id`],
-	/// with all of the updates given in [`update_channel_data`] applied. Otherwise,
-	/// there is a risk of broadcasting a revoked transaction and losing money.
+	/// with all of the updates given in [`update_channel_data`] applied.
+	///
+	/// See the ChannelDataPersister trait documentation for more details, and
+	/// for information on consensus between backups.
 	///
 	/// See [`ChannelMonitor::read`] for deserializing a ChannelMonitor.
 	///