Struct lightning::ln::channelmanager::ChannelManager

pub struct ChannelManager<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>
where
    M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>,
    T::Target: BroadcasterInterface,
    ES::Target: EntropySource,
    NS::Target: NodeSigner,
    SP::Target: SignerProvider,
    F::Target: FeeEstimator,
    R::Target: Router,
    L::Target: Logger,
{ /* private fields */ }

A lightning node’s channel state machine and payment management logic, which facilitates sending, forwarding, and receiving payments through lightning channels.

ChannelManager is parameterized by a number of components to achieve this.

• chain::Watch (typically ChainMonitor) for on-chain monitoring and enforcement of each channel
• BroadcasterInterface for broadcasting transactions related to opening, funding, and closing channels
• EntropySource for providing random data needed for cryptographic operations
• NodeSigner for cryptographic operations scoped to the node
• SignerProvider for providing signers whose operations are scoped to individual channels
• FeeEstimator to determine transaction fee rates needed to have a transaction mined in a timely manner
• Router for finding payment paths when initiating and retrying payments
• Logger for logging operational information of varying degrees

Additionally, it implements the following traits:

• ChannelMessageHandler to handle off-chain channel activity from peers
• MessageSendEventsProvider to similarly send such messages to peers
• OffersMessageHandler for BOLT 12 message handling and sending
• EventsProvider to generate user-actionable Events
• chain::Listen and chain::Confirm for notification of on-chain activity

Thus, ChannelManager is typically used to parameterize a MessageHandler and an OnionMessenger. The latter is required to support BOLT 12 functionality.

ChannelManager vs ChannelMonitor

It’s important to distinguish between the off-chain management and on-chain enforcement of lightning channels. ChannelManager exchanges messages with peers to manage the off-chain state of each channel. During this process, it generates a ChannelMonitor for each channel and a ChannelMonitorUpdate for each relevant change, notifying its parameterized chain::Watch of them.

An implementation of chain::Watch, such as ChainMonitor, is responsible for aggregating these ChannelMonitors and applying any ChannelMonitorUpdates to them. It then monitors for any pertinent on-chain activity, enforcing claims as needed.

This division of off-chain management and on-chain enforcement allows for interesting node setups. For instance, on-chain enforcement could be moved to a separate host or have added redundancy, possibly as a watchtower. See chain::Watch for the relevant interface.

Initialization

Use ChannelManager::new with the most recent BlockHash when creating a fresh instance. Otherwise, if restarting, construct ChannelManagerReadArgs with the necessary parameters and references to any deserialized ChannelMonitors that were previously persisted. Use this to deserialize the ChannelManager and feed it any new chain data since it was last online, as detailed in the ChannelManagerReadArgs documentation.

use bitcoin::BlockHash;
use bitcoin::network::constants::Network;
use lightning::chain::BestBlock;
use lightning::ln::channelmanager::{ChainParameters, ChannelManager, ChannelManagerReadArgs};
use lightning::util::config::UserConfig;
use lightning::util::ser::ReadableArgs;

// Fresh start with no channels
let params = ChainParameters {
    network: Network::Bitcoin,
    best_block,
};
let default_config = UserConfig::default();
let channel_manager = ChannelManager::new(
    fee_estimator, chain_monitor, tx_broadcaster, router, logger, entropy_source, node_signer,
    signer_provider, default_config, params, current_timestamp
);

// Restart from deserialized data
let mut channel_monitors = read_channel_monitors();
let args = ChannelManagerReadArgs::new(
    entropy_source, node_signer, signer_provider, fee_estimator, chain_monitor, tx_broadcaster,
    router, logger, default_config, channel_monitors.iter_mut().collect()
);
let (block_hash, channel_manager) =
    <(BlockHash, ChannelManager<_, _, _, _, _, _, _, _>)>::read(&mut reader, args)?;

// Update the ChannelManager and ChannelMonitors with the latest chain data
// ...

// Move the monitors to the ChannelManager's chain::Watch parameter
for monitor in channel_monitors {
    chain_monitor.watch_channel(monitor.get_funding_txo().0, monitor);
}

Operation

The following is required for ChannelManager to function properly:

• Handle messages from peers using its ChannelMessageHandler implementation (typically called by PeerManager::read_event when processing network I/O)
• Send messages to peers obtained via its MessageSendEventsProvider implementation (typically initiated when PeerManager::process_events is called)
• Feed on-chain activity using either its chain::Listen or chain::Confirm implementation as documented by those traits
• Perform any periodic channel and payment checks by calling timer_tick_occurred roughly every minute
• Persist to disk whenever get_and_clear_needs_persistence returns true using a Persister such as a KVStore implementation
• Handle Events obtained via its EventsProvider implementation

The Future returned by get_event_or_persistence_needed_future is useful in determining when the last two requirements need to be checked.

The lightning-block-sync and lightning-transaction-sync crates provide utilities that simplify feeding in on-chain activity using the chain::Listen and chain::Confirm traits, respectively. The remaining requirements can be met using the lightning-background-processor crate. For languages other than Rust, the availability of similar utilities may vary.

Channels

ChannelManager’s primary function involves managing a channel state. Without channels, payments can’t be sent. Use list_channels or list_usable_channels for a snapshot of the currently open channels.

let channels = channel_manager.list_usable_channels();
for details in channels {
    println!("{:?}", details);
}

Each channel is identified using a ChannelId, which will change throughout the channel’s life cycle. Additionally, channels are assigned a user_channel_id, which is given in Events associated with the channel and serves as a fixed identifier but is otherwise unused by ChannelManager.

Opening Channels

To an open a channel with a peer, call create_channel. This will initiate the process of opening an outbound channel, which requires self-funding when handling Event::FundingGenerationReady.

let value_sats = 1_000_000;
let push_msats = 10_000_000;
match channel_manager.create_channel(peer_id, value_sats, push_msats, 42, None, None) {
    Ok(channel_id) => println!("Opening channel {}", channel_id),
    Err(e) => println!("Error opening channel: {:?}", e),
}

// On the event processing thread once the peer has responded
channel_manager.process_pending_events(&|event| match event {
    Event::FundingGenerationReady {
        temporary_channel_id, counterparty_node_id, channel_value_satoshis, output_script,
        user_channel_id, ..
    } => {
        assert_eq!(user_channel_id, 42);
        let funding_transaction = wallet.create_funding_transaction(
            channel_value_satoshis, output_script
        );
        match channel_manager.funding_transaction_generated(
            &temporary_channel_id, &counterparty_node_id, funding_transaction
        ) {
            Ok(()) => println!("Funding channel {}", temporary_channel_id),
            Err(e) => println!("Error funding channel {}: {:?}", temporary_channel_id, e),
        }
    },
    Event::ChannelPending { channel_id, user_channel_id, former_temporary_channel_id, .. } => {
        assert_eq!(user_channel_id, 42);
        println!(
            "Channel {} now {} pending (funding transaction has been broadcasted)", channel_id,
            former_temporary_channel_id.unwrap()
        );
    },
    Event::ChannelReady { channel_id, user_channel_id, .. } => {
        assert_eq!(user_channel_id, 42);
        println!("Channel {} ready", channel_id);
    },
    // ...
});

Accepting Channels

Inbound channels are initiated by peers and are automatically accepted unless ChannelManager has UserConfig::manually_accept_inbound_channels set. In that case, the channel may be either accepted or rejected when handling Event::OpenChannelRequest.

