bsv-sdk 0.1.0 → 0.2.0

data/lib/bsv/transaction/transaction.rb

@@ -84,11 +84,47 @@ module BSV
         to_binary.unpack1('H*')
       end
 
+      # Serialise the transaction in Extended Format (BRC-30).
+      #
+      # EF embeds source satoshis and source locking scripts in each input,
+      # allowing ARC to validate sighashes without fetching parent transactions.
+      #
+      # @return [String] raw EF transaction bytes
+      # @raise [ArgumentError] if any input is missing source_satoshis or source_locking_script
+      def to_ef
+        buf = [@version].pack('V')
+        buf << "\x00\x00\x00\x00\x00\xEF".b
+        buf << VarInt.encode(@inputs.length)
+        @inputs.each do |input|
+          raise ArgumentError, 'inputs must have source_satoshis for EF' if input.source_satoshis.nil?
+          raise ArgumentError, 'inputs must have source_locking_script for EF' if input.source_locking_script.nil?
+
+          buf << input.to_binary
+          buf << [input.source_satoshis].pack('Q<')
+          lock_bytes = input.source_locking_script.to_binary
+          buf << VarInt.encode(lock_bytes.bytesize)
+          buf << lock_bytes
+        end
+        buf << VarInt.encode(@outputs.length)
+        @outputs.each { |o| buf << o.to_binary }
+        buf << [@lock_time].pack('V')
+        buf
+      end
+
+      # Serialise the transaction in Extended Format as a hex string.
+      #
+      # @return [String] hex-encoded EF transaction
+      def to_ef_hex
+        to_ef.unpack1('H*')
+      end
+
       # Deserialise a transaction from binary data.
       #
       # @param data [String] raw binary transaction
       # @return [Transaction] the parsed transaction
       def self.from_binary(data)
+        raise ArgumentError, "truncated transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
+
         offset = 0
 
         version = data.byteslice(offset, 4).unpack1('V')
@@ -112,6 +148,11 @@ module BSV
           offset += consumed
         end
 
+        if data.bytesize < offset + 4
+          raise ArgumentError,
+                "truncated transaction: need 4 bytes for lock_time at offset #{offset}, got #{data.bytesize - offset}"
+        end
+
         tx.instance_variable_set(:@lock_time, data.byteslice(offset, 4).unpack1('V'))
         tx
       end
@@ -124,6 +165,79 @@ module BSV
         from_binary([hex].pack('H*'))
       end
 
+      # Deserialise a transaction from Extended Format (BRC-30) binary data.
+      #
+      # @param data [String] raw EF binary
+      # @return [Transaction] the parsed transaction with source data on inputs
+      # @raise [ArgumentError] if the EF marker is invalid
+      def self.from_ef(data)
+        if data.bytesize < 10
+          raise ArgumentError,
+                "truncated EF transaction: need at least 10 bytes, got #{data.bytesize}"
+        end
+
+        offset = 0
+
+        version = data.byteslice(offset, 4).unpack1('V')
+        offset += 4
+
+        marker = data.byteslice(offset, 6)
+        raise ArgumentError, 'invalid EF marker' unless marker == "\x00\x00\x00\x00\x00\xEF".b
+
+        offset += 6
+
+        tx = new(version: version)
+
+        input_count, vi_size = VarInt.decode(data, offset)
+        offset += vi_size
+        input_count.times do
+          input, consumed = TransactionInput.from_binary(data, offset)
+          tx.add_input(input)
+          offset += consumed
+
+          if data.bytesize < offset + 8
+            remaining = data.bytesize - offset
+            raise ArgumentError,
+                  "truncated EF input: need 8 bytes for source_satoshis at offset #{offset}, got #{remaining}"
+          end
+
+          input.source_satoshis = data.byteslice(offset, 8).unpack1('Q<')
+          offset += 8
+
+          lock_len, vi_size = VarInt.decode(data, offset)
+          offset += vi_size
+          if lock_len.positive?
+            input.source_locking_script = BSV::Script::Script.from_binary(data.byteslice(offset, lock_len))
+            offset += lock_len
+          end
+        end
+
+        output_count, vi_size = VarInt.decode(data, offset)
+        offset += vi_size
+        output_count.times do
+          output, consumed = TransactionOutput.from_binary(data, offset)
+          tx.add_output(output)
+          offset += consumed
+        end
+
+        if data.bytesize < offset + 4
+          remaining = data.bytesize - offset
+          raise ArgumentError,
+                "truncated EF transaction: need 4 bytes for lock_time at offset #{offset}, got #{remaining}"
+        end
+
+        tx.instance_variable_set(:@lock_time, data.byteslice(offset, 4).unpack1('V'))
+        tx
+      end
+
+      # Deserialise a transaction from an Extended Format hex string.
+      #
+      # @param hex [String] hex-encoded EF transaction
+      # @return [Transaction] the parsed transaction with source data on inputs
+      def self.from_ef_hex(hex)
+        from_ef([hex].pack('H*'))
+      end
+
       # Deserialise a transaction from binary data at a given offset,
       # returning the transaction and the number of bytes consumed.
       #
