utxoracle 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e06742e7448c182f3f2399e200c50e0563f3d8672433d942028cbc7c1827f60b
+  data.tar.gz: 33f2c9d1d7e496664c84a682e3b0d09a0971f152f7f351b59d7cdeb0baa48bba
+SHA512:
+  metadata.gz: b64d8799da84d9ee041e61548adcf889067bd0bcef7b5331d59e43aca4bec7a4075d6bdd0773939132d9b8dec4b428e60a05be9bf9b720ecfec74b40b805e74f
+  data.tar.gz: caeb20a9d134903c29cccfd3bd03697a1bcf5b56452762ea383850b9423a4bc056d7ac77e4d18ed6f455d7765e21935421172ccd2ab3ca733298545792a03628

data/.gitignore

@@ -0,0 +1,59 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+/Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rspec_status

@@ -0,0 +1,8 @@
+example_id                             | status | run_time        |
+-------------------------------------- | ------ | --------------- |
+./spec/utxoracle/oracle_spec.rb[1:1:1] | failed | 0.00966 seconds |
+./spec/utxoracle/rpc_spec.rb[1:1:1]    | passed | 0.00025 seconds |
+./spec/utxoracle/rpc_spec.rb[1:2]      | passed | 0.01109 seconds |
+./spec/utxoracle/rpc_spec.rb[1:3]      | passed | 0.00028 seconds |
+./spec/utxoracle/rpc_spec.rb[1:4]      | passed | 0.00214 seconds |
+./spec/utxoracle_spec.rb[1:1]          | passed | 0.00127 seconds |

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Carolina-Bitcoin-Project
+
+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,92 @@
+# UTXOracle.rb
+Ruby implementation of https://utxo.live/oracle/.
+
+(Original implementation by [SteveSimple](https://twitter.com/SteveSimple) & [DanielLHinton](https://twitter.com/DanielLHinton) who discovered and built the first offline bitcoin price oracle.)
+
+## Table of contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  * [Requiring the gem](#requiring-the-gem)
+  * [Fetching Price](#fetching-price)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add utxoracle
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install utxoracle
+
+## Usage
+
+### Requiring the gem
+
+All examples below assume that the gem has been required.
+
+```ruby
+require 'utxoracle'
+```
+
+
+### Fetching price
+
+#### Using a raw bitcoin node
+```ruby
+provider = Utxoracle::RawBitcoinNode.new("aUser", "aPassword", "127.0.0.1", 8332)
+```
+
+#### Using mempool.space node
+```ruby
+provider = Utxoracle::MempoolDotSpace.new
+```
+
+####
+```ruby
+oracle = Utxoracle::Oracle.new(provider)
+oracle.price("2023-10-30")
+34840
+```
+
+## Development
+
+After checking out the repo, run `bundle i` to install dependencies.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file
+to [rubygems.org](https://rubygems.org).
+
+The health and maintainability of the codebase is ensured through a set of
+Rake tasks to test, lint and audit the gem for security vulnerabilities and documentation:
+
+```
+rake build                    # Build utxoracle-0.0.1.gem into the pkg directory
+rake build:checksum           # Generate SHA512 checksum if utxoracle-0.0.1.gem into the checksums directory
+rake clean                    # Remove any temporary products
+rake clobber                  # Remove any generated files
+rake install                  # Build and install utxoracle-0.0.1.gem into system gems
+rake install:local            # Build and install utxoracle-0.0.1.gem into system gems without network access
+rake release[remote]          # Create tag v0.0.1 and build and push utxoracle-0.0.1.gem to rubygems.org
+rake rubocop                  # Run RuboCop
+rake rubocop:autocorrect      # Autocorrect RuboCop offenses (only when it's safe)
+rake rubocop:autocorrect_all  # Autocorrect RuboCop offenses (safe and unsafe)
+rake spec                     # Run RSpec code examples
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Carolina-Bitcoin-Project/UTXOracle.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'rubocop/rake_task'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ['--display-cop-names']
+end

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'utxoracle'
+require 'pry'
+
+Pry.start

data/lib/utxoracle/oracle.rb

@@ -0,0 +1,352 @@
+require 'time'
+require_relative 'rpc'
+require_relative 'providers/raw_bitcoin_node'
+
+module Utxoracle
+  class Oracle
+    SECONDS_IN_A_DAY      = 60 * 60 * 24
+    FOUR_HOURS            = 14_400
+    MAINNET_PORT          = 8332
+    TESTNET_PORT          = 18_332
+    NUMBER_OF_BINS        = 2401
+
+    def initialize(provider, log = false)
+      @provider           = provider
+      @log                = log
+      @round_usd_stencil  = build_round_usd_stencil
+      @cache              = {}
+    end
+
+    def price(requested_date)
+      unless validate_date(requested_date)
+        puts "Invalid date.\nEarliest available: 2020-07-26.\nLatest available #{Date.today}.\nFormat: YYYY-MM-DD."
+        return
+      end
+
+      if price_estimate = @cache[requested_date]
+        puts "price_estimate is #{price_estimate}"
+        return price_estimate
+      end
+
+      @requested_date = Time.parse requested_date.tr('\n', '')
+      @cache[requested_date] = run
+      @cache[requested_date]
+    end
+
+    private
+
+    # TODO: - Refactor.
+    # We need this code to be "plug and play" - so stats wizards can
+    # quickly iterate on different models. Or even chat-gpt to cross
+    # reference with historical exchange prices.
+    def run
+      block_count     = @provider.getblockcount
+      block_hash      = @provider.getblockhash(block_count)
+      blockheader     = @provider.getblockheader(block_hash, true)
+
+      time_datetime = Time.at(blockheader['time']).utc
+      latest_year = time_datetime.year
+      latest_month = time_datetime.month
+      latest_day = time_datetime.day
+      latest_utc_midnight = Time.new(latest_year, latest_month, latest_day).utc
+
+      latest_time_in_seconds = blockheader['time']
+      yesterday_seconds = latest_time_in_seconds - SECONDS_IN_A_DAY
+      latest_price_day = Time.at(yesterday_seconds).utc
+      latest_price_date = latest_price_day.utc.strftime('%Y-%m-%d')
+
+      price_day_seconds =  @requested_date.to_i - FOUR_HOURS
+      price_day_date_utc = @requested_date
+
+      seconds_since_price_day = latest_time_in_seconds - price_day_seconds
+      blocks_ago_estimate = (144 * seconds_since_price_day.to_f / SECONDS_IN_A_DAY.to_f).round
+      price_day_block_estimate = (block_count - blocks_ago_estimate).to_i
+
+      block_hash_b       = @provider.getblockhash(price_day_block_estimate)
+      block_header       = @provider.getblockheader(block_hash_b, true)
+      time_in_seconds = block_header['time']
+
+      seconds_difference = time_in_seconds - price_day_seconds
+      block_jump_estimate = (144.0 * seconds_difference / SECONDS_IN_A_DAY).round
+
+      last_estimate = 0
+      last_last_estimate = 0
+      while block_jump_estimate > 6 && block_jump_estimate != last_last_estimate
+        last_last_estimate = last_estimate
+        last_estimate = block_jump_estimate
+
+        price_day_block_estimate -= block_jump_estimate
+        block_hash_b       = @provider.getblockhash(price_day_block_estimate)
+        block_header       = @provider.getblockheader(block_hash_b, true)
+
+        time_in_seconds = block_header['time']
+        seconds_difference = time_in_seconds - price_day_seconds
+        block_jump_estimate = (144.0 * seconds_difference / SECONDS_IN_A_DAY).round
+      end
+
+      if time_in_seconds > price_day_seconds
+        while time_in_seconds > price_day_seconds
+          price_day_block_estimate -= 1
+          block_hash_b       = @provider.getblockhash(price_day_block_estimate)
+          block_header       = @provider.getblockheader(block_hash_b, true)
+          time_in_seconds = block_header['time']
+        end
+
+        price_day_block_estimate += 1
+      elsif time_in_seconds < price_day_seconds
+        while time_in_seconds < price_day_seconds
+          price_day_block_estimate += 1
+          block_hash_b       = @provider.getblockhash(price_day_block_estimate)
+          block_header       = @provider.getblockheader(block_hash_b, true)
+          time_in_seconds = block_header['time']
+        end
+      end
+
+      price_day_block = price_day_block_estimate
+
+      first_bin_value = -6
+      last_bin_value = 6
+      range_bin_values = last_bin_value - first_bin_value
+
+      output_bell_curve_bins = [0.0]
+
+      for exponent in -6..5
+        for bin_width in 0..199
+          bin_value = 10**(exponent + bin_width / 200.0).to_f
+          output_bell_curve_bins << bin_value
+        end
+      end
+
+      output_bell_curve_bin_counts = []
+      for n in 0..NUMBER_OF_BINS - 1
+        output_bell_curve_bin_counts << 0.0
+      end
+
+      puts("Reading all blocks on #{price_day_date_utc}...") if @log
+      puts('This will take a few minutes (~144 blocks)...') if @log
+      puts("Height\tTime(utc)\t Completion %") if @log
+
+      block_height = price_day_block_estimate
+      block_hash_b = @provider.getblockhash(block_height)
+      block_b = @provider.getblock(block_hash_b, 2)
+
+      time = Time.at(block_b['time']).utc
+      time_in_seconds = block_b['time']
+
+      hour = time.hour
+      day = time.day
+      minute = time.min
+
+      target = day
+      blocks_on_this_day = 0
+
+      while target == day
+        blocks_on_this_day += 1
+
+        progress_estimate = 100.0 * (hour + minute / 60) / 24.0
+        puts("#{block_height}\t#{time.strftime('%H:%M:%S')}\t#{progress_estimate}") if @log
+
+        for tx in block_b['tx']
+          outputs = tx['vout']
+          for output in outputs
+
+            amount = output['value']
+            next unless 1e-6 < amount && amount < 1e6
+
+            amount_log = Math.log10 amount
+
+            percent_in_range = (amount_log - first_bin_value).to_f / range_bin_values.to_f
+            bin_number_est = (percent_in_range * NUMBER_OF_BINS).to_i
+
+            bin_number_est += 1 while output_bell_curve_bins[bin_number_est] <= amount
+            bin_number = bin_number_est - 1
+
+            output_bell_curve_bin_counts[bin_number] += 1.0
+          end
+        end
+
+        block_height += 1
+        block_hash_b = @provider.getblockhash(block_height)
+        block_b = @provider.getblock(block_hash_b, 2)
+
+        time = Time.at(block_b['time']).utc
+        time_in_seconds = block_b['time']
+        hour = time.hour
+        day = time.day
+        minute = time.min
+      end
+
+      puts "blocks_on_this_day: #{blocks_on_this_day}" if @log
+
+      for n in 0..201 - 1
+        output_bell_curve_bin_counts[n] = 0.0
+      end
+
+      for n in 1601..NUMBER_OF_BINS - 1
+        output_bell_curve_bin_counts[n] = 0.0
+      end
+
+      for r in round_btc_bins
+        amount_above = output_bell_curve_bin_counts[r + 1]
+        amount_below = output_bell_curve_bin_counts[r - 1]
+        output_bell_curve_bin_counts[r] = 0.5 * (amount_above + amount_below).to_f
+      end
+
+      curve_sum = 0.0
+      for n in 201..1601 - 1
+        curve_sum += output_bell_curve_bin_counts[n]
+      end
+
+      for n in 201..1601 - 1
+        output_bell_curve_bin_counts[n] /= curve_sum
+        output_bell_curve_bin_counts[n] = 0.008 if output_bell_curve_bin_counts[n] > 0.008
+      end
+
+      best_slide       = 0
+      best_slide_score = 0.0
+      total_score      = 0.0
+      number_of_scores = 0
+
+      min_slide = -200
+      max_slide = 200
+
+      for slide in min_slide..max_slide - 1
+        shifted_curve = output_bell_curve_bin_counts.slice(201 + slide, 1401 + slide)
+
+        slide_score = 0.0
+        for n in 0..shifted_curve.count - 1
+          slide_score += shifted_curve[n] * @round_usd_stencil[n + 201]
+        end
+
+        total_score += slide_score
+        number_of_scores += 1
+
+        if slide_score > best_slide_score
+          best_slide_score = slide_score
+          best_slide = slide
+        end
+      end
+
+      usd100_in_btc_best = output_bell_curve_bins[801 + best_slide]
+      btc_in_usd_best = 100 / usd100_in_btc_best
+
+      neighbor_up = output_bell_curve_bin_counts.slice(201 + best_slide + 1, 1401 + best_slide + 1)
+      neighbor_up_score = 0.0
+      for n in 0..neighbor_up.count - 1
+        neighbor_up_score += (neighbor_up[n] * @round_usd_stencil[n + 201]).to_f
+      end
+
+      neighbor_down = output_bell_curve_bin_counts.slice(201 + best_slide - 1, 1401 + best_slide - 1)
+      neighbor_down_score = 0.0
+      for n in 0..neighbor_down.count - 1
+        neighbor_down_score += (neighbor_down[n] * @round_usd_stencil[n + 201]).to_f
+      end
+
+      best_neighbor = +1
+      neighbor_score = neighbor_up_score
+      if neighbor_down_score > neighbor_up_score
+        best_neighbor = -1
+        neighbor_score = neighbor_down_score
+      end
+
+      usd100_in_btc_2nd = output_bell_curve_bins[801 + best_slide + best_neighbor]
+      btc_in_usd_2nd = 100 / usd100_in_btc_2nd.to_f
+
+      # weight average the two usd price estimates
+      avg_score = total_score / number_of_scores.to_f
+      a1 = best_slide_score - avg_score
+      a2 = (neighbor_score - avg_score).abs # theoretically possible to be negative
+      w1 = a1 / (a1 + a2).to_f
+      w2 = a2 / (a1 + a2)
+      price_estimate = (w1 * btc_in_usd_best + w2 * btc_in_usd_2nd).to_i
+
+      puts "price_estimate is #{price_estimate}" if @log
+
+      price_estimate
+    end
+
+    def build_round_usd_stencil
+      round_usd_stencil = []
+      for n in 0..NUMBER_OF_BINS
+        round_usd_stencil.append(0.0)
+      end
+
+      # fill the round usd stencil with the values found by the process mentioned above
+      round_usd_stencil[401] = 0.0005957955691168063     # $1
+      round_usd_stencil[402] = 0.0004454790662303128     # (next one for tx/atm fees)
+      round_usd_stencil[429] = 0.0001763099393598914     # $1.50
+      round_usd_stencil[430] = 0.0001851801497144573
+      round_usd_stencil[461] = 0.0006205616481885794     # $2
+      round_usd_stencil[462] = 0.0005985696860584984
+      round_usd_stencil[496] = 0.0006919505728046619     # $3
+      round_usd_stencil[497] = 0.0008912933078342840
+      round_usd_stencil[540] = 0.0009372916238804205     # $5
+      round_usd_stencil[541] = 0.0017125522985034724     # (larger needed range for fees)
+      round_usd_stencil[600] = 0.0021702347223143030
+      round_usd_stencil[601] = 0.0037018622326411380     # $10
+      round_usd_stencil[602] = 0.0027322168706743802
+      round_usd_stencil[603] = 0.0016268322583097678     # (larger needed range for fees)
+      round_usd_stencil[604] = 0.0012601953416497664
+      round_usd_stencil[661] = 0.0041425242880295460     # $20
+      round_usd_stencil[662] = 0.0039247767475640830
+      round_usd_stencil[696] = 0.0032399441632017228     # $30
+      round_usd_stencil[697] = 0.0037112959007355585
+      round_usd_stencil[740] = 0.0049921908828370000     # $50
+      round_usd_stencil[741] = 0.0070636869018197105
+      round_usd_stencil[801] = 0.0080000000000000000     # $100
+      round_usd_stencil[802] = 0.0065431388282424440     # (larger needed range for fees)
+      round_usd_stencil[803] = 0.0044279509203361735
+      round_usd_stencil[861] = 0.0046132440551747015     # $200
+      round_usd_stencil[862] = 0.0043647851395531140
+      round_usd_stencil[896] = 0.0031980892880846567     # $300
+      round_usd_stencil[897] = 0.0034237641632481910
+      round_usd_stencil[939] = 0.0025995335505435034     # $500
+      round_usd_stencil[940] = 0.0032631930982226645     # (larger needed range for fees)
+      round_usd_stencil[941] = 0.0042753262790881080
+      round_usd_stencil[1001] = 0.0037699501474772350     # $1,000
+      round_usd_stencil[1002] = 0.0030872891064215764     # (larger needed range for fees)
+      round_usd_stencil[1003] = 0.0023237040836798163
+      round_usd_stencil[1061] = 0.0023671764210889895     # $2,000
+      round_usd_stencil[1062] = 0.0020106877104798474
+      round_usd_stencil[1140] = 0.0009099214128654502     # $3,000
+      round_usd_stencil[1141] = 0.0012008546799361498
+      round_usd_stencil[1201] = 0.0007862586076341524     # $10,000
+      round_usd_stencil[1202] = 0.0006900048077192579
+
+      round_usd_stencil
+    end
+
+    def round_btc_bins
+      [
+        201,  # 1k sats
+        401,  # 10k
+        461,  # 20k
+        496,  # 30k
+        540,  # 50k
+        601,  # 100k
+        661,  # 200k
+        696,  # 300k
+        740,  # 500k
+        801,  # 0.01 btc
+        861,  # 0.02
+        896,  # 0.03
+        940,  # 0.04
+        1001, # 0.1
+        1061, # 0.2
+        1096, # 0.3
+        1140, # 0.5
+        1201  # 1 btc
+      ]
+    end
+
+    def validate_date(date)
+      y, m, d = date.split '-'
+      valid_format = Date.valid_date? y.to_i, m.to_i, d.to_i
+
+      valid_range = (Date.parse(date) > Date.parse('2020-7-26')) &&
+                    (Date.parse(date) < Date.today)
+
+      valid_format && valid_range
+    end
+  end
+end

data/lib/utxoracle/provider.rb

@@ -0,0 +1,25 @@
+module Utxoracle
+  class Provider
+    def init
+      raise NoMethodError
+    end
+
+    def getblockcount
+      raise NoMethodError
+    end
+
+    def getblockhash
+      raise NoMethodError
+    end
+
+    def getblockheader
+      raise NoMethodError
+    end
+
+    def getblock
+      raise NoMethodError
+    end
+
+    # TODO: - Build a mechanism allowing for fallbacks; be fault tolerant to node, website, etc.
+  end
+end

data/lib/utxoracle/providers/mempool_dot_space.rb

@@ -0,0 +1,69 @@
+require_relative '../provider'
+require_relative '../request'
+
+# Unfortunately Mempool limits the number of tx's you can fetch in bulk,
+# and throttles the number of requests the oracle takes to compute.
+# Running this requires an Enterprise license.
+module Utxoracle
+  class MempoolDotSpace < Provider
+    def initialize; end
+
+    def getblockcount
+      Request.send('https://mempool.space/api/blocks/tip/height').body.to_i
+    end
+
+    def getblockhash(height)
+      Request.send("https://mempool.space/api/block-height/#{height}").body
+    end
+
+    # Oracle.price needs blockheader['time']
+    def getblockheader(block_hash, _verbose = true)
+      hex_block_header = Request.send("https://mempool.space/api/block/#{block_hash}/header").body
+
+      # version = hex_to_int(reverse_byte_order(hex_block_header[0..7]))
+      # prev_block_hash = reverse_byte_order(hex_block_header[8..71])
+      # merkle_root = reverse_byte_order(hex_block_header[72..135])
+      timestamp = hex_to_int(reverse_byte_order(hex_block_header[136..143]))
+      # bits = reverse_byte_order(hex_block_header[144..151])
+      # nonce = hex_to_int(reverse_byte_order(hex_block_header[152..159]))
+
+      {
+        'time' => timestamp
+      }
+    end
+
+    def getblock(block_hash, _verbosity = 2)
+      block = JSON.parse Request.send("https://mempool.space/api/block/#{block_hash}").body
+
+      # mempool API maps 'timestamp' to 'time'
+      block['time'] = block['timestamp']
+
+      # mempool API doesn't return tx. Set to empty array:
+      block['tx'] = []
+
+      # Get all tx_ids in the block
+      tx_ids = JSON.parse Request.send("https://mempool.space/api/block/#{block_hash}/txids").body
+
+      # Append vout to block['tx']
+      # ( requires mempool enterprise: 429 Too Many Requests)
+      tx_ids.each do |tx_id|
+        tx = JSON.parse Request.send("https://mempool.space/api/tx/#{tx_id}").body
+        block['tx'] << tx['vout']
+      end
+
+      block
+    end
+
+    private
+
+    # Reverse byte order in a hexadecimal string.
+    def reverse_byte_order(hex_string)
+      hex_string.scan(/../).reverse.join
+    end
+
+    # Convert hexadecimal string to an integer.
+    def hex_to_int(hex_string)
+      hex_string.to_i(16)
+    end
+  end
+end

data/lib/utxoracle/providers/raw_bitcoin_node.rb

@@ -0,0 +1,26 @@
+require_relative '../provider'
+require_relative '../rpc'
+
+module Utxoracle
+  class RawBitcoinNode < Provider
+    def initialize(rpcuser, rpcpassword, ip, port)
+      @rpc = Rpc.new("http://#{rpcuser}:#{rpcpassword}@#{ip}:#{port}")
+    end
+
+    def getblockcount
+      @rpc.getblockcount
+    end
+
+    def getblockhash(height)
+      @rpc.getblockhash(height)
+    end
+
+    def getblockheader(block_hash, verbose = true)
+      @rpc.getblockheader(block_hash, verbose)
+    end
+
+    def getblock(block_hash, verbosity = 2)
+      @rpc.getblock(block_hash, verbosity)
+    end
+  end
+end

data/lib/utxoracle/request.rb

@@ -0,0 +1,16 @@
+require 'typhoeus'
+
+class Request
+  def self.send(domain, method = :get, body = '', params = {}, headers = {})
+    request = Typhoeus::Request.new(
+      domain,
+      method:,
+      body:,
+      params:,
+      headers:
+    )
+
+    request.run
+    request.response
+  end
+end

data/lib/utxoracle/rpc.rb

@@ -0,0 +1,30 @@
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Utxoracle
+  class Rpc
+    def initialize(service_url)
+      @uri = URI.parse(service_url)
+    end
+
+    def method_missing(name, *args)
+      post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json
+      resp = JSON.parse(http_post_request(post_body))
+      raise JSONRPCError, resp['error'] if resp['error']
+
+      resp['result']
+    end
+
+    def http_post_request(post_body)
+      http    = Net::HTTP.new(@uri.host, @uri.port)
+      request = Net::HTTP::Post.new(@uri.request_uri)
+      request.basic_auth @uri.user, @uri.password
+      request.content_type = 'application/json'
+      request.body = post_body
+      http.request(request).body
+    end
+
+    class JSONRPCError < RuntimeError; end
+  end
+end

data/lib/utxoracle/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Utxoracle
+  VERSION = '0.0.1'
+end

data/lib/utxoracle.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'utxoracle/rpc'
+require_relative 'utxoracle/version'
+require_relative 'utxoracle/oracle'
+require_relative 'utxoracle/providers/mempool_dot_space'
+require_relative 'utxoracle/providers/raw_bitcoin_node'
+
+module Utxoracle
+end

data/spec/spec_helper.rb

@@ -0,0 +1,33 @@
+require 'simplecov'
+require 'simplecov-console'
+require 'pry'
+
+SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
+  [
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::Console
+  ]
+)
+
+unless ENV['COVERAGE'] == 'false'
+  SimpleCov.start do
+    root 'lib'
+    coverage_dir "#{Dir.pwd}/coverage"
+  end
+end
+
+require 'utxoracle'
+
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = '.rspec_status'
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

data/spec/utxoracle/oracle_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# RSpec.describe Utxoracle::Oracle do
+#   let(:oracle) do
+#     described_class.new('aUser', 'aPassword', '127.0.0.1', '8332')
+#   end
+#
+#   describe '.new' do
+#     it 'initialized an Rpc instance' do
+#       expect(Utxoracle::Rpc).to receive(:new)
+#       described_class.new('aUser', 'aPassword', '127.0.0.1', '8332')
+#       expect(oracle.class).to eq Utxoracle::Oracle
+#     end
+#   end
+#
+#   # TODO: - test cache
+#   # TODO - test provider interface
+#   # TODO - test `price` return type
+# end

data/spec/utxoracle/rpc_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Utxoracle::Rpc do
+  let(:rpc) do
+    described_class.new('http://foo:bar@127.0.0.1:8332')
+  end
+  describe '.new' do
+    it 'creates an instance of Rpc with given uri' do
+      expect(rpc.class).to eq(Utxoracle::Rpc)
+    end
+  end
+
+  it 'exposes http request interface' do
+    allow(rpc).to receive(:http_post_request).and_return(true)
+    expect(rpc.http_post_request('')).to eq true
+  end
+
+  it 'forwards methods over http' do
+    allow(rpc).to receive(:http_post_request).and_return("{\"result\":814521,\"error\":null,\"id\":\"jsonrpc\"}\n")
+    expect(rpc.getblockcount).to eq 814_521
+  end
+
+  it 'returns error from http endpoint when indicated' do
+    expect(rpc).to receive(:http_post_request).and_return("{\"result\":814521,\"error\":\"test error\",\"id\":\"jsonrpc\"}\n")
+    expect { rpc.test_rpc_call }.to raise_error(Utxoracle::Rpc::JSONRPCError)
+  end
+end

data/spec/utxoracle_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Utxoracle do
+  it 'has a version number' do
+    expect(Utxoracle::VERSION).not_to be_nil
+  end
+end

data/utxoracle.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$:.unshift lib unless $:.include?(lib)
+
+require 'utxoracle/version'
+
+Gem::Specification.new do |spec|
+  spec.name                   = 'utxoracle'
+  spec.version                = Utxoracle::VERSION
+  spec.platform               = Gem::Platform::RUBY
+  spec.authors                = ['Keith Gardner']
+
+  spec.summary                = 'Interface for UTXOracle.'
+  spec.description            = 'Object oriented design for interacting with UTXOracle.'
+  spec.homepage               = 'https://github.com/Carolina-Bitcoin-Project/UTXOracle'
+  spec.license                = 'MIT'
+  spec.required_ruby_version  = '>= 3.1.0'
+
+  spec.files                  = `git ls-files`.split("\n")
+  spec.bindir                 = 'exe'
+  spec.require_path           = 'lib'
+
+  spec.add_dependency 'typhoeus'
+
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov-console'
+end

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification
+name: utxoracle
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Keith Gardner
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Object oriented design for interacting with UTXOracle.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rspec_status"
+- ".ruby-version"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- lib/utxoracle.rb
+- lib/utxoracle/oracle.rb
+- lib/utxoracle/provider.rb
+- lib/utxoracle/providers/mempool_dot_space.rb
+- lib/utxoracle/providers/raw_bitcoin_node.rb
+- lib/utxoracle/request.rb
+- lib/utxoracle/rpc.rb
+- lib/utxoracle/version.rb
+- spec/spec_helper.rb
+- spec/utxoracle/oracle_spec.rb
+- spec/utxoracle/rpc_spec.rb
+- spec/utxoracle_spec.rb
+- utxoracle.gemspec
+homepage: https://github.com/Carolina-Bitcoin-Project/UTXOracle
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Interface for UTXOracle.
+test_files: []