lighstorm 0.0.8 → 0.0.10

data/controllers/transaction/all.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../invoice/all'
+require_relative '../../models/transaction'
+
+module Lighstorm
+  module Controllers
+    module Transaction
+      module All
+        def self.fetch(limit: nil)
+          transactions = []
+
+          Invoice::All.data(spontaneous: true).filter do |invoice|
+            !invoice[:payments].nil? && invoice[:payments].size.positive?
+          end.each do |invoice|
+            invoice[:payments].each do |payment|
+              transactions << {
+                direction: 'in',
+                at: payment[:at],
+                amount: payment[:amount],
+                message: payment[:message],
+                kind: 'invoice',
+                data: invoice
+              }
+            end
+          end
+
+          transactions = transactions.sort_by { |transaction| -transaction[:at].to_i }
+
+          transactions = transactions[0..limit - 1] unless limit.nil?
+
+          { transactions: transactions }
+        end
+
+        def self.transform(raw)
+          raw[:transactions].map do |transaction|
+            transaction[:_key] = SecureRandom.hex
+            transaction
+          end
+        end
+
+        def self.data(limit: nil, &vcr)
+          raw = vcr.nil? ? fetch(limit: limit) : vcr.call(-> { fetch(limit: limit) })
+
+          transform(raw)
+        end
+
+        def self.model(data)
+          data.map { |data| Models::Transaction.new(data) }
+        end
+      end
+    end
+  end
+end

data/controllers/transaction.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative './transaction/all'
+
+module Lighstorm
+  module Controllers
+    module Transaction
+      def self.all(limit: nil)
+        All.model(All.data(limit: limit))
+      end
+    end
+  end
+end

data/deleted.sh

@@ -0,0 +1 @@
+	deleted.sh

data/docs/README.md

@@ -27,7 +27,7 @@ Lighstorm::Channel.mine.first.myself.node.alias
 Add to your `Gemfile`:
 
 ```ruby
-gem 'lighstorm', '~> 0.0.8'
+gem 'lighstorm', '~> 0.0.10'
 ```
 
 Run `bundle install`.
