bsv-wallet 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9ebc3008fda1b4430f4e813abd4d9e4e87329a6845b247adab0d967b2c4fe5a
-  data.tar.gz: b05c60a9f6d73e85c2bd0d179abe77e9d80018112336ce20b92782fc35b91b6e
+  metadata.gz: 43a1c78810a0351eb11cf29575e9d2a9e8ffca2d5e844f8122bc28dc5dfffb02
+  data.tar.gz: 358f2f7514b5d44f1896ec3ca6898cfb2e195142639711e787f545d27eda6f03
 SHA512:
-  metadata.gz: f1d6d32a26a674919fb659da57e6305b641dacbeb51eb0582af92f6e60396a73eed9ff373c48a90f95a4d5e1f86cefe9e10d69e71da515b8e08fc383fb8dc872
-  data.tar.gz: 36e41e56f39d3b6ee945605a2ce831a2a220975f92458dfe081b627dc6ce9419f1a8fc69735fc6bec18cbb6e09bf5c55bf387b43ac09416c49d1af166785458c
+  metadata.gz: c82bcf291d49346fd574d8bf442b690575f4b42d3c66e94a8262a32ceab596831d7c9b8c69a3617e5540f29e93417014f16979aa0e345eff0b48577de6ddf10e
+  data.tar.gz: 8a5adfbe6bb90ea76d8478d181f3a453d5a9c4a15ad3a1f7eb833ef9d1b2862b5305d2dcaab016f4b10d83f5f091338f1e66c9ba3fdf0858f25597304d345308

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to the `bsv-wallet` 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.11.0 — 2026-04-22
+
+### Added
+- `chain_data_source:` constructor param on `Client` — injectable chain
+  data provider for local blockchain queries without a remote substrate
+- `sync_utxos` restored — discovers on-chain UTXOs via the chain data
+  source and imports them into storage as `:spendable` with
+  `derivation_type: :identity`. Deduplicates transaction fetches and
+  validates UTXO API values against transaction outputs (#599)
+- `get_height` restored with local chain data fallback — returns
+  `{ height: Integer }` without requiring a substrate (#597)
+- `get_header_for_height` restored with local chain data fallback —
+  returns WoC block header JSON (#598)
+- BEEF SPV merkle root verification restored in `internalize_action`
+  when a chain data source with `valid_root_for_height?` is available;
+  error messages now distinguish SPV rejection from structural
+  invalidity (#600)
+- Store conformance shared examples extracted to
+  `lib/bsv/wallet/testing/` — downstream adapter gems can now
+  `require 'bsv/wallet/testing/store_conformance'` for interface and
+  wallet-level test coverage (#591)
+
+### Changed
+- `MemoryStore` guarded in `Client.new` — raises `ArgumentError` unless
+  `allow_memory_store: true` is passed, preventing accidental data loss
+  in production
+- Wallet-level dual-store specs refactored to use shared examples via
+  `it_behaves_like`; no test coverage lost (1281 examples preserved)
+
+### Fixed
+- `sync_utxos` deduplicates UTXO response entries before processing
+  and caches fetched transactions by txid to minimise WoC API calls
+- `internalize_action` chain tracker guard uses explicit nil check for
+  clarity
+- Consistent error message wording across `get_height` and
+  `get_header_for_height`
+
 ## 0.10.0 — 2026-04-21
 
 ### Added

data/lib/bsv/wallet/client/brc100/network.rb

@@ -7,26 +7,46 @@ module BSV
       module Network
         # Returns the current blockchain height.
         #
-        # Requires a substrate — raises {UnsupportedActionError} locally.
+        # Delegates to the substrate when configured. Falls back to the local
+        # chain data source when present. Raises {UnsupportedActionError} when
+        # neither is available.
         #
         # @return [Hash] { height: Integer }
         def get_height(args = {}, originator: nil)
           return @substrate.get_height(args, originator: originator) if @substrate
 
-          raise UnsupportedActionError, 'get_height requires a remote substrate'
+          raise UnsupportedActionError, 'get_height requires a chain_data_source or remote substrate' unless @chain_data_source
+
+          { height: @chain_data_source.current_height }
         end
 
         # Returns the block header at the given height.
         #
-        # Requires a substrate — raises {UnsupportedActionError} locally.
+        # Delegates to the substrate when configured; falls back to the local
+        # chain data source otherwise.
+        #
+        # Note: BRC-100 specifies +{ header: String }+ (80-byte raw hex), but the
+        # local fallback returns the richer WoC JSON hash (containing +hash+,
+        # +merkleroot+, +previousblockhash+, +time+, +nonce+, +bits+,
+        # +version+, and +height+) under the +header+ key. This is strictly more
+        # useful for local callers and avoids error-prone byte-order reassembly.
+        #
+        # *Warning:* the WalletWire binary serialiser expects +header+ to be a
+        # hex string. This local fallback should not be used behind a wire
+        # transport without first converting the JSON hash to raw 80-byte hex.
         #
         # @param args [Hash]
-        # @option args [Integer] :height block height
-        # @return [Hash] { header: String } 80-byte hex-encoded block header
+        # @option args [Integer] :height block height (must be >= 0)
+        # @return [Hash] { header: Hash } WoC block header JSON
         def get_header_for_height(args, originator: nil)
           return @substrate.get_header_for_height(args, originator: originator) if @substrate
 
-          raise UnsupportedActionError, 'get_header_for_height requires a remote substrate'
+          raise UnsupportedActionError, 'get_header_for_height requires a chain_data_source or remote substrate' unless @chain_data_source
+
+          height = args[:height]
+          raise InvalidParameterError.new('height', 'a non-negative Integer') unless height.is_a?(Integer) && !height.negative?
+
+          { header: @chain_data_source.get_block_header(height) }
         end
 
         # Returns the network this wallet is configured for.

data/lib/bsv/wallet/client/brc100/transaction.rb

@@ -175,7 +175,19 @@ module BSV
           beef_binary = args[:tx].pack('C*')
           beef = BSV::Transaction::Beef.from_binary(beef_binary)
 
-          raise WalletError, 'BEEF verification failed: the bundle is structurally invalid' unless beef.verify(nil)
+          # Use the chain data source for SPV merkle root verification when available;
+          # fall back to structural-only verification otherwise.
+          chain_tracker = @chain_data_source if @chain_data_source.respond_to?(:valid_root_for_height?)
+          unless beef.verify(chain_tracker)
+            # Distinguish SPV failures from structural invalidity so callers
+            # can tell whether the problem is the BEEF itself or the merkle root.
+            message = if chain_tracker && beef.verify(nil)
+                        'BEEF verification failed: merkle root not confirmed by chain tracker'
+                      else
+                        'BEEF verification failed: the bundle is structurally invalid'
+                      end
+            raise WalletError, message
+          end
 
           tx = extract_subject_transaction(beef)
 

data/lib/bsv/wallet/client/certificate_signature.rb

@@ -56,7 +56,7 @@ module BSV
       #   a fresh +Client.new('anyone', storage: Store::Memory.new)+
       # @return [true] when the signature verifies
       # @raise [InvalidError] otherwise
-      def verify!(cert, verifier: Client.new('anyone', storage: Store::Memory.new))
+      def verify!(cert, verifier: Client.new('anyone', storage: Store::Memory.new, allow_memory_store: true))
         signature_hex = cert[:signature]
         raise InvalidError, 'signature is missing' if signature_hex.nil? || signature_hex.empty?
 

data/lib/bsv/wallet/client.rb

@@ -50,9 +50,13 @@ module BSV
       # @return [Interface, nil] the optional substrate for remote wallet delegation
       attr_reader :substrate
 
+      # @return [#current_height, #get_block_header, #fetch_utxos, #fetch_transaction, nil]
+      #   optional chain data source for SPV and block header lookups
+      attr_reader :chain_data_source
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
-      # @param storage [Store] persistence adapter (default: Store::File.new).
-      #   Use +storage: Store::Memory.new+ for tests.
+      # @param storage [Store] persistence adapter (default: Store::File.new)
+      # @param allow_memory_store [Boolean] set +true+ to suppress the MemoryStore safety guard
       # @param network [String] 'mainnet' (default) or 'testnet'
       # @param proof_store [ProofStore, nil] merkle proof store (default: LocalProofStore backed by storage)
       # @param http_client [#request, nil] injectable HTTP client for certificate issuance
@@ -62,6 +66,8 @@ module BSV
       # @param broadcaster [#broadcast, nil] optional broadcaster
       # @param broadcast_queue [BroadcastQueue, nil] optional broadcast queue; defaults to BroadcastQueue::Inline
       # @param substrate [Interface, nil] optional remote wallet substrate
+      # @param chain_data_source [#current_height, #get_block_header, #fetch_utxos, #fetch_transaction, nil]
+      #   optional chain data source for SPV and block header lookups
       def initialize(
         key,
         storage: Store::File.new,
@@ -73,10 +79,19 @@ module BSV
         change_generator: nil,
         broadcaster: nil,
         broadcast_queue: nil,
-        substrate: nil
+        substrate: nil,
+        chain_data_source: nil,
+        allow_memory_store: false
       )
+        if storage.is_a?(Store::Memory) && !storage.is_a?(Store::File) && !allow_memory_store
+          raise ArgumentError,
+                'MemoryStore is not a safe storage adapter for wallets. ' \
+                'See: https://sgbett.github.io/bsv-ruby-sdk/gems/wallet/#storage-adapters'
+        end
+
         @key_deriver = key.is_a?(KeyDeriver) ? key : KeyDeriver.new(key)
         @substrate = substrate
+        @chain_data_source = chain_data_source
         @storage = storage
         @network = network
         @proof_store = proof_store || LocalProofStore.new(storage)
@@ -98,9 +113,68 @@ module BSV
         @broadcast_queue.broadcast_enabled?
       end
 
-      # Raises {UnsupportedActionError}.
+      # Discovers UTXOs on-chain for the wallet's identity address and imports
+      # any that are not already in local storage.
+      #
+      # Requires either a substrate or a chain_data_source. When both are present,
+      # the substrate takes priority.
+      #
+      # @return [Integer] number of UTXOs imported (0 if nothing new)
+      # @raise [UnsupportedActionError] when neither substrate nor chain_data_source is set
+      # @raise [WalletError] when a fetched transaction has an out-of-bounds tx_pos
       def sync_utxos
-        raise UnsupportedActionError, 'sync_utxos requires a remote substrate or custom integration'
+        return @substrate.sync_utxos if @substrate
+
+        raise UnsupportedActionError, 'sync_utxos requires a chain_data_source or remote substrate' unless @chain_data_source
+
+        address = identity_address
+        utxos = @chain_data_source.fetch_utxos(address)
+        return 0 if utxos.empty?
+
+        # Group UTXOs by tx_hash to minimise WoC API calls — rate limiting
+        # is aggressive and penalties are harsh, so one fetch per transaction
+        # is far better than one fetch per UTXO.
+        tx_cache = {}
+        new_utxos = utxos.uniq { |u| "#{u.tx_hash}.#{u.tx_pos}" }
+                         .reject { |u| output_exists?("#{u.tx_hash}.#{u.tx_pos}") }
+        return 0 if new_utxos.empty?
+
+        new_utxos.each do |utxo|
+          tx = tx_cache[utxo.tx_hash] ||= @chain_data_source.fetch_transaction(utxo.tx_hash)
+
+          pos = utxo.tx_pos
+          unless pos.is_a?(Integer) && pos >= 0 && pos < tx.outputs.length
+            raise WalletError, "Invalid tx_pos #{pos.inspect} for #{utxo.tx_hash} (#{tx.outputs.length} outputs)"
+          end
+
+          output = tx.outputs[pos]
+          output_satoshis = output.satoshis
+
+          # The transaction output is the authoritative source for satoshis —
+          # a mismatch with the UTXO API would produce invalid sighashes.
+          if !utxo.satoshis.nil? && utxo.satoshis != output_satoshis
+            raise WalletError,
+                  "UTXO value mismatch for #{utxo.tx_hash}.#{pos}: " \
+                  "chain reported #{utxo.satoshis}, tx output is #{output_satoshis}"
+          end
+
+          locking_script_hex = output.locking_script.to_hex
+          outpoint = "#{utxo.tx_hash}.#{utxo.tx_pos}"
+
+          @storage.store_output({
+                                  outpoint: outpoint,
+                                  satoshis: output_satoshis,
+                                  locking_script: locking_script_hex,
+                                  basket: 'default',
+                                  tags: [],
+                                  derivation_type: :identity,
+                                  state: :spendable,
+                                  source_tx_hex: tx.to_hex
+                                })
+          @storage.store_transaction(utxo.tx_hash, tx.to_hex)
+        end
+
+        new_utxos.length
       end
 
       # --- UTXO Pool & Settings ---

data/lib/bsv/wallet/store.rb

@@ -3,6 +3,14 @@
 module BSV
   module Wallet
     # Storage implementations. See {Interface::Store} for the contract.
+    #
+    # The recommended adapter is {Store::File} (JSON file-backed) or
+    # +bsv-wallet-postgres+ for production use.
+    #
+    # {Store::Memory} is available but will raise when passed to
+    # +Client.new+ unless +allow_memory_store: true+ is set — data is
+    # lost on process exit, including derived key material needed to
+    # spend change outputs.
     module Store
       autoload :Memory, 'bsv/wallet/store/memory'
       autoload :File,   'bsv/wallet/store/file'