Struct Node 

pub struct Node { /* private fields */ }

The Node is an RPC stub representing the node running in the cloud. It is the main entrypoint to interact with the node.

Implementations

impl Node

pub fn signerless(credentials: Credentials) -> Result<Self, Error>

Construct a signerless Node — credentials only, no SDK-side signer running. The actual signing happens elsewhere (a paired device, a hardware signer, the CLN node’s local signer). Operations that require signing fall through to the node side.

Not a UniFFI export. UniFFI consumers reach this via NodeBuilder::connect(credentials, None) (mnemonic omitted). Sibling Rust crates (e.g. gl-sdk-napi) call this directly when wrapping signerless flows into their own bindings.

impl Node

pub fn stop(&self) -> Result<(), Error>

Stop the node if it is currently running.

pub fn credentials(&self) -> Result<Vec<u8>, Error>

Returns the serialized credentials for this node. The app should persist these bytes and pass them to connect() on next launch.

pub fn disconnect(&self) -> Result<(), Error>

Disconnects from the node and stops the signer if running. After disconnect, all RPC methods will return an error. Safe to call multiple times.

pub fn receive( &self, label: String, description: String, amount_msat: Option<u64>, ) -> Result<ReceiveResponse, Error>

Receive an off-chain payment.

This method generates a request for a payment, also called an invoice, that encodes all the information, including amount and destination, for a prospective sender to send a lightning payment. The invoice includes negotiation of an LSPS2 / JIT channel, meaning that if there is no channel sufficient to receive the requested funds, the node will negotiate an opening, and when/if executed the payment will cause a channel to be created, and the incoming payment to be forwarded.

pub fn send( &self, invoice: String, amount_msat: Option<u64>, ) -> Result<SendResponse, Error>

pub fn onchain_send( &self, destination: String, amount_or_all: String, sat_per_vbyte: Option<u32>, utxos: Option<Vec<Outpoint>>, ) -> Result<OnchainSendResponse, Error>

Send bitcoin on-chain to a destination address.

Arguments

• destination — A Bitcoin address (bech32, p2sh, or p2tr).
• amount_or_all — Amount to send. Accepts:
  • "50000" or "50000sat" — 50,000 satoshis
  • "50000msat" — 50,000 millisatoshis
  • "all" — sweep the entire on-chain balance
• sat_per_vbyte — Optional fee rate in sats per virtual byte. Pass None to let the node pick. Pass the value from a prior prepare_onchain_send to reproduce the previewed fee.
• utxos — Optional pinned input set. Pass the utxos returned by prepare_onchain_send (together with the same sat_per_vbyte) to broadcast a transaction with the exact inputs and fee shown in the preview. Pass None to let the node coin-select.

Returns the raw transaction, txid, and PSBT once broadcast. The transaction is broadcast immediately — this is not a dry run.

pub fn prepare_onchain_send( &self, destination: String, amount_or_all: String, sat_per_vbyte: Option<u32>, ) -> Result<PreparedOnchainSend, Error>

Preview an on-chain send without broadcasting or reserving UTXOs.

Runs CLN’s coin selection at the given fee rate and returns the inputs that would be spent, the fee, and the amount the recipient would receive. Safe to call repeatedly (e.g. while the user adjusts a fee slider) — nothing is locked.

To broadcast with the previewed values, pass the returned utxos and sat_per_vbyte back to onchain_send. Identical inputs at the same fee rate yield the same fee.

Use this for “Send Max” UIs. recipient_sat is the only authoritative post-fee amount the destination will receive for a sweep. NodeState.onchain_balance_msat includes the emergency reserve and the fee — neither of which leaves the wallet with the recipient. For the entry-point button label (a pre-fee approximation that updates without an RPC), use OnchainBalanceState::Available.withdrawable_sat.

Arguments

• destination — A Bitcoin address (bech32, p2sh, or p2tr).
• amount_or_all — Amount to send. Accepts:
  • "50000" or "50000sat" — 50,000 satoshis
  • "50000msat" — 50,000 millisatoshis
  • "all" — sweep the entire on-chain balance
• sat_per_vbyte — Fee rate in sats per virtual byte. Pass None to use the node’s “normal” priority feerate; the effective rate CLN picked is reported back in the result’s sat_per_vbyte field, which can be passed to onchain_send to reproduce it.

pub fn onchain_balance_state(&self) -> Result<OnchainBalanceState, Error>

Classify the on-chain wallet for the withdraw entry-point UI.

Runs three RPCs concurrently:

• list_funds — current confirmed/unconfirmed/immature on-chain balances.
• list_peer_channels — pending channel-close payouts that haven’t yet hit the wallet.
• fund_psbt(satoshi=All, reserve=0, normal feerate) — a non-locking probe whose response tells us exactly how much CLN will carve as the anchor-channel emergency reserve for this specific node, no client-side guessing required. The carved amount is computed from the response as total_inputs − excess − fee, which is identical to what CLN would carve on a real broadcast.

Cheaper to call than node_state() and answers a different question. Wallets typically call it once per render of the home screen.

For the exact post-fee recipient amount of a withdraw, use prepare_onchain_send; the withdrawable_sat returned here is a pre-fee, reserve-aware figure for the entry-point label.

