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 | Type | Required | 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 | Required | Default | Description |
|---|---|---|---|---|
| allow_outbound_0conf | boolean | ✗ | true | When setting an outbound channel, it can be used straight away without waiting for any on-chain confirmations. |
| force_announced_channel_preference | boolean | ✗ | true | Set to force an incoming channel to match our announced channel preference in ChannelOptions announced_channel. |
| outbound_channels_confirmations | integer | ✗ | 144 | Confirmations we will wait for before considering an inbound channel locked in. |
| our_locktime_limit | boolean | ✗ | 2016 | Set to the amount of blocks we're willing to wait to claim money back to us. |
| min_funding_sats | boolean | ✗ | 0 | Minimum allowed satoshis when an inbound channel is funded. |
| max_funding_sats | boolean | ✗ | 16777215 | Maximum allowed satoshis when an inbound channel is funded. |
| max_htlc_minimum_msat | boolean | ✗ | 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 | ✗ | 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 | ✗ | 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 | ✗ | 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 | Required | Default | Description |
|---|---|---|---|---|
| name | string | ✓ | - | The name of the node that will be used in lightning explorers |
| listening port | integer | ✗ | 9735 | The port that this node listens for incoming connections on. |
| color | string | ✗ | 2b6680 | A hexadecimal color string which will be used in network graphs on lightning explorers |
| payment_retries | integer | ✗ | 5 | Number of times a payment will be retried if it fails. |
| backup_path | string | ✗ | - | The backup path for channel backups, preferably on an external drive. |
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| type | string | ✓ | - | Exact for a specific amount or Max for whole balance. |
| value | object | ✗ | - | 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 | Required | Default | Description |
|---|---|---|---|---|
| inbound_channels_confirmations | string | ✗ | 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 | ✗ | 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 | ✗ | 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 | ✗ | 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 | ✗ | 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 | ✗ | 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 | ✗ | 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 | ✗ | 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 | Type | Required | Default | Description |
|---|---|---|---|---|
| proportional_fee_in_millionths_sats | integer | ✗ | 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 | ✗ | 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 | ✗ | 72 | Blocks until CheckLockTimeVerify (CLTV) expiry. |
| max_dust_htlc_exposure_msat | integer | ✗ | 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 | ✗ | 1000 | The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| channel_id | string | ✗ | Unique string identifying a channel by its ID. |
| counterparty_node_id | string | ✗ | A hexadecimal string identifying a counterparty node. |
| funding_tx | string | ✗ | A transaction ID which added funds. |
| from_funding_value | integer | ✗ | The minimum value of channel funding in satoshis. |
| to_funding_value | integer | ✗ | The maximum value of channel funding in satoshis. |
| channel_type | string | ✗ | Inbound or Outbound. |
| closing_tx | integer | ✗ | A transaction ID which closed the channel. |
| closure_reason | integer | ✗ | The reason a channel was closed. |
| claiming_tx | integer | ✗ | 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 | ✗ | The minimum balance of channel funds claimed in satoshis. |
| to_claimed_balance | integer | ✗ | The maximum balance of channel funds claimed in satoshis. |
| channel_visibility | integer | ✗ | Public or Private. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| channel_id | string | ✗ | Unique string identifying a channel by its ID. |
| counterparty_node_id | string | ✗ | A hexadecimal string identifying a counterparty node. |
| funding_tx | string | ✗ | A transaction ID which added funds. |
| from_funding_value_sats | integer | ✗ | The minimum value of channel funding in satoshis. |
| to_funding_value_sats | integer | ✗ | The maximum value of channel funding in satoshis. |
| is_outbound | boolean | ✗ | If true, limits the response to outbound channels only. |
| from_balance_msat | integer | ✗ | The minimum channel balance in millisatoshis. |
| to_balance_msat | integer | ✗ | The maximum channel balance in millisatoshis. |
| from_outbound_capacity_msat | integer | ✗ | The minimum outbound capacity of the channel balance in millisatoshis. |
| to_outbound_capacity_msat | integer | ✗ | The maximum outbound capacity of the channel balance in millisatoshis. |
| from_inbound_capacity_msat | integer | ✗ | The minimum inbound capacity of the channel balance in millisatoshis. |
| to_inbound_capacity_msat | integer | ✗ | The maximum inbound capacity of the channel balance in millisatoshis. |
| confirmed | boolean | ✗ | 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 | ✗ | 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 | ✗ | If true, only channels that our node announces to the lightning network, these channels are visible on lightning explorers will be returned. |
| Parameter | Type | Required | 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. Seconds until the payment expires. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| payment_type | object | ✗ | A standard LightningPaymentType object. |
| description | string | ✗ | A note to indicate the purpose of the invoice. |
| status | string | ✗ | Accepted values: pending, succeeded, failed. |
| from_amount_msat | integer | ✗ | Minimum amount sent in millisatoshis |
| to_amount_msat | integer | ✗ | Maximum amount sent in millisatoshis |
| from_fee_paid_msat | integer | ✗ | Minimum transaction fee paid in millisatoshis |
| to_fee_paid_msat | integer | ✗ | Maximum transaction fee paid in millisatoshis |
| from_timestamp | string | ✗ | Minimum timestamp in unix epoch format of payment results to return. |
| to_timestamp | string | ✗ | Maximum timestamp in unix epoch format of payment results to return. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | ✓ | Accepted values are Outbound Payment or Inbound Payment. |
| destination | string | ✗ | Only used if type is Outbound Payment. A pubkey which will receive the payment. |
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| force_announced_channel_preference | boolean | ✗ | false | The user may override this preference in the channel opening request method call. |
| their_to_self_delay | integer | ✗ | 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). |
| our_to_self_delay | integer | ✗ | 1008 | The time that our counterparty requires us to wait to claim our money, if we broadcast a revoked transaction. |
| our_htlc_minimum_msat | integer | ✗ | 0 | The smallest value HTLC we will accept to forward from the counterparty. |
| max_accepted_htlcs | integer | ✗ | 483 | The maximum number of HTLCs we will accept from the counterparty. |
| min_max_htlc_value_in_flight_msat | boolean | ✗ | 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 | ✗ | 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 | ✗ | 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 | Required | Default | Description |
|---|---|---|---|---|
| node_pubkey | string | ✓ | - | Lightning node pubkey |
| backup_password | string | ✓ | - | Backup password used to encrypt channel backups |
| listening_port | integer | ✗ | 9735 | Listening port for the Lightning network |
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| type | string | ✓ | - | Exact for a specific amount or Max for whole balance. |
| value | object | ✗ | - | Required if type is Exact. The amount in BTC you want to open the channel with. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| forwarding_fee_proportional_millionths | integer | ✗ | Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| forwarding_fee_base_msat | integer | ✗ | Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats. |
| cltv_expiry_delta | integer | ✗ | Blocks until CheckLockTimeVerify (CLTV) expiry. |
| max_dust_htlc_exposure_msat | integer | ✗ | 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 | ✗ | The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| channel_id | string | ✗ | Unique string identifying a channel by its ID. |
| counterparty_node_id | string | ✗ | A hexadecimal string identifying a counterparty node. |
| funding_tx | string | ✗ | A transaction ID which added funds. |
| from_funding_value | integer | ✗ | The minimum value of channel funding in satoshis. |
| to_funding_value | integer | ✗ | The maximum value of channel funding in satoshis. |
| channel_type | string | ✗ | Inbound or Outbound. |
| closing_tx | integer | ✗ | A transaction ID which closed the channel. |
| closure_reason | integer | ✗ | The reason a channel was closed. |
| claiming_tx | integer | ✗ | 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 | ✗ | The minimum balance of channel funds claimed in satoshis. |
| to_claimed_balance | integer | ✗ | The maximum balance of channel funds claimed in satoshis. |
| channel_visibility | integer | ✗ | Public or Private. |