channel_manager.process_pending_events(&|event| match event {
    Event::OpenChannelRequest { temporary_channel_id, counterparty_node_id, ..  } => {
        if !is_trusted(counterparty_node_id) {
            match channel_manager.force_close_without_broadcasting_txn(
                &temporary_channel_id, &counterparty_node_id
            ) {
                Ok(()) => println!("Rejecting channel {}", temporary_channel_id),
                Err(e) => println!("Error rejecting channel {}: {:?}", temporary_channel_id, e),
            }
            return;
        }

        let user_channel_id = 43;
        match channel_manager.accept_inbound_channel(
            &temporary_channel_id, &counterparty_node_id, user_channel_id
        ) {
            Ok(()) => println!("Accepting channel {}", temporary_channel_id),
            Err(e) => println!("Error accepting channel {}: {:?}", temporary_channel_id, e),
        }
    },
    // ...
});

Closing Channels

There are two ways to close a channel: either cooperatively using close_channel or unilaterally using force_close_broadcasting_latest_txn. The former is ideal as it makes for lower fees and immediate access to funds. However, the latter may be necessary if the counterparty isn’t behaving properly or has gone offline. Event::ChannelClosed is generated once the channel has been closed successfully.

match channel_manager.close_channel(&channel_id, &counterparty_node_id) {
    Ok(()) => println!("Closing channel {}", channel_id),
    Err(e) => println!("Error closing channel {}: {:?}", channel_id, e),
}

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::ChannelClosed { channel_id, user_channel_id, ..  } => {
        assert_eq!(user_channel_id, 42);
        println!("Channel {} closed", channel_id);
    },
    // ...
});

Payments

ChannelManager is responsible for sending, forwarding, and receiving payments through its channels. A payment is typically initiated from a BOLT 11 invoice or a BOLT 12 offer, though spontaneous (i.e., keysend) payments are also possible. Incoming payments don’t require maintaining any additional state as ChannelManager can reconstruct the PaymentPreimage from the PaymentSecret. Sending payments, however, require tracking in order to retry failed HTLCs.

After a payment is initiated, it will appear in list_recent_payments until a short time after either an Event::PaymentSent or Event::PaymentFailed is handled. Failed HTLCs for a payment will be retried according to the payment’s Retry strategy or until abandon_payment is called.

BOLT 11 Invoices

The lightning-invoice crate is useful for creating BOLT 11 invoices. Specifically, use the functions in its utils module for constructing invoices that are compatible with ChannelManager. These functions serve as a convenience for building invoices with the PaymentHash and PaymentSecret returned from create_inbound_payment. To provide your own PaymentHash, use create_inbound_payment_for_hash or the corresponding functions in the lightning-invoice utils module.

ChannelManager generates an Event::PaymentClaimable once the full payment has been received. Call claim_funds to release the PaymentPreimage, which in turn will result in an Event::PaymentClaimed.

// Or use utils::create_invoice_from_channelmanager
let known_payment_hash = match channel_manager.create_inbound_payment(
    Some(10_000_000), 3600, None
) {
    Ok((payment_hash, _payment_secret)) => {
        println!("Creating inbound payment {}", payment_hash);
        payment_hash
    },
    Err(()) => panic!("Error creating inbound payment"),
};

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::PaymentClaimable { payment_hash, purpose, .. } => match purpose {
        PaymentPurpose::Bolt11InvoicePayment { payment_preimage: Some(payment_preimage), .. } => {
            assert_eq!(payment_hash, known_payment_hash);
            println!("Claiming payment {}", payment_hash);
            channel_manager.claim_funds(payment_preimage);
        },
        PaymentPurpose::Bolt11InvoicePayment { payment_preimage: None, .. } => {
            println!("Unknown payment hash: {}", payment_hash);
        },
        PaymentPurpose::SpontaneousPayment(payment_preimage) => {
            assert_ne!(payment_hash, known_payment_hash);
            println!("Claiming spontaneous payment {}", payment_hash);
            channel_manager.claim_funds(payment_preimage);
        },
        // ...
    },
    Event::PaymentClaimed { payment_hash, amount_msat, .. } => {
        assert_eq!(payment_hash, known_payment_hash);
        println!("Claimed {} msats", amount_msat);
    },
    // ...
});

For paying an invoice, lightning-invoice provides a payment module with convenience functions for use with send_payment.

// let (payment_hash, recipient_onion, route_params) =
//     payment::payment_parameters_from_invoice(&invoice);
let payment_id = PaymentId([42; 32]);
match channel_manager.send_payment(
    payment_hash, recipient_onion, payment_id, route_params, retry
) {
    Ok(()) => println!("Sending payment with hash {}", payment_hash),
    Err(e) => println!("Failed sending payment with hash {}: {:?}", payment_hash, e),
}

let expected_payment_id = payment_id;
let expected_payment_hash = payment_hash;
assert!(
    channel_manager.list_recent_payments().iter().find(|details| matches!(
        details,
        RecentPaymentDetails::Pending {
            payment_id: expected_payment_id,
            payment_hash: expected_payment_hash,
            ..
        }
    )).is_some()
);

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::PaymentSent { payment_hash, .. } => println!("Paid {}", payment_hash),
    Event::PaymentFailed { payment_hash, .. } => println!("Failed paying {}", payment_hash),
    // ...
});

BOLT 12 Offers

The offers module is useful for creating BOLT 12 offers. An Offer is a precursor to a Bolt12Invoice, which must first be requested by the payer. The interchange of these messages as defined in the specification is handled by ChannelManager and its implementation of OffersMessageHandler. However, this only works with an Offer created using a builder returned by create_offer_builder. With this approach, BOLT 12 offers and invoices are stateless just as BOLT 11 invoices are.

let offer = channel_manager
    .create_offer_builder()?
    .description("coffee".to_string())
    .amount_msats(10_000_000)
    .build()?;
let bech32_offer = offer.to_string();

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::PaymentClaimable { payment_hash, purpose, .. } => match purpose {
        PaymentPurpose::Bolt12OfferPayment { payment_preimage: Some(payment_preimage), .. } => {
            println!("Claiming payment {}", payment_hash);
            channel_manager.claim_funds(payment_preimage);
        },
        PaymentPurpose::Bolt12OfferPayment { payment_preimage: None, .. } => {
            println!("Unknown payment hash: {}", payment_hash);
        },
        // ...
    },
    Event::PaymentClaimed { payment_hash, amount_msat, .. } => {
        println!("Claimed {} msats", amount_msat);
    },
    // ...
});

Use pay_for_offer to initiated payment, which sends an InvoiceRequest for an Offer and pays the Bolt12Invoice response. In addition to success and failure events, ChannelManager may also generate an Event::InvoiceRequestFailed.

let payment_id = PaymentId([42; 32]);
match channel_manager.pay_for_offer(
    offer, quantity, amount_msats, payer_note, payment_id, retry, max_total_routing_fee_msat
) {
    Ok(()) => println!("Requesting invoice for offer"),
    Err(e) => println!("Unable to request invoice for offer: {:?}", e),
}

// First the payment will be waiting on an invoice
let expected_payment_id = payment_id;
assert!(
    channel_manager.list_recent_payments().iter().find(|details| matches!(
        details,
        RecentPaymentDetails::AwaitingInvoice { payment_id: expected_payment_id }
    )).is_some()
);

// Once the invoice is received, a payment will be sent
assert!(
    channel_manager.list_recent_payments().iter().find(|details| matches!(
        details,
        RecentPaymentDetails::Pending { payment_id: expected_payment_id, ..  }
    )).is_some()
);

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::PaymentSent { payment_id: Some(payment_id), .. } => println!("Paid {}", payment_id),
    Event::PaymentFailed { payment_id, .. } => println!("Failed paying {}", payment_id),
    Event::InvoiceRequestFailed { payment_id, .. } => println!("Failed paying {}", payment_id),
    // ...
});

