Struct lightning::ln::channelmanager::ChannelManager

pub struct ChannelManager<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger,  { /* fields omitted */ }

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.

Implements Writeable to write out all channel state to disk. Implies peer_disconnected() for all peers during write/read (though does not modify this instance, only the instance being serialized). This will result in any channels which have not yet exchanged funding_created (ie called funding_transaction_generated for outbound channels).

Note that you can be a bit lazier about writing out ChannelManager than you can be with ChannelMonitors. With ChannelMonitors you MUST write each monitor update out to disk before returning from chain::Watch::watch_/update_channel, with ChannelManagers, writing updates happens out-of-band (and will prevent any other ChannelManager operations from occurring during the serialization process). If the deserialized version is out-of-date compared to the ChannelMonitors passed by reference to read(), those channels will be force-closed based on the ChannelMonitor state and no funds will be lost (mod on-chain transaction fees).

Note that the deserializer is only implemented for (Sha256dHash, ChannelManager), which tells you the last block hash which was block_connect()ed. You MUST rescan any blocks along the "reorg path" (ie call block_disconnected() until you get to a common block and then call block_connected() to step towards your best block) upon deserialization before using the object!

Note that ChannelManager is responsible for tracking liveness of its channels and generating ChannelUpdate messages informing peers that the channel is temporarily disabled. To avoid spam due to quick disconnection/reconnection, updates are not sent until the channel has been offline for a full minute. In order to track this, you must call timer_chan_freshness_every_min roughly once per minute, though it doesn't have to be perfect.

Rather than using a plain ChannelManager, it is preferable to use either a SimpleArcChannelManager a SimpleRefChannelManager, for conciseness. See their documentation for more details, but essentially you should default to using a SimpleRefChannelManager, and use a SimpleArcChannelManager when you require a ChannelManager with a static lifetime, such as when you're using lightning-net-tokio.

Implementations

impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<ChanSigner, M, T, K, F, L> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger, 

pub fn new(
    network: Network,
    fee_est: F,
    chain_monitor: M,
    tx_broadcaster: T,
    logger: L,
    keys_manager: K,
    config: UserConfig,
    current_blockchain_height: usize
) -> Self

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.

Non-proportional fees are fixed according to our risk using the provided fee estimator.

panics if channel_value_satoshis is >= MAX_FUNDING_SATOSHIS!

Users must provide the current blockchain height from which to track onchain channel funding outpoints and send payments with reliable timelocks.

Users need to notify the new ChannelManager when a new block is connected or disconnected using its block_connected and block_disconnected methods.

pub fn create_channel(
    &self,
    their_network_key: PublicKey,
    channel_value_satoshis: u64,
    push_msat: u64,
    user_id: u64,
    override_config: Option<UserConfig>
) -> Result<(), APIError>

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 message event, so you should probably poll PeerManager::process_events afterwards.

Raises APIError::APIMisuseError when channel_value_satoshis > 2**24 or push_msat is greater than channel_value_satoshis * 1k or channel_value_satoshis is < 1000.

pub fn list_channels(&self) -> Vec<ChannelDetails>

Gets the list of open channels, in random order. See ChannelDetail field documentation for more information.

pub fn list_usable_channels(&self) -> Vec<ChannelDetails>

Gets the list of usable channels, in random order. Useful as an argument to get_route to ensure non-announced channels are used.

These are guaranteed to have their is_live value set to true, see the documentation for ChannelDetails::is_live for more info on exactly what the criteria are.

pub fn close_channel(&self, channel_id: &[u8; 32]) -> Result<(), APIError>

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 message event on success, which should be relayed.

pub fn force_close_channel(&self, channel_id: &[u8; 32])

Force closes a channel, immediately broadcasting the latest local commitment transaction to the chain and rejecting new HTLCs on the given channel.

pub fn force_close_all_channels(&self)

Force close all channels, immediately broadcasting the latest local commitment transaction for each to the chain and rejecting new HTLCs on each.

pub fn send_payment(
    &self,
    route: &Route,
    payment_hash: PaymentHash,
    payment_secret: &Option<PaymentSecret>
) -> Result<(), PaymentSendFailure>

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.

May generate SendHTLCs message(s) event on success, which should be relayed.

Each path may have a different return value, and PaymentSendValue may return a Vec with each entry matching the corresponding-index entry in the route paths, see PaymentSendFailure for more info.

In general, a path may raise:

• APIError::RouteError when an invalid route or forwarding parameter (cltv_delta, fee, node public key) is specified.
• APIError::ChannelUnavailable if the next-hop channel is not available for updates (including due to previous monitor update failure or new permanent monitor update failure).
• APIError::MonitorUpdateFailed if a new monitor update failure prevented sending the relevant updates.

