lighstorm 0.0.9 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 551ffb5be38f96d6c0bb4f7b8fbde5763c623f0d100f0a1b34acb90a6074fb23
-  data.tar.gz: 59451d54f2ad6d45c95c7649ab0a048a4adeb7a15f1af08f133d8eaae107d9bc
+  metadata.gz: 6072337300f3fd850fbca3ba5c7c804842c275d5f35fa288dfb83747fa0b1a56
+  data.tar.gz: 8a16d83cb96f0ed911ebd55e12707b20f0aac00a0acac8d176e544a68abad647
 SHA512:
-  metadata.gz: 54e1e6929a1f5dc67f319461d6fc3799dd5cd5c349224c19198a6bffd203bd3e6431fb6bf571976c2a1c0d3d1d07ceb9cb272206f06794c52595c4ec8d5d57d3
-  data.tar.gz: a903325535c6c2e98b95c4e54cb51f7bbd7123b40dfb2b9143fc9d7a392290230f1bb026c7bd30a669c8f981286ef56acfe0a2bf3751ea9cce5a4d663e160d61
+  metadata.gz: 3ccb6cef3322fcd1c0efb1439ddaf756e631113fbc7544218d10d6f71d08ca2ad80cf08b029ae4145e6916dcefc9ee3683124567bb952b02bf70793cc794616b
+  data.tar.gz: 2755ec9d8c2bf041459be7292983103c880f032e5e1e315ce2da2cc97ff945bbfb9f4083259a0c88ec22df8cd0301282c8ea376d63371a438ad58677b7f3d9e6

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lighstorm (0.0.9)
+    lighstorm (0.0.11)
       dotenv (~> 2.8, >= 2.8.1)
       lnd-client (~> 0.0.5)
       zache (~> 0.12.0)
@@ -47,7 +47,7 @@ GEM
     rspec-expectations (3.12.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.3)
+    rspec-mocks (3.12.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)

data/README.md

