lighstorm 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c585645f0ccf6b55a8b0840d5351900f701002a4616f351016f1b8d9f097ed4
-  data.tar.gz: fca5794bab41231c60400aab4ce82021bb649df52df63acf801ef4931bf5c53c
+  metadata.gz: 79b37e0a32c6d34ed5e4b05fc32eb894a808a08b9d2b6efea608be59644a94c9
+  data.tar.gz: ba7f317ff7699cdae5f9645f533e1779ca5de988aec3d8320172f2ec6807d0d1
 SHA512:
-  metadata.gz: 0717fc86e023d1591872b3c81c58338c713409030f3bc2351988ee62abb163b262df95e1357537c7530d3f3bd615208af99f68c92a0a53b6f6b784401d5c8e15
-  data.tar.gz: ff9bba186921987b3f301f95f82f1d3b7041feb4db92d8ca2a43c663915ea12e6d609615419805bc26cde7c2ba658702b713a603dd33c3f024de6b16794eca7e
+  metadata.gz: b633147091290d526f184ca324964d9bc2fd13cb769a2009e7b732280ddd305fac82d63d2c9c735277ecc14f2fbdf4310d7b4d95611398753879746d170ed33b
+  data.tar.gz: e979df8953dd05ab5efceb268cde4f305190bc07d3304e304155ddef3ebf876f0444612b59420e2c7f24572d20b758e6521a7a569e3788eaf5b76037ee8ded7e

data/.env.example

@@ -0,0 +1,5 @@
+LIGHSTORM_LND_ADDRESS=127.0.0.1:10009
+LIGHSTORM_CERTIFICATE_PATH=/lnd/tls.cert
+LIGHSTORM_MACAROON_PATH=/lnd/data/chain/bitcoin/mainnet/admin.macaroon
+LIGHSTORM_RUN_INTEGRATION_TESTS=false
+LIGHSTORM_RUN_INTEGRATION_TESTS_SLOW=false

data/.gitignore

@@ -1 +1,2 @@
 *.gem
+.env

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -9,6 +9,16 @@ Naming/FileName:
   Exclude:
     - 'ports/dsl/lighstorm.rb'
 
+Metrics/MethodLength:
+  Enabled: false
+
 Layout/LineLength:
   Exclude:
     - 'static/spec.rb'
+
+Security/MarshalLoad:
+  Exclude:
+    - 'spec/helpers/vcr.rb'
+
+require:
+ - rubocop-rspec

data/Gemfile

@@ -5,6 +5,10 @@ source 'https://rubygems.org'
 gemspec
 
 group :test, :development do
+  gem 'babosa', '~> 2.0'
+  gem 'dotenv', '~> 2.8', '>= 2.8.1'
   gem 'pry-byebug', '~> 3.10', '>= 3.10.1'
+  gem 'rspec', '~> 3.12'
   gem 'rubocop', '~> 1.45', '>= 1.45.1'
+  gem 'rubocop-rspec', '~> 2.18', '>= 2.18.1'
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lighstorm (0.0.3)
+    lighstorm (0.0.4)
       dotenv (~> 2.8, >= 2.8.1)
       lnd-client (~> 0.0.5)
       zache (~> 0.12.0)
@@ -10,10 +10,12 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    babosa (2.0.0)
     byebug (11.1.3)
     coderay (1.1.3)
+    diff-lcs (1.5.0)
     dotenv (2.8.1)
-    google-protobuf (3.21.12)
+    google-protobuf (3.22.0-x86_64-linux)
     googleapis-common-protos-types (1.5.0)
       google-protobuf (~> 3.14)
     grpc (1.52.0-x86_64-linux)
@@ -35,6 +37,19 @@ GEM
     rainbow (3.1.1)
     regexp_parser (2.7.0)
     rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
     rubocop (1.45.1)
       json (~> 2.3)
       parallel (~> 1.10)
@@ -47,6 +62,11 @@ GEM
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.26.0)
       parser (>= 3.2.1.0)
+    rubocop-capybara (2.17.1)
+      rubocop (~> 1.41)
+    rubocop-rspec (2.18.1)
+      rubocop (~> 1.33)
+      rubocop-capybara (~> 2.17)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.4.2)
     zache (0.12.0)
