bsv-sdk 0.1.0 → 0.2.0

data/lib/bsv/transaction/beef.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module BSV
   module Transaction
     # Background Evaluation Extended Format (BEEF) for SPV-ready transaction
@@ -104,6 +106,11 @@ module BSV
       # @param data [String] raw BEEF binary
       # @return [Beef] the parsed BEEF bundle
       def self.from_binary(data)
+        if data.bytesize < 4
+          raise ArgumentError,
+                "truncated BEEF: need at least 4 bytes for version, got #{data.bytesize}"
+        end
+
         offset = 0
 
         version = data.byteslice(offset, 4).unpack1('V')
@@ -112,9 +119,13 @@ module BSV
         beef = new(version: version)
 
         if version == ATOMIC_BEEF
+          if data.bytesize < offset + 36
+            remaining = data.bytesize - offset
+            raise ArgumentError, "truncated Atomic BEEF: need 36 bytes at offset #{offset}, got #{remaining}"
+          end
+
           beef.instance_variable_set(:@subject_txid, data.byteslice(offset, 32))
           offset += 32
-          # Read inner V2 version
           inner_version = data.byteslice(offset, 4).unpack1('V')
           offset += 4
           beef.instance_variable_set(:@version, inner_version)
@@ -208,6 +219,261 @@ module BSV
         nil
       end
 