@@ -34,7 +34,7 @@ Although it tries to stay close to [Lightning's terminologies](https://docs.ligh
 Add to your `Gemfile`:
 
 ```ruby
-gem 'lighstorm', '~> 0.0.9'
+gem 'lighstorm', '~> 0.0.11'
 ```
 
 ```ruby
@@ -46,15 +46,22 @@ Lighstorm.config!(
   macaroon_path: '/lnd/data/chain/bitcoin/mainnet/admin.macaroon',
 )
 
-puts Lighstorm.version # => 0.0.9
+puts Lighstorm.version # => 0.0.11
 
 Lighstorm::Node.myself.alias # => icebaker/old-stone
 
 Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1_000,
+  description: 'Coffee',
+  amount: { millisatoshis: 1_000 },
   payable: 'once'
 )
 
+Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay
+
+Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay(
+  fee: { maximum: { millisatoshis: 1000 } }
+)
+
 Lighstorm::Satoshis.new(
   millisatoshis: 75_621_650
 ).satoshis # => 75_621

data/adapters/invoice.rb

@@ -18,7 +18,7 @@ module Lighstorm
         }
       end
 
-      def self.decode_pay_req(grpc, request_code = nil)
+      def self.decode_pay_req(grpc, code = nil)
         adapted = {
           _source: :decode_pay_req,
           _key: Digest::SHA256.hexdigest(
@@ -43,7 +43,7 @@ module Lighstorm
           }
         }
 
-        adapted[:code] = request_code unless request_code.nil?
+        adapted[:code] = code unless code.nil?
 
         if grpc[:features].key?(30) && grpc[:features][30][:is_required]
           raise "unexpected feature[30] name #{grpc[:features][30][:name]}" if grpc[:features][30][:name] != 'amp'

data/controllers/invoice/actions/create.rb

@@ -16,7 +16,7 @@ module Lighstorm
           ).to_h
         end
 
-        def self.prepare(payable:, expires_in:, description: nil, millisatoshis: nil)
+        def self.prepare(payable:, expires_in:, description: nil, amount: nil)
           request = {
             service: :lightning,
             method: :add_invoice,
@@ -28,7 +28,7 @@ module Lighstorm
             }
           }
 
-          request[:params][:value_msat] = millisatoshis unless millisatoshis.nil?
+          request[:params][:value_msat] = amount[:millisatoshis] unless amount.nil?
 
           if payable.to_sym == :indefinitely
             request[:params][:is_amp] = true
@@ -55,10 +55,10 @@ module Lighstorm
           FindBySecretHash.model(data)
         end
 
-        def self.perform(payable:, expires_in:, description: nil, millisatoshis: nil, preview: false, &vcr)
+        def self.perform(payable:, expires_in:, description: nil, amount: nil, preview: false, &vcr)
           grpc_request = prepare(
             description: description,
-            millisatoshis: millisatoshis,
+            amount: amount,
             expires_in: expires_in,
             payable: payable
           )

data/controllers/invoice/actions/pay.rb

@@ -18,8 +18,8 @@ module Lighstorm
           Payment::Pay.dispatch(grpc_request, &vcr)
         end
 
-        def self.fetch(request_code, &vcr)
-          Payment::Pay.fetch(request_code, &vcr)
+        def self.fetch(code, &vcr)
+          Payment::Pay.fetch(code, &vcr)
         end
 
         def self.adapt(data, node_get_info)
@@ -30,19 +30,23 @@ module Lighstorm
           Payment::Pay.model(data)
         end
 
-        def self.prepare(request_code:, times_out_in:, millisatoshis: nil, message: nil)
+        def self.prepare(code:, times_out_in:, amount: nil, fee: nil, message: nil)
           request = {
             service: :router,
             method: :send_payment_v2,
             params: {
-              payment_request: request_code,
+              payment_request: code,
               timeout_seconds: Helpers::TimeExpression.seconds(times_out_in),
               allow_self_payment: true,
               dest_custom_records: {}
             }
           }
 
-          request[:params][:amt_msat] = millisatoshis unless millisatoshis.nil?
+          request[:params][:amt_msat] = amount[:millisatoshis] unless amount.nil?
+
+          unless fee.nil? || fee[:maximum].nil? || fee[:maximum][:millisatoshis].nil?
+            request[:params][:fee_limit_msat] = fee[:maximum][:millisatoshis]
+          end
 
           if !message.nil? && !message.empty?
             # https://github.com/satoshisstream/satoshis.stream/blob/main/TLV_registry.md
@@ -55,11 +59,15 @@ module Lighstorm
         end
 
         def self.perform(
-          times_out_in:, request_code:, millisatoshis: nil, message: nil, preview: false, &vcr
+          times_out_in:, code:,
+          amount: nil, fee: nil,
+          message: nil,
+          preview: false, &vcr
         )
           grpc_request = prepare(
-            request_code: request_code,
-            millisatoshis: millisatoshis,
+            code: code,
+            amount: amount,
+            fee: fee,
             message: message,
             times_out_in: times_out_in
           )
@@ -70,7 +78,7 @@ module Lighstorm
 
           Payment::Pay.raise_error_if_exists!(response)
 
-          data = fetch(request_code, &vcr)
+          data = fetch(code, &vcr)
 
           adapted = adapt(response, data)
 

data/controllers/invoice/decode.rb

@@ -8,17 +8,17 @@ module Lighstorm
   module Controllers
     module Invoice
       module Decode
-        def self.fetch(request_code)
+        def self.fetch(code)
           {
-            _request_code: request_code,
-            decode_pay_req: Ports::GRPC.lightning.decode_pay_req(pay_req: request_code).to_h
+            _code: code,
+            decode_pay_req: Ports::GRPC.lightning.decode_pay_req(pay_req: code).to_h
           }
         end
 
         def self.adapt(raw)
           {
             decode_pay_req: Lighstorm::Adapter::Invoice.decode_pay_req(
-              raw[:decode_pay_req], raw[:_request_code]
+              raw[:decode_pay_req], raw[:_code]
             )
           }
         end
@@ -27,8 +27,8 @@ module Lighstorm
           adapted[:decode_pay_req]
         end
 
-        def self.data(request_code, &vcr)
-          raw = vcr.nil? ? fetch(request_code) : vcr.call(-> { fetch(request_code) })
+        def self.data(code, &vcr)
+          raw = vcr.nil? ? fetch(code) : vcr.call(-> { fetch(code) })
 
           adapted = adapt(raw)
 

data/controllers/invoice/find_by_code.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../../ports/grpc'
+require_relative '../../adapters/invoice'
+require_relative '../../models/invoice'
+
+module Lighstorm
+  module Controllers
+    module Invoice
+      module FindByCode
+        def self.fetch(code)
+          at = Time.now
+
+          decoded = Ports::GRPC.lightning.decode_pay_req(pay_req: code).to_h
+
+          { response: {
+            at: at,
+            decode_pay_req: decoded,
+            lookup_invoice: Ports::GRPC.lightning.lookup_invoice(r_hash_str: decoded[:payment_hash]).to_h
+          }, exception: nil }
+        rescue StandardError => e
+          { exception: e }
+        end
+
+        def self.adapt(raw)
+          raise 'missing at' if raw[:at].nil?
+
+          {
+            lookup_invoice: Lighstorm::Adapter::Invoice.lookup_invoice(
+              raw[:lookup_invoice],
+              raw[:at]
+            )
+          }
+        end
+
+        def self.transform(adapted)
+          adapted[:lookup_invoice][:known] = true
+          adapted[:lookup_invoice]
+        end
+
+        def self.data(code, &vcr)
+          raw = vcr.nil? ? fetch(code) : vcr.call(-> { fetch(code) })
+
+          raise_error_if_exists!(raw)
+
+          adapted = adapt(raw[:response])
+
+          transform(adapted)
+        end
+
+        def self.model(data)
+          Lighstorm::Models::Invoice.new(data)
+        end
+
+        def self.raise_error_if_exists!(response)
+          return if response[:exception].nil?
+
+          if response[:exception].is_a?(GRPC::NotFound)
+            raise NoInvoiceFoundError.new(
+              "Invoice not found. Try using Invoice.decode if you don't own the invoice.",
+              grpc: response[:exception]
+            )
+          end
+
+          raise LighstormError.new(grpc: response[:exception])
+        end
+      end
+    end
+  end
+end

data/controllers/invoice/find_by_secret_hash.rb

@@ -9,10 +9,12 @@ module Lighstorm
     module Invoice
       module FindBySecretHash
         def self.fetch(secret_hash)
-          {
+          { response: {
             at: Time.now,
             lookup_invoice: Ports::GRPC.lightning.lookup_invoice(r_hash_str: secret_hash).to_h
-          }
+          }, exception: nil }
+        rescue StandardError => e
+          { exception: e }
         end
 
         def self.adapt(raw)
@@ -34,7 +36,7 @@ module Lighstorm
         def self.data(secret_hash, &vcr)
           raw = vcr.nil? ? fetch(secret_hash) : vcr.call(-> { fetch(secret_hash) })
 
-          adapted = adapt(raw)
+          adapted = adapt(raw[:response])
 
           transform(adapted)
         end

data/controllers/invoice.rb

@@ -3,6 +3,7 @@
 require_relative './invoice/all'
 require_relative './invoice/decode'
 require_relative './invoice/find_by_secret_hash'
+require_relative './invoice/find_by_code'
 require_relative './invoice/actions/create'
 
 module Lighstorm
@@ -20,17 +21,21 @@ module Lighstorm
         All.model(All.data).last
       end
 
-      def self.find_by_secret_hash(secret_hash)
-        FindBySecretHash.model(FindBySecretHash.data(secret_hash))
+      def self.find_by_secret_hash(secret_hash, &vcr)
+        FindBySecretHash.model(FindBySecretHash.data(secret_hash, &vcr))
       end
 
-      def self.decode(request_code, &vcr)
-        Decode.model(Decode.data(request_code, &vcr))
+      def self.find_by_code(code, &vcr)
+        FindByCode.model(FindByCode.data(code, &vcr))
+      end
+
+      def self.decode(code, &vcr)
+        Decode.model(Decode.data(code, &vcr))
       end
 
       def self.create(
         payable:,
-        description: nil, millisatoshis: nil,
+        description: nil, amount: nil,
         # Lightning Invoice Expiration: UX Considerations
         # https://d.elor.me/2022/01/lightning-invoice-expiration-ux-considerations/
         expires_in: { hours: 24 },
@@ -39,7 +44,7 @@ module Lighstorm
         Create.perform(
           payable: payable,
           description: description,
-          millisatoshis: millisatoshis,
+          amount: amount,
           expires_in: expires_in,
           preview: preview,
           &vcr

data/controllers/node/actions/pay.rb

@@ -34,7 +34,7 @@ module Lighstorm
           Payment::Pay.model(data)
         end
 
-        def self.prepare(public_key:, millisatoshis:, times_out_in:, secret:, through:, message: nil)
+        def self.prepare(public_key:, amount:, times_out_in:, secret:, through:, fee: nil, message: nil)
           # Appreciation note for people that suffered in the past and shared
           # their knowledge, so we don't have to struggle the same:
           # - https://github.com/lightningnetwork/lnd/discussions/6357
@@ -46,7 +46,7 @@ module Lighstorm
             method: :send_payment_v2,
             params: {
               dest: [public_key].pack('H*'),
-              amt_msat: millisatoshis,
+              amt_msat: amount[:millisatoshis],
               timeout_seconds: Helpers::TimeExpression.seconds(times_out_in),
               allow_self_payment: true,
               dest_custom_records: {}
@@ -58,6 +58,10 @@ module Lighstorm
             request[:params][:dest_custom_records][34_349_334] = message
           end
 
+          unless fee.nil? || fee[:maximum].nil? || fee[:maximum][:millisatoshis].nil?
+            request[:params][:fee_limit_msat] = fee[:maximum][:millisatoshis]
+          end
+
           if through.to_sym == :keysend
             request[:params][:payment_hash] = [secret[:hash]].pack('H*')
             request[:params][:dest_custom_records][5_482_373_484] = [secret[:preimage]].pack('H*')
@@ -71,8 +75,8 @@ module Lighstorm
         end
 
         def self.perform(
-          public_key:, millisatoshis:, through:,
-          times_out_in:,
+          public_key:, amount:, through:,
+          times_out_in:, fee: nil,
           message: nil, secret: nil,
           preview: false, &vcr
         )
@@ -80,7 +84,8 @@ module Lighstorm
 
           grpc_request = prepare(
             public_key: public_key,
-            millisatoshis: millisatoshis,
+            amount: amount,
+            fee: fee,
             through: through,
             times_out_in: times_out_in,
             secret: secret,

data/controllers/payment/actions/pay.rb

@@ -30,15 +30,15 @@ module Lighstorm
           vcr.nil? ? call(grpc_request) : vcr.call(-> { call(grpc_request) }, :dispatch)
         end
 
-        def self.fetch_all(request_code)
+        def self.fetch_all(code)
           {
-            invoice_decode: request_code.nil? ? nil : Invoice::Decode.data(request_code),
+            invoice_decode: code.nil? ? nil : Invoice::Decode.data(code),
             node_myself: Node::Myself.data
           }
         end
 
-        def self.fetch(request_code = nil, &vcr)
-          raw = vcr.nil? ? fetch_all(request_code) : vcr.call(-> { fetch_all(request_code) })
+        def self.fetch(code = nil, &vcr)
+          raw = vcr.nil? ? fetch_all(code) : vcr.call(-> { fetch_all(code) })
         end
 
         def self.adapt(grpc_data, fetch_data)

data/controllers/payment/all.rb

@@ -12,7 +12,7 @@ module Lighstorm
   module Controllers
     module Payment
       module All
-        def self.fetch(purpose: nil, limit: nil, fetch: {})
+        def self.fetch(purpose: nil, invoice_code: nil, secret_hash: nil, limit: nil, fetch: {})
           at = Time.now
 
           grpc = Ports::GRPC.session
@@ -31,6 +31,10 @@ module Lighstorm
             response.payments.each do |payment|
               payment = payment.to_h
 
+              next unless invoice_code.nil? || payment[:payment_request] == invoice_code
+
+              next unless secret_hash.nil? || payment[:payment_hash] == secret_hash
+
               payment_purpose = Adapter::Purpose.list_payments(payment, get_info)
 
               case purpose
@@ -108,9 +112,13 @@ module Lighstorm
 
                 next if fetch[:get_node_info] == false || data[:get_node_info][hop[:pub_key]]
 
-                data[:get_node_info][hop[:pub_key]] = grpc.lightning.get_node_info(
-                  pub_key: hop[:pub_key]
-                ).to_h
+                begin
+                  data[:get_node_info][hop[:pub_key]] = grpc.lightning.get_node_info(
+                    pub_key: hop[:pub_key]
+                  ).to_h
+                rescue StandardError => e
+                  data[:get_node_info][hop[:pub_key]] = { _error: e }
+                end
               end
             end
           end
@@ -151,24 +159,36 @@ module Lighstorm
             end
 
             unless fetch[:get_node_info] == false || data[:get_node_info][channel[:node1_pub]]
-              data[:get_node_info][channel[:node1_pub]] = grpc.lightning.get_node_info(
-                pub_key: channel[:node1_pub]
-              ).to_h
+              begin
+                data[:get_node_info][channel[:node1_pub]] = grpc.lightning.get_node_info(
+                  pub_key: channel[:node1_pub]
+                ).to_h
+              rescue StandardError => e
+                data[:get_node_info][channel[:node1_pub]] = { _error: e }
+              end
             end
 
             next if fetch[:get_node_info] == false || data[:get_node_info][channel[:node2_pub]]
 
-            data[:get_node_info][channel[:node2_pub]] = grpc.lightning.get_node_info(
-              pub_key: channel[:node2_pub]
-            ).to_h
+            begin
+              data[:get_node_info][channel[:node2_pub]] = grpc.lightning.get_node_info(
+                pub_key: channel[:node2_pub]
+              ).to_h
+            rescue StandardError => e
+              data[:get_node_info][channel[:node2_pub]] = { _error: e }
+            end
           end
 
           data[:list_channels].each_value do |channel|
             next if fetch[:get_node_info] == false || data[:get_node_info][channel[:remote_pubkey]]
 
-            data[:get_node_info][channel[:remote_pubkey]] = grpc.lightning.get_node_info(
-              pub_key: channel[:remote_pubkey]
-            ).to_h
+            begin
+              data[:get_node_info][channel[:remote_pubkey]] = grpc.lightning.get_node_info(
+                pub_key: channel[:remote_pubkey]
+              ).to_h
+            rescue StandardError => e
+              data[:get_node_info][channel[:remote_pubkey]] = { _error: e }
+            end
           end
 
           data[:@meta] = { calls: grpc.calls }
@@ -223,6 +243,8 @@ module Lighstorm
           end
 
           raw[:get_node_info].each_key do |key|
+            next if raw[:get_node_info][key][:_error]
+
             adapted[:get_node_info][key] = Lighstorm::Adapter::Node.get_node_info(
               raw[:get_node_info][key]
             )
@@ -373,11 +395,22 @@ module Lighstorm
           list_payments
         end
 
-        def self.data(purpose: nil, limit: nil, fetch: {}, &vcr)
+        def self.data(
+          purpose: nil, invoice_code: nil, secret_hash: nil, limit: nil,
+          fetch: {}, &vcr
+        )
           raw = if vcr.nil?
-                  self.fetch(purpose: purpose, limit: limit, fetch: fetch)
+                  self.fetch(
+                    purpose: purpose, invoice_code: invoice_code, secret_hash: secret_hash,
+                    limit: limit, fetch: fetch
+                  )
                 else
-                  vcr.call(-> { self.fetch(purpose: purpose, limit: limit, fetch: fetch) })
+                  vcr.call(lambda {
+                             self.fetch(
+                               purpose: purpose, invoice_code: invoice_code, secret_hash: secret_hash,
+                               limit: limit, fetch: fetch
+                             )
+                           })
                 end
 
           adapted = adapt(raw)

data/controllers/payment.rb

@@ -16,6 +16,14 @@ module Lighstorm
       def self.last(purpose: nil, fetch: {})
         All.model(All.data(purpose: purpose, fetch: fetch)).last
       end
+
+      def self.find_by_secret_hash(secret_hash, &vcr)
+        All.model(All.data(secret_hash: secret_hash, &vcr)).first
+      end
+
+      def self.find_by_invoice_code(invoice_code, &vcr)
+        All.model(All.data(invoice_code: invoice_code, &vcr)).first
+      end
     end
   end
 end

data/docs/README.md

@@ -27,7 +27,7 @@ Lighstorm::Channel.mine.first.myself.node.alias
 Add to your `Gemfile`:
 
 ```ruby
-gem 'lighstorm', '~> 0.0.9'
+gem 'lighstorm', '~> 0.0.11'
 ```
 
 Run `bundle install`.
@@ -60,23 +60,25 @@ Lighstorm.config!(
 ```ruby
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.9
+puts Lighstorm.version # => 0.0.11
 
 Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000, payable: 'once'
+  description: 'Coffee', amount: { millisatoshis: 1000 }, payable: 'once'
 )
 