Note that depending on the type of the PaymentSendFailure the HTLC may have been irrevocably committed to on our end. In such a case, do NOT retry the payment with a different route unless you intend to pay twice!

payment_secret is unrelated to payment_hash (or PaymentPreimage) and exists to authenticate the sender to the recipient and prevent payment-probing (deanonymization) attacks. For newer nodes, it will be provided to you in the invoice. If you do not have one, the Route must not contain multiple paths as multi-path payments require a recipient-provided payment_secret. If a payment_secret is provided, we assume that the invoice had the payment_secret feature bit set (either as required or as available). If multiple paths are present in the Route, we assume the invoice had the basic_mpp feature set.

pub fn funding_transaction_generated(
    &self,
    temporary_channel_id: &[u8; 32],
    funding_txo: OutPoint
)

Call this upon creation of a funding transaction for the given channel.

Note that ALL inputs in the transaction pointed to by funding_txo MUST spend SegWit outputs or your counterparty can steal your funds!

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 broadcast_node_announcement(
    &self,
    rgb: [u8; 3],
    alias: [u8; 32],
    addresses: Vec<NetAddress>
)

Generates a signed node_announcement from the given arguments and creates a BroadcastNodeAnnouncement event. Note that such messages will be ignored unless peers have seen a channel_announcement from us (ie unless we have public channels open).

RGB is a node "color" and alias is a printable human-readable string to describe this node to humans. They carry no in-protocol meaning.

addresses represent the set (possibly empty) of socket addresses on which this node accepts incoming connections. These will be broadcast to the network, publicly tying these addresses together. If you wish to preserve user privacy, addresses should likely contain only Tor Onion addresses.

Panics if addresses is absurdly large (more than 500).

pub fn process_pending_htlc_forwards(&self)

Processes HTLCs which are pending waiting on random forward delay.

Should only really ever be called in response to a PendingHTLCsForwardable event. Will likely generate further events.

pub fn timer_chan_freshness_every_min(&self)

If a peer is disconnected we mark any channels with that peer as 'disabled'. After some time, if channels are still disabled we need to broadcast a ChannelUpdate to inform the network about the uselessness of these channels.

This method handles all the details, and must be called roughly once per minute.

pub fn fail_htlc_backwards(
    &self,
    payment_hash: &PaymentHash,
    payment_secret: &Option<PaymentSecret>
) -> bool

Indicates that the preimage for payment_hash is unknown or the received amount is incorrect after a PaymentReceived event, failing the HTLC back to its origin and freeing resources along the path (including in our own channel on which we received it). Returns false if no payment was found to fail backwards, true if the process of failing the HTLC backwards has been started.

pub fn claim_funds(
    &self,
    payment_preimage: PaymentPreimage,
    payment_secret: &Option<PaymentSecret>,
    expected_amount: u64
) -> bool

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!

You must specify the expected amounts for this HTLC, and we will only claim HTLCs available within a few percent of the expected amount. This is critical for several reasons : a) it avoids providing senders with proof-of-payment (in the form of the payment_preimage without having provided the full value and b) it avoids certain privacy-breaking recipient-probing attacks which may reveal payment activity to motivated attackers.

Note that the privacy concerns in (b) are not relevant in payments with a payment_secret set. Thus, for such payments we will claim any payments which do not under-pay.

May panic if called except in response to a PaymentReceived event.

pub fn get_our_node_id(&self) -> PublicKey

Gets the node_id held by this ChannelManager

pub fn channel_monitor_updated(
    &self,
    funding_txo: &OutPoint,
    highest_applied_update_id: u64
)

Restores a single, given channel to normal operation after a ChannelMonitorUpdateErr::TemporaryFailure was returned from a channel monitor update operation.

All ChannelMonitor updates up to and including highest_applied_update_id must have been fully committed in every copy of the given channels' ChannelMonitors.

Note that there is no effect to calling with a highest_applied_update_id other than the current latest ChannelMonitorUpdate and one call to this function after multiple ChannelMonitorUpdateErr::TemporaryFailures is fine. The highest_applied_update_id field exists largely only to prevent races between this and concurrent update_monitor calls.

Thus, the anticipated use is, at a high level:

1. You register a chain::Watch with this ChannelManager,
2. it stores each update to disk, and begins updating any remote (eg watchtower) copies of said ChannelMonitors as it can, returning ChannelMonitorUpdateErr::TemporaryFailures any time it cannot do so instantly,
3. update(s) are applied to each remote copy of a ChannelMonitor,
4. once all remote copies are updated, you call this function with the update_id that completed, and once it is the latest the Channel will be re-enabled.

impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<ChanSigner, M, T, K, F, L> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger, 

