Go to file
bumi 9b1499616d Add PaymentResponse wrapper
This is an experimental wrapper around the send_payment shortcut calls.
The goal is to provide a simple interface to check if the payment was
successful.
2020-08-29 19:40:45 +02:00
bin hello lnd world 2019-02-08 06:51:42 +01:00
lib Add PaymentResponse wrapper 2020-08-29 19:40:45 +02:00
spec hello lnd world 2019-02-08 06:51:42 +01:00
.gitignore gitignore build .gem files 2020-05-09 14:37:08 +02:00
.rspec hello lnd world 2019-02-08 06:51:42 +01:00
Gemfile hello lnd world 2019-02-08 06:51:42 +01:00
Gemfile.lock v0.10.0 with support for routerrpc 2020-05-09 14:37:08 +02:00
LICENSE.txt hello lnd world 2019-02-08 06:51:42 +01:00
README.md Add script to generate LND ruby GRPC service files 2020-08-28 14:37:57 +02:00
Rakefile hello lnd world 2019-02-08 06:51:42 +01:00
examples.rb Update examples.rb 2020-07-03 16:29:03 +02:00
generate-grpc-service-files.sh Add script to generate LND ruby GRPC service files 2020-08-28 14:37:57 +02:00
lnrpc.gemspec Add support for v0.11 GRPC services 2020-08-28 14:14:50 +02:00

README.md

Lnrpc - ruby gRPC client for LND

Gem Version

a gRPC client for LND, the Lightning Network Daemon packed as ruby gem.

Installation

Note: there is still an GRPC/protobuf issue with Ruby 2.7. So lnrpc requires Ruby < 2.7.

Add this line to your application's Gemfile:

gem 'lnrpc', '~> 0.10.0'

lnrpc follows the lnd versioning, thus it is recommended to specify the exact version you need for your lnd node as dependency (see #Versioning).

And then execute:

$ bundle

Or install it yourself as:

$ gem install lnrpc
# or for pre releases:
$ gem install lnrcp --pre

Usage

This gem makes the gRPC client classes created from the LND service defintions available.

require "lnrpc"

# With the changes in LND v.10.0 this load the `Lnrpc` and `Routerrpc` namespace

Lnrpc::Lightning::Stub
Routerrpc:::Routerrpc::Stub
Lnrpc::GetInfoRequest
...

Learn more about gRPC on gRPC.io.

The LND API reference can be found here: https://api.lightning.community/

Example

require "lnrpc"

credentials = File.read("/path/to/tls.cert")
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
puts response.alias

router = Routerprc::Router::Stub.new("localhost:10009", GRPC::Core::ChannelCredentials.new(self.credentials))
...

Client wrapper

NOTE: v10.0 has breaking changes!

An optional client wrapper (Lnrpc::Client) makes initializing the gRPC client easier and removes the need for some boilerplate code for calling RPC methods.

Example

lnd = Lnrpc::Client.new({credentials_path: '/path/to.cert.cls', macaroon_path: '/path/to/admin.macaroon'})
lnd.lightning # => Lnrpc::Lightning::Stub
lnd.router # => Lnrpc::Router::Stub

lnd.ligthning.get_info

Also have a look at examples.rb

Initializing a new client

The Lnrpc::Client constructor allows the following options:

  • credentials:
    • credentials : the credentials data as string (pass nil if a "trusted" cert (e.g. from letsencrypt is used)
    • credentials_path : the path to a credentials file (tls.cert) as string (default: "#{LND_HOME_DIR}/tls.cert" )
  • macaroon:
    • macaroon : the macaroon as hex string
    • macaroon_path : the path to the macaroon file created by lnd as string (default: "#{LND_HOME_DIR}/data/chain/bitcoin/mainnet/admin.macaroon")
  • address:
    • address : lnd address as string. format: address:port, e.g. localhost:10009 (default)

If no credentials or no macaroon is provided default files are assumed in ENV['LND_HOME'] || "~/.lnd". A macaroon is required.

require 'lnrpc'

lnd = Lnrpc::Client.new({
  credentials_path: '/path/to.cert.cls',
  macaroon_path: '/path/to/admin.macaroon',
  address: 'host:port'
})

# the actual gRPC client is available through:
lnd.lightning.grpc
lnd.router.grpc

Calling RPC methods

The client wrapper passes any supported RPC method call to the gRPC client applying the following conventions:

If the first parameter is a hash or blank the corresponding gRPC request object will be instantiated.

Example:

client.lightning.get_info
# is the same as:
client.lightning.grpc.get_info(Lnrpc::GetInfoRequest.new)

client.lightning.list_channels(inactive_only: true)
# is the same as:
request = Lnrpc::ListChannelsRequest.new(inactive_only: true)
client.lightning.grpc.list_channels(request)

client.lightning.wallet_balance.total_balance
# is the same as:
request = Lnrpc::WalletBalanceRequest.new()
client.lightning.grpc.wallet_balance(request).total_balance

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
  • Initialize your client with the options detailed above. BTC Pay Server utilizes LetsEncrypt for trusted TLC Certificates so set that option to nil.

Don't have a BTC Pay Server? Setting one up is easy.

Versioning

This gem follows the LND versions and will update the gRPC service definitions accordingly. e.g. gem version 0.5.2 includes the gRPC service definitions from LND v0.5.2

see rubygems for all available releases.

Update service definitions

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

$ ./generate-grpc-service-files.sh

Other resources

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bumi/lnrpc.

License

The gem is available as open source under the terms of the MIT License.