From 4d61ce9ab58fde1faa03fc73ba315198166ad4bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hampus=20Sj=C3=B6berg?= Date: Tue, 21 Jan 2025 16:54:42 +0400 Subject: [PATCH] Update lightning.proto --- proto/lightning.proto | 384 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 360 insertions(+), 24 deletions(-) diff --git a/proto/lightning.proto b/proto/lightning.proto index d76b78a80..409564e53 100644 --- a/proto/lightning.proto +++ b/proto/lightning.proto @@ -143,6 +143,13 @@ service Lightning { */ rpc GetInfo (GetInfoRequest) returns (GetInfoResponse); + /* lncli: 'getdebuginfo' + GetDebugInfo returns debug information concerning the state of the daemon + and its subsystems. This includes the full configuration and the latest log + entries from the log file. + */ + rpc GetDebugInfo (GetDebugInfoRequest) returns (GetDebugInfoResponse); + /** lncli: `getrecoveryinfo` GetRecoveryInfo returns information concerning the recovery mode including whether it's in a recovery mode, whether the recovery is finished, and the @@ -322,7 +329,7 @@ service Lightning { optionally specify the add_index and/or the settle_index. If the add_index is specified, then we'll first start by sending add invoice events for all invoices with an add_index greater than the specified value. If the - settle_index is specified, the next, we'll send out all settle events for + settle_index is specified, then next, we'll send out all settle events for invoices with a settle_index greater than the specified value. One or both of these fields can be set. If no fields are set, then we'll only send out the latest add/settle events. @@ -341,13 +348,13 @@ service Lightning { */ rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse); - /* + /* lncli: `deletepayments` DeletePayment deletes an outgoing payment from DB. Note that it will not attempt to delete an In-Flight payment, since that would be unsafe. */ rpc DeletePayment (DeletePaymentRequest) returns (DeletePaymentResponse); - /* + /* lncli: `deletepayments --all` DeleteAllPayments deletes all outgoing payments from DB. Note that it will not attempt to delete In-Flight payments, since that would be unsafe. */ @@ -479,7 +486,7 @@ service Lightning { rpc ExportAllChannelBackups (ChanBackupExportRequest) returns (ChanBackupSnapshot); - /* + /* lncli: `verifychanbackup` VerifyChanBackup allows a caller to verify the integrity of a channel backup snapshot. This method will accept either a packed Single or a packed Multi. Specifying both will result in an error. @@ -877,7 +884,8 @@ message SendRequest { repeated FeatureBit dest_features = 15; /* - The payment address of the generated invoice. + The payment address of the generated invoice. This is also called + payment secret in specifications (e.g. BOLT 11). */ bytes payment_addr = 16; } @@ -1083,6 +1091,18 @@ message LightningAddress { string host = 2; } +enum CoinSelectionStrategy { + // Use the coin selection strategy defined in the global configuration + // (lnd.conf). + STRATEGY_USE_GLOBAL_CONFIG = 0; + + // Select the largest available coins first during coin selection. + STRATEGY_LARGEST = 1; + + // Randomly select the available coins during coin selection. + STRATEGY_RANDOM = 2; +} + message EstimateFeeRequest { // The map from addresses to amounts for the transaction. map AddrToAmount = 1; @@ -1097,6 +1117,9 @@ message EstimateFeeRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 4; + + // The strategy to use for selecting coins during fees estimation. + CoinSelectionStrategy coin_selection_strategy = 5; } message EstimateFeeResponse { @@ -1137,6 +1160,9 @@ message SendManyRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 8; + + // The strategy to use for selecting coins during sending many requests. + CoinSelectionStrategy coin_selection_strategy = 9; } message SendManyResponse { // The id of the transaction @@ -1164,9 +1190,8 @@ message SendCoinsRequest { int64 sat_per_byte = 5 [deprecated = true]; /* - If set, then the amount field will be ignored, and lnd will attempt to - send all the coins under control of the internal wallet to the specified - address. + If set, the amount field should be unset. It indicates lnd will send all + wallet coins or all selected coins to the specified address. */ bool send_all = 6; @@ -1179,6 +1204,12 @@ message SendCoinsRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 9; + + // The strategy to use for selecting coins. + CoinSelectionStrategy coin_selection_strategy = 10; + + // A list of selected outpoints as inputs for the transaction. + repeated OutPoint outpoints = 11; } message SendCoinsResponse { // The transaction ID of the transaction @@ -1357,8 +1388,14 @@ enum CommitmentType { A channel that uses musig2 for the funding output, and the new tapscript features where relevant. */ - // TODO(roasbeef): need script enforce mirror type for the above as well? SIMPLE_TAPROOT = 5; + + /* + Identical to the SIMPLE_TAPROOT channel type, but with extra functionality. + This channel type also commits to additional meta data in the tapscript + leaves for the scripts in a channel. + */ + SIMPLE_TAPROOT_OVERLAY = 6; } message ChannelConstraints { @@ -1561,6 +1598,11 @@ message Channel { the channel's operation. */ string memo = 36; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 37; } message ListChannelsRequest { @@ -1926,12 +1968,16 @@ message GetInfoResponse { /* Whether the current node is connected to testnet. This field is deprecated and the network field should be used instead - **/ + */ bool testnet = 10 [deprecated = true]; reserved 11; - // A list of active chains the node is connected to + /* + A list of active chains the node is connected to. This will only + ever contain a single entry since LND will only ever have a single + chain backend during its lifetime. + */ repeated Chain chains = 16; // The URIs of the current node. @@ -1952,6 +1998,14 @@ message GetInfoResponse { bool store_final_htlc_resolutions = 22; } +message GetDebugInfoRequest { +} + +message GetDebugInfoResponse { + map config = 1; + repeated string log = 2; +} + message GetRecoveryInfoRequest { } message GetRecoveryInfoResponse { @@ -1966,8 +2020,9 @@ message GetRecoveryInfoResponse { } message Chain { - // The blockchain the node is on (eg bitcoin, litecoin) - string chain = 1; + // Deprecated. The chain is now always assumed to be bitcoin. + // The blockchain the node is on (must be bitcoin) + string chain = 1 [deprecated = true]; // The network the node is on (eg regtest, testnet, mainnet) string network = 2; @@ -1984,10 +2039,38 @@ message ChannelOpenUpdate { ChannelPoint channel_point = 1; } +message CloseOutput { + // The amount in satoshi of this close output. This amount is the final + // commitment balance of the channel and the actual amount paid out on chain + // might be smaller due to subtracted fees. + int64 amount_sat = 1; + + // The pkScript of the close output. + bytes pk_script = 2; + + // Whether this output is for the local or remote node. + bool is_local = 3; + + // The TLV encoded custom channel data records for this output, which might + // be set for custom channels. + bytes custom_channel_data = 4; +} + message ChannelCloseUpdate { bytes closing_txid = 1; bool success = 2; + + // The local channel close output. If the local channel balance was dust to + // begin with, this output will not be set. + CloseOutput local_close_output = 3; + + // The remote channel close output. If the remote channel balance was dust + // to begin with, this output will not be set. + CloseOutput remote_close_output = 4; + + // Any additional outputs that might be added for custom channel types. + repeated CloseOutput additional_outputs = 5; } message CloseChannelRequest { @@ -2027,12 +2110,18 @@ message CloseChannelRequest { // // NOTE: This field is only respected if we're the initiator of the channel. uint64 max_fee_per_vbyte = 7; + + // If true, then the rpc call will not block while it awaits a closing txid. + // Consequently this RPC call will not return a closing txid if this value + // is set. + bool no_wait = 8; } message CloseStatusUpdate { oneof update { PendingUpdate close_pending = 1; ChannelCloseUpdate chan_close = 3; + InstantUpdate close_instant = 4; } } @@ -2041,6 +2130,9 @@ message PendingUpdate { uint32 output_index = 2; } +message InstantUpdate { +} + message ReadyForPsbtFunding { /* The P2WSH address of the channel funding multisig address that the below @@ -2085,6 +2177,9 @@ message BatchOpenChannelRequest { // An optional label for the batch transaction, limited to 500 characters. string label = 6; + + // The strategy to use for selecting coins during batch opening channels. + CoinSelectionStrategy coin_selection_strategy = 7; } message BatchOpenChannel { @@ -2608,6 +2703,9 @@ message PendingHTLC { } message PendingChannelsRequest { + // Indicates whether to include the raw transaction hex for + // waiting_close_channels. + bool include_raw_tx = 1; } message PendingChannelsResponse { message PendingChannel { @@ -2650,6 +2748,11 @@ message PendingChannelsResponse { impacts the channel's operation. */ string memo = 13; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 34; } message PendingOpenChannel { @@ -2705,6 +2808,10 @@ message PendingChannelsResponse { // The transaction id of the closing transaction string closing_txid = 4; + + // The raw hex encoded bytes of the closing transaction. Included if + // include_raw_tx in the request is true. + string closing_tx_hex = 5; } message Commitments { @@ -2843,6 +2950,11 @@ message WalletBalanceRequest { // The wallet account the balance is shown for. // If this is not specified, the balance of the "default" account is shown. string account = 1; + + // The minimum number of confirmations each one of your outputs used for the + // funding transaction must satisfy. If this is not specified, the default + // value of 1 is used. + int32 min_confs = 2; } message WalletBalanceResponse { @@ -2900,6 +3012,12 @@ message ChannelBalanceResponse { // Sum of channels pending remote balances. Amount pending_open_remote_balance = 8; + + /* + Custom channel data that might be populated if there are custom channels + present. + */ + bytes custom_channel_data = 9; } message QueryRoutesRequest { @@ -2928,6 +3046,9 @@ message QueryRoutesRequest { not add any additional block padding on top of final_ctlv_delta. This padding of a few blocks needs to be added manually or otherwise failures may happen when a block comes in while the payment is in flight. + + Note: must not be set if making a payment to a blinded path (delta is + set by the aggregate parameters provided by blinded_payment_paths) */ int32 final_cltv_delta = 4; @@ -3001,12 +3122,21 @@ message QueryRoutesRequest { */ repeated lnrpc.RouteHint route_hints = 16; + /* + An optional blinded path(s) to reach the destination. Note that the + introduction node must be provided as the first hop in the route. + */ + repeated BlindedPaymentPath blinded_payment_paths = 19; + /* Features assumed to be supported by the final node. All transitive feature dependencies must also be set properly. For a given feature bit pair, either optional or remote may be set, but not both. If this field is nil or empty, the router will try to load destination features from the graph as a fallback. + + Note: must not be set if making a payment to a blinded route (features + are provided in blinded_payment_paths). */ repeated lnrpc.FeatureBit dest_features = 17; @@ -3112,6 +3242,32 @@ message Hop { // The payment metadata to send along with the payment to the payee. bytes metadata = 13; + + /* + Blinding point is an optional blinding point included for introduction + nodes in blinded paths. This field is mandatory for hops that represents + the introduction point in a blinded path. + */ + bytes blinding_point = 14; + + /* + Encrypted data is a receiver-produced blob of data that provides hops + in a blinded route with forwarding data. As this data is encrypted by + the recipient, we will not be able to parse it - it is essentially an + arbitrary blob of data from our node's perspective. This field is + mandatory for all hops in a blinded path, including the introduction + node. + */ + bytes encrypted_data = 15; + + /* + The total amount that is sent to the recipient (possibly across multiple + HTLCs), as specified by the sender when making a payment to a blinded path. + This value is only set in the final hop payload of a blinded payment. This + value is analogous to the MPPRecord that is used for regular (non-blinded) + MPP payments. + */ + uint64 total_amt_msat = 16; } message MPPRecord { @@ -3119,7 +3275,8 @@ message MPPRecord { A unique, random identifier used to authenticate the sender as the intended payer of a multi-path payment. The payment_addr must be the same for all subpayments, and match the payment_addr provided in the receiver's invoice. - The same payment_addr must be used on all subpayments. + The same payment_addr must be used on all subpayments. This is also called + payment secret in specifications (e.g. BOLT 11). */ bytes payment_addr = 11; @@ -3186,6 +3343,20 @@ message Route { The total amount in millisatoshis. */ int64 total_amt_msat = 6; + + /* + The actual on-chain amount that was sent out to the first hop. This value is + only different from the total_amt_msat field if this is a custom channel + payment and the value transported in the HTLC is different from the BTC + amount in the HTLC. If this value is zero, then this is an old payment that + didn't have this value yet and can be ignored. + */ + int64 first_hop_amount_msat = 7; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 8; } message NodeInfoRequest { @@ -3249,6 +3420,9 @@ message RoutingPolicy { // Custom channel update tlv records. map custom_records = 8; + + int32 inbound_fee_base_msat = 9; + int32 inbound_fee_rate_milli_msat = 10; } /* @@ -3335,6 +3509,10 @@ message ChanInfoRequest { output index for the channel. */ uint64 chan_id = 1 [jstype = JS_STRING]; + + // The channel point of the channel in format funding_txid:output_index. If + // chan_id is specified, this field is ignored. + string chan_point = 2; } message NetworkInfoRequest { @@ -3457,6 +3635,64 @@ message RouteHint { repeated HopHint hop_hints = 1; } +message BlindedPaymentPath { + // The blinded path to send the payment to. + BlindedPath blinded_path = 1; + + // The base fee for the blinded path provided, expressed in msat. + uint64 base_fee_msat = 2; + + /* + The proportional fee for the blinded path provided, expressed in parts + per million. + */ + uint32 proportional_fee_rate = 3; + + /* + The total CLTV delta for the blinded path provided, including the + final CLTV delta for the receiving node. + */ + uint32 total_cltv_delta = 4; + + /* + The minimum hltc size that may be sent over the blinded path, expressed + in msat. + */ + uint64 htlc_min_msat = 5; + + /* + The maximum htlc size that may be sent over the blinded path, expressed + in msat. + */ + uint64 htlc_max_msat = 6; + + // The feature bits for the route. + repeated FeatureBit features = 7; +} + +message BlindedPath { + // The unblinded pubkey of the introduction node for the route. + bytes introduction_node = 1; + + // The ephemeral pubkey used by nodes in the blinded route. + bytes blinding_point = 2; + + /* + A set of blinded node keys and data blobs for the blinded portion of the + route. Note that the first hop is expected to be the introduction node, + so the route is always expected to have at least one hop. + */ + repeated BlindedHop blinded_hops = 3; +} + +message BlindedHop { + // The blinded public key of the node. + bytes blinded_node = 1; + + // An encrypted blob of data provided to the blinded node. + bytes encrypted_data = 2; +} + message AMPInvoiceState { // The state the HTLCs associated with this setID are in. InvoiceHTLCState state = 1; @@ -3643,9 +3879,10 @@ message Invoice { bool is_keysend = 25; /* - The payment address of this invoice. This value will be used in MPP - payments, and also for newer invoices that always require the MPP payload - for added end-to-end security. + The payment address of this invoice. This is also called payment secret in + specifications (e.g. BOLT 11). This value will be used in MPP payments, and + also for newer invoices that always require the MPP payload for added + end-to-end security. Note: Output only, don't specify for creating an invoice. */ bytes payment_addr = 26; @@ -3666,10 +3903,52 @@ message Invoice { */ map amp_invoice_state = 28; + /* + Signals that the invoice should include blinded paths to hide the true + identity of the recipient. + */ + bool is_blinded = 29; + + /* + Config values to use when creating blinded paths for this invoice. These + can be used to override the defaults config values provided in by the + global config. This field is only used if is_blinded is true. + */ + BlindedPathConfig blinded_path_config = 30; + /* The minimum number of hop hints to include in this invoice. */ - int32 min_hop_hints = 29; + int32 min_hop_hints = 31; +} + +message BlindedPathConfig { + /* + The minimum number of real hops to include in a blinded path. This doesn't + include our node, so if the minimum is 1, then the path will contain at + minimum our node along with an introduction node hop. If it is zero then + the shortest path will use our node as an introduction node. + */ + optional uint32 min_num_real_hops = 1; + + /* + The number of hops to include in a blinded path. This doesn't include our + node, so if it is 1, then the path will contain our node along with an + introduction node or dummy node hop. If paths shorter than NumHops is + found, then they will be padded using dummy hops. + */ + optional uint32 num_hops = 2; + + /* + The maximum number of blinded paths to select and add to an invoice. + */ + optional uint32 max_num_paths = 3; + + /* + A list of node IDs of nodes that should not be used in any of our generated + blinded paths. + */ + repeated bytes node_omission_list = 4; } enum InvoiceHTLCState { @@ -3712,6 +3991,11 @@ message InvoiceHTLC { // Details relevant to AMP HTLCs, only populated if this is an AMP HTLC. AMP amp = 11; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 12; } // Details specific to AMP HTLCs. @@ -3755,9 +4039,9 @@ message AddInvoiceResponse { uint64 add_index = 16; /* - The payment address of the generated invoice. This value should be used - in all payments for this invoice as we require it for end to end - security. + The payment address of the generated invoice. This is also called + payment secret in specifications (e.g. BOLT 11). This value should be used + in all payments for this invoice as we require it for end to end security. */ bytes payment_addr = 17; } @@ -3878,6 +4162,11 @@ enum PaymentFailureReason { Insufficient local balance. */ FAILURE_REASON_INSUFFICIENT_BALANCE = 5; + + /* + The payment was canceled. + */ + FAILURE_REASON_CANCELED = 6; } message Payment { @@ -3908,10 +4197,20 @@ message Payment { string payment_request = 9; enum PaymentStatus { - UNKNOWN = 0; + // Deprecated. This status will never be returned. + UNKNOWN = 0 [deprecated = true]; + + // Payment has inflight HTLCs. IN_FLIGHT = 1; + + // Payment is settled. SUCCEEDED = 2; + + // Payment is failed. FAILED = 3; + + // Payment is created and has not attempted any HTLCs. + INITIATED = 4; } // The status of the payment. @@ -3937,6 +4236,12 @@ message Payment { uint64 payment_index = 15; PaymentFailureReason failure_reason = 16; + + /* + The custom TLV records that were sent to the first hop as part of the HTLC + wire message for this payment. + */ + map first_hop_custom_records = 17; } message HTLCAttempt { @@ -4007,11 +4312,11 @@ message ListPaymentsRequest { */ bool count_total_payments = 5; - // If set, returns all invoices with a creation date greater than or equal + // If set, returns all payments with a creation date greater than or equal // to it. Measured in seconds since the unix epoch. uint64 creation_date_start = 6; - // If set, returns all invoices with a creation date less than or equal to + // If set, returns all payments with a creation date less than or equal to // it. Measured in seconds since the unix epoch. uint64 creation_date_end = 7; } @@ -4059,6 +4364,10 @@ message DeleteAllPaymentsRequest { Only delete failed HTLCs from payments, not the payment itself. */ bool failed_htlcs_only = 2; + + // Delete all payments. NOTE: Using this option requires careful + // consideration as it is a destructive operation. + bool all_payments = 3; } message DeletePaymentResponse { @@ -4109,6 +4418,7 @@ message PayReq { bytes payment_addr = 11; int64 num_msat = 12; map features = 13; + repeated BlindedPaymentPath blinded_paths = 14; } enum FeatureBit { @@ -4135,6 +4445,8 @@ enum FeatureBit { ANCHORS_OPT = 21; ANCHORS_ZERO_FEE_HTLC_REQ = 22; ANCHORS_ZERO_FEE_HTLC_OPT = 23; + ROUTE_BLINDING_REQUIRED = 24; + ROUTE_BLINDING_OPTIONAL = 25; AMP_REQ = 30; AMP_OPT = 31; } @@ -4164,7 +4476,15 @@ message ChannelFeeReport { // The effective fee rate in milli-satoshis. Computed by dividing the // fee_per_mil value by 1 million. double fee_rate = 4; + + // The base fee charged regardless of the number of milli-satoshis sent. + int32 inbound_base_fee_msat = 6; + + // The amount charged per milli-satoshis transferred expressed in + // millionths of a satoshi. + int32 inbound_fee_per_mil = 7; } + message FeeReportResponse { // An array of channel fee reports which describes the current fee schedule // for each channel. @@ -4183,6 +4503,16 @@ message FeeReportResponse { uint64 month_fee_sum = 4; } +message InboundFee { + // The inbound base fee charged regardless of the number of milli-satoshis + // received in the channel. By default, only negative values are accepted. + int32 base_fee_msat = 1; + + // The effective inbound fee rate in micro-satoshis (parts per million). + // By default, only negative values are accepted. + int32 fee_rate_ppm = 2; +} + message PolicyUpdateRequest { oneof scope { // If set, then this update applies to all currently active channels. @@ -4215,7 +4545,12 @@ message PolicyUpdateRequest { // If true, min_htlc_msat is applied. bool min_htlc_msat_specified = 8; + + // Optional inbound fee. If unset, the previously set value will be + // retained [EXPERIMENTAL]. + InboundFee inbound_fee = 10; } + enum UpdateFailure { UPDATE_FAILURE_UNKNOWN = 0; UPDATE_FAILURE_PENDING = 1; @@ -4491,6 +4826,7 @@ message Failure { EXPIRY_TOO_FAR = 22; MPP_TIMEOUT = 23; INVALID_ONION_PAYLOAD = 24; + INVALID_ONION_BLINDING = 25; /* An internal error occurred.