@@ -60,12 +60,26 @@ Lighstorm.config!(
 ```ruby
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.8
+puts Lighstorm.version # => 0.0.10
 
 Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000
+  description: 'Coffee', amount: { millisatoshis: 1000 }, payable: 'once'
 )
 
+Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay
+
+Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj').pay(
+  fee: { maximum: { millisatoshis: 1000 } }
+)
+
+Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+).pay(amount: { millisatoshis: 1000 })
+
+Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+).send_message('Hello from Lighstorm!', amount: { millisatoshis: 1000 })
+
 Lighstorm::Node.myself.alias # => icebaker/old-stone
 Lighstorm::Node.myself.public_key # => 02d3...e997
 
@@ -95,7 +109,7 @@ payment.hops.first.channel.partner.node.alias
 
 Lighstorm::Satoshis.new(
   millisatoshis: 75621650
-).satoshis # => 75621
+).satoshis # => 75621.65
 ```
 
 # Data Modeling
@@ -146,7 +160,9 @@ forward = Lighstorm::Forward.last
 forward.at
 
 forward.fee.millisatoshis
-forward.fee.parts_per_million
+forward.fee.parts_per_million(
+  forward.in.amount.millisatoshis
+)
 
 forward.in.amount.millisatoshis
 forward.out.amount.millisatoshis
@@ -168,15 +184,15 @@ forward.out.channel.partner.node.alias
 ### Payment
 
 ```ruby
-payment = Payment.last
+payment = Lighstorm::Payment.last
 
-payment.status
-payment.created_at
+payment.at
+payment.state
 
 # https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
-payment.request.code # "lnbc20m1pv...qqdhhwkj"
+payment.invoice.code # "lnbc20m1pv...qqdhhwkj"
 
-payment.request.amount.millisatoshis
+payment.invoice.amount.millisatoshis
 
 payment.from.hop
 payment.from.amount.millisatoshis
@@ -239,6 +255,86 @@ node.platform.lightning.implementation
 node.platform.lightning.version
 ```
 
+### Pay
+
+Read more about [_Spontaneous Payments_](https://docs.lightning.engineering/lightning-network-tools/lnd/send-messages-with-keysend#send-a-spontaneous-payment).
+
+```ruby
+destination = Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+)
+
+destination.alias # => 'icebaker/old-stone'
+
+destination.pay(amount: { millisatoshis: 1000 })
+
+destination.pay(
+  amount: { millisatoshis: 1500 },
+  fee: { maximum: { millisatoshis: 1000 } },
+  message: 'Hello from Lighstorm!',
+  through: 'amp',
+  times_out_in: { seconds: 5 }
+)
+
+destination.pay(
+  amount: { millisatoshis: 1200 },
+  fee: { maximum: { millisatoshis: 1000 } },
+  message: 'Hello from Lighstorm!',
+  through: 'keysend',
+  times_out_in: { seconds: 5 }
+)
+
+action = destination.pay(amount: { millisatoshis: 1000 })
+action.result.fee.millisatoshis
+```
+
+### Send Messages
+
+**Warning:** Sending messages through Lightning Network requires you to spend satoshis and potentially pay fees.
+
+```ruby
+destination = Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+)
+
+destination.alias # => 'icebaker/old-stone'
+
+destination.send_message(
+  'Hello from Lighstorm!',
+  amount: { millisatoshis: 1000 }
+)
+
+destination.send_message(
+  'Hello from Lighstorm!',
+  amount: { millisatoshis: 1000 },
+  fee: { maximum: { millisatoshis: 1000 } },
+  through: 'amp',
+  times_out_in: { seconds: 5 }
+)
+
+destination.send_message(
+  'Hello from Lighstorm!',
+  amount: { millisatoshis: 1000 },
+  fee: { maximum: { millisatoshis: 1000 } },
+  through: 'keysend',
+  times_out_in: { seconds: 5 }
+)
+
+action = destination.send_message(
+  'Hello from Lighstorm!',
+  amount: { millisatoshis: 1000 }
+)
+action.result.fee.millisatoshis
+```
+
+Read more about sending messages:
+- [_Send a message to other nodes_](https://docs.lightning.engineering/lightning-network-tools/lnd/send-messages-with-keysend#send-a-message-to-other-nodes)
+- [_Does Private messaging over Bitcoin’s Lightning Network have potential?_](https://cryptopurview.com/private-messaging-over-bitcoins-lightning-network/)
+- [_How Bitcoin's Lightning Can Be Used for Private Messaging_](https://www.coindesk.com/markets/2019/11/09/how-bitcoins-lightning-can-be-used-for-private-messaging/)
+
+### Error Handling
+Same error handling used for [Invoices Payment Errors](?id=error-handling-1)
+
 ## Channel
 
 [![This is an image representing Channel as a graph.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-channel.png)](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-channel.png)
@@ -373,23 +469,24 @@ Lighstorm::Invoice.find_by_secret_hash(
 invoice._key
 
 invoice.created_at
-invoice.settle_at
+invoice.expires_at
+invoice.settled_at
 
 invoice.state
 
 # https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
-invoice.request.code # "lnbc20m1pv...qqdhhwkj"
+invoice.code # "lnbc20m1pv...qqdhhwkj"
 
-invoice.request.amount.millisatoshis
+invoice.amount.millisatoshis
 
-invoice.request.description.memo
-invoice.request.description.hash
+invoice.payable # 'once' or 'indefinitely'
 
-# https://docs.lightning.engineering/the-lightning-network/multihop-payments
-invoice.request.secret.preimage
-invoice.request.secret.hash
+invoice.description.memo
+invoice.description.hash
 
-invoice.request.address
+# https://docs.lightning.engineering/the-lightning-network/multihop-payments
+invoice.secret.preimage
+invoice.secret.hash
 ```
 
 ### Create
@@ -400,11 +497,27 @@ invoice.request.address
 # 'preview' let you check the expected operation
 # before actually performing it for debug purposes
 preview = Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000, preview: true
+  description: 'Coffee', amount: { millisatoshis: 1000 },
+  payable: 'once', preview: true
+)
+
+action = Lighstorm::Invoice.create(
+  description: 'Coffee', amount: { millisatoshis: 1000 },
+  payable: 'once', expires_in: { minutes: 5 }
+)
+
+action = Lighstorm::Invoice.create(
+  description: 'Beer', payable: 'once'
+)
+
+action = Lighstorm::Invoice.create(
+  description: 'Donations', payable: 'indefinitely',
+  expires_in: { hours: 24 }
 )
 
 action = Lighstorm::Invoice.create(
-  description: 'Piña Colada', millisatoshis: 1000
+  description: 'Concert Ticket', amount: { millisatoshis: 500000000 },
+  payable: 'indefinitely', expires_in: { days: 5 }
 )
 
 action.to_h
@@ -413,6 +526,102 @@ action.response
 invoice = action.result
 ```
 
+### Pay
+
+[Understanding Lightning Invoices](https://docs.lightning.engineering/the-lightning-network/payment-lifecycle/understanding-lightning-invoices)
+
+```ruby
+invoice = Lighstorm::Invoice.decode('lnbc20m1pv...qqdhhwkj')
+
+# 'preview' let you check the expected operation
+# before actually performing it for debug purposes
+invoice.pay(preview: true)
+
+action = invoice.pay
+
+action.to_h
+
+action.response
+payment = action.result
+
+payment.at
+payment.state
+
+payment.amount.millisatoshis
+payment.fee.millisatoshis
+payment.fee.parts_per_million(
+  payment.amount.millisatoshis
+)
+
+payment.purpose
+payment.hops.size
+```
+
+```ruby
+invoice.pay(
+  amount: { millisatoshis: 1500 },
+  fee: { maximum: { millisatoshis: 1000 } },
+  message: 'here we go',
+  times_out_in: { seconds: 5 }
+)
+```
+
+#### Error Handling
+Check [Error Handling](?id=error-handling-2)
+
+```ruby
+begin
+  invoice.pay
+rescue AlreadyPaidError => error
+  error.message # 'The invoice is already paid.'
+  error.grpc.class # GRPC::AlreadyExists
+  error.grpc.message # '6:invoice is already paid. debug_error_string:{UNKNOWN...'
+end
+```
+
+```ruby
+begin
+  invoice.pay(amount: { millisatoshis: 1000 })
+rescue AmountForNonZeroError => error
+  error.message # 'Millisatoshis must not be specified...'
+  error.grpc.class # GRPC::Unknown
+  error.grpc.message # '2:amount must not be specified when paying...'
+end
+```
+
+```ruby
+begin
+  invoice.pay
+rescue MissingMillisatoshisError => error
+  error.message # 'Millisatoshis must be specified...'
+  error.grpc.class # GRPC::Unknown
+  error.grpc.message # '2:amount must be specified when paying a zero...'
+end
+```
+
+```ruby
+begin
+  invoice.pay
+rescue NoRouteFoundError => error
+  error.message # 'FAILURE_REASON_NO_ROUTE'
+  e.response
+  e.response.last[:failure_reason] # => :FAILURE_REASON_NO_ROUTE
+end
+```
+
+
+```ruby
+begin
+  invoice.pay
+rescue PaymentError => error
+  error.class
+  error.message
+
+  error.grpc
+  error.response
+  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)
@@ -430,7 +639,8 @@ Lighstorm::Payment.last
 Lighstorm::Payment.all(limit: 10, purpose: 'rebalance')
 
 # Possible Purposes:
-['self-payment', 'peer-to-peer', 'rebalance', 'payment']
+# 'self-payment', 'peer-to-peer',
+# 'rebalance', 'payment'
 
 # _key is helpful for reactive javascript frameworks.
 # Please don't consider it as a unique identifier
@@ -440,34 +650,53 @@ payment._key
 
 payment.to_h
 
-payment.status
-payment.created_at
-payment.settled_at
-payment.purpose
+payment.at
+
+payment.amount.millisatoshis
 
 payment.fee.millisatoshis
 payment.fee.parts_per_million(
-  payment.request.amount.millisatoshis
+  payment.amount.millisatoshis
 )
 
-# https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
-payment.request.code # "lnbc20m1pv...qqdhhwkj"
+payment.state
+payment.message
 
-payment.request.amount.millisatoshis
+payment.how # 'spontaneously', 'with-invoice'
+payment.through # 'keysend', 'amp', 'non-amp'
+payment.purpose
+# 'self-payment', 'peer-to-peer',
+# 'rebalance', 'payment'
 
 # https://docs.lightning.engineering/the-lightning-network/multihop-payments
-payment.request.secret.preimage
-payment.request.secret.hash
+payment.secret.preimage
+payment.secret.hash
+
+payment.invoice.created_at
+payment.invoice.expires_at
+payment.invoice.settled_at
+
+payment.invoice.state
+
+# https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
+payment.invoice.code # "lnbc20m1pv...qqdhhwkj"
+payment.invoice.amount.millisatoshis
 
-payment.request.address
+payment.invoice.payable # 'once', 'indefinitely'
 
-payment.request.description.memo
-payment.request.description.hash
+payment.invoice.description.memo
+payment.invoice.description.hash
+
+# https://docs.lightning.engineering/the-lightning-network/multihop-payments
+payment.invoice.secret.preimage
+payment.invoice.secret.hash
 
 payment.from.hop
 payment.from.amount.millisatoshis
 payment.from.fee.millisatoshis
-payment.from.fee.parts_per_million(payment.from.amount.millisatoshis)
+payment.from.fee.parts_per_million(
+  payment.from.amount.millisatoshis
+)
 
 payment.from.channel.id
 
@@ -482,7 +711,9 @@ payment.from.channel.exit.color
 payment.to.hop
 payment.to.amount.millisatoshis
 payment.to.fee.millisatoshis
-payment.to.fee.parts_per_million(payment.to.amount.millisatoshis)
+payment.to.fee.parts_per_million(
+  payment.to.amount.millisatoshis
+)
 
 payment.to.channel.id
 
@@ -502,7 +733,9 @@ payment.hops[0].last?
 payment.hops[0].hop
 payment.hops[0].amount.millisatoshis
 payment.hops[0].fee.millisatoshis
-payment.hops[0].fee.parts_per_million(payment.hops[0].amount.millisatoshis)
+payment.hops[0].fee.parts_per_million(
+  payment.hops[0].amount.millisatoshis
+)
 
 payment.hops[0].channel.id
 
@@ -666,6 +899,7 @@ Lighstorm::Channel.adapt(dump: channel.dump)
 
 ```ruby
 Lighstorm::Satoshis
+Lighstorm::Satoshis.new(bitcoins: 0.005)
 Lighstorm::Satoshis.new(millisatoshis: 75621650)
 
 satoshis.to_h
@@ -736,24 +970,26 @@ end
 ```ruby
 LighstormError
 
+ArgumentError
 IncoherentGossipError
-
-TooManyArgumentsError
 MissingCredentialsError
 MissingGossipHandlerError
-MissingMillisatoshisError
 MissingPartsPerMillionError
-MissingTTLError
-
 NegativeNotAllowedError
-
 NotYourChannelError
 NotYourNodeError
-UnknownChannelError
-
 OperationNotAllowedError
+TooManyArgumentsError
 UnexpectedNumberOfHTLCsError
+UnknownChannelError
 UpdateChannelPolicyError
+
+PaymentError
+
+AlreadyPaidError
+AmountForNonZeroError
+MissingMillisatoshisError
+NoRouteFoundError
 ```
 
 # Development
@@ -767,7 +1003,7 @@ gem 'lighstorm', path: '/home/user/lighstorm'
 # demo.rb
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.8
+puts Lighstorm.version # => 0.0.10
 ```
 
 ```sh
@@ -827,13 +1063,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
@@ -969,6 +1207,24 @@ expected: nil
 
 Remember to undo it afterward, replacing `expect!` with `expect`.
 
+### Extra Tips for Testing
+
+To auto-fix contracts:
+
+```sh
+rspec --format json | bundle exec rake contracts:fix
+```
+
+To delete unused test data files, update the `.env` file:
+```sh
+LIGHSTORM_DELETE_UNUSED_TEST_DATA=true
+```
+
+Deletion will only occur if you run all tests and no failures are found:
+```ruby
+bundle exec rspec
+```
+
 ## Generating Documentation
 
 ```sh
@@ -984,13 +1240,13 @@ gem build lighstorm.gemspec
 
 gem signin
 
-gem push lighstorm-0.0.8.gem
+gem push lighstorm-0.0.10.gem
 ```
 
 _________________
 
 <center>
-  lighstorm 0.0.8
+  lighstorm 0.0.10
   |
   <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.8
+0.0.10
 
 ⚠️ _Warning: Early-stage, breaking changes are expected._
 

data/docs/index.html

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

data/helpers/time_expression.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../models/errors'
+
+module Lighstorm
+  module Helpers
+    module TimeExpression
+      def self.seconds(expression)
+        raise Errors::ArgumentError, 'missing keywords for time expression' unless expression.is_a?(Hash)
+
+        duration = 0.0
+        expression.each_key do |key|
+          case key
+          when :seconds
+            duration += expression[key].to_f
+          when :minutes
+            duration += (expression[key].to_f * 60.0)
+          when :hours
+            duration += (expression[key].to_f * 60.0 * 60.0)
+          when :days
+            duration += (expression[key].to_f * 24.0 * 60.0 * 60.0)
+          else
+            raise Errors::ArgumentError, "unexpected keyword :#{key} for time expression #{expression}"
+          end
+        end
+
+        raise Errors::ArgumentError, 'missing keywords for time expression' if expression.keys.empty?
+
+        duration.to_i
+      end
+    end
+  end
+end

data/models/connections/payment_channel.rb

@@ -24,11 +24,11 @@ module Lighstorm
       end
 
       def amount
-        @amount ||= Satoshis.new(millisatoshis: @data[:amount][:millisatoshis])
+        @amount ||= @data[:amount] ? Satoshis.new(millisatoshis: @data[:amount][:millisatoshis]) : nil
       end
 
       def fee
-        @fee ||= Satoshis.new(millisatoshis: @data[:fee][:millisatoshis])
+        @fee ||= @data[:fee] ? Satoshis.new(millisatoshis: @data[:fee][:millisatoshis]) : nil
       end
 
       def channel
@@ -36,15 +36,20 @@ module Lighstorm
       end
 
       def to_h
-        {
+        result = {
           hop: hop,
-          amount: amount.to_h,
-          fee: {
-            millisatoshis: fee.millisatoshis,
-            parts_per_million: fee.parts_per_million(amount.millisatoshis)
-          },
           channel: channel.to_h
         }
+
+        result[:amount] = amount.to_h if amount
+        if fee
+          result[:fee] = {
+            millisatoshis: fee.millisatoshis,
+            parts_per_million: fee.parts_per_million(amount.millisatoshis)
+          }
+        end
+
+        result
       end
     end
   end