-Lighstorm::Invoice.decode(
-  'lnbc20m1pv...qqdhhwkj'
-).pay
+Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay
+
+Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay(
+  fee: { maximum: { millisatoshis: 1000 } }
+)
 
 Lighstorm::Node.find_by_public_key(
   '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
-).pay(millisatoshis: 1000)
+).pay(amount: { millisatoshis: 1000 })
 
 Lighstorm::Node.find_by_public_key(
   '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
-).send_message('Hello from Lighstorm!', millisatoshis: 1000)
+).send_message('Hello from Lighstorm!', amount: { millisatoshis: 1000 })
 
 Lighstorm::Node.myself.alias # => icebaker/old-stone
 Lighstorm::Node.myself.public_key # => 02d3...e997
@@ -264,23 +266,25 @@ destination = Lighstorm::Node.find_by_public_key(
 
 destination.alias # => 'icebaker/old-stone'
 
-destination.pay(millisatoshis: 1000)
+destination.pay(amount: { millisatoshis: 1000 })
 
 destination.pay(
-  millisatoshis: 1500,
+  amount: { millisatoshis: 1500 },
+  fee: { maximum: { millisatoshis: 1000 } },
   message: 'Hello from Lighstorm!',
   through: 'amp',
   times_out_in: { seconds: 5 }
 )
 
 destination.pay(
-  millisatoshis: 1200,
+  amount: { millisatoshis: 1200 },
+  fee: { maximum: { millisatoshis: 1000 } },
   message: 'Hello from Lighstorm!',
   through: 'keysend',
   times_out_in: { seconds: 5 }
 )
 
-action = destination.pay(millisatoshis: 1000)
+action = destination.pay(amount: { millisatoshis: 1000 })
 action.result.fee.millisatoshis
 ```
 
@@ -295,23 +299,31 @@ destination = Lighstorm::Node.find_by_public_key(
 
 destination.alias # => 'icebaker/old-stone'
 
-destination.send_message('Hello from Lighstorm!', millisatoshis: 1000)
+destination.send_message(
+  'Hello from Lighstorm!',
+  amount: { millisatoshis: 1000 }
+)
 
 destination.send_message(
   'Hello from Lighstorm!',
-  millisatoshis: 1000,
+  amount: { millisatoshis: 1000 },
+  fee: { maximum: { millisatoshis: 1000 } },
   through: 'amp',
   times_out_in: { seconds: 5 }
 )
 
 destination.send_message(
   'Hello from Lighstorm!',
-  millisatoshis: 1000,
+  amount: { millisatoshis: 1000 },
+  fee: { maximum: { millisatoshis: 1000 } },
   through: 'keysend',
   times_out_in: { seconds: 5 }
 )
 
-action = destination.send_message('Hello from Lighstorm!', millisatoshis: 1000)
+action = destination.send_message(
+  'Hello from Lighstorm!',
+  amount: { millisatoshis: 1000 }
+)
 action.result.fee.millisatoshis
 ```
 
@@ -450,6 +462,12 @@ Lighstorm::Invoice.find_by_secret_hash(
   '1d438b8100518c9fba0a607e3317d6b36f74ceef3a6591836eb2f679c6853501'
 )
 
+invoice = Lighstorm::Invoice.find_by_code('lnbc20n1pj...0eqps7h0k9')
+
+invoice.secret.valid_proof?(
+  'c504f73f83e3772b802844b54021e44e071c03011eeda476b198f7a093bcb09e'
+) # => true
+
 # _key is helpful for reactive javascript frameworks.
 # Please don't consider it as a unique identifier
 # for the item. Instead, use it as a volatile key for
@@ -485,12 +503,12 @@ invoice.secret.hash
 # 'preview' let you check the expected operation
 # before actually performing it for debug purposes
 preview = Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000,
+  description: 'Coffee', amount: { millisatoshis: 1000 },
   payable: 'once', preview: true
 )
 
 action = Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000,
