lnrpc 0.5.2.beta → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9f1749c1fa4257d3624d77aa15e4b8d47f1c6ef2bc19c33965a9bbc8c544b39
-  data.tar.gz: b7792de3c448b8a2d53376befe522bdfa819e15cecd0387934742233152a5912
+  metadata.gz: 4079c08041cc28f7f4f489ac59fb3223aab2621845c994b7bcad33fc36bef99b
+  data.tar.gz: d01a5e679555dab57793833fe1614fafd9cc7fe9c25961eee2ea72795e16b169
 SHA512:
-  metadata.gz: 27ebcf6544a548ab97d5bdeeb2452ebdaa5f5ea1a1870339e8c54e38e23b576c15dfb1ea6b0a5421e854beed8ccc645f8dbd5cc6c030e61f19d9a834b28e1f31
-  data.tar.gz: f3fa6207e3c74da86a8d4054163eb028be1b07ef146b4be10370da210c11684f46503c18d9d67ddfae332c67e1e61b34c8a3a9615a4161ced4a266e394751d64
+  metadata.gz: 3488c416c8ff54a371e81256dfe9cc7a9f2144a8d7a53f7f73f8c48b7410899f1c4a26be01ce51a840d2de1aacdc0030e3668d183a2930213c79ef051ed4cf93
+  data.tar.gz: 270b6e3681a5e59ca790b94f2ed35381e936b39b20b50524ffe9c8b44965fcfc4d1095d3957df4360a4315fcfce21ef165322ca12e825a6463396c867e84180d

data/Gemfile.lock

@@ -1,17 +1,18 @@
 PATH
   remote: .
   specs:
-    lnrpc (0.1.0)
-      grpc (>= 1.16.0)
+    lnrpc (0.5.2.beta)
+      google-protobuf (>= 3.7)
+      grpc (>= 1.19.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.3)
-    google-protobuf (3.6.1)
+    google-protobuf (3.7.0)
     googleapis-common-protos-types (1.0.3)
       google-protobuf (~> 3.0)
-    grpc (1.18.0)
+    grpc (1.19.0)
       google-protobuf (~> 3.1)
       googleapis-common-protos-types (~> 1.0.0)
     rake (10.5.0)

data/README.md

@@ -1,8 +1,9 @@
-# Lnrpc
+# Lnrpc - ruby gRPC client for LND
 
