Komodo Docs
GitHub

Lightning Common Structures

lightning-common-structuresstructureslightning_common_structures

ConfirmationTargets

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.

CounterpartyChannelConfig

Parameter Type Required Default Description
allow_outbound_0conf boolean – 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 boolean – true Optional, defaults to true. Set to force an incoming channel to match our announced channel preference in ChannelOptions announced_channel.
outbound_channels_confirmations integer – 144 Optional, defaults to 144. Confirmations we will wait for before considering an inbound channel locked in.
our_locktime_limit boolean – 2016 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 – 0 Optional, defaults to 0. Minimum allowed satoshis when an inbound channel is funded.
max_funding_sats boolean – 16777215 Optional, defaults to 16777215. Maximum allowed satoshis when an inbound channel is funded.
max_htlc_minimum_msat boolean – 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_max_htlc_value_in_flight_msat boolean – 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.
max_channel_reserve_sats boolean – 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 boolean – 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.

LightningActivationParams

Parameter Type Required Default Description
name string ✓ The name of the node that will be used in lightning explorers
listening port integer – 9735 Optional, defaults to 9735. The port that this node listens for incoming connections on.
color string – 2b6680 Optional, defaults to 2b6680. A hexadecimal color string which will be used in network graphs on lightning explorers
payment_retries integer – 5 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.

LightningChannelAmount

Parameter Type Required 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.

LightningChannelConfig

Parameter Type Required Default Description
inbound_channels_confirmations string – 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 integer – 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.
our_htlc_minimum_msat integer – 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.
announced_channel boolean – 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 boolean – 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 integer – 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.
negotiate_scid_privacy integer – 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.
their_channel_reserve_sats boolean – 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.

LightningChannelOptions

Parameter Type Required Default Description
proportional_fee_in_millionths_sats integer – 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.
base_fee_msat integer – 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 integer – 72 Optional, defaults to 72. Blocks until CheckLockTimeVerify (CLTV) expiry.
max_dust_htlc_exposure_msat integer – 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.
force_close_avoidance_max_fee_sats integer – 1000 Optional, defaults to 1000. The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds.

LightningClosedChannelsFilter

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.

LightningOpenChannelsFilter

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.

LightningPayment

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.

LightningPaymentFilter

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.

LightningPaymentType

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.

ChannelConfigLimits

Parameter Type Required Default Description
force_announced_channel_preference boolean – false Optional, defaults to false. The user may override this preference in the channel opening request method call.
their_to_self_delay integer – 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).
our_to_self_delay integer – 1008 Optional, defaults to 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 Optional, defaults to 0. The smallest value HTLC we will accept to forward from the counterparty.
max_accepted_htlcs integer – 483 Optional, defaults to 483. The maximum number of HTLCs we will accept from the counterparty.
min_max_htlc_value_in_flight_msat boolean – 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.
max_channel_reserve_sats boolean – 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 boolean – 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.

LightningActivationParams

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 Optional, defaults to 9735. Listening port for the Lightning network

LightningChannelValue

Parameter Type Required 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.

LightningChannelConfig

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.

LightningClosedChannelsFilter

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.