@@ -131,6 +245,11 @@ module BSV
       # @param offset [Integer] byte offset to start reading from
       # @return [Array(Transaction, Integer)] the transaction and bytes consumed
       def self.from_binary_with_offset(data, offset = 0)
+        if data.bytesize < offset + 10
+          raise ArgumentError,
+                "truncated transaction: need at least 10 bytes at offset #{offset}, got #{data.bytesize - offset}"
+        end
+
         start = offset
 
         version = data.byteslice(offset, 4).unpack1('V')
@@ -154,12 +273,87 @@ module BSV
           offset += consumed
         end
 
+        if data.bytesize < offset + 4
+          raise ArgumentError,
+                "truncated transaction: need 4 bytes for lock_time at offset #{offset}, got #{data.bytesize - offset}"
+        end
+
         tx.instance_variable_set(:@lock_time, data.byteslice(offset, 4).unpack1('V'))
         offset += 4
 
         [tx, offset - start]
       end
 
+      # --- BEEF convenience methods ---
+
+      # Serialise this transaction (with its ancestry chain and merkle proofs)
+      # into a BEEF V2 binary bundle.
+      #
+      # Walks the `source_transaction` references on inputs to collect ancestors.
+      # Transactions with a `merkle_path` are treated as proven leaves — their
+      # ancestors are not traversed further.
+      #
+      # @return [String] raw BEEF V2 binary
+      def to_beef
+        beef = Beef.new
+        bump_map = {}
+        ancestors = collect_ancestors
+
+        ancestors.each do |tx|
+          # Collect BUMPs
+          if tx.merkle_path
+            height = tx.merkle_path.block_height
+            unless bump_map.key?(height)
+              bump_map[height] = beef.bumps.length
+              beef.bumps << tx.merkle_path
+            end
+          end
+
+          # Add transaction in dependency order
+          entry = if tx.merkle_path
+                    Beef::BeefTx.new(
+                      format: Beef::FORMAT_RAW_TX_AND_BUMP,
+                      transaction: tx,
+                      bump_index: bump_map[tx.merkle_path.block_height]
+                    )
+                  else
+                    Beef::BeefTx.new(
+                      format: Beef::FORMAT_RAW_TX,
+                      transaction: tx
+                    )
+                  end
+          beef.transactions << entry
+        end
+
+        beef.to_binary
+      end
+
+      # Serialise this transaction to a BEEF V2 hex string.
+      #
+      # @return [String] hex-encoded BEEF
+      def to_beef_hex
+        to_beef.unpack1('H*')
+      end
+
+      # Parse a BEEF binary bundle and return the subject transaction
+      # (the last transaction in the bundle).
+      #
+      # @param data [String] raw BEEF binary
+      # @return [Transaction] the subject transaction with ancestry wired
+      def self.from_beef(data)
+        beef = Beef.from_binary(data)
+        last_tx_entry = beef.transactions.reverse.find(&:transaction)
+        last_tx_entry&.transaction
+      end
+
+      # Parse a BEEF hex string and return the subject transaction.
+      #
+      # @param hex [String] hex-encoded BEEF
+      # @return [Transaction] the subject transaction with ancestry wired
+      def self.from_beef_hex(hex)
+        from_beef([hex].pack('H*'))
+      end
+
       # --- Transaction ID ---
 
       # Compute the transaction ID (double-SHA-256 of the serialised tx, reversed).