+      # Find the merkle path (BUMP) for a transaction by its txid.
+      #
+      # @param txid [String] 32-byte txid in internal byte order
+      # @return [MerklePath, nil] the merkle path, or nil if not found
+      def find_bump(txid)
+        bt = @transactions.find { |entry| entry.txid == txid && entry.format == FORMAT_RAW_TX_AND_BUMP }
+        return unless bt
+
+        bt.transaction&.merkle_path || (bt.bump_index && @bumps[bt.bump_index])
+      end
+
+      # Find a transaction with all source_transactions wired for signing.
+      #
+      # @param txid [String] 32-byte txid in internal byte order
+      # @return [Transaction, nil] the transaction with wired inputs, or nil
+      def find_transaction_for_signing(txid)
+        tx = find_transaction(txid)
+        return unless tx
+
+        wire_inputs(tx)
+        tx
+      end
+
+      # Find a transaction and recursively wire its ancestry (source transactions
+      # and merkle paths) for atomic proof validation.
+      #
+      # @param txid [String] 32-byte txid in internal byte order
+      # @return [Transaction, nil] the transaction with full proof tree, or nil
+      def find_atomic_transaction(txid)
+        tx = find_transaction(txid)
+        return unless tx
+
+        wire_ancestry(tx)
+        tx
+      end
+
+      # Serialise as Atomic BEEF (BRC-95) hex string.
+      #
+      # @param subject_txid [String] 32-byte subject transaction ID
+      # @return [String] hex-encoded Atomic BEEF
+      def to_atomic_hex(subject_txid)
+        to_atomic_binary(subject_txid).unpack1('H*')
+      end
+
+      # --- Merge operations ---
+
+      # Add or deduplicate a merkle path (BUMP) in this BEEF bundle.
+      #
+      # If an existing BUMP shares the same block_height and merkle root,
+      # it is combined (via MerklePath#combine) and the existing index is
+      # returned. Otherwise the BUMP is appended.
+      #
+      # @param merkle_path [MerklePath] the BUMP to merge
+      # @return [Integer] the index of the (possibly merged) BUMP
+      def merge_bump(merkle_path)
+        root = merkle_path.compute_root
+        @bumps.each_with_index do |existing, idx|
+          next unless existing.block_height == merkle_path.block_height
+
+          if existing.compute_root == root
+            existing.combine(merkle_path)
+            return idx
+          end
+        end
+
+        @bumps << merkle_path
+        @bumps.length - 1
+      end
+
+      # Add a transaction to this BEEF bundle.
+      #
+      # Recursively merges the transaction's ancestors (via source_transaction
+      # references on inputs) and their merkle paths. Duplicate transactions
+      # (same txid) are not re-added.
+      #
+      # @param tx [Transaction] the transaction to merge
+      # @return [BeefTx] the (possibly existing) BeefTx entry
+      def merge_transaction(tx)
+        txid = tx.txid
+
+        # Check for existing entry
+        existing = @transactions.find { |bt| bt.txid == txid }
+        return existing if existing
+
+        # Recursively merge ancestors first (dependency order)
+        tx.inputs.each do |input|
+          merge_transaction(input.source_transaction) if input.source_transaction
+        end
+
+        # Merge this transaction's BUMP if it has one
+        entry = if tx.merkle_path
+                  bump_idx = merge_bump(tx.merkle_path)
+                  BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_idx)
+                else
+                  BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+                end
+        @transactions << entry
+        entry
+      end
+
+      # Add a transaction from raw binary data.
+      #
+      # @param raw_bytes [String] raw transaction binary
+      # @param bump_index [Integer, nil] optional BUMP index
+      # @return [BeefTx] the new BeefTx entry
+      def merge_raw_tx(raw_bytes, bump_index: nil)
+        tx = Transaction.from_binary(raw_bytes)
+        existing = @transactions.find { |bt| bt.txid == tx.txid }
+        return existing if existing
+
+        entry = if bump_index
+                  tx.merkle_path = @bumps[bump_index] if bump_index < @bumps.length
+                  BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index)
+                else
+                  BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+                end
+        @transactions << entry
+        entry
+      end
+
+      # Merge all BUMPs and transactions from another BEEF bundle.
+      #
+      # BUMP indices are remapped during merge.
+      #
+      # @param other [Beef] the BEEF bundle to merge from
+      # @return [self]
+      def merge(other)
+        # Build index remap for BUMPs
+        bump_remap = {}
+        other.bumps.each_with_index do |bump, old_idx|
+          bump_remap[old_idx] = merge_bump(bump)
+        end
+
+        # Merge transactions with remapped BUMP indices
+        other.transactions.each do |beef_tx|
+          case beef_tx.format
+          when FORMAT_TXID_ONLY
+            next if @transactions.any? { |bt| bt.txid == beef_tx.known_txid }
+
+            @transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_txid: beef_tx.known_txid)
+          else
+            next if @transactions.any? { |bt| bt.txid == beef_tx.txid }
+
+            if beef_tx.format == FORMAT_RAW_TX_AND_BUMP && beef_tx.bump_index
+              new_idx = bump_remap[beef_tx.bump_index] || beef_tx.bump_index
+              beef_tx.transaction.merkle_path = @bumps[new_idx]
+              @transactions << BeefTx.new(
+                format: FORMAT_RAW_TX_AND_BUMP,
+                transaction: beef_tx.transaction,
+                bump_index: new_idx
+              )
+            else
+              @transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: beef_tx.transaction)
+            end
+          end
+        end
+
+        self
+      end
+
+      # Convert a transaction entry to TXID-only format.
+      #
+      # @param txid [String] 32-byte txid in internal byte order
+      # @return [BeefTx, nil] the converted entry, or nil if not found
+      def make_txid_only(txid)
+        idx = @transactions.index { |bt| bt.txid == txid }
+        return unless idx
+
+        @transactions[idx] = BeefTx.new(format: FORMAT_TXID_ONLY, known_txid: txid)
+      end
+
+      # --- Validation ---
+
+      # Check structural validity of the BEEF bundle.
+      #
+      # A valid BEEF has every transaction either:
+      # - proven (has a BUMP / merkle_path), or
+      # - all its inputs reference transactions that are themselves valid
+      #   within this bundle.
+      #
+      # @param allow_txid_only [Boolean] whether TXID-only entries count as valid (default: false)
+      # @return [Boolean] true if structurally valid
+      def valid?(allow_txid_only: false)
+        known_txids = build_known_txids(allow_txid_only)
+
+        # TXID-only entries are invalid unless explicitly allowed
+        has_txid_only = @transactions.any? { |bt| bt.format == FORMAT_TXID_ONLY }
+        return false if has_txid_only && !allow_txid_only
+
+        pending = @transactions.select { |bt| bt.transaction && !known_txids.include?(bt.txid) }
+
+        # Iteratively resolve: if all inputs of a tx are known, it becomes known
+        changed = true
+        while changed
+          changed = false
+          pending.reject! do |bt|
+            all_inputs_known = bt.transaction.inputs.all? do |input|
+              known_txids.include?(input.prev_tx_id.reverse)
+            end
+            if all_inputs_known
+              known_txids.add(bt.txid)
+              changed = true
+            end
+            all_inputs_known
+          end
+        end
+
+        pending.empty?
+      end
+
+      # Sort transactions in topological (dependency) order in place.
+      #
+      # After sorting, every transaction's input ancestors appear before it
+      # in the array. This is required for correct BEEF serialisation.
+      #
+      # @return [self]
+      def sort_transactions!
+        return self if @transactions.length <= 1
+
+        txid_index = {}
+        @transactions.each_with_index { |bt, i| txid_index[bt.txid] = i }
+
+        # Build adjacency: for each tx, which other txs must come before it?
+        in_degree = Array.new(@transactions.length, 0)
+        dependents = Array.new(@transactions.length) { [] }
+
+        @transactions.each_with_index do |bt, i|
+          next unless bt.transaction
+
+          bt.transaction.inputs.each do |input|
+            dep_idx = txid_index[input.prev_tx_id.reverse]
+            next unless dep_idx
+
+            dependents[dep_idx] << i
+            in_degree[i] += 1
+          end
+        end
+
+        # Kahn's algorithm
+        queue = (0...@transactions.length).select { |i| in_degree[i].zero? }
+        sorted = []
+
+        until queue.empty?
+          idx = queue.shift
+          sorted << @transactions[idx]
+          dependents[idx].each do |dep|
+            in_degree[dep] -= 1
+            queue << dep if in_degree[dep].zero?
+          end
+        end
+
+        @transactions = sorted
+        self
+      end
+
       # --- Private class methods for deserialisation ---
 
       class << self
