lightning 10.7.0 → 10.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Versions
2
2
 
3
- ## 10.7.0
3
+ ## 10.7.1
4
4
 
5
5
  - `getPendingChannels`: Add support for `close_transaction` to return raw tx
6
6
 
@@ -1,11 +1,29 @@
1
1
  syntax = "proto3";
2
2
 
3
- import "lightning.proto";
4
-
5
3
  package invoicesrpc;
6
4
 
5
+ import "lightning.proto";
6
+
7
7
  option go_package = "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc";
8
8
 
9
+ /*
10
+ * Comments in this file will be directly parsed into the API
11
+ * Documentation as descriptions of the associated method, message, or field.
12
+ * These descriptions should go right above the definition of the object, and
13
+ * can be in either block or // comment format.
14
+ *
15
+ * An RPC method can be matched to an lncli command by placing a line in the
16
+ * beginning of the description in exactly the following format:
17
+ * lncli: `methodname`
18
+ *
19
+ * Failure to specify the exact name of the command will cause documentation
20
+ * generation to fail.
21
+ *
22
+ * More information on how exactly the gRPC documentation is generated from
23
+ * this proto file can be found here:
24
+ * https://github.com/lightninglabs/lightning-api
25
+ */
26
+
9
27
  // Invoices is a service that can be used to create, accept, settle and cancel
10
28
  // invoices.
11
29
  service Invoices {
@@ -17,20 +35,20 @@ service Invoices {
17
35
  rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest)
18
36
  returns (stream lnrpc.Invoice);
19
37
 
20
- /*
38
+ /* lncli: `cancelinvoice`
21
39
  CancelInvoice cancels a currently open invoice. If the invoice is already
22
40
  canceled, this call will succeed. If the invoice is already settled, it will
23
41
  fail.
24
42
  */
25
43
  rpc CancelInvoice (CancelInvoiceMsg) returns (CancelInvoiceResp);
26
44
 
27
- /*
45
+ /* lncli: `addholdinvoice`
28
46
  AddHoldInvoice creates a hold invoice. It ties the invoice to the hash
29
47
  supplied in the request.
30
48
  */
31
49
  rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp);
32
50
 
33
- /*
51
+ /* lncli: `settleinvoice`
34
52
  SettleInvoice settles an accepted invoice. If the invoice is already
35
53
  settled, this call will succeed.
36
54
  */