@@ -299,13 +493,82 @@ module BSV
         )
       end
 
+      # --- SPV verification ---
+
+      # Perform full SPV verification of this transaction and its ancestry.
+      #
+      # Uses a queue-based approach (matching TS/Go SDKs) to walk the
+      # transaction ancestry chain:
+      #
+      # 1. If a transaction has a merkle path that validates against the chain
+      #    tracker, it is marked verified (inputs are not re-checked).
+      # 2. Otherwise, each input's scripts are executed via the interpreter,
+      #    and source transactions are enqueued for verification.
+      # 3. Optionally validates that the root transaction's fee meets the
+      #    provided fee model.
+      # 4. Checks that total outputs do not exceed total inputs.
+      #
+      # @param chain_tracker [ChainTracker] chain tracker for merkle root validation
+      # @param fee_model [FeeModel, nil] optional fee model to validate the root transaction's fee
+      # @return [true] on successful verification
+      # @raise [ArgumentError] if a source transaction or unlocking script is missing
+      # @raise [BSV::Script::ScriptError] if script execution fails
+      # @raise [VerificationError] for merkle path failures, fee validation, or output overflow
+      def verify(chain_tracker:, fee_model: nil)
+        verified = {}
+        queue = [self]
+
+        until queue.empty?
+          tx = queue.shift
+          tx_id = tx.txid_hex
+          next if verified[tx_id]
+
+          # Merkle path short-circuit: proven transaction needs no input verification
+          if tx.merkle_path
+            unless tx.merkle_path.verify(tx_id, chain_tracker)
+              raise VerificationError.new(:invalid_merkle_proof,
+                                          "invalid merkle proof for transaction #{tx_id}")
+            end
+
+            verified[tx_id] = true
+            next
+          end
+
+          # Fee validation (root transaction only)
+          verify_fee(fee_model) if tx.equal?(self) && fee_model
+
+          # Verify each input
+          tx.inputs.each_with_index do |input, index|
+            verify_input_requirements(tx, input, index)
+            tx.verify_input(index)
+
+            # Enqueue source transaction for verification if not yet verified
+            source_tx = input.source_transaction
+            queue << source_tx if source_tx && !verified[source_tx.txid_hex]
+          end
+
+          # Output ≤ input check
+          verify_output_constraint(tx)
+
+          verified[tx_id] = true
+        end
+
+        true
+      end
+
       # --- Fee estimation ---
 
       # Sum of all input source satoshi values.
       #
       # @return [Integer] total input value in satoshis
       def total_input_satoshis
-        @inputs.sum { |i| i.source_satoshis || 0 }
+        @inputs.each_with_index do |input, idx|
+          if input.source_satoshis.nil?
+            raise ArgumentError,
+                  "input #{idx} has nil source_satoshis — set it before computing totals"
+          end
+        end
+        @inputs.sum(&:source_satoshis)
       end
 
       # Sum of all output satoshi values.
@@ -324,8 +587,86 @@ module BSV
         (size * satoshis_per_byte).ceil
       end
 
+      # Estimate the serialised transaction size in bytes.
+      #
+      # Uses actual unlocking script size for signed inputs and template
+      # estimated length for unsigned inputs.
+      #
+      # @return [Integer] estimated size in bytes
+      def estimated_size
+        size = 4 # version
+        size += VarInt.encode(@inputs.length).bytesize
+        @inputs.each_with_index do |input, index|
+          size += if input.unlocking_script
+                    input.to_binary.bytesize
+                  elsif input.unlocking_script_template
+                    script_len = input.unlocking_script_template.estimated_length(self, index)
+                    32 + 4 + VarInt.encode(script_len).bytesize + script_len + 4
+                  else
+                    UNSIGNED_P2PKH_INPUT_SIZE
+                  end
+        end
+        size += VarInt.encode(@outputs.length).bytesize
+        @outputs.each { |o| size += o.to_binary.bytesize }
+        size += 4 # lock_time
+        size
+      end
+
+      # Compute the fee and distribute change across change outputs.
+      #
+      # Accepts a {FeeModel} instance, a numeric fee in satoshis, or nil
+      # (defaults to {FeeModels::SatoshisPerKilobyte} at 50 sat/kB).
+      #
+      # After computing the fee, distributes remaining satoshis equally
+      # across outputs marked as change. If insufficient change, removes
+      # all change outputs (excess goes to miners).
+      #
+      # @param model_or_fee [FeeModel, Integer, nil] fee model, fixed fee, or nil for default
+      # @return [self] for chaining
+      def fee(model_or_fee = nil)
+        fee_sats = compute_fee_sats(model_or_fee)
+        distribute_change(fee_sats)
+        self
+      end
+
       private
 
