lighstorm 0.0.8 → 0.0.9

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.9'
 ```
 
 Run `bundle install`.
@@ -60,12 +60,24 @@ Lighstorm.config!(
 ```ruby
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.8
+puts Lighstorm.version # => 0.0.9
 
 Lighstorm::Invoice.create(
-  description: 'Coffee', millisatoshis: 1000
+  description: 'Coffee', millisatoshis: 1000, payable: 'once'
 )
 
+Lighstorm::Invoice.decode(
+  'lnbc20m1pv...qqdhhwkj'
+).pay
+
+Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+).pay(millisatoshis: 1000)
+
+Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+).send_message('Hello from Lighstorm!', millisatoshis: 1000)
+
 Lighstorm::Node.myself.alias # => icebaker/old-stone
 Lighstorm::Node.myself.public_key # => 02d3...e997
 
@@ -95,7 +107,7 @@ payment.hops.first.channel.partner.node.alias
 
 Lighstorm::Satoshis.new(
   millisatoshis: 75621650
-).satoshis # => 75621
+).satoshis # => 75621.65
 ```
 
 # Data Modeling
@@ -146,7 +158,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 +182,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 +253,76 @@ 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(millisatoshis: 1000)
+
+destination.pay(
+  millisatoshis: 1500,
+  message: 'Hello from Lighstorm!',
+  through: 'amp',
+  times_out_in: { seconds: 5 }
+)
+
+destination.pay(
+  millisatoshis: 1200,
+  message: 'Hello from Lighstorm!',
+  through: 'keysend',
+  times_out_in: { seconds: 5 }
+)
+
+action = destination.pay(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!', millisatoshis: 1000)
+
+destination.send_message(
+  'Hello from Lighstorm!',
+  millisatoshis: 1000,
+  through: 'amp',
+  times_out_in: { seconds: 5 }
+)
+
+destination.send_message(
+  'Hello from Lighstorm!',
+  millisatoshis: 1000,
+  through: 'keysend',
+  times_out_in: { seconds: 5 }
+)
+
+action = destination.send_message('Hello from Lighstorm!', 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 +457,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 +485,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', millisatoshis: 1000,
+  payable: 'once', preview: true
+)
+
+action = Lighstorm::Invoice.create(
+  description: 'Coffee', millisatoshis: 1000,
+  payable: 'once', expires_in: { minutes: 5 }
 )
 
 action = Lighstorm::Invoice.create(
-  description: 'Piña Colada', millisatoshis: 1000
+  description: 'Beer', payable: 'once'
+)
+
+action = Lighstorm::Invoice.create(
+  description: 'Donations', payable: 'indefinitely',
+  expires_in: { hours: 24 }
+)
+
+action = Lighstorm::Invoice.create(
+  description: 'Concert Ticket', millisatoshis: 500000000,
+  payable: 'indefinitely', expires_in: { days: 5 }
 )
 
 action.to_h
@@ -413,6 +514,101 @@ 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(
+  millisatoshis: 1500,
+  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(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 +626,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 +637,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.request.address
+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.description.memo
-payment.request.description.hash
+payment.invoice.payable # 'once', 'indefinitely'
+
+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 +698,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 +720,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 +886,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 +957,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 +990,7 @@ gem 'lighstorm', path: '/home/user/lighstorm'
 # demo.rb
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.8
+puts Lighstorm.version # => 0.0.9
 ```
 
 ```sh
@@ -969,6 +1192,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 +1225,13 @@ gem build lighstorm.gemspec
 
 gem signin
 
-gem push lighstorm-0.0.8.gem
+gem push lighstorm-0.0.9.gem
 ```
 
 _________________
 
 <center>
-  lighstorm 0.0.8
+  lighstorm 0.0.9
   |
   <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.9
 
 ⚠️ _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.9',
       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

data/models/edges/channel.rb

@@ -9,7 +9,7 @@ require_relative '../../components/lnd'
 require_relative '../../components/cache'
 
 require_relative '../nodes/node'
-require_relative 'channel/accounting'
+require_relative './channel/accounting'
 
 require_relative '../../controllers/channel/actions/apply_gossip'
 require_relative '../connections/channel_node'