lnrpc 0.9.0 → 0.10.0

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 353271a0231be5f99b2979774980f7f7500846efaafefe95d04beb2fe7d4b8a5
4
- data.tar.gz: e5b0b419399029853b50d2738aa299f5cd17403b2eee55dd354c0ca6ef8f0c43
3
+ metadata.gz: 6a50669372559c0f119a65b3b3c28807aef5f08b3dc6bb34661ac5c2cd65c3c1
4
+ data.tar.gz: a0792b47d9062ab479857b24f04ed6ef16dde19bb8cc64f907bb032619d37d5f
5
5
  SHA512:
6
- metadata.gz: f5b0aa7b9c3ce6cfc66c9779e920f6ff3f9cf2ca4bffd98f2ccc8eff18eae5f9c3752b7f26068baa8734c92bb80932a5458f521592a470ab134df6b98a0af9ee
7
- data.tar.gz: 974f7023636ea5dd841a7bbcf9603b9fa43e657e55ee89850a5eb363ee74620d2d620c10bf3d09f3ce2230a70929070419b7ca5bc419e9398380f51d18267dc0
6
+ metadata.gz: 818af8a8ea58e2ea57fadc1767b8575059a744d5953ac275f8e2f7d58fc766fb44977a7850c9014d9063254502578bb8488da9d72a97483ec63d278adad4f89d
7
+ data.tar.gz: 7514a4eb8bd482459cceded2c990d10f2d39cfedc5d06163d6bcf067bdee59404d97b4e3d599e57c1c18951639896dc2ca7c3862a0c6a936e378d444b6d75d1b
data/.gitignore CHANGED
@@ -11,3 +11,5 @@
11
11
  .rspec_status
12
12
 
13
13
  .ruby-version
14
+
15
+ *.gem
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- lnrpc (0.8.0.beta)
4
+ lnrpc (0.10.0)
5
5
  google-protobuf (>= 3.7)
6
6
  grpc (>= 1.19.0)
7
7
 
@@ -15,7 +15,7 @@ GEM
15
15
  grpc (1.24.0)
16
16
  google-protobuf (~> 3.8)
17
17
  googleapis-common-protos-types (~> 1.0)
18
- rake (10.5.0)
18
+ rake (13.0.1)
19
19
  rspec (3.9.0)
20
20
  rspec-core (~> 3.9.0)
21
21
  rspec-expectations (~> 3.9.0)
@@ -36,7 +36,7 @@ PLATFORMS
36
36
  DEPENDENCIES
37
37
  bundler (~> 1.17)
38
38
  lnrpc!
39
- rake (~> 10.0)
39
+ rake (~> 13.0)
40
40
  rspec (~> 3.0)
41
41
 
42
42
  BUNDLED WITH
data/README.md CHANGED
@@ -3,13 +3,15 @@
3
3
 