pub fn block_connected(
    &self,
    header: &BlockHeader,
    txdata: &TransactionData<'_>,
    height: u32
)

Updates channel state based on transactions seen in a connected block.

pub fn block_disconnected(&self, header: &BlockHeader)

Updates channel state based on a disconnected block.

If necessary, the channel may be force-closed without letting the counterparty participate in the shutdown.

Trait Implementations

impl<ChanSigner: ChannelKeys, M: Deref + Sync + Send, T: Deref + Sync + Send, K: Deref + Sync + Send, F: Deref + Sync + Send, L: Deref + Sync + Send> ChannelMessageHandler for ChannelManager<ChanSigner, M, T, K, F, L> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger, 

pub fn handle_open_channel(
    &self,
    counterparty_node_id: &PublicKey,
    their_features: InitFeatures,
    msg: &OpenChannel
)

Handle an incoming open_channel message from the given peer.

pub fn handle_accept_channel(
    &self,
    counterparty_node_id: &PublicKey,
    their_features: InitFeatures,
    msg: &AcceptChannel
)

Handle an incoming accept_channel message from the given peer.

pub fn handle_funding_created(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &FundingCreated
)

Handle an incoming funding_created message from the given peer.

pub fn handle_funding_signed(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &FundingSigned
)

Handle an incoming funding_signed message from the given peer.

pub fn handle_funding_locked(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &FundingLocked
)

Handle an incoming funding_locked message from the given peer.

pub fn handle_shutdown(&self, counterparty_node_id: &PublicKey, msg: &Shutdown)

Handle an incoming shutdown message from the given peer.

pub fn handle_closing_signed(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &ClosingSigned
)

Handle an incoming closing_signed message from the given peer.

pub fn handle_update_add_htlc(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &UpdateAddHTLC
)

Handle an incoming update_add_htlc message from the given peer.

pub fn handle_update_fulfill_htlc(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &UpdateFulfillHTLC
)

Handle an incoming update_fulfill_htlc message from the given peer.

pub fn handle_update_fail_htlc(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &UpdateFailHTLC
)

Handle an incoming update_fail_htlc message from the given peer.

pub fn handle_update_fail_malformed_htlc(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &UpdateFailMalformedHTLC
)

Handle an incoming update_fail_malformed_htlc message from the given peer.

pub fn handle_commitment_signed(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &CommitmentSigned
)

Handle an incoming commitment_signed message from the given peer.

pub fn handle_revoke_and_ack(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &RevokeAndACK
)

Handle an incoming revoke_and_ack message from the given peer.

pub fn handle_update_fee(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &UpdateFee
)

Handle an incoming update_fee message from the given peer.

pub fn handle_announcement_signatures(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &AnnouncementSignatures
)

Handle an incoming announcement_signatures message from the given peer.

pub fn handle_channel_reestablish(
    &self,
    counterparty_node_id: &PublicKey,
    msg: &ChannelReestablish
)

Handle an incoming channel_reestablish message from the given peer.

pub fn peer_disconnected(
    &self,
    counterparty_node_id: &PublicKey,
    no_connection_possible: bool
)

Indicates a connection to the peer failed/an existing connection was lost. If no connection is believed to be possible in the future (eg they're sending us messages we don't understand or indicate they require unknown feature bits), no_connection_possible is set and any outstanding channels should be failed.

pub fn peer_connected(&self, counterparty_node_id: &PublicKey, init_msg: &Init)

Handle a peer reconnecting, possibly generating channel_reestablish message(s).

pub fn handle_error(&self, counterparty_node_id: &PublicKey, msg: &ErrorMessage)

Handle an incoming error message from the given peer.

impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> EventsProvider for ChannelManager<ChanSigner, M, T, K, F, L> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger, 

pub fn get_and_clear_pending_events(&self) -> Vec<Event>

Gets the list of pending events which were generated by previous actions, clearing the list in the process.

impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> MessageSendEventsProvider for ChannelManager<ChanSigner, M, T, K, F, L> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger, 

pub fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>

Gets the list of pending events which were generated by previous actions, clearing the list in the process.

impl<ChanSigner: ChannelKeys + Writeable, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> Writeable for ChannelManager<ChanSigner, M, T, K, F, L> where
    M::Target: Watch<Keys = ChanSigner>,
    T::Target: BroadcasterInterface,
    K::Target: KeysInterface<ChanKeySigner = ChanSigner>,
    F::Target: FeeEstimator,
    L::Target: Logger, 

pub fn write<W: Writer>(&self, writer: &mut W) -> Result<(), Error>

Writes self out to the given Writer

pub fn encode(&self) -> Vec<u8>

Writes self out to a Vec

pub fn encode_with_len(&self) -> Vec<u8>

Writes self out to a Vec