BOLT 12 Refunds

A Refund is a request for an invoice to be paid. Like paying for an Offer, creating a Refund involves maintaining state since it represents a future outbound payment. Therefore, use create_refund_builder when creating one, otherwise ChannelManager will refuse to pay any corresponding Bolt12Invoice that it receives.

let payment_id = PaymentId([42; 32]);
let refund = channel_manager
    .create_refund_builder(
        amount_msats, absolute_expiry, payment_id, retry, max_total_routing_fee_msat
    )?
    .description("coffee".to_string())
    .payer_note("refund for order 1234".to_string())
    .build()?;
let bech32_refund = refund.to_string();

// First the payment will be waiting on an invoice
let expected_payment_id = payment_id;
assert!(
    channel_manager.list_recent_payments().iter().find(|details| matches!(
        details,
        RecentPaymentDetails::AwaitingInvoice { payment_id: expected_payment_id }
    )).is_some()
);

// Once the invoice is received, a payment will be sent
assert!(
    channel_manager.list_recent_payments().iter().find(|details| matches!(
        details,
        RecentPaymentDetails::Pending { payment_id: expected_payment_id, ..  }
    )).is_some()
);

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::PaymentSent { payment_id: Some(payment_id), .. } => println!("Paid {}", payment_id),
    Event::PaymentFailed { payment_id, .. } => println!("Failed paying {}", payment_id),
    // ...
});

Use request_refund_payment to send a Bolt12Invoice for receiving the refund. Similar to creating an Offer, this is stateless as it represents an inbound payment.

let known_payment_hash = match channel_manager.request_refund_payment(refund) {
    Ok(invoice) => {
        let payment_hash = invoice.payment_hash();
        println!("Requesting refund payment {}", payment_hash);
        payment_hash
    },
    Err(e) => panic!("Unable to request payment for refund: {:?}", e),
};

// On the event processing thread
channel_manager.process_pending_events(&|event| match event {
    Event::PaymentClaimable { payment_hash, purpose, .. } => match purpose {
    	PaymentPurpose::Bolt12RefundPayment { payment_preimage: Some(payment_preimage), .. } => {
            assert_eq!(payment_hash, known_payment_hash);
            println!("Claiming payment {}", payment_hash);
            channel_manager.claim_funds(payment_preimage);
        },
    	PaymentPurpose::Bolt12RefundPayment { payment_preimage: None, .. } => {
            println!("Unknown payment hash: {}", payment_hash);
    	},
        // ...
    },
    Event::PaymentClaimed { payment_hash, amount_msat, .. } => {
        assert_eq!(payment_hash, known_payment_hash);
        println!("Claimed {} msats", amount_msat);
    },
    // ...
});

Persistence

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 (i.e., called funding_transaction_generated for outbound channels) being closed.

Note that you can be a bit lazier about writing out ChannelManager than you can be with ChannelMonitor. With ChannelMonitor you MUST durably write each ChannelMonitorUpdate before returning from chain::Watch::watch_channel/update_channel or before completing async writes. 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 ChannelMonitor passed by reference to read, those channels will be force-closed based on the ChannelMonitor state and no funds will be lost (modulo on-chain transaction fees).

Note that the deserializer is only implemented for (BlockHash, ChannelManager), which tells you the last block hash which was connected. You should get the best block tip before using the manager. See chain::Listen and chain::Confirm for more details.

ChannelUpdate Messages

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_tick_occurred roughly once per minute, though it doesn’t have to be perfect.

DoS Mitigation

To avoid trivial DoS issues, ChannelManager limits the number of inbound connections and inbound channels without confirmed funding transactions. This may result in nodes which we do not have a channel with being unable to connect to us or open new channels with us if we have many peers with unfunded channels.

Because it is an indication of trust, inbound channels which we’ve accepted as 0conf are exempted from the count of unfunded channels. Similarly, outbound channels and connections are never limited. Please ensure you limit the count of such channels yourself.

Type Aliases

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<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

pub fn new( fee_est: F, chain_monitor: M, tx_broadcaster: T, router: R, logger: L, entropy_source: ES, node_signer: NS, signer_provider: SP, config: UserConfig, params: ChainParameters, current_timestamp: u32 ) -> Self

Constructs a new ChannelManager to hold several channels and route between them.

The current time or latest block header time can be provided as the current_timestamp.

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.

Users need to notify the new ChannelManager when a new block is connected or disconnected using its block_connected and block_disconnected methods, starting from after params.best_block.block_hash. See chain::Listen and chain::Confirm for more details.

pub fn get_current_default_configuration(&self) -> &UserConfig

Gets the current configuration applied to all new channels.

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

Creates a new outbound channel to the given remote node and with the given value.

user_channel_id will be provided back as in Event::FundingGenerationReady::user_channel_id to allow tracking of which events correspond with which create_channel call. Note that the user_channel_id defaults to a randomized value for inbound channels. user_channel_id has no meaning inside of LDK, it is simply copied to events and otherwise ignored.

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

Raises APIError::ChannelUnavailable if the channel cannot be opened due to failing to generate a shutdown scriptpubkey or destination script set by SignerProvider::get_shutdown_scriptpubkey or SignerProvider::get_destination_script.

Note that we do not check if you are currently connected to the given peer. If no connection is available, the outbound open_channel message may fail to send, resulting in the channel eventually being silently forgotten (dropped on reload).

If temporary_channel_id is specified, it will be used as the temporary channel ID of the channel. Otherwise, a random one will be generated for you.

Returns the new Channel’s temporary channel_id. This ID will appear as Event::FundingGenerationReady::temporary_channel_id and in ChannelDetails::channel_id until after ChannelManager::funding_transaction_generated is called, swapping the Channel’s ID for one derived from the funding transaction’s TXID. If the counterparty rejects the channel immediately, this temporary ID will appear in Event::ChannelClosed::channel_id.

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

Gets the list of open channels, in random order. See ChannelDetails 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 Router::find_route to ensure non-announced channels are used.

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

pub fn list_channels_with_counterparty( &self, counterparty_node_id: &PublicKey ) -> Vec<ChannelDetails>

Gets the list of channels we have with a given counterparty, in random order.

pub fn list_recent_payments(&self) -> Vec<RecentPaymentDetails>

Returns in an undefined order recent payments that – if not fulfilled – have yet to find a successful path, or have unresolved HTLCs.

This can be useful for payments that may have been prepared, but ultimately not sent, as a result of a crash. If such a payment exists, is not listed here, and an Event::PaymentSent has not been received, you may consider resending the payment.

pub fn close_channel( &self, channel_id: &ChannelId, counterparty_node_id: &PublicKey ) -> 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.

• If we are the channel initiator, we will pay between our ChannelCloseMinimum and ChannelConfig::force_close_avoidance_max_fee_satoshis plus our NonAnchorChannelFee fee estimate.
• If our counterparty is the channel initiator, we will require a channel closing transaction feerate of at least our ChannelCloseMinimum feerate or the feerate which would appear on a force-closure transaction, whichever is lower. We will allow our counterparty to pay as much fee as they’d like, however.

May generate a SendShutdown message event on success, which should be relayed.

Raises APIError::ChannelUnavailable if the channel cannot be closed due to failing to generate a shutdown scriptpubkey or destination script set by SignerProvider::get_shutdown_scriptpubkey. A force-closure may be needed to close the channel.

