/
lightning.proto
4998 lines (4098 loc) · 156 KB
/
lightning.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
syntax = "proto3";
package lnrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc";
/*
* 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
*/
// Lightning is the main RPC server of the daemon.
service Lightning {
/* lncli: `walletbalance`
WalletBalance returns total unspent outputs(confirmed and unconfirmed), all
confirmed unspent outputs and all unconfirmed unspent outputs under control
of the wallet.
*/
rpc WalletBalance (WalletBalanceRequest) returns (WalletBalanceResponse);
/* lncli: `channelbalance`
ChannelBalance returns a report on the total funds across all open channels,
categorized in local/remote, pending local/remote and unsettled local/remote
balances.
*/
rpc ChannelBalance (ChannelBalanceRequest) returns (ChannelBalanceResponse);
/* lncli: `listchaintxns`
GetTransactions returns a list describing all the known transactions
relevant to the wallet.
*/
rpc GetTransactions (GetTransactionsRequest) returns (TransactionDetails);
/* lncli: `estimatefee`
EstimateFee asks the chain backend to estimate the fee rate and total fees
for a transaction that pays to multiple specified outputs.
When using REST, the `AddrToAmount` map type can be set by appending
`&AddrToAmount[<address>]=<amount_to_send>` to the URL. Unfortunately this
map type doesn't appear in the REST API documentation because of a bug in
the grpc-gateway library.
*/
rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse);
/* lncli: `sendcoins`
SendCoins executes a request to send coins to a particular address. Unlike
SendMany, this RPC call only allows creating a single output at a time. If
neither target_conf, or sat_per_vbyte are set, then the internal wallet will
consult its fee model to determine a fee for the default confirmation
target.
*/
rpc SendCoins (SendCoinsRequest) returns (SendCoinsResponse);
/* lncli: `listunspent`
Deprecated, use walletrpc.ListUnspent instead.
ListUnspent returns a list of all utxos spendable by the wallet with a
number of confirmations between the specified minimum and maximum.
*/
rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse);
/*
SubscribeTransactions creates a uni-directional stream from the server to
the client in which any newly discovered transactions relevant to the
wallet are sent over.
*/
rpc SubscribeTransactions (GetTransactionsRequest)
returns (stream Transaction);
/* lncli: `sendmany`
SendMany handles a request for a transaction that creates multiple specified
outputs in parallel. If neither target_conf, or sat_per_vbyte are set, then
the internal wallet will consult its fee model to determine a fee for the
default confirmation target.
*/
rpc SendMany (SendManyRequest) returns (SendManyResponse);
/* lncli: `newaddress`
NewAddress creates a new address under control of the local wallet.
*/
rpc NewAddress (NewAddressRequest) returns (NewAddressResponse);
/* lncli: `signmessage`
SignMessage signs a message with this node's private key. The returned
signature string is `zbase32` encoded and pubkey recoverable, meaning that
only the message digest and signature are needed for verification.
*/
rpc SignMessage (SignMessageRequest) returns (SignMessageResponse);
/* lncli: `verifymessage`
VerifyMessage verifies a signature over a message and recovers the signer's
public key. The signature is only deemed valid if the recovered public key
corresponds to a node key in the public Lightning network. The signature
must be zbase32 encoded and signed by an active node in the resident node's
channel database. In addition to returning the validity of the signature,
VerifyMessage also returns the recovered pubkey from the signature.
*/
rpc VerifyMessage (VerifyMessageRequest) returns (VerifyMessageResponse);
/* lncli: `connect`
ConnectPeer attempts to establish a connection to a remote peer. This is at
the networking level, and is used for communication between nodes. This is
distinct from establishing a channel with a peer.
*/
rpc ConnectPeer (ConnectPeerRequest) returns (ConnectPeerResponse);
/* lncli: `disconnect`
DisconnectPeer attempts to disconnect one peer from another identified by a
given pubKey. In the case that we currently have a pending or active channel
with the target peer, then this action will be not be allowed.
*/
rpc DisconnectPeer (DisconnectPeerRequest) returns (DisconnectPeerResponse);
/* lncli: `listpeers`
ListPeers returns a verbose listing of all currently active peers.
*/
rpc ListPeers (ListPeersRequest) returns (ListPeersResponse);
/*
SubscribePeerEvents creates a uni-directional stream from the server to
the client in which any events relevant to the state of peers are sent
over. Events include peers going online and offline.
*/
rpc SubscribePeerEvents (PeerEventSubscription) returns (stream PeerEvent);
/* lncli: `getinfo`
GetInfo returns general information concerning the lightning node including
it's identity pubkey, alias, the chains it is connected to, and information
concerning the number of open+pending channels.
*/
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
progress made so far.
*/
rpc GetRecoveryInfo (GetRecoveryInfoRequest)
returns (GetRecoveryInfoResponse);
// TODO(roasbeef): merge with below with bool?
/* lncli: `pendingchannels`
PendingChannels returns a list of all the channels that are currently
considered "pending". A channel is pending if it has finished the funding
workflow and is waiting for confirmations for the funding txn, or is in the
process of closure, either initiated cooperatively or non-cooperatively.
*/
rpc PendingChannels (PendingChannelsRequest)
returns (PendingChannelsResponse);
/* lncli: `listchannels`
ListChannels returns a description of all the open channels that this node
is a participant in.
*/
rpc ListChannels (ListChannelsRequest) returns (ListChannelsResponse);
/*
SubscribeChannelEvents creates a uni-directional stream from the server to
the client in which any updates relevant to the state of the channels are
sent over. Events include new active channels, inactive channels, and closed
channels.
*/
rpc SubscribeChannelEvents (ChannelEventSubscription)
returns (stream ChannelEventUpdate);
/* lncli: `closedchannels`
ClosedChannels returns a description of all the closed channels that
this node was a participant in.
*/
rpc ClosedChannels (ClosedChannelsRequest) returns (ClosedChannelsResponse);
/*
OpenChannelSync is a synchronous version of the OpenChannel RPC call. This
call is meant to be consumed by clients to the REST proxy. As with all
other sync calls, all byte slices are intended to be populated as hex
encoded strings.
*/
rpc OpenChannelSync (OpenChannelRequest) returns (ChannelPoint);
/* lncli: `openchannel`
OpenChannel attempts to open a singly funded channel specified in the
request to a remote peer. Users are able to specify a target number of
blocks that the funding transaction should be confirmed in, or a manual fee
rate to us for the funding transaction. If neither are specified, then a
lax block confirmation target is used. Each OpenStatusUpdate will return
the pending channel ID of the in-progress channel. Depending on the
arguments specified in the OpenChannelRequest, this pending channel ID can
then be used to manually progress the channel funding flow.
*/
rpc OpenChannel (OpenChannelRequest) returns (stream OpenStatusUpdate);
/* lncli: `batchopenchannel`
BatchOpenChannel attempts to open multiple single-funded channels in a
single transaction in an atomic way. This means either all channel open
requests succeed at once or all attempts are aborted if any of them fail.
This is the safer variant of using PSBTs to manually fund a batch of
channels through the OpenChannel RPC.
*/
rpc BatchOpenChannel (BatchOpenChannelRequest)
returns (BatchOpenChannelResponse);
/*
FundingStateStep is an advanced funding related call that allows the caller
to either execute some preparatory steps for a funding workflow, or
manually progress a funding workflow. The primary way a funding flow is
identified is via its pending channel ID. As an example, this method can be
used to specify that we're expecting a funding flow for a particular
pending channel ID, for which we need to use specific parameters.
Alternatively, this can be used to interactively drive PSBT signing for
funding for partially complete funding transactions.
*/
rpc FundingStateStep (FundingTransitionMsg) returns (FundingStateStepResp);
/*
ChannelAcceptor dispatches a bi-directional streaming RPC in which
OpenChannel requests are sent to the client and the client responds with
a boolean that tells LND whether or not to accept the channel. This allows
node operators to specify their own criteria for accepting inbound channels
through a single persistent connection.
*/
rpc ChannelAcceptor (stream ChannelAcceptResponse)
returns (stream ChannelAcceptRequest);
/* lncli: `closechannel`
CloseChannel attempts to close an active channel identified by its channel
outpoint (ChannelPoint). The actions of this method can additionally be
augmented to attempt a force close after a timeout period in the case of an
inactive peer. If a non-force close (cooperative closure) is requested,
then the user can specify either a target number of blocks until the
closure transaction is confirmed, or a manual fee rate. If neither are
specified, then a default lax, block confirmation target is used.
*/
rpc CloseChannel (CloseChannelRequest) returns (stream CloseStatusUpdate);
/* lncli: `abandonchannel`
AbandonChannel removes all channel state from the database except for a
close summary. This method can be used to get rid of permanently unusable
channels due to bugs fixed in newer versions of lnd. This method can also be
used to remove externally funded channels where the funding transaction was
never broadcast. Only available for non-externally funded channels in dev
build.
*/
rpc AbandonChannel (AbandonChannelRequest) returns (AbandonChannelResponse);
/* lncli: `sendpayment`
Deprecated, use routerrpc.SendPaymentV2. SendPayment dispatches a
bi-directional streaming RPC for sending payments through the Lightning
Network. A single RPC invocation creates a persistent bi-directional
stream allowing clients to rapidly send payments through the Lightning
Network with a single persistent connection.
*/
rpc SendPayment (stream SendRequest) returns (stream SendResponse) {
option deprecated = true;
}
/*
SendPaymentSync is the synchronous non-streaming version of SendPayment.
This RPC is intended to be consumed by clients of the REST proxy.
Additionally, this RPC expects the destination's public key and the payment
hash (if any) to be encoded as hex strings.
*/
rpc SendPaymentSync (SendRequest) returns (SendResponse);
/* lncli: `sendtoroute`
Deprecated, use routerrpc.SendToRouteV2. SendToRoute is a bi-directional
streaming RPC for sending payment through the Lightning Network. This
method differs from SendPayment in that it allows users to specify a full
route manually. This can be used for things like rebalancing, and atomic
swaps.
*/
rpc SendToRoute (stream SendToRouteRequest) returns (stream SendResponse) {
option deprecated = true;
}
/*
SendToRouteSync is a synchronous version of SendToRoute. It Will block
until the payment either fails or succeeds.
*/
rpc SendToRouteSync (SendToRouteRequest) returns (SendResponse);
/* lncli: `addinvoice`
AddInvoice attempts to add a new invoice to the invoice database. Any
duplicated invoices are rejected, therefore all invoices *must* have a
unique payment preimage.
*/
rpc AddInvoice (Invoice) returns (AddInvoiceResponse);
/* lncli: `listinvoices`
ListInvoices returns a list of all the invoices currently stored within the
database. Any active debug invoices are ignored. It has full support for
paginated responses, allowing users to query for specific invoices through
their add_index. This can be done by using either the first_index_offset or
last_index_offset fields included in the response as the index_offset of the
next request. By default, the first 100 invoices created will be returned.
Backwards pagination is also supported through the Reversed flag.
*/
rpc ListInvoices (ListInvoiceRequest) returns (ListInvoiceResponse);
/* lncli: `lookupinvoice`
LookupInvoice attempts to look up an invoice according to its payment hash.
The passed payment hash *must* be exactly 32 bytes, if not, an error is
returned.
*/
rpc LookupInvoice (PaymentHash) returns (Invoice);
/*
SubscribeInvoices returns a uni-directional stream (server -> client) for
notifying the client of newly added/settled invoices. The caller can
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, 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.
*/
rpc SubscribeInvoices (InvoiceSubscription) returns (stream Invoice);
/* lncli: `decodepayreq`
DecodePayReq takes an encoded payment request string and attempts to decode
it, returning a full description of the conditions encoded within the
payment request.
*/
rpc DecodePayReq (PayReqString) returns (PayReq);
/* lncli: `listpayments`
ListPayments returns a list of all outgoing payments.
*/
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.
*/
rpc DeleteAllPayments (DeleteAllPaymentsRequest)
returns (DeleteAllPaymentsResponse);
/* lncli: `describegraph`
DescribeGraph returns a description of the latest graph state from the
point of view of the node. The graph information is partitioned into two
components: all the nodes/vertexes, and all the edges that connect the
vertexes themselves. As this is a directed graph, the edges also contain
the node directional specific routing policy which includes: the time lock
delta, fee information, etc.
*/
rpc DescribeGraph (ChannelGraphRequest) returns (ChannelGraph);
/* lncli: `getnodemetrics`
GetNodeMetrics returns node metrics calculated from the graph. Currently
the only supported metric is betweenness centrality of individual nodes.
*/
rpc GetNodeMetrics (NodeMetricsRequest) returns (NodeMetricsResponse);
/* lncli: `getchaninfo`
GetChanInfo returns the latest authenticated network announcement for the
given channel identified by its channel ID: an 8-byte integer which
uniquely identifies the location of transaction's funding output within the
blockchain.
*/
rpc GetChanInfo (ChanInfoRequest) returns (ChannelEdge);
/* lncli: `getnodeinfo`
GetNodeInfo returns the latest advertised, aggregated, and authenticated
channel information for the specified node identified by its public key.
*/
rpc GetNodeInfo (NodeInfoRequest) returns (NodeInfo);
/* lncli: `queryroutes`
QueryRoutes attempts to query the daemon's Channel Router for a possible
route to a target destination capable of carrying a specific amount of
satoshis. The returned route contains the full details required to craft and
send an HTLC, also including the necessary information that should be
present within the Sphinx packet encapsulated within the HTLC.
When using REST, the `dest_custom_records` map type can be set by appending
`&dest_custom_records[<record_number>]=<record_data_base64_url_encoded>`
to the URL. Unfortunately this map type doesn't appear in the REST API
documentation because of a bug in the grpc-gateway library.
*/
rpc QueryRoutes (QueryRoutesRequest) returns (QueryRoutesResponse);
/* lncli: `getnetworkinfo`
GetNetworkInfo returns some basic stats about the known channel graph from
the point of view of the node.
*/
rpc GetNetworkInfo (NetworkInfoRequest) returns (NetworkInfo);
/* lncli: `stop`
StopDaemon will send a shutdown request to the interrupt handler, triggering
a graceful shutdown of the daemon.
*/
rpc StopDaemon (StopRequest) returns (StopResponse);
/*
SubscribeChannelGraph launches a streaming RPC that allows the caller to
receive notifications upon any changes to the channel graph topology from
the point of view of the responding node. Events notified include: new
nodes coming online, nodes updating their authenticated attributes, new
channels being advertised, updates in the routing policy for a directional
channel edge, and when channels are closed on-chain.
*/
rpc SubscribeChannelGraph (GraphTopologySubscription)
returns (stream GraphTopologyUpdate);
/* lncli: `debuglevel`
DebugLevel allows a caller to programmatically set the logging verbosity of
lnd. The logging can be targeted according to a coarse daemon-wide logging
level, or in a granular fashion to specify the logging for a target
sub-system.
*/
rpc DebugLevel (DebugLevelRequest) returns (DebugLevelResponse);
/* lncli: `feereport`
FeeReport allows the caller to obtain a report detailing the current fee
schedule enforced by the node globally for each channel.
*/
rpc FeeReport (FeeReportRequest) returns (FeeReportResponse);
/* lncli: `updatechanpolicy`
UpdateChannelPolicy allows the caller to update the fee schedule and
channel policies for all channels globally, or a particular channel.
*/
rpc UpdateChannelPolicy (PolicyUpdateRequest)
returns (PolicyUpdateResponse);
/* lncli: `fwdinghistory`
ForwardingHistory allows the caller to query the htlcswitch for a record of
all HTLCs forwarded within the target time range, and integer offset
within that time range, for a maximum number of events. If no maximum number
of events is specified, up to 100 events will be returned. If no time-range
is specified, then events will be returned in the order that they occured.
A list of forwarding events are returned. The size of each forwarding event
is 40 bytes, and the max message size able to be returned in gRPC is 4 MiB.
As a result each message can only contain 50k entries. Each response has
the index offset of the last entry. The index offset can be provided to the
request to allow the caller to skip a series of records.
*/
rpc ForwardingHistory (ForwardingHistoryRequest)
returns (ForwardingHistoryResponse);
/* lncli: `exportchanbackup`
ExportChannelBackup attempts to return an encrypted static channel backup
for the target channel identified by it channel point. The backup is
encrypted with a key generated from the aezeed seed of the user. The
returned backup can either be restored using the RestoreChannelBackup
method once lnd is running, or via the InitWallet and UnlockWallet methods
from the WalletUnlocker service.
*/
rpc ExportChannelBackup (ExportChannelBackupRequest)
returns (ChannelBackup);
/*
ExportAllChannelBackups returns static channel backups for all existing
channels known to lnd. A set of regular singular static channel backups for
each channel are returned. Additionally, a multi-channel backup is returned
as well, which contains a single encrypted blob containing the backups of
each channel.
*/
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.
*/
rpc VerifyChanBackup (ChanBackupSnapshot)
returns (VerifyChanBackupResponse);
/* lncli: `restorechanbackup`
RestoreChannelBackups accepts a set of singular channel backups, or a
single encrypted multi-chan backup and attempts to recover any funds
remaining within the channel. If we are able to unpack the backup, then the
new channel will be shown under listchannels, as well as pending channels.
*/
rpc RestoreChannelBackups (RestoreChanBackupRequest)
returns (RestoreBackupResponse);
/*
SubscribeChannelBackups allows a client to sub-subscribe to the most up to
date information concerning the state of all channel backups. Each time a
new channel is added, we return the new set of channels, along with a
multi-chan backup containing the backup info for all channels. Each time a
channel is closed, we send a new update, which contains new new chan back
ups, but the updated set of encrypted multi-chan backups with the closed
channel(s) removed.
*/
rpc SubscribeChannelBackups (ChannelBackupSubscription)
returns (stream ChanBackupSnapshot);
/* lncli: `bakemacaroon`
BakeMacaroon allows the creation of a new macaroon with custom read and
write permissions. No first-party caveats are added since this can be done
offline.
*/
rpc BakeMacaroon (BakeMacaroonRequest) returns (BakeMacaroonResponse);
/* lncli: `listmacaroonids`
ListMacaroonIDs returns all root key IDs that are in use.
*/
rpc ListMacaroonIDs (ListMacaroonIDsRequest)
returns (ListMacaroonIDsResponse);
/* lncli: `deletemacaroonid`
DeleteMacaroonID deletes the specified macaroon ID and invalidates all
macaroons derived from that ID.
*/
rpc DeleteMacaroonID (DeleteMacaroonIDRequest)
returns (DeleteMacaroonIDResponse);
/* lncli: `listpermissions`
ListPermissions lists all RPC method URIs and their required macaroon
permissions to access them.
*/
rpc ListPermissions (ListPermissionsRequest)
returns (ListPermissionsResponse);
/*
CheckMacaroonPermissions checks whether a request follows the constraints
imposed on the macaroon and that the macaroon is authorized to follow the
provided permissions.
*/
rpc CheckMacaroonPermissions (CheckMacPermRequest)
returns (CheckMacPermResponse);
/*
RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A
gRPC middleware is software component external to lnd that aims to add
additional business logic to lnd by observing/intercepting/validating
incoming gRPC client requests and (if needed) replacing/overwriting outgoing
messages before they're sent to the client. When registering the middleware
must identify itself and indicate what custom macaroon caveats it wants to
be responsible for. Only requests that contain a macaroon with that specific
custom caveat are then sent to the middleware for inspection. The other
option is to register for the read-only mode in which all requests/responses
are forwarded for interception to the middleware but the middleware is not
allowed to modify any responses. As a security measure, _no_ middleware can
modify responses for requests made with _unencumbered_ macaroons!
*/
rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse)
returns (stream RPCMiddlewareRequest);
/* lncli: `sendcustom`
SendCustomMessage sends a custom peer message.
*/
rpc SendCustomMessage (SendCustomMessageRequest)
returns (SendCustomMessageResponse);
/* lncli: `subscribecustom`
SubscribeCustomMessages subscribes to a stream of incoming custom peer
messages.
To include messages with type outside of the custom range (>= 32768) lnd
needs to be compiled with the `dev` build tag, and the message type to
override should be specified in lnd's experimental protocol configuration.
*/
rpc SubscribeCustomMessages (SubscribeCustomMessagesRequest)
returns (stream CustomMessage);
/* lncli: `listaliases`
ListAliases returns the set of all aliases that have ever existed with
their confirmed SCID (if it exists) and/or the base SCID (in the case of
zero conf).
*/
rpc ListAliases (ListAliasesRequest) returns (ListAliasesResponse);
/*
LookupHtlcResolution retrieves a final htlc resolution from the database.
If the htlc has no final resolution yet, a NotFound grpc status code is
returned.
*/
rpc LookupHtlcResolution (LookupHtlcResolutionRequest)
returns (LookupHtlcResolutionResponse);
}
message LookupHtlcResolutionRequest {
uint64 chan_id = 1;
uint64 htlc_index = 2;
}
message LookupHtlcResolutionResponse {
// Settled is true is the htlc was settled. If false, the htlc was failed.
bool settled = 1;
// Offchain indicates whether the htlc was resolved off-chain or on-chain.
bool offchain = 2;
}
message SubscribeCustomMessagesRequest {
}
message CustomMessage {
// Peer from which the message originates
bytes peer = 1;
// Message type. This value will be in the custom range (>= 32768).
uint32 type = 2;
// Raw message data
bytes data = 3;
}
message SendCustomMessageRequest {
// Peer to send the message to
bytes peer = 1;
// Message type. This value needs to be in the custom range (>= 32768).
// To send a type < custom range, lnd needs to be compiled with the `dev`
// build tag, and the message type to override should be specified in lnd's
// experimental protocol configuration.
uint32 type = 2;
// Raw message data.
bytes data = 3;
}
message SendCustomMessageResponse {
}
message Utxo {
// The type of address
AddressType address_type = 1;
// The address
string address = 2;
// The value of the unspent coin in satoshis
int64 amount_sat = 3;
// The pkscript in hex
string pk_script = 4;
// The outpoint in format txid:n
OutPoint outpoint = 5;
// The number of confirmations for the Utxo
int64 confirmations = 6;
}
enum OutputScriptType {
SCRIPT_TYPE_PUBKEY_HASH = 0;
SCRIPT_TYPE_SCRIPT_HASH = 1;
SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH = 2;
SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH = 3;
SCRIPT_TYPE_PUBKEY = 4;
SCRIPT_TYPE_MULTISIG = 5;
SCRIPT_TYPE_NULLDATA = 6;
SCRIPT_TYPE_NON_STANDARD = 7;
SCRIPT_TYPE_WITNESS_UNKNOWN = 8;
SCRIPT_TYPE_WITNESS_V1_TAPROOT = 9;
}
message OutputDetail {
// The type of the output
OutputScriptType output_type = 1;
// The address
string address = 2;
// The pkscript in hex
string pk_script = 3;
// The output index used in the raw transaction
int64 output_index = 4;
// The value of the output coin in satoshis
int64 amount = 5;
// Denotes if the output is controlled by the internal wallet
bool is_our_address = 6;
}
message Transaction {
// The transaction hash
string tx_hash = 1;
// The transaction amount, denominated in satoshis
int64 amount = 2;
// The number of confirmations
int32 num_confirmations = 3;
// The hash of the block this transaction was included in
string block_hash = 4;
// The height of the block this transaction was included in
int32 block_height = 5;
// Timestamp of this transaction
int64 time_stamp = 6;
// Fees paid for this transaction
int64 total_fees = 7;
// Addresses that received funds for this transaction. Deprecated as it is
// now incorporated in the output_details field.
repeated string dest_addresses = 8 [deprecated = true];
// Outputs that received funds for this transaction
repeated OutputDetail output_details = 11;
// The raw transaction hex.
string raw_tx_hex = 9;
// A label that was optionally set on transaction broadcast.
string label = 10;
// PreviousOutpoints/Inputs of this transaction.
repeated PreviousOutPoint previous_outpoints = 12;
}
message GetTransactionsRequest {
/*
The height from which to list transactions, inclusive. If this value is
greater than end_height, transactions will be read in reverse.
*/
int32 start_height = 1;
/*
The height until which to list transactions, inclusive. To include
unconfirmed transactions, this value should be set to -1, which will
return transactions from start_height until the current chain tip and
unconfirmed transactions. If no end_height is provided, the call will
default to this option.
*/
int32 end_height = 2;
// An optional filter to only include transactions relevant to an account.
string account = 3;
}
message TransactionDetails {
// The list of transactions relevant to the wallet.
repeated Transaction transactions = 1;
}
message FeeLimit {
oneof limit {
/*
The fee limit expressed as a fixed amount of satoshis.
The fields fixed and fixed_msat are mutually exclusive.
*/
int64 fixed = 1;
/*
The fee limit expressed as a fixed amount of millisatoshis.
The fields fixed and fixed_msat are mutually exclusive.
*/
int64 fixed_msat = 3;
// The fee limit expressed as a percentage of the payment amount.
int64 percent = 2;
}
}
message SendRequest {
/*
The identity pubkey of the payment recipient. When using REST, this field
must be encoded as base64.
*/
bytes dest = 1;
/*
The hex-encoded identity pubkey of the payment recipient. Deprecated now
that the REST gateway supports base64 encoding of bytes fields.
*/
string dest_string = 2 [deprecated = true];
/*
The amount to send expressed in satoshis.
The fields amt and amt_msat are mutually exclusive.
*/
int64 amt = 3;
/*
The amount to send expressed in millisatoshis.
The fields amt and amt_msat are mutually exclusive.
*/
int64 amt_msat = 12;
/*
The hash to use within the payment's HTLC. When using REST, this field
must be encoded as base64.
*/
bytes payment_hash = 4;
/*
The hex-encoded hash to use within the payment's HTLC. Deprecated now
that the REST gateway supports base64 encoding of bytes fields.
*/
string payment_hash_string = 5 [deprecated = true];
/*
A bare-bones invoice for a payment within the Lightning Network. With the
details of the invoice, the sender has all the data necessary to send a
payment to the recipient.
*/
string payment_request = 6;
/*
The CLTV delta from the current height that should be used to set the
timelock for the final hop.
*/
int32 final_cltv_delta = 7;
/*
The maximum number of satoshis that will be paid as a fee of the payment.
This value can be represented either as a percentage of the amount being
sent, or as a fixed amount of the maximum fee the user is willing the pay to
send the payment. If not specified, lnd will use a default value of 100%
fees for small amounts (<=1k sat) or 5% fees for larger amounts.
*/
FeeLimit fee_limit = 8;
/*
The channel id of the channel that must be taken to the first hop. If zero,
any channel may be used.
*/
uint64 outgoing_chan_id = 9 [jstype = JS_STRING];
/*
The pubkey of the last hop of the route. If empty, any hop may be used.
*/
bytes last_hop_pubkey = 13;
/*
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.
*/
uint32 cltv_limit = 10;
/*
An optional field that can be used to pass an arbitrary set of TLV records
to a peer which understands the new records. This can be used to pass
application specific data during the payment attempt. Record types are
required to be in the custom range >= 65536. When using REST, the values
must be encoded as base64.
*/
map<uint64, bytes> dest_custom_records = 11;
// If set, circular payments to self are permitted.
bool allow_self_payment = 14;
/*
Features assumed to be supported by the final node. All transitive feature
dependencies must also be set properly. For a given feature bit pair, either
optional or remote may be set, but not both. If this field is nil or empty,
the router will try to load destination features from the graph as a
fallback.
*/
repeated FeatureBit dest_features = 15;
/*
The payment address of the generated invoice. This is also called
payment secret in specifications (e.g. BOLT 11).
*/
bytes payment_addr = 16;
}
message SendResponse {
string payment_error = 1;
bytes payment_preimage = 2;
Route payment_route = 3;
bytes payment_hash = 4;
}
message SendToRouteRequest {
/*
The payment hash to use for the HTLC. When using REST, this field must be
encoded as base64.
*/
bytes payment_hash = 1;
/*
An optional hex-encoded payment hash to be used for the HTLC. Deprecated now
that the REST gateway supports base64 encoding of bytes fields.
*/
string payment_hash_string = 2 [deprecated = true];
reserved 3;
// Route that should be used to attempt to complete the payment.
Route route = 4;
}
message ChannelAcceptRequest {
// The pubkey of the node that wishes to open an inbound channel.
bytes node_pubkey = 1;
// The hash of the genesis block that the proposed channel resides in.
bytes chain_hash = 2;
// The pending channel id.
bytes pending_chan_id = 3;
// The funding amount in satoshis that initiator wishes to use in the
// channel.
uint64 funding_amt = 4;
// The push amount of the proposed channel in millisatoshis.
uint64 push_amt = 5;
// The dust limit of the initiator's commitment tx.
uint64 dust_limit = 6;
// The maximum amount of coins in millisatoshis that can be pending in this
// channel.
uint64 max_value_in_flight = 7;
// The minimum amount of satoshis the initiator requires us to have at all
// times.
uint64 channel_reserve = 8;
// The smallest HTLC in millisatoshis that the initiator will accept.
uint64 min_htlc = 9;
// The initial fee rate that the initiator suggests for both commitment
// transactions.
uint64 fee_per_kw = 10;
/*
The number of blocks to use for the relative time lock in the pay-to-self
output of both commitment transactions.
*/
uint32 csv_delay = 11;
// The total number of incoming HTLC's that the initiator will accept.
uint32 max_accepted_htlcs = 12;
// A bit-field which the initiator uses to specify proposed channel
// behavior.
uint32 channel_flags = 13;
// The commitment type the initiator wishes to use for the proposed channel.
CommitmentType commitment_type = 14;
// Whether the initiator wants to open a zero-conf channel via the channel
// type.
bool wants_zero_conf = 15;
// Whether the initiator wants to use the scid-alias channel type. This is
// separate from the feature bit.
bool wants_scid_alias = 16;
}
message ChannelAcceptResponse {
// Whether or not the client accepts the channel.
bool accept = 1;
// The pending channel id to which this response applies.
bytes pending_chan_id = 2;
/*
An optional error to send the initiating party to indicate why the channel
was rejected. This field *should not* contain sensitive information, it will
be sent to the initiating party. This field should only be set if accept is
false, the channel will be rejected if an error is set with accept=true
because the meaning of this response is ambiguous. Limited to 500
characters.
*/
string error = 3;
/*
The upfront shutdown address to use if the initiating peer supports option
upfront shutdown script (see ListPeers for the features supported). Note
that the channel open will fail if this value is set for a peer that does
not support this feature bit.