bsv-sdk 0.2.1 → 0.3.1

data/lib/bsv/transaction/transaction.rb

@@ -19,6 +19,19 @@ module BSV
       # Estimated size of an unsigned P2PKH input in bytes.
       UNSIGNED_P2PKH_INPUT_SIZE = 148
 
+      # Lookup table for benford_number calculation.
+      # we want float values for log10(1 + (1.0 / i)) for the 9 integers 0 < i < 10
+      # in ruby this becomes: (1..9).to_a.collect{|d| Math.log10(1 + (1.0 / d)) }
+      LOG10_RECIPROCAL_D_VALUES_1TO9 = [0.3010299956639812,
+                                        0.17609125905568124,
+                                        0.12493873660829993,
+                                        0.09691001300805642,
+                                        0.07918124604762482,
+                                        0.06694678963061322,
+                                        0.05799194697768673,
+                                        0.05115252244738129,
+                                        0.04575749056067514].freeze
+
       # @return [Integer] transaction version number
       attr_reader :version
 
@@ -149,8 +162,7 @@ module BSV
         end
 
         if data.bytesize < offset + 4
-          raise ArgumentError,
-                "truncated transaction: need 4 bytes for lock_time at offset #{offset}, got #{data.bytesize - offset}"
+          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'))
@@ -171,10 +183,7 @@ module BSV
       # @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
+        raise ArgumentError, "truncated EF transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
 
         offset = 0
 
@@ -197,8 +206,7 @@ module BSV
 
           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}"
+            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<')
@@ -222,8 +230,7 @@ module BSV
 
         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}"
+          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'))
@@ -246,8 +253,7 @@ module BSV
       # @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}"
+          raise ArgumentError, "truncated transaction: need at least 10 bytes at offset #{offset}, got #{data.bytesize - offset}"
         end
 
         start = offset
@@ -274,8 +280,7 @@ module BSV
         end
 
         if data.bytesize < offset + 4
-          raise ArgumentError,
-                "truncated transaction: need 4 bytes for lock_time at offset #{offset}, got #{data.bytesize - offset}"
+          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'))
@@ -557,10 +562,7 @@ module BSV
       # @return [Integer] total input value in satoshis
       def total_input_satoshis
         @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
+          raise ArgumentError, "input #{idx} has nil source_satoshis — set it before computing totals" if input.source_satoshis.nil?
         end
         @inputs.sum(&:source_satoshis)
       end
@@ -611,15 +613,29 @@ module BSV
       # 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).
+      # After computing the fee, distributes remaining satoshis across outputs
+      # marked as change. The distribution strategy is controlled by the
+      # +change_distribution:+ keyword argument:
+      #
+      # - +:equal+ (default) — divides change equally across all change outputs,
+      #   matching TS SDK default behaviour.
+      # - +:random+ — Benford-inspired distribution that biases amounts towards
+      #   the lower end of the available range, improving privacy by producing
+      #   varied change amounts.
+      #
+      # If insufficient change remains, all change outputs are removed.
       #
       # @param model_or_fee [FeeModel, Integer, nil] fee model, fixed fee, or nil for default
+      # @param change_distribution [Symbol] +:equal+ or +:random+ (default: +:equal+)
       # @return [self] for chaining
-      def fee(model_or_fee = nil)
+      # @raise [ArgumentError] if +change_distribution+ is not +:random+ or +:equal+
+      def fee(model_or_fee = nil, change_distribution: :equal)
+        unless %i[random equal].include?(change_distribution)
+          raise ArgumentError, "invalid change_distribution #{change_distribution.inspect}; expected :random or :equal"
+        end
+
         fee_sats = compute_fee_sats(model_or_fee)
-        distribute_change(fee_sats)
+        distribute_change(fee_sats, change_distribution)
         self
       end
 
@@ -627,18 +643,9 @@ module BSV
 
       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"
+        raise ArgumentError, "input #{index} of transaction #{tx_id} has no unlocking script" if input.unlocking_script.nil?
+        raise ArgumentError, "input #{index} of transaction #{tx_id} has no source locking script" if input.source_locking_script.nil?
+        raise ArgumentError, "input #{index} of transaction #{tx_id} has no source satoshis" if input.source_satoshis.nil?
       end
 
       def verify_fee(fee_model)
