2018-01-10 19:21:03 +01:00
# How to write a Ruby gRPC client for the Lightning Network Daemon
This section enumerates what you need to do to write a client that communicates
with `lnd` in Ruby.
### Introduction
`lnd` uses the `gRPC` protocol for communication with clients like `lncli` .
`gRPC` is based on protocol buffers and as such, you will need to compile
the `lnd` proto file in Ruby before you can use it to communicate with `lnd` .
### Setup
Install gRPC rubygems:
2021-01-17 14:58:57 +01:00
```shell
⛰ gem install grpc
⛰ gem install grpc-tools
2018-01-10 19:21:03 +01:00
```
Clone the Google APIs repository:
2021-01-17 14:58:57 +01:00
```shell
⛰ git clone https://github.com/googleapis/googleapis.git
2018-01-10 19:21:03 +01:00
```
Fetch the `rpc.proto` file (or copy it from your local source directory):
2021-01-17 14:58:57 +01:00
```shell
⛰ curl -o rpc.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/rpc.proto
2018-01-10 19:21:03 +01:00
```
Compile the proto file:
2021-01-17 14:58:57 +01:00
```shell
⛰ grpc_tools_ruby_protoc --proto_path googleapis:. --ruby_out= . --grpc_out= . rpc.proto
2018-01-10 19:21:03 +01:00
```
Two files will be generated in the current directory:
* `rpc_pb.rb`
* `rpc_services_pb.rb`
2018-05-25 12:15:23 +10:00
### Examples
#### Simple client to display wallet balance
2018-01-10 19:21:03 +01:00
2018-02-07 09:30:09 +01:00
Every time you use the Ruby gRPC you need to require the `rpc_services_pb` file.
2018-01-10 19:21:03 +01:00
We assume that `lnd` runs on the default `localhost:10009` .
We further assume you run `lnd` with `--no-macaroons` .
```ruby
#!/usr/bin/env ruby
$: . unshift ( File . dirname ( __FILE__ ))
require 'grpc'
require 'rpc_services_pb'
2018-05-25 12:15:23 +10:00
# Due to updated ECDSA generated tls.cert we need to let gprc know that
# we need to use that cipher suite otherwise there will be a handhsake
# error when we communicate with the lnd rpc server.
ENV [ 'GRPC_SSL_CIPHER_SUITES' ] = "HIGH+ECDSA"
2018-01-10 19:21:03 +01:00
certificate = File . read ( File . expand_path ( "~/.lnd/tls.cert" ))
credentials = GRPC :: Core :: ChannelCredentials . new ( certificate )
stub = Lnrpc :: Lightning :: Stub . new ( '127.0.0.1:10009' , credentials )
response = stub . wallet_balance ( Lnrpc :: WalletBalanceRequest . new ())
puts "Total balance: #{ response . total_balance } "
```
This will show the `total_balance` of the wallet.
2018-05-25 12:15:23 +10:00
#### Streaming client for invoice payment updates
2018-01-10 19:21:03 +01:00
```ruby
#!/usr/bin/env ruby
$: . unshift ( File . dirname ( __FILE__ ))
require 'grpc'
require 'rpc_services_pb'
2018-05-25 12:15:23 +10:00
ENV [ 'GRPC_SSL_CIPHER_SUITES' ] = "HIGH+ECDSA"
2018-01-10 19:21:03 +01:00
certificate = File . read ( File . expand_path ( "~/.lnd/tls.cert" ))
credentials = GRPC :: Core :: ChannelCredentials . new ( certificate )
stub = Lnrpc :: Lightning :: Stub . new ( '127.0.0.1:10009' , credentials )
stub . subscribe_invoices ( Lnrpc :: InvoiceSubscription . new ) do | invoice |
puts invoice . inspect
end
```
Now, create an invoice on your node:
2021-01-17 14:58:57 +01:00
```shell
⛰ lncli addinvoice --amt= 590
2018-01-10 19:21:03 +01:00
{
"r_hash" : <R_HASH>,
"pay_req" : <PAY_REQ>
}
```
Next send a payment to it from another node:
2021-01-17 14:58:57 +01:00
```shell
⛰ lncli sendpayment --pay_req= <PAY_REQ>
2018-01-10 19:21:03 +01:00
```
You should now see the details of the settled invoice appear.
2018-05-25 12:15:23 +10:00
#### Using Macaroons
To authenticate using macaroons you need to include the macaroon in the metadata of the request.
```ruby
2018-08-22 16:11:20 -04:00
# Lnd admin macaroon is at ~/.lnd/data/chain/bitcoin/simnet/admin.macaroon on Linux and
# ~/Library/Application Support/Lnd/data/chain/bitcoin/simnet/admin.macaroon on Mac
macaroon_binary = File . read ( File . expand_path ( "~/.lnd/data/chain/bitcoin/simnet/admin.macaroon" ))
2018-05-25 12:15:23 +10:00
macaroon = macaroon_binary . each_byte . map { | b | b . to_s ( 16 ) . rjust ( 2 , '0' ) } . join
```
The simplest approach to use the macaroon is to include the metadata in each request as shown below.
```ruby
2018-10-26 13:24:30 -07:00
stub . get_info ( Lnrpc :: GetInfoRequest . new , metadata : { macaroon : macaroon })
2018-05-25 12:15:23 +10:00
```
However, this can get tiresome to do for each request. We can use gRPC interceptors to add this metadata to each request automatically. Our interceptor class would look like this.
```ruby
class MacaroonInterceptor < GRPC :: ClientInterceptor
attr_reader :macaroon
def initialize ( macaroon )
@macaroon = macaroon
super
end
def request_response ( request :, call :, method :, metadata :)
metadata [ 'macaroon' ] = macaroon
yield
end
2018-10-26 14:02:32 -07:00
def server_streamer ( request :, call :, method :, metadata :)
metadata [ 'macaroon' ] = macaroon
yield
end
2018-05-25 12:15:23 +10:00
end
```
And then we would include it when we create our stub like so.
```ruby
certificate = File . read ( File . expand_path ( "~/.lnd/tls.cert" ))
credentials = GRPC :: Core :: ChannelCredentials . new ( certificate )
2018-08-22 16:11:20 -04:00
macaroon_binary = File . read ( File . expand_path ( "~/.lnd/data/chain/bitcoin/simnet/admin.macaroon" ))
2018-05-25 12:15:23 +10:00
macaroon = macaroon_binary . each_byte . map { | b | b . to_s ( 16 ) . rjust ( 2 , '0' ) } . join
stub = Lnrpc :: Lightning :: Stub . new (
'localhost:10009' ,
credentials ,
interceptors : [ MacaroonInterceptor . new ( macaroon ) ]
)
# Now we don't need to pass the metadata on a request level
p stub . get_info ( Lnrpc :: GetInfoRequest . new )
```
2018-12-26 14:02:29 -08:00
#### Receive Large Responses
A GRPC::ResourceExhausted exception is raised when a server response is too large. In particular, this will happen with mainnet DescribeGraph calls. The solution is to raise the default limits by including a channel_args hash when creating our stub.
```ruby
stub = Lnrpc :: Lightning :: Stub . new (
'localhost:10009' ,
credentials ,
channel_args : { "grpc.max_receive_message_length" => 1024 * 1024 * 50 }
)
2021-01-17 14:58:57 +01:00
```