+  description: 'Coffee', amount: { millisatoshis: 1000 },
   payable: 'once', expires_in: { minutes: 5 }
 )
 
@@ -504,7 +522,7 @@ action = Lighstorm::Invoice.create(
 )
 
 action = Lighstorm::Invoice.create(
-  description: 'Concert Ticket', millisatoshis: 500000000,
+  description: 'Concert Ticket', amount: { millisatoshis: 500000000 },
   payable: 'indefinitely', expires_in: { days: 5 }
 )
 
@@ -514,6 +532,19 @@ action.response
 invoice = action.result
 ```
 
+### Proof of Payment
+
+[Making Payments](https://docs.lightning.engineering/the-lightning-network/multihop-payments)
+
+
+```ruby
+invoice = Lighstorm::Invoice.find_by_code('lnbc20n1pj...0eqps7h0k9')
+
+invoice.secret.valid_proof?(
+  'c504f73f83e3772b802844b54021e44e071c03011eeda476b198f7a093bcb09e'
+) # => true
+```
+
 ### Pay
 
 [Understanding Lightning Invoices](https://docs.lightning.engineering/the-lightning-network/payment-lifecycle/understanding-lightning-invoices)
@@ -535,6 +566,8 @@ payment = action.result
 payment.at
 payment.state
 
+payment.secret.proof
+
 payment.amount.millisatoshis
 payment.fee.millisatoshis
 payment.fee.parts_per_million(
@@ -547,7 +580,8 @@ payment.hops.size
 
 ```ruby
 invoice.pay(
-  millisatoshis: 1500,
+  amount: { millisatoshis: 1500 },
+  fee: { maximum: { millisatoshis: 1000 } },
   message: 'here we go',
   times_out_in: { seconds: 5 }
 )
