Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bumi/lnrpc

a gRPC client for the Lightning Network Daemin (LND) packed as rubygem
https://github.com/bumi/lnrpc

bitcoin grpc lightning lightning-network lnd ruby

Last synced: 2 months ago
JSON representation

a gRPC client for the Lightning Network Daemin (LND) packed as rubygem

Awesome Lists containing this project

README 

        
# Lnrpc - ruby gRPC client for LND

[![Gem Version](https://badge.fury.io/rb/lnrpc.svg)](https://badge.fury.io/rb/lnrpc)



a [gRPC](https://grpc.io/) client for [LND, the Lightning Network Daemon](https://github.com/lightningnetwork/lnd/) packed as ruby gem.



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'lnrpc', '~> 0.15.5'

```

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)).



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 definitions](https://github.com/lightningnetwork/lnd/tree/master/lnrpc) available.  



```ruby

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](https://grpc.io/) on [gRPC.io](https://grpc.io/).



The LND API reference can be found here: [https://api.lightning.community/](https://api.lightning.community/)



### Example



```ruby

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](https://github.com/bumi/lnrpc/blob/master/lib/lnrpc/client.rb)) makes

initializing the gRPC client easier and removes the need for some boilerplate code for calling RPC methods.



#### Example

```ruby

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.lightning.get_info

```



Also have a look at [examples.rb](https://github.com/bumi/lnrpc/blob/master/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.



```ruby

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:



```ruby

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.](https://medium.com/@BtcpayServer/launch-btcpay-server-via-web-interface-and-deploy-full-bitcoin-node-lnd-in-less-than-a-minute-dc8bc6f06a3)



## 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](https://rubygems.org/gems/lnrpc) 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



+ 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



## 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)



## 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](https://opensource.org/licenses/MIT).