4
4
  a [gRPC](https://grpc.io/) client for [LND, the Lightning Network Daemon](https://github.com/lightningnetwork/lnd/) packed as ruby gem.
5
5
 
6
-
7
6
  ## Installation
8
7
 
8
+ Note: there is still an GRPC/protobuf [issue with Ruby 2.7](https://github.com/protocolbuffers/protobuf/issues/7070).
9
+ So lnrpc requires Ruby < 2.7.
10
+
9
11
  Add this line to your application's Gemfile:
10
12
 
11
13
  ```ruby
12
- gem 'lnrpc', '~> 0.7.0'
14
+ gem 'lnrpc', '~> 0.10.0'
13
15
  ```
14
16
  lnrpc follows the lnd versioning, thus it is recommended to specify the exact version you need for your lnd node as dependency (see [#Versioning](#Versioning)).
15
17
 
@@ -30,10 +32,12 @@ This gem makes the gRPC client classes created from the [LND service defintions]
30
32
  ```ruby
31
33
  require "lnrpc"
32
34
 
33
- # the gRPC client is available under the Lnrpc namespace, e.g.
35
+ # With the changes in LND v.10.0 this load the `Lnrpc` and `Routerrpc` namespace
34
36
 
35
37
  Lnrpc::Lightning::Stub
38
+ Routerrpc:::Routerrpc::Stub
36
39
  Lnrpc::GetInfoRequest
40
+ ...
37
41
  ```
38
42
 
39
43
  Learn more about [gRPC](https://grpc.io/) on [gRPC.io](https://grpc.io/).
@@ -55,17 +59,26 @@ client = Lnrpc::Lightning::Stub.new("localhost:10009", GRPC::Core::ChannelCreden
55
59
  request = Lnrpc::GetInfoRequest.new
56
60
  response = client.get_info(request, { metadata: { macaroon: macaroon } }) #=> Lnrpc::GetInfoResponse
57
61
  puts response.alias
62
+
63
+ router = Routerprc::Router::Stub.new("localhost:10009", GRPC::Core::ChannelCredentials.new(self.credentials))
64
+ ...
65
+
58
66
  ```
59
67
 
60
68
  ### Client wrapper
61
69
 
70
+ NOTE: v10.0 has breaking changes!
71
+
62
72
  An optional client wrapper ([Lnrpc::Client](https://github.com/bumi/lnrpc/blob/master/lib/lnrpc/client.rb)) makes
63
73
  initializing the gRPC client easier and removes the need for some boilerplate code for calling RPC methods.
64
74
 
65
75
  #### Example
66
76
  ```ruby
67
77
  lnd = Lnrpc::Client.new({credentials_path: '/path/to.cert.cls', macaroon_path: '/path/to/admin.macaroon'})
68
- lnd.get_info
78
+ lnd.lightning # => Lnrpc::Lightning::Stub
79
+ lnd.router # => Lnrpc::Router::Stub
80
+
81
+ lnd.ligthning.get_info
69
82
  ```
70
83
 
71
84
  Also have a look at [examples.rb](https://github.com/bumi/lnrpc/blob/master/examples.rb)
@@ -96,7 +109,8 @@ lnd = Lnrpc::Client.new({
96
109
  })
97
110
 
98
111
  # the actual gRPC client is available through:
99
- lnd.grpc_client
112
+ lnd.lightning.grpc
113
+ lnd.router.grpc
100
114
  ```
101
115
 
102
116
  #### Calling RPC methods
@@ -108,19 +122,19 @@ If the first parameter is a hash or blank the corresponding gRPC request object
108
122
  Example:
109
123
 
110
124
  ```ruby
111
- client.get_info
125
+ client.lightning.get_info
112
126
  # is the same as:
113
- client.grpc_client.get_info(Lnrpc::GetInfoRequest.new)
127
+ client.lightning.grpc.get_info(Lnrpc::GetInfoRequest.new)
114
128
 
115
- client.list_channels(inactive_only: true)
129
+ client.lightning.list_channels(inactive_only: true)
116
130
  # is the same as:
117
131
  request = Lnrpc::ListChannelsRequest.new(inactive_only: true)
118
- client.grpc_client.list_channels(request)
132
+ client.lightning.grpc.list_channels(request)
119
133
 
120
- client.wallet_balance.total_balance
134
+ client.lightning.wallet_balance.total_balance
121
135
  # is the same as:
122
136
  request = Lnrpc::WalletBalanceRequest.new()
123
- client.grpc_client.wallet_balance(request).total_balance
137
+ client.lightning.grpc.wallet_balance(request).total_balance
124
138
  ```
125
139
 
126
140
  ## Using with BTC Pay Server
@@ -153,6 +167,14 @@ see [rubygems](https://rubygems.org/gems/lnrpc) for all available releases.
153
167
 
154
168
  3. Update `rpc_services_pb.rb` to use `require_relative` to load `rpc_pb`
155
169
 
170
+ 4. Generate `router_pb.rb` and `router_services_pb.rb`
171
+
172
+ $ grpc_tools_ruby_protoc -I/usr/local/include -I. -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis -I$GOPATH/src/github.com/lightningnetwork/lnd/lnrpc --ruby_out=plugins=grpc,paths=source_relative:. --grpc_out=. router.proto
173
+
174
+ 5. Copy `router.proto`, `router_pb.rb` and `router_services_pb.rb` to `lib`
175
+
176
+ 6. Update `router_services_pb.rb` to use `require_relative` to load `router_pb`
177
+
156
178
  ## Other resources
157
179
 
158
180
  * [LND gRPC API Reference](https://api.lightning.community)
@@ -1,10 +1,22 @@
1
- require "lnrpc/version"
2
- require "lnrpc/rpc_services_pb"
1
+ require 'lnrpc/version'
2
+ require 'lnrpc/rpc_services_pb'
3
+ require 'lnrpc/router_services_pb'
4
+ require 'securerandom'
3
5
 
4
6
  module Lnrpc
5
7
  class Error < StandardError; end
6
8
  autoload :Client, 'lnrpc/client'
9
+ autoload :GrpcWrapper, 'lnrpc/grpc_wrapper'
7
10
  autoload :MacaroonInterceptor, 'lnrpc/macaroon_interceptor'
8
- end
9
11
 
12
+ PREIMAGE_BYTE_LENGTH = 32
13
+ KEY_SEND_PREIMAGE_TYPE = 5482373484
14
+
15
+ def self.create_preimage
16
+ SecureRandom.random_bytes(PREIMAGE_BYTE_LENGTH)
17
+ end
10
18
 
19
+ def self.to_byte_array(str)
20
+ [str].pack("H*")
21
+ end
22
+ end
@@ -3,32 +3,12 @@ require "lnrpc/macaroon_interceptor"
3
3
  module Lnrpc
4
4
  class Client
5
5
  attr_accessor :address, :credentials, :macaroon
6
- attr_writer :grpc_client
7
6
 
8
7
  LND_HOME_DIR = ENV['LND_HOME'] || "~/.lnd"
9
8
  DEFAULT_ADDRESS = 'localhost:10009'
10
9
  DEFAULT_CREDENTIALS_PATH = "#{LND_HOME_DIR}/tls.cert"
11
10
  DEFAULT_MACAROON_PATH = "#{LND_HOME_DIR}/data/chain/bitcoin/mainnet/admin.macaroon"
12
11
 
13
- NON_CONVENTION_REQUEST_CLASSES = {
14
- add_invoice: Lnrpc::Invoice,
15
- send_payment: Lnrpc::SendRequest,
16
- send_payment_sync: Lnrpc::SendRequest,
17
- open_channel_sync: Lnrpc::OpenChannelRequest,
18
- send_to_route_sync: Lnrpc::SendToRouteRequest,
19
- lookup_invoice: Lnrpc::PaymentHash,
20
- decode_pay_req: Lnrpc::PayReqString,
21
- describe_graph: Lnrpc::ChannelGraphRequest,
22
- get_chan_info: Lnrpc::ChanInfoRequest,
23
- get_node_info: Lnrpc::NodeInfoRequest,
24
- get_network_info: Lnrpc::NetworkInfoRequest,
25
- stop_daemon: Lnrpc::StopRequest,
26
- update_channel_policy: Lnrpc::PolicyUpdateResponse,
27
- subscribe_channel_graph: Lnrpc::GraphTopologySubscription,
28
- subscribe_invoices: Lnrpc::InvoiceSubscription,
29
- subscribe_transactions: Lnrpc::GetTransactionsRequest
30
- }
31
-
32
12
  def initialize(options={})
33
13
  self.address = options[:address] || DEFAULT_ADDRESS
34
14
 
@@ -46,42 +26,36 @@ module Lnrpc
46
26
  self.macaroon = options[:macaroon]
47
27
  end
48
28
 
49
- def grpc_client
50
- @grpc_client ||= Lnrpc::Lightning::Stub.new(self.address,
51
- GRPC::Core::ChannelCredentials.new(self.credentials),
52
- interceptors: [Lnrpc::MacaroonInterceptor.new(self.macaroon)]
53
- )
29
+ def lightning
30
+ @lightning ||= GrpcWrapper.new(Lnrpc::Lightning::Stub.new(address,
31
+ GRPC::Core::ChannelCredentials.new(credentials),
32
+ interceptors: [Lnrpc::MacaroonInterceptor.new(macaroon)]
33
+ ))
54
34
  end
55
35
 
56
- def pay(payreq)
57
- self.send_payment_sync(Lnrpc::SendRequest.new(payment_request: payreq))
36
+ def router
37
+ @router ||= GrpcWrapper.new(Routerrpc::Router::Stub.new(address,
38
+ GRPC::Core::ChannelCredentials.new(credentials),
39
+ interceptors: [Lnrpc::MacaroonInterceptor.new(macaroon)]
40
+ ))
58
41
  end
59
42
 
60
- def method_missing(m, *args, &block)
61
- if self.grpc_client.respond_to?(m)
62
- params = args[0]
43
+ def keysend(args)
44
+ args[:dest_custom_records] ||= {}
45
+ args[:dest_custom_records][Lnrpc::KEY_SEND_PREIMAGE_TYPE] ||= Lnrpc.create_preimage
46
+ args[:payment_hash] ||= Digest::SHA256.digest(args[:dest_custom_records][Lnrpc::KEY_SEND_PREIMAGE_TYPE])
47
+ args[:timeout_seconds] ||= 60
48
+ router.send_payment_v2(args)
49
+ end
63
50
 
64
- args[0] = params.nil? ? request_class_for(m).new : request_class_for(m).new(params)
65
- self.grpc_client.send(m, *args, &block)
66
- else
67
- super
68
- end
51
+ def pay(args)
52
+ args[:timeout_seconds] ||= 60
53
+ router.send_payment_v2(args)
69
54
  end
70
55
 
71
56
  def inspect
72
57
  "#{self.to_s} @address=\"#{self.address}\""
73
58
  end
74
59
 
75
- private
76
- def request_class_for(method_name)
77
- if NON_CONVENTION_REQUEST_CLASSES.key?(method_name.to_sym)
78
- NON_CONVENTION_REQUEST_CLASSES[method_name.to_sym]
79
- else
80
- klass = method_name.to_s.sub(/^[a-z\d]*/) { |match| match.capitalize }
81
- klass.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
82
- Lnrpc.const_get("#{klass}Request")
83
- end
84
- end
85
60
  end
86
61
  end
87
-
@@ -0,0 +1,66 @@
1
+ module Lnrpc
2
+ class GrpcWrapper
3
+ NON_CONVENTION_REQUEST_CLASSES = {
4
+ add_invoice: Lnrpc::Invoice,
5
+ decode_pay_req: Lnrpc::PayReqString,
6
+ describe_graph: Lnrpc::ChannelGraphRequest,
7
+ export_all_channel_backups: Lnrpc::ChanBackupExportRequest,
8
+ funding_state_step: Lnrpc::FundingTransitionMsg,
9
+ get_chan_info: Lnrpc::ChanInfoRequest,
10
+ get_network_info: Lnrpc::NetworkInfoRequest,
11
+ get_node_info: Lnrpc::NodeInfoRequest,
12
+ get_node_metrics: Lnrpc::NodeMetricsRequest,
13
+ lookup_invoice: Lnrpc::PaymentHash,
14
+ open_channel_sync: Lnrpc::OpenChannelRequest,
15
+ send_payment_sync: Lnrpc::SendRequest,
16
+ send_to_route_sync: Lnrpc::SendToRouteRequest,
17
+ stop_daemon: Lnrpc::StopRequest,
18
+ subscribe_channel_backups: Lnrpc::ChannelBackupSubscription,
19
+ subscribe_channel_event: Lnrpc::ChannelEventSubscription,
20
+ subscribe_channel_graph: Lnrpc::GraphTopologySubscription,
21
+ subscribe_invoices: Lnrpc::InvoiceSubscription,
22
+ subscribe_peer_event: Lnrpc::PeerEventSubscription,
23
+ subscribe_transactions: Lnrpc::GetTransactionsRequest,
24
+ update_channel_policy: Lnrpc::PolicyUpdateResponse,
25
+ varify_channel_backup: Lnrpc::ChanBackupSnapshot,
26
+
27
+ estimate_route_fee: Routerrpc::RouteFeeRequest,
28
+ send_payment: Routerrpc::SendPaymentRequest,
29
+ send_payment_v2: Routerrpc::SendPaymentRequest,
30
+ track_payment_v2: Routerrpc::TrackPaymentRequest
31
+ }
32
+
33
+ attr_reader :grpc
34
+
35
+ def initialize(grpc)
36
+ @grpc = grpc
37
+ end
38
+
39
+ def method_missing(m, *args, &block)
40
+ if self.grpc.respond_to?(m)
41
+ params = args[0]
42
+
43
+ args[0] = params.nil? ? request_class_for(m).new : request_class_for(m).new(params)
44
+ self.grpc.send(m, *args, &block)
45
+ else
46
+ super
47
+ end
48
+ end
49
+
50
+ def inspect
51
+ "#{self.to_s} @grpc=\"#{self.grpc.to_s}\""
52
+ end
53
+
54
+ private
55
+
56
+ def request_class_for(method_name)
57
+ if NON_CONVENTION_REQUEST_CLASSES.key?(method_name.to_sym)
58
+ NON_CONVENTION_REQUEST_CLASSES[method_name.to_sym]
59
+ else
60
+ klass = method_name.to_s.sub(/^[a-z\d]*/) { |match| match.capitalize }
61
+ klass.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
62
+ Module.const_get(grpc.class.name.to_s[/.+?(?=::)/]).const_get("#{klass}Request")
63
+ end
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,560 @@
1
+ syntax = "proto3";
2
+
3
+ import "rpc.proto";
4
+
5
+ package routerrpc;
6
+
7
+ option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";
8
+
9
+ message SendPaymentRequest {
10
+ /// The identity pubkey of the payment recipient
11
+ bytes dest = 1;
12
+
13
+ /**
14
+ Number of satoshis to send.
15
+
16
+ The fields amt and amt_msat are mutually exclusive.
17
+ */
18
+ int64 amt = 2;
19
+
20
+ /**
21
+ Number of millisatoshis to send.
22
+
23
+ The fields amt and amt_msat are mutually exclusive.
24
+ */
25
+ int64 amt_msat = 12;
26
+
27
+ /// The hash to use within the payment's HTLC
28
+ bytes payment_hash = 3;
29
+
30
+ /**
31
+ The CLTV delta from the current height that should be used to set the
32
+ timelock for the final hop.
33
+ */
34
+ int32 final_cltv_delta = 4;
35
+
36
+ /**
37
+ A bare-bones invoice for a payment within the Lightning Network. With the
38
+ details of the invoice, the sender has all the data necessary to send a
39
+ payment to the recipient. The amount in the payment request may be zero. In
40
+ that case it is required to set the amt field as well. If no payment request
41
+ is specified, the following fields are required: dest, amt and payment_hash.
42
+ */
43
+ string payment_request = 5;
44
+
45
+ /**
46
+ An upper limit on the amount of time we should spend when attempting to
47
+ fulfill the payment. This is expressed in seconds. If we cannot make a
48
+ successful payment within this time frame, an error will be returned.
49
+ This field must be non-zero.
50
+ */
51
+ int32 timeout_seconds = 6;
52
+
53
+ /**
54
+ The maximum number of satoshis that will be paid as a fee of the payment.
55
+ If this field is left to the default value of 0, only zero-fee routes will
56
+ be considered. This usually means single hop routes connecting directly to
57
+ the destination. To send the payment without a fee limit, use max int here.
58
+
59
+ The fields fee_limit_sat and fee_limit_msat are mutually exclusive.
60
+ */
61
+ int64 fee_limit_sat = 7;
62
+
63
+ /**
64
+ The maximum number of millisatoshis that will be paid as a fee of the
65
+ payment. If this field is left to the default value of 0, only zero-fee
66
+ routes will be considered. This usually means single hop routes connecting
67
+ directly to the destination. To send the payment without a fee limit, use
68
+ max int here.
69
+
70
+ The fields fee_limit_sat and fee_limit_msat are mutually exclusive.
71
+ */
72
+ int64 fee_limit_msat = 13;
73
+
74
+ /**
75
+ The channel id of the channel that must be taken to the first hop. If zero,
76
+ any channel may be used.
77
+ */
78
+ uint64 outgoing_chan_id = 8 [jstype = JS_STRING];
79
+
80
+ /**
81
+ The pubkey of the last hop of the route. If empty, any hop may be used.
82
+ */
83
+ bytes last_hop_pubkey = 14;
84
+
85
+ /**
86
+ An optional maximum total time lock for the route. This should not exceed
87
+ lnd's `--max-cltv-expiry` setting. If zero, then the value of
88
+ `--max-cltv-expiry` is enforced.
89
+ */
90
+ int32 cltv_limit = 9;
91
+
92
+ /**
93
+ Optional route hints to reach the destination through private channels.
94
+ */
95
+ repeated lnrpc.RouteHint route_hints = 10;
96
+
97
+ /**
98
+ An optional field that can be used to pass an arbitrary set of TLV records
99
+ to a peer which understands the new records. This can be used to pass
100
+ application specific data during the payment attempt. Record types are
101
+ required to be in the custom range >= 65536. When using REST, the values
102
+ must be encoded as base64.
103
+ */
104
+ map<uint64, bytes> dest_custom_records = 11;
105
+
106
+ /// If set, circular payments to self are permitted.
107
+ bool allow_self_payment = 15;
108
+
109
+ /**
110
+ Features assumed to be supported by the final node. All transitive feature
111
+ dependencies must also be set properly. For a given feature bit pair, either
112
+ optional or remote may be set, but not both. If this field is nil or empty,
113
+ the router will try to load destination features from the graph as a
114
+ fallback.
115
+ */
116
+ repeated lnrpc.FeatureBit dest_features = 16;
117
+
118
+ /**
119
+ The maximum number of partial payments that may be use to complete the full
120
+ amount.
121
+ */
122
+ uint32 max_parts = 17;
123
+
124
+ /**
125
+ If set, only the final payment update is streamed back. Intermediate updates
126
+ that show which htlcs are still in flight are suppressed.
127
+ */
128
+ bool no_inflight_updates = 18;
129
+ }
130
+
131
+ message TrackPaymentRequest {
132
+ /// The hash of the payment to look up.
133
+ bytes payment_hash = 1;
134
+
135
+ /**
136
+ If set, only the final payment update is streamed back. Intermediate updates
137
+ that show which htlcs are still in flight are suppressed.
138
+ */
139
+ bool no_inflight_updates = 2;
140
+ }
141
+
142
+ message RouteFeeRequest {
143
+ /**
144
+ The destination once wishes to obtain a routing fee quote to.
145
+ */
146
+ bytes dest = 1;
147
+
148
+ /**
149
+ The amount one wishes to send to the target destination.
150
+ */
151
+ int64 amt_sat = 2;
152
+ }
153
+
154
+ message RouteFeeResponse {
155
+ /**
156
+ A lower bound of the estimated fee to the target destination within the
157
+ network, expressed in milli-satoshis.
158
+ */
159
+ int64 routing_fee_msat = 1;
160
+
161
+ /**
162
+ An estimate of the worst case time delay that can occur. Note that callers
163
+ will still need to factor in the final CLTV delta of the last hop into this
164
+ value.
165
+ */
166
+ int64 time_lock_delay = 2;
167
+ }
168
+
169
+ message SendToRouteRequest {
170
+ /// The payment hash to use for the HTLC.
171
+ bytes payment_hash = 1;
172
+
173
+ /// Route that should be used to attempt to complete the payment.
174
+ lnrpc.Route route = 2;
175
+ }
176
+
177
+ message SendToRouteResponse {
178
+ /// The preimage obtained by making the payment.
179
+ bytes preimage = 1;
180
+
181
+ /// The failure message in case the payment failed.
182
+ lnrpc.Failure failure = 2;
183
+ }
184
+
185
+ message ResetMissionControlRequest {
186
+ }
187
+
188
+ message ResetMissionControlResponse {
189
+ }
190
+
191
+ message QueryMissionControlRequest {
192
+ }
193
+
194
+ /// QueryMissionControlResponse contains mission control state.
195
+ message QueryMissionControlResponse {
196
+ reserved 1;
197
+
198
+ /// Node pair-level mission control state.
199
+ repeated PairHistory pairs = 2;
200
+ }
201
+
202
+ /// PairHistory contains the mission control state for a particular node pair.
203
+ message PairHistory {
204
+ /// The source node pubkey of the pair.
205
+ bytes node_from = 1;
206
+
207
+ /// The destination node pubkey of the pair.
208
+ bytes node_to = 2;
209
+
210
+ reserved 3, 4, 5, 6;
211
+
212
+ PairData history = 7;
213
+ }
214
+
215
+ message PairData {
216
+ /// Time of last failure.
217
+ int64 fail_time = 1;
218
+
219
+ /**
220
+ Lowest amount that failed to forward rounded to whole sats. This may be
221
+ set to zero if the failure is independent of amount.
222
+ */
223
+ int64 fail_amt_sat = 2;
224
+
225
+ /**
226
+ Lowest amount that failed to forward in millisats. This may be
227
+ set to zero if the failure is independent of amount.
228
+ */
229
+ int64 fail_amt_msat = 4;
230
+
231
+ reserved 3;
232
+
233
+ /// Time of last success.
234
+ int64 success_time = 5;
235
+
236
+ /// Highest amount that we could successfully forward rounded to whole sats.
237
+ int64 success_amt_sat = 6;
238
+
239
+ /// Highest amount that we could successfully forward in millisats.
240
+ int64 success_amt_msat = 7;
241
+ }
242
+
243
+ message QueryProbabilityRequest {
244
+ /// The source node pubkey of the pair.
245
+ bytes from_node = 1;
246
+
247
+ /// The destination node pubkey of the pair.
248
+ bytes to_node = 2;
249
+
250
+ /// The amount for which to calculate a probability.
251
+ int64 amt_msat = 3;
252
+ }
253
+
254
+ message QueryProbabilityResponse {
255
+ /// The success probability for the requested pair.
256
+ double probability = 1;
257
+
258
+ /// The historical data for the requested pair.
259
+ PairData history = 2;
260
+ }
261
+
262
+ message BuildRouteRequest {
263
+ /**
264
+ The amount to send expressed in msat. If set to zero, the minimum routable
265
+ amount is used.
266
+ */
267
+ int64 amt_msat = 1;
268
+
269
+ /**
270
+ CLTV delta from the current height that should be used for the timelock
271
+ of the final hop
272
+ */
273
+ int32 final_cltv_delta = 2;
274
+
275
+ /**
276
+ The channel id of the channel that must be taken to the first hop. If zero,
277
+ any channel may be used.
278
+ */
279
+ uint64 outgoing_chan_id = 3 [jstype = JS_STRING];
280
+
281
+ /**
282
+ A list of hops that defines the route. This does not include the source hop
283
+ pubkey.
284
+ */
285
+ repeated bytes hop_pubkeys = 4;
286
+ }
287
+
288
+ message BuildRouteResponse {
289
+ /**
290
+ Fully specified route that can be used to execute the payment.
291
+ */
292
+ lnrpc.Route route = 1;
293
+ }
294
+
295
+ message SubscribeHtlcEventsRequest {
296
+ }
297
+
298
+ /**
299
+ HtlcEvent contains the htlc event that was processed. These are served on a
300
+ best-effort basis; events are not persisted, delivery is not guaranteed
301
+ (in the event of a crash in the switch, forward events may be lost) and
302
+ some events may be replayed upon restart. Events consumed from this package
303
+ should be de-duplicated by the htlc's unique combination of incoming and
304
+ outgoing channel id and htlc id. [EXPERIMENTAL]
305
+ */
306
+ message HtlcEvent {
307
+ /**
308
+ The short channel id that the incoming htlc arrived at our node on. This
309
+ value is zero for sends.
310
+ */
311
+ uint64 incoming_channel_id = 1;
312
+
313
+ /**
314
+ The short channel id that the outgoing htlc left our node on. This value
315
+ is zero for receives.
316
+ */
317
+ uint64 outgoing_channel_id = 2;
318
+
319
+ /**
320
+ Incoming id is the index of the incoming htlc in the incoming channel.
321
+ This value is zero for sends.
322
+ */
323
+ uint64 incoming_htlc_id = 3;
324
+
325
+ /**
326
+ Outgoing id is the index of the outgoing htlc in the outgoing channel.
327
+ This value is zero for receives.
328
+ */
329
+ uint64 outgoing_htlc_id = 4;
330
+
331
+ /**
332
+ The time in unix nanoseconds that the event occurred.
333
+ */
334
+ uint64 timestamp_ns = 5;
335
+
336
+ enum EventType {
337
+ UNKNOWN = 0;
338
+ SEND = 1;
339
+ RECEIVE = 2;
340
+ FORWARD = 3;
341
+ }
342
+
343
+ /**
344
+ The event type indicates whether the htlc was part of a send, receive or
345
+ forward.
346
+ */
347
+ EventType event_type = 6;
348
+
349
+ oneof event {
350
+ ForwardEvent forward_event = 7;
351
+ ForwardFailEvent forward_fail_event = 8;
352
+ SettleEvent settle_event = 9;
353
+ LinkFailEvent link_fail_event = 10;
354
+ }
355
+ }
356
+
357
+ message HtlcInfo {
358
+ // The timelock on the incoming htlc.
359
+ uint32 incoming_timelock = 1;
360
+
361
+ // The timelock on the outgoing htlc.
362
+ uint32 outgoing_timelock = 2;
363
+
364
+ // The amount of the incoming htlc.
365
+ uint64 incoming_amt_msat = 3;
366
+
367
+ // The amount of the outgoing htlc.
368
+ uint64 outgoing_amt_msat = 4;
369
+ }
370
+
371
+ message ForwardEvent {
372
+ // Info contains details about the htlc that was forwarded.
373
+ HtlcInfo info = 1;
374
+ }
375
+
376
+ message ForwardFailEvent {
377
+ }
378
+
379
+ message SettleEvent {
380
+ }
381
+
382
+ message LinkFailEvent {
383
+ // Info contains details about the htlc that we failed.
384
+ HtlcInfo info = 1;
385
+
386
+ // FailureCode is the BOLT error code for the failure.
387
+ lnrpc.Failure.FailureCode wire_failure = 2;
388
+
389
+ /**
390
+ FailureDetail provides additional information about the reason for the
391
+ failure. This detail enriches the information provided by the wire message
392
+ and may be 'no detail' if the wire message requires no additional metadata.
393
+ */
394
+ FailureDetail failure_detail = 3;
395
+
396
+ // A string representation of the link failure.
397
+ string failure_string = 4;
398
+ }
399
+
400
+ enum FailureDetail {
401
+ UNKNOWN = 0;
402
+ NO_DETAIL = 1;
403
+ ONION_DECODE = 2;
404
+ LINK_NOT_ELIGIBLE = 3;
405
+ ON_CHAIN_TIMEOUT = 4;
406
+ HTLC_EXCEEDS_MAX = 5;
407
+ INSUFFICIENT_BALANCE = 6;
408
+ INCOMPLETE_FORWARD = 7;
409
+ HTLC_ADD_FAILED = 8;
410
+ FORWARDS_DISABLED = 9;
411
+ INVOICE_CANCELED = 10;
412
+ INVOICE_UNDERPAID = 11;
413
+ INVOICE_EXPIRY_TOO_SOON = 12;
414
+ INVOICE_NOT_OPEN = 13;
415
+ MPP_INVOICE_TIMEOUT = 14;
416
+ ADDRESS_MISMATCH = 15;
417
+ SET_TOTAL_MISMATCH = 16;
418
+ SET_TOTAL_TOO_LOW = 17;
419
+ SET_OVERPAID = 18;
420
+ UNKNOWN_INVOICE = 19;
421
+ INVALID_KEYSEND = 20;
422
+ MPP_IN_PROGRESS = 21;
423
+ CIRCULAR_ROUTE = 22;
424
+ }
425
+
426
+ enum PaymentState {
427
+ /**
428
+ Payment is still in flight.
429
+ */
430
+ IN_FLIGHT = 0;
431
+
432
+ /**
433
+ Payment completed successfully.
434
+ */
435
+ SUCCEEDED = 1;
436
+
437
+ /**
438
+ There are more routes to try, but the payment timeout was exceeded.
439
+ */
440
+ FAILED_TIMEOUT = 2;
441
+
442
+ /**
443
+ All possible routes were tried and failed permanently. Or were no
444
+ routes to the destination at all.
445
+ */
446
+ FAILED_NO_ROUTE = 3;
447
+
448
+ /**
449
+ A non-recoverable error has occured.
450
+ */
451
+ FAILED_ERROR = 4;
452
+
453
+ /**
454
+ Payment details incorrect (unknown hash, invalid amt or
455
+ invalid final cltv delta)
456
+ */
457
+ FAILED_INCORRECT_PAYMENT_DETAILS = 5;
458
+
459
+ /**
460
+ Insufficient local balance.
461
+ */
462
+ FAILED_INSUFFICIENT_BALANCE = 6;
463
+ }
464
+
465
+ message PaymentStatus {
466
+ /// Current state the payment is in.
467
+ PaymentState state = 1;
468
+
469
+ /**
470
+ The pre-image of the payment when state is SUCCEEDED.
471
+ */
472
+ bytes preimage = 2;
473
+
474
+ reserved 3;
475
+
476
+ /**
477
+ The HTLCs made in attempt to settle the payment [EXPERIMENTAL].
478
+ */
479
+ repeated lnrpc.HTLCAttempt htlcs = 4;
480
+ }
481
+
482
+ service Router {
483
+ /**
484
+ SendPaymentV2 attempts to route a payment described by the passed
485
+ PaymentRequest to the final destination. The call returns a stream of
486
+ payment updates.
487
+ */
488
+ rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment);
489
+
490
+ /**
491
+ TrackPaymentV2 returns an update stream for the payment identified by the
492
+ payment hash.
493
+ */
494
+ rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment);
495
+
496
+ /**
497
+ EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it
498
+ may cost to send an HTLC to the target end destination.
499
+ */
500
+ rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse);
501
+
502
+ /**
503
+ SendToRoute attempts to make a payment via the specified route. This method
504
+ differs from SendPayment in that it allows users to specify a full route
505
+ manually. This can be used for things like rebalancing, and atomic swaps.
506
+ */
507
+ rpc SendToRoute (SendToRouteRequest) returns (SendToRouteResponse);
508
+
509
+ /**
510
+ ResetMissionControl clears all mission control state and starts with a clean
511
+ slate.
512
+ */
513
+ rpc ResetMissionControl (ResetMissionControlRequest)
514
+ returns (ResetMissionControlResponse);
515
+
516
+ /**
517
+ QueryMissionControl exposes the internal mission control state to callers.
518
+ It is a development feature.
519
+ */
520
+ rpc QueryMissionControl (QueryMissionControlRequest)
521
+ returns (QueryMissionControlResponse);
522
+
523
+ /**
524
+ QueryProbability returns the current success probability estimate for a
525
+ given node pair and amount.
526
+ */
527
+ rpc QueryProbability (QueryProbabilityRequest)
528
+ returns (QueryProbabilityResponse);
529
+
530
+ /**
531
+ BuildRoute builds a fully specified route based on a list of hop public
532
+ keys. It retrieves the relevant channel policies from the graph in order to
533
+ calculate the correct fees and time locks.
534
+ */
535
+ rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse);
536
+
537
+ /**
538
+ SubscribeHtlcEvents creates a uni-directional stream from the server to
539
+ the client which delivers a stream of htlc events.
540
+ */
541
+ rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest)
542
+ returns (stream HtlcEvent);
543
+
544
+ /**
545
+ Deprecated, use SendPaymentV2. SendPayment attempts to route a payment
546
+ described by the passed PaymentRequest to the final destination. The call
547
+ returns a stream of payment status updates.
548
+ */
549
+ rpc SendPayment(SendPaymentRequest) returns (stream PaymentStatus) {
550
+ option deprecated = true;
551
+ }
552
+
553
+ /**
554
+ Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for
555
+ the payment identified by the payment hash.
556
+ */
557
+ rpc TrackPayment(TrackPaymentRequest) returns (stream PaymentStatus) {
558
+ option deprecated = true;
559
+ }
560
+ }