@@ -568,7 +602,7 @@ end
 
 ```ruby
 begin
-  invoice.pay(millisatoshis: 1000)
+  invoice.pay(amount: { millisatoshis: 1000 })
 rescue AmountForNonZeroError => error
   error.message # 'Millisatoshis must not be specified...'
   error.grpc.class # GRPC::Unknown
@@ -609,6 +643,7 @@ rescue PaymentError => error
   error.result
 end
 ```
+
 ## Payment
 
 [![This is an image representing Payment as a graph.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-payment.png)](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-payment.png)
@@ -629,6 +664,12 @@ Lighstorm::Payment.all(limit: 10, purpose: 'rebalance')
 # 'self-payment', 'peer-to-peer',
 # 'rebalance', 'payment'
 
+Lighstorm::Payment.find_by_invoice_code('lnbc20n1pj...0eqps7h0k9')
+
+Lighstorm::Payment.find_by_secret_hash(
+  '1d438b8100518c9fba0a607e3317d6b36f74ceef3a6591836eb2f679c6853501'
+)
+
 # _key is helpful for reactive javascript frameworks.
 # Please don't consider it as a unique identifier
 # for the item. Instead, use it as a volatile key for
@@ -658,6 +699,7 @@ payment.purpose
 # https://docs.lightning.engineering/the-lightning-network/multihop-payments
 payment.secret.preimage
 payment.secret.hash