pub fn onchain_fee_rates(&self) -> Result<OnchainFeeRates, Error>

On-chain fee rates, in sats per virtual byte, at several confirmation targets.

Sourced from the connected node’s view of the network — no 3rd-party HTTP calls. Use as the basis for a fee-picker UI; minimum_relay_sat_per_vbyte is the relay floor enforced at broadcast time and should be the lower bound of any slider.

pub fn onchain_receive(&self) -> Result<OnchainReceiveResponse, Error>

Generate a fresh on-chain Bitcoin address for receiving funds.

Returns both a bech32 (SegWit v0) and a p2tr (Taproot) address. Either can be shared with a sender. Deposited funds will appear in node_state().onchain_balance_msat once confirmed.

pub fn get_info(&self) -> Result<GetInfoResponse, Error>

Get information about the node.

Returns basic information about the node including its ID, alias, network, and channel counts.

pub fn list_peers(&self) -> Result<ListPeersResponse, Error>

List all peers connected to this node.

Returns information about all peers including their connection status.

pub fn list_peer_channels(&self) -> Result<ListPeerChannelsResponse, Error>

List all channels with peers.

Returns detailed information about all channels including their state, capacity, and balances.

pub fn list_funds(&self) -> Result<ListFundsResponse, Error>

List all funds available to the node.

Returns information about on-chain outputs and channel funds that are available or pending.

pub fn node_state(&self) -> Result<NodeState, Error>

Get a snapshot of the node’s balances, capacity, and connectivity.

Aggregates data from multiple RPCs into a single NodeState. Queries the node live on each call — not cached.

pub fn list_invoices( &self, label: Option<String>, invstring: Option<String>, payment_hash: Option<Vec<u8>>, offer_id: Option<String>, index: Option<ListIndex>, start: Option<u64>, limit: Option<u32>, ) -> Result<ListInvoicesResponse, Error>

List invoices (received payment requests). All parameters are optional filters; pass None to fetch all.

pub fn list_pays( &self, bolt11: Option<String>, payment_hash: Option<Vec<u8>>, status: Option<PayStatus>, index: Option<ListIndex>, start: Option<u64>, limit: Option<u32>, ) -> Result<ListPaysResponse, Error>

List outgoing payments. All parameters are optional filters; pass None to fetch all.

pub fn list_payments( &self, req: ListPaymentsRequest, ) -> Result<Vec<Payment>, Error>

List payments (sent and received), merged into a single timeline.

Fetches invoices and outgoing payments from the node, merges them into a unified list, and applies optional filters. Use list_invoices/list_pays for direct CLN access. Results are sorted newest-first.

pub fn stream_node_events(&self) -> Result<Arc<NodeEventStream>, Error>

Stream real-time events from the node.

Returns a NodeEventStream iterator. Call next() repeatedly to receive events as they occur (e.g., invoice payments).

The next() method blocks the calling thread until an event is available, but does not block the underlying async runtime, so other node methods can be called concurrently from other threads.

pub fn generate_diagnostic_data(&self) -> Result<String, Error>

Collect a diagnostic snapshot of the node and SDK state.

Returns a pretty-printed JSON string with shape: { "timestamp": <unix-secs>, "node": { ... }, "sdk": { "version": ..., "node_state": ... } }. The node object contains one entry per CLN RPC (getinfo, listpeerchannels, listfunds); each value is the serialized response, or { "error": "..." } if that RPC failed. Payment and invoice history are deliberately excluded to avoid leaking preimages, payment hashes, bolt11 strings, and labels into support dumps. Intended for support tickets.

pub fn lnurl_pay( &self, request: LnUrlPayRequest, ) -> Result<LnUrlPayResult, Error>

Execute an LNURL-pay flow (LUD-06).

Sends the chosen amount (and optional comment) to the service’s callback, receives and validates a BOLT11 invoice, pays it, and processes any success action (LUD-09/10).

Call the top-level parse_input first to obtain the LnUrlPayRequestData, then build an LnUrlPayRequest with the user’s chosen amount.

pub fn lnurl_withdraw( &self, request: LnUrlWithdrawRequest, ) -> Result<LnUrlWithdrawResult, Error>

Execute an LNURL-withdraw flow (LUD-03).

Creates an invoice on this node for the requested amount, sends it to the service’s callback URL, and the service pays it asynchronously.

Call the top-level parse_input first to obtain the LnUrlWithdrawRequestData, then build an LnUrlWithdrawRequest with the user’s chosen amount.

Trait Implementations

impl Drop for Node

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<UT> LiftRef<UT> for Node

type LiftType = Arc<Node>

impl<UT> LowerError<UT> for Node

fn lower_error(obj: Self) -> RustBuffer

Lower this value for scaffolding function return

impl<UT> LowerReturn<UT> for Node

type ReturnType = <Arc<Node> as LowerReturn<UniFfiTag>>::ReturnType

The type that should be returned by scaffolding functions for this type.

fn lower_return(obj: Self) -> Result<Self::ReturnType, RustCallError>

Lower the return value from an scaffolding call

fn handle_failed_lift( error: LiftArgsError, ) -> Result<Self::ReturnType, RustCallError>

Lower the return value for failed argument lifts

impl<UT> TypeId<UT> for Node

const TYPE_ID_META: MetadataBuffer