@@ -303,6 +569,42 @@ module BSV
 
       private
 
+      # Build a set of txids that are "known" (proven or txid-only).
+      def build_known_txids(allow_txid_only)
+        known = Set.new
+        @transactions.each do |bt|
+          case bt.format
+          when FORMAT_RAW_TX_AND_BUMP
+            known.add(bt.txid)
+          when FORMAT_TXID_ONLY
+            known.add(bt.txid) if allow_txid_only
+          end
+        end
+        known
+      end
+
+      # Wire source_transaction references on a transaction's inputs.
+      def wire_inputs(tx)
+        tx.inputs.each do |input|
+          next if input.source_transaction
+
+          source = find_transaction(input.prev_tx_id.reverse)
+          input.source_transaction = source if source
+        end
+      end
+
+      # Recursively wire source_transactions and merkle_paths.
+      def wire_ancestry(tx)
+        wire_inputs(tx)
+        tx.inputs.each do |input|
+          next unless input.source_transaction
+
+          source = input.source_transaction
+          source.merkle_path ||= find_bump(source.txid)
+          wire_ancestry(source)
+        end
+      end
+
       def build_bump_map
         map = {}.compare_by_identity
         idx = 0

data/lib/bsv/transaction/chain_tracker.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    # Base class for chain trackers that verify merkle roots against the blockchain.
+    #
+    # Chain trackers confirm that a given merkle root corresponds to a valid block
+    # at a specific height. This is essential for SPV verification — without it,
+    # merkle proofs cannot be validated against the actual blockchain.
+    #
+    # Subclasses must implement {#valid_root_for_height?} and {#current_height}.
+    #
+    # @example Implementing a custom chain tracker
+    #   class MyTracker < BSV::Transaction::ChainTracker
+    #     def valid_root_for_height?(root, height)
+    #       # query your block header source
+    #     end
+    #
+    #     def current_height
+    #       # return current chain tip height
+    #     end
+    #   end
+    class ChainTracker
+      # Verify that a merkle root is valid for the given block height.
+      #
+      # @param root [String] merkle root as a hex string
+      # @param height [Integer] block height
+      # @return [Boolean] true if the root matches the block at the given height
+      # @raise [NotImplementedError] if not overridden by a subclass
+      def valid_root_for_height?(_root, _height)
+        raise NotImplementedError, "#{self.class}#valid_root_for_height? must be implemented"
+      end
+
+      # Return the current blockchain height.
+      #
+      # @return [Integer] the height of the chain tip
+      # @raise [NotImplementedError] if not overridden by a subclass
+      def current_height
+        raise NotImplementedError, "#{self.class}#current_height must be implemented"
+      end
+    end
+  end
+end