+payment.secret.proof
 
 payment.invoice.created_at
 payment.invoice.expires_at
@@ -734,6 +776,18 @@ payment.hops[0].channel.entry.public_key
 payment.hops[0].channel.entry.alias
 payment.hops[0].channel.entry.color
 ```
+
+### Proof of Payment
+
+[Making Payments](https://docs.lightning.engineering/the-lightning-network/multihop-payments)
+
+```ruby
+payment = Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay.result
+
+payment.secret.proof
+# => 'c504f73f83e3772b802844b54021e44e071c03011eeda476b198f7a093bcb09e'
+```
+
 ### Performance
 Avoid fetching data that you don't need:
 ```ruby
@@ -990,7 +1044,7 @@ gem 'lighstorm', path: '/home/user/lighstorm'
 # demo.rb
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.9
+puts Lighstorm.version # => 0.0.11
 ```
 
 ```sh
@@ -1050,13 +1104,15 @@ The downside is that we can't [lazy-load](https://en.wikipedia.org/wiki/Lazy_loa
 To perform an _action_, like creating an Invoice, you:
 ```ruby
 Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000
+  description: 'Coffee', amount: { millisatoshis: 1000 }
 )
 ```
 
 Internally, what's happening:
 ```ruby
-action = Lighstorm::Invoice.create(description: 'Coffee', millisatoshis: 1000)
+action = Lighstorm::Invoice.create(
+  description: 'Coffee', amount: { millisatoshis: 1000 }
+)
 
    request = Controllers::Invoice::Create.prepare(params) # pure
   response = Controllers::Invoice::Create.dispatch(request) # side effect
@@ -1225,13 +1281,13 @@ gem build lighstorm.gemspec
 
 gem signin
 
-gem push lighstorm-0.0.9.gem
+gem push lighstorm-0.0.11.gem
 ```
 
 _________________
 
 <center>
