bsv-sdk 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1ead96687ff2a6118fde4ab72a7dc0b11c7d82db8b4b883910120bcc0cee0dc
-  data.tar.gz: 5a089f6b80111ba4abf5472bfbd8067a028b35a73f90e504e2541376d0d00d55
+  metadata.gz: 4532a163439721455da80290d8b02342e597a01bb1e00b259d13343f8f9bd592
+  data.tar.gz: b7cfda4a8084b96c28f34afb6829fcba9f5be0dabb01fca536147bfe2c66bad8
 SHA512:
-  metadata.gz: d05f8b3b8a584706323c631fb9ff005420c6d5cdc5081f76fbf6a73b15c12323b87d30f469e5fa186bfa30b51905ffe4bc0785b57bd77d72286ee3f8ce03dc1f
-  data.tar.gz: b892a8add5e5faaad6bc837ab26de879419cc457d909be4f5b1fb812fd4a69fb5356529689081dffe1195caffdb2e259da6a073ea1ce6ff2f0d08068c73a67f1
+  metadata.gz: ed0b97db3cec8503eba509f232a463d8566373b34ccaf5fe7cd130a72e712cde17b083b4ce94ef64fa84786d6e6aec8965423ca6b8a7471ada70ebd522956e2a
+  data.tar.gz: 0747a93bef059a8eccf0f504e703d20ddc875f8c562db8f01d3af4050bf7562deb262eb4494db4d98b78665f91274ed77754fa76e99254b8592b7e0f1526aa13

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to the `bsv-sdk` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.0 — 2026-04-22
+
+### Added
+- `BSV::Network::WhatsOnChain` expanded with `current_height`,
+  `get_block_header(height)`, and `valid_root_for_height?(root, height)` —
+  a single WhatsOnChain instance now serves as a complete chain data source
+  (#596)
+- BEEF-based SPV verification conformance tests (#607)
+
+### Changed
+- `Transaction#verify` now raises `VerificationError` for all failure modes:
+  `:script_failure` (wraps `ScriptError` with cause chaining),
+  `:missing_source` (replaces `ArgumentError`), `:invalid_merkle_proof`,
+  `:insufficient_fee`, and `:output_overflow`. Code rescuing `ArgumentError`
+  or `ScriptError` from `verify` must switch to `VerificationError` (#608)
+- Removed dead code: `BSV::Wallet::Wallet` (superseded by bsv-wallet gem's
+  `Client`), `BSV::Messages` (unused re-export alias), and duplicate
+  `BSV::Wallet::InsufficientFundsError` (#594)
+
+### Fixed
+- WhatsOnChain `valid_root_for_height?` YARD doc now correctly documents
+  that 404 returns `false` rather than raising
+
 ## 0.13.0 — 2026-04-21
 
 ### Added

data/lib/bsv/auth/certificate.rb

@@ -176,7 +176,7 @@ module BSV
       def verify(verifier_wallet = nil)
         raise ArgumentError, 'certificate has no signature to verify' if @signature.nil? || @signature.empty?
 
-        verifier_wallet ||= BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new)
+        verifier_wallet ||= BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new, allow_memory_store: true)
         preimage  = to_binary(include_signature: false)
         sig_bytes = [@signature].pack('H*').unpack('C*')
 

data/lib/bsv/network/whats_on_chain.rb

@@ -5,8 +5,11 @@ module BSV
     # WhatsOnChain chain data provider for reading transactions and UTXOs
     # from the BSV network.
     #
-    # Any object responding to #fetch_utxos(address) and
-    # #fetch_transaction(txid) can serve as a chain data provider;
+    # Any object responding to #fetch_utxos(address),
+    # #fetch_transaction(txid), #current_height,
+    # #get_block_header(height), and optionally
+    # #valid_root_for_height?(root_hex, height) can serve as a chain
+    # data source;
     # this class implements that contract by delegating to
     # Protocols::WoCREST.
     #
@@ -62,6 +65,42 @@ module BSV
         BSV::Transaction::Transaction.from_hex(result.data)
       end
 
+      # Return the current blockchain height.
+      # @return [Integer]
+      # @raise [BSV::Network::ChainProviderError] on network or API error
+      def current_height
+        result = @protocol.call(:current_height)
+        raise_on_error(result)
+
+        result.data
+      end
+
+      # Fetch the block header for a given height.
+      # @param height [Integer] block height
+      # @return [Hash] parsed block header JSON
+      # @raise [BSV::Network::ChainProviderError] on network or API error
+      def get_block_header(height)
+        result = @protocol.call(:get_block_header, height)
+        raise_on_error(result)
+
+        result.data
+      end
+
+      # Verify that a merkle root is valid for the given block height.
+      # Returns +false+ when the block is not found (404); raises on other errors.
+      # @param root [String] expected merkle root as hex
+      # @param height [Integer] block height
+      # @return [Boolean]
+      # @raise [BSV::Network::ChainProviderError] on network or non-404 API error
+      def valid_root_for_height?(root, height)
+        result = @protocol.call(:valid_root, root, height)
+        return false if result.not_found?
+
+        raise_on_error(result)
+
+        result.data == true
+      end
+
       private
 
       # Translates a non-success Protocol result into a raised ChainProviderError.

data/lib/bsv/transaction/transaction.rb

@@ -550,12 +550,30 @@ module BSV
       #    provided fee model.
       # 4. Checks that total outputs do not exceed total inputs.
       #
+      # == Semantic Divergences from Reference SDKs
+      #
+      # This implementation raises +VerificationError+ for all failure modes.
+      # The TypeScript and Python SDKs return +false+ for script failures and
+      # output overflow. The Go SDK propagates errors (not booleans) for script
+      # failures, aligning with the Ruby approach.
+      #
+      # Rationale: raising provides structured error information (+#code+,
+      # +#message+, +#cause+) that a boolean cannot convey. Consumers can
+      # rescue +VerificationError+ and inspect +#code+ for specifics.
+      #
+      # Divergence summary:
+      # - +:output_overflow+ — Ruby raises; TS/Python return +false+; Go omits the check
+      # - +:script_failure+ — Ruby raises; TS/Python return +false+; Go also propagates errors
+      # - +:missing_source+ — Ruby raises; consistent with TS/Go/Python (all raise/error)
+      #
       # @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
+      # @raise [VerificationError] with code +:invalid_merkle_proof+ if a merkle proof is invalid
+      # @raise [VerificationError] with code +:insufficient_fee+ if the fee is below the model's threshold
+      # @raise [VerificationError] with code +:output_overflow+ if outputs exceed inputs
+      # @raise [VerificationError] with code +:script_failure+ if script execution fails
+      # @raise [VerificationError] with code +:missing_source+ if an input is missing required source data
       def verify(chain_tracker:, fee_model: nil)
         verified = {}
         queue = [self]
@@ -581,8 +599,26 @@ module BSV
 
           # Verify each input
           tx.inputs.each_with_index do |input, index|
+            # Populate source data from source_transaction when not already set.
+            # Matches the TS SDK pattern: sourceOutput is read directly from
+            # source_transaction.outputs[sourceOutputIndex] during verify.
+            if input.source_transaction
+              source_output = input.source_transaction.outputs[input.prev_tx_out_index]
+              if source_output
+                input.source_locking_script ||= source_output.locking_script
+                input.source_satoshis ||= source_output.satoshis
+              end
+            end
+
             verify_input_requirements(tx, input, index)
-            tx.verify_input(index)
+            begin
+              tx.verify_input(index)
+            rescue BSV::Script::ScriptError => e
+              raise VerificationError.new(
+                :script_failure,
+                "script verification failed for input #{index} of transaction #{tx.txid_hex}: #{e.message}"
+              )
+            end
 
             # Enqueue source transaction for verification if not yet verified
             source_tx = input.source_transaction
@@ -742,9 +778,18 @@ module BSV
 
       def verify_input_requirements(tx, input, index)
         tx_id = tx.txid_hex
-        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?
+        if input.unlocking_script.nil?
+          raise VerificationError.new(:missing_source,
+                                      "input #{index} of transaction #{tx_id} has no unlocking script")
+        end
+        if input.source_locking_script.nil?
+          raise VerificationError.new(:missing_source,
+                                      "input #{index} of transaction #{tx_id} has no source locking script")
+        end
+        return unless input.source_satoshis.nil?
+
+        raise VerificationError.new(:missing_source,
+                                    "input #{index} of transaction #{tx_id} has no source satoshis")
       end
 
       def verify_fee(fee_model)

data/lib/bsv/transaction/verification_error.rb

@@ -7,6 +7,15 @@ module BSV
     # Carries a machine-readable code alongside a human-readable message,
     # matching the typed error pattern used by the Go SDK
     # (ErrInvalidMerklePath, ErrFeeTooLow, ErrScriptVerificationFailed).
+    #
+    # == Error Codes
+    #
+    # - +:invalid_merkle_proof+ — merkle path verification failed against the chain tracker
+    # - +:insufficient_fee+ — transaction fee is below the fee model's requirement
+    # - +:output_overflow+ — total outputs exceed total inputs
+    # - +:script_failure+ — script interpreter rejected an input (original +ScriptError+ in +#cause+)
+    # - +:missing_source+ — required input data (unlocking script, source locking script,
+    #   or source satoshis) is absent
     class VerificationError < StandardError
       # @return [Symbol] the error code
       attr_reader :code
@@ -14,6 +23,8 @@ module BSV
       INVALID_MERKLE_PROOF = :invalid_merkle_proof
       INSUFFICIENT_FEE = :insufficient_fee
       OUTPUT_OVERFLOW = :output_overflow
+      SCRIPT_FAILURE = :script_failure
+      MISSING_SOURCE = :missing_source
 
       # @param code [Symbol] error code
       # @param message [String] human-readable description

data/lib/bsv/version.rb

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

data/lib/bsv-sdk.rb

@@ -7,12 +7,11 @@ module BSV
   autoload :Script,      'bsv/script'
   autoload :Transaction, 'bsv/transaction'
   autoload :Network,     'bsv/network'
-  require_relative 'bsv/wallet' # eager — BSV::Wallet may be pre-defined by bsv-wallet gemspec
   autoload :Auth,        'bsv/auth'
   autoload :Overlay,     'bsv/overlay'
   autoload :Identity,    'bsv/identity'
   autoload :Registry,    'bsv/registry'
   autoload :MCP,         'bsv/mcp'
-  autoload :Messages,    'bsv/messages'
+
   autoload :WireFormat,  'bsv/wire_format'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -67,7 +67,6 @@ files:
 - lib/bsv/mcp/tools/fetch_utxos.rb
 - lib/bsv/mcp/tools/generate_key.rb
 - lib/bsv/mcp/tools/helpers.rb
-- lib/bsv/messages.rb
 - lib/bsv/network.rb
 - lib/bsv/network/arc.rb
 - lib/bsv/network/broadcast_error.rb
@@ -163,9 +162,6 @@ files:
 - 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
-- lib/bsv/wallet/wallet.rb
 - lib/bsv/wire_format.rb
 homepage: https://github.com/sgbett/bsv-ruby-sdk
 licenses:

data/lib/bsv/messages.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  # Namespace providing TS SDK naming parity for messaging primitives.
-  #
-  # Re-exports {BSV::Primitives::SignedMessage} and {BSV::Primitives::EncryptedMessage}
-  # under the +BSV::Messages+ namespace, matching the structure of the TypeScript SDK
-  # (ts-sdk/src/messages/index.ts).
-  #
-  # The canonical implementations remain in +BSV::Primitives+; this module is a
-  # lightweight re-export only.
-  module Messages
-    SignedMessage = BSV::Primitives::SignedMessage
-    EncryptedMessage = BSV::Primitives::EncryptedMessage
-  end
-end

data/lib/bsv/wallet/insufficient_funds_error.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    class InsufficientFundsError < StandardError
-      attr_reader :required, :available
-
-      def initialize(message = nil, required: nil, available: nil)
-        @required = required
-        @available = available
-        super(message || "insufficient funds: need #{required}, have #{available}")
-      end
-    end
-  end
-end

data/lib/bsv/wallet/wallet.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    # Holds a private key, sources UTXOs via a chain data provider, and
-    # funds and signs P2PKH transactions.
-    #
-    # The provider is duck-typed — any object responding to
-    # #fetch_utxos(address) and #fetch_transaction(txid) qualifies.
-    class Wallet
-      DUST_THRESHOLD = 1
-
-      attr_reader :private_key, :provider
-
-      def initialize(private_key:, provider:)
-        @private_key = private_key
-        @provider = provider
-      end
-
-      def address(network: :mainnet)
-        @private_key.public_key.address(network: network)
-      end
-
-      def balance(network: :mainnet)
-        @provider.fetch_utxos(address(network: network)).sum(&:satoshis)
-      end
-
-      def fund(tx, network: :mainnet, satoshis_per_byte: 0.1)
-        utxos = @provider.fetch_utxos(address(network: network))
-        output_total = tx.total_output_satoshis
-
-        # Add a dummy change output so fee estimation accounts for its size
-        dummy_change = BSV::Transaction::TransactionOutput.new(
-          satoshis: 0, locking_script: locking_script
-        )
-        tx.add_output(dummy_change)
-
-        input_total = tx.total_input_satoshis
-        funded = false
-
-        utxos.each do |utxo|
-          tx.add_input(build_input(utxo))
-          input_total += utxo.satoshis
-
-          fee = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-          if input_total >= output_total + fee
-            funded = true
-            break
-          end
-        end
-
-        # Remove the dummy change output
-        tx.outputs.delete(dummy_change)
-
-        unless funded
-          fee = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-          raise InsufficientFundsError.new(required: output_total + fee, available: input_total)
-        end
-
-        add_change_if_needed(tx, input_total, output_total, satoshis_per_byte)
-
-        tx
-      end
-
-      def sign(tx)
-        tx.sign_all(@private_key)
-      end
-
-      def fund_and_sign(tx, network: :mainnet, satoshis_per_byte: 0.1)
-        fund(tx, network: network, satoshis_per_byte: satoshis_per_byte)
-        sign(tx)
-      end
-
-      private
-
-      def locking_script
-        @locking_script ||= BSV::Script::Script.p2pkh_lock(@private_key.public_key.hash160)
-      end
-
-      def build_input(utxo)
-        input = BSV::Transaction::TransactionInput.new(
-          prev_tx_id: BSV::Transaction::TransactionInput.txid_from_hex(utxo.tx_hash),
-          prev_tx_out_index: utxo.tx_pos
-        )
-        input.source_satoshis = utxo.satoshis
-        input.source_locking_script = locking_script
-        input.unlocking_script_template = BSV::Transaction::P2PKH.new(@private_key)
-        input
-      end
-
-      def add_change_if_needed(tx, input_total, output_total, satoshis_per_byte)
-        fee_without_change = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-        remainder = input_total - output_total - fee_without_change
-
-        return if remainder < DUST_THRESHOLD
-
-        change_output = BSV::Transaction::TransactionOutput.new(
-          satoshis: remainder, locking_script: locking_script
-        )
-        tx.add_output(change_output)
-
-        # Recalculate: adding the change output increases fee slightly
-        new_fee = tx.estimated_fee(satoshis_per_byte: satoshis_per_byte)
-        fee_increase = new_fee - fee_without_change
-        final_change = remainder - fee_increase
-
-        if final_change >= DUST_THRESHOLD
-          tx.outputs.delete(change_output)
-          tx.add_output(
-            BSV::Transaction::TransactionOutput.new(
-              satoshis: final_change, locking_script: locking_script
-            )
-          )
-        else
-          tx.outputs.delete(change_output) # change absorbed by fee
-        end
-      end
-    end
-  end
-end

data/lib/bsv/wallet.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    autoload :InsufficientFundsError, 'bsv/wallet/insufficient_funds_error'
-    autoload :Wallet,                 'bsv/wallet/wallet'
-  end
-end