+      def verify_input_requirements(tx, input, index)
+        tx_id = tx.txid_hex
+        if input.unlocking_script.nil?
+          raise ArgumentError,
+                "input #{index} of transaction #{tx_id} has no unlocking script"
+        end
+        if input.source_locking_script.nil?
+          raise ArgumentError,
+                "input #{index} of transaction #{tx_id} has no source locking script"
+        end
+        return unless input.source_satoshis.nil?
+
+        raise ArgumentError,
+              "input #{index} of transaction #{tx_id} has no source satoshis"
+      end
+
+      def verify_fee(fee_model)
+        required_fee = fee_model.compute_fee(self)
+        actual_fee = total_input_satoshis - total_output_satoshis
+        return if actual_fee >= required_fee
+
+        raise VerificationError.new(:insufficient_fee,
+                                    "insufficient fee: transaction pays #{actual_fee} sat " \
+                                    "but fee model requires #{required_fee} sat")
+      end
+
+      def verify_output_constraint(tx)
+        input_total = tx.total_input_satoshis
+        output_total = tx.total_output_satoshis
+        return if output_total <= input_total
+
+        raise VerificationError.new(:output_overflow,
+                                    "outputs (#{output_total}) exceed inputs (#{input_total}) " \
+                                    "for transaction #{tx.txid_hex}")
+      end
+
       ZERO_HASH = "\x00".b * 32
       private_constant :ZERO_HASH
 
@@ -357,23 +698,62 @@ module BSV
         end
       end
 
-      def estimated_size
-        size = 4 # version
-        size += VarInt.encode(@inputs.length).bytesize
-        @inputs.each_with_index do |input, index|
-          size += if input.unlocking_script
-                    input.to_binary.bytesize
-                  elsif input.unlocking_script_template
-                    script_len = input.unlocking_script_template.estimated_length(self, index)
-                    32 + 4 + VarInt.encode(script_len).bytesize + script_len + 4
-                  else
-                    UNSIGNED_P2PKH_INPUT_SIZE
-                  end
+      # Collect this transaction and all its ancestors in dependency order
+      # (ancestors first, self last). Stops recursion at transactions with
+      # a merkle_path (proven leaves). Deduplicates by txid.
+      def collect_ancestors
+        seen = {}
+        result = []
+        collect_ancestors_recursive(self, seen, result)
+        result
+      end
+
+      def collect_ancestors_recursive(tx, seen, result)
+        txid = tx.txid
+        return if seen.key?(txid)
+
+        unless tx.merkle_path
+          tx.inputs.each do |input|
+            next unless input.source_transaction
+
+            collect_ancestors_recursive(input.source_transaction, seen, result)
+          end
+        end
+
+        seen[txid] = true
+        result << tx
+      end
+
+      def compute_fee_sats(model_or_fee)
+        case model_or_fee
+        when nil
+          FeeModels::SatoshisPerKilobyte.new.compute_fee(self)
+        when FeeModel
+          model_or_fee.compute_fee(self)
+        when Numeric
+          model_or_fee.ceil
+        else
+          raise ArgumentError, "expected FeeModel, Numeric, or nil; got #{model_or_fee.class}"
+        end
+      end
+
+      def distribute_change(fee_sats)
+        change_outputs = @outputs.select(&:change)
+        return if change_outputs.empty?
+
+        input_sats = total_input_satoshis
+        non_change_sats = @outputs.reject(&:change).sum(&:satoshis)
+        available = input_sats - non_change_sats - fee_sats
+
+        if available <= change_outputs.length
+          @outputs.reject!(&:change)
+        else
+          per_output = available / change_outputs.length
+          remainder = available % change_outputs.length
+          change_outputs.each_with_index do |output, i|
+            output.satoshis = per_output + (i < remainder ? 1 : 0)
+          end
         end
