lighstorm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc2a22398ed869fa9709af719d701c1fa00f5475f8de245111b40d602211e84d
+  data.tar.gz: c41b6c9d08350d0e4717242eb663b6e85aa9c9c714f46974e4969e340d13a033
+SHA512:
+  metadata.gz: f560d47006a324f3468122cc719a89595523cfb639b8ad6dc45cf4ee7bc4d3bb2befb0a5ec5b02f84d8810bd7364322ef78f224611097a407999aaab571fd8c6
+  data.tar.gz: 1ae71460fae62e5022eeff6f3a91e15dadd23ef382162efb068b74d61cd7ae714b68182165a463b6d035eb6daa0fb5dde5ef0aa1e7c660f91e77a85f42f8f0f7

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.0.0
+  NewCops: enable
+
+Style/Documentation:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - 'ports/dsl/lighstorm.rb'
+
+Layout/LineLength:
+  Exclude:
+    - 'static/spec.rb'

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test, :development do
+  gem 'pry-byebug', '~> 3.10', '>= 3.10.1'
+  gem 'rubocop', '~> 1.44', '>= 1.44.1'
+end

data/Gemfile.lock

@@ -0,0 +1,63 @@
+PATH
+  remote: .
+  specs:
+    lighstorm (0.0.1)
+      dotenv (~> 2.8, >= 2.8.1)
+      lnd-client (~> 0.0.4)
+      zache (~> 0.12.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    dotenv (2.8.1)
+    google-protobuf (3.21.12)
+    googleapis-common-protos-types (1.5.0)
+      google-protobuf (~> 3.14)
+    grpc (1.51.0)
+      google-protobuf (~> 3.21)
+      googleapis-common-protos-types (~> 1.0)
+    json (2.6.3)
+    lnd-client (0.0.4)
+      grpc (~> 1.51)
+    method_source (1.0.0)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    rainbow (3.1.1)
+    regexp_parser (2.6.2)
+    rexml (3.2.5)
+    rubocop (1.44.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.4.2)
+    zache (0.12.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  lighstorm!
+  pry-byebug (~> 3.10, >= 3.10.1)
+  rubocop (~> 1.44, >= 1.44.1)
+
+BUNDLED WITH
+   2.4.4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 icebaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,362 @@
+# Lighstorm
+
+> ⚠️ Warning: Early-stage, breaking changes are expected.
+
+API for interacting with a [Lightning Node](https://lightning.network).
+
+![Lighstorm text written stylized with an illustration of a Graph connecting two Nodes.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/lighstorm.png)
+
+```ruby
+Lighstorm::Channel.first.myself.node.alias
+```
+
+## Index
+
+- [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)
+- [Development](#development)
+  - [Publish to RubyGems](#publish-to-rubygems)
+
+## About
+
+_Lighstorm_ is an opinionated abstraction layer on top of the [lnd-client](https://github.com/icebaker/lnd-client).
+
+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, optimizing for [programmer happiness](https://rubyonrails.org/doctrine).
+
+## Usage
+
+### Installing
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'lighstorm', '~> 0.0.1'
+```
+
+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
+```
+
+It will automatically load your credentials.
+
+Alternatively, you can set the credentials at runtime:
+
+```ruby
+require 'lighstorm'
+
+Lighstorm.config!(
+  lnd_address: '127.0.0.1:10009',
+  certificate_path: '/lnd/tls.cert',
+  macaroon_path: '/lnd/data/chain/bitcoin/mainnet/admin.macaroon',
+)
+
+```
+
+### Documentation
+
+#### API
+
+```ruby
+Lighstorm::Node
+
+Lighstorm::Node.myself
+Lighstorm::Node.find_by_public_key(
+  '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+)
+
+node.to_h
+
+node.channels
+
+node.alias
+node.public_key
+node.color
+
+node.platform.blockchain
+node.platform.network
+node.platform.lightning.implementation
+node.platform.lightning.version
+
+Lighstorm::Channel
+Lighstorm::Channel.all
+Lighstorm::Channel.first
+Lighstorm::Channel.last
+Lighstorm::Channel.find_by_id(850099509773795329)
+
+channel.to_h
+
+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
+
+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.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
+
+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.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::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.from.hop
+payment.from.amount.milisatoshis
+payment.from.fee.milisatoshis
+payment.from.fee.parts_per_million
+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.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].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.1
+
+Lighstorm::Satoshis.new(
+  milisatoshis: 75621650
+).satoshis # => 75621
+
+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.all.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
+
+[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)
+
+#### Channel
+
+```ruby
+channel = Lighstorm::Channel.first
+
+channel.id
+
+channel.accounting.capacity.milisatoshis
+
+channel.partner.accounting.balance.milisatoshis
+channel.partner.node.alias
+channel.partner.policy.fee.rate.parts_per_million
+
+channel.myself.accounting.balance.milisatoshis
+channel.myself.node.alias
+channel.myself.policy.fee.rate.parts_per_million
+```
+
+![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
+```
+
+![This is an image representing Forward as a graph.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/graph-forward.png)
+
+#### Payment
+
+```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
+```
+
+![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.1
+```
+
+```sh
+bundle
+rubocop -A
+```
+
+### Publish to RubyGems
+
+```sh
+gem build lighstorm.gemspec
+
+gem signin
+
+gem push lighstorm-0.0.1.gem
+```

data/components/cache.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+require 'zache'
+
+module Lighstorm
+  class Cache
+    include Singleton
+
+    attr_writer :config, :middleware
+
+    def self.for(...)
+      instance.for(...)
+    end
+
+    def initialize
+      @client = Zache.new
+    end
+
+    def for(key, ttl: 1, params: {}, &block)
+      key = build_key_for(key, params)
+
+      @client.get(key, lifetime: ttl) do
+        block.call
+      end
+    end
+
+    def build_key_for(key, params)
+      return key unless params.size.positive?
+
+      key_params = []
+      params.keys.sort.each do |param_key|
+        key_params << "#{param_key}:#{params[param_key]}"
+      end
+      "#{key}/#{key_params.sort.join(',')}"
+    end
+  end
+end

data/components/lnd.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+require 'lnd-client'
+
+module Lighstorm
+  class LND
+    include Singleton
+
+    attr_writer :config, :middleware
+
+    def initialize
+      @config = nil
+      @client = nil
+      @middleware = ->(_key, &block) { block.call }
+    end
+
+    def middleware(key, &block)
+      @middleware.call(key, &block)
+    end
+
+    def client
+      return @client if @client
+
+      raise 'missing credentials' if @config.nil? && ENV.fetch('LIGHSTORM_CERTIFICATE_PATH', nil).nil?
+
+      @client = if @config
+                  create_client_from_config
+                else
+                  create_client_from_environment_variables
+                end
+
+      @client.lightning(channel_args: { 'grpc.max_receive_message_length' => 1024 * 1024 * 50 })
+
+      @client
+    end
+
+    def create_client_from_config
+      LNDClient.new(
+        socket_address: @config[:lnd_address],
+        certificate_path: @config[:certificate_path],
+        macaroon_path: @config[:macaroon_path]
+      )
+    end
+
+    def create_client_from_environment_variables
+      LNDClient.new(
+        socket_address: ENV.fetch('LIGHSTORM_LND_ADDRESS', nil),
+        certificate_path: ENV.fetch('LIGHSTORM_CERTIFICATE_PATH', nil),
+        macaroon_path: ENV.fetch('LIGHSTORM_MACAROON_PATH', nil)
+      )
+    end
+  end
+end

data/lighstorm.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'static/spec'
+
+Gem::Specification.new do |spec|
+  spec.name    = Lighstorm::Static::SPEC[:name]
+  spec.version = Lighstorm::Static::SPEC[:version]
+  spec.authors = [Lighstorm::Static::SPEC[:author]]
+
+  spec.summary = Lighstorm::Static::SPEC[:summary]
+  spec.description = Lighstorm::Static::SPEC[:description]
+
+  spec.homepage = Lighstorm::Static::SPEC[:github]
+
+  spec.license = Lighstorm::Static::SPEC[:license]
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = Lighstorm::Static::SPEC[:github]
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/})
+    end
+  end
+
+  spec.require_paths = ['ports/dsl']
+
+  spec.add_dependency 'dotenv', '~> 2.8', '>= 2.8.1'
+  spec.add_dependency 'lnd-client', '~> 0.0.4'
+  spec.add_dependency 'zache', '~> 0.12.0'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/models/connections/channel_node/accounting.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../../satoshis'
+
+module Lighstorm
+  module Models
+    class ChannelNodeAccounting
+      def initialize(channel, node)
+        @channel = channel
+        @node = node
+      end
+
+      def balance
+        @balance ||= if @node.myself?
+                       Satoshis.new(milisatoshis: (
+                         @channel.data[:list_channels][:channels].first.local_balance.to_f * 1000.0
+                       ))
+                     else
+                       Satoshis.new(milisatoshis: (
+                         @channel.data[:list_channels][:channels].first.remote_balance.to_f * 1000.0
+                       ))
+                     end
+      end
+
+      def to_h
+        { balance: balance.to_h }
+      end
+    end
+  end
+end

data/models/connections/channel_node/constraints.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lighstorm
+  module Models
+    class Constraints
+      def initialize(channel, node)
+        @channel = channel
+        @node = node
+      end
+
+      def data
+        @data ||= if @node.myself?
+                    @channel.data[:list_channels][:channels].first.local_constraints
+                  else
+                    @channel.data[:list_channels][:channels].first.remote_constraints
+                  end
+      end
+
+      def to_h
+        data.to_h
+      end
+    end
+  end
+end

data/models/connections/channel_node/fee.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../../satoshis'
+require_relative '../../rate'
+
+module Lighstorm
+  module Models
+    class Fee
+      def initialize(policy, channel, node)
+        if node.myself?
+          @base = Satoshis.new(
+            milisatoshis: channel.data[:fee_report][:channel_fees].first.base_fee_msat
+          )
+
+          @rate = Rate.new(
+            parts_per_million: channel.data[:fee_report][:channel_fees].first.fee_per_mil
+          )
+        else
+          @base = Satoshis.new(milisatoshis: policy.data.fee_base_msat)
+
+          @rate = Rate.new(parts_per_million: policy.data.fee_rate_milli_msat)
+        end
+      end
+
+      def to_h
+        {
+          base: @base.to_h,
+          rate: @rate.to_h
+        }
+      end
+    end
+  end
+end