Struct NodeState 

pub struct NodeState {

    pub id: String,
    pub block_height: u32,
    pub network: String,
    pub version: String,
    pub alias: Option<String>,
    pub color: String,
    pub num_active_channels: u32,
    pub num_pending_channels: u32,
    pub num_inactive_channels: u32,
    pub channels_balance_msat: u64,
    pub max_payable_msat: u64,
    pub total_channel_capacity_msat: u64,
    pub max_chan_reserve_msat: u64,
    pub onchain_balance_msat: u64,
    pub unconfirmed_onchain_balance_msat: u64,
    pub immature_onchain_balance_msat: u64,
    pub pending_onchain_balance_msat: u64,
    pub max_receivable_single_payment_msat: u64,
    pub total_inbound_liquidity_msat: u64,
    pub connected_channel_peers: Vec<String>,
    pub utxos: Vec<FundOutput>,
    pub total_onchain_msat: u64,
    pub total_balance_msat: u64,
    pub spendable_balance_msat: u64,
}

A point-in-time snapshot of the node’s balances, capacity, and connectivity. Returned by node_state().

All amounts are in millisatoshis (1 sat = 1000 msat).

Fields

id: String

The node’s public key as a lowercase hex string (66 chars).

block_height: u32

Latest block height the node has synced to.

network: String

The Bitcoin network this node is running on (e.g. “bitcoin”, “regtest”).

version: String

CLN version string (e.g. “v24.11”).

alias: Option<String>

Human-readable node alias, if set.

color: String

3-byte RGB color of the node, as a lowercase hex string (6 chars).

num_active_channels: u32

Number of channels that are open and operational. These are the channels that contribute to channels_balance_msat, max_payable_msat, total_channel_capacity_msat, and total_inbound_liquidity_msat.

num_pending_channels: u32

Number of channels that are being opened but not yet confirmed. Pending channels do not contribute to any balance or capacity field on this snapshot; their funds show up only after they transition to active.

num_inactive_channels: u32

Number of channels that are open but the peer is offline. Inactive channels hold balance but cannot be used for payments until the peer reconnects; they do not contribute to max_payable_msat or total_inbound_liquidity_msat (those are computed from the live spendable_msat / receivable_msat reported by CLN, which goes to zero when the peer is offline).

channels_balance_msat: u64

Total our-side balance across all open channels, including amounts that protocol reserves make unspendable.

This is the field a wallet’s home screen should show as the user’s “Lightning balance” — it reflects what they own off-chain, matching what they’d expect to see at a glance.

Do not use this to gate a send button: some of it is locked in channel reserves. Use max_payable_msat for that.

max_payable_msat: u64

Aggregate spendable amount across all open channels. Equal to channels_balance_msat - max_chan_reserve_msat.

This is the field a send screen should gate against — it is what the user can actually move right now over Lightning in total.

Caveat: a single Lightning payment is additionally bounded by the largest channel’s own spendable_msat. Reaching this full aggregate amount in one payment requires multi-path-payment support from the recipient and a working route.

total_channel_capacity_msat: u64

Sum of all open channel capacities (your side + remote side).

max_chan_reserve_msat: u64

Amount locked in protocol channel reserves, computed as channels_balance_msat - max_payable_msat. These sats are yours on paper but cannot be spent until the channel closes.

onchain_balance_msat: u64

Confirmed on-chain balance available for spending or opening channels.

unconfirmed_onchain_balance_msat: u64

On-chain balance from transactions that have not yet been confirmed.

immature_onchain_balance_msat: u64

On-chain balance confirmed but not yet spendable (e.g. coinbase outputs inside the 100-block maturation window).

pending_onchain_balance_msat: u64

On-chain balance locked in channels that are being closed. These funds will become available once the close is confirmed.

max_receivable_single_payment_msat: u64

Largest single Lightning payment the node can receive without splitting across channels. Bounded by the inbound capacity of the largest open channel.

total_inbound_liquidity_msat: u64

Total amount you can receive across all open channels combined.