@@ -120,8 +138,9 @@ message AddHoldInvoiceResp {
120
138
  uint64 add_index = 2;
121
139
 
122
140
  /*
123
- The payment address of the generated invoice. This value should be used
124
- in all payments for this invoice as we require it for end to end
141
+ The payment address of the generated invoice. This is also called
142
+ the payment secret in specifications (e.g. BOLT 11). This value should
143
+ be used in all payments for this invoice as we require it for end to end
125
144
  security.
126
145
  */
127
146
  bytes payment_addr = 3;
@@ -1940,10 +1940,11 @@ message GetInfoResponse {
1940
1940
  reserved 11;
1941
1941
 
1942
1942
  /*
1943
- Deprecated. The only active chain is bitcoin.
1944
- A list of active chains the node is connected to
1943
+ A list of active chains the node is connected to. This will only
1944
+ ever contain a single entry since LND will only ever have a single
1945
+ chain backend during its lifetime.
1945
1946
  */
1946
- repeated Chain chains = 16 [deprecated = true];
1947
+ repeated Chain chains = 16;
1947
1948
 
1948
1949
  // The URIs of the current node.
1949
1950
  repeated string uris = 12;
@@ -1,9 +1,9 @@
1
1
  syntax = "proto3";
2
2
 
3
- import "lightning.proto";
4
-
5
3
  package peersrpc;
6
4
 
5
+ import "lightning.proto";
6
+
7
7
  option go_package = "github.com/lightningnetwork/lnd/lnrpc/peersrpc";
8
8
 
9
9
  // Peers is a service that can be used to get information and interact
@@ -1,22 +1,43 @@
1
1
  syntax = "proto3";
2
2
 
3
- import "lightning.proto";
4
-
5
3
  package routerrpc;
6
4
 
5
+ import "lightning.proto";
6
+
7
7
  option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";
8
8
 
9
+ /*
10
+ * Comments in this file will be directly parsed into the API
11
+ * Documentation as descriptions of the associated method, message, or field.
12
+ * These descriptions should go right above the definition of the object, and
13
+ * can be in either block or // comment format.
14
+ *
15
+ * An RPC method can be matched to an lncli command by placing a line in the
16
+ * beginning of the description in exactly the following format:
17
+ * lncli: `methodname`
18
+ *
19
+ * Failure to specify the exact name of the command will cause documentation
20
+ * generation to fail.
21
+ *
22
+ * More information on how exactly the gRPC documentation is generated from
23
+ * this proto file can be found here:
24
+ * https://github.com/lightninglabs/lightning-api
25
+ */
26
+
9
27
  // Router is a service that offers advanced interaction with the router
10
28
  // subsystem of the daemon.
11
29
  service Router {
12
30
  /*
13
31
  SendPaymentV2 attempts to route a payment described by the passed
14
32
  PaymentRequest to the final destination. The call returns a stream of
15
- payment updates.
33
+ payment updates. When using this RPC, make sure to set a fee limit, as the
34
+ default routing fee limit is 0 sats. Without a non-zero fee limit only
35
+ routes without fees will be attempted which often fails with
36
+ FAILURE_REASON_NO_ROUTE.
16
37
  */
17
38
  rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment);
18
39
 
19
- /*
40
+ /* lncli: `trackpayment`
20
41
  TrackPaymentV2 returns an update stream for the payment identified by the
21
42
  payment hash.
22
43
  */
@@ -57,21 +78,21 @@ service Router {
57
78
  */
58
79
  rpc SendToRouteV2 (SendToRouteRequest) returns (lnrpc.HTLCAttempt);
59
80
 
60
- /*
81
+ /* lncli: `resetmc`
61
82
  ResetMissionControl clears all mission control state and starts with a clean
62
83
  slate.
63
84
  */
64
85
  rpc ResetMissionControl (ResetMissionControlRequest)
65
86
  returns (ResetMissionControlResponse);
66
87
 
67
- /*
88
+ /* lncli: `querymc`
68
89
  QueryMissionControl exposes the internal mission control state to callers.
69
90
  It is a development feature.
70
91
  */
71
92
  rpc QueryMissionControl (QueryMissionControlRequest)
72
93
  returns (QueryMissionControlResponse);
73
94
 
74
- /*
95
+ /* lncli: `importmc`
75
96
  XImportMissionControl is an experimental API that imports the state provided
76
97
  to the internal mission control's state, using all results which are more
77
98
  recent than our existing values. These values will only be imported
@@ -80,20 +101,20 @@ service Router {
80
101
  rpc XImportMissionControl (XImportMissionControlRequest)
81
102
  returns (XImportMissionControlResponse);
82
103
 
83
- /*
104
+ /* lncli: `getmccfg`
84
105
  GetMissionControlConfig returns mission control's current config.
85
106
  */
86
107
  rpc GetMissionControlConfig (GetMissionControlConfigRequest)
87
108
  returns (GetMissionControlConfigResponse);
88
109
 
89
- /*
110
+ /* lncli: `setmccfg`
90
111
  SetMissionControlConfig will set mission control's config, if the config
91
112
  provided is valid.
92
113
  */
93
114
  rpc SetMissionControlConfig (SetMissionControlConfigRequest)
94
115
  returns (SetMissionControlConfigResponse);
95
116
 
96
- /*
117
+ /* lncli: `queryprob`
97
118
  Deprecated. QueryProbability returns the current success probability
98
119
  estimate for a given node pair and amount. The call returns a zero success
99
120
  probability if no channel is available or if the amount violates min/max
@@ -102,10 +123,14 @@ service Router {
102
123
  rpc QueryProbability (QueryProbabilityRequest)
103
124
  returns (QueryProbabilityResponse);
104
125
 
105
- /*
126
+ /* lncli: `buildroute`
106
127
  BuildRoute builds a fully specified route based on a list of hop public
107
128
  keys. It retrieves the relevant channel policies from the graph in order to
108
129
  calculate the correct fees and time locks.
130
+ Note that LND will use its default final_cltv_delta if no value is supplied.
131
+ Make sure to add the correct final_cltv_delta depending on the invoice
132
+ restriction. Moreover the caller has to make sure to provide the
133
+ payment_addr if the route is paying an invoice which signaled it.
109
134
  */
110
135
  rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse);
111
136
 
@@ -143,7 +168,7 @@ service Router {
143
168
  rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse)
144
169
  returns (stream ForwardHtlcInterceptRequest);
145
170
 
146
- /*
171
+ /* lncli: `updatechanstatus`
147
172
  UpdateChanStatus attempts to manually set the state of a channel
148
173
  (enabled, disabled, or auto). A manual "disable" request will cause the
149
174
  channel to stay disabled until a subsequent manual request of either
@@ -164,13 +189,6 @@ message SendPaymentRequest {
164
189
  */
165
190
  int64 amt = 2;
166
191
 
167
- /*
168
- Number of millisatoshis to send.
169
-
170
- The fields amt and amt_msat are mutually exclusive.
171
- */
172
- int64 amt_msat = 12;
173
-
174
192
  // The hash to use within the payment's HTLC
175
193
  bytes payment_hash = 3;
176
194
 
@@ -180,9 +198,6 @@ message SendPaymentRequest {
180
198
  */
181
199
  int32 final_cltv_delta = 4;
182
200
 
183
- // An optional payment addr to be included within the last hop of the route.
184
- bytes payment_addr = 20;
185
-
186
201
  /*
187
202
  A bare-bones invoice for a payment within the Lightning Network. With the
188
203
  details of the invoice, the sender has all the data necessary to send a
@@ -210,17 +225,6 @@ message SendPaymentRequest {
210
225
  */
211
226
  int64 fee_limit_sat = 7;
212
227
 
213
- /*
214
- The maximum number of millisatoshis that will be paid as a fee of the
215
- payment. If this field is left to the default value of 0, only zero-fee
216
- routes will be considered. This usually means single hop routes connecting
217
- directly to the destination. To send the payment without a fee limit, use
218
- max int here.
219
-
220
- The fields fee_limit_sat and fee_limit_msat are mutually exclusive.
221
- */
222
- int64 fee_limit_msat = 13;
223
-
224
228
  /*
225
229
  Deprecated, use outgoing_chan_ids. The channel id of the channel that must
226
230
  be taken to the first hop. If zero, any channel may be used (unless
@@ -229,19 +233,8 @@ message SendPaymentRequest {
229
233
  uint64 outgoing_chan_id = 8 [jstype = JS_STRING, deprecated = true];
230
234
 
231
235
  /*
232
- The channel ids of the channels are allowed for the first hop. If empty,
233
- any channel may be used.
234
- */
235
- repeated uint64 outgoing_chan_ids = 19;
236
-
237
- /*
238
- The pubkey of the last hop of the route. If empty, any hop may be used.
239
- */
240
- bytes last_hop_pubkey = 14;
241
-
242
- /*
243
- An optional maximum total time lock for the route. This should not exceed
244
- lnd's `--max-cltv-expiry` setting. If zero, then the value of
236
+ An optional maximum total time lock for the route. This should not
237
+ exceed lnd's `--max-cltv-expiry` setting. If zero, then the value of
245
238
  `--max-cltv-expiry` is enforced.
246
239
  */
247
240
  int32 cltv_limit = 9;
@@ -260,6 +253,29 @@ message SendPaymentRequest {
260
253
  */
261
254
  map<uint64, bytes> dest_custom_records = 11;
262
255
 
256
+ /*
257
+ Number of millisatoshis to send.
258
+
259
+ The fields amt and amt_msat are mutually exclusive.
260
+ */
261
+ int64 amt_msat = 12;
262
+
263
+ /*
264
+ The maximum number of millisatoshis that will be paid as a fee of the
265
+ payment. If this field is left to the default value of 0, only zero-fee
266
+ routes will be considered. This usually means single hop routes connecting
267
+ directly to the destination. To send the payment without a fee limit, use
268
+ max int here.
269
+
270
+ The fields fee_limit_sat and fee_limit_msat are mutually exclusive.
271
+ */
272
+ int64 fee_limit_msat = 13;
273
+
274
+ /*
275
+ The pubkey of the last hop of the route. If empty, any hop may be used.
276
+ */
277
+ bytes last_hop_pubkey = 14;
278
+
263
279
  // If set, circular payments to self are permitted.
264
280
  bool allow_self_payment = 15;
265
281
 
@@ -284,6 +300,18 @@ message SendPaymentRequest {
284
300
  */
285
301
  bool no_inflight_updates = 18;
286
302
 
303
+ /*
304
+ The channel ids of the channels are allowed for the first hop. If empty,
305
+ any channel may be used.
306
+ */
307
+ repeated uint64 outgoing_chan_ids = 19;
308
+
309
+ /*
310
+ An optional payment addr to be included within the last hop of the route.
311
+ This is also called payment secret in specifications (e.g. BOLT 11).
312
+ */
313
+ bytes payment_addr = 20;
314
+
287
315
  /*
288
316
  The largest payment split that should be attempted when making a payment if
289
317
  splitting is necessary. Setting this value will effectively cause lnd to
@@ -325,14 +353,39 @@ message TrackPaymentsRequest {
325
353
 
326
354
  message RouteFeeRequest {
327
355
  /*
328
- The destination once wishes to obtain a routing fee quote to.
356
+ The destination one wishes to obtain a routing fee quote to. If set, this
357
+ parameter requires the amt_sat parameter also to be set. This parameter
358
+ combination triggers a graph based routing fee estimation as opposed to a
359
+ payment probe based estimate in case a payment request is provided. The
360
+ graph based estimation is an algorithm that is executed on the in memory
361
+ graph. Hence its runtime is significantly shorter than a payment probe
362
+ estimation that sends out actual payments to the network.
329
363
  */
330
364
  bytes dest = 1;
331
365
 
332
366
  /*
333
- The amount one wishes to send to the target destination.
367
+ The amount one wishes to send to the target destination. It is only to be
368
+ used in combination with the dest parameter.
334
369
  */
335
370
  int64 amt_sat = 2;
371
+
372
+ /*
373
+ A payment request of the target node that the route fee request is intended
374
+ for. Its parameters are input to probe payments that estimate routing fees.
375
+ The timeout parameter can be specified to set a maximum time on the probing
376
+ attempt. Cannot be used in combination with dest and amt_sat.
377
+ */
378
+ string payment_request = 3;
379
+
380
+ /*
381
+ A user preference of how long a probe payment should maximally be allowed to
382
+ take, denoted in seconds. The probing payment loop is aborted if this
383
+ timeout is reached. Note that the probing process itself can take longer
384
+ than the timeout if the HTLC becomes delayed or stuck. Canceling the context
385
+ of this call will not cancel the payment loop, the duration is only
386
+ controlled by the timeout parameter.
387
+ */
388
+ uint32 timeout = 4;
336
389
  }
337
390
 
338
391
  message RouteFeeResponse {
@@ -348,6 +401,12 @@ message RouteFeeResponse {
348
401
  value.
349
402
  */
350
403
  int64 time_lock_delay = 2;
404
+
405
+ /*
406
+ An indication whether a probing payment succeeded or whether and why it
407
+ failed. FAILURE_REASON_NONE indicates success.
408
+ */
409
+ lnrpc.PaymentFailureReason failure_reason = 5;
351
410
  }
352
411
 
353
412
  message SendToRouteRequest {
@@ -634,7 +693,10 @@ message BuildRouteRequest {
634
693
  */
635
694
  repeated bytes hop_pubkeys = 4;
636
695
 
637
- // An optional payment addr to be included within the last hop of the route.
696
+ /*
697
+ An optional payment addr to be included within the last hop of the route.
698
+ This is also called payment secret in specifications (e.g. BOLT 11).
699
+ */
638
700
  bytes payment_addr = 5;
639
701
  }
640
702
 
@@ -349,6 +349,12 @@ message SignMessageReq {
349
349
  privKey + h_tapTweak(internalKey || tapTweak)
350
350
  */
351
351
  bytes schnorr_sig_tap_tweak = 6;
352
+
353
+ /*
354
+ An optional tag that can be provided when taking a tagged hash of a
355
+ message. This option can only be used when schnorr_sig is true.
356
+ */
357
+ bytes tag = 7;
352
358
  }
353
359
  message SignMessageResp {
354
360
  /*
@@ -380,6 +386,12 @@ message VerifyMessageReq {
380
386
  Specifies if the signature is a Schnorr signature.
381
387
  */
382
388
  bool is_schnorr_sig = 4;
389
+
390
+ /*
391
+ An optional tag that can be provided when taking a tagged hash of a
392
+ message. This option can only be used when is_schnorr_sig is true.
393
+ */
394
+ bytes tag = 5;
383
395
  }
384
396
 
385
397
  message VerifyMessageResp {
@@ -475,7 +487,7 @@ message MuSig2CombineKeysRequest {
475
487
  repeated bytes all_signer_pubkeys = 1;
476
488
 
477
489
  /*
478
- A series of optional generic tweaks to be applied to the the aggregated
490
+ A series of optional generic tweaks to be applied to the aggregated
479
491
  public key.
480
492
  */
481
493
  repeated TweakDesc tweaks = 2;
@@ -539,7 +551,7 @@ message MuSig2SessionRequest {
539
551
  repeated bytes other_signer_public_nonces = 3;
540
552
 
541
553
  /*
542
- A series of optional generic tweaks to be applied to the the aggregated
554
+ A series of optional generic tweaks to be applied to the aggregated
543
555
  public key.
544
556
  */
545
557
  repeated TweakDesc tweaks = 4;
@@ -558,6 +570,16 @@ message MuSig2SessionRequest {
558
570
  combined key and nonces are created.
559
571
  */
560
572
  MuSig2Version version = 6;
573
+
574
+ /*
575
+ A set of pre generated secret local nonces to use in the musig2 session.
576
+ This field is optional. This can be useful for protocols that need to send
577
+ nonces ahead of time before the set of signer keys are known. This value
578
+ MUST be 97 bytes and be the concatenation of two CSPRNG generated 32 byte
579
+ values and local public key used for signing as specified in the key_loc
580
+ field.
581
+ */
582
+ bytes pregenerated_local_nonce = 7;
561
583
  }
562
584
 
563
585
  message MuSig2SessionResponse {
@@ -288,15 +288,25 @@ service WalletKit {
288
288
 
289
289
  /* lncli: `wallet psbt fund`
290
290
  FundPsbt creates a fully populated PSBT that contains enough inputs to fund
291
- the outputs specified in the template. There are two ways of specifying a
292
- template: Either by passing in a PSBT with at least one output declared or
293
- by passing in a raw TxTemplate message.
294
-
295
- If there are no inputs specified in the template, coin selection is
296
- performed automatically. If the template does contain any inputs, it is
297
- assumed that full coin selection happened externally and no additional
298
- inputs are added. If the specified inputs aren't enough to fund the outputs
299
- with the given fee rate, an error is returned.
291
+ the outputs specified in the template. There are three ways a user can
292
+ specify what we call the template (a list of inputs and outputs to use in
293
+ the PSBT): Either as a PSBT packet directly with no coin selection (using
294
+ the legacy "psbt" field), a PSBT with advanced coin selection support (using
295
+ the new "coin_select" field) or as a raw RPC message (using the "raw"
296
+ field).
297
+ The legacy "psbt" and "raw" modes, the following restrictions apply:
298
+ 1. If there are no inputs specified in the template, coin selection is
299
+ performed automatically.
300
+ 2. If the template does contain any inputs, it is assumed that full
301
+ coin selection happened externally and no additional inputs are added. If
302
+ the specified inputs aren't enough to fund the outputs with the given fee
303
+ rate, an error is returned.
304
+
305
+ The new "coin_select" mode does not have these restrictions and allows the
306
+ user to specify a PSBT with inputs and outputs and still perform coin
307
+ selection on top of that.
308
+ For all modes this RPC requires any inputs that are specified to be locked
309
+ by the user (if they belong to this node in the first place).
300
310
 
301
311
  After either selecting or verifying the inputs, all input UTXOs are locked
302
312
  with an internal app ID.
@@ -507,6 +517,13 @@ message AddressProperty {
507
517
 
508
518
  // The balance of the address.
509
519
  int64 balance = 3;
520
+
521
+ // The full derivation path of the address. This will be empty for imported
522
+ // addresses.
523
+ string derivation_path = 4;
524
+
525
+ // The public key of the address. This will be empty for imported addresses.
526
+ bytes public_key = 5;
510
527
  }
511
528
 
512
529
  message AccountWithAddresses {
@@ -1238,6 +1255,26 @@ message FundPsbtRequest {
1238
1255
  Use the outputs and optional inputs from this raw template.
1239
1256
  */
1240
1257
  TxTemplate raw = 2;
1258
+
1259
+ /*
1260
+ Use an existing PSBT packet as the template for the funded PSBT.
1261
+
1262
+ The difference to the pure PSBT template above is that coin selection is
1263
+ performed even if inputs are specified. The output amounts are summed up
1264
+ and used as the target amount for coin selection. A change output must
1265
+ either already exist in the PSBT and be marked as such, otherwise a new
1266
+ change output of the specified output type will be added. Any inputs
1267
+ already specified in the PSBT must already be locked (if they belong to
1268
+ this node), only newly added inputs will be locked by this RPC.
1269
+
1270
+ In case the sum of the already provided inputs exceeds the required
1271
+ output amount, no new coins are selected. Instead only the fee and
1272
+ change amount calculation is performed (e.g. a change output is added if
1273
+ requested or the change is added to the specified existing change
1274
+ output, given there is any non-dust change). This can be identified by
1275
+ the returned locked UTXOs being empty.
1276
+ */
1277
+ PsbtCoinSelect coin_select = 9;
1241
1278
  }
1242
1279
 
1243
1280
  oneof fees {
@@ -1285,7 +1322,8 @@ message FundPsbtResponse {
1285
1322
 
1286
1323
  /*
1287
1324
  The list of lock leases that were acquired for the inputs in the funded PSBT
1288
- packet.
1325
+ packet. Only inputs added to the PSBT by this RPC are locked, inputs that
1326
+ were already present in the PSBT are not locked.
1289
1327
  */
1290
1328
  repeated UtxoLease locked_utxos = 3;
1291
1329
  }
@@ -1308,6 +1346,38 @@ message TxTemplate {
1308
1346
  map<string, uint64> outputs = 2;
1309
1347
  }
1310
1348
 
1349
+ message PsbtCoinSelect {
1350
+ /*
1351
+ The template to use for the funded PSBT. The template must contain at least
1352
+ one non-dust output. The amount to be funded is calculated by summing up the
1353
+ amounts of all outputs in the template, subtracting all the input values of
1354
+ the already specified inputs. The change value is added to the output that
1355
+ is marked as such (or a new change output is added if none is marked). For
1356
+ the input amount calculation to be correct, the template must have the
1357
+ WitnessUtxo field set for all inputs. Any inputs already specified in the
1358
+ PSBT must already be locked (if they belong to this node), only newly added
1359
+ inputs will be locked by this RPC.
1360
+ */
1361
+ bytes psbt = 1;
1362
+
1363
+ oneof change_output {
1364
+ /*
1365
+ Use the existing output within the template PSBT with the specified
1366
+ index as the change output. Any leftover change will be added to the
1367
+ already specified amount of that output. To add a new change output to
1368
+ the PSBT, set the "add" field below instead. The type of change output
1369
+ added is defined by change_type in the parent message.
1370
+ */
1371
+ int32 existing_output_index = 2;
1372
+
1373
+ /*
1374
+ Add a new change output to the PSBT using the change_type specified in
1375
+ the parent message.
1376
+ */
1377
+ bool add = 3;
1378
+ }
1379
+ }
1380
+
1311
1381
  message UtxoLease {
1312
1382
  /*
1313
1383
  A 32 byte random ID that identifies the lease.
@@ -4,10 +4,28 @@ package wtclientrpc;
4
4
 
5
5
  option go_package = "github.com/lightningnetwork/lnd/lnrpc/wtclientrpc";
6
6
 
7
+ /*
8
+ * Comments in this file will be directly parsed into the API
9
+ * Documentation as descriptions of the associated method, message, or field.
10
+ * These descriptions should go right above the definition of the object, and
11
+ * can be in either block or // comment format.
12
+ *
13
+ * An RPC method can be matched to an lncli command by placing a line in the
14
+ * beginning of the description in exactly the following format:
15
+ * lncli: `methodname`
16
+ *
17
+ * Failure to specify the exact name of the command will cause documentation
18
+ * generation to fail.
19
+ *
20
+ * More information on how exactly the gRPC documentation is generated from
21
+ * this proto file can be found here:
22
+ * https://github.com/lightninglabs/lightning-api
23
+ */
24
+
7
25
  // WatchtowerClient is a service that grants access to the watchtower client
8
26
  // functionality of the daemon.
9
27
  service WatchtowerClient {
10
- /*
28
+ /* lncli: `wtclient add`
11
29
  AddTower adds a new watchtower reachable at the given address and
12
30
  considers it for new sessions. If the watchtower already exists, then
13
31
  any new addresses included will be considered when dialing it for
@@ -15,7 +33,7 @@ service WatchtowerClient {
15
33
  */
16
34
  rpc AddTower (AddTowerRequest) returns (AddTowerResponse);
17
35
 
18
- /*
36
+ /* lncli: `wtclient remove`
19
37
  RemoveTower removes a watchtower from being considered for future session
20
38
  negotiations and from being used for any subsequent backups until it's added
21
39
  again. If an address is provided, then this RPC only serves as a way of
@@ -23,16 +41,39 @@ service WatchtowerClient {
23
41
  */
24
42
  rpc RemoveTower (RemoveTowerRequest) returns (RemoveTowerResponse);
25
43
 
26
- // ListTowers returns the list of watchtowers registered with the client.
44
+ /* lncli: `wtclient deactivate`
45
+ DeactivateTower sets the given tower's status to inactive so that it
46
+ is not considered for session negotiation. Its sessions will also not
47
+ be used while the tower is inactive.
48
+ */
49
+ rpc DeactivateTower (DeactivateTowerRequest)
50
+ returns (DeactivateTowerResponse);
51
+
52
+ /* lncli: `wtclient session terminate`
53
+ Terminate terminates the given session and marks it as terminal so that
54
+ it is not used for backups anymore.
55
+ */
56
+ rpc TerminateSession (TerminateSessionRequest)
57
+ returns (TerminateSessionResponse);
58
+
59
+ /* lncli: `wtclient towers`
60
+ ListTowers returns the list of watchtowers registered with the client.
61
+ */
27
62
  rpc ListTowers (ListTowersRequest) returns (ListTowersResponse);
28
63
 
29
- // GetTowerInfo retrieves information for a registered watchtower.
64
+ /* lncli: `wtclient tower`
65
+ GetTowerInfo retrieves information for a registered watchtower.
66
+ */
30
67
  rpc GetTowerInfo (GetTowerInfoRequest) returns (Tower);
31
68
 
32
- // Stats returns the in-memory statistics of the client since startup.
69
+ /* lncli: `wtclient stats`
70
+ Stats returns the in-memory statistics of the client since startup.
71
+ */
33
72
  rpc Stats (StatsRequest) returns (StatsResponse);
34
73
 
35
- // Policy returns the active watchtower client policy configuration.
74
+ /* lncli: `wtclient policy`
75
+ Policy returns the active watchtower client policy configuration.
76
+ */
36
77
  rpc Policy (PolicyRequest) returns (PolicyResponse);
37
78
  }
38
79
 
@@ -62,6 +103,26 @@ message RemoveTowerRequest {
62
103
  message RemoveTowerResponse {
63
104
  }
64
105
 
106
+ message DeactivateTowerRequest {
107
+ // The identifying public key of the watchtower to deactivate.
108
+ bytes pubkey = 1;
109
+ }
110
+
111
+ message DeactivateTowerResponse {
112
+ // A string describing the action that took place.
113
+ string status = 1;
114
+ }
115
+
116
+ message TerminateSessionRequest {
117
+ // The ID of the session that should be terminated.
118
+ bytes session_id = 1;
119
+ }
120
+
121
+ message TerminateSessionResponse {
122
+ // A string describing the action that took place.
123
+ string status = 1;
124
+ }
125
+
65
126
  message GetTowerInfoRequest {
66
127
  // The identifying public key of the watchtower to retrieve information for.
67
128
  bytes pubkey = 1;
@@ -102,6 +163,11 @@ message TowerSession {
102
163
  the justice transaction in the event of a channel breach.
103
164
  */
104
165
  uint32 sweep_sat_per_vbyte = 5;
166
+
167
+ /*
168
+ The ID of the session.
169
+ */
170
+ bytes id = 6;
105
171
  }
106
172
 
107
173
  message Tower {
package/package.json CHANGED
@@ -9,7 +9,7 @@
9
9
  "dependencies": {
10
10
  "@grpc/grpc-js": "1.10.2",
11
11
  "@grpc/proto-loader": "0.7.10",
12
- "@types/node": "20.11.25",
12
+ "@types/node": "20.11.27",
13
13
  "@types/request": "2.48.12",
14
14
  "@types/ws": "8.5.10",
15
15
  "async": "3.2.5",
@@ -53,5 +53,5 @@
53
53
  "directory": "test/typescript"
54
54
  },
55
55
  "types": "index.d.ts",
56
- "version": "10.7.0"
56
+ "version": "10.7.1"
57
57
  }