Struct LSPS2ServiceHandler 

pub struct LSPS2ServiceHandler<CM: Deref, K: Deref + Clone, T: Deref>
where
    CM::Target: AChannelManager,
    K::Target: KVStore,
    T::Target: BroadcasterInterface,
{ /* private fields */ }

The main object allowing to send and receive bLIP-52 / LSPS2 messages.

Implementations

impl<CM: Deref, K: Deref + Clone, T: Deref + Clone> LSPS2ServiceHandler<CM, K, T>

where CM::Target: AChannelManager, K::Target: KVStore, T::Target: BroadcasterInterface,

pub fn config(&self) -> &LSPS2ServiceConfig

Returns a reference to the used config.

pub fn invalid_token_provided( &self, counterparty_node_id: &PublicKey, request_id: LSPSRequestId, ) -> Result<(), APIError>

Used by LSP to inform a client requesting a JIT Channel the token they used is invalid.

Should be called in response to receiving a LSPS2ServiceEvent::GetInfo event.

pub fn opening_fee_params_generated( &self, counterparty_node_id: &PublicKey, request_id: LSPSRequestId, opening_fee_params_menu: Vec<LSPS2RawOpeningFeeParams>, ) -> Result<(), APIError>

Used by LSP to provide fee parameters to a client requesting a JIT Channel.

Should be called in response to receiving a LSPS2ServiceEvent::GetInfo event.

pub async fn invoice_parameters_generated( &self, counterparty_node_id: &PublicKey, request_id: LSPSRequestId, intercept_scid: u64, cltv_expiry_delta: u32, client_trusts_lsp: bool, user_channel_id: u128, ) -> Result<(), APIError>

Used by LSP to provide the client with the intercept scid, a unique user_channel_id, and cltv_expiry_delta to include in their invoice.

The intercept scid must be retrieved from ChannelManager::get_intercept_scid. The given user_channel_id must be locally unique and will eventually be returned via events to be used when opening the channel via ChannelManager::create_channel. Note implementors will need to ensure their calls to ChannelManager::create_channel are idempotent based on this identifier.

Should be called in response to receiving a LSPS2ServiceEvent::BuyRequest event.

client_trusts_lsp:

• false (default) => “LSP trusts client”: LSP broadcasts the funding transaction as soon as it is safe and forwards the payment normally.
• true => “Client trusts LSP”: LSP may defer broadcasting the funding transaction until after the client claims the forwarded HTLC(s).

pub async fn htlc_intercepted( &self, intercept_scid: u64, intercept_id: InterceptId, expected_outbound_amount_msat: u64, payment_hash: PaymentHash, ) -> Result<(), APIError>

Forward Event::HTLCIntercepted event parameters into this function.

Will fail the intercepted HTLC if the intercept scid matches a payment we are expecting but the payment amount is incorrect or the expiry has passed.

Will generate a LSPS2ServiceEvent::OpenChannel event if the intercept scid matches a payment we are expected and the payment amount is correct and the offer has not expired.

Will do nothing if the intercept scid does not match any of the ones we gave out.

pub async fn htlc_handling_failed( &self, failure_type: HTLCHandlingFailureType, ) -> Result<(), APIError>

Forward Event::HTLCHandlingFailed event parameter into this function.

Will attempt to forward the next payment in the queue if one is present. Will do nothing if the intercept scid does not match any of the ones we gave out or if the payment queue is empty

pub async fn payment_forwarded( &self, next_channel_id: ChannelId, skimmed_fee_msat: u64, ) -> Result<(), APIError>

Forward Event::PaymentForwarded event parameter into this function.

Will register the forwarded payment as having paid the JIT channel fee, and forward any held and future HTLCs for the SCID of the initial invoice.

When the reported skimmed fee equals or exceeds the promised opening fee, any HTLCs that were being held for that JIT channel are forwarded. In a client_trusts_lsp flow, once the fee has been fully paid, the channel’s funding transaction will be broadcasted.

Note that next_channel_id and skimmed_fee_msat are required to be provided. Therefore, the corresponding Event::PaymentForwarded events need to be generated and serialized by LDK versions greater or equal to 0.0.122.

pub async fn channel_open_abandoned( &self, counterparty_node_id: &PublicKey, user_channel_id: u128, ) -> Result<(), APIError>

Abandons a pending JIT‐open flow for user_channel_id, removing all local state.

This removes the intercept SCID, any outbound channel state, and associated channel‐ID mappings for the specified user_channel_id, but only while no payment has been forwarded yet and no channel has been opened on-chain.

Returns an error if:

• there is no channel matching user_channel_id, or
• a payment has already been forwarded or a channel has already been opened

Note: this does not close or roll back any on‐chain channel which may already have been opened. The caller must call this before or instead of initiating the channel open, as it only affects the local LSPS2 state and doesn’t affect any channels that might already exist on-chain. Any pending channel open attempts must be managed separately.

pub async fn channel_open_failed( &self, counterparty_node_id: &PublicKey, user_channel_id: u128, ) -> Result<(), APIError>

Used to fail intercepted HTLCs backwards when a channel open attempt ultimately fails.

This function should be called after receiving an LSPS2ServiceEvent::OpenChannel event but only if the channel could not be successfully established. It resets the JIT channel state so that the payer may try the payment again.

pub async fn channel_ready( &self, user_channel_id: u128, channel_id: &ChannelId, counterparty_node_id: &PublicKey, ) -> Result<(), APIError>

Forward Event::ChannelReady event parameters into this function.

Will forward the intercepted HTLC if it matches a channel we need to forward a payment over otherwise it will be ignored.

pub fn channel_needs_manual_broadcast( &self, user_channel_id: u128, counterparty_node_id: &PublicKey, ) -> Result<bool, APIError>

Checks if the JIT channel with the given user_channel_id needs manual broadcast.

Will be true if client_trusts_lsp is set to true.

pub fn store_funding_transaction( &self, user_channel_id: u128, counterparty_node_id: &PublicKey, funding_tx: Transaction, ) -> Result<(), APIError>

Stores the funding transaction for a JIT channel.

Call this when the funding transaction is created.

In client_trusts_lsp the broadcasting of the funding transaction will be handled internally after you also mark it as broadcast-safe via set_funding_tx_broadcast_safe and once the opening fee has been collected. You do not need to broadcast the funding transaction yourself in this flow.

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

Marks that the funding transaction for the JIT channel identified by user_channel_id is now safe to broadcast.

In LDK call this when you receive Event::FundingTxBroadcastSafe. In other Lightning backends call it once the funding transaction is fully negotiated and signed (all signatures verified), your channel state machine will now proceed assuming the funding transaction will confirm, and you are intentionally deferring the actual broadcast so the LSPS2 flow (when client_trusts_lsp = true) can first collect the opening fee from the intercepted payment.

In a client_trusts_lsp flow, after this is set and the opening fee has been fully skimmed, the channel’s funding transaction will be broadcasted if the channel is still usable. If the channel has been closed or force-closed before this point, the funding transaction will not be broadcasted.