From d3e23cc4d973081f3905f39a1a4f99946ebe8b02 Mon Sep 17 00:00:00 2001 From: pycanis Date: Wed, 11 Sep 2024 22:14:13 +0200 Subject: [PATCH] Update protos + add router.proto --- build.rs | 1 + src/lib.rs | 16 +- vendor/lightning.proto | 606 +++++++++++++++- vendor/peersrpc/peers.proto | 4 +- vendor/routerrpc/router.proto | 1114 ++++++++++++++++++++++++++++++ vendor/signrpc/signer.proto | 91 ++- vendor/walletrpc/walletkit.proto | 781 +++++++++++++++++++-- 7 files changed, 2492 insertions(+), 121 deletions(-) create mode 100644 vendor/routerrpc/router.proto diff --git a/build.rs b/build.rs index cfed7b3..c64cf5d 100644 --- a/build.rs +++ b/build.rs @@ -20,6 +20,7 @@ fn main() -> std::io::Result<()> { "lightning.proto", "peersrpc/peers.proto", "verrpc/verrpc.proto", + "routerrpc/router.proto" ]; let proto_paths: Vec<_> = protos diff --git a/src/lib.rs b/src/lib.rs index ce03484..cd74307 100755 --- a/src/lib.rs +++ b/src/lib.rs @@ -98,6 +98,9 @@ pub type VersionerClient = // Convenience type alias for signer client. pub type SignerClient = signrpc::signer_client::SignerClient>; +// Convenience type alias for router client. +pub type RouterClient = routerrpc::router_client::RouterClient>; + /// The client returned by `connect` function /// /// This is a convenience type which you most likely want to use instead of raw client. @@ -108,6 +111,7 @@ pub struct Client { signer: SignerClient, peers: PeersClient, version: VersionerClient, + router: RouterClient, } impl Client { @@ -135,6 +139,11 @@ impl Client { pub fn peers(&mut self) -> &mut PeersClient { &mut self.peers } + + /// Returns the router client. + pub fn router(&mut self) -> &mut RouterClient { + &mut self.router + } } /// [`tonic::Status`] is re-exported as `Error` for convenience. @@ -175,6 +184,10 @@ pub mod peersrpc { tonic::include_proto!("peersrpc"); } +pub mod routerrpc { + tonic::include_proto!("routerrpc"); +} + /// Supplies requests with macaroon #[derive(Clone)] pub struct MacaroonInterceptor { @@ -231,7 +244,8 @@ pub async fn connect(address: A, cert_file: CP, macaroon_file: MP) -> interceptor.clone(), ), version: verrpc::versioner_client::VersionerClient::with_interceptor(conn.clone(), interceptor.clone()), - signer: signrpc::signer_client::SignerClient::with_interceptor(conn, interceptor), + signer: signrpc::signer_client::SignerClient::with_interceptor(conn.clone(), interceptor.clone()), + router: routerrpc::router_client::RouterClient::with_interceptor(conn, interceptor), }; Ok(client) } diff --git a/vendor/lightning.proto b/vendor/lightning.proto index b1716e3..6d975c8 100644 --- a/vendor/lightning.proto +++ b/vendor/lightning.proto @@ -101,8 +101,10 @@ service Lightning { rpc SignMessage (SignMessageRequest) returns (SignMessageResponse); /* lncli: `verifymessage` - VerifyMessage verifies a signature over a msg. The signature must be - zbase32 encoded and signed by an active node in the resident node's + VerifyMessage verifies a signature over a message and recovers the signer's + public key. The signature is only deemed valid if the recovered public key + corresponds to a node key in the public Lightning network. The signature + must be zbase32 encoded and signed by an active node in the resident node's channel database. In addition to returning the validity of the signature, VerifyMessage also returns the recovered pubkey from the signature. */ @@ -141,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 @@ -320,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. @@ -339,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. */ @@ -477,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. @@ -567,6 +576,10 @@ service Lightning { /* lncli: `subscribecustom` SubscribeCustomMessages subscribes to a stream of incoming custom peer messages. + + To include messages with type outside of the custom range (>= 32768) lnd + needs to be compiled with the `dev` build tag, and the message type to + override should be specified in lnd's experimental protocol configuration. */ rpc SubscribeCustomMessages (SubscribeCustomMessagesRequest) returns (stream CustomMessage); @@ -577,6 +590,28 @@ service Lightning { zero conf). */ rpc ListAliases (ListAliasesRequest) returns (ListAliasesResponse); + + /* + LookupHtlcResolution retrieves a final htlc resolution from the database. + If the htlc has no final resolution yet, a NotFound grpc status code is + returned. + */ + rpc LookupHtlcResolution (LookupHtlcResolutionRequest) + returns (LookupHtlcResolutionResponse); +} + +message LookupHtlcResolutionRequest { + uint64 chan_id = 1; + + uint64 htlc_index = 2; +} + +message LookupHtlcResolutionResponse { + // Settled is true is the htlc was settled. If false, the htlc was failed. + bool settled = 1; + + // Offchain indicates whether the htlc was resolved off-chain or on-chain. + bool offchain = 2; } message SubscribeCustomMessagesRequest { @@ -598,6 +633,9 @@ message SendCustomMessageRequest { bytes peer = 1; // Message type. This value needs to be in the custom range (>= 32768). + // To send a type < custom range, lnd needs to be compiled with the `dev` + // build tag, and the message type to override should be specified in lnd's + // experimental protocol configuration. uint32 type = 2; // Raw message data. @@ -637,6 +675,7 @@ enum OutputScriptType { SCRIPT_TYPE_NULLDATA = 6; SCRIPT_TYPE_NON_STANDARD = 7; SCRIPT_TYPE_WITNESS_UNKNOWN = 8; + SCRIPT_TYPE_WITNESS_V1_TAPROOT = 9; } message OutputDetail { @@ -845,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; } @@ -1051,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; @@ -1065,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 { @@ -1105,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 @@ -1132,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; @@ -1147,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 @@ -1320,6 +1383,13 @@ enum CommitmentType { channel before its maturity date. */ SCRIPT_ENFORCED_LEASE = 4; + + /* + 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; } message ChannelConstraints { @@ -1509,6 +1579,19 @@ message Channel { // This is the confirmed / on-chain zero-conf SCID. uint64 zero_conf_confirmed_scid = 33; + + // The configured alias name of our peer. + string peer_alias = 34; + + // This is the peer SCID alias. + uint64 peer_scid_alias = 35 [jstype = JS_STRING]; + + /* + An optional note-to-self to go along with the channel containing some + useful information. This is only ever stored locally and in no way impacts + the channel's operation. + */ + string memo = 36; } message ListChannelsRequest { @@ -1522,6 +1605,11 @@ message ListChannelsRequest { empty, all channels will be returned. */ bytes peer = 5; + + // Informs the server if the peer alias lookup per channel should be + // enabled. It is turned off by default in order to avoid degradation of + // performance for existing clients. + bool peer_alias_lookup = 6; } message ListChannelsResponse { // The list of active channels @@ -1869,12 +1957,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. @@ -1890,6 +1982,17 @@ message GetInfoResponse { Indicates whether the HTLC interceptor API is in always-on mode. */ bool require_htlc_interceptor = 21; + + // Indicates whether final htlc resolutions are stored on disk. + bool store_final_htlc_resolutions = 22; +} + +message GetDebugInfoRequest { +} + +message GetDebugInfoResponse { + map config = 1; + repeated string log = 2; } message GetRecoveryInfoRequest { @@ -1906,8 +2009,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; @@ -1967,12 +2071,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; } } @@ -1981,6 +2091,9 @@ message PendingUpdate { uint32 output_index = 2; } +message InstantUpdate { +} + message ReadyForPsbtFunding { /* The P2WSH address of the channel funding multisig address that the below @@ -2025,6 +2138,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 { @@ -2075,6 +2191,76 @@ message BatchOpenChannel { the remote peer supports explicit channel negotiation. */ CommitmentType commitment_type = 9; + + /* + The maximum amount of coins in millisatoshi that can be pending within + the channel. It only applies to the remote party. + */ + uint64 remote_max_value_in_flight_msat = 10; + + /* + The maximum number of concurrent HTLCs we will allow the remote party to add + to the commitment transaction. + */ + uint32 remote_max_htlcs = 11; + + /* + Max local csv is the maximum csv delay we will allow for our own commitment + transaction. + */ + uint32 max_local_csv = 12; + + /* + If this is true, then a zero-conf channel open will be attempted. + */ + bool zero_conf = 13; + + /* + If this is true, then an option-scid-alias channel-type open will be + attempted. + */ + bool scid_alias = 14; + + /* + The base fee charged regardless of the number of milli-satoshis sent. + */ + uint64 base_fee = 15; + + /* + The fee rate in ppm (parts per million) that will be charged in + proportion of the value of each forwarded HTLC. + */ + uint64 fee_rate = 16; + + /* + If use_base_fee is true the open channel announcement will update the + channel base fee with the value specified in base_fee. In the case of + a base_fee of 0 use_base_fee is needed downstream to distinguish whether + to use the default base fee value specified in the config or 0. + */ + bool use_base_fee = 17; + + /* + If use_fee_rate is true the open channel announcement will update the + channel fee rate with the value specified in fee_rate. In the case of + a fee_rate of 0 use_fee_rate is needed downstream to distinguish whether + to use the default fee rate value specified in the config or 0. + */ + bool use_fee_rate = 18; + + /* + The number of satoshis we require the remote peer to reserve. This value, + if specified, must be above the dust limit and below 20% of the channel + capacity. + */ + uint64 remote_chan_reserve_sat = 19; + + /* + An optional note-to-self to go along with the channel containing some + useful information. This is only ever stored locally and in no way impacts + the channel's operation. + */ + string memo = 20; } message BatchOpenChannelResponse { @@ -2189,6 +2375,59 @@ message OpenChannelRequest { attempted. */ bool scid_alias = 20; + + /* + The base fee charged regardless of the number of milli-satoshis sent. + */ + uint64 base_fee = 21; + + /* + The fee rate in ppm (parts per million) that will be charged in + proportion of the value of each forwarded HTLC. + */ + uint64 fee_rate = 22; + + /* + If use_base_fee is true the open channel announcement will update the + channel base fee with the value specified in base_fee. In the case of + a base_fee of 0 use_base_fee is needed downstream to distinguish whether + to use the default base fee value specified in the config or 0. + */ + bool use_base_fee = 23; + + /* + If use_fee_rate is true the open channel announcement will update the + channel fee rate with the value specified in fee_rate. In the case of + a fee_rate of 0 use_fee_rate is needed downstream to distinguish whether + to use the default fee rate value specified in the config or 0. + */ + bool use_fee_rate = 24; + + /* + The number of satoshis we require the remote peer to reserve. This value, + if specified, must be above the dust limit and below 20% of the channel + capacity. + */ + uint64 remote_chan_reserve_sat = 25; + + /* + If set, then lnd will attempt to commit all the coins under control of the + internal wallet to open the channel, and the LocalFundingAmount field must + be zero and is ignored. + */ + bool fund_max = 26; + + /* + An optional note-to-self to go along with the channel containing some + useful information. This is only ever stored locally and in no way impacts + the channel's operation. + */ + string memo = 27; + + /* + A list of selected outpoints that are allocated for channel funding. + */ + repeated OutPoint outpoints = 28; } message OpenStatusUpdate { oneof update { @@ -2270,6 +2509,11 @@ message ChanPointShim { the value is less than 500,000, or as an absolute height otherwise. */ uint32 thaw_height = 6; + + /* + Indicates that the funding output is using a MuSig2 multi-sig output. + */ + bool musig2 = 7; } message PsbtShim { @@ -2420,6 +2664,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 { @@ -2455,6 +2702,13 @@ message PendingChannelsResponse { // Whether this channel is advertised to the network or not. bool private = 12; + + /* + An optional note-to-self to go along with the channel containing some + useful information. This is only ever stored locally and in no way + impacts the channel's operation. + */ + string memo = 13; } message PendingOpenChannel { @@ -2482,6 +2736,17 @@ message PendingChannelsResponse { // Previously used for confirmation_height. Do not reuse. reserved 2; + + // The number of blocks until the funding transaction is considered + // expired. If this value gets close to zero, there is a risk that the + // channel funding will be canceled by the channel responder. The + // channel should be fee bumped using CPFP (see walletrpc.BumpFee) to + // ensure that the channel confirms in time. Otherwise a force-close + // will be necessary if the channel confirms after the funding + // transaction expires. A negative value means the channel responder has + // very likely canceled the funding and the channel will never become + // fully operational. + int32 funding_expiry_blocks = 3; } message WaitingCloseChannel { @@ -2499,6 +2764,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 { @@ -2563,9 +2832,17 @@ message PendingChannelsResponse { repeated PendingHTLC pending_htlcs = 8; + /* + There are three resolution states for the anchor: + limbo, lost and recovered. Derive the current state + from the limbo and recovered balances. + */ enum AnchorState { + // The recovered_balance is zero and limbo_balance is non-zero. LIMBO = 0; + // The recovered_balance is non-zero. RECOVERED = 1; + // A state that is neither LIMBO nor RECOVERED. LOST = 2; } @@ -2626,6 +2903,14 @@ message WalletAccountBalance { } 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 { @@ -2711,6 +2996,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; @@ -2784,12 +3072,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; @@ -2895,6 +3192,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 { @@ -2902,7 +3225,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; @@ -2969,6 +3293,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 { @@ -3011,6 +3349,9 @@ message LightningNode { repeated NodeAddress addresses = 4; string color = 5; map features = 6; + + // Custom node announcement tlv records. + map custom_records = 7; } message NodeAddress { @@ -3026,6 +3367,12 @@ message RoutingPolicy { bool disabled = 5; uint64 max_htlc_msat = 6; uint32 last_update = 7; + + // Custom channel update tlv records. + map custom_records = 8; + + int32 inbound_fee_base_msat = 9; + int32 inbound_fee_rate_milli_msat = 10; } /* @@ -3053,6 +3400,9 @@ message ChannelEdge { RoutingPolicy node1_policy = 7; RoutingPolicy node2_policy = 8; + + // Custom channel announcement tlv records. + map custom_records = 9; } message ChannelGraphRequest { @@ -3109,6 +3459,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 { @@ -3231,6 +3585,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; @@ -3285,7 +3697,7 @@ message Invoice { int64 value_msat = 23; /* - Whether this invoice has been fulfilled + Whether this invoice has been fulfilled. The field is deprecated. Use the state field instead (compare to SETTLED). */ @@ -3293,12 +3705,14 @@ message Invoice { /* When this invoice was created. + Measured in seconds since the unix epoch. Note: Output only, don't specify for creating an invoice. */ int64 creation_date = 7; /* When this invoice was settled. + Measured in seconds since the unix epoch. Note: Output only, don't specify for creating an invoice. */ int64 settle_date = 8; @@ -3319,7 +3733,7 @@ message Invoice { */ bytes description_hash = 10; - // Payment request expiry time in seconds. Default is 3600 (1 hour). + // Payment request expiry time in seconds. Default is 86400 (24 hours). int64 expiry = 11; // Fallback on-chain address. @@ -3335,6 +3749,8 @@ message Invoice { repeated RouteHint route_hints = 14; // Whether this invoice should include routing hints for private channels. + // Note: When enabled, if value and value_msat are zero, a large number of + // hints with these channels can be included, which might not be desirable. bool private = 15; /* @@ -3360,22 +3776,22 @@ message Invoice { /* The amount that was accepted for this invoice, in satoshis. This will ONLY - be set if this invoice has been settled. We provide this field as if the - invoice was created with a zero value, then we need to record what amount - was ultimately accepted. Additionally, it's possible that the sender paid - MORE that was specified in the original invoice. So we'll record that here - as well. + be set if this invoice has been settled or accepted. We provide this field + as if the invoice was created with a zero value, then we need to record what + amount was ultimately accepted. Additionally, it's possible that the sender + paid MORE that was specified in the original invoice. So we'll record that + here as well. Note: Output only, don't specify for creating an invoice. */ int64 amt_paid_sat = 19; /* The amount that was accepted for this invoice, in millisatoshis. This will - ONLY be set if this invoice has been settled. We provide this field as if - the invoice was created with a zero value, then we need to record what - amount was ultimately accepted. Additionally, it's possible that the sender - paid MORE that was specified in the original invoice. So we'll record that - here as well. + ONLY be set if this invoice has been settled or accepted. We provide this + field as if the invoice was created with a zero value, then we need to + record what amount was ultimately accepted. Additionally, it's possible that + the sender paid MORE that was specified in the original invoice. So we'll + record that here as well. Note: Output only, don't specify for creating an invoice. */ int64 amt_paid_msat = 20; @@ -3413,9 +3829,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; @@ -3435,6 +3852,48 @@ message Invoice { Note: Output only, don't specify for creating an 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; +} + +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 { @@ -3520,9 +3979,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; } @@ -3563,7 +4022,16 @@ message ListInvoiceRequest { specified index offset. This can be used to paginate backwards. */ bool reversed = 6; + + // If set, returns all invoices with a creation date greater than or equal + // to it. Measured in seconds since the unix epoch. + uint64 creation_date_start = 7; + + // If set, returns all invoices with a creation date less than or equal to + // it. Measured in seconds since the unix epoch. + uint64 creation_date_end = 8; } + message ListInvoiceResponse { /* A list of invoices from the time slice of the time series specified in the @@ -3634,6 +4102,11 @@ enum PaymentFailureReason { Insufficient local balance. */ FAILURE_REASON_INSUFFICIENT_BALANCE = 5; + + /* + The payment was canceled. + */ + FAILURE_REASON_CANCELED = 6; } message Payment { @@ -3664,10 +4137,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. @@ -3693,6 +4176,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 { @@ -3762,6 +4251,14 @@ message ListPaymentsRequest { of payments, as all of them have to be iterated through to be counted. */ bool count_total_payments = 5; + + // 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 payments with a creation date less than or equal to + // it. Measured in seconds since the unix epoch. + uint64 creation_date_end = 7; } message ListPaymentsResponse { @@ -3807,6 +4304,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 { @@ -3857,6 +4358,7 @@ message PayReq { bytes payment_addr = 11; int64 num_msat = 12; map features = 13; + repeated BlindedPaymentPath blinded_paths = 14; } enum FeatureBit { @@ -3883,6 +4385,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; } @@ -3912,7 +4416,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. @@ -3931,6 +4443,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. @@ -3963,7 +4485,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; @@ -4006,6 +4533,10 @@ message ForwardingHistoryRequest { // The max number of events to return in the response to this query. uint32 num_max_events = 4; + + // Informs the server if the peer alias should be looked up for each + // forwarding event. + bool peer_alias_lookup = 5; } message ForwardingEvent { // Timestamp is the time (unix epoch offset) that this circuit was @@ -4045,6 +4576,12 @@ message ForwardingEvent { // circuit was completed. uint64 timestamp_ns = 11; + // The peer alias of the incoming channel. + string peer_alias_in = 12; + + // The peer alias of the outgoing channel. + string peer_alias_out = 13; + // TODO(roasbeef): add settlement latency? // * use FPE on the chan id? // * also list failures? @@ -4229,6 +4766,7 @@ message Failure { EXPIRY_TOO_FAR = 22; MPP_TIMEOUT = 23; INVALID_ONION_PAYLOAD = 24; + INVALID_ONION_BLINDING = 25; /* An internal error occurred. diff --git a/vendor/peersrpc/peers.proto b/vendor/peersrpc/peers.proto index 4cfdab5..9e6ac84 100644 --- a/vendor/peersrpc/peers.proto +++ b/vendor/peersrpc/peers.proto @@ -1,9 +1,9 @@ syntax = "proto3"; -import "lightning.proto"; - package peersrpc; +import "lightning.proto"; + option go_package = "github.com/lightningnetwork/lnd/lnrpc/peersrpc"; // Peers is a service that can be used to get information and interact diff --git a/vendor/routerrpc/router.proto b/vendor/routerrpc/router.proto new file mode 100644 index 0000000..92da751 --- /dev/null +++ b/vendor/routerrpc/router.proto @@ -0,0 +1,1114 @@ +syntax = "proto3"; + +package routerrpc; + +import "lightning.proto"; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc"; + +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + +// Router is a service that offers advanced interaction with the router +// subsystem of the daemon. +service Router { + /* + SendPaymentV2 attempts to route a payment described by the passed + PaymentRequest to the final destination. The call returns a stream of + payment updates. When using this RPC, make sure to set a fee limit, as the + default routing fee limit is 0 sats. Without a non-zero fee limit only + routes without fees will be attempted which often fails with + FAILURE_REASON_NO_ROUTE. + */ + rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment); + + /* lncli: `trackpayment` + TrackPaymentV2 returns an update stream for the payment identified by the + payment hash. + */ + rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment); + + /* + TrackPayments returns an update stream for every payment that is not in a + terminal state. Note that if payments are in-flight while starting a new + subscription, the start of the payment stream could produce out-of-order + and/or duplicate events. In order to get updates for every in-flight + payment attempt make sure to subscribe to this method before initiating any + payments. + */ + rpc TrackPayments (TrackPaymentsRequest) returns (stream lnrpc.Payment); + + /* + EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it + may cost to send an HTLC to the target end destination. + */ + rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse); + + /* + Deprecated, use SendToRouteV2. SendToRoute attempts to make a payment via + the specified route. This method differs from SendPayment in that it + allows users to specify a full route manually. This can be used for + things like rebalancing, and atomic swaps. It differs from the newer + SendToRouteV2 in that it doesn't return the full HTLC information. + */ + rpc SendToRoute (SendToRouteRequest) returns (SendToRouteResponse) { + option deprecated = true; + } + + /* + SendToRouteV2 attempts to make a payment via the specified route. This + method differs from SendPayment in that it allows users to specify a full + route manually. This can be used for things like rebalancing, and atomic + swaps. + */ + rpc SendToRouteV2 (SendToRouteRequest) returns (lnrpc.HTLCAttempt); + + /* lncli: `resetmc` + ResetMissionControl clears all mission control state and starts with a clean + slate. + */ + rpc ResetMissionControl (ResetMissionControlRequest) + returns (ResetMissionControlResponse); + + /* lncli: `querymc` + QueryMissionControl exposes the internal mission control state to callers. + It is a development feature. + */ + rpc QueryMissionControl (QueryMissionControlRequest) + returns (QueryMissionControlResponse); + + /* lncli: `importmc` + XImportMissionControl is an experimental API that imports the state provided + to the internal mission control's state, using all results which are more + recent than our existing values. These values will only be imported + in-memory, and will not be persisted across restarts. + */ + rpc XImportMissionControl (XImportMissionControlRequest) + returns (XImportMissionControlResponse); + + /* lncli: `getmccfg` + GetMissionControlConfig returns mission control's current config. + */ + rpc GetMissionControlConfig (GetMissionControlConfigRequest) + returns (GetMissionControlConfigResponse); + + /* lncli: `setmccfg` + SetMissionControlConfig will set mission control's config, if the config + provided is valid. + */ + rpc SetMissionControlConfig (SetMissionControlConfigRequest) + returns (SetMissionControlConfigResponse); + + /* lncli: `queryprob` + Deprecated. QueryProbability returns the current success probability + estimate for a given node pair and amount. The call returns a zero success + probability if no channel is available or if the amount violates min/max + HTLC constraints. + */ + rpc QueryProbability (QueryProbabilityRequest) + returns (QueryProbabilityResponse); + + /* lncli: `buildroute` + BuildRoute builds a fully specified route based on a list of hop public + keys. It retrieves the relevant channel policies from the graph in order to + calculate the correct fees and time locks. + Note that LND will use its default final_cltv_delta if no value is supplied. + Make sure to add the correct final_cltv_delta depending on the invoice + restriction. Moreover the caller has to make sure to provide the + payment_addr if the route is paying an invoice which signaled it. + */ + rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse); + + /* + SubscribeHtlcEvents creates a uni-directional stream from the server to + the client which delivers a stream of htlc events. + */ + rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest) + returns (stream HtlcEvent); + + /* + Deprecated, use SendPaymentV2. SendPayment attempts to route a payment + described by the passed PaymentRequest to the final destination. The call + returns a stream of payment status updates. + */ + rpc SendPayment (SendPaymentRequest) returns (stream PaymentStatus) { + option deprecated = true; + } + + /* + Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for + the payment identified by the payment hash. + */ + rpc TrackPayment (TrackPaymentRequest) returns (stream PaymentStatus) { + option deprecated = true; + } + + /** + HtlcInterceptor dispatches a bi-directional streaming RPC in which + Forwarded HTLC requests are sent to the client and the client responds with + a boolean that tells LND if this htlc should be intercepted. + In case of interception, the htlc can be either settled, cancelled or + resumed later by using the ResolveHoldForward endpoint. + */ + rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse) + returns (stream ForwardHtlcInterceptRequest); + + /* lncli: `updatechanstatus` + UpdateChanStatus attempts to manually set the state of a channel + (enabled, disabled, or auto). A manual "disable" request will cause the + channel to stay disabled until a subsequent manual request of either + "enable" or "auto". + */ + rpc UpdateChanStatus (UpdateChanStatusRequest) + returns (UpdateChanStatusResponse); + + /* + XAddLocalChanAliases is an experimental API that creates a set of new + channel SCID alias mappings. The final total set of aliases in the manager + after the add operation is returned. This is only a locally stored alias, + and will not be communicated to the channel peer via any message. Therefore, + routing over such an alias will only work if the peer also calls this same + RPC on their end. If an alias already exists, an error is returned + */ + rpc XAddLocalChanAliases (AddAliasesRequest) returns (AddAliasesResponse); + + /* + XDeleteLocalChanAliases is an experimental API that deletes a set of alias + mappings. The final total set of aliases in the manager after the delete + operation is returned. The deletion will not be communicated to the channel + peer via any message. + */ + rpc XDeleteLocalChanAliases (DeleteAliasesRequest) + returns (DeleteAliasesResponse); +} + +message SendPaymentRequest { + // The identity pubkey of the payment recipient + bytes dest = 1; + + /* + Number of satoshis to send. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt = 2; + + // The hash to use within the payment's HTLC + bytes payment_hash = 3; + + /* + The CLTV delta from the current height that should be used to set the + timelock for the final hop. + */ + int32 final_cltv_delta = 4; + + /* + A bare-bones invoice for a payment within the Lightning Network. With the + details of the invoice, the sender has all the data necessary to send a + payment to the recipient. The amount in the payment request may be zero. In + that case it is required to set the amt field as well. If no payment request + is specified, the following fields are required: dest, amt and payment_hash. + */ + string payment_request = 5; + + /* + An upper limit on the amount of time we should spend when attempting to + fulfill the payment. This is expressed in seconds. If we cannot make a + successful payment within this time frame, an error will be returned. + This field must be non-zero. + */ + int32 timeout_seconds = 6; + + /* + The maximum number of satoshis that will be paid as a fee of the payment. + If this field is left to the default value of 0, only zero-fee routes will + be considered. This usually means single hop routes connecting directly to + the destination. To send the payment without a fee limit, use max int here. + + The fields fee_limit_sat and fee_limit_msat are mutually exclusive. + */ + int64 fee_limit_sat = 7; + + /* + Deprecated, use outgoing_chan_ids. The channel id of the channel that must + be taken to the first hop. If zero, any channel may be used (unless + outgoing_chan_ids are set). + */ + uint64 outgoing_chan_id = 8 [jstype = JS_STRING, deprecated = true]; + + /* + An optional maximum total time lock for the route. This should not + exceed lnd's `--max-cltv-expiry` setting. If zero, then the value of + `--max-cltv-expiry` is enforced. + */ + int32 cltv_limit = 9; + + /* + Optional route hints to reach the destination through private channels. + */ + repeated lnrpc.RouteHint route_hints = 10; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to a peer which understands the new records. This can be used to pass + application specific data during the payment attempt. Record types are + required to be in the custom range >= 65536. When using REST, the values + must be encoded as base64. + */ + map dest_custom_records = 11; + + /* + Number of millisatoshis to send. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt_msat = 12; + + /* + The maximum number of millisatoshis that will be paid as a fee of the + payment. If this field is left to the default value of 0, only zero-fee + routes will be considered. This usually means single hop routes connecting + directly to the destination. To send the payment without a fee limit, use + max int here. + + The fields fee_limit_sat and fee_limit_msat are mutually exclusive. + */ + int64 fee_limit_msat = 13; + + /* + The pubkey of the last hop of the route. If empty, any hop may be used. + */ + bytes last_hop_pubkey = 14; + + // If set, circular payments to self are permitted. + bool allow_self_payment = 15; + + /* + 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. + */ + repeated lnrpc.FeatureBit dest_features = 16; + + /* + The maximum number of partial payments that may be use to complete the full + amount. + */ + uint32 max_parts = 17; + + /* + If set, only the final payment update is streamed back. Intermediate updates + that show which htlcs are still in flight are suppressed. + */ + bool no_inflight_updates = 18; + + /* + The channel ids of the channels are allowed for the first hop. If empty, + any channel may be used. + */ + repeated uint64 outgoing_chan_ids = 19; + + /* + An optional payment addr to be included within the last hop of the route. + This is also called payment secret in specifications (e.g. BOLT 11). + */ + bytes payment_addr = 20; + + /* + The largest payment split that should be attempted when making a payment if + splitting is necessary. Setting this value will effectively cause lnd to + split more aggressively, vs only when it thinks it needs to. Note that this + value is in milli-satoshis. + */ + uint64 max_shard_size_msat = 21; + + /* + If set, an AMP-payment will be attempted. + */ + bool amp = 22; + + /* + The time preference for this payment. Set to -1 to optimize for fees + only, to 1 to optimize for reliability only or a value inbetween for a mix. + */ + double time_pref = 23; + + /* + If set, the payment loop can be interrupted by manually canceling the + payment context, even before the payment timeout is reached. Note that the + payment may still succeed after cancellation, as in-flight attempts can + still settle afterwards. Canceling will only prevent further attempts from + being sent. + */ + bool cancelable = 24; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to the first hop peer of this payment. This can be used to pass application + specific data during the payment attempt. Record types are required to be in + the custom range >= 65536. When using REST, the values must be encoded as + base64. + */ + map first_hop_custom_records = 25; +} + +message TrackPaymentRequest { + // The hash of the payment to look up. + bytes payment_hash = 1; + + /* + If set, only the final payment update is streamed back. Intermediate updates + that show which htlcs are still in flight are suppressed. + */ + bool no_inflight_updates = 2; +} + +message TrackPaymentsRequest { + /* + If set, only the final payment updates are streamed back. Intermediate + updates that show which htlcs are still in flight are suppressed. + */ + bool no_inflight_updates = 1; +} + +message RouteFeeRequest { + /* + The destination one wishes to obtain a routing fee quote to. If set, this + parameter requires the amt_sat parameter also to be set. This parameter + combination triggers a graph based routing fee estimation as opposed to a + payment probe based estimate in case a payment request is provided. The + graph based estimation is an algorithm that is executed on the in memory + graph. Hence its runtime is significantly shorter than a payment probe + estimation that sends out actual payments to the network. + */ + bytes dest = 1; + + /* + The amount one wishes to send to the target destination. It is only to be + used in combination with the dest parameter. + */ + int64 amt_sat = 2; + + /* + A payment request of the target node that the route fee request is intended + for. Its parameters are input to probe payments that estimate routing fees. + The timeout parameter can be specified to set a maximum time on the probing + attempt. Cannot be used in combination with dest and amt_sat. + */ + string payment_request = 3; + + /* + A user preference of how long a probe payment should maximally be allowed to + take, denoted in seconds. The probing payment loop is aborted if this + timeout is reached. Note that the probing process itself can take longer + than the timeout if the HTLC becomes delayed or stuck. Canceling the context + of this call will not cancel the payment loop, the duration is only + controlled by the timeout parameter. + */ + uint32 timeout = 4; +} + +message RouteFeeResponse { + /* + A lower bound of the estimated fee to the target destination within the + network, expressed in milli-satoshis. + */ + int64 routing_fee_msat = 1; + + /* + An estimate of the worst case time delay that can occur. Note that callers + will still need to factor in the final CLTV delta of the last hop into this + value. + */ + int64 time_lock_delay = 2; + + /* + An indication whether a probing payment succeeded or whether and why it + failed. FAILURE_REASON_NONE indicates success. + */ + lnrpc.PaymentFailureReason failure_reason = 5; +} + +message SendToRouteRequest { + // The payment hash to use for the HTLC. + bytes payment_hash = 1; + + // Route that should be used to attempt to complete the payment. + lnrpc.Route route = 2; + + /* + Whether the payment should be marked as failed when a temporary error is + returned from the given route. Set it to true so the payment won't be + failed unless a terminal error is occurred, such as payment timeout, no + routes, incorrect payment details, or insufficient funds. + */ + bool skip_temp_err = 3; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to the first hop peer of this payment. This can be used to pass application + specific data during the payment attempt. Record types are required to be in + the custom range >= 65536. When using REST, the values must be encoded as + base64. + */ + map first_hop_custom_records = 4; +} + +message SendToRouteResponse { + // The preimage obtained by making the payment. + bytes preimage = 1; + + // The failure message in case the payment failed. + lnrpc.Failure failure = 2; +} + +message ResetMissionControlRequest { +} + +message ResetMissionControlResponse { +} + +message QueryMissionControlRequest { +} + +// QueryMissionControlResponse contains mission control state. +message QueryMissionControlResponse { + reserved 1; + + // Node pair-level mission control state. + repeated PairHistory pairs = 2; +} + +message XImportMissionControlRequest { + // Node pair-level mission control state to be imported. + repeated PairHistory pairs = 1; + + // Whether to force override MC pair history. Note that even with force + // override the failure pair is imported before the success pair and both + // still clamp existing failure/success amounts. + bool force = 2; +} + +message XImportMissionControlResponse { +} + +// PairHistory contains the mission control state for a particular node pair. +message PairHistory { + // The source node pubkey of the pair. + bytes node_from = 1; + + // The destination node pubkey of the pair. + bytes node_to = 2; + + reserved 3, 4, 5, 6; + + PairData history = 7; +} + +message PairData { + // Time of last failure. + int64 fail_time = 1; + + /* + Lowest amount that failed to forward rounded to whole sats. This may be + set to zero if the failure is independent of amount. + */ + int64 fail_amt_sat = 2; + + /* + Lowest amount that failed to forward in millisats. This may be + set to zero if the failure is independent of amount. + */ + int64 fail_amt_msat = 4; + + reserved 3; + + // Time of last success. + int64 success_time = 5; + + // Highest amount that we could successfully forward rounded to whole sats. + int64 success_amt_sat = 6; + + // Highest amount that we could successfully forward in millisats. + int64 success_amt_msat = 7; +} + +message GetMissionControlConfigRequest { +} + +message GetMissionControlConfigResponse { + /* + Mission control's currently active config. + */ + MissionControlConfig config = 1; +} + +message SetMissionControlConfigRequest { + /* + The config to set for mission control. Note that all values *must* be set, + because the full config will be applied. + */ + MissionControlConfig config = 1; +} + +message SetMissionControlConfigResponse { +} + +message MissionControlConfig { + /* + Deprecated, use AprioriParameters. The amount of time mission control will + take to restore a penalized node or channel back to 50% success probability, + expressed in seconds. Setting this value to a higher value will penalize + failures for longer, making mission control less likely to route through + nodes and channels that we have previously recorded failures for. + */ + uint64 half_life_seconds = 1 [deprecated = true]; + + /* + Deprecated, use AprioriParameters. The probability of success mission + control should assign to hop in a route where it has no other information + available. Higher values will make mission control more willing to try hops + that we have no information about, lower values will discourage trying these + hops. + */ + float hop_probability = 2 [deprecated = true]; + + /* + Deprecated, use AprioriParameters. The importance that mission control + should place on historical results, expressed as a value in [0;1]. Setting + this value to 1 will ignore all historical payments and just use the hop + probability to assess the probability of success for each hop. A zero value + ignores hop probability completely and relies entirely on historical + results, unless none are available. + */ + float weight = 3 [deprecated = true]; + + /* + The maximum number of payment results that mission control will store. + */ + uint32 maximum_payment_results = 4; + + /* + The minimum time that must have passed since the previously recorded failure + before we raise the failure amount. + */ + uint64 minimum_failure_relax_interval = 5; + + enum ProbabilityModel { + APRIORI = 0; + BIMODAL = 1; + } + + /* + ProbabilityModel defines which probability estimator should be used in + pathfinding. Note that the bimodal estimator is experimental. + */ + ProbabilityModel model = 6; + + /* + EstimatorConfig is populated dependent on the estimator type. + */ + oneof EstimatorConfig { + AprioriParameters apriori = 7; + BimodalParameters bimodal = 8; + } +} + +message BimodalParameters { + /* + NodeWeight defines how strongly other previous forwardings on channels of a + router should be taken into account when computing a channel's probability + to route. The allowed values are in the range [0, 1], where a value of 0 + means that only direct information about a channel is taken into account. + */ + double node_weight = 1; + + /* + ScaleMsat describes the scale over which channels statistically have some + liquidity left. The value determines how quickly the bimodal distribution + drops off from the edges of a channel. A larger value (compared to typical + channel capacities) means that the drop off is slow and that channel + balances are distributed more uniformly. A small value leads to the + assumption of very unbalanced channels. + */ + uint64 scale_msat = 2; + + /* + DecayTime describes the information decay of knowledge about previous + successes and failures in channels. The smaller the decay time, the quicker + we forget about past forwardings. + */ + uint64 decay_time = 3; +} + +message AprioriParameters { + /* + The amount of time mission control will take to restore a penalized node + or channel back to 50% success probability, expressed in seconds. Setting + this value to a higher value will penalize failures for longer, making + mission control less likely to route through nodes and channels that we + have previously recorded failures for. + */ + uint64 half_life_seconds = 1; + + /* + The probability of success mission control should assign to hop in a route + where it has no other information available. Higher values will make mission + control more willing to try hops that we have no information about, lower + values will discourage trying these hops. + */ + double hop_probability = 2; + + /* + The importance that mission control should place on historical results, + expressed as a value in [0;1]. Setting this value to 1 will ignore all + historical payments and just use the hop probability to assess the + probability of success for each hop. A zero value ignores hop probability + completely and relies entirely on historical results, unless none are + available. + */ + double weight = 3; + + /* + The fraction of a channel's capacity that we consider to have liquidity. For + amounts that come close to or exceed the fraction, an additional penalty is + applied. A value of 1.0 disables the capacity factor. Allowed values are in + [0.75, 1.0]. + */ + double capacity_fraction = 4; +} + +message QueryProbabilityRequest { + // The source node pubkey of the pair. + bytes from_node = 1; + + // The destination node pubkey of the pair. + bytes to_node = 2; + + // The amount for which to calculate a probability. + int64 amt_msat = 3; +} + +message QueryProbabilityResponse { + // The success probability for the requested pair. + double probability = 1; + + // The historical data for the requested pair. + PairData history = 2; +} + +message BuildRouteRequest { + /* + The amount to send expressed in msat. If set to zero, the minimum routable + amount is used. + */ + int64 amt_msat = 1; + + /* + CLTV delta from the current height that should be used for the timelock + of the final hop + */ + int32 final_cltv_delta = 2; + + /* + The channel id of the channel that must be taken to the first hop. If zero, + any channel may be used. + */ + uint64 outgoing_chan_id = 3 [jstype = JS_STRING]; + + /* + A list of hops that defines the route. This does not include the source hop + pubkey. + */ + repeated bytes hop_pubkeys = 4; + + /* + An optional payment addr to be included within the last hop of the route. + This is also called payment secret in specifications (e.g. BOLT 11). + */ + bytes payment_addr = 5; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to the first hop peer of this payment. This can be used to pass application + specific data during the payment attempt. Record types are required to be in + the custom range >= 65536. When using REST, the values must be encoded as + base64. + */ + map first_hop_custom_records = 6; +} + +message BuildRouteResponse { + /* + Fully specified route that can be used to execute the payment. + */ + lnrpc.Route route = 1; +} + +message SubscribeHtlcEventsRequest { +} + +/* +HtlcEvent contains the htlc event that was processed. These are served on a +best-effort basis; events are not persisted, delivery is not guaranteed +(in the event of a crash in the switch, forward events may be lost) and +some events may be replayed upon restart. Events consumed from this package +should be de-duplicated by the htlc's unique combination of incoming and +outgoing channel id and htlc id. [EXPERIMENTAL] +*/ +message HtlcEvent { + /* + The short channel id that the incoming htlc arrived at our node on. This + value is zero for sends. + */ + uint64 incoming_channel_id = 1; + + /* + The short channel id that the outgoing htlc left our node on. This value + is zero for receives. + */ + uint64 outgoing_channel_id = 2; + + /* + Incoming id is the index of the incoming htlc in the incoming channel. + This value is zero for sends. + */ + uint64 incoming_htlc_id = 3; + + /* + Outgoing id is the index of the outgoing htlc in the outgoing channel. + This value is zero for receives. + */ + uint64 outgoing_htlc_id = 4; + + /* + The time in unix nanoseconds that the event occurred. + */ + uint64 timestamp_ns = 5; + + enum EventType { + UNKNOWN = 0; + SEND = 1; + RECEIVE = 2; + FORWARD = 3; + } + + /* + The event type indicates whether the htlc was part of a send, receive or + forward. + */ + EventType event_type = 6; + + oneof event { + ForwardEvent forward_event = 7; + ForwardFailEvent forward_fail_event = 8; + SettleEvent settle_event = 9; + LinkFailEvent link_fail_event = 10; + SubscribedEvent subscribed_event = 11; + FinalHtlcEvent final_htlc_event = 12; + } +} + +message HtlcInfo { + // The timelock on the incoming htlc. + uint32 incoming_timelock = 1; + + // The timelock on the outgoing htlc. + uint32 outgoing_timelock = 2; + + // The amount of the incoming htlc. + uint64 incoming_amt_msat = 3; + + // The amount of the outgoing htlc. + uint64 outgoing_amt_msat = 4; +} + +message ForwardEvent { + // Info contains details about the htlc that was forwarded. + HtlcInfo info = 1; +} + +message ForwardFailEvent { +} + +message SettleEvent { + // The revealed preimage. + bytes preimage = 1; +} + +message FinalHtlcEvent { + bool settled = 1; + bool offchain = 2; +} + +message SubscribedEvent { +} + +message LinkFailEvent { + // Info contains details about the htlc that we failed. + HtlcInfo info = 1; + + // FailureCode is the BOLT error code for the failure. + lnrpc.Failure.FailureCode wire_failure = 2; + + /* + FailureDetail provides additional information about the reason for the + failure. This detail enriches the information provided by the wire message + and may be 'no detail' if the wire message requires no additional metadata. + */ + FailureDetail failure_detail = 3; + + // A string representation of the link failure. + string failure_string = 4; +} + +enum FailureDetail { + UNKNOWN = 0; + NO_DETAIL = 1; + ONION_DECODE = 2; + LINK_NOT_ELIGIBLE = 3; + ON_CHAIN_TIMEOUT = 4; + HTLC_EXCEEDS_MAX = 5; + INSUFFICIENT_BALANCE = 6; + INCOMPLETE_FORWARD = 7; + HTLC_ADD_FAILED = 8; + FORWARDS_DISABLED = 9; + INVOICE_CANCELED = 10; + INVOICE_UNDERPAID = 11; + INVOICE_EXPIRY_TOO_SOON = 12; + INVOICE_NOT_OPEN = 13; + MPP_INVOICE_TIMEOUT = 14; + ADDRESS_MISMATCH = 15; + SET_TOTAL_MISMATCH = 16; + SET_TOTAL_TOO_LOW = 17; + SET_OVERPAID = 18; + UNKNOWN_INVOICE = 19; + INVALID_KEYSEND = 20; + MPP_IN_PROGRESS = 21; + CIRCULAR_ROUTE = 22; +} + +enum PaymentState { + /* + Payment is still in flight. + */ + IN_FLIGHT = 0; + + /* + Payment completed successfully. + */ + SUCCEEDED = 1; + + /* + There are more routes to try, but the payment timeout was exceeded. + */ + FAILED_TIMEOUT = 2; + + /* + All possible routes were tried and failed permanently. Or were no + routes to the destination at all. + */ + FAILED_NO_ROUTE = 3; + + /* + A non-recoverable error has occurred. + */ + FAILED_ERROR = 4; + + /* + Payment details incorrect (unknown hash, invalid amt or + invalid final cltv delta) + */ + FAILED_INCORRECT_PAYMENT_DETAILS = 5; + + /* + Insufficient local balance. + */ + FAILED_INSUFFICIENT_BALANCE = 6; +} + +message PaymentStatus { + // Current state the payment is in. + PaymentState state = 1; + + /* + The pre-image of the payment when state is SUCCEEDED. + */ + bytes preimage = 2; + + reserved 3; + + /* + The HTLCs made in attempt to settle the payment [EXPERIMENTAL]. + */ + repeated lnrpc.HTLCAttempt htlcs = 4; +} + +message CircuitKey { + /// The id of the channel that the is part of this circuit. + uint64 chan_id = 1; + + /// The index of the incoming htlc in the incoming channel. + uint64 htlc_id = 2; +} + +message ForwardHtlcInterceptRequest { + /* + The key of this forwarded htlc. It defines the incoming channel id and + the index in this channel. + */ + CircuitKey incoming_circuit_key = 1; + + // The incoming htlc amount. + uint64 incoming_amount_msat = 5; + + // The incoming htlc expiry. + uint32 incoming_expiry = 6; + + /* + The htlc payment hash. This value is not guaranteed to be unique per + request. + */ + bytes payment_hash = 2; + + // The requested outgoing channel id for this forwarded htlc. Because of + // non-strict forwarding, this isn't necessarily the channel over which the + // packet will be forwarded eventually. A different channel to the same peer + // may be selected as well. + uint64 outgoing_requested_chan_id = 7; + + // The outgoing htlc amount. + uint64 outgoing_amount_msat = 3; + + // The outgoing htlc expiry. + uint32 outgoing_expiry = 4; + + // Any custom records that were present in the payload. + map custom_records = 8; + + // The onion blob for the next hop + bytes onion_blob = 9; + + // The block height at which this htlc will be auto-failed to prevent the + // channel from force-closing. + int32 auto_fail_height = 10; + + // The custom records of the peer's incoming p2p wire message. + map in_wire_custom_records = 11; +} + +/** +ForwardHtlcInterceptResponse enables the caller to resolve a previously hold +forward. The caller can choose either to: +- `Resume`: Execute the default behavior (usually forward). +- `ResumeModified`: Execute the default behavior (usually forward) with HTLC + field modifications. +- `Reject`: Fail the htlc backwards. +- `Settle`: Settle this htlc with a given preimage. +*/ +message ForwardHtlcInterceptResponse { + /** + The key of this forwarded htlc. It defines the incoming channel id and + the index in this channel. + */ + CircuitKey incoming_circuit_key = 1; + + // The resolve action for this intercepted htlc. + ResolveHoldForwardAction action = 2; + + // The preimage in case the resolve action is Settle. + bytes preimage = 3; + + // Encrypted failure message in case the resolve action is Fail. + // + // If failure_message is specified, the failure_code field must be set + // to zero. + bytes failure_message = 4; + + // Return the specified failure code in case the resolve action is Fail. The + // message data fields are populated automatically. + // + // If a non-zero failure_code is specified, failure_message must not be set. + // + // For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the + // default value for this field. + lnrpc.Failure.FailureCode failure_code = 5; + + // The amount that was set on the p2p wire message of the incoming HTLC. + // This field is ignored if the action is not RESUME_MODIFIED or the amount + // is zero. + uint64 in_amount_msat = 6; + + // The amount to set on the p2p wire message of the resumed HTLC. This field + // is ignored if the action is not RESUME_MODIFIED or the amount is zero. + uint64 out_amount_msat = 7; + + // Any custom records that should be set on the p2p wire message message of + // the resumed HTLC. This field is ignored if the action is not + // RESUME_MODIFIED. + map out_wire_custom_records = 8; +} + +enum ResolveHoldForwardAction { + // SETTLE is an action that is used to settle an HTLC instead of forwarding + // it. + SETTLE = 0; + + // FAIL is an action that is used to fail an HTLC backwards. + FAIL = 1; + + // RESUME is an action that is used to resume a forward HTLC. + RESUME = 2; + + // RESUME_MODIFIED is an action that is used to resume a hold forward HTLC + // with modifications specified during interception. + RESUME_MODIFIED = 3; +} + +message UpdateChanStatusRequest { + lnrpc.ChannelPoint chan_point = 1; + + ChanStatusAction action = 2; +} + +enum ChanStatusAction { + ENABLE = 0; + DISABLE = 1; + AUTO = 2; +} + +message UpdateChanStatusResponse { +} + +message AddAliasesRequest { + repeated lnrpc.AliasMap alias_maps = 1; +} + +message AddAliasesResponse { + repeated lnrpc.AliasMap alias_maps = 1; +} + +message DeleteAliasesRequest { + repeated lnrpc.AliasMap alias_maps = 1; +} + +message DeleteAliasesResponse { + repeated lnrpc.AliasMap alias_maps = 1; +} \ No newline at end of file diff --git a/vendor/signrpc/signer.proto b/vendor/signrpc/signer.proto index 5ea85dd..28a3295 100644 --- a/vendor/signrpc/signer.proto +++ b/vendor/signrpc/signer.proto @@ -349,6 +349,12 @@ message SignMessageReq { privKey + h_tapTweak(internalKey || tapTweak) */ bytes schnorr_sig_tap_tweak = 6; + + /* + An optional tag that can be provided when taking a tagged hash of a + message. This option can only be used when schnorr_sig is true. + */ + bytes tag = 7; } message SignMessageResp { /* @@ -380,6 +386,12 @@ message VerifyMessageReq { Specifies if the signature is a Schnorr signature. */ bool is_schnorr_sig = 4; + + /* + An optional tag that can be provided when taking a tagged hash of a + message. This option can only be used when is_schnorr_sig is true. + */ + bytes tag = 5; } message VerifyMessageResp { @@ -444,17 +456,38 @@ message TaprootTweakDesc { bool key_spend_only = 2; } +enum MuSig2Version { + /* + The default value on the RPC is zero for enums so we need to represent an + invalid/undefined version by default to make sure clients upgrade their + software to set the version explicitly. + */ + MUSIG2_VERSION_UNDEFINED = 0; + + /* + The version of MuSig2 that lnd 0.15.x shipped with, which corresponds to the + version v0.4.0 of the MuSig2 BIP draft. + */ + MUSIG2_VERSION_V040 = 1; + + /* + The current version of MuSig2 which corresponds to the version v1.0.0rc2 of + the MuSig2 BIP draft. + */ + MUSIG2_VERSION_V100RC2 = 2; +} + message MuSig2CombineKeysRequest { /* - A list of all public keys (serialized in 32-byte x-only format!) - participating in the signing session. The list will always be sorted - lexicographically internally. This must include the local key which is - described by the above key_loc. + A list of all public keys (serialized in 32-byte x-only format for v0.4.0 + and 33-byte compressed format for v1.0.0rc2!) participating in the signing + session. The list will always be sorted lexicographically internally. This + must include the local key which is described by the above key_loc. */ repeated bytes all_signer_pubkeys = 1; /* - A series of optional generic tweaks to be applied to the the aggregated + A series of optional generic tweaks to be applied to the aggregated public key. */ repeated TweakDesc tweaks = 2; @@ -465,6 +498,14 @@ message MuSig2CombineKeysRequest { on-chain. */ TaprootTweakDesc taproot_tweak = 3; + + /* + The mandatory version of the MuSig2 BIP draft to use. This is necessary to + differentiate between the changes that were made to the BIP while this + experimental RPC was already released. Some of those changes affect how the + combined key and nonces are created. + */ + MuSig2Version version = 4; } message MuSig2CombineKeysResponse { @@ -482,6 +523,11 @@ message MuSig2CombineKeysResponse { is used. */ bytes taproot_internal_key = 2; + + /* + The version of the MuSig2 BIP that was used to combine the keys. + */ + MuSig2Version version = 4; } message MuSig2SessionRequest { @@ -491,10 +537,10 @@ message MuSig2SessionRequest { KeyLocator key_loc = 1; /* - A list of all public keys (serialized in 32-byte x-only format!) - participating in the signing session. The list will always be sorted - lexicographically internally. This must include the local key which is - described by the above key_loc. + A list of all public keys (serialized in 32-byte x-only format for v0.4.0 + and 33-byte compressed format for v1.0.0rc2!) participating in the signing + session. The list will always be sorted lexicographically internally. This + must include the local key which is described by the above key_loc. */ repeated bytes all_signer_pubkeys = 2; @@ -505,7 +551,7 @@ message MuSig2SessionRequest { repeated bytes other_signer_public_nonces = 3; /* - A series of optional generic tweaks to be applied to the the aggregated + A series of optional generic tweaks to be applied to the aggregated public key. */ repeated TweakDesc tweaks = 4; @@ -516,6 +562,24 @@ message MuSig2SessionRequest { on-chain. */ TaprootTweakDesc taproot_tweak = 5; + + /* + The mandatory version of the MuSig2 BIP draft to use. This is necessary to + differentiate between the changes that were made to the BIP while this + experimental RPC was already released. Some of those changes affect how the + combined key and nonces are created. + */ + MuSig2Version version = 6; + + /* + A set of pre generated secret local nonces to use in the musig2 session. + This field is optional. This can be useful for protocols that need to send + nonces ahead of time before the set of signer keys are known. This value + MUST be 97 bytes and be the concatenation of two CSPRNG generated 32 byte + values and local public key used for signing as specified in the key_loc + field. + */ + bytes pregenerated_local_nonce = 7; } message MuSig2SessionResponse { @@ -553,6 +617,11 @@ message MuSig2SessionResponse { now. */ bool have_all_nonces = 5; + + /* + The version of the MuSig2 BIP that was used to create the session. + */ + MuSig2Version version = 6; } message MuSig2RegisterNoncesRequest { @@ -637,4 +706,4 @@ message MuSig2CleanupRequest { } message MuSig2CleanupResponse { -} \ No newline at end of file +} diff --git a/vendor/walletrpc/walletkit.proto b/vendor/walletrpc/walletkit.proto index 2e5f453..eac7a73 100644 --- a/vendor/walletrpc/walletkit.proto +++ b/vendor/walletrpc/walletkit.proto @@ -1,12 +1,30 @@ syntax = "proto3"; +package walletrpc; + import "lightning.proto"; import "signrpc/signer.proto"; -package walletrpc; - option go_package = "github.com/lightningnetwork/lnd/lnrpc/walletrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // WalletKit is a service that gives access to the core functionalities of the // daemon's wallet. service WalletKit { @@ -18,7 +36,7 @@ service WalletKit { */ rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse); - /* + /* lncli: `wallet leaseoutput` LeaseOutput locks an output to the given ID, preventing it from being available for any future coin selection attempts. The absolute time of the lock's expiration is returned. The expiration of the lock can be extended by @@ -27,14 +45,14 @@ service WalletKit { */ rpc LeaseOutput (LeaseOutputRequest) returns (LeaseOutputResponse); - /* + /* lncli: `wallet releaseoutput` ReleaseOutput unlocks an output, allowing it to be available for coin selection if it remains unspent. The ID should match the one used to originally lock the output. */ rpc ReleaseOutput (ReleaseOutputRequest) returns (ReleaseOutputResponse); - /* + /* lncli: `wallet listleases` ListLeases lists all currently locked utxos. */ rpc ListLeases (ListLeasesRequest) returns (ListLeasesResponse); @@ -57,14 +75,19 @@ service WalletKit { */ rpc NextAddr (AddrRequest) returns (AddrResponse); - /* + /* lncli: `wallet gettx` + GetTransaction returns details for a transaction found in the wallet. + */ + rpc GetTransaction (GetTransactionRequest) returns (lnrpc.Transaction); + + /* lncli: `wallet accounts list` ListAccounts retrieves all accounts belonging to the wallet by default. A name and key scope filter can be provided to filter through all of the wallet accounts and return only those matching. */ rpc ListAccounts (ListAccountsRequest) returns (ListAccountsResponse); - /* + /* lncli: `wallet requiredreserve` RequiredReserve returns the minimum amount of satoshis that should be kept in the wallet in order to fee bump anchor channels if necessary. The value scales with the number of public anchor channels but is capped at a maximum. @@ -72,7 +95,55 @@ service WalletKit { rpc RequiredReserve (RequiredReserveRequest) returns (RequiredReserveResponse); - /* + /* lncli: `wallet addresses list` + ListAddresses retrieves all the addresses along with their balance. An + account name filter can be provided to filter through all of the + wallet accounts and return the addresses of only those matching. + */ + rpc ListAddresses (ListAddressesRequest) returns (ListAddressesResponse); + + /* lncli: `wallet addresses signmessage` + SignMessageWithAddr returns the compact signature (base64 encoded) created + with the private key of the provided address. This requires the address + to be solely based on a public key lock (no scripts). Obviously the internal + lnd wallet has to possess the private key of the address otherwise + an error is returned. + + This method aims to provide full compatibility with the bitcoin-core and + btcd implementation. Bitcoin-core's algorithm is not specified in a + BIP and only applicable for legacy addresses. This method enhances the + signing for additional address types: P2WKH, NP2WKH, P2TR. + For P2TR addresses this represents a special case. ECDSA is used to create + a compact signature which makes the public key of the signature recoverable. + */ + rpc SignMessageWithAddr (SignMessageWithAddrRequest) + returns (SignMessageWithAddrResponse); + + /* lncli: `wallet addresses verifymessage` + VerifyMessageWithAddr returns the validity and the recovered public key of + the provided compact signature (base64 encoded). The verification is + twofold. First the validity of the signature itself is checked and then + it is verified that the recovered public key of the signature equals + the public key of the provided address. There is no dependence on the + private key of the address therefore also external addresses are allowed + to verify signatures. + Supported address types are P2PKH, P2WKH, NP2WKH, P2TR. + + This method is the counterpart of the related signing method + (SignMessageWithAddr) and aims to provide full compatibility to + bitcoin-core's implementation. Although bitcoin-core/btcd only provide + this functionality for legacy addresses this function enhances it to + the address types: P2PKH, P2WKH, NP2WKH, P2TR. + + The verification for P2TR addresses is a special case and requires the + ECDSA compact signature to compare the reovered public key to the internal + taproot key. The compact ECDSA signature format was used because there + are still no known compact signature schemes for schnorr signatures. + */ + rpc VerifyMessageWithAddr (VerifyMessageWithAddrRequest) + returns (VerifyMessageWithAddrResponse); + + /* lncli: `wallet accounts import` ImportAccount imports an account backed by an account extended public key. The master key fingerprint denotes the fingerprint of the root key corresponding to the account public key (also known as the key with @@ -99,8 +170,12 @@ service WalletKit { */ rpc ImportAccount (ImportAccountRequest) returns (ImportAccountResponse); - /* - ImportPublicKey imports a public key as watch-only into the wallet. + /* lncli: `wallet accounts import-pubkey` + ImportPublicKey imports a public key as watch-only into the wallet. The + public key is converted into a simple address of the given type and that + address script is watched on chain. For Taproot keys, this will only watch + the BIP-0086 style output script. Use ImportTapscript for more advanced key + spend or script spend outputs. NOTE: Events (deposits/spends) for a key will only be detected by lnd if they happen after the import. Rescans to detect past events will be @@ -110,6 +185,22 @@ service WalletKit { returns (ImportPublicKeyResponse); /* + ImportTapscript imports a Taproot script and internal key and adds the + resulting Taproot output key as a watch-only output script into the wallet. + For BIP-0086 style Taproot keys (no root hash commitment and no script spend + path) use ImportPublicKey. + + NOTE: Events (deposits/spends) for a key will only be detected by lnd if + they happen after the import. Rescans to detect past events will be + supported later on. + + NOTE: Taproot keys imported through this RPC currently _cannot_ be used for + funding PSBTs. Only tracking the balance and UTXOs is currently supported. + */ + rpc ImportTapscript (ImportTapscriptRequest) + returns (ImportTapscriptResponse); + + /* lncli: `wallet publishtx` PublishTransaction attempts to publish the passed transaction to the network. Once this returns without an error, the wallet will continually attempt to re-broadcast the transaction on start up, until it enters the @@ -117,6 +208,13 @@ service WalletKit { */ rpc PublishTransaction (Transaction) returns (PublishResponse); + /* lncli: `wallet removetx` + RemoveTransaction attempts to remove the provided transaction from the + internal transaction store of the wallet. + */ + rpc RemoveTransaction (GetTransactionRequest) + returns (RemoveTransactionResponse); + /* SendOutputs is similar to the existing sendmany call in Bitcoind, and allows the caller to create a transaction that sends to several outputs at @@ -131,7 +229,7 @@ service WalletKit { */ rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse); - /* + /* lncli: `pendingsweeps` PendingSweeps returns lists of on-chain outputs that lnd is currently attempting to sweep within its central batching engine. Outputs with similar fee rates are batched together in order to sweep them within a single @@ -143,62 +241,82 @@ service WalletKit { */ rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse); - /* - BumpFee bumps the fee of an arbitrary input within a transaction. This RPC - takes a different approach than bitcoind's bumpfee command. lnd has a - central batching engine in which inputs with similar fee rates are batched - together to save on transaction fees. Due to this, we cannot rely on - bumping the fee on a specific transaction, since transactions can change at - any point with the addition of new inputs. The list of inputs that - currently exist within lnd's central batching engine can be retrieved - through the PendingSweeps RPC. - - When bumping the fee of an input that currently exists within lnd's central - batching engine, a higher fee transaction will be created that replaces the - lower fee transaction through the Replace-By-Fee (RBF) policy. If it + /* lncli: `wallet bumpfee` + BumpFee is an endpoint that allows users to interact with lnd's sweeper + directly. It takes an outpoint from an unconfirmed transaction and sends it + to the sweeper for potential fee bumping. Depending on whether the outpoint + has been registered in the sweeper (an existing input, e.g., an anchor + output) or not (a new input, e.g., an unconfirmed wallet utxo), this will + either be an RBF or CPFP attempt. + + When receiving an input, lnd’s sweeper needs to understand its time + sensitivity to make economical fee bumps - internally a fee function is + created using the deadline and budget to guide the process. When the + deadline is approaching, the fee function will increase the fee rate and + perform an RBF. + + When a force close happens, all the outputs from the force closing + transaction will be registered in the sweeper. The sweeper will then handle + the creation, publish, and fee bumping of the sweeping transactions. + Everytime a new block comes in, unless the sweeping transaction is + confirmed, an RBF is attempted. To interfere with this automatic process, + users can use BumpFee to specify customized fee rate, budget, deadline, and + whether the sweep should happen immediately. It's recommended to call + `ListSweeps` to understand the shape of the existing sweeping transaction + first - depending on the number of inputs in this transaction, the RBF + requirements can be quite different. This RPC also serves useful when wanting to perform a Child-Pays-For-Parent (CPFP), where the child transaction pays for its parent's fee. This can be done by specifying an outpoint within the low fee transaction that is under the control of the wallet. - - The fee preference can be expressed either as a specific fee rate or a delta - of blocks in which the output should be swept on-chain within. If a fee - preference is not explicitly specified, then an error is returned. - - Note that this RPC currently doesn't perform any validation checks on the - fee preference being provided. For now, the responsibility of ensuring that - the new fee preference is sufficient is delegated to the user. */ rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse); - /* + /* lncli: `wallet bumpforceclosefee` + BumpForceCloseFee is an endpoint that allows users to bump the fee of a + channel force close. This only works for channels with option_anchors. + */ + rpc BumpForceCloseFee (BumpForceCloseFeeRequest) + returns (BumpForceCloseFeeResponse); + + /* lncli: `wallet listsweeps` ListSweeps returns a list of the sweep transactions our node has produced. Note that these sweeps may not be confirmed yet, as we record sweeps on broadcast, not confirmation. */ rpc ListSweeps (ListSweepsRequest) returns (ListSweepsResponse); - /* + /* lncli: `wallet labeltx` LabelTransaction adds a label to a transaction. If the transaction already has a label the call will fail unless the overwrite bool is set. This will - overwrite the exiting transaction label. Labels must not be empty, and + overwrite the existing transaction label. Labels must not be empty, and cannot exceed 500 characters. */ rpc LabelTransaction (LabelTransactionRequest) returns (LabelTransactionResponse); - /* + /* lncli: `wallet psbt fund` FundPsbt creates a fully populated PSBT that contains enough inputs to fund - the outputs specified in the template. There are two ways of specifying a - template: Either by passing in a PSBT with at least one output declared or - by passing in a raw TxTemplate message. - - If there are no inputs specified in the template, coin selection is - performed automatically. If the template does contain any inputs, it is - assumed that full coin selection happened externally and no additional - inputs are added. If the specified inputs aren't enough to fund the outputs - with the given fee rate, an error is returned. + the outputs specified in the template. There are three ways a user can + specify what we call the template (a list of inputs and outputs to use in + the PSBT): Either as a PSBT packet directly with no coin selection (using + the legacy "psbt" field), a PSBT with advanced coin selection support (using + the new "coin_select" field) or as a raw RPC message (using the "raw" + field). + The legacy "psbt" and "raw" modes, the following restrictions apply: + 1. If there are no inputs specified in the template, coin selection is + performed automatically. + 2. If the template does contain any inputs, it is assumed that full + coin selection happened externally and no additional inputs are added. If + the specified inputs aren't enough to fund the outputs with the given fee + rate, an error is returned. + + The new "coin_select" mode does not have these restrictions and allows the + user to specify a PSBT with inputs and outputs and still perform coin + selection on top of that. + For all modes this RPC requires any inputs that are specified to be locked + by the user (if they belong to this node in the first place). After either selecting or verifying the inputs, all input UTXOs are locked with an internal app ID. @@ -225,7 +343,7 @@ service WalletKit { */ rpc SignPsbt (SignPsbtRequest) returns (SignPsbtResponse); - /* + /* lncli: `wallet psbt finalize` FinalizePsbt expects a partial transaction with all inputs and outputs fully declared and tries to sign all inputs that belong to the wallet. Lnd must be the last signer of the transaction. That means, if there are any unsigned @@ -348,14 +466,7 @@ message Account { // The name used to identify the account. string name = 1; - /* - The type of addresses the account supports. - AddressType | External Branch | Internal Branch - --------------------------------------------------------------------- - WITNESS_PUBKEY_HASH | P2WPKH | P2WPKH - NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | NP2WPKH - HYBRID_NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | P2WPKH - */ + // The type of addresses the account supports. AddressType address_type = 2; /* @@ -397,6 +508,57 @@ message Account { // Whether the wallet stores private keys for the account. bool watch_only = 8; } + +message AddressProperty { + /* + The address encoded using the appropriate format depending on the + address type (base58, bech32, bech32m). + + Note that lnd's internal/custom keys for channels and other + functionality are derived from the same scope. Since they + aren't really used as addresses and will never have an + on-chain balance, we'll show the public key instead (only if + the show_custom_accounts flag is provided). + */ + string address = 1; + + // Denotes if the address is a change address. + bool is_internal = 2; + + // The balance of the address. + int64 balance = 3; + + // The full derivation path of the address. This will be empty for imported + // addresses. + string derivation_path = 4; + + // The public key of the address. This will be empty for imported addresses. + bytes public_key = 5; +} + +message AccountWithAddresses { + // The name used to identify the account. + string name = 1; + + // The type of addresses the account supports. + AddressType address_type = 2; + + /* + The derivation path corresponding to the account public key. This will + always be empty for the default imported account in which single public keys + are imported into. + */ + string derivation_path = 3; + + /* + List of address, its type internal/external & balance. + Note that the order of addresses will be random and not according to the + derivation index, since that information is not stored by the underlying + wallet. + */ + repeated AddressProperty addresses = 4; +} + message ListAccountsRequest { // An optional filter to only return accounts matching this name. string name = 1; @@ -404,6 +566,7 @@ message ListAccountsRequest { // An optional filter to only return accounts matching this address type. AddressType address_type = 2; } + message ListAccountsResponse { repeated Account accounts = 1; } @@ -418,6 +581,62 @@ message RequiredReserveResponse { int64 required_reserve = 1; } +message ListAddressesRequest { + // An optional filter to only return addresses matching this account. + string account_name = 1; + + // An optional flag to return LND's custom accounts (Purpose=1017) + // public key along with other addresses. + bool show_custom_accounts = 2; +} + +message ListAddressesResponse { + // A list of all the accounts and their addresses. + repeated AccountWithAddresses account_with_addresses = 1; +} + +message GetTransactionRequest { + // The txid of the transaction. + string txid = 1; +} + +message SignMessageWithAddrRequest { + // The message to be signed. When using REST, this field must be encoded as + // base64. + bytes msg = 1; + + // The address which will be used to look up the private key and sign the + // corresponding message. + string addr = 2; +} + +message SignMessageWithAddrResponse { + // The compact ECDSA signature for the given message encoded in base64. + string signature = 1; +} + +message VerifyMessageWithAddrRequest { + // The message to be signed. When using REST, this field must be encoded as + // base64. + bytes msg = 1; + + // The compact ECDSA signature to be verified over the given message + // ecoded in base64. + string signature = 2; + + // The address which will be used to look up the public key and verify the + // the signature. + string addr = 3; +} + +message VerifyMessageWithAddrResponse { + // Whether the signature was valid over the given message. + bool valid = 1; + + // The pubkey recovered from the signature. + bytes pubkey = 2; +} + message ImportAccountRequest { // A name to identify the account with. string name = 1; @@ -482,9 +701,82 @@ message ImportPublicKeyRequest { message ImportPublicKeyResponse { } +message ImportTapscriptRequest { + /* + The internal public key, serialized as 32-byte x-only public key. + */ + bytes internal_public_key = 1; + + oneof script { + /* + The full script tree with all individual leaves is known and the root + hash can be constructed from the full tree directly. + */ + TapscriptFullTree full_tree = 2; + + /* + Only a single script leaf is known. To construct the root hash, the full + inclusion proof must also be provided. + */ + TapscriptPartialReveal partial_reveal = 3; + + /* + Only the root hash of the Taproot script tree (or other form of Taproot + commitment) is known. + */ + bytes root_hash_only = 4; + + /* + Only the final, tweaked Taproot key is known and no additional + information about the internal key or type of tweak that was used to + derive it. When this is set, the wallet treats the key in + internal_public_key as the Taproot key directly. This can be useful for + tracking arbitrary Taproot outputs without the goal of ever being able + to spend from them through the internal wallet. + */ + bool full_key_only = 5; + } +} + +message TapscriptFullTree { + /* + The complete, ordered list of all tap leaves of the tree. + */ + repeated TapLeaf all_leaves = 1; +} + +message TapLeaf { + // The leaf version. Should be 0xc0 (192) in case of a SegWit v1 script. + uint32 leaf_version = 1; + + // The script of the tap leaf. + bytes script = 2; +} + +message TapscriptPartialReveal { + // The tap leaf that is known and will be revealed. + TapLeaf revealed_leaf = 1; + + // The BIP-0341 serialized inclusion proof that is required to prove that + // the revealed leaf is part of the tree. This contains 0..n blocks of 32 + // bytes. If the tree only contained a single leaf (which is the revealed + // leaf), this can be empty. + bytes full_inclusion_proof = 2; +} + +message ImportTapscriptResponse { + /* + The resulting pay-to-Taproot address that represents the imported internal + key with the script committed to it. + */ + string p2tr_address = 1; +} + message Transaction { /* - The raw serialized transaction. + The raw serialized transaction. Despite the field name, this does need to be + specified in raw bytes (or base64 encoded when using REST) and not in hex. + To not break existing software, the field can't simply be renamed. */ bytes tx_hex = 1; @@ -493,6 +785,7 @@ message Transaction { */ string label = 2; } + message PublishResponse { /* If blank, then no error occurred and the transaction was successfully @@ -504,6 +797,11 @@ message PublishResponse { string publish_error = 1; } +message RemoveTransactionResponse { + // The status of the remove transaction operation. + string status = 1; +} + message SendOutputsRequest { /* The number of satoshis per kilo weight that should be used when crafting @@ -525,6 +823,9 @@ message SendOutputsRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 5; + + // The strategy to use for selecting coins during sending the outputs. + lnrpc.CoinSelectionStrategy coin_selection_strategy = 6; } message SendOutputsResponse { /* @@ -545,6 +846,9 @@ message EstimateFeeResponse { confirmation target in the request. */ int64 sat_per_kw = 1; + + // The current minimum relay fee based on our chain backend in sat/kw. + int64 min_relay_fee_sat_per_kw = 2; } enum WitnessType { @@ -635,6 +939,161 @@ enum WitnessType { transaction. */ COMMITMENT_ANCHOR = 13; + + /* + A witness type that is similar to the COMMITMENT_NO_DELAY type, + but it omits the tweak that randomizes the key we need to + spend with a channel peer supplied set of randomness. + */ + COMMITMENT_NO_DELAY_TWEAKLESS = 14; + + /* + A witness type that allows us to spend our output on the counterparty's + commitment transaction after a confirmation. + */ + COMMITMENT_TO_REMOTE_CONFIRMED = 15; + + /* + A witness type that allows us to sweep an HTLC output that we extended + to a party, but was never fulfilled. This _is_ the HTLC output directly + on our commitment transaction, and the input to the second-level HTLC + timeout transaction. It can only be spent after CLTV expiry, and + commitment confirmation. + */ + HTLC_OFFERED_TIMEOUT_SECOND_LEVEL_INPUT_CONFIRMED = 16; + + /* + A witness type that allows us to sweep an HTLC output that was offered + to us, and for which we have a payment preimage. This _is_ the HTLC + output directly on our commitment transaction, and the input to the + second-level HTLC success transaction. It can only be spent after the + commitment has confirmed. + */ + HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL_INPUT_CONFIRMED = 17; + + /* + A witness type that allows us to spend our output on our local + commitment transaction after a relative and absolute lock-time lockout as + part of the script enforced lease commitment type. + */ + LEASE_COMMITMENT_TIME_LOCK = 18; + + /* + A witness type that allows us to spend our output on the counterparty's + commitment transaction after a confirmation and absolute locktime as part + of the script enforced lease commitment type. + */ + LEASE_COMMITMENT_TO_REMOTE_CONFIRMED = 19; + + /* + A witness type that allows us to sweep an HTLC output that we extended + to a party, but was never fulfilled. This HTLC output isn't directly on + the commitment transaction, but is the result of a confirmed second-level + HTLC transaction. As a result, we can only spend this after a CSV delay + and CLTV locktime as part of the script enforced lease commitment type. + */ + LEASE_HTLC_OFFERED_TIMEOUT_SECOND_LEVEL = 20; + + /* + A witness type that allows us to sweep an HTLC output that was offered + to us, and for which we have a payment preimage. This HTLC output isn't + directly on our commitment transaction, but is the result of confirmed + second-level HTLC transaction. As a result, we can only spend this after + a CSV delay and CLTV locktime as part of the script enforced lease + commitment type. + */ + LEASE_HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL = 21; + + /* + A witness type that allows us to spend a regular p2tr output that's sent + to an output which is under complete control of the backing wallet. + */ + TAPROOT_PUB_KEY_SPEND = 22; + + /* + A witness type that allows us to spend our settled local commitment after a + CSV delay when we force close the channel. + */ + TAPROOT_LOCAL_COMMIT_SPEND = 23; + + /* + A witness type that allows us to spend our settled local commitment after + a CSV delay when the remote party has force closed the channel. + */ + TAPROOT_REMOTE_COMMIT_SPEND = 24; + + /* + A witness type that we'll use for spending our own anchor output. + */ + TAPROOT_ANCHOR_SWEEP_SPEND = 25; + + /* + A witness that allows us to timeout an HTLC we offered to the remote party + on our commitment transaction. We use this when we need to go on chain to + time out an HTLC. + */ + TAPROOT_HTLC_OFFERED_TIMEOUT_SECOND_LEVEL = 26; + + /* + A witness type that allows us to sweep an HTLC we accepted on our commitment + transaction after we go to the second level on chain. + */ + TAPROOT_HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL = 27; + + /* + A witness that allows us to sweep an HTLC on the revoked transaction of the + remote party that goes to the second level. + */ + TAPROOT_HTLC_SECOND_LEVEL_REVOKE = 28; + + /* + A witness that allows us to sweep an HTLC sent to us by the remote party + in the event that they broadcast a revoked state. + */ + TAPROOT_HTLC_ACCEPTED_REVOKE = 29; + + /* + A witness that allows us to sweep an HTLC we offered to the remote party if + they broadcast a revoked commitment. + */ + TAPROOT_HTLC_OFFERED_REVOKE = 30; + + /* + A witness that allows us to sweep an HTLC we offered to the remote party + that lies on the commitment transaction for the remote party. We can spend + this output after the absolute CLTV timeout of the HTLC as passed. + */ + TAPROOT_HTLC_OFFERED_REMOTE_TIMEOUT = 31; + + /* + A witness type that allows us to sign the second level HTLC timeout + transaction when spending from an HTLC residing on our local commitment + transaction. + This is used by the sweeper to re-sign inputs if it needs to aggregate + several second level HTLCs. + */ + TAPROOT_HTLC_LOCAL_OFFERED_TIMEOUT = 32; + + /* + A witness that allows us to sweep an HTLC that was offered to us by the + remote party for a taproot channels. We use this witness in the case that + the remote party goes to chain, and we know the pre-image to the HTLC. We + can sweep this without any additional timeout. + */ + TAPROOT_HTLC_ACCEPTED_REMOTE_SUCCESS = 33; + + /* + A witness type that allows us to sweep the HTLC offered to us on our local + commitment transaction. We'll use this when we need to go on chain to sweep + the HTLC. In this case, this is the second level HTLC success transaction. + */ + TAPROOT_HTLC_ACCEPTED_LOCAL_SUCCESS = 34; + + /* + A witness that allows us to sweep the settled output of a malicious + counterparty's who broadcasts a revoked taproot commitment transaction. + */ + TAPROOT_COMMITMENT_REVOKE = 35; } message PendingSweep { @@ -659,33 +1118,56 @@ message PendingSweep { uint32 broadcast_attempts = 5; /* + Deprecated. The next height of the chain at which we'll attempt to broadcast the sweep transaction of the output. */ - uint32 next_broadcast_height = 6; + uint32 next_broadcast_height = 6 [deprecated = true]; - // The requested confirmation target for this output. - uint32 requested_conf_target = 8; + /* + Deprecated, use immediate. + Whether this input must be force-swept. This means that it is swept + immediately. + */ + bool force = 7 [deprecated = true]; + + /* + Deprecated, use deadline. + The requested confirmation target for this output, which is the deadline + used by the sweeper. + */ + uint32 requested_conf_target = 8 [deprecated = true]; // Deprecated, use requested_sat_per_vbyte. // The requested fee rate, expressed in sat/vbyte, for this output. uint32 requested_sat_per_byte = 9 [deprecated = true]; /* - The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee - rate is only determined once a sweeping transaction for the output is - created, so it's possible for this to be 0 before this. + The current fee rate we'll use to sweep the output, expressed in sat/vbyte. + The fee rate is only determined once a sweeping transaction for the output + is created, so it's possible for this to be 0 before this. */ uint64 sat_per_vbyte = 10; - // The requested fee rate, expressed in sat/vbyte, for this output. + // The requested starting fee rate, expressed in sat/vbyte, for this + // output. When not requested, this field will be 0. uint64 requested_sat_per_vbyte = 11; /* - Whether this input must be force-swept. This means that it is swept even - if it has a negative yield. + Whether this input will be swept immediately. + */ + bool immediate = 12; + + /* + The budget for this sweep, expressed in satoshis. This is the maximum amount + that can be spent as fees to sweep this output. */ - bool force = 7; + uint64 budget = 13; + + /* + The deadline height used for this output when perform fee bumping. + */ + uint32 deadline_height = 14; } message PendingSweepsRequest { @@ -702,7 +1184,9 @@ message BumpFeeRequest { // The input we're attempting to bump the fee of. lnrpc.OutPoint outpoint = 1; - // The target number of blocks that the input should be spent within. + // Optional. The deadline in number of blocks that the input should be spent + // within. When not set, for new inputs, the default value (1008) is used; + // for existing inputs, their current values will be retained. uint32 target_conf = 2; /* @@ -713,19 +1197,80 @@ message BumpFeeRequest { uint32 sat_per_byte = 3 [deprecated = true]; /* - Whether this input must be force-swept. This means that it is swept even - if it has a negative yield. + Deprecated, use immediate. + Whether this input must be force-swept. This means that it is swept + immediately. */ - bool force = 4; + bool force = 4 [deprecated = true]; /* - The fee rate, expressed in sat/vbyte, that should be used to spend the input - with. + Optional. The starting fee rate, expressed in sat/vbyte, that will be used + to spend the input with initially. This value will be used by the sweeper's + fee function as its starting fee rate. When not set, the sweeper will use + the estimated fee rate using the `target_conf` as the starting fee rate. */ uint64 sat_per_vbyte = 5; + + /* + Optional. Whether this input will be swept immediately. When set to true, + the sweeper will sweep this input without waiting for the next batch. + */ + bool immediate = 6; + + /* + Optional. The max amount in sats that can be used as the fees. Setting this + value greater than the input's value may result in CPFP - one or more wallet + utxos will be used to pay the fees specified by the budget. If not set, for + new inputs, by default 50% of the input's value will be treated as the + budget for fee bumping; for existing inputs, their current budgets will be + retained. + */ + uint64 budget = 7; } message BumpFeeResponse { + // The status of the bump fee operation. + string status = 1; +} + +message BumpForceCloseFeeRequest { + // The channel point which force close transaction we are attempting to + // bump the fee rate for. + lnrpc.ChannelPoint chan_point = 1; + + // Optional. The deadline delta in number of blocks that the anchor output + // should be spent within to bump the closing transaction. + uint32 deadline_delta = 2; + + /* + Optional. The starting fee rate, expressed in sat/vbyte. This value will be + used by the sweeper's fee function as its starting fee rate. When not set, + the sweeper will use the estimated fee rate using the target_conf as the + starting fee rate. + */ + uint64 starting_feerate = 3; + + /* + Optional. Whether this cpfp transaction will be triggered immediately. When + set to true, the sweeper will consider all currently registered sweeps and + trigger new batch transactions including the sweeping of the anchor output + related to the selected force close transaction. + */ + bool immediate = 4; + + /* + Optional. The max amount in sats that can be used as the fees. For already + registered anchor outputs if not set explicitly the old value will be used. + For channel force closes which have no HTLCs in their commitment transaction + this value has to be set to an appropriate amount to pay for the cpfp + transaction of the force closed channel otherwise the fee bumping will fail. + */ + uint64 budget = 5; +} + +message BumpForceCloseFeeResponse { + // The status of the force close fee bump operation. + string status = 1; } message ListSweepsRequest { @@ -735,6 +1280,13 @@ message ListSweepsRequest { replaced-by-fee, so will not be included in this output. */ bool verbose = 1; + + /* + The start height to use when fetching sweeps. If not specified (0), the + result will start from the earliest sweep. If set to -1 the result will + only include unconfirmed sweeps (at the time of the call). + */ + int32 start_height = 2; } message ListSweepsResponse { @@ -754,7 +1306,8 @@ message ListSweepsResponse { } message LabelTransactionRequest { - // The txid of the transaction to label. + // The txid of the transaction to label. Note: When using gRPC, the bytes + // must be in little-endian (reverse) order. bytes txid = 1; // The label to add to the transaction, limited to 500 characters. @@ -767,6 +1320,23 @@ message LabelTransactionRequest { message LabelTransactionResponse { } +// The possible change address types for default accounts and single imported +// public keys. By default, P2WPKH will be used. We don't provide the +// possibility to choose P2PKH as it is a legacy key scope, nor NP2WPKH as +// no key scope permits to do so. For custom accounts, no change type should +// be provided as the coin selection key scope will always be used to generate +// the change address. +enum ChangeAddressType { + // CHANGE_ADDRESS_TYPE_UNSPECIFIED indicates that no change address type is + // provided. We will then use P2WPKH address type for change (BIP0084 key + // scope). + CHANGE_ADDRESS_TYPE_UNSPECIFIED = 0; + + // CHANGE_ADDRESS_TYPE_P2TR indicates to use P2TR address for change output + // (BIP0086 key scope). + CHANGE_ADDRESS_TYPE_P2TR = 1; +} + message FundPsbtRequest { oneof template { /* @@ -785,6 +1355,26 @@ message FundPsbtRequest { Use the outputs and optional inputs from this raw template. */ TxTemplate raw = 2; + + /* + Use an existing PSBT packet as the template for the funded PSBT. + + The difference to the pure PSBT template above is that coin selection is + performed even if inputs are specified. The output amounts are summed up + and used as the target amount for coin selection. A change output must + either already exist in the PSBT and be marked as such, otherwise a new + change output of the specified output type will be added. Any inputs + already specified in the PSBT must already be locked (if they belong to + this node), only newly added inputs will be locked by this RPC. + + In case the sum of the already provided inputs exceeds the required + output amount, no new coins are selected. Instead only the fee and + change amount calculation is performed (e.g. a change output is added if + requested or the change is added to the specified existing change + output, given there is any non-dust change). This can be identified by + the returned locked UTXOs being empty. + */ + PsbtCoinSelect coin_select = 9; } oneof fees { @@ -812,6 +1402,15 @@ message FundPsbtRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 7; + + // The address type for the change. If empty, P2WPKH addresses will be used + // for default accounts and single imported public keys. For custom + // accounts, no change type should be provided as the coin selection key + // scope will always be used to generate the change address. + ChangeAddressType change_type = 8; + + // The strategy to use for selecting coins during funding the PSBT. + lnrpc.CoinSelectionStrategy coin_selection_strategy = 10; } message FundPsbtResponse { /* @@ -826,7 +1425,8 @@ message FundPsbtResponse { /* The list of lock leases that were acquired for the inputs in the funded PSBT - packet. + packet. Only inputs added to the PSBT by this RPC are locked, inputs that + were already present in the PSBT are not locked. */ repeated UtxoLease locked_utxos = 3; } @@ -849,6 +1449,38 @@ message TxTemplate { map outputs = 2; } +message PsbtCoinSelect { + /* + The template to use for the funded PSBT. The template must contain at least + one non-dust output. The amount to be funded is calculated by summing up the + amounts of all outputs in the template, subtracting all the input values of + the already specified inputs. The change value is added to the output that + is marked as such (or a new change output is added if none is marked). For + the input amount calculation to be correct, the template must have the + WitnessUtxo field set for all inputs. Any inputs already specified in the + PSBT must already be locked (if they belong to this node), only newly added + inputs will be locked by this RPC. + */ + bytes psbt = 1; + + oneof change_output { + /* + Use the existing output within the template PSBT with the specified + index as the change output. Any leftover change will be added to the + already specified amount of that output. To add a new change output to + the PSBT, set the "add" field below instead. The type of change output + added is defined by change_type in the parent message. + */ + int32 existing_output_index = 2; + + /* + Add a new change output to the PSBT using the change_type specified in + the parent message. + */ + bool add = 3; + } +} + message UtxoLease { /* A 32 byte random ID that identifies the lease. @@ -885,6 +1517,9 @@ message SignPsbtRequest { message SignPsbtResponse { // The signed transaction in PSBT format. bytes signed_psbt = 1; + + // The indices of signed inputs. + repeated uint32 signed_inputs = 2; } message FinalizePsbtRequest {