Lightning Network Structures
This object represents the number of blocks required for an on-chain lightning-related transaction to be confirmed.
It is used for estimating the transaction fee rate (feerate) for different transaction types in the context of permissionless transactions performed by the node. Different target types are background, normal, and high_priority.
| Parameter | Type | Description |
|---|---|---|
| background | integer | Used for transactions that can tolerate slower confirmation times when the transaction fee rate decreases. These transactions are not time-sensitive and can afford to wait longer for confirmation. The recommended range is 12 to 144 blocks to ensure a low feerate. |
| normal | integer | Used for transactions that we want to confirm promptly, without significant delay (e.g, transactions for opening payment channels). These transactions are important but not critical. Suggested value is 6 blocks to ensure a moderate feerate. |
| high_priority | integer | Used for transactions that require quick confirmation to prevent potential loss of funds (e.g. redeeming a Hashed Time Lock Contract (HTLC) on the blockchain before it times out). These transactions are time-critical and must be confirmed promptly to ensure the security of funds. Recommended value for high_priority is 1-2 blocks to ensure a high feerate. |
Using the recommended values in the above table with a coin that has a block time of 10 minutes, the equivalent time in minutes is:
background: 120 minutes to 1440 minutes (2 hours to 1 day).normal: 60 minutes (one hour).high_priority: 10 to 20 minutes.
| Parameter | Type | Description |
|---|---|---|
| allow_outbound_0conf | boolean | Optional, defaults to true. When setting an outbound channel, it can be used straight away without waiting for any on-chain confirmations. |
| force_announced_channel_preference | boolean | Optional, defaults to true. Set to force an incoming channel to match our announced channel preference in ChannelOptions announced_channel. |
| outbound_channels_confirmations | integer | Optional, defaults to 144. Confirmations we will wait for before considering an inbound channel locked in. |
| our_locktime_limit | boolean | Optional, defaults to 2016. Set to the amount of blocks we're willing to wait to claim money back to us. |
| min_funding_sats | boolean | Optional, defaults to 0. Minimum allowed satoshis when an inbound channel is funded. |
| max_funding_sats | boolean | Optional, defaults to 16777215. Maximum allowed satoshis when an inbound channel is funded. |
| max_htlc_minimum_msat | boolean | Optional, defaults to 18446744073709551615. The remote node sets a limit on the minimum size of HTLCs we can send to them. This allows us to limit the maximum minimum-size they can require. |
| min_max_htlc_value_in_flight_msat | boolean | Optional, defaults to 0. The remote node sets a limit on the maximum value of pending HTLCs to them at any given time to limit their funds exposure to HTLCs. This allows us to set a minimum such value. |
| max_channel_reserve_sats | boolean | Optional, defaults to 18446744073709551615. The remote node will require us to keep a certain amount in direct payment to ourselves at all time, ensuring that we are able to be punished if we broadcast an old state. This allows us to limit the amount which we will have to keep to ourselves (and cannot use for HTLCs). |
| min_max_accepted_htlcs | boolean | Optional, defaults to 0. The remote node sets a limit on the maximum number of pending HTLCs to them at any given time. This allows us to set a minimum such value. |
| Parameter | Type | Description |
|---|---|---|
| name | string | The name of the node that will be used in lightning explorers |
| listening port | integer | Optional, defaults to 9735. The port that this node listens for incoming connections on. |
| color | string | Optional, defaults to 2b6680. A hexidecimal color string which will be used in network graphs on lightning explorers |
| payment_retries | integer | Optional, defaults to 5. Number of times a payment will be retried if it fails. |
| backup_path | string | Optional. The backup path for channel backups, preferably on an external drive. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Exact for a specific amount or Max for whole balance. |
| value | object | Only required if type is Exact. The amount in BTC you want to open the channel with. |
The values in this object are only used if the channel is being opened by the user. If the channel is being opened by the counterparty, the values in this object are ignored.
If not specified when using the open_channel or update_channel methods, the values in this object will default to the values set in the coins configuration file.
| Parameter | Type | Description |
|---|---|---|
| inbound_channels_confirmations | string | Optional, defaults to 6. Should be set in coins file, and applies to all channels. Confirmations we will wait for before considering an inbound channel locked in. |
| max_inbound_in_flight_htlc_percent | integer | Optional, defaults to 10. Should be set in coins file, and applies to all channels. Sets the percentage of the channel value we will cap the total value of outstanding inbound HTLCs to. |
| our_htlc_minimum_msat | integer | Optional, defaults to 1. The smallest value HTLC we will accept to process. The channel gets closed any time our counterparty misbehaves by sending us an HTLC with a value smaller than this. |
| announced_channel | boolean | Optional, defaults to false. Set to announce the channel publicly and notify all nodes that they can route via this channel. GUIs and wallet apps should be set to false. |
| commit_upfront_shutdown_pubkey | boolean | Optional, defaults to true. When true (and the counterparty agrees), the user must use the same key for cooperative closing. This prevents a user from changing the destination address in a cooperative close, which slightly increases security (however, this option is not required if the counterparty does not support it and a channel can be accepted regardless). Note that the key for forced closing is always fixed when opening a channel and is different from shutdown_pubkey. |
| counterparty_locktime | integer | Optional, defaults to 144. The number of blocks we require our counterparty to wait to claim their money on chainif they broadcast a revoked transaction. We have to be online at least once during this time to punish our counterparty for broadcasting a revoked transaction. We have to account also for the time to broadcast and confirm our transaction, possibly with time in between to RBF (Replace-By-Fee) the spending transaction. |
| negotiate_scid_privacy | integer | Optional, defaults to false. If true, we attempt to negotiate the scid_privacy (referred to as scid_alias in the BOLTs) option for outbound private channels. This provides better privacy by not including our real on-chain channel UTXO in each invoice and requiring that our counterparty only relay HTLCs to us using the channel's SCID alias. |
| their_channel_reserve_sats | boolean | Optional, defaults to 10000 or 1% of channel value. The minimum balance that the other node has to maintain on their side, at all times. This ensures that if our counterparty broadcasts a revoked state, we can punish them by claiming at least this value on chain. |
For GUIs and wallet apps, it is recommended to set announced_channel to false (the default value), as the node is not expected to be reliably online.
| Parameter | Type | Description |
|---|---|---|
| proportional_fee_in_millionths_sats | integer | Optional, defaults to 0. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| base_fee_msat | integer | Optional, defaults to 1000. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| cltv_expiry_delta | integer | Optional, defaults to 72. Blocks until CheckLockTimeVerify (CLTV) expiry. |
| max_dust_htlc_exposure_msat | integer | Optional, defaults to 5000000. Limit our total exposure to in-flight HTLCs which are burned to fees as they are too small to claim on-chain. |
| force_close_avoidance_max_fee_sats | integer | Optional, defaults to 1000. The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. |
| Parameter | Type | Description |
|---|---|---|
| channel_id | string | Optional. Unique string identifying a channel by its ID. |
| counterparty_node_id | string | Optional. A hexidecimal string identifying a counterparty node. |
| funding_tx | string | Optional. A transaction ID which added funds. |
| from_funding_value | integer | Optional. The minimum value of channel funding in satoshis. |
| to_funding_value | integer | Optional. The maximum value of channel funding in satoshis. |
| channel_type | string | Optional. Inbound or Outbound. |
| closing_tx | integer | Optional. A transaction ID which closed the channel. |
| closure_reason | integer | Optional. The reason a channel was closed. |
| claiming_tx | integer | Optional. The ID of the transaction that returned the remaining outbound funds when the channel was closed to our on-chain address. |
| from_claimed_balance | integer | Optional. The minimum balance of channel funds claimed in satoshis. |
| to_claimed_balance | integer | Optional. The maximum balance of channel funds claimed in satoshis. |
| channel_visibility | integer | Optional. Public or Private. |
| Parameter | Type | Description |
|---|---|---|
| channel_id | string | Optional. Unique string identifying a channel by its ID. |
| counterparty_node_id | string | Optional. A hexidecimal string identifying a counterparty node. |
| funding_tx | string | Optional. A transaction ID which added funds. |
| from_funding_value_sats | integer | Optional. The minimum value of channel funding in satoshis. |
| to_funding_value_sats | integer | Optional. The maximum value of channel funding in satoshis. |
| is_outbound | boolean | Optional. If true, limits the response to outbound channels only. |
| from_balance_msat | integer | Optional. The minimum channel balance in millisatoshis. |
| to_balance_msat | integer | Optional. The maximum channel balance in millisatoshis. |
| from_outbound_capacity_msat | integer | Optional. The minimum outbound capacity of the channel balance in millisatoshis. |
| to_outbound_capacity_msat | integer | Optional. The maximum outbound capacity of the channel balance in millisatoshis. |
| from_inbound_capacity_msat | integer | Optional. The minimum inbound capacity of the channel balance in millisatoshis. |
| to_inbound_capacity_msat | integer | Optional. The maximum inbound capacity of the channel balance in millisatoshis. |
| confirmed | boolean | Optional. If true, only channels with channel opening transactions that passed the number of confirmations required for the channel to be usable will be returned. |
| is_usable | boolean | Optional. If true, only channels that are confirmed and the counterparty is online, meaning that these channels can be used for payments will be returned. |
| is_public | boolean | Optional. If true, only channels that our node announces to the lightning network, these channels are visible on lightning explorers will be returned. |
| Parameter | Type | Description |
|---|---|---|
| type | string | The payment type. Accepted values are invoice or keysend. |
| invoice | string | Only used if type is invoice. An identifying string which represents the invoice. |
| destination | string | Only used if type is keysend. A node_pubkey (which is also the node address in lightning context). Not to be confused with an onchain address. |
| amount_in_msat | string | Only used if type is keysend. Amount to be paid, in millisatoshis (A thousandth of a satoshi; the same as 0.00000000001 bitcoin). |
| expiry | string | Only used if type is keysend. Optional, defaults to 3600. Seconds until the payment expires. |
| Parameter | Type | Description |
|---|---|---|
| payment_type | object | A standard LightningPaymentType object. |
| description | string | Optional. A note to indicate the purpose of the invoice. |
| status | string | Optional. Accepted values: pending, succeeded, failed. |
| from_amount_msat | integer | Optional. Minimum amount sent in millisatoshis |
| to_amount_msat | integer | Optional. Maximum amount sent in millisatoshis |
| from_fee_paid_msat | integer | Optional. Minimum transaction fee paid in millisatoshis |
| to_fee_paid_msat | integer | Optional. Maximum transaction fee paid in millisatoshis |
| from_timestamp | string | Optional. Minimum timestamp (in milliseconds) of payment results to return. |
| to_timestamp | string | Optional. Maximum timestamp (in milliseconds) of payment results to return. |
| Parameter | Type | Description |
|---|---|---|
| type | object | Accepted values are Outbound Payment or Inbound Payment. |
| destination | string | Only used if type is Outbound Payment. A pubkey which will receive the payment. |