Lightning Common Structures
structureslightning_common_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* = required | 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. |
| 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. |
| 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. |
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* = required | Type | Description |
|---|---|---|
| allow_outbound_0conf | booleandefault: true | 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 | booleandefault: true | Optional, defaults to true. Set to force an incoming channel to match our announced channel preference in ChannelOptions announced_channel. |
| max_channel_reserve_sats | booleandefault: 18446744073709551615 | 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). |
| max_funding_sats | booleandefault: 16777215 | Optional, defaults to 16777215. Maximum allowed satoshis when an inbound channel is funded. |
| max_htlc_minimum_msat | booleandefault: 18446744073709551615 | 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_funding_sats | booleandefault: 0 | Optional, defaults to 0. Minimum allowed satoshis when an inbound channel is funded. |
| min_max_accepted_htlcs | booleandefault: 0 | 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. |
| min_max_htlc_value_in_flight_msat | booleandefault: 0 | 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. |
| our_locktime_limit | booleandefault: 2016 | Optional, defaults to 2016. Set to the amount of blocks we're willing to wait to claim money back to us. |
| outbound_channels_confirmations | integerdefault: 144 | Optional, defaults to 144. Confirmations we will wait for before considering an inbound channel locked in. |
| Parameter* = required | Type | Description |
|---|---|---|
| name* | string | The name of the node that will be used in lightning explorers |
| backup_path | string | Optional. The backup path for channel backups, preferably on an external drive. |
| color | stringdefault: 2b6680 | Optional, defaults to 2b6680. A hexadecimal color string which will be used in network graphs on lightning explorers |
| listening port | integerdefault: 9735 | Optional, defaults to 9735. The port that this node listens for incoming connections on. |
| payment_retries | integerdefault: 5 | Optional, defaults to 5. Number of times a payment will be retried if it fails. |
| Parameter* = required | Type | Description |
|---|---|---|
| type* | string | Exact for a specific amount or Max for whole balance. |
| value | object | Optional. 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* = required | Type | Description |
|---|---|---|
| announced_channel | booleandefault: false | 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 | booleandefault: true | 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 | integerdefault: 144 | 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. |
| inbound_channels_confirmations | stringdefault: 6 | 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 | integerdefault: 10 | 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. |
| negotiate_scid_privacy | integerdefault: false | 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. |
| our_htlc_minimum_msat | integerdefault: 1 | 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. |
| their_channel_reserve_sats | booleandefault: 10000 | Optional, defaults to 10000. 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* = required | Type | Description |
|---|---|---|
| base_fee_msat | integerdefault: 1000 | 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 | integerdefault: 72 | Optional, defaults to 72. Blocks until CheckLockTimeVerify (CLTV) expiry. |
| force_close_avoidance_max_fee_sats | integerdefault: 1000 | Optional, defaults to 1000. The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. |
| max_dust_htlc_exposure_msat | integerdefault: 5000000 | 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. |
| proportional_fee_in_millionths_sats | integerdefault: 0 | Optional, defaults to 0. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| Parameter* = required | Type | Description |
|---|---|---|
| channel_id | string | Optional. Unique string identifying a channel by its ID. |
| channel_type | string | Optional. Inbound or Outbound. |
| channel_visibility | integer | Optional. Public or Private. |
| 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. |
| closing_tx | integer | Optional. A transaction ID which closed the channel. |
| closure_reason | integer | Optional. The reason a channel was closed. |
| counterparty_node_id | string | Optional. A hexadecimal string identifying a counterparty node. |
| from_claimed_balance | integer | Optional. The minimum balance of channel funds claimed in satoshis. |
| from_funding_value | integer | Optional. The minimum value of channel funding in satoshis. |
| funding_tx | string | Optional. A transaction ID which added funds. |
| to_claimed_balance | integer | Optional. The maximum balance of channel funds claimed in satoshis. |
| to_funding_value | integer | Optional. The maximum value of channel funding in satoshis. |
| Parameter* = required | Type | Description |
|---|---|---|
| channel_id | string | Optional. Unique string identifying a channel by its ID. |
| 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. |
| counterparty_node_id | string | Optional. A hexadecimal string identifying a counterparty node. |
| from_balance_msat | integer | Optional. The minimum channel balance in millisatoshis. |
| from_funding_value_sats | integer | Optional. The minimum value of channel funding in satoshis. |
| from_inbound_capacity_msat | integer | Optional. The minimum inbound capacity of the channel balance in millisatoshis. |
| from_outbound_capacity_msat | integer | Optional. The minimum outbound capacity of the channel balance in millisatoshis. |
| funding_tx | string | Optional. A transaction ID which added funds. |
| is_outbound | boolean | Optional. If true, limits the response to outbound channels only. |
| 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. |
| 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. |
| to_balance_msat | integer | Optional. The maximum channel balance in millisatoshis. |
| to_funding_value_sats | integer | Optional. The maximum value of channel funding in satoshis. |
| to_inbound_capacity_msat | integer | Optional. The maximum inbound capacity of the channel balance in millisatoshis. |
| to_outbound_capacity_msat | integer | Optional. The maximum outbound capacity of the channel balance in millisatoshis. |
| Parameter* = required | Type | Description |
|---|---|---|
| type* | string | The payment type. Accepted values are invoice or `keysend`. |
| amount_in_msat | string | Optional. Only used if type is keysend. Amount to be paid, in millisatoshis (A thousandth of a satoshi; the same as 0.00000000001 bitcoin). |
| destination | string | Optional. 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. |
| expiry | string | Optional. Only used if type is keysend. Seconds until the payment expires. |
| invoice | string | Optional. Only used if type is invoice. An identifying string which represents the invoice. |
| Parameter* = required | Type | Description |
|---|---|---|
| description | string | Optional. A note to indicate the purpose of the invoice. |
| from_amount_msat | integer | Optional. Minimum amount sent in millisatoshis |
| from_fee_paid_msat | integer | Optional. Minimum transaction fee paid in millisatoshis |
| from_timestamp | string | Optional. Minimum timestamp in unix epoch format of payment results to return. |
| payment_type | object | Optional. A standard LightningPaymentType object. |
| status | string | Optional. Accepted values: pending, succeeded, failed. |
| to_amount_msat | integer | Optional. Maximum amount sent in millisatoshis |
| to_fee_paid_msat | integer | Optional. Maximum transaction fee paid in millisatoshis |
| to_timestamp | string | Optional. Maximum timestamp in unix epoch format of payment results to return. |
| Parameter* = required | Type | Description |
|---|---|---|
| type* | string | Accepted values are Outbound Payment or Inbound Payment. |
| destination | string | Optional. Only used if type is Outbound Payment. A pubkey which will receive the payment. |
| Parameter* = required | Type | Description |
|---|---|---|
| force_announced_channel_preference | booleandefault: false | Optional, defaults to false. The user may override this preference in the channel opening request method call. |
| max_accepted_htlcs | integerdefault: 483 | Optional, defaults to 483. The maximum number of HTLCs we will accept from the counterparty. |
| max_channel_reserve_sats | booleandefault: 18446744073709551615 | 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 | booleandefault: 0 | 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. |
| min_max_htlc_value_in_flight_msat | booleandefault: 0 | 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. |
| our_htlc_minimum_msat | integerdefault: 0 | Optional, defaults to 0. The smallest value HTLC we will accept to forward from the counterparty. |
| our_to_self_delay | integerdefault: 1008 | Optional, defaults to 1008. The time that our counterparty requires us to wait to claim our money, if we broadcast a revoked transaction. |
| their_to_self_delay | integerdefault: 1008 | Optional, defaults to 1008. The time that we require our counterparty to wait to claim their money, if they broadcast a revoked transaction. This can be increased to provide more punishment for broadcasting old states, but will result in higher fees (since emergency transactions will be larger). |
| Parameter* = required | Type | Description |
|---|---|---|
| backup_password* | string | Backup password used to encrypt channel backups |
| node_pubkey* | string | Lightning node pubkey |
| listening_port | integerdefault: 9735 | Optional, defaults to 9735. Listening port for the Lightning network |
| Parameter* = required | Type | Description |
|---|---|---|
| type* | string | Exact for a specific amount or Max for whole balance. |
| value | object | Optional. Required if type is Exact. The amount in BTC you want to open the channel with. |
| Parameter* = required | Type | Description |
|---|---|---|
| cltv_expiry_delta | integer | Optional. Blocks until CheckLockTimeVerify (CLTV) expiry. |
| force_close_avoidance_max_fee_sats | integer | Optional. The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. |
| forwarding_fee_base_msat | integer | Optional. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| forwarding_fee_proportional_millionths | integer | Optional. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| max_dust_htlc_exposure_msat | integer | Optional. Limit our total exposure to in-flight HTLCs which are burned to fees as they are too small to claim on-chain. |
| Parameter* = required | Type | Description |
|---|---|---|
| channel_id | string | Optional. Unique string identifying a channel by its ID. |
| channel_type | string | Optional. Inbound or Outbound. |
| channel_visibility | integer | Optional. Public or Private. |
| 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. |
| closing_tx | integer | Optional. A transaction ID which closed the channel. |
| closure_reason | integer | Optional. The reason a channel was closed. |
| counterparty_node_id | string | Optional. A hexadecimal string identifying a counterparty node. |
| from_claimed_balance | integer | Optional. The minimum balance of channel funds claimed in satoshis. |
| from_funding_value | integer | Optional. The minimum value of channel funding in satoshis. |
| funding_tx | string | Optional. A transaction ID which added funds. |
| to_claimed_balance | integer | Optional. The maximum balance of channel funds claimed in satoshis. |
| to_funding_value | integer | Optional. The maximum value of channel funding in satoshis. |