connected_channel_peers: Vec<String>

Lowercase hex public keys of peers we have at least one channel with and are currently connected to. Peers we’re connected to but have no channel with are not represented here; for routing-node use cases, query list_peers() directly.

utxos: Vec<FundOutput>

Unspent on-chain outputs owned by the node’s wallet. Excludes spent outputs; includes confirmed, unconfirmed, immature, and reserved UTXOs (callers can filter by status and reserved).

total_onchain_msat: u64

All non-pending on-chain balance buckets summed: onchain_balance_msat + unconfirmed_onchain_balance_msat + immature_onchain_balance_msat. Excludes funds locked in closing channels (pending_onchain_balance_msat) since those are not yet on-chain UTXOs.

total_balance_msat: u64

Everything the user owns, summed: channel balance (including protocol reserves) + all on-chain buckets + funds locked in closing channels. The “total holdings” number a wallet home screen typically shows.

spendable_balance_msat: u64

What the user can spend right now: max_payable_msat + onchain_balance_msat. Excludes reserves, unconfirmed, immature, and pending amounts. The number a send-money screen should gate against.

Trait Implementations

impl Clone for NodeState

fn clone(&self) -> NodeState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<UT> ConvertError<UT> for NodeState

fn try_convert_unexpected_callback_error( e: UnexpectedUniFFICallbackError, ) -> Result<Self>

impl<UT> FfiConverter<UT> for NodeState

const TYPE_ID_META: MetadataBuffer

Type ID metadata, serialized into a MetadataBuffer.

type FfiType = RustBuffer

The low-level type used for passing values of this type over the FFI.

fn lower(v: Self) -> RustBuffer

Lower a rust value of the target type, into an FFI value of type Self::FfiType.

fn try_lift(buf: RustBuffer) -> Result<Self>

Lift a rust value of the target type, from an FFI value of type Self::FfiType.

fn write(obj: Self, buf: &mut Vec<u8>)

Write a rust value into a buffer, to send over the FFI in serialized form.

fn try_read(buf: &mut &[u8]) -> Result<Self>

Read a rust value from a buffer, received over the FFI in serialized form.

impl<UT> Lift<UT> for NodeState

type FfiType = <NodeState as FfiConverter<UT>>::FfiType

fn try_lift(v: Self::FfiType) -> Result<Self>

fn try_read(buf: &mut &[u8]) -> Result<Self>

fn try_lift_from_rust_buffer(v: RustBuffer) -> Result<Self, Error>

Convenience method

impl<UT> LiftRef<UT> for NodeState

type LiftType = NodeState

impl<UT> LiftReturn<UT> for NodeState

type ReturnType = <NodeState as Lift<UT>>::FfiType

FFI return type for trait interfaces

fn try_lift_successful_return(v: Self::ReturnType) -> Result<Self>

Lift a successfully returned value from a trait interface

fn lift_foreign_return( ffi_return: Self::ReturnType, call_status: RustCallStatus, ) -> Self

Lift a foreign returned value from a trait interface

fn lift_error(_buf: RustBuffer) -> Self

Lift a Rust value for a callback interface method error result

fn handle_callback_unexpected_error(e: UnexpectedUniFFICallbackError) -> Self

Lift a Rust value for an unexpected callback interface error

impl<UT> Lower<UT> for NodeState

type FfiType = <NodeState as FfiConverter<UT>>::FfiType

fn lower(obj: Self) -> Self::FfiType

fn write(obj: Self, buf: &mut Vec<u8>)

fn lower_into_rust_buffer(obj: Self) -> RustBuffer

Convenience method

impl<UT> LowerError<UT> for NodeState

fn lower_error(obj: Self) -> RustBuffer

Lower this value for scaffolding function return

impl<UT> LowerReturn<UT> for NodeState

type ReturnType = <NodeState as Lower<UT>>::FfiType

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

fn lower_return(v: 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 Serialize for NodeState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<UT> TypeId<UT> for NodeState

const TYPE_ID_META: MetadataBuffer