use chain;
use chain::{Filter, WatchedOutput};
use chain::chaininterface::{BroadcasterInterface, FeeEstimator};
-use chain::channelmonitor;
-use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateErr, Balance, MonitorEvent, Persist, TransactionOutputs};
+use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateErr, Balance, MonitorEvent, TransactionOutputs};
use chain::transaction::{OutPoint, TransactionData};
use chain::keysinterface::Sign;
use util::logger::Logger;
use sync::RwLock;
use core::ops::Deref;
+/// `Persist` defines behavior for persisting channel monitors: this could 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
+/// `ChannelMonitorUpdate` or the updated monitor itself. 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.
+pub trait Persist<ChannelSigner: Sign> {
+ /// Persist a new channel's data. The data can be stored any way you want, but
+ /// the identifier provided by Rust-Lightning is the channel's outpoint (and
+ /// it is up to you to maintain a correct mapping between the outpoint and the
+ /// stored channel data). Note that you **must** persist every new monitor to
+ /// disk. See the `Persist` trait documentation for more details.
+ ///
+ /// See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
+ /// and [`ChannelMonitorUpdateErr`] for requirements when returning errors.
+ ///
+ /// [`Writeable::write`]: crate::util::ser::Writeable::write
+ fn persist_new_channel(&self, id: OutPoint, data: &ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>;
+
+ /// Update one channel's data. The provided `ChannelMonitor` has already
+ /// applied the given update.
+ ///
+ /// Note that on every update, you **must** persist either the
+ /// `ChannelMonitorUpdate` or the updated monitor itself to disk/backups. See
+ /// the `Persist` trait documentation for more details.
+ ///
+ /// 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 `ChannelManager`
+ /// deserialization routine. See [`ChannelMonitor::update_monitor`] for
+ /// applying a monitor update to a monitor. 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. The size of each monitor grows `O(number of state updates)`
+ /// whereas updates are small and `O(1)`.
+ ///
+ /// See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
+ /// [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
+ /// [`ChannelMonitorUpdateErr`] for requirements when returning errors.
+ ///
+ /// [`Writeable::write`]: crate::util::ser::Writeable::write
+ fn update_persisted_channel(&self, id: OutPoint, update: &ChannelMonitorUpdate, data: &ChannelMonitor<ChannelSigner>) -> Result<(), ChannelMonitorUpdateErr>;
+}
+
/// An implementation of [`chain::Watch`] for monitoring channels.
///
/// Connected and disconnected blocks must be provided to `ChainMonitor` as documented by
T::Target: BroadcasterInterface,
F::Target: FeeEstimator,
L::Target: Logger,
- P::Target: channelmonitor::Persist<ChannelSigner>,
+ P::Target: Persist<ChannelSigner>,
{
/// The monitors
pub monitors: RwLock<HashMap<OutPoint, ChannelMonitor<ChannelSigner>>>,
T::Target: BroadcasterInterface,
F::Target: FeeEstimator,
L::Target: Logger,
- P::Target: channelmonitor::Persist<ChannelSigner>,
+ P::Target: Persist<ChannelSigner>,
{
/// Dispatches to per-channel monitors, which are responsible for updating their on-chain view
/// of a channel and reacting accordingly based on transactions in the given chain data. See
T::Target: BroadcasterInterface,
F::Target: FeeEstimator,
L::Target: Logger,
- P::Target: channelmonitor::Persist<ChannelSigner>,
+ P::Target: Persist<ChannelSigner>,
{
fn block_connected(&self, block: &Block, height: u32) {
let header = &block.header;
T::Target: BroadcasterInterface,
F::Target: FeeEstimator,
L::Target: Logger,
- P::Target: channelmonitor::Persist<ChannelSigner>,
+ P::Target: Persist<ChannelSigner>,
{
fn transactions_confirmed(&self, header: &BlockHeader, txdata: &TransactionData, height: u32) {
log_debug!(self.logger, "{} provided transactions confirmed at height {} in block {}", txdata.len(), height, header.block_hash());
T::Target: BroadcasterInterface,
F::Target: FeeEstimator,
L::Target: Logger,
- P::Target: channelmonitor::Persist<ChannelSigner>,
+ P::Target: Persist<ChannelSigner>,
{
/// Adds the monitor that watches the channel referred to by the given outpoint.
///
T::Target: BroadcasterInterface,
F::Target: FeeEstimator,
L::Target: Logger,
- P::Target: channelmonitor::Persist<ChannelSigner>,
+ P::Target: Persist<ChannelSigner>,
{
/// Processes [`SpendableOutputs`] events produced from each [`ChannelMonitor`] upon maturity.
///