2019-02-12 05:22:07 +00:00
# Lnrpc - ruby gRPC client for LND
2019-07-03 15:30:43 +00:00
[![Gem Version ](https://badge.fury.io/rb/lnrpc.svg )](https://badge.fury.io/rb/lnrpc)
2019-02-08 05:51:42 +00:00
2019-02-12 17:48:39 +00:00
a [gRPC ](https://grpc.io/ ) client for [LND, the Lightning Network Daemon ](https://github.com/lightningnetwork/lnd/ ) packed as ruby gem.
2019-02-08 05:51:42 +00:00
## Installation
Add this line to your application's Gemfile:
```ruby
2023-03-10 10:03:32 +00:00
gem 'lnrpc', '~> 0.15.5'
2019-02-08 05:51:42 +00:00
```
2019-05-15 09:49:35 +00:00
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 )).
2019-02-08 05:51:42 +00:00
And then execute:
$ bundle
Or install it yourself as:
$ gem install lnrpc
2019-02-12 17:48:39 +00:00
# or for pre releases:
$ gem install lnrcp --pre
2019-02-08 05:51:42 +00:00
## Usage
2021-11-22 02:03:39 +00:00
This gem makes the gRPC client classes created from the [LND service definitions ](https://github.com/lightningnetwork/lnd/tree/master/lnrpc ) available.
2019-02-12 05:22:07 +00:00
```ruby
require "lnrpc"
2020-05-09 12:50:11 +00:00
# With the changes in LND v.10.0 this load the `Lnrpc` and `Routerrpc` namespace
2019-02-12 05:22:07 +00:00
Lnrpc::Lightning::Stub
2021-11-22 02:03:39 +00:00
Routerrpc::Routerrpc::Stub
2019-02-12 05:22:07 +00:00
Lnrpc::GetInfoRequest
2020-05-09 12:50:11 +00:00
...
2019-02-12 05:22:07 +00:00
```
Learn more about [gRPC ](https://grpc.io/ ) on [gRPC.io ](https://grpc.io/ ).
2019-02-12 05:15:04 +00:00
The LND API reference can be found here: [https://api.lightning.community/ ](https://api.lightning.community/ )
### Example
```ruby
require "lnrpc"
2019-05-15 09:30:46 +00:00
credentials = File.read("/path/to/tls.cert")
2019-02-12 05:15:04 +00:00
macaroon = File.read("/path/to/readonly.macaroon").unpack("H*")
# initialize a new client
client = Lnrpc::Lightning::Stub.new("localhost:10009", GRPC::Core::ChannelCredentials.new(self.credentials))
# perform a request
request = Lnrpc::GetInfoRequest.new
response = client.get_info(request, { metadata: { macaroon: macaroon } }) #=> Lnrpc::GetInfoResponse
2019-05-15 09:30:46 +00:00
puts response.alias
2020-05-09 12:50:11 +00:00
router = Routerprc::Router::Stub.new("localhost:10009", GRPC::Core::ChannelCredentials.new(self.credentials))
...
2019-02-12 05:15:04 +00:00
```
### Client wrapper
2020-05-09 12:50:11 +00:00
NOTE: v10.0 has breaking changes!
2019-05-15 09:30:46 +00:00
An optional client wrapper ([Lnrpc::Client](https://github.com/bumi/lnrpc/blob/master/lib/lnrpc/client.rb)) makes
2019-02-12 05:15:04 +00:00
initializing the gRPC client easier and removes the need for some boilerplate code for calling RPC methods.
2019-02-12 05:22:07 +00:00
#### Example
```ruby
lnd = Lnrpc::Client.new({credentials_path: '/path/to.cert.cls', macaroon_path: '/path/to/admin.macaroon'})
2020-05-09 12:50:11 +00:00
lnd.lightning # => Lnrpc::Lightning::Stub
lnd.router # => Lnrpc::Router::Stub
2021-07-14 03:14:49 +00:00
lnd.lightning.get_info
2019-02-12 05:22:07 +00:00
```
2019-02-12 06:06:58 +00:00
Also have a look at [examples.rb ](https://github.com/bumi/lnrpc/blob/master/examples.rb )
2019-02-12 05:15:04 +00:00
#### Initializing a new client
2019-05-15 09:30:46 +00:00
The Lnrpc::Client constructor allows the following options:
2019-02-12 05:15:04 +00:00
2019-05-15 09:30:46 +00:00
* credentials:
2019-03-04 19:14:35 +00:00
- `credentials` : the credentials data as string (pass nil if a "trusted" cert (e.g. from letsencrypt is used)
2019-03-04 19:20:05 +00:00
- `credentials_path` : the path to a credentials file (tls.cert) as string (default: `"#{LND_HOME_DIR}/tls.cert"` )
2019-05-15 09:30:46 +00:00
* macaroon:
2019-02-12 05:15:04 +00:00
- `macaroon` : the macaroon as hex string
2019-03-04 19:20:05 +00:00
- `macaroon_path` : the path to the macaroon file created by lnd as string (default: `"#{LND_HOME_DIR}/data/chain/bitcoin/mainnet/admin.macaroon"` )
2019-02-12 05:15:04 +00:00
* address:
2019-03-04 19:20:05 +00:00
- `address` : lnd address as string. format: address:port, e.g. localhost:10009 (default)
2019-02-12 05:15:04 +00:00
2019-05-15 09:30:46 +00:00
If no credentials or no macaroon is provided default files are assumed in `ENV['LND_HOME'] || "~/.lnd"` .
2019-03-04 19:20:05 +00:00
A macaroon is required.
2019-02-12 05:15:04 +00:00
```ruby
require 'lnrpc'
lnd = Lnrpc::Client.new({
2019-05-15 09:30:46 +00:00
credentials_path: '/path/to.cert.cls',
2019-02-12 05:15:04 +00:00
macaroon_path: '/path/to/admin.macaroon',
address: 'host:port'
})
# the actual gRPC client is available through:
2020-05-09 12:50:11 +00:00
lnd.lightning.grpc
lnd.router.grpc
2019-02-12 05:15:04 +00:00
```
#### Calling RPC methods
The client wrapper passes any supported RPC method call to the gRPC client applying the following conventions:
2019-05-15 09:30:46 +00:00
If the first parameter is a hash or blank the corresponding gRPC request object will be instantiated.
2019-02-12 05:15:04 +00:00
Example:
```ruby
2020-05-09 12:50:11 +00:00
client.lightning.get_info
2019-05-15 09:30:46 +00:00
# is the same as:
2020-05-09 12:50:11 +00:00
client.lightning.grpc.get_info(Lnrpc::GetInfoRequest.new)
2019-02-12 05:15:04 +00:00
2020-05-09 12:50:11 +00:00
client.lightning.list_channels(inactive_only: true)
2019-05-15 09:30:46 +00:00
# is the same as:
2019-02-12 06:21:55 +00:00
request = Lnrpc::ListChannelsRequest.new(inactive_only: true)
2020-05-09 12:50:11 +00:00
client.lightning.grpc.list_channels(request)
2019-02-12 06:21:55 +00:00
2020-05-09 12:50:11 +00:00
client.lightning.wallet_balance.total_balance
2019-05-15 09:30:46 +00:00
# is the same as:
2021-11-22 02:03:39 +00:00
request = Lnrpc::WalletBalanceRequest.new
2020-05-09 12:50:11 +00:00
client.lightning.grpc.wallet_balance(request).total_balance
2019-02-12 05:15:04 +00:00
```
2019-03-07 23:45:29 +00:00
## Using with BTC Pay Server
If you have a running BTC Pay Server with LND support, integrating with lnrpc is easy.
- Navigate to the domain associated with your BTC Pay Server
- Navigate to Services on the Server Settings page
- Click "see information" for your gRPC Server
- The link by "More details..." will expose the address and various macaroon hex strings
2021-11-22 02:03:39 +00:00
- Initialize your client with the options detailed above. BTC Pay Server utilizes LetsEncrypt for trusted TLC Certificates so set that option to nil.
2019-03-07 23:45:29 +00:00
Don't have a BTC Pay Server? [Setting one up is easy. ](https://medium.com/@BtcpayServer/launch-btcpay-server-via-web-interface-and-deploy-full-bitcoin-node-lnd-in-less-than-a-minute-dc8bc6f06a3 )
2019-05-15 09:30:46 +00:00
2019-02-12 05:15:04 +00:00
## Versioning
2019-05-15 09:30:46 +00:00
This gem follows the LND versions and will update the gRPC service definitions accordingly.
2019-02-12 05:15:04 +00:00
e.g. gem version 0.5.2 includes the gRPC service definitions from LND v0.5.2
2019-05-15 09:49:35 +00:00
see [rubygems ](https://rubygems.org/gems/lnrpc ) for all available releases.
2019-02-12 05:15:04 +00:00
2019-05-15 09:30:46 +00:00
### Update service definitions
2020-08-28 12:37:57 +00:00
The script `generate-grpc-service-files.sh` can be used to generate the GRPC ruby files.
The files will be stored in `lib/grpc_services`
2019-05-15 09:30:46 +00:00
2020-08-28 12:37:57 +00:00
$ ./generate-grpc-service-files.sh
2019-05-15 09:30:46 +00:00
2021-07-09 18:28:06 +00:00
+ Make sure you have the [grpc-tools ](https://rubygems.org/gems/grpc-tools ) installed
+ Make sure you have the lnd source in your $GOPATH/src folder
2020-05-09 12:50:11 +00:00
2019-02-12 05:15:04 +00:00
## Other resources
* [LND gRPC API Reference ](https://api.lightning.community )
* [LND Developer Site ](https://dev.lightning.community/ )
* [gRPC Ruby quick start ](https://grpc.io/docs/quickstart/ruby.html )
2019-02-08 05:51:42 +00:00
## Contributing
2019-02-08 05:53:44 +00:00
Bug reports and pull requests are welcome on GitHub at https://github.com/bumi/lnrpc.
2019-02-08 05:51:42 +00:00
## License
The gem is available as open source under the terms of the [MIT License ](https://opensource.org/licenses/MIT ).