-  lighstorm 0.0.9
+  lighstorm 0.0.11
   |
   <a href="https://github.com/icebaker/lighstorm" rel="noopener noreferrer" target="_blank">GitHub</a>
   |

data/docs/_coverpage.md

@@ -8,7 +8,7 @@
 - Built for maximum **reliability**.
 - Optimized for programmer **happiness**.
 
-0.0.9
+0.0.11
 
 ⚠️ _Warning: Early-stage, breaking changes are expected._
 

data/docs/index.html

@@ -18,7 +18,7 @@
   <script>
     window.$docsify = {
       coverpage: true,
-      name: 'Lighstorm 0.0.9',
+      name: 'Lighstorm 0.0.11',
       repo: 'https://github.com/icebaker/lighstorm'
     }
   </script>

data/models/errors.rb

@@ -2,7 +2,21 @@
 
 module Lighstorm
   module Errors
-    class LighstormError < StandardError; end
+    class LighstormError < StandardError
+      attr_reader :grpc
+
+      def initialize(message = nil, grpc: nil)
+        super(message)
+        @grpc = grpc
+      end
+
+      def to_h
+        output = { class: self.class, message: message }
+        output[:grpc] = grpc.message unless grpc.nil?
+
+        output
+      end
+    end
 
     class ToDoError < LighstormError; end
 