-        size += VarInt.encode(@outputs.length).bytesize
-        @outputs.each { |o| size += o.to_binary.bytesize }
-        size += 4 # lock_time
-        size
       end
     end
   end

data/lib/bsv/transaction/transaction_input.rb

@@ -61,6 +61,11 @@ module BSV
       # @param offset [Integer] byte offset to start reading from
       # @return [Array(TransactionInput, Integer)] the input and bytes consumed
       def self.from_binary(data, offset = 0)
+        if data.bytesize < offset + 36
+          raise ArgumentError,
+                "truncated input: need 36 bytes for outpoint at offset #{offset}, got #{data.bytesize - offset}"
+        end
+
         prev_tx_id = data.byteslice(offset, 32)
         prev_tx_out_index = data.byteslice(offset + 32, 4).unpack1('V')
         offset += 36
@@ -68,9 +73,20 @@ module BSV
         script_len, vi_size = VarInt.decode(data, offset)
         offset += vi_size
 
+        if data.bytesize < offset + script_len
+          remaining = data.bytesize - offset
+          raise ArgumentError,
+                "truncated input: need #{script_len} bytes for script at offset #{offset}, got #{remaining}"
+        end
+
         unlocking_script = (BSV::Script::Script.from_binary(data.byteslice(offset, script_len)) if script_len.positive?)
         offset += script_len
 
+        if data.bytesize < offset + 4
+          raise ArgumentError,
+                "truncated input: need 4 bytes for sequence at offset #{offset}, got #{data.bytesize - offset}"
+        end
+
         sequence = data.byteslice(offset, 4).unpack1('V')
 
         total = 36 + vi_size + script_len + 4

data/lib/bsv/transaction/transaction_output.rb

@@ -9,16 +9,21 @@ module BSV
     # unlocking scripts.
     class TransactionOutput
       # @return [Integer] the output value in satoshis
-      attr_reader :satoshis
+      attr_accessor :satoshis
 
       # @return [Script::Script] the locking script (spending conditions)
       attr_reader :locking_script
 
+      # @return [Boolean] whether this output receives change
+      attr_accessor :change
+
       # @param satoshis [Integer] output value in satoshis
       # @param locking_script [Script::Script] the locking script
-      def initialize(satoshis:, locking_script:)
+      # @param change [Boolean] whether this is a change output (default: false)
+      def initialize(satoshis:, locking_script:, change: false)
         @satoshis = satoshis
         @locking_script = locking_script
+        @change = change
       end
 
       # Serialise the output to its binary wire format.
@@ -35,12 +40,23 @@ module BSV
       # @param offset [Integer] byte offset to start reading from
       # @return [Array(TransactionOutput, Integer)] the output and bytes consumed
       def self.from_binary(data, offset = 0)
+        if data.bytesize < offset + 8
+          raise ArgumentError,
+                "truncated output: need 8 bytes for satoshis at offset #{offset}, got #{data.bytesize - offset}"
+        end
+
         satoshis = data.byteslice(offset, 8).unpack1('Q<')
         offset += 8
 
         script_len, vi_size = VarInt.decode(data, offset)
         offset += vi_size
 
+        if data.bytesize < offset + script_len
+          remaining = data.bytesize - offset
+          raise ArgumentError,
+                "truncated output: need #{script_len} bytes for script at offset #{offset}, got #{remaining}"
+        end
+
         script_bytes = data.byteslice(offset, script_len)
         locking_script = BSV::Script::Script.from_binary(script_bytes)
 

data/lib/bsv/transaction/var_int.rb

@@ -32,16 +32,36 @@ module BSV
       # @param offset [Integer] byte offset to start reading from
       # @return [Array(Integer, Integer)] the decoded value and number of bytes consumed
       def decode(data, offset = 0)
