From 48fc1af4a0e53e66c9a794b303df24b162811137 Mon Sep 17 00:00:00 2001 From: Nitesh Balusu Date: Fri, 5 Jul 2024 19:11:18 -0400 Subject: [PATCH] bump until lnd v0.18.1-beta --- Cargo.toml | 4 +- vendor/devrpc/dev.proto | 24 +- vendor/invoicesrpc/invoices.proto | 33 ++- vendor/lightning.proto | 245 ++++++++++++++-- vendor/lnclipb/lncli.proto | 4 +- vendor/neutrinorpc/neutrino.proto | 30 +- vendor/peersrpc/peers.proto | 4 +- vendor/routerrpc/router.proto | 160 +++++++---- vendor/signrpc/signer.proto | 16 +- vendor/walletrpc/walletkit.proto | 383 +++++++++++++++++++++----- vendor/walletunlocker.proto | 4 +- vendor/watchtowerrpc/watchtower.proto | 20 +- vendor/wtclientrpc/wtclient.proto | 81 +++++- 13 files changed, 841 insertions(+), 167 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 7e4331d..bd3d03f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,8 +20,8 @@ tonic-openssl = { version = "0.2" } hyper = "0.14" hyper-openssl = "0.9" prost = "0.10" -tokio = { version = "1.35", features = ["rt-multi-thread", "macros"] } -tokio-stream = { version = "0.1.14", features = ["net"] } +tokio = { version = "1.38", features = ["rt-multi-thread", "macros"] } +tokio-stream = { version = "0.1.15", features = ["net"] } openssl = "0.10.16" tower = "0.4.13" pretty_env_logger = "0.5.0" diff --git a/vendor/devrpc/dev.proto b/vendor/devrpc/dev.proto index 72808a8..55b11a9 100644 --- a/vendor/devrpc/dev.proto +++ b/vendor/devrpc/dev.proto @@ -1,13 +1,31 @@ syntax = "proto3"; -import "lightning.proto"; - package devrpc; +import "lightning.proto"; + option go_package = "github.com/lightningnetwork/lnd/lnrpc/devrpc"; +/* + * 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 + */ + service Dev { - /* + /* lncli: `importgraph` ImportGraph imports a ChannelGraph into the graph database. Should only be used for development. */ diff --git a/vendor/invoicesrpc/invoices.proto b/vendor/invoicesrpc/invoices.proto index d5f327d..6bc2a76 100644 --- a/vendor/invoicesrpc/invoices.proto +++ b/vendor/invoicesrpc/invoices.proto @@ -1,11 +1,29 @@ syntax = "proto3"; -import "lightning.proto"; - package invoicesrpc; +import "lightning.proto"; + option go_package = "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc"; +/* + * 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 + */ + // Invoices is a service that can be used to create, accept, settle and cancel // invoices. service Invoices { @@ -17,20 +35,20 @@ service Invoices { rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest) returns (stream lnrpc.Invoice); - /* + /* lncli: `cancelinvoice` CancelInvoice cancels a currently open invoice. If the invoice is already canceled, this call will succeed. If the invoice is already settled, it will fail. */ rpc CancelInvoice (CancelInvoiceMsg) returns (CancelInvoiceResp); - /* + /* lncli: `addholdinvoice` AddHoldInvoice creates a hold invoice. It ties the invoice to the hash supplied in the request. */ rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp); - /* + /* lncli: `settleinvoice` SettleInvoice settles an accepted invoice. If the invoice is already settled, this call will succeed. */ @@ -120,8 +138,9 @@ message AddHoldInvoiceResp { uint64 add_index = 2; /* - 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 + The payment address of the generated invoice. This is also called + the 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 = 3; diff --git a/vendor/lightning.proto b/vendor/lightning.proto index 008d4db..2ceda84 100644 --- a/vendor/lightning.proto +++ b/vendor/lightning.proto @@ -143,6 +143,13 @@ service Lightning { */ rpc GetInfo (GetInfoRequest) returns (GetInfoResponse); + /* lncli: 'getdebuginfo' + GetDebugInfo returns debug information concerning the state of the daemon + and its subsystems. This includes the full configuration and the latest log + entries from the log file. + */ + rpc GetDebugInfo (GetDebugInfoRequest) returns (GetDebugInfoResponse); + /** lncli: `getrecoveryinfo` GetRecoveryInfo returns information concerning the recovery mode including whether it's in a recovery mode, whether the recovery is finished, and the @@ -322,7 +329,7 @@ service Lightning { optionally specify the add_index and/or the settle_index. If the add_index is specified, then we'll first start by sending add invoice events for all invoices with an add_index greater than the specified value. If the - settle_index is specified, the next, we'll send out all settle events for + settle_index is specified, then next, we'll send out all settle events for invoices with a settle_index greater than the specified value. One or both of these fields can be set. If no fields are set, then we'll only send out the latest add/settle events. @@ -341,13 +348,13 @@ service Lightning { */ rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse); - /* + /* lncli: `deletepayments` DeletePayment deletes an outgoing payment from DB. Note that it will not attempt to delete an In-Flight payment, since that would be unsafe. */ rpc DeletePayment (DeletePaymentRequest) returns (DeletePaymentResponse); - /* + /* lncli: `deletepayments --all` DeleteAllPayments deletes all outgoing payments from DB. Note that it will not attempt to delete In-Flight payments, since that would be unsafe. */ @@ -479,7 +486,7 @@ service Lightning { rpc ExportAllChannelBackups (ChanBackupExportRequest) returns (ChanBackupSnapshot); - /* + /* lncli: `verifychanbackup` VerifyChanBackup allows a caller to verify the integrity of a channel backup snapshot. This method will accept either a packed Single or a packed Multi. Specifying both will result in an error. @@ -877,7 +884,8 @@ message SendRequest { repeated FeatureBit dest_features = 15; /* - The payment address of the generated invoice. + The payment address of the generated invoice. This is also called + payment secret in specifications (e.g. BOLT 11). */ bytes payment_addr = 16; } @@ -1083,6 +1091,18 @@ message LightningAddress { string host = 2; } +enum CoinSelectionStrategy { + // Use the coin selection strategy defined in the global configuration + // (lnd.conf). + STRATEGY_USE_GLOBAL_CONFIG = 0; + + // Select the largest available coins first during coin selection. + STRATEGY_LARGEST = 1; + + // Randomly select the available coins during coin selection. + STRATEGY_RANDOM = 2; +} + message EstimateFeeRequest { // The map from addresses to amounts for the transaction. map AddrToAmount = 1; @@ -1097,6 +1117,9 @@ message EstimateFeeRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 4; + + // The strategy to use for selecting coins during fees estimation. + CoinSelectionStrategy coin_selection_strategy = 5; } message EstimateFeeResponse { @@ -1137,6 +1160,9 @@ message SendManyRequest { // Whether unconfirmed outputs should be used as inputs for the transaction. bool spend_unconfirmed = 8; + + // The strategy to use for selecting coins during sending many requests. + CoinSelectionStrategy coin_selection_strategy = 9; } message SendManyResponse { // The id of the transaction @@ -1179,6 +1205,9 @@ 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; } message SendCoinsResponse { // The transaction ID of the transaction @@ -1926,12 +1955,16 @@ message GetInfoResponse { /* Whether the current node is connected to testnet. This field is deprecated and the network field should be used instead - **/ + */ bool testnet = 10 [deprecated = true]; reserved 11; - // A list of active chains the node is connected to + /* + A list of active chains the node is connected to. This will only + ever contain a single entry since LND will only ever have a single + chain backend during its lifetime. + */ repeated Chain chains = 16; // The URIs of the current node. @@ -1952,6 +1985,14 @@ message GetInfoResponse { bool store_final_htlc_resolutions = 22; } +message GetDebugInfoRequest { +} + +message GetDebugInfoResponse { + map config = 1; + repeated string log = 2; +} + message GetRecoveryInfoRequest { } message GetRecoveryInfoResponse { @@ -1966,8 +2007,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; @@ -2027,12 +2069,18 @@ message CloseChannelRequest { // // NOTE: This field is only respected if we're the initiator of the channel. uint64 max_fee_per_vbyte = 7; + + // If true, then the rpc call will not block while it awaits a closing txid. + // Consequently this RPC call will not return a closing txid if this value + // is set. + bool no_wait = 8; } message CloseStatusUpdate { oneof update { PendingUpdate close_pending = 1; ChannelCloseUpdate chan_close = 3; + InstantUpdate close_instant = 4; } } @@ -2041,6 +2089,9 @@ message PendingUpdate { uint32 output_index = 2; } +message InstantUpdate { +} + message ReadyForPsbtFunding { /* The P2WSH address of the channel funding multisig address that the below @@ -2085,6 +2136,9 @@ message BatchOpenChannelRequest { // An optional label for the batch transaction, limited to 500 characters. string label = 6; + + // The strategy to use for selecting coins during batch opening channels. + CoinSelectionStrategy coin_selection_strategy = 7; } message BatchOpenChannel { @@ -2608,6 +2662,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 { @@ -2705,6 +2762,10 @@ message PendingChannelsResponse { // The transaction id of the closing transaction string closing_txid = 4; + + // The raw hex encoded bytes of the closing transaction. Included if + // include_raw_tx in the request is true. + string closing_tx_hex = 5; } message Commitments { @@ -2843,6 +2904,11 @@ message WalletBalanceRequest { // The wallet account the balance is shown for. // If this is not specified, the balance of the "default" account is shown. string account = 1; + + // The minimum number of confirmations each one of your outputs used for the + // funding transaction must satisfy. If this is not specified, the default + // value of 1 is used. + int32 min_confs = 2; } message WalletBalanceResponse { @@ -2928,6 +2994,9 @@ message QueryRoutesRequest { not add any additional block padding on top of final_ctlv_delta. This padding of a few blocks needs to be added manually or otherwise failures may happen when a block comes in while the payment is in flight. + + Note: must not be set if making a payment to a blinded path (delta is + set by the aggregate parameters provided by blinded_payment_paths) */ int32 final_cltv_delta = 4; @@ -3001,12 +3070,21 @@ message QueryRoutesRequest { */ repeated lnrpc.RouteHint route_hints = 16; + /* + An optional blinded path(s) to reach the destination. Note that the + introduction node must be provided as the first hop in the route. + */ + repeated BlindedPaymentPath blinded_payment_paths = 19; + /* Features assumed to be supported by the final node. All transitive feature dependencies must also be set properly. For a given feature bit pair, either optional or remote may be set, but not both. If this field is nil or empty, the router will try to load destination features from the graph as a fallback. + + Note: must not be set if making a payment to a blinded route (features + are provided in blinded_payment_paths). */ repeated lnrpc.FeatureBit dest_features = 17; @@ -3112,6 +3190,32 @@ message Hop { // The payment metadata to send along with the payment to the payee. bytes metadata = 13; + + /* + Blinding point is an optional blinding point included for introduction + nodes in blinded paths. This field is mandatory for hops that represents + the introduction point in a blinded path. + */ + bytes blinding_point = 14; + + /* + Encrypted data is a receiver-produced blob of data that provides hops + in a blinded route with forwarding data. As this data is encrypted by + the recipient, we will not be able to parse it - it is essentially an + arbitrary blob of data from our node's perspective. This field is + mandatory for all hops in a blinded path, including the introduction + node. + */ + bytes encrypted_data = 15; + + /* + The total amount that is sent to the recipient (possibly across multiple + HTLCs), as specified by the sender when making a payment to a blinded path. + This value is only set in the final hop payload of a blinded payment. This + value is analogous to the MPPRecord that is used for regular (non-blinded) + MPP payments. + */ + uint64 total_amt_msat = 16; } message MPPRecord { @@ -3119,7 +3223,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; @@ -3249,6 +3354,9 @@ message RoutingPolicy { // Custom channel update tlv records. map custom_records = 8; + + int32 inbound_fee_base_msat = 9; + int32 inbound_fee_rate_milli_msat = 10; } /* @@ -3457,6 +3565,64 @@ message RouteHint { repeated HopHint hop_hints = 1; } +message BlindedPaymentPath { + // The blinded path to send the payment to. + BlindedPath blinded_path = 1; + + // The base fee for the blinded path provided, expressed in msat. + uint64 base_fee_msat = 2; + + /* + The proportional fee for the blinded path provided, expressed in parts + per million. + */ + uint32 proportional_fee_rate = 3; + + /* + The total CLTV delta for the blinded path provided, including the + final CLTV delta for the receiving node. + */ + uint32 total_cltv_delta = 4; + + /* + The minimum hltc size that may be sent over the blinded path, expressed + in msat. + */ + uint64 htlc_min_msat = 5; + + /* + The maximum htlc size that may be sent over the blinded path, expressed + in msat. + */ + uint64 htlc_max_msat = 6; + + // The feature bits for the route. + repeated FeatureBit features = 7; +} + +message BlindedPath { + // The unblinded pubkey of the introduction node for the route. + bytes introduction_node = 1; + + // The ephemeral pubkey used by nodes in the blinded route. + bytes blinding_point = 2; + + /* + A set of blinded node keys and data blobs for the blinded portion of the + route. Note that the first hop is expected to be the introduction node, + so the route is always expected to have at least one hop. + */ + repeated BlindedHop blinded_hops = 3; +} + +message BlindedHop { + // The blinded public key of the node. + bytes blinded_node = 1; + + // An encrypted blob of data provided to the blinded node. + bytes encrypted_data = 2; +} + message AMPInvoiceState { // The state the HTLCs associated with this setID are in. InvoiceHTLCState state = 1; @@ -3643,9 +3809,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; @@ -3750,9 +3917,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; } @@ -3903,10 +4070,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. @@ -4002,11 +4179,11 @@ message ListPaymentsRequest { */ bool count_total_payments = 5; - // If set, returns all invoices with a creation date greater than or equal + // If set, returns all payments with a creation date greater than or equal // to it. Measured in seconds since the unix epoch. uint64 creation_date_start = 6; - // If set, returns all invoices with a creation date less than or equal to + // If set, returns all payments with a creation date less than or equal to // it. Measured in seconds since the unix epoch. uint64 creation_date_end = 7; } @@ -4054,6 +4231,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 { @@ -4130,6 +4311,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; } @@ -4159,7 +4342,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. @@ -4178,6 +4369,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. @@ -4210,7 +4411,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; @@ -4486,6 +4692,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/lnclipb/lncli.proto b/vendor/lnclipb/lncli.proto index f82f653..262869a 100644 --- a/vendor/lnclipb/lncli.proto +++ b/vendor/lnclipb/lncli.proto @@ -1,9 +1,9 @@ syntax = "proto3"; -import "verrpc/verrpc.proto"; - package lnclipb; +import "verrpc/verrpc.proto"; + option go_package = "github.com/lightningnetwork/lnd/lnrpc/lnclipb"; message VersionResponse { diff --git a/vendor/neutrinorpc/neutrino.proto b/vendor/neutrinorpc/neutrino.proto index 950c43b..2f1ad06 100644 --- a/vendor/neutrinorpc/neutrino.proto +++ b/vendor/neutrinorpc/neutrino.proto @@ -4,34 +4,52 @@ package neutrinorpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/neutrinorpc"; +/* + * 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 + */ + // NeutrinoKit is a service that can be used to get information about the // current state of the neutrino instance, fetch blocks and add/remove peers. service NeutrinoKit { - /* + /* lncli: `neutrino status` Status returns the status of the light client neutrino instance, along with height and hash of the best block, and a list of connected peers. */ rpc Status (StatusRequest) returns (StatusResponse); - /* + /* lncli: `neutrino addpeer` AddPeer adds a new peer that has already been connected to the server. */ rpc AddPeer (AddPeerRequest) returns (AddPeerResponse); - /* + /* lncli: `neutrino disconnectpeer` DisconnectPeer disconnects a peer by target address. Both outbound and inbound nodes will be searched for the target node. An error message will be returned if the peer was not found. */ rpc DisconnectPeer (DisconnectPeerRequest) returns (DisconnectPeerResponse); - /* + /* lncli: `neutrino isbanned` IsBanned returns true if the peer is banned, otherwise false. */ rpc IsBanned (IsBannedRequest) returns (IsBannedResponse); - /* + /* lncli: `neutrino getblockheader` GetBlockHeader returns a block header with a particular block hash. */ rpc GetBlockHeader (GetBlockHeaderRequest) returns (GetBlockHeaderResponse); @@ -41,7 +59,7 @@ service NeutrinoKit { */ rpc GetBlock (GetBlockRequest) returns (GetBlockResponse); - /* + /* lncli: `neutrino getcfilter` GetCFilter returns a compact filter from a block. */ rpc GetCFilter (GetCFilterRequest) returns (GetCFilterResponse); diff --git a/vendor/peersrpc/peers.proto b/vendor/peersrpc/peers.proto index 40f2c88..09100c6 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 index d072fb8..f1e26ef 100644 --- a/vendor/routerrpc/router.proto +++ b/vendor/routerrpc/router.proto @@ -1,22 +1,43 @@ syntax = "proto3"; -import "lightning.proto"; - 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. + 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. */ @@ -57,21 +78,21 @@ service Router { */ 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 @@ -80,20 +101,20 @@ service Router { 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 @@ -102,10 +123,14 @@ service Router { 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); @@ -143,7 +168,7 @@ service Router { 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 @@ -164,13 +189,6 @@ message SendPaymentRequest { */ int64 amt = 2; - /* - Number of millisatoshis to send. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt_msat = 12; - // The hash to use within the payment's HTLC bytes payment_hash = 3; @@ -180,9 +198,6 @@ message SendPaymentRequest { */ int32 final_cltv_delta = 4; - // An optional payment addr to be included within the last hop of the route. - bytes payment_addr = 20; - /* 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 @@ -210,17 +225,6 @@ message SendPaymentRequest { */ int64 fee_limit_sat = 7; - /* - 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; - /* 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 @@ -229,19 +233,8 @@ message SendPaymentRequest { uint64 outgoing_chan_id = 8 [jstype = JS_STRING, deprecated = true]; /* - 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; - - /* - The pubkey of the last hop of the route. If empty, any hop may be used. - */ - bytes last_hop_pubkey = 14; - - /* - 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 + 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; @@ -260,6 +253,29 @@ message SendPaymentRequest { */ 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; @@ -284,6 +300,18 @@ message SendPaymentRequest { */ 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 @@ -325,14 +353,39 @@ message TrackPaymentsRequest { message RouteFeeRequest { /* - The destination once wishes to obtain a routing fee quote to. + 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. + 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 { @@ -348,6 +401,12 @@ message RouteFeeResponse { 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 { @@ -634,7 +693,10 @@ message BuildRouteRequest { */ repeated bytes hop_pubkeys = 4; - // An optional payment addr to be included within the last hop of the route. + /* + 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; } diff --git a/vendor/signrpc/signer.proto b/vendor/signrpc/signer.proto index 48d4279..ad43f0d 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 { @@ -475,7 +487,7 @@ message MuSig2CombineKeysRequest { 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; @@ -539,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; diff --git a/vendor/walletrpc/walletkit.proto b/vendor/walletrpc/walletkit.proto index 4564098..aad16df 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,14 +95,14 @@ 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 @@ -96,7 +119,7 @@ service WalletKit { 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 @@ -120,7 +143,7 @@ service WalletKit { 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 @@ -147,7 +170,7 @@ service WalletKit { */ rpc ImportAccount (ImportAccountRequest) returns (ImportAccountResponse); - /* + /* 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 @@ -177,7 +200,7 @@ service WalletKit { 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 @@ -185,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 @@ -199,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 @@ -211,62 +241,75 @@ 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 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. @@ -293,7 +336,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 @@ -477,6 +520,13 @@ message AddressProperty { // 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 { @@ -538,6 +588,11 @@ message ListAddressesResponse { 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. @@ -723,6 +778,7 @@ message Transaction { */ string label = 2; } + message PublishResponse { /* If blank, then no error occurred and the transaction was successfully @@ -734,6 +790,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 @@ -755,6 +816,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 { /* @@ -935,6 +999,91 @@ enum WitnessType { 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 { @@ -959,33 +1108,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. + */ + uint64 budget = 13; + + /* + The deadline height used for this output when perform fee bumping. */ - bool force = 7; + uint32 deadline_height = 14; } message PendingSweepsRequest { @@ -1002,7 +1174,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; /* @@ -1013,19 +1187,40 @@ 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 ListSweepsRequest { @@ -1110,6 +1305,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 { @@ -1143,6 +1358,9 @@ message FundPsbtRequest { // 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 { /* @@ -1157,7 +1375,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; } @@ -1180,6 +1399,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. diff --git a/vendor/walletunlocker.proto b/vendor/walletunlocker.proto index b1ed615..7bcead5 100644 --- a/vendor/walletunlocker.proto +++ b/vendor/walletunlocker.proto @@ -1,9 +1,9 @@ syntax = "proto3"; -import "lightning.proto"; - package lnrpc; +import "lightning.proto"; + option go_package = "github.com/lightningnetwork/lnd/lnrpc"; /* diff --git a/vendor/watchtowerrpc/watchtower.proto b/vendor/watchtowerrpc/watchtower.proto index 3fb8e4e..147617f 100644 --- a/vendor/watchtowerrpc/watchtower.proto +++ b/vendor/watchtowerrpc/watchtower.proto @@ -4,10 +4,28 @@ package watchtowerrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/watchtowerrpc"; +/* + * 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 + */ + // Watchtower is a service that grants access to the watchtower server // functionality of the daemon. service Watchtower { - /* lncli: tower info + /* lncli: `tower info` GetInfo returns general information concerning the companion watchtower including its public key and URIs where the server is currently listening for clients. diff --git a/vendor/wtclientrpc/wtclient.proto b/vendor/wtclientrpc/wtclient.proto index 268583c..cba1bbb 100644 --- a/vendor/wtclientrpc/wtclient.proto +++ b/vendor/wtclientrpc/wtclient.proto @@ -4,10 +4,28 @@ package wtclientrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/wtclientrpc"; +/* + * 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 + */ + // WatchtowerClient is a service that grants access to the watchtower client // functionality of the daemon. service WatchtowerClient { - /* + /* lncli: `wtclient add` AddTower adds a new watchtower reachable at the given address and considers it for new sessions. If the watchtower already exists, then any new addresses included will be considered when dialing it for @@ -15,7 +33,7 @@ service WatchtowerClient { */ rpc AddTower (AddTowerRequest) returns (AddTowerResponse); - /* + /* lncli: `wtclient remove` RemoveTower removes a watchtower from being considered for future session negotiations and from being used for any subsequent backups until it's added again. If an address is provided, then this RPC only serves as a way of @@ -23,16 +41,39 @@ service WatchtowerClient { */ rpc RemoveTower (RemoveTowerRequest) returns (RemoveTowerResponse); - // ListTowers returns the list of watchtowers registered with the client. + /* lncli: `wtclient deactivate` + DeactivateTower sets the given tower's status to inactive so that it + is not considered for session negotiation. Its sessions will also not + be used while the tower is inactive. + */ + rpc DeactivateTower (DeactivateTowerRequest) + returns (DeactivateTowerResponse); + + /* lncli: `wtclient session terminate` + Terminate terminates the given session and marks it as terminal so that + it is not used for backups anymore. + */ + rpc TerminateSession (TerminateSessionRequest) + returns (TerminateSessionResponse); + + /* lncli: `wtclient towers` + ListTowers returns the list of watchtowers registered with the client. + */ rpc ListTowers (ListTowersRequest) returns (ListTowersResponse); - // GetTowerInfo retrieves information for a registered watchtower. + /* lncli: `wtclient tower` + GetTowerInfo retrieves information for a registered watchtower. + */ rpc GetTowerInfo (GetTowerInfoRequest) returns (Tower); - // Stats returns the in-memory statistics of the client since startup. + /* lncli: `wtclient stats` + Stats returns the in-memory statistics of the client since startup. + */ rpc Stats (StatsRequest) returns (StatsResponse); - // Policy returns the active watchtower client policy configuration. + /* lncli: `wtclient policy` + Policy returns the active watchtower client policy configuration. + */ rpc Policy (PolicyRequest) returns (PolicyResponse); } @@ -62,6 +103,26 @@ message RemoveTowerRequest { message RemoveTowerResponse { } +message DeactivateTowerRequest { + // The identifying public key of the watchtower to deactivate. + bytes pubkey = 1; +} + +message DeactivateTowerResponse { + // A string describing the action that took place. + string status = 1; +} + +message TerminateSessionRequest { + // The ID of the session that should be terminated. + bytes session_id = 1; +} + +message TerminateSessionResponse { + // A string describing the action that took place. + string status = 1; +} + message GetTowerInfoRequest { // The identifying public key of the watchtower to retrieve information for. bytes pubkey = 1; @@ -102,6 +163,11 @@ message TowerSession { the justice transaction in the event of a channel breach. */ uint32 sweep_sat_per_vbyte = 5; + + /* + The ID of the session. + */ + bytes id = 6; } message Tower { @@ -193,6 +259,9 @@ enum PolicyType { // Selects the policy from the anchor tower client. ANCHOR = 1; + + // Selects the policy from the taproot tower client. + TAPROOT = 2; } message PolicyRequest {