@@ -19,6 +33,7 @@ module Lighstorm
     class OperationNotAllowedError < LighstormError; end
     class UnexpectedNumberOfHTLCsError < LighstormError; end
     class UnknownChannelError < LighstormError; end
+    class NoInvoiceFoundError < LighstormError; end
 
     class InvoiceMayHaveMultiplePaymentsError < LighstormError; end
 

data/models/invoice.rb

@@ -84,7 +84,8 @@ module Lighstorm
       end
 
       def pay(
-        millisatoshis: nil, message: nil, route: nil,
+        amount: nil, message: nil, route: nil,
+        fee: nil,
         times_out_in: { seconds: 5 },
         preview: false
       )
@@ -92,8 +93,9 @@ module Lighstorm
           Controllers::Invoice::PayThroughRoute.perform(self, route: route, preview: preview)
         else
           Controllers::Invoice::Pay.perform(
-            request_code: code,
-            millisatoshis: millisatoshis,
+            code: code,
+            amount: amount,
+            fee: fee,
             message: message,
             times_out_in: times_out_in,
             preview: preview

data/models/nodes/node.rb

@@ -100,13 +100,14 @@ module Lighstorm
       end
 
       def send_message(
-        message, millisatoshis:, secret: nil,
+        message, amount:, fee: nil, secret: nil,
         times_out_in: { seconds: 5 }, through: 'amp',
         preview: false
       )
         pay(
           message: message,
-          millisatoshis: millisatoshis,
+          amount: amount,
+          fee: fee,
           secret: secret,
           times_out_in: times_out_in,
           through: through,
@@ -115,13 +116,15 @@ module Lighstorm
       end
 
       def pay(
-        millisatoshis:, message: nil, secret: nil,
+        amount:, message: nil, secret: nil,
+        fee: nil,
         times_out_in: { seconds: 5 }, through: 'amp',
         preview: false
       )
         Controllers::Node::Pay.perform(
           public_key: public_key,
-          millisatoshis: millisatoshis,
+          amount: amount,
+          fee: fee,
           through: through,
           secret: secret,
           message: message,

data/models/secret.rb

@@ -7,9 +7,15 @@ module Lighstorm
     class Secret
       attr_reader :preimage, :hash
 
-      def self.create
+      def self.generate
         data = { preimage: SecureRandom.hex(32) }
         data[:hash] = Digest::SHA256.hexdigest([data[:preimage]].pack('H*'))
+        data
+      end
+
+      def self.create(&vcr)
+        data = vcr.nil? ? generate : vcr.call(-> { generate })
+
         Secret.new(data)
       end
 
@@ -20,6 +26,14 @@ module Lighstorm
         @hash = data[:hash]
       end
 
+      def proof
+        @preimage
+      end
+
+      def valid_proof?(candidate_preimage)
+        candidate_preimage == preimage
+      end
+
       def to_h
         {
           preimage: preimage,

data/static/spec.rb

@@ -4,7 +4,7 @@ module Lighstorm
   module Static
     SPEC = {
       name: 'lighstorm',
-      version: '0.0.9',
+      version: '0.0.11',
       author: 'icebaker',
       summary: 'API for interacting with a Lightning Node.',
       description: 'Lighstorm is an opinionated abstraction layer on top of the lnd-client for interacting with a Lightning Node.',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lighstorm
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.11
 platform: ruby
 authors:
 - icebaker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-11 00:00:00.000000000 Z
+date: 2023-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv
@@ -103,6 +103,7 @@ files:
 - controllers/invoice/actions/pay_through_route.rb
 - controllers/invoice/all.rb
 - controllers/invoice/decode.rb
+- controllers/invoice/find_by_code.rb
 - controllers/invoice/find_by_secret_hash.rb
 - controllers/node.rb
 - controllers/node/actions/apply_gossip.rb