pub fn close_channel_with_feerate_and_script( &self, channel_id: &ChannelId, counterparty_node_id: &PublicKey, target_feerate_sats_per_1000_weight: Option<u32>, shutdown_script: Option<ShutdownScript> ) -> 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.

target_feerate_sat_per_1000_weight has different meanings depending on if we initiated the channel being closed or not:

• If we are the channel initiator, we will pay at least this feerate on the closing transaction. The upper-bound is set by ChannelConfig::force_close_avoidance_max_fee_satoshis plus our NonAnchorChannelFee fee estimate (or target_feerate_sat_per_1000_weight, if it is greater).
• If our counterparty is the channel initiator, we will refuse to accept a channel closure transaction feerate below target_feerate_sat_per_1000_weight (or the feerate which will appear on a force-closure transaction, whichever is lower).

The shutdown_script provided will be used as the scriptPubKey for the closing transaction. Will fail if a shutdown script has already been set for this channel by [’ChannelHandshakeConfig::commit_upfront_shutdown_pubkey`]. The given shutdown script must also be compatible with our and the counterparty’s features.

May generate a SendShutdown message event on success, which should be relayed.

Raises APIError::ChannelUnavailable if the channel cannot be closed due to failing to generate a shutdown scriptpubkey or destination script set by SignerProvider::get_shutdown_scriptpubkey. A force-closure may be needed to close the channel.

pub fn force_close_broadcasting_latest_txn( &self, channel_id: &ChannelId, counterparty_node_id: &PublicKey ) -> Result<(), APIError>

Force closes a channel, immediately broadcasting the latest local transaction(s) and rejecting new HTLCs on the given channel. Fails if channel_id is unknown to the manager, or if the counterparty_node_id isn’t the counterparty of the corresponding channel.

pub fn force_close_without_broadcasting_txn( &self, channel_id: &ChannelId, counterparty_node_id: &PublicKey ) -> Result<(), APIError>

Force closes a channel, rejecting new HTLCs on the given channel but skips broadcasting the latest local transaction(s). Fails if channel_id is unknown to the manager, or if the counterparty_node_id isn’t the counterparty of the corresponding channel.

You can always broadcast the latest local transaction(s) via ChannelMonitor::broadcast_latest_holder_commitment_txn.

pub fn force_close_all_channels_broadcasting_latest_txn(&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 force_close_all_channels_without_broadcasting_txn(&self)

Force close all channels rejecting new HTLCs on each but without broadcasting the latest local transaction(s).

pub fn send_payment_with_route( &self, route: &Route, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields, payment_id: PaymentId ) -> 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.

May generate UpdateHTLCs message(s) event on success, which should be relayed (e.g. via PeerManager::process_events).

Avoiding Duplicate Payments

If a pending payment is currently in-flight with the same PaymentId provided, this method will error with an APIError::InvalidRoute. Note, however, that once a payment is no longer pending (either via ChannelManager::abandon_payment, or handling of an Event::PaymentSent or Event::PaymentFailed) LDK will not stop you from sending a second payment with the same PaymentId.

Thus, in order to ensure duplicate payments are not sent, you should implement your own tracking of payments, including state to indicate once a payment has completed. Because you should also ensure that PaymentHashes are not re-used, for simplicity, you should consider using the PaymentHash as the key for tracking payments. In that case, the PaymentId should be a copy of the PaymentHash bytes.

Additionally, in the scenario where we begin the process of sending a payment, but crash before send_payment returns (or prior to ChannelMonitorUpdate persistence if you’re using ChannelMonitorUpdateStatus::InProgress), the payment may be lost on restart. See ChannelManager::list_recent_payments for more information.

Possible Error States on PaymentSendFailure

Each path may have a different return value, and PaymentSendFailure 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::InvalidRoute 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 as it has been closed, doesn’t exist, or the peer is currently disconnected.
• APIError::MonitorUpdateInProgress 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!

pub fn send_payment( &self, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields, payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry ) -> Result<(), RetryableSendFailure>

Similar to ChannelManager::send_payment_with_route, but will automatically find a route based on route_params and retry failed payment paths based on retry_strategy.

pub fn abandon_payment(&self, payment_id: PaymentId)

Signals that no further attempts for the given payment should occur. Useful if you have a pending outbound payment with retries remaining, but wish to stop retrying the payment before retries are exhausted.

Event Generation

If no Event::PaymentFailed event had been generated before, one will be generated as soon as there are no remaining pending HTLCs for this payment.

Note that calling this method does not prevent a payment from succeeding. You must still wait until you receive either a Event::PaymentFailed or Event::PaymentSent event to determine the ultimate status of a payment.

Requested Invoices

In the case of paying a Bolt12Invoice via ChannelManager::pay_for_offer, abandoning the payment prior to receiving the invoice will result in an Event::InvoiceRequestFailed and prevent any attempts at paying it once received. The other events may only be generated once the invoice has been received.

Restart Behavior

If an Event::PaymentFailed is generated and we restart without first persisting the ChannelManager, another Event::PaymentFailed may be generated; likewise for Event::InvoiceRequestFailed.

pub fn send_spontaneous_payment( &self, route: &Route, payment_preimage: Option<PaymentPreimage>, recipient_onion: RecipientOnionFields, payment_id: PaymentId ) -> Result<PaymentHash, PaymentSendFailure>

Send a spontaneous payment, which is a payment that does not require the recipient to have generated an invoice. Optionally, you may specify the preimage. If you do choose to specify the preimage, it must be a cryptographically secure random value that no intermediate node would be able to guess – otherwise, an intermediate node may claim the payment and it will never reach the recipient.

See send_payment documentation for more details on the return value of this function and idempotency guarantees provided by the PaymentId key.

Similar to regular payments, you MUST NOT reuse a payment_preimage value. See send_payment for more information about the risks of duplicate preimage usage.

pub fn send_spontaneous_payment_with_retry( &self, payment_preimage: Option<PaymentPreimage>, recipient_onion: RecipientOnionFields, payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry ) -> Result<PaymentHash, RetryableSendFailure>

Similar to ChannelManager::send_spontaneous_payment, but will automatically find a route based on route_params and retry failed payment paths based on retry_strategy.

See PaymentParameters::for_keysend for help in constructing route_params for spontaneous payments.

pub fn send_probe( &self, path: Path ) -> Result<(PaymentHash, PaymentId), PaymentSendFailure>

Send a payment that is probing the given route for liquidity. We calculate the PaymentHash of probes based on a static secret and a random PaymentId, which allows us to easily discern them from real payments.

pub fn send_spontaneous_preflight_probes( &self, node_id: PublicKey, amount_msat: u64, final_cltv_expiry_delta: u32, liquidity_limit_multiplier: Option<u64> ) -> Result<Vec<(PaymentHash, PaymentId)>, ProbeSendFailure>

Sends payment probes over all paths of a route that would be used to pay the given amount to the given node_id.

See ChannelManager::send_preflight_probes for more information.

pub fn send_preflight_probes( &self, route_params: RouteParameters, liquidity_limit_multiplier: Option<u64> ) -> Result<Vec<(PaymentHash, PaymentId)>, ProbeSendFailure>

Sends payment probes over all paths of a route that would be used to pay a route found according to the given RouteParameters.

This may be used to send “pre-flight” probes, i.e., to train our scorer before conducting the actual payment. Note this is only useful if there likely is sufficient time for the probe to settle before sending out the actual payment, e.g., when waiting for user confirmation in a wallet UI.

Otherwise, there is a chance the probe could take up some liquidity needed to complete the actual payment. Users should therefore be cautious and might avoid sending probes if liquidity is scarce and/or they don’t expect the probe to return before they send the payment. To mitigate this issue, channels with available liquidity less than the required amount times the given liquidity_limit_multiplier won’t be used to send pre-flight probes. If None is given as liquidity_limit_multiplier, it defaults to 3.

pub fn funding_transaction_generated( &self, temporary_channel_id: &ChannelId, counterparty_node_id: &PublicKey, funding_transaction: Transaction ) -> Result<(), APIError>

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

Returns an APIError::APIMisuseError if the funding_transaction spent non-SegWit outputs or if no output was found which matches the parameters in Event::FundingGenerationReady.

Returns APIError::APIMisuseError if the funding transaction is not final for propagation across the p2p network.

Returns APIError::ChannelUnavailable if a funding transaction has already been provided for the channel or if the channel has been closed as indicated by Event::ChannelClosed.

May panic if the output found in the funding transaction is duplicative with some other channel (note that this should be trivially prevented by using unique funding transaction keys per-channel).

Do NOT broadcast the funding transaction yourself. When we have safely received our counterparty’s signature the funding transaction will automatically be broadcast via the BroadcasterInterface provided when this ChannelManager was constructed.

Note that this includes RBF or similar transaction replacement strategies - lightning does not currently support replacing a funding transaction on an existing channel. Instead, create a new channel with a conflicting funding transaction.

Note to keep the miner incentives aligned in moving the blockchain forward, we recommend the wallet software generating the funding transaction to apply anti-fee sniping as implemented by Bitcoin Core wallet. See https://bitcoinops.org/en/topics/fee-sniping/ for more details.

pub fn batch_funding_transaction_generated( &self, temporary_channels: &[(&ChannelId, &PublicKey)], funding_transaction: Transaction ) -> Result<(), APIError>

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

Return values are identical to Self::funding_transaction_generated, respective to each individual channel and transaction output.

Do NOT broadcast the funding transaction yourself. This batch funding transaction will only be broadcast when we have safely received and persisted the counterparty’s signature for each channel.

If there is an error, all channels in the batch are to be considered closed.

pub fn update_partial_channel_config( &self, counterparty_node_id: &PublicKey, channel_ids: &[ChannelId], config_update: &ChannelConfigUpdate ) -> Result<(), APIError>

Atomically applies partial updates to the ChannelConfig of the given channels.

Once the updates are applied, each eligible channel (advertised with a known short channel ID and a change in forwarding_fee_proportional_millionths, forwarding_fee_base_msat, or cltv_expiry_delta) has a BroadcastChannelUpdate event message generated containing the new ChannelUpdate message which should be broadcast to the network.

Returns ChannelUnavailable when a channel is not found or an incorrect counterparty_node_id is provided.

Returns APIMisuseError when a cltv_expiry_delta update is to be applied with a value below MIN_CLTV_EXPIRY_DELTA.

If an error is returned, none of the updates should be considered applied.

pub fn update_channel_config( &self, counterparty_node_id: &PublicKey, channel_ids: &[ChannelId], config: &ChannelConfig ) -> Result<(), APIError>

Atomically updates the ChannelConfig for the given channels.

Once the updates are applied, each eligible channel (advertised with a known short channel ID and a change in forwarding_fee_proportional_millionths, forwarding_fee_base_msat, or cltv_expiry_delta) has a BroadcastChannelUpdate event message generated containing the new ChannelUpdate message which should be broadcast to the network.

Returns ChannelUnavailable when a channel is not found or an incorrect counterparty_node_id is provided.

Returns APIMisuseError when a cltv_expiry_delta update is to be applied with a value below MIN_CLTV_EXPIRY_DELTA.

If an error is returned, none of the updates should be considered applied.

pub fn forward_intercepted_htlc( &self, intercept_id: InterceptId, next_hop_channel_id: &ChannelId, next_node_id: PublicKey, amt_to_forward_msat: u64 ) -> Result<(), APIError>

Attempts to forward an intercepted HTLC over the provided channel id and with the provided amount to forward. Should only be called in response to an HTLCIntercepted event.

Intercepted HTLCs can be useful for Lightning Service Providers (LSPs) to open a just-in-time channel to a receiving node if the node lacks sufficient inbound liquidity.

To make use of intercepted HTLCs, set UserConfig::accept_intercept_htlcs and use ChannelManager::get_intercept_scid to generate short channel id(s) to put in the receiver’s invoice route hints. These route hints will signal to LDK to generate an HTLCIntercepted event when it receives the forwarded HTLC, and this method or ChannelManager::fail_intercepted_htlc MUST be called in response to the event.

Note that LDK does not enforce fee requirements in amt_to_forward_msat, and will not stop you from forwarding more than you received. See HTLCIntercepted::expected_outbound_amount_msat for more on forwarding a different amount than expected.

Errors if the event was not handled in time, in which case the HTLC was automatically failed backwards.

pub fn fail_intercepted_htlc( &self, intercept_id: InterceptId ) -> Result<(), APIError>

Fails the intercepted HTLC indicated by intercept_id. Should only be called in response to an HTLCIntercepted event. See ChannelManager::forward_intercepted_htlc.

Errors if the event was not handled in time, in which case the HTLC was automatically failed backwards.

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_tick_occurred(&self)

Performs actions which should happen on startup and roughly once per minute thereafter.

This currently includes:

• Increasing or decreasing the on-chain feerate estimates for our outbound channels,
• Broadcasting ChannelUpdate messages if we’ve been disconnected from our peer for more than a minute, informing the network that they should no longer attempt to route over the channel.
• Expiring a channel’s previous ChannelConfig if necessary to only allow forwarding HTLCs with the current ChannelConfig.
• Removing peers which have disconnected but and no longer have any channels.
• Force-closing and removing channels which have not completed establishment in a timely manner.
• Forgetting about stale outbound payments, either those that have already been fulfilled or those awaiting an invoice that hasn’t been delivered in the necessary amount of time. The latter is determined using the system clock in std and the highest seen block time minus two hours in no-std.

Note that this may cause reentrancy through chain::Watch::update_channel calls or feerate estimate fetches.

pub fn fail_htlc_backwards(&self, payment_hash: &PaymentHash)

Indicates that the preimage for payment_hash is unknown or the received amount is incorrect after a PaymentClaimable event, failing the HTLC back to its origin and freeing resources along the path (including in our own channel on which we received it).

Note that in some cases around unclean shutdown, it is possible the payment may have already been claimed by you via ChannelManager::claim_funds prior to you seeing (a second copy of) the events::Event::PaymentClaimable event. Alternatively, the payment may have already been failed automatically by LDK if it was nearing its expiration time.

While LDK will never claim a payment automatically on your behalf (i.e. without you calling ChannelManager::claim_funds), you should still monitor for events::Event::PaymentClaimed events even for payments you intend to fail, especially on startup during which time claims that were in-progress at shutdown may be replayed.

pub fn fail_htlc_backwards_with_reason( &self, payment_hash: &PaymentHash, failure_code: FailureCode )

This is a variant of ChannelManager::fail_htlc_backwards that allows you to specify the reason for the failure.

See FailureCode for valid failure codes.

pub fn claim_funds(&self, payment_preimage: PaymentPreimage)

Provides a payment preimage in response to Event::PaymentClaimable, generating any MessageSendEvents needed to claim the payment.

This method is guaranteed to ensure the payment has been claimed but only if the current height is strictly below Event::PaymentClaimable::claim_deadline. To avoid race conditions, you should wait for an Event::PaymentClaimed before considering the payment successful. It will generally be available in the next process_pending_events call.

Note that if you did not set an amount_msat when calling create_inbound_payment or create_inbound_payment_for_hash you must check that the amount in the PaymentClaimable event matches your expectation. If you fail to do so and call this method, you may provide the sender “proof-of-payment” when they did not fulfill the full expected payment.

This function will fail the payment if it has custom TLVs with even type numbers, as we will assume they are unknown. If you intend to accept even custom TLVs, you should use claim_funds_with_known_custom_tlvs.

pub fn claim_funds_with_known_custom_tlvs( &self, payment_preimage: PaymentPreimage )

This is a variant of claim_funds that allows accepting a payment with custom TLVs with even type numbers.

Note

You MUST check you’ve understood all even TLVs before using this to claim, otherwise you may unintentionally agree to some protocol you do not understand.

pub fn get_our_node_id(&self) -> PublicKey

Gets the node_id held by this ChannelManager

pub fn accept_inbound_channel( &self, temporary_channel_id: &ChannelId, counterparty_node_id: &PublicKey, user_channel_id: u128 ) -> Result<(), APIError>

Accepts a request to open a channel after a Event::OpenChannelRequest.

The temporary_channel_id parameter indicates which inbound channel should be accepted, and the counterparty_node_id parameter is the id of the peer which has requested to open the channel.

The user_channel_id parameter will be provided back in Event::ChannelClosed::user_channel_id to allow tracking of which events correspond with which accept_inbound_channel/accept_inbound_channel_from_trusted_peer_0conf call.

Note that this method will return an error and reject the channel, if it requires support for zero confirmations. Instead, accept_inbound_channel_from_trusted_peer_0conf must be used to accept such channels.

pub fn accept_inbound_channel_from_trusted_peer_0conf( &self, temporary_channel_id: &ChannelId, counterparty_node_id: &PublicKey, user_channel_id: u128 ) -> Result<(), APIError>

Accepts a request to open a channel after a events::Event::OpenChannelRequest, treating it as confirmed immediately.

The user_channel_id parameter will be provided back in Event::ChannelClosed::user_channel_id to allow tracking of which events correspond with which accept_inbound_channel/accept_inbound_channel_from_trusted_peer_0conf call.

Unlike ChannelManager::accept_inbound_channel, this method accepts the incoming channel and (if the counterparty agrees), enables forwarding of payments immediately.

This fully trusts that the counterparty has honestly and correctly constructed the funding transaction and blindly assumes that it will eventually confirm.

If it does not confirm before we decide to close the channel, or if the funding transaction does not pay to the correct script the correct amount, you will lose funds.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

pub fn create_offer_builder( &self ) -> Result<OfferBuilder<'_, DerivedMetadata, All>, Bolt12SemanticError>

Creates an OfferBuilder such that the Offer it builds is recognized by the ChannelManager when handling InvoiceRequest messages for the offer. The offer will not have an expiration unless otherwise set on the builder.

Privacy

Uses MessageRouter::create_blinded_paths to construct a BlindedPath for the offer. However, if one is not found, uses a one-hop BlindedPath with ChannelManager::get_our_node_id as the introduction node instead. In the latter case, the node must be announced, otherwise, there is no way to find a path to the introduction in order to send the InvoiceRequest.

Also, uses a derived signing pubkey in the offer for recipient privacy.

Limitations

Requires a direct connection to the introduction node in the responding InvoiceRequest’s reply path.

Errors

Errors if the parameterized Router is unable to create a blinded path for the offer.

This is not exported to bindings users as builder patterns don’t map outside of move semantics.

pub fn create_refund_builder( &self, amount_msats: u64, absolute_expiry: Duration, payment_id: PaymentId, retry_strategy: Retry, max_total_routing_fee_msat: Option<u64> ) -> Result<RefundBuilder<'_, All>, Bolt12SemanticError>

Creates a RefundBuilder such that the Refund it builds is recognized by the ChannelManager when handling Bolt12Invoice messages for the refund.

Payment

The provided payment_id is used to ensure that only one invoice is paid for the refund. See Avoiding Duplicate Payments for other requirements once the payment has been sent.

The builder will have the provided expiration set. Any changes to the expiration on the returned builder will not be honored by ChannelManager. For no-std, the highest seen block time minus two hours is used for the current time when determining if the refund has expired.

To revoke the refund, use ChannelManager::abandon_payment prior to receiving the invoice. If abandoned, or an invoice isn’t received before expiration, the payment will fail with an Event::InvoiceRequestFailed.

If max_total_routing_fee_msat is not specified, The default from RouteParameters::from_payment_params_and_value is applied.

Privacy

Uses MessageRouter::create_blinded_paths to construct a BlindedPath for the refund. However, if one is not found, uses a one-hop BlindedPath with ChannelManager::get_our_node_id as the introduction node instead. In the latter case, the node must be announced, otherwise, there is no way to find a path to the introduction in order to send the Bolt12Invoice.

Also, uses a derived payer id in the refund for payer privacy.

Limitations

Requires a direct connection to an introduction node in the responding Bolt12Invoice::payment_paths.

Errors

Errors if:

• a duplicate payment_id is provided given the caveats in the aforementioned link,
• amount_msats is invalid, or
• the parameterized Router is unable to create a blinded path for the refund.

This is not exported to bindings users as builder patterns don’t map outside of move semantics.

pub fn pay_for_offer( &self, offer: &Offer, quantity: Option<u64>, amount_msats: Option<u64>, payer_note: Option<String>, payment_id: PaymentId, retry_strategy: Retry, max_total_routing_fee_msat: Option<u64> ) -> Result<(), Bolt12SemanticError>

Pays for an Offer using the given parameters by creating an InvoiceRequest and enqueuing it to be sent via an onion message. ChannelManager will pay the actual Bolt12Invoice once it is received.

Uses InvoiceRequestBuilder such that the InvoiceRequest it builds is recognized by the ChannelManager when handling a Bolt12Invoice message in response to the request. The optional parameters are used in the builder, if Some:

• quantity for InvoiceRequest::quantity which must be set if Offer::expects_quantity is true.
• amount_msats if overpaying what is required for the given quantity is desired, and
• payer_note for InvoiceRequest::payer_note.

If max_total_routing_fee_msat is not specified, The default from RouteParameters::from_payment_params_and_value is applied.

Payment

The provided payment_id is used to ensure that only one invoice is paid for the request when received. See Avoiding Duplicate Payments for other requirements once the payment has been sent.

To revoke the request, use ChannelManager::abandon_payment prior to receiving the invoice. If abandoned, or an invoice isn’t received in a reasonable amount of time, the payment will fail with an Event::InvoiceRequestFailed.

Privacy

Uses a one-hop BlindedPath for the reply path with ChannelManager::get_our_node_id as the introduction node and a derived payer id for payer privacy. As such, currently, the node must be announced. Otherwise, there is no way to find a path to the introduction node in order to send the Bolt12Invoice.

Limitations

Requires a direct connection to an introduction node in Offer::paths or to Offer::signing_pubkey, if empty. A similar restriction applies to the responding Bolt12Invoice::payment_paths.

Errors

Errors if:

• a duplicate payment_id is provided given the caveats in the aforementioned link,
• the provided parameters are invalid for the offer,
• the offer is for an unsupported chain, or
• the parameterized Router is unable to create a blinded reply path for the invoice request.

pub fn request_refund_payment( &self, refund: &Refund ) -> Result<Bolt12Invoice, Bolt12SemanticError>

Creates a Bolt12Invoice for a Refund and enqueues it to be sent via an onion message.

The resulting invoice uses a PaymentHash recognized by the ChannelManager and a BlindedPath containing the PaymentSecret needed to reconstruct the corresponding PaymentPreimage. It is returned purely for informational purposes.

Limitations

Requires a direct connection to an introduction node in Refund::paths or to Refund::payer_id, if empty. This request is best effort; an invoice will be sent to each node meeting the aforementioned criteria, but there’s no guarantee that they will be received and no retries will be made.

Errors

Errors if:

• the refund is for an unsupported chain, or
• the parameterized Router is unable to create a blinded payment path or reply path for the invoice.

pub fn create_inbound_payment( &self, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option<u16> ) -> Result<(PaymentHash, PaymentSecret), ()>

Gets a payment secret and payment hash for use in an invoice given to a third party wishing to pay us.

This differs from create_inbound_payment_for_hash only in that it generates the PaymentHash and PaymentPreimage for you.

The PaymentPreimage will ultimately be returned to you in the PaymentClaimable event, which will have the PaymentClaimable::purpose return Some for PaymentPurpose::preimage. That should then be passed directly to claim_funds.

See create_inbound_payment_for_hash for detailed documentation on behavior and requirements.

Note that a malicious eavesdropper can intuit whether an inbound payment was created by create_inbound_payment or create_inbound_payment_for_hash based on runtime.

Note

If you register an inbound payment with this method, then serialize the ChannelManager, then deserialize it with a node running 0.0.103 and earlier, the payment will fail to be received.

Errors if min_value_msat is greater than total bitcoin supply.

If min_final_cltv_expiry_delta is set to some value, then the payment will not be receivable on versions of LDK prior to 0.0.114.

pub fn create_inbound_payment_for_hash( &self, payment_hash: PaymentHash, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32, min_final_cltv_expiry: Option<u16> ) -> Result<PaymentSecret, ()>

Gets a PaymentSecret for a given PaymentHash, for which the payment preimage is stored external to LDK.

A PaymentClaimable event will only be generated if the PaymentSecret matches a payment secret fetched via this method or create_inbound_payment, and which is at least the min_value_msat provided here, if one is provided.

The PaymentHash (and corresponding PaymentPreimage) should be globally unique, though note that LDK will not stop you from registering duplicate payment hashes for inbound payments.

min_value_msat should be set if the invoice being generated contains a value. Any payment received for the returned PaymentHash will be required to be at least min_value_msat before a PaymentClaimable event will be generated, ensuring that we do not provide the sender “proof-of-payment” unless they have paid the required amount.

invoice_expiry_delta_secs describes the number of seconds that the invoice is valid for in excess of the current time. This should roughly match the expiry time set in the invoice. After this many seconds, we will remove the inbound payment, resulting in any attempts to pay the invoice failing. The BOLT spec suggests 3,600 secs as a default validity time for invoices when no timeout is set.

Note that we use block header time to time-out pending inbound payments (with some margin to compensate for the inaccuracy of block header timestamps). Thus, in practice we will accept a payment and generate a PaymentClaimable event for some time after the expiry. If you need exact expiry semantics, you should enforce them upon receipt of PaymentClaimable.

Note that invoices generated for inbound payments should have their min_final_cltv_expiry_delta set to at least MIN_FINAL_CLTV_EXPIRY_DELTA.

Note that a malicious eavesdropper can intuit whether an inbound payment was created by create_inbound_payment or create_inbound_payment_for_hash based on runtime.

Note

If you register an inbound payment with this method, then serialize the ChannelManager, then deserialize it with a node running 0.0.103 and earlier, the payment will fail to be received.

Errors if min_value_msat is greater than total bitcoin supply.

If min_final_cltv_expiry_delta is set to some value, then the payment will not be receivable on versions of LDK prior to 0.0.114.

pub fn get_payment_preimage( &self, payment_hash: PaymentHash, payment_secret: PaymentSecret ) -> Result<PaymentPreimage, APIError>

Gets an LDK-generated payment preimage from a payment hash and payment secret that were previously returned from create_inbound_payment.

pub fn get_phantom_scid(&self) -> u64

Gets a fake short channel id for use in receiving phantom node payments. These fake scids are used when constructing the phantom invoice’s route hints.

pub fn get_phantom_route_hints(&self) -> PhantomRouteHints

Gets route hints for use in receiving phantom node payments.

pub fn get_intercept_scid(&self) -> u64

Gets a fake short channel id for use in receiving intercepted payments. These fake scids are used when constructing the route hints for HTLCs intended to be intercepted. See ChannelManager::forward_intercepted_htlc.

Note that this method is not guaranteed to return unique values, you may need to call it a few times to get a unique scid.

pub fn compute_inflight_htlcs(&self) -> InFlightHtlcs

Gets inflight HTLC information by processing pending outbound payments that are in our channels. May be used during pathfinding to account for in-use channel liquidity.

pub async fn process_pending_events_async<Future: Future, H: Fn(Event) -> Future>( &self, handler: H )

Processes any events asynchronously in the order they were generated since the last call using the given event handler.

See the trait-level documentation of EventsProvider for requirements.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

pub fn get_event_or_persistence_needed_future(&self) -> Future

Gets a Future that completes when this ChannelManager may need to be persisted or may have events that need processing.

In order to check if this ChannelManager needs persisting, call Self::get_and_clear_needs_persistence.

Note that callbacks registered on the Future MUST NOT call back into this ChannelManager and should instead register actions to be taken later.

pub fn get_and_clear_needs_persistence(&self) -> bool

Returns true if this ChannelManager needs to be persisted.

See Self::get_event_or_persistence_needed_future for retrieving a Future that indicates this should be checked.

pub fn current_best_block(&self) -> BestBlock

Gets the latest best block which was connected either via the chain::Listen or chain::Confirm interfaces.

pub fn node_features(&self) -> NodeFeatures

Fetches the set of NodeFeatures flags that are provided by or required by ChannelManager.

pub fn channel_features(&self) -> ChannelFeatures

Fetches the set of ChannelFeatures flags that are provided by or required by ChannelManager.

pub fn channel_type_features(&self) -> ChannelTypeFeatures

Fetches the set of ChannelTypeFeatures flags that are provided by or required by ChannelManager.

pub fn init_features(&self) -> InitFeatures

Fetches the set of InitFeatures flags that are provided by or required by ChannelManager.

Trait Implementations

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> AChannelManager for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

type Watch = <M as Deref>::Target

A type implementing chain::Watch.

type M = M

A type that may be dereferenced to Self::Watch.

type Broadcaster = <T as Deref>::Target

A type implementing BroadcasterInterface.

type T = T

A type that may be dereferenced to Self::Broadcaster.

type EntropySource = <ES as Deref>::Target

A type implementing EntropySource.

type ES = ES

A type that may be dereferenced to Self::EntropySource.

type NodeSigner = <NS as Deref>::Target

A type implementing NodeSigner.

type NS = NS

A type that may be dereferenced to Self::NodeSigner.

type Signer = <<SP as Deref>::Target as SignerProvider>::EcdsaSigner

A type implementing WriteableEcdsaChannelSigner.

type SignerProvider = <SP as Deref>::Target

A type implementing SignerProvider for Self::Signer.

type SP = SP

A type that may be dereferenced to Self::SignerProvider.

type FeeEstimator = <F as Deref>::Target

A type implementing FeeEstimator.

type F = F

A type that may be dereferenced to Self::FeeEstimator.

type Router = <R as Deref>::Target

A type implementing Router.

type R = R

A type that may be dereferenced to Self::Router.

type Logger = <L as Deref>::Target

A type implementing Logger.

type L = L

A type that may be dereferenced to Self::Logger.

fn get_cm(&self) -> &ChannelManager<M, T, ES, NS, SP, F, R, L>

Returns a reference to the actual ChannelManager object.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> ChannelMessageHandler for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

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

Handle an incoming open_channel message from the given peer.

fn handle_open_channel_v2( &self, counterparty_node_id: &PublicKey, msg: &OpenChannelV2 )

Handle an incoming open_channel2 message from the given peer.

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

Handle an incoming accept_channel message from the given peer.

fn handle_accept_channel_v2( &self, counterparty_node_id: &PublicKey, msg: &AcceptChannelV2 )

Handle an incoming accept_channel2 message from the given peer.

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

Handle an incoming funding_created message from the given peer.

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

Handle an incoming funding_signed message from the given peer.

fn handle_channel_ready( &self, counterparty_node_id: &PublicKey, msg: &ChannelReady )

Handle an incoming channel_ready message from the given peer.

fn handle_stfu(&self, counterparty_node_id: &PublicKey, msg: &Stfu)

Handle an incoming stfu message from the given peer.

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

Handle an incoming shutdown message from the given peer.

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

Handle an incoming closing_signed message from the given peer.

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

Handle an incoming update_add_htlc message from the given peer.

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

Handle an incoming update_fulfill_htlc message from the given peer.

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

Handle an incoming update_fail_htlc message from the given peer.

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.

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

Handle an incoming commitment_signed message from the given peer.

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

Handle an incoming revoke_and_ack message from the given peer.

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

Handle an incoming update_fee message from the given peer.

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

Handle an incoming announcement_signatures message from the given peer.

fn handle_channel_update( &self, counterparty_node_id: &PublicKey, msg: &ChannelUpdate )

Handle an incoming channel_update message from the given peer.

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

Handle an incoming channel_reestablish message from the given peer.

fn peer_disconnected(&self, counterparty_node_id: &PublicKey)

Indicates a connection to the peer failed/an existing connection was lost.

fn peer_connected( &self, counterparty_node_id: &PublicKey, init_msg: &Init, inbound: bool ) -> Result<(), ()>

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

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

Handle an incoming error message from the given peer.

fn provided_node_features(&self) -> NodeFeatures

Gets the node feature flags which this handler itself supports. All available handlers are queried similarly and their feature flags are OR’d together to form the NodeFeatures which are broadcasted in our NodeAnnouncement message.

fn provided_init_features( &self, _their_init_features: &PublicKey ) -> InitFeatures

Gets the init feature flags which should be sent to the given peer. All available handlers are queried similarly and their feature flags are OR’d together to form the InitFeatures which are sent in our Init message.

fn get_chain_hashes(&self) -> Option<Vec<ChainHash>>

Gets the chain hashes for this ChannelMessageHandler indicating which chains it supports.

fn handle_tx_add_input( &self, counterparty_node_id: &PublicKey, msg: &TxAddInput )

Handle an incoming tx_add_input message from the given peer.

fn handle_tx_add_output( &self, counterparty_node_id: &PublicKey, msg: &TxAddOutput )

Handle an incoming tx_add_output message from the given peer.

fn handle_tx_remove_input( &self, counterparty_node_id: &PublicKey, msg: &TxRemoveInput )

Handle an incoming tx_remove_input message from the given peer.

fn handle_tx_remove_output( &self, counterparty_node_id: &PublicKey, msg: &TxRemoveOutput )

Handle an incoming tx_remove_output message from the given peer.

fn handle_tx_complete(&self, counterparty_node_id: &PublicKey, msg: &TxComplete)

Handle an incoming tx_complete message from the given peer.

fn handle_tx_signatures( &self, counterparty_node_id: &PublicKey, msg: &TxSignatures )

Handle an incoming tx_signatures message from the given peer.

fn handle_tx_init_rbf(&self, counterparty_node_id: &PublicKey, msg: &TxInitRbf)

Handle an incoming tx_init_rbf message from the given peer.

fn handle_tx_ack_rbf(&self, counterparty_node_id: &PublicKey, msg: &TxAckRbf)

Handle an incoming tx_ack_rbf message from the given peer.

fn handle_tx_abort(&self, counterparty_node_id: &PublicKey, msg: &TxAbort)

Handle an incoming tx_abort message from the given peer.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> Confirm for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

fn transactions_confirmed( &self, header: &Header, txdata: &TransactionData<'_>, height: u32 )

Notifies LDK of transactions confirmed in a block with a given header and height.

fn best_block_updated(&self, header: &Header, height: u32)

Notifies LDK of an update to the best header connected at the given height.

fn get_relevant_txids(&self) -> Vec<(Txid, u32, Option<BlockHash>)>

Returns transactions that must be monitored for reorganization out of the chain along with the height and the hash of the block as part of which it had been previously confirmed.

fn transaction_unconfirmed(&self, txid: &Txid)

Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> EventsProvider for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

fn process_pending_events<H: Deref>(&self, handler: H)

where H::Target: EventHandler,

Processes events that must be periodically handled.

An EventHandler may safely call back to the provider in order to handle an event. However, it must not call Writeable::write as doing so would result in a deadlock.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> Listen for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

fn filtered_block_connected( &self, header: &Header, txdata: &TransactionData<'_>, height: u32 )

Notifies the listener that a block was added at the given height, with the transaction data possibly filtered.

fn block_disconnected(&self, header: &Header, height: u32)

Notifies the listener that a block was removed at the given height.

fn block_connected(&self, block: &Block, height: u32)

Notifies the listener that a block was added at the given height.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> MessageSendEventsProvider for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

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

Returns MessageSendEvents strictly ordered per-peer, in the order they were generated. The returned array will contain MessageSendEvents for different peers if MessageSendEvents to more than one peer exists, but MessageSendEvents to the same peer is always placed next to each other.

Note that that while MessageSendEvents are strictly ordered per-peer, the peer order for the chunks of MessageSendEvents for different peers is random. I.e. if the array contains MessageSendEvents for both node_a and node_b, the MessageSendEvents for node_a will randomly be placed first or last in the returned array.

Note that even though BroadcastChannelAnnouncement and BroadcastChannelUpdate MessageSendEvents are intended to be broadcasted to all peers, they will be placed among the MessageSendEvents to the specific peer they were generated under.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> NodeIdLookUp for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

fn next_node_id(&self, short_channel_id: u64) -> Option<PublicKey>

Returns the node id of the forwarding node’s channel counterparty with short_channel_id.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> OffersMessageHandler for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

fn handle_message(&self, message: OffersMessage) -> Option<OffersMessage>

Handles the given message by either responding with an Bolt12Invoice, sending a payment, or replying with an error.

fn release_pending_messages(&self) -> Vec<PendingOnionMessage<OffersMessage>>

Available on non-c_bindings only.

Releases any OffersMessages that need to be sent.

impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref> Writeable for ChannelManager<M, T, ES, NS, SP, F, R, L>

where M::Target: Watch<<SP::Target as SignerProvider>::EcdsaSigner>, T::Target: BroadcasterInterface, ES::Target: EntropySource, NS::Target: NodeSigner, SP::Target: SignerProvider, F::Target: FeeEstimator, R::Target: Router, L::Target: Logger,

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

Writes self out to the given Writer.

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

Writes self out to a Vec<u8>.

fn serialized_length(&self) -> usize

Gets the length of this object after it has been serialized. This can be overridden to optimize cases where we prepend an object with its length.