@@ -55,9 +75,13 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  babosa (~> 2.0)
+  dotenv (~> 2.8, >= 2.8.1)
   lighstorm!
   pry-byebug (~> 3.10, >= 3.10.1)
+  rspec (~> 3.12)
   rubocop (~> 1.45, >= 1.45.1)
+  rubocop-rspec (~> 2.18, >= 2.18.1)
 
 BUNDLED WITH
    2.4.4

data/README.md

@@ -14,17 +14,10 @@ Lighstorm::Channel.mine.first.myself.node.alias
 
 - [About](#about)
 - [Usage](#usage)
-  - [Installing](#installing)
-  - [Credentials](#credentials)
-  - [Documentation](#documentation)
-    - [API](#api)
-    - [Examples](#examples)
-  - [Data Modeling](#data-modeling)
-    - [Graph Theory](#graph-theory)
-    - [Channel](#channel)
-    - [Forward](#forward)
-    - [Payment](#payment)
+  - [Documentation](https://icebaker.github.io/lighstorm)
 - [Development](#development)
+  - [Testing](#testing)
+  - [Generating Documentation](#generating-documentation)
   - [Publish to RubyGems](#publish-to-rubygems)
 
 ## About
@@ -33,33 +26,16 @@ _Lighstorm_ is an opinionated abstraction layer on top of the [lnd-client](https
 
 It brings an [object-oriented](https://en.wikipedia.org/wiki/Object-oriented_programming) approach for interacting with a [Lightning Node](https://github.com/lightningnetwork/lnd), influenced by the [Active Record Pattern](https://www.martinfowler.com/eaaCatalog/activeRecord.html) and [Active Record Models](https://guides.rubyonrails.org/active_record_basics.html) conventions.
 
-Although it tries to stay close to [Lightning's terminologies](https://docs.lightning.engineering/lightning-network-tools/lnd), it brings its own vocabulary and [data modeling](#data-modeling), optimizing for [programmer happiness](https://rubyonrails.org/doctrine).
+Although it tries to stay close to [Lightning's terminologies](https://docs.lightning.engineering/lightning-network-tools/lnd), it brings its own vocabulary and [data modeling](https://icebaker.github.io/lighstorm/#/README?id=data-modeling), optimizing for [programmer happiness](https://rubyonrails.org/doctrine).
 
 ## Usage
 
-### Installing
-
 Add to your `Gemfile`:
 
 ```ruby
-gem 'lighstorm', '~> 0.0.3'
-```
-
-Run `bundle install`.
-
-### Credentials
-
-Set the following _Environment Variables_ or create a `.env` file:
-```bash
-LIGHSTORM_LND_ADDRESS=127.0.0.1:10009
-LIGHSTORM_CERTIFICATE_PATH=/lnd/tls.cert
-LIGHSTORM_MACAROON_PATH=/lnd/data/chain/bitcoin/mainnet/admin.macaroon
+gem 'lighstorm', '~> 0.0.4'
 ```
 
-It will automatically load your credentials.
-
-Alternatively, you can set the credentials at runtime:
-
 ```ruby
 require 'lighstorm'
 
@@ -69,369 +45,52 @@ Lighstorm.config!(
   macaroon_path: '/lnd/data/chain/bitcoin/mainnet/admin.macaroon',
 )
 
-```
-
-### Documentation
-
-#### API
-
-```ruby
-Lighstorm::Node
-
-Lighstorm::Node.myself # Your Node.
-Lighstorm::Node.all # All 18k+ Nodes on the Network.
-Lighstorm::Node.find_by_public_key(
-  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
-)
-
-node.to_h
-
-node.channels
-
-node.alias
-node.public_key
-node.color
-node.myself?
-
-node.platform.blockchain
-node.platform.network
-node.platform.lightning.implementation
-node.platform.lightning.version
-
-Lighstorm::Channel
-Lighstorm::Channel.mine # Your Node's Channels.
-Lighstorm::Channel.all # All 80k+ Channels on the Network.
-Lighstorm::Channel.find_by_id('850099509773795329')
-
-channel.to_h
-
-channel.mine?
-
-channel.id
-channel.opened_at
-channel.up_at
-channel.active
-channel.exposure
-
-channel.accounting.capacity.milisatoshis
-channel.accounting.sent.milisatoshis
-channel.accounting.received.milisatoshis
-channel.accounting.unsettled.milisatoshis
-
-# Channels that don't belong to you:
-channel.partners
-
-channel.partners[0]
-channel.partners[0].node.alias
-
-channel.partners[1]
-channel.partners[1].node.alias
-
-# Channels that belong to you:
-channel.myself
-channel.myself.node.alias
-
-channel.partner
-channel.partner.node.alias
-
-channel.partner.accounting.balance.milisatoshis
-channel.partner.node.alias
-channel.partner.node.public_key
-channel.partner.node.color
-channel.partner.policy.fee.base.milisatoshis
-channel.partner.policy.fee.rate.parts_per_million
-channel.partner.policy.htlc.minimum.milisatoshis
-channel.partner.policy.htlc.maximum.milisatoshis
-
-channel.myself.accounting.balance.milisatoshis
-channel.myself.node.alias
-channel.myself.node.public_key
-channel.myself.node.color
-channel.myself.policy.fee.base.milisatoshis
-channel.myself.policy.fee.rate.parts_per_million
-channel.myself.policy.htlc.minimum.milisatoshis
-channel.myself.policy.htlc.maximum.milisatoshis
-
-channel.myself.policy.fee.update(
-  { rate: { parts_per_million: 25 } }, preview: true
-)
-
-channel.myself.policy.fee.update(
-  { base: { milisatoshis: 1 } }
-)
-
-channel.myself.policy.fee.update(
-  { rate: { parts_per_million: 25 } }
-)
-
-channel.myself.policy.fee.update(
-  { base: { milisatoshis: 1 }, rate: { parts_per_million: 25 } }
-)
-
-Lighstorm::Forward
-Lighstorm::Forward.all
-Lighstorm::Forward.first
-Lighstorm::Forward.last
-Lighstorm::Forward.all(limit: 10)
-
-forward.to_h
-
-forward.id
-forward.at
-
-forward.fee.milisatoshis
-forward.fee.parts_per_million(
-  forward.in.amount.milisatoshis
-)
-
-forward.in.amount.milisatoshis
-
-forward.in.channel.id
-forward.in.channel.partner.node.alias
-forward.in.channel.partner.node.public_key
-forward.in.channel.partner.node.color
-
-forward.out.channel.id
-forward.out.channel.partner.node.alias
-forward.out.channel.partner.node.public_key
-forward.out.channel.partner.node.color
-
-Lighstorm::Forward.group_by_channel(direction: :in, hours_ago: 24, limit: 5)
-
-group.to_h
-
-group.last_at
-group.analysis.count
-group.analysis.sums.amount.milisatoshis
-group.analysis.sums.fee.milisatoshis
-group.analysis.averages.amount.milisatoshis
-group.analysis.averages.fee.milisatoshis
-group.analysis.averages.fee.parts_per_million(
-  group.analysis.averages.amount.milisatoshis
-)
-
-group.in.id
-group.in.partner.node.alias
-group.in.partner.node.public_key
-group.in.partner.node.color
-
-Lighstorm::Forward.group_by_channel(direction: :out)
-
-group.to_h
-
-group.last_at
-group.analysis.count
-
-group.out.id
-group.out.partner.node.alias
-group.out.partner.node.public_key
-group.out.partner.node.color
-
-Lighstorm::Payment
-Lighstorm::Payment.all
-Lighstorm::Payment.first
-Lighstorm::Payment.last
-Lighstorm::Payment.all(limit: 10, purpose: 'rebalance', hops: false)
-
-payment.id
-payment.hash
-payment.created_at
-payment.purpose
-payment.status
-payment.amount.milisatoshis
-payment.fee.milisatoshis
-payment.fee.parts_per_million(
-  payment.amount.milisatoshis
-)
-
-payment.from.hop
-payment.from.amount.milisatoshis
-payment.from.fee.milisatoshis
-payment.from.fee.parts_per_million(
-  payment.from.amount.milisatoshis
-)
-
-payment.from.channel.id
-payment.from.channel.partner.node.alias
-payment.from.channel.partner.node.public_key
-payment.from.channel.partner.node.color
-
-payment.to.hop
-payment.to.amount.milisatoshis
-payment.to.fee.milisatoshis
-payment.to.fee.parts_per_million(
-  payment.to.amount.milisatoshis
-)
-
-payment.to.channel.id
-payment.to.channel.partner.node.alias
-payment.to.channel.partner.node.public_key
-payment.to.channel.partner.node.color
-
-payment.hops.size
-
-payment.hops[0].hop
-payment.hops[0].amount.milisatoshis
-payment.hops[0].fee.milisatoshis
-payment.hops[0].fee.parts_per_million(
-  payment.hops[0].amount.milisatoshis
-)
-
-payment.hops[0].channel.id
-payment.hops[0].channel.partner.node.alias
-payment.hops[0].channel.partner.node.public_key
-payment.hops[0].channel.partner.node.color
-
-Lighstorm::Satoshis
-Lighstorm::Satoshis.new(milisatoshis: 75621650)
-
-satoshis.to_h
-
-satoshis.milisatoshis
-satoshis.satoshis
-satoshis.bitcoins
-
-satoshis.msats
-satoshis.sats
-satoshis.btc
-
-reference_in_milisatoshis = 75_621_650_000
-satoshis.parts_per_million(reference_in_milisatoshis)
-```
-
-#### Examples
-
-```ruby
-require 'lighstorm'
-
-puts Lighstorm.version # => 0.0.3
+puts Lighstorm.version # => 0.0.4
 
 Lighstorm::Satoshis.new(
-  milisatoshis: 75621650
-).satoshis # => 75621
+  milisatoshis: 75_621_650
+).satoshis # => 75_621
 
 Lighstorm::Node.myself.alias # => icebaker/old-stone
-Lighstorm::Node.myself.public_key # => 02d3...e997
-
-Lighstorm::Node.myself.to_h #> { ... }
-
-Lighstorm::Node.myself.channels.count # => 5
-
-Lighstorm::Channel.mine.first.partner.node.alias
-
-forward = Lighstorm::Forward.all(limit: 10).first
-
-forward.in.amount.milisatoshis # => 75621650
-forward.in.amount.satoshis # => 75621
-forward.in.amount.bitcoins # => 0.0007562165
-forward.in.channel.partner.node.alias
-forward.out.channel.partner.node.alias
-
-forward.to_h # => { ... }
-
-payment = Lighstorm::Payment.all.first
-
-payment.from.channel.id # => 850099509773795329
-payment.to.channel.id # => 821539695188246532
-payment.amount.sats # => 957262
-payment.hops.size # => 4
-payment.hops.first.channel.partner.node.alias
 ```
 
-### Data Modeling
-
-#### Graph Theory
+Check the [full documentation](https://icebaker.github.io/lighstorm).
 
-[Graphs](https://en.wikipedia.org/wiki/Graph_theory) provide a great representation to abstract the [Lightning Network](https://lightning.network) data.
-
-So, we are going to think in terms of _Edges_, _Nodes_, and _Connections_:
-
-![This is an image describing Graphs and their terminologies.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-theory.png)
+## Development
 
-#### Channel
+Copy the `.env.example` file to `.env` and provide the required data.
 
 ```ruby
-channel = Lighstorm::Channel.mine.first
-
-channel.id
-
-channel.accounting.capacity.milisatoshis
+# Gemfile
+gem 'lighstorm', path: '/home/user/lighstorm'
 
-channel.partner.accounting.balance.milisatoshis
-channel.partner.node.alias
-channel.partner.policy.fee.rate.parts_per_million
+# demo.rb
+require 'lighstorm'
 
-channel.myself.accounting.balance.milisatoshis
-channel.myself.node.alias
-channel.myself.policy.fee.rate.parts_per_million
+puts Lighstorm.version # => 0.0.4
 ```
 
-![This is an image representing Channel as a graph.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-channel.png)
-
-#### Forward
-
-```ruby
-forward = Lighstorm::Forward.last
-
-forward.at
-
-forward.fee.parts_per_million
-
-forward.in.amount.milisatoshis
-
-forward.in.channel.id
-forward.in.channel.partner.node.alias
-
-forward.out.channel.id
-forward.out.channel.partner.node.alias
+```sh
+bundle
+rubocop -A
 ```
 
-![This is an image representing Forward as a graph.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-forward.png)
+### Testing
 
-#### Payment
+Copy the `.env.example` file to `.env` and provide the required data.
 
-```ruby
-payment = Payment.last
-
-payment.hash
-payment.amount.milisatoshis
-
-payment.from.hop
-payment.from.amount.milisatoshis
-payment.from.fee.milisatoshis
-payment.from.channel.id
-payment.from.channel.partner.node.alias
-
-payment.to.hop
-payment.to.amount.milisatoshis
-payment.to.fee.milisatoshis
-payment.to.channel.id
-payment.to.channel.partner.node.alias
-
-payment.hops[0].hop
-payment.hops[0].amount.milisatoshis
-payment.hops[0].fee.milisatoshis
-payment.hops[0].channel.id
-payment.hops[0].channel.partner.node.alias
 ```
+bundle
 
-![This is an image representing Payment as a graph.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-payment.png)
-
-## Development
-
-```ruby
-# Gemfile
-gem 'lighstorm', path: '/home/user/lighstorm'
-
-# demo.rb
-require 'lighstorm'
-
-puts Lighstorm.version # => 0.0.3
+bundle exec rspec
 ```
 
+### Generating Documentation
+
 ```sh
-bundle
-rubocop -A
+npm i docsify-cli -g
+
+docsify serve ./docs
 ```
 
 ### Publish to RubyGems
@@ -441,5 +100,5 @@ gem build lighstorm.gemspec
 
 gem signin
 
-gem push lighstorm-0.0.3.gem
+gem push lighstorm-0.0.4.gem
 ```

data/adapters/connections/channel_node/fee.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Lighstorm
+  module Adapter
+    class Fee
+      def self.fee_report(grpc)
+        {
+          _source: :fee_report,
+          id: grpc[:chan_id].to_s,
+          partner: {
+            policy: {
+              fee: {
+                base: {
+                  milisatoshis: grpc[:base_fee_msat]
+                },
+                rate: {
+                  parts_per_million: grpc[:fee_per_mil]
+                }
+              }
+            }
+          }
+        }
+      end
+    end
+  end
+end

data/adapters/connections/channel_node.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative '../nodes/node'
+
+module Lighstorm
+  module Adapter
+    class ChannelNode
+      def self.list_channels(grpc, key)
+        {
+          _source: :list_channels,
+          accounting: { balance: { milisatoshis: grpc[:"#{key}_balance"] * 1000 } },
+          node: Node.list_channels(grpc, key)
+        }
+      end
+
+      def self.get_chan_info(grpc, index)
+        data = {
+          _source: :get_chan_info,
+          node: Node.get_chan_info(grpc, index)
+        }
+
+        if grpc[:"node#{index}_policy"]
+          data[:policy] = {
+            fee: {
+              base: { milisatoshis: grpc[:"node#{index}_policy"][:fee_base_msat] },
+              rate: { parts_per_million: grpc[:"node#{index}_policy"][:fee_rate_milli_msat] }
+            },
+            htlc: {
+              minimum: { milisatoshis: grpc[:"node#{index}_policy"][:min_htlc] },
+              maximum: { milisatoshis: grpc[:"node#{index}_policy"][:max_htlc_msat] },
+              # https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#cltv_expiry_delta-selection
+              blocks: {
+                delta: {
+                  minimum: grpc[:"node#{index}_policy"][:time_lock_delta] # aka cltv_expiry_delta
+                }
+              }
+            }
+          }
+        end
+
+        data
+      end
+
+      def self.describe_graph(grpc, index)
+        {
+          _source: :describe_graph,
+          node: Node.describe_graph_from_channel(grpc, index)
+        }
+      end
+    end
+  end
+end

data/adapters/connections/payment_channel.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Lighstorm
+  module Adapter
+    class PaymentChannel
+      def self.list_payments(grpc, index)
+        {
+          _source: :list_payments,
+          hop: index + 1,
+          amount: { milisatoshis: grpc[:amt_to_forward_msat] },
+          fee: { milisatoshis: grpc[:fee_msat] },
+          channel: {
+            _key: Digest::SHA256.hexdigest(grpc[:chan_id].to_s),
+            id: grpc[:chan_id].to_s,
+            partners: [
+              node: {
+                _key: Digest::SHA256.hexdigest(grpc[:pub_key].to_s),
+                public_key: grpc[:pub_key]
+              }
+            ]
+          }
+        }
+      end
+    end
+  end
+end