data/lib/bsv/transaction/chain_trackers/whats_on_chain.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module BSV
+  module Transaction
+    module ChainTrackers
+      # Chain tracker that verifies merkle roots using the WhatsOnChain API.
+      #
+      # Queries the WoC block header endpoint to retrieve the merkle root for a
+      # given block height and compares it with the provided root.
+      #
+      # @example
+      #   tracker = BSV::Transaction::ChainTrackers::WhatsOnChain.new
+      #   tracker.valid_root_for_height?('abcd...', 800_000)
+      class WhatsOnChain < ChainTracker
+        BASE_URL = 'https://api.whatsonchain.com'
+
+        NETWORKS = {
+          main: 'main',
+          mainnet: 'main',
+          test: 'test',
+          testnet: 'test',
+          stn: 'stn'
+        }.freeze
+
+        # @param network [Symbol] :main, :mainnet, :test, :testnet, or :stn
+        # @param api_key [String, nil] optional WoC API key
+        # @param http_client [#request, nil] injectable HTTP client for testing
+        def initialize(network: :main, api_key: nil, http_client: nil)
+          super()
+          @network = NETWORKS.fetch(network) { raise ArgumentError, "unknown network: #{network}" }
+          @api_key = api_key
+          @http_client = http_client
+        end
+
+        # Verify that a merkle root is valid for the given block height.
+        #
+        # @param root [String] merkle root as a hex string
+        # @param height [Integer] block height
+        # @return [Boolean]
+        def valid_root_for_height?(root, height)
+          response = get("/v1/bsv/#{@network}/block/#{height}/header")
+          return false if response.nil?
+
+          data = JSON.parse(response.body)
+          data['merkleroot'].downcase == root.downcase
+        end
+
+        # Return the current blockchain height.
+        #
+        # @return [Integer]
+        def current_height
+          response = get("/v1/bsv/#{@network}/chain/info", not_found_returns_nil: false)
+          data = JSON.parse(response.body)
+          data['blocks']
+        end
+
+        private
+
+        # @param path [String] API path
+        # @param not_found_returns_nil [Boolean] if true, return nil on 404 instead of raising
+        # @return [Net::HTTPResponse, nil]
+        def get(path, not_found_returns_nil: true)
+          uri = URI("#{BASE_URL}#{path}")
+          request = Net::HTTP::Get.new(uri)
+          request['Authorization'] = @api_key if @api_key
+
+          response = execute(uri, request)
+          code = response.code.to_i
+
+          return nil if not_found_returns_nil && code == 404
+          return response if (200..299).cover?(code)
+
+          raise BSV::Network::ChainProviderError.new(
+            response.body || "HTTP #{code}",
+            status_code: code
+          )
+        end
+
+        def execute(uri, request)
+          if @http_client
+            @http_client.request(uri, request)
+          else
+            Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+              http.request(request)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/transaction/chain_trackers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    # Namespace for chain tracker implementations.
+    module ChainTrackers
+      autoload :WhatsOnChain, 'bsv/transaction/chain_trackers/whats_on_chain'
+    end
+  end
+end