+        if offset >= data.bytesize
+          raise ArgumentError,
+                "truncated varint: need 1 byte at offset #{offset}, got end of data"
+        end
+
         first = data.getbyte(offset)
 
         case first
         when 0..0xFC
           [first, 1]
         when 0xFD
+          if data.bytesize < offset + 3
+            raise ArgumentError,
+                  "truncated varint: need 3 bytes at offset #{offset}, got #{data.bytesize - offset}"
+          end
+
           [data.byteslice(offset + 1, 2).unpack1('v'), 3]
         when 0xFE
+          if data.bytesize < offset + 5
+            raise ArgumentError,
+                  "truncated varint: need 5 bytes at offset #{offset}, got #{data.bytesize - offset}"
+          end
+
           [data.byteslice(offset + 1, 4).unpack1('V'), 5]
         when 0xFF
+          if data.bytesize < offset + 9
+            raise ArgumentError,
+                  "truncated varint: need 9 bytes at offset #{offset}, got #{data.bytesize - offset}"
+          end
+
           [data.byteslice(offset + 1, 8).unpack1('Q<'), 9]
         end
       end

data/lib/bsv/transaction/verification_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module BSV
+  module Transaction
+    # Error raised during SPV verification.
+    #
+    # Carries a machine-readable code alongside a human-readable message,
+    # matching the typed error pattern used by the Go SDK
+    # (ErrInvalidMerklePath, ErrFeeTooLow, ErrScriptVerificationFailed).
+    class VerificationError < StandardError
+      # @return [Symbol] the error code
+      attr_reader :code
+
+      INVALID_MERKLE_PROOF = :invalid_merkle_proof
+      INSUFFICIENT_FEE = :insufficient_fee
+      OUTPUT_OVERFLOW = :output_overflow
+
+      # @param code [Symbol] error code
+      # @param message [String] human-readable description
+      def initialize(code, message)
+        @code = code
+        super(message)
+      end
+    end
+  end
+end

data/lib/bsv/transaction.rb

@@ -13,6 +13,11 @@ module BSV
     autoload :TransactionInput,  'bsv/transaction/transaction_input'
     autoload :Sighash,           'bsv/transaction/sighash'
     autoload :MerklePath,        'bsv/transaction/merkle_path'
+    autoload :FeeModel,                  'bsv/transaction/fee_model'
+    autoload :FeeModels,                 'bsv/transaction/fee_models'
+    autoload :VerificationError, 'bsv/transaction/verification_error'
+    autoload :ChainTracker,              'bsv/transaction/chain_tracker'
+    autoload :ChainTrackers,             'bsv/transaction/chain_trackers'
     autoload :Beef,                      'bsv/transaction/beef'
     autoload :UnlockingScriptTemplate,   'bsv/transaction/unlocking_script_template'
     autoload :P2PKH,                     'bsv/transaction/p2pkh'

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-02-14 00:00:00.000000000 Z
+date: 2026-03-07 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby library for interacting with the BSV Blockchain — keys, scripts,
   transactions, and more.
@@ -64,6 +64,12 @@ files:
 - lib/bsv/script/script.rb
 - lib/bsv/transaction.rb
 - lib/bsv/transaction/beef.rb
+- lib/bsv/transaction/chain_tracker.rb
+- lib/bsv/transaction/chain_trackers.rb
+- lib/bsv/transaction/chain_trackers/whats_on_chain.rb
+- lib/bsv/transaction/fee_model.rb
+- lib/bsv/transaction/fee_models.rb
+- lib/bsv/transaction/fee_models/satoshis_per_kilobyte.rb
 - lib/bsv/transaction/merkle_path.rb
 - lib/bsv/transaction/p2pkh.rb
 - lib/bsv/transaction/sighash.rb
@@ -72,6 +78,7 @@ files:
 - lib/bsv/transaction/transaction_output.rb
 - lib/bsv/transaction/unlocking_script_template.rb
 - lib/bsv/transaction/var_int.rb
+- lib/bsv/transaction/verification_error.rb
 - lib/bsv/version.rb
 - lib/bsv/wallet.rb
 - lib/bsv/wallet/insufficient_funds_error.rb