@@ -647,8 +654,7 @@ module BSV
         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")
+                                    "insufficient fee: transaction pays #{actual_fee} sat but fee model requires #{required_fee} sat")
       end
 
       def verify_output_constraint(tx)
@@ -657,8 +663,7 @@ module BSV
         return if output_total <= input_total
 
         raise VerificationError.new(:output_overflow,
-                                    "outputs (#{output_total}) exceed inputs (#{input_total}) " \
-                                    "for transaction #{tx.txid_hex}")
+                                    "outputs (#{output_total}) exceed inputs (#{input_total}) for transaction #{tx.txid_hex}")
       end
 
       ZERO_HASH = "\x00".b * 32
@@ -731,7 +736,7 @@ module BSV
         end
       end
 
-      def distribute_change(fee_sats)
+      def distribute_change(fee_sats, change_distribution)
         change_outputs = @outputs.select(&:change)
         return if change_outputs.empty?
 
@@ -741,14 +746,87 @@ module BSV
 
         if available <= change_outputs.length
           @outputs.reject!(&:change)
+          return
+        end
+
+        if change_distribution == :random
+          distribute_random_change(available, change_outputs)
         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
+          distribute_equal_change(available, change_outputs)
         end
       end
+
+      def distribute_equal_change(available, change_outputs)
+        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
+
+      # Distribute change using a Benford-inspired algorithm that biases amounts
+      # towards the lower end of the available range.
+      #
+      # Algorithm:
+      # 1. Reserve 1 satoshi per change output as a minimum guarantee.
+      # 2. For each output except the last, take a Benford-scaled portion of the
+      #    remaining pool and add it to that output's base amount.
+      # 3. The last change output receives only its 1 sat base.
+      # 4. Any remainder (from floor rounding) is assigned to the last transaction
+      #    output, matching TS SDK behaviour.
+      #
+      # @param available [Integer] total satoshis to distribute
+      # @param change_outputs [Array<TransactionOutput>] outputs flagged as change
+      # @return [void]
+      def distribute_random_change(available, change_outputs)
+        n = change_outputs.length
+
+        # Initialise each output with a 1-sat base and reserve that pool
+        amounts = Array.new(n, 1)
+        pool = available - n
+        distributed = n
+
+        # Allocate Benford-scaled portions to all outputs except the last
+        (n - 1).times do |i|
+          portion = benford_number(0, pool)
+          amounts[i] += portion
+          distributed += portion
+          pool -= portion
+        end
+
+        # Assign computed amounts to change outputs
+        change_outputs.each_with_index do |output, i|
+          output.satoshis = amounts[i]
+        end
+
+        # Assign any remainder (floor-rounding loss) to the last transaction output
+        remainder = available - distributed
+        return unless remainder.positive?
+
+        last_output = @outputs.last
+        last_output.satoshis = (last_output.satoshis || 0) + remainder
+      end
+
+      # Generate a Benford-inspired integer in the range [min, max).
+      #
+      # Randomly selects a scale factor that biases the result towards the lower end of
+      # the range, based on the Benford distribution of leading digits.
+      #
+      # Reference ts SDK implementation
+      # Math.floor(min + ((max - min) * Math.log10(1 + 1 / d)) / Math.log10(10))
+      #
+      # We simplify:
+      #  - log10(10) = 1, divide by 1 is a no-op, removed it
+      #  - pre-calculated the 9 possible values to a look-up table LOG10_RECIPROCAL_D_VALUES_1TO9
+      #  - rearrange to "start at min, add a scaled portion of the range"
+      #
+      # @param min [Integer] lower bound (inclusive)
+      # @param max [Integer] upper bound (exclusive)
+      # @return [Integer] Benford-distributed integer
+      def benford_number(min, max)
+        scale_factor = LOG10_RECIPROCAL_D_VALUES_1TO9[Random.rand(9)] # Array indexing starts at 0
+        (min + (scale_factor * (max - min))).floor
+      end
     end
   end
 end

data/lib/bsv/transaction/transaction_input.rb