data/lib/bsv/transaction/fee_model.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    # Base class for fee models that compute transaction fees.
+    #
+    # Fee models determine how many satoshis a transaction should pay in fees
+    # based on its size or other properties. Subclasses must implement
+    # {#compute_fee}.
+    #
+    # @example Implementing a custom fee model
+    #   class FixedFee < BSV::Transaction::FeeModel
+    #     def compute_fee(_transaction)
+    #       1000
+    #     end
+    #   end
+    class FeeModel
+      # Compute the fee for a transaction.
+      #
+      # @param transaction [Transaction] the transaction to compute the fee for
+      # @return [Integer] the fee in satoshis
+      # @raise [NotImplementedError] if not overridden by a subclass
+      def compute_fee(_transaction)
+        raise NotImplementedError, "#{self.class}#compute_fee must be implemented"
+      end
+    end
+  end
+end

data/lib/bsv/transaction/fee_models/satoshis_per_kilobyte.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    module FeeModels
+      # Fee model that charges a configurable number of satoshis per kilobyte.
+      #
+      # Uses the transaction's estimated size (from templates for unsigned inputs,
+      # actual size for signed inputs) to compute the fee.
+      #
+      # @example
+      #   model = BSV::Transaction::FeeModels::SatoshisPerKilobyte.new(value: 100)
+      #   fee = model.compute_fee(transaction) # => 25 (for a ~250 byte tx)
+      class SatoshisPerKilobyte < FeeModel
+        # @return [Integer] satoshis per kilobyte rate
+        attr_reader :value
+
+        # @param value [Integer] satoshis per kilobyte (default: 50)
+        def initialize(value: 50)
+          super()
+          @value = value
+        end
+
+        # Compute the fee for a transaction based on its estimated size.
+        #
+        # @param transaction [Transaction] the transaction to compute the fee for
+        # @return [Integer] the fee in satoshis
+        def compute_fee(transaction)
+          size = transaction.estimated_size
+          (size / 1000.0 * @value).ceil
+        end
+      end
+    end
+  end
+end

data/lib/bsv/transaction/fee_models.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    # Namespace for fee model implementations.
+    module FeeModels
+      autoload :SatoshisPerKilobyte, 'bsv/transaction/fee_models/satoshis_per_kilobyte'
+    end
+  end
+end

data/lib/bsv/transaction/merkle_path.rb

@@ -186,6 +186,21 @@ module BSV
         compute_root(txid).reverse.unpack1('H*')
       end
 
+      # --- Verification ---
+
+      # Verify that this merkle path is valid for a given transaction.
+      #
+      # Computes the merkle root from the path and txid, then checks it
+      # against the blockchain via the provided chain tracker.
+      #
+      # @param txid_hex [String] hex-encoded transaction ID (display order)
+      # @param chain_tracker [ChainTracker] chain tracker to verify the root against
+      # @return [Boolean] true if the computed root matches the block at this height
+      def verify(txid_hex, chain_tracker)
+        root_hex = compute_root_hex(txid_hex)
+        chain_tracker.valid_root_for_height?(root_hex, @block_height)
+      end
+
       # --- Combine ---
 
       # Merge another merkle path into this one.
@@ -208,7 +223,7 @@ module BSV
           @path << [] if h >= @path.length
           next if h >= other.path.length
 
-          existing = @path[h].each_with_object({}) { |e, m| m[e.offset] = e }
+          existing = @path[h].to_h { |e| [e.offset, e] }
           other.path[h].each do |elem|
             existing[elem.offset] ||= elem
           end
@@ -222,7 +237,7 @@ module BSV
 
       def build_indexed_path
         @path.map do |level|
-          level.each_with_object({}) { |elem, h| h[elem.offset] = elem }
+          level.to_h { |elem| [elem.offset, elem] }
         end
       end