bsv-sdk 0.24.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac0ee4456475effef9fa92627f77e4b973cfe834efda2f936725074c35060f95
-  data.tar.gz: acd91340c476db84531efd41003ea068e3b5029cbb63e74bab782d17b48694d5
+  metadata.gz: 6152fa9bc473f3ff11eca96fa5a9f1302d88cdbe3d72782c13da1760a5507514
+  data.tar.gz: e3f45fa1d03d36f9943d172fb8db396869f2ad2ff333b8d071af161062e56fc3
 SHA512:
-  metadata.gz: 02fffbfda10161282e87c26d8be157377a3b3861830b2891fe1331a3ea4b51e2743bc707fd01c8f3b1a5921173037d70322259c3d8dda39ea7caeffd2ee3cfd5
-  data.tar.gz: 0b4d5dea8e5b447d98603150a8873f14f8e24b7b75377fa5baa43bf497fedb62c11865ccc96eb15f78c49323987b896290955b483169dec065a307f468f3e584
+  metadata.gz: 802d2a0fe86432760fa64b12ac6787b4e8a9c3ce02ea5f66e19eee9e3b61bc050f0712fa8c98f5cfe0ca92550a7b7df7927624f5b120fb5274aac082acb66a0b
+  data.tar.gz: 7ecae6d4a729130f3d14e637b5822cec7bcab141a7e32abcd4d0275b4c81a0c545d64a2272a8684ef8702b85f4a676f6e3545437ccca5f38a1b57108099baf57

