pub struct Node<K: KVStore + Sync + Send + 'static> { /* private fields */ }
Expand description
The main interface object of LDK Node, wrapping the necessary LDK and BDK functionalities.
Needs to be initialized and instantiated through Builder::build
.
Implementations§
source§impl<K: KVStore + Sync + Send + 'static> Node<K>
impl<K: KVStore + Sync + Send + 'static> Node<K>
sourcepub fn start(&self) -> Result<(), Error>
pub fn start(&self) -> Result<(), Error>
Starts the necessary background tasks, such as handling events coming from user input, LDK/BDK, and the peer-to-peer network.
After this returns, the Node
instance can be controlled via the provided API methods in
a thread-safe manner.
sourcepub fn is_running(&self) -> bool
pub fn is_running(&self) -> bool
Returns whether the Node
is running.
sourcepub fn stop(&self) -> Result<(), Error>
pub fn stop(&self) -> Result<(), Error>
Disconnects all peers, stops all running background tasks, and shuts down Node
.
After this returns most API methods will return Error::NotRunning
.
sourcepub fn next_event(&self) -> Option<Event>
pub fn next_event(&self) -> Option<Event>
Returns the next event in the event queue, if currently available.
Will return Some(..)
if an event is available and None
otherwise.
Note: this will always return the same event until handling is confirmed via Node::event_handled
.
sourcepub fn wait_next_event(&self) -> Event
pub fn wait_next_event(&self) -> Event
Returns the next event in the event queue.
Will block the current thread until the next event is available.
Note: this will always return the same event until handling is confirmed via Node::event_handled
.
sourcepub fn event_handled(&self)
pub fn event_handled(&self)
Confirm the last retrieved event handled.
Note: This MUST be called after each event has been handled.
sourcepub fn listening_addresses(&self) -> Option<Vec<SocketAddress>>
pub fn listening_addresses(&self) -> Option<Vec<SocketAddress>>
Returns our own listening addresses.
sourcepub fn new_onchain_address(&self) -> Result<Address, Error>
pub fn new_onchain_address(&self) -> Result<Address, Error>
Retrieve a new on-chain/funding address.
sourcepub fn spendable_onchain_balance_sats(&self) -> Result<u64, Error>
pub fn spendable_onchain_balance_sats(&self) -> Result<u64, Error>
Retrieve the currently spendable on-chain balance in satoshis.
sourcepub fn total_onchain_balance_sats(&self) -> Result<u64, Error>
pub fn total_onchain_balance_sats(&self) -> Result<u64, Error>
Retrieve the current total on-chain balance in satoshis.
sourcepub fn send_to_onchain_address(
&self,
address: &Address,
amount_sats: u64
) -> Result<Txid, Error>
pub fn send_to_onchain_address( &self, address: &Address, amount_sats: u64 ) -> Result<Txid, Error>
Send an on-chain payment to the given address.
sourcepub fn send_all_to_onchain_address(
&self,
address: &Address
) -> Result<Txid, Error>
pub fn send_all_to_onchain_address( &self, address: &Address ) -> Result<Txid, Error>
Send an on-chain payment to the given address, draining all the available funds.
sourcepub fn list_channels(&self) -> Vec<ChannelDetails>
pub fn list_channels(&self) -> Vec<ChannelDetails>
Retrieve a list of known channels.
sourcepub fn connect(
&self,
node_id: PublicKey,
address: SocketAddress,
persist: bool
) -> Result<(), Error>
pub fn connect( &self, node_id: PublicKey, address: SocketAddress, persist: bool ) -> Result<(), Error>
Connect to a node on the peer-to-peer network.
If persist
is set to true
, we’ll remember the peer and reconnect to it on restart.
sourcepub fn disconnect(&self, counterparty_node_id: PublicKey) -> Result<(), Error>
pub fn disconnect(&self, counterparty_node_id: PublicKey) -> Result<(), Error>
Disconnects the peer with the given node id.
Will also remove the peer from the peer store, i.e., after this has been called we won’t try to reconnect on restart.
sourcepub fn connect_open_channel(
&self,
node_id: PublicKey,
address: SocketAddress,
channel_amount_sats: u64,
push_to_counterparty_msat: Option<u64>,
channel_config: Option<Arc<ChannelConfig>>,
announce_channel: bool
) -> Result<(), Error>
pub fn connect_open_channel( &self, node_id: PublicKey, address: SocketAddress, channel_amount_sats: u64, push_to_counterparty_msat: Option<u64>, channel_config: Option<Arc<ChannelConfig>>, announce_channel: bool ) -> Result<(), Error>
Connect to a node and open a new channel. Disconnects and re-connects are handled automatically
Disconnects and reconnects are handled automatically.
If push_to_counterparty_msat
is set, the given value will be pushed (read: sent) to the
channel counterparty on channel open. This can be useful to start out with the balance not
entirely shifted to one side, therefore allowing to receive payments from the getgo.
Returns a temporary channel id.
sourcepub fn sync_wallets(&self) -> Result<(), Error>
pub fn sync_wallets(&self) -> Result<(), Error>
Manually sync the LDK and BDK wallets with the current chain state.
Note: The wallets are regularly synced in the background, which is configurable via
Config::onchain_wallet_sync_interval_secs
and Config::wallet_sync_interval_secs
.
Therefore, using this blocking sync method is almost always redundant and should be avoided
where possible.
sourcepub fn close_channel(
&self,
channel_id: &ChannelId,
counterparty_node_id: PublicKey
) -> Result<(), Error>
pub fn close_channel( &self, channel_id: &ChannelId, counterparty_node_id: PublicKey ) -> Result<(), Error>
Close a previously opened channel.
sourcepub fn update_channel_config(
&self,
channel_id: &ChannelId,
counterparty_node_id: PublicKey,
channel_config: Arc<ChannelConfig>
) -> Result<(), Error>
pub fn update_channel_config( &self, channel_id: &ChannelId, counterparty_node_id: PublicKey, channel_config: Arc<ChannelConfig> ) -> Result<(), Error>
Update the config for a previously opened channel.
sourcepub fn send_payment(
&self,
invoice: &Bolt11Invoice
) -> Result<PaymentHash, Error>
pub fn send_payment( &self, invoice: &Bolt11Invoice ) -> Result<PaymentHash, Error>
Send a payment given an invoice.
sourcepub fn send_payment_using_amount(
&self,
invoice: &Bolt11Invoice,
amount_msat: u64
) -> Result<PaymentHash, Error>
pub fn send_payment_using_amount( &self, invoice: &Bolt11Invoice, amount_msat: u64 ) -> Result<PaymentHash, Error>
Send a payment given an invoice and an amount in millisatoshi.
This will fail if the amount given is less than the value required by the given invoice.
This can be used to pay a so-called “zero-amount” invoice, i.e., an invoice that leaves the amount paid to be determined by the user.
sourcepub fn send_spontaneous_payment(
&self,
amount_msat: u64,
node_id: PublicKey
) -> Result<PaymentHash, Error>
pub fn send_spontaneous_payment( &self, amount_msat: u64, node_id: PublicKey ) -> Result<PaymentHash, Error>
Send a spontaneous, aka. “keysend”, payment
sourcepub fn send_payment_probes(&self, invoice: &Bolt11Invoice) -> Result<(), Error>
pub fn send_payment_probes(&self, invoice: &Bolt11Invoice) -> Result<(), Error>
Sends payment probes over all paths of a route that would be used to pay the given invoice.
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 Config::probing_liquidity_limit_multiplier
won’t be used to send
pre-flight probes.
sourcepub fn send_spontaneous_payment_probes(
&self,
amount_msat: u64,
node_id: PublicKey
) -> Result<(), Error>
pub fn send_spontaneous_payment_probes( &self, amount_msat: u64, node_id: PublicKey ) -> Result<(), Error>
Sends payment probes over all paths of a route that would be used to pay the given
amount to the given node_id
.
See Self::send_payment_probes
for more information.
sourcepub fn send_payment_probes_using_amount(
&self,
invoice: &Bolt11Invoice,
amount_msat: u64
) -> Result<(), Error>
pub fn send_payment_probes_using_amount( &self, invoice: &Bolt11Invoice, amount_msat: u64 ) -> Result<(), Error>
Sends payment probes over all paths of a route that would be used to pay the given zero-value invoice using the given amount.
This can be used to send pre-flight probes for a so-called “zero-amount” invoice, i.e., an invoice that leaves the amount paid to be determined by the user.
See Self::send_payment_probes
for more information.
sourcepub fn receive_payment(
&self,
amount_msat: u64,
description: &str,
expiry_secs: u32
) -> Result<Bolt11Invoice, Error>
pub fn receive_payment( &self, amount_msat: u64, description: &str, expiry_secs: u32 ) -> Result<Bolt11Invoice, Error>
Returns a payable invoice that can be used to request and receive a payment of the amount given.
sourcepub fn receive_variable_amount_payment(
&self,
description: &str,
expiry_secs: u32
) -> Result<Bolt11Invoice, Error>
pub fn receive_variable_amount_payment( &self, description: &str, expiry_secs: u32 ) -> Result<Bolt11Invoice, Error>
Returns a payable invoice that can be used to request and receive a payment for which the amount is to be determined by the user, also known as a “zero-amount” invoice.
sourcepub fn payment(&self, payment_hash: &PaymentHash) -> Option<PaymentDetails>
pub fn payment(&self, payment_hash: &PaymentHash) -> Option<PaymentDetails>
Retrieve the details of a specific payment with the given hash.
Returns Some
if the payment was known and None
otherwise.
sourcepub fn remove_payment(&self, payment_hash: &PaymentHash) -> Result<(), Error>
pub fn remove_payment(&self, payment_hash: &PaymentHash) -> Result<(), Error>
Remove the payment with the given hash from the store.
sourcepub fn list_payments_with_filter<F: FnMut(&&PaymentDetails) -> bool>(
&self,
f: F
) -> Vec<PaymentDetails>
pub fn list_payments_with_filter<F: FnMut(&&PaymentDetails) -> bool>( &self, f: F ) -> Vec<PaymentDetails>
Retrieves all payments that match the given predicate.
For example, you could retrieve all stored outbound payments as follows:
node.list_payments_with_filter(|p| p.direction == PaymentDirection::Outbound);
sourcepub fn list_payments(&self) -> Vec<PaymentDetails>
pub fn list_payments(&self) -> Vec<PaymentDetails>
Retrieves all payments.
sourcepub fn list_peers(&self) -> Vec<PeerDetails>
pub fn list_peers(&self) -> Vec<PeerDetails>
Retrieves a list of known peers.
sourcepub fn sign_message(&self, msg: &[u8]) -> Result<String, Error>
pub fn sign_message(&self, msg: &[u8]) -> Result<String, Error>
Creates a digital ECDSA signature of a message with the node’s secret key.
A receiver knowing the corresponding PublicKey
(e.g. the node’s id) and the message
can be sure that the signature was generated by the caller.
Signatures are EC recoverable, meaning that given the message and the
signature the PublicKey
of the signer can be extracted.
Trait Implementations§
Auto Trait Implementations§
impl<K> Freeze for Node<K>
impl<K> !RefUnwindSafe for Node<K>
impl<K> Send for Node<K>
impl<K> Sync for Node<K>
impl<K> Unpin for Node<K>
impl<K> !UnwindSafe for Node<K>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more