-gRPC service definitions for lnd packed as ruby gem. 
+a [gRPC](https://grpc.io/) client for [LND, the Lightning Network Daemon](https://github.com/lightningnetwork/lnd/) packed as ruby gem.
+
+Currently published as [beta release](https://rubygems.org/gems/lnrpc) to rubygems for LND v0.5.2.beta. (see [#Versioning](#Versioning))
 
-currently highly experimental and subject to change. 
 
 ## Installation
 
@@ -19,10 +20,119 @@ And then execute:
 Or install it yourself as:
 
     $ gem install lnrpc
+    # or for pre releases:
+    $ gem install lnrcp --pre
 
 ## Usage
 
-TODO: Write usage instructions here
+This gem makes the gRPC client classes created from the [LND service defintions](https://github.com/lightningnetwork/lnd/tree/master/lnrpc) available.  
+
+```ruby
+require "lnrpc"
+
+# the gRPC client is available under the Lnrpc namespace, e.g. 
+
+Lnrpc::Lightning::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 
+```
+
+### Client wrapper
+
+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.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
+  - `credentials_path` : the path to a credentials file (tls.cert) as string
+* macaroon: 
+  - `macaroon` : the macaroon as hex string
+  - `macaroon_path` : the path to the macaroon file created by lnd as string
+* address:
+  - `address` : lnd address as string. format: address:port, e.g. default: localhost:10009
+
+
+```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.grpc_client
+```
+
+#### 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.get_info
+# is the same as: 
+client.grpc_client.get_info(Lnrpc::GetInfoRequest.new)
+
+client.list_channels(inactive_only: true)
+# is the same as: 
+request = Lnrpc::ListChannelsRequest.new(inactive_only: true)
+client.grpc_client.list_channels(request)
+
+client.wallet_balance.total_balance
+# is the same as: 
+request = Lnrpc::WalletBalanceRequest.new()
+client.grpc_client.wallet_balance(request).total_balance
+```
+
+
+## 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
+
+
+## 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
 

data/examples.rb

@@ -0,0 +1,15 @@
+require "lnrpc"
+
+lnd = Lnrpc::Client.new() # use defaults for credentials, macaraoon and address
+
+get_info_res = lnd.get_info
+puts get_info_res.alias
+
+puts lnd.wallet_balance.total_balance
+
+pay_request = "lntb50u1pw9mmndpp5nvnff958pxc9eqknwntyxapjw7l5grt5e2y70cmmnu0lljfa0sdqdpsgfkx7cmtwd68yetpd5s9xct5v4kxc6t5v5s8yatz0ysxwetdcqzysxqyz5vqjkhlyn40z76gyn7dx32p9j58dftve9xrlvnqqazht7w2fdauukhyhr9y4k3ngjn8s6srglj8swk7tm70ng54wdkq47ahytpwffvaeusp500csz"
+lnd.pay(pay_request) # or:
+lnd.send_payment_sync(payment_request: pay_request)
+
+invoice_res = lnd.add_invoice(value: 1000, memo: 'I :heart: ruby')
+puts invoice_res.payment_request

data/lib/lnrpc/client.rb

@@ -1,3 +1,5 @@
+require "grpc"
+require "lnrpc/macaroon_interceptor"
 module Lnrpc
   class Client
     attr_accessor :address, :credentials, :macaroon, :grpc_client
@@ -7,6 +9,25 @@ module Lnrpc
     DEFAULT_CREDENTIALS_PATH = "#{LND_HOME_DIR}/tls.cert"
     DEFAULT_MACAROON_PATH = "#{LND_HOME_DIR}/data/chain/bitcoin/mainnet/admin.macaroon"
 
+    NON_CONVENTION_REQUEST_CLASSES = {
+      add_invoice: Lnrpc::Invoice,
+      send_payment: Lnrpc::SendRequest,
+      send_payment_sync: Lnrpc::SendRequest,
+      open_channel_sync: Lnrpc::OpenChannelRequest,
+      send_to_route_sync: Lnrpc::SendToRouteRequest,
+      lookup_invoice: Lnrpc::PaymentHash,
+      decode_pay_req: Lnrpc::PayReqString,
+      describe_graph: Lnrpc::ChannelGraphRequest,
+      get_chan_info: Lnrpc::ChanInfoRequest,
+      get_node_info: Lnrpc::NodeInfoRequest,
+      get_network_info: Lnrpc::NetworkInfoRequest,
+      stop_daemon: Lnrpc::StopRequest,
+      update_channel_policy: Lnrpc::PolicyUpdateResponse,
+      subscribe_channel_graph: Lnrpc::GraphTopologySubscription,
+      subscribe_invoices: Lnrpc::InvoiceSubscription,
+      subscribe_transactions: Lnrpc::GetTransactionsRequest
+    }
+
     def initialize(options={})
       self.address = options[:address] || DEFAULT_ADDRESS
 
@@ -19,7 +40,10 @@ module Lnrpc
       end
       self.macaroon = options[:macaroon]
 
-      self.grpc_client = Lnrpc::Lightning::Stub.new(self.address, GRPC::Core::ChannelCredentials.new(self.credentials))
+      self.grpc_client = Lnrpc::Lightning::Stub.new(self.address,
+                                                    GRPC::Core::ChannelCredentials.new(self.credentials),
+                                                    interceptors: [Lnrpc::MacaroonInterceptor.new(self.macaroon)]
+                                                   )
     end
 
     def pay(payreq)
@@ -29,20 +53,27 @@ module Lnrpc
     def method_missing(m, *args, &block)
       if self.grpc_client.respond_to?(m)
         params  = args[0]
-        options = args[1] || { metadata: { macaroon: self.macaroon } }
 
-        request = params.nil? ? request_class_for(m).new : request_class_for(m).new(params)
-        self.grpc_client.send(m, request, options)
+        args[0] = params.nil? ? request_class_for(m).new : request_class_for(m).new(params)
+        self.grpc_client.send(m, *args)
       else
         super
       end
     end
 
+    def inspect
+      "#{self.to_s} @address=\"#{self.address}\""
+    end
+
     private
     def request_class_for(method_name)
-      string = method_name.to_s.sub(/^[a-z\d]*/) { |match| match.capitalize }
-      string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
-      Lnrpc.const_get("#{string}Request")
+      if NON_CONVENTION_REQUEST_CLASSES.key?(method_name.to_sym)
+        NON_CONVENTION_REQUEST_CLASSES[method_name.to_sym]
+      else
+        klass = method_name.to_s.sub(/^[a-z\d]*/) { |match| match.capitalize }
+        klass.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
+        Lnrpc.const_get("#{klass}Request")
+      end
     end
   end
 end

data/lib/lnrpc/macaroon_interceptor.rb

@@ -0,0 +1,22 @@
+require "grpc"
+
+module Lnrpc
+  class MacaroonInterceptor < GRPC::ClientInterceptor
+    def initialize(macaroon_hex)
+      @macaroon = macaroon_hex
+    end
+
+    def inject_macaroon_metadata(request:, call:, method:, metadata:)
+      if !metadata.has_key?('macaroon') && !metadata.has_key?(:macaroon)
+        metadata[:macaroon] = @macaroon
+      end
+      yield
+    end
+
+    alias :request_response :inject_macaroon_metadata
+    alias :client_streamer :inject_macaroon_metadata
+    alias :server_streamer :inject_macaroon_metadata
+    alias :bidi_streamer :inject_macaroon_metadata
+
+  end
+end

data/lib/lnrpc/version.rb

@@ -1,3 +1,3 @@
 module Lnrpc
-  VERSION = "0.5.2.beta"
+  VERSION = "0.5.2"
 end

data/lib/lnrpc.rb

@@ -4,6 +4,7 @@ require "lnrpc/rpc_services_pb"
 module Lnrpc
   class Error < StandardError; end
   autoload :Client, 'lnrpc/client'
+  autoload :MacaroonInterceptor, 'lnrpc/macaroon_interceptor'
 end
 
 

data/lnrpc.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["hello@michaelbumann.com"]
 
   spec.summary       = %q{gRPC interface for lnd packed as ruby gem}
-  spec.description   = %q{gRPC service definitions for the Lightning Network Daemon (lnd) gRPC interace packed as ruby gem}
+  spec.description   = %q{gRPC service definitions for the Lightning Network Daemon (lnd) gRPC interface packed as ruby gem}
   spec.homepage      = "https://github.com/bumi/lnrpc"
   spec.license       = "MIT"
 
@@ -27,5 +27,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   
-  spec.add_dependency "grpc", ">= 1.16.0"
+  spec.add_dependency "grpc", ">= 1.19.0"
+  spec.add_dependency "google-protobuf", ">=3.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lnrpc
 version: !ruby/object:Gem::Version
-  version: 0.5.2.beta
+  version: 0.5.2
 platform: ruby
 authors:
 - Michael Bumann
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-02-12 00:00:00.000000000 Z
+date: 2019-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -58,16 +58,30 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.16.0
+        version: 1.19.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.16.0
+        version: 1.19.0
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
 description: gRPC service definitions for the Lightning Network Daemon (lnd) gRPC
-  interace packed as ruby gem
+  interface packed as ruby gem
 email:
 - hello@michaelbumann.com
 executables: []
@@ -83,8 +97,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples.rb
 - lib/lnrpc.rb
 - lib/lnrpc/client.rb
+- lib/lnrpc/macaroon_interceptor.rb
 - lib/lnrpc/rpc.proto
 - lib/lnrpc/rpc_pb.rb
 - lib/lnrpc/rpc_services_pb.rb
@@ -105,9 +121,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.7.6