@@ -74,9 +74,8 @@ module BSV
         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}"
+                "truncated input: need #{script_len} bytes for script at offset #{offset}, got #{data.bytesize - offset}"
         end
 
         unlocking_script = (BSV::Script::Script.from_binary(data.byteslice(offset, script_len)) if script_len.positive?)

data/lib/bsv/transaction/transaction_output.rb

@@ -52,9 +52,8 @@ module BSV
         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}"
+                "truncated output: need #{script_len} bytes for script at offset #{offset}, got #{data.bytesize - offset}"
         end
 
         script_bytes = data.byteslice(offset, script_len)

data/lib/bsv/transaction/var_int.rb

@@ -32,10 +32,7 @@ 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
+        raise ArgumentError, "truncated varint: need 1 byte at offset #{offset}, got end of data" if offset >= data.bytesize
 
         first = data.getbyte(offset)
 
@@ -43,24 +40,15 @@ module BSV
         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
+          raise ArgumentError, "truncated varint: need 3 bytes at offset #{offset}, got #{data.bytesize - offset}" if data.bytesize < offset + 3
 
           [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
+          raise ArgumentError, "truncated varint: need 5 bytes at offset #{offset}, got #{data.bytesize - offset}" if data.bytesize < offset + 5
 
           [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
+          raise ArgumentError, "truncated varint: need 9 bytes at offset #{offset}, got #{data.bytesize - offset}" if data.bytesize < offset + 9
 
           [data.byteslice(offset + 1, 8).unpack1('Q<'), 9]
         end

data/lib/bsv/transaction.rb

@@ -8,19 +8,19 @@ module BSV
   # {Transaction::MerklePath} for BRC-74 merkle proofs, and
   # {Transaction::Sighash} constants for BIP-143 sighash computation.
   module Transaction
-    autoload :VarInt,            'bsv/transaction/var_int'
-    autoload :TransactionOutput, 'bsv/transaction/transaction_output'
-    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'
-    autoload :Transaction,               'bsv/transaction/transaction'
+    autoload :VarInt,                   'bsv/transaction/var_int'
+    autoload :TransactionOutput,        'bsv/transaction/transaction_output'
+    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'
+    autoload :Transaction,              'bsv/transaction/transaction'
   end
 end

data/lib/bsv/version.rb

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

data/lib/bsv/wallet_interface/chain_provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Duck-typed interface for blockchain data providers.
+    #
+    # Include this module in chain provider adapters and override all methods.
+    # The default implementations raise NotImplementedError.
+    #
+    # @example Custom provider
+    #   class MyChainProvider
+    #     include BSV::Wallet::ChainProvider
+    #
+    #     def get_height
+    #       # query your node/API
+    #     end
+    #
+    #     def get_header(height)
+    #       # return 80-byte hex block header
+    #     end
+    #   end
+    module ChainProvider
+      # Returns the current blockchain height.
+      # @return [Integer]
+      def get_height
+        raise NotImplementedError, "#{self.class}#get_height not implemented"
+      end
+
+      # Returns the block header at the given height.
+      # @param _height [Integer] block height
+      # @return [String] 80-byte hex-encoded block header
+      def get_header(_height)
+        raise NotImplementedError, "#{self.class}#get_header not implemented"
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/errors/invalid_hmac_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class InvalidHmacError < WalletError
+      def initialize(message = 'The provided HMAC is invalid')
+        super(message, 3)
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/errors/invalid_parameter_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class InvalidParameterError < WalletError
+      attr_reader :parameter
+
+      def initialize(parameter, must_be = 'valid')
+        @parameter = parameter
+        super("The #{parameter} parameter must be #{must_be}", 6)
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/errors/invalid_signature_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class InvalidSignatureError < WalletError
+      def initialize(message = 'The provided signature is invalid')
+        super(message, 4)
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/errors/unsupported_action_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class UnsupportedActionError < WalletError
+      def initialize(method_name = 'this method')
+        super("#{method_name} is not supported by this wallet implementation", 2)
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/errors/wallet_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class WalletError < StandardError
+      attr_reader :code
+
+      def initialize(message, code = 1)
+        @code = code
+        super(message)
+      end
+    end
+  end
+end