data/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.26.0 — 2026-07-08
+
+### Breaking Changes
+- `Transaction::Tx#verify` — the `verified:` kwarg now accepts `nil | Hash{String => Boolean}`
+  (previously `nil | Set<String>`). The Hash is mutated in place, so a caller can both pre-seed
+  the already-verified wtxid set and read back the wtxids walked during verification. A frozen
+  Hash, or a Hash with a truthy `default`/`default_proc`, is rejected at entry (funds risk) (#904).
+
+### Added
+- `Transaction::Tx#verify(verified:)` bidirectional verification cache: pre-seeding short-circuits
+  already-verified ancestor subtrees; post-read exposes the walked wtxid set for a persistent
+  verification cache (#904, #909, #910).
+- Transaction memoisation: per-struct binary, component-hash, and wire-order memos across `Tx`,
+  inputs, and outputs, invalidated on mutation — repeated `to_binary`/`wtxid`/hash computation is
+  now cached (#881).
+- Conformance canonical corpus: a pinned-revision loader plus fetch/sync tooling and cache layout,
+  with the BEEF, BUMP, sighash, SHA-256, ECIES, BRC-42 key-derivation, and script-test specs
+  migrated onto it (#840, #841, #842–#847).
+
+### Fixed
+- Interpreter consensus hardening: correct Chronicle gating of `OP_VER`/`OP_VERIF` (with
+  tx_version), `OP_2MUL`/`OP_2DIV`, and multi-`OP_ELSE` (relaxed mode); enforce the `CLEANSTACK`
+  and `SIGPUSHONLY` verification flags; whitelist verification flags (#837, #850, #851, #852, #853,
+  #854).
+- `Transaction::Tx#verify` — translate the fee-gate `ArgumentError` (missing source data) into a
+  `VerificationError` (`:missing_source`) so every failure mode raises a consistent error type
+  (#904).
+- `Transaction::Tx#verify` — fix a funds-risk bug where a Hash with a truthy default could silently
+  short-circuit verification for unseen wtxids (#904).
+
+### Changed
+- Performance: reuse OpenSSL digest contexts in primitives hashing (thread-safety documented); split
+  `clear_caches` from `invalidate_caches` in the transaction cache lifecycle (#881, #882).
+
+## 0.25.0 — 2026-06-18
+
+### Added
+- `BSV::Storage::Utils` — UHRP URL helpers (`normalise_url`, `url_for_hash`,
+  `url_for_file`, `hash_from_url`, `valid_url?`) (#817).
+- `BSV::Overlay::Historian` — generic output-history walker over `LookupResolver`,
+  enabling protocol-specific replay of an outpoint's lineage (#818).
+- `BSV::Registry` — typed `resolve_basket`, `resolve_protocol`, and
+  `resolve_certificate` methods on the registry client (#819).
+- `BSV::KVStore::Interpreter` — `Historian`-compatible interpreter for KV
+  protocol outputs (#820).
+- `BSV::Storage::Downloader` — UHRP resolver and content fetcher with
+  hash verification (#821).
+- `BSV::KVStore::Global` — overlay-backed read-only key-value reader (#822).
+- `BSV::Script::BIP276` — text encoding for scripts and templates (`encode`,
+  `decode`) (#830).
+- `BSV::Transaction::BeefParty` — `Beef` subclass tracking per-party knowledge
+  of transactions for multi-party BEEF exchange, plus supporting methods on
+  `Beef` (#831).
+
+### Changed
+- `Beef` wire-inputs debug log now uses the existing `TransactionInput#dtxid_hex`
+  and `Tx#dtxid` accessors instead of inlined byte-order conversions (#828).
+
+### Fixed
+- ECIES bitcore variant — added `iv:` kwarg and TypeScript SDK conformance
+  vector (#829).
+
 ## 0.24.0 — 2026-06-11
 
 ### Breaking Changes

data/README.md

@@ -24,7 +24,7 @@ This Ruby SDK is a port of the official BSV Blockchain SDKs, which serve as its
 
 The reference SDKs:
 
-- [TypeScript SDK](https://github.com/bsv-blockchain/ts-sdk)
+- [TypeScript SDK](https://github.com/bsv-blockchain/ts-stack)
 - [Go SDK](https://github.com/bsv-blockchain/go-sdk)
 - [Python SDK](https://github.com/bsv-blockchain/py-sdk)
 
@@ -89,8 +89,10 @@ locking_script = BSV::Script::Script.p2pkh_lock(pubkey_hash)
 tx = BSV::Transaction::Tx.new
 
 # Add an input referencing a previous transaction output
+# wtxid_from_hex converts a display-order hex txid to wire-order binary
+utxo_txid = '5884e5db9de218238671572340b207ee85b628074e7e467096c267266baf77a4'
 input = BSV::Transaction::TransactionInput.new(
-  prev_tx_id: source_txid_bytes,   # 32-byte binary txid of the UTXO
+  prev_wtxid: BSV::Transaction::TransactionInput.wtxid_from_hex(utxo_txid),
   prev_tx_out_index: 0
 )
 input.source_satoshis = 100_000

data/lib/bsv/kv_store/entry.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BSV
+  module KVStore
+    # An immutable KVStore entry returned from {Global#get}.
+    #
+    # +token+ is populated only when +include_token: true+ is passed to +#get+.
+    # +history+ is populated only when +history: true+ is passed to +#get+.
+    Entry = Data.define(:key, :value, :controller, :protocol_id, :tags, :token, :history) do
+      def initialize(key:, value:, controller:, protocol_id:, tags:, token: nil, history: nil)
+        super
+      end
+    end
+  end
+end

data/lib/bsv/kv_store/global.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module KVStore
+    # Read-only client for the global KVStore overlay service.
+    #
+    # Queries the +ls_kvstore+ lookup service via a {BSV::Overlay::LookupResolver},
+    # decodes PushDrop tokens (5-field legacy and 6-field current formats), verifies
+    # the token signature, and returns typed {Entry} objects.
+    #
+    # Set/remove operations require wallet writes and are out of scope — those live
+    # in the +bsv-wallet+ gem.
+    #
+    # == Selector requirement
+    #
+    # {#get} raises +ArgumentError+ unless at least one of +key+, +controller+,
+    # +protocol_id+, or a non-empty +tags+ array is supplied in the query.
+    #
+    # == Always returns Array
+    #
+    # {#get} always returns +Array<Entry>+, even for single-result selectors such
+    # as +key + controller+. Callers that expect at most one result should use
+    # +.first+.
+    #
+    # == Silent skipping
+    #
+    # Outputs that fail BEEF parsing, PushDrop decoding, field-count validation, or
+    # signature verification are silently skipped (matching the TS SDK contract).
+    class Global
+      # @param network_preset [Symbol] :mainnet, :testnet, or :local
+      # @param lookup_resolver [BSV::Overlay::LookupResolver, nil] injectable resolver
+      # @param service_name [String] lookup service identifier
+      # @param proto_wallet [BSV::Wallet::ProtoWallet, nil] injectable wallet used for
+      #   signature verification; defaults to +ProtoWallet.new('anyone')+. Tests can
+      #   substitute a double to avoid +allow_any_instance_of+.
+      def initialize(network_preset: :mainnet, lookup_resolver: nil, service_name: 'ls_kvstore', proto_wallet: nil)
+        @lookup_resolver = lookup_resolver || BSV::Overlay::LookupResolver.new(network_preset: network_preset)
+        @service_name = service_name
+        @proto_wallet = proto_wallet || BSV::Wallet::ProtoWallet.new('anyone')
+      end
+
+      # Query the overlay for KVStore entries.
+      #
+      # @param query [Hash] selector: +:key+, +:controller+, +:protocol_id+, +:tags+,
+      #   +:tag_query_mode+. At least one of the first four must be present.
+      # @param include_token [Boolean] populate {Token} on each entry when true
+      # @param history [Boolean] populate history via {BSV::Overlay::Historian} when true
+      # @return [Array<Entry>] matching entries (empty array when nothing matches)
+      # @raise [ArgumentError] if no selector is provided
+      def get(query, include_token: false, history: false)
+        validate_selector!(query)
+
+        question = BSV::Overlay::LookupQuestion.new(
+          service: @service_name,
+          query: camelise(query)
+        )
+
+        answer = @lookup_resolver.query(question)
+        return [] unless answer.type == 'output-list'
+
+        answer.outputs.filter_map do |output|
+          build_entry(output, include_token: include_token, history: history)
+        rescue StandardError
+          nil
+        end
+      end
+
+      private
+
+      # ---- Selector validation ----
+
+      def validate_selector!(query)
+        raise ArgumentError, 'query must be a Hash' unless query.is_a?(Hash)
+
+        has_key        = query[:key].is_a?(String)        && !query[:key].empty?
+        has_controller = query[:controller].is_a?(String) && !query[:controller].empty?
+        has_protocol   = query[:protocol_id].is_a?(Array) && query[:protocol_id].length == 2
+        has_tags       = query[:tags].is_a?(Array)        && !query[:tags].empty?
+
+        return if has_key || has_controller || has_protocol || has_tags
+
+        raise ArgumentError,
+              'At least one selector required (key, controller, protocol_id, or non-empty tags)'
+      end
+
+      # ---- Entry construction ----
+
+      def build_entry(output, include_token:, history:)
+        beef_data    = output['beef'] || output[:beef]
+        output_index = (output['outputIndex'] || output[:output_index] || 0).to_i
+        raise 'Negative outputIndex' if output_index.negative?
+
+        beef = parse_beef!(beef_data)
+        beef_tx = beef.transactions.last
+        raise 'No transaction in BEEF' if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
+
+        tx     = beef_tx.transaction
+        txout  = tx.outputs[output_index]
+        raise 'outputIndex out of range' if txout.nil?
+
+        locking_script = txout.locking_script
+        raise 'No locking script' unless locking_script&.pushdrop?
+
+        raw_fields = locking_script.pushdrop_fields
+        raise 'Not a PushDrop script' unless raw_fields
+
+        field_count = raw_fields.length
+        raise "Unexpected field count: #{field_count}" unless [5, 6].include?(field_count)
+
+        # Separate data fields from trailing signature field
+        data_fields = raw_fields[0...-1]
+        sig_bytes   = raw_fields.last
+
+        # Decode common fields (indices match kvProtocol in TS SDK)
+        protocol_id = decode_protocol_id!(data_fields[0])
+        key         = decode_utf8!(data_fields[1])
+        value       = decode_utf8!(data_fields[2])
+        controller  = data_fields[3].unpack1('H*')
+
+        # New format (6 fields) has tags at index 4; old format (5 fields) has no tags field
+        tags = if field_count == 6
+                 begin
+                   JSON.parse(decode_utf8!(data_fields[4]))
+                 rescue StandardError
+                   nil
+                 end
+               end
+
+        verify_signature!(data_fields, sig_bytes, protocol_id, key, controller)
+
+        token = if include_token
+                  Token.new(
+                    dtxid: tx.dtxid_hex,
+                    output_index: output_index,
+                    beef: beef,
+                    satoshis: txout.satoshis || 0
+                  )
+                end
+
+        entry_history = if history
+                          BSV::Overlay::Historian
+                            .new(BSV::KVStore::Interpreter)
+                            .build_history(tx, { key: key, protocol_id: protocol_id })
+                        end
+
+        Entry.new(
+          key: key,
+          value: value,
+          controller: controller,
+          protocol_id: protocol_id,
+          tags: tags,
+          token: token,
+          history: entry_history
+        )
+      end
+
+      # ---- Field decoding helpers ----
+
+      def parse_beef!(beef_data)
+        case beef_data
+        when String
+          BSV::Transaction::Beef.from_binary(beef_data)
+        when Array
+          BSV::Transaction::Beef.from_binary(beef_data.pack('C*'))
+        else
+          raise 'Missing or unsupported BEEF data'
+        end
+      end
+
+      def decode_utf8!(bytes)
+        raise 'Nil field' if bytes.nil?
+
+        str = bytes.force_encoding(Encoding::UTF_8)
+        raise 'Invalid UTF-8' unless str.valid_encoding?
+
+        str
+      end
+
+      def decode_protocol_id!(bytes)
+        JSON.parse(decode_utf8!(bytes))
+      end
+
+      # ---- Signature verification ----
+
+      def verify_signature!(data_fields, sig_bytes, protocol_id, key, controller)
+        @proto_wallet.verify_signature(
+          data: data_fields.join.bytes,
+          signature: sig_bytes.bytes,
+          protocol_id: protocol_id,
+          key_id: key,
+          counterparty: controller
+        )
+      end
+
+      # ---- Query key camelisation ----
+
+      def camelise(query)
+        query.transform_keys do |k|
+          case k
+          when :protocol_id    then :protocolID
+          when :tag_query_mode then :tagQueryMode
+          else k
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/kv_store/interpreter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BSV
+  module KVStore
+    # Historian interpreter for KVStore PushDrop tokens.
+    #
+    # Decodes a PushDrop locking script from the specified output, validates it
+    # has the expected field count (5 old format / 6 new format), and filters by
+    # +ctx[:key]+ and +ctx[:protocol_id]+.
+    #
+    # Returns the value as a UTF-8 string, or +nil+ for any non-match or error.
+    # Never raises.
+    #
+    # Field layout (old format — 5 fields):
+    #   [0] protocolID (JSON-encoded array)
+    #   [1] key
+    #   [2] value
+    #   [3] controller
+    #   [4] signature
+    #
+    # Field layout (new format — 6 fields):
+    #   [0] protocolID (JSON-encoded array)
+    #   [1] key
+    #   [2] value
+    #   [3] controller
+    #   [4] tags
+    #   [5] signature
+    module Interpreter
+      PROTOCOL_ID    = 0
+      KEY            = 1
+      VALUE          = 2
+      CONTROLLER     = 3
+      TAGS_NEW       = 4
+      SIGNATURE_OLD  = 4
+      SIGNATURE_NEW  = 5
+
+      KV_PROTOCOL_FIELDS_OLD = 5
+      KV_PROTOCOL_FIELDS_NEW = 6
+
+      # Decode the KVStore token at +output_index+ in +tx+.
+      #
+      # Implements the Historian interpreter contract:
+      # +interpreter.call(tx, output_index, ctx)+ → String or nil.
+      #
+      # @param tx [Transaction::Tx, nil] the transaction to inspect
+      # @param output_index [Integer] index into +tx.outputs+
+      # @param ctx [Hash, nil] must contain +:key+ (String) and +:protocol_id+ (Array)
+      # @return [String, nil] the decoded UTF-8 value, or nil on any mismatch/error
+      def self.call(tx, output_index, ctx)
+        return nil if tx.nil?
+        return nil if ctx.nil? || ctx[:key].nil?
+
+        output = tx.outputs[output_index]
+        return nil if output.nil?
+
+        locking_script = output.locking_script
+        return nil if locking_script.nil?
+
+        return nil unless locking_script.pushdrop?
+
+        fields = locking_script.pushdrop_fields
+        return nil unless fields
+
+        field_count = fields.length
+        return nil unless [KV_PROTOCOL_FIELDS_OLD, KV_PROTOCOL_FIELDS_NEW].include?(field_count)
+
+        protocol_id_bytes = fields[PROTOCOL_ID]
+        return nil if protocol_id_bytes.nil?
+
+        begin
+          protocol_id_str = protocol_id_bytes.force_encoding(Encoding::UTF_8)
+          return nil unless protocol_id_str.valid_encoding?
+
+          parsed_protocol_id = JSON.parse(protocol_id_str)
+          return nil unless parsed_protocol_id == ctx[:protocol_id]
+        rescue JSON::ParserError
+          return nil
+        end
+
+        key_bytes = fields[KEY]
+        return nil if key_bytes.nil?
+
+        begin
+          key_str = key_bytes.force_encoding(Encoding::UTF_8)
+          return nil unless key_str.valid_encoding?
+          return nil unless key_str == ctx[:key]
+        rescue StandardError
+          return nil
+        end
+
+        begin
+          value_bytes = fields[VALUE]
+          return nil if value_bytes.nil?
+
+          value_str = value_bytes.force_encoding(Encoding::UTF_8)
+          return nil unless value_str.valid_encoding?
+
+          value_str
+        rescue StandardError
+          nil
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/bsv/kv_store/token.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BSV
+  module KVStore
+    # Transaction output reference for a KVStore token.
+    #
+    # Populated when +include_token: true+ is passed to {Global#get}.
+    Token = Data.define(:dtxid, :output_index, :beef, :satoshis)
+  end
+end

data/lib/bsv/kv_store.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BSV
+  module KVStore
+    autoload :Interpreter, 'bsv/kv_store/interpreter'
+    autoload :Entry,       'bsv/kv_store/entry'
+    autoload :Token,       'bsv/kv_store/token'
+    autoload :Global,      'bsv/kv_store/global'
+  end
+end

data/lib/bsv/mcp/tools/helpers.rb

@@ -21,7 +21,7 @@ module BSV
 
         # Convert a Transaction to a hash suitable for JSON responses.
         #
-        # @param tx [BSV::Transaction::Tx]
+        # @param tx [Transaction::Tx]
         # @return [Hash]
         def self.transaction_to_h(tx)
           {
@@ -33,7 +33,7 @@ module BSV
           }
         end
 
-        # Convert a TransactionInput to a hash.
+        # Convert a Transaction::TransactionInput to a hash.
         # @api private
         def self.input_to_h(input, _index)
           unlock_script = input.unlocking_script
@@ -46,7 +46,7 @@ module BSV
           }
         end
 
-        # Convert a TransactionOutput to a hash.
+        # Convert a Transaction::TransactionOutput to a hash.
         # @api private
         def self.output_to_h(output, index)
           script = output.locking_script

data/lib/bsv/overlay/admin_token_template.rb

@@ -80,7 +80,7 @@ module BSV
         # Computes the BIP-143 sighash (SIGHASH_ALL|FORK_ID) and signs it
         # using the wallet's derived key for the protocol.
         #
-        # @param tx [BSV::Transaction::Tx] the spending transaction
+        # @param tx [Transaction::Tx] the spending transaction
         # @param input_index [Integer] which input to sign
         # @return [BSV::Script::Script] the unlocking script
         def sign(tx, input_index)
@@ -101,7 +101,7 @@ module BSV
 
         # Estimated byte length of the unlocking script.
         #
-        # @param _tx [BSV::Transaction::Tx] unused
+        # @param _tx [Transaction::Tx] unused
         # @param _input_index [Integer] unused
         # @return [Integer]
         def estimated_length(_tx, _input_index)

data/lib/bsv/overlay/historian.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module BSV
+  module Overlay
+    # Builds a chronological history (oldest → newest) of typed values by traversing
+    # a transaction's input ancestry and interpreting each output with a provided interpreter.
+    #
+    # The interpreter contract is: +interpreter.call(tx, output_index, ctx)+, returning the
+    # typed value or +nil+. Any callable responding to +:call+ is accepted (lambda, proc,
+    # method, or object).
+    #
+    # Traversal follows +input.source_transaction+ references recursively. Callers must
+    # supply transactions whose inputs have +source_transaction+ populated.
+    #
+    # == Cycle safety
+    #
+    # Each transaction is visited at most once, tracked by its +wtxid+ (wire-order binary).
+    #
+    # == Value semantics
+    #
+    # Only +nil+ is excluded. Falsy non-nil values (+false+, +""+, +0+) are valid history
+    # entries and are included in the result.
+    #
+    # == Caching
+    #
+    # An optional +history_cache+ (any +[]/[]=+ responder) caches complete history results.
+    # Cache keys have the form: <tt>"#{interpreter_version}|#{dtxid_hex}|#{ctx_key}"</tt>.
+    # Cached arrays are stored frozen; each retrieval returns a +dup+ to protect the cache.
+    #
+    # == Note
+    #
+    # The Ruby Historian is synchronous. There is no async/await semantics.
+    class Historian
+      # @param interpreter       [#call]     callable: +call(tx, output_index, ctx) → value|nil+
+      # @param debug             [Boolean]   enable debug logging via +BSV.logger+
+      # @param history_cache     [Hash, nil] optional cache store (+[]/[]=+ responder)
+      # @param interpreter_version [String]  version tag for cache key invalidation
+      # @param ctx_key_fn        [#call, nil] serialises context to a string cache key
+      def initialize(interpreter, debug: false, history_cache: nil, interpreter_version: 'v1', ctx_key_fn: nil)
+        @interpreter = interpreter
+        @debug = debug
+        @history_cache = history_cache
+        @interpreter_version = interpreter_version
+        @ctx_key_fn = ctx_key_fn
+      end
+
+      # Traverses input ancestry from +start_transaction+ and returns all interpreted
+      # values in chronological order (oldest first).
+      #
+      # @param start_transaction [Transaction::Tx]
+      # @param context           [Object, nil] forwarded verbatim to the interpreter
+      # @return [Array] interpreted values, oldest first
+      def build_history(start_transaction, context = nil)
+        if @history_cache
+          key = cache_key(start_transaction, context)
+          cached = @history_cache[key]
+          unless cached.nil?
+            BSV.logger&.debug { "[Historian] History cache hit: #{key}" } if @debug
+            return cached.dup
+          end
+        end
+
+        history = []
+        visited = {}
+
+        traverse(start_transaction, context, history, visited)
+
+        result = history.reverse
+
+        if @history_cache
+          key ||= cache_key(start_transaction, context)
+          @history_cache[key] = result.dup.freeze
+          BSV.logger&.debug { "[Historian] History cached: #{key}" } if @debug
+        end
+
+        result
+      end
+
+      private
+
+      def cache_key(tx, context)
+        ctx_key = @ctx_key_fn ? @ctx_key_fn.call(context) : context.to_s
+        "#{@interpreter_version}|#{tx.dtxid_hex}|#{ctx_key}"
+      end
+
+      def traverse(tx, context, history, visited)
+        id = tx.wtxid
+
+        if visited.key?(id)
+          BSV.logger&.debug { "[Historian] Skipping already visited transaction: #{tx.dtxid_hex}" } if @debug
+          return
+        end
+
+        visited[id] = true
+
+        BSV.logger&.debug { "[Historian] Processing transaction: #{tx.dtxid_hex}" } if @debug
+
+        tx.outputs.each_with_index do |_output, index|
+          value = @interpreter.call(tx, index, context)
+          unless value.nil?
+            history << value
+            BSV.logger&.debug { "[Historian] Added value to history: #{value.inspect}" } if @debug
+          end
+        rescue StandardError => e
+          BSV.logger&.debug { "[Historian] Failed to interpret output #{index}: #{e.message}" } if @debug
+        end
+
+        tx.inputs.each do |input|
+          if input.source_transaction
+            traverse(input.source_transaction, context, history, visited)
+          elsif @debug
+            BSV.logger&.debug { '[Historian] Input missing sourceTransaction, skipping' }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -74,7 +74,7 @@ module BSV
 
       # Broadcast a transaction to all interested overlay hosts.
       #
-      # @param tx [BSV::Transaction::Tx] the transaction to broadcast
+      # @param tx [Transaction::Tx] the transaction to broadcast
       # @return [OverlayBroadcastResult]
       def broadcast(tx)
         beef = serialise_beef(tx)

data/lib/bsv/overlay.rb

@@ -25,5 +25,6 @@ module BSV
     autoload :HTTPSBroadcastFacilitator,  'bsv/overlay/broadcast_facilitator'
     autoload :TopicBroadcaster,           'bsv/overlay/topic_broadcaster'
     autoload :SHIPBroadcaster,            'bsv/overlay/topic_broadcaster'
+    autoload :Historian,                  'bsv/overlay/historian'
   end
 end