bsv-sdk 0.16.0 → 0.18.0

data/lib/bsv/network/provider.rb

@@ -22,17 +22,30 @@ module BSV
     #   result = gorillapool.call(:broadcast, tx)
     #   result.success?  # => true
     class Provider
-      attr_reader :name
+      attr_reader :name, :auth, :rate_limit
 
-      # @param name  [String] human-readable provider name (e.g. 'GorillaPool')
-      # @param block [Proc]   optional configuration block — yields +self+
-      def initialize(name, &block)
+      # @param name       [String]        human-readable provider name (e.g. 'GorillaPool')
+      # @param auth       [Hash, Symbol]  authentication config or +:none+ (default: +:none+).
+      #                                   An empty hash or +nil+ is treated as +:none+.
+      # @param rate_limit [Numeric, nil]  maximum requests per second (+nil+ = unlimited)
+      # @param block      [Proc]          optional configuration block — yields +self+
+      def initialize(name, auth: :none, rate_limit: nil, &block)
         @name           = name
+        @auth           = normalise_auth(auth)
+        @rate_limit     = rate_limit
         @protocols      = []
         @command_index  = {}
         block&.call(self)
       end
 
+      # Returns +true+ when the provider is configured with authentication
+      # credentials (i.e. +auth+ is not +:none+ and not an empty hash).
+      #
+      # @return [Boolean]
+      def authenticated?
+        @auth != :none
+      end
+
       # Registers a protocol class with the provider.
       #
       # The class is instantiated with the supplied +kwargs+. Its commands are
@@ -100,7 +113,9 @@ module BSV
       # @return [String]
       def to_s
         protocol_summary = @protocols.map { |p| p.class.name&.split('::')&.last || p.class.to_s }.join(', ')
-        "#<#{self.class} name=#{@name.inspect} protocols=[#{protocol_summary}]>"
+        auth_status      = authenticated? ? 'authenticated' : 'unauthenticated'
+        rate_part        = @rate_limit.nil? ? '' : " rate_limit=#{@rate_limit}"
+        "#<#{self.class} name=#{@name.inspect} auth=#{auth_status}#{rate_part} protocols=[#{protocol_summary}]>"
       end
       alias inspect to_s
 
@@ -118,6 +133,22 @@ module BSV
 
         instance.call(sym, *args, **kwargs)
       end
+
+      private
+
+      # Normalises the +auth+ argument so that +nil+ and empty hashes are
+      # stored as +:none+, giving a single canonical sentinel value for
+      # "no authentication".
+      #
+      # @param auth [Hash, Symbol, nil]
+      # @return [Hash, Symbol]
+      def normalise_auth(auth)
+        return :none if auth.nil?
+        return :none if auth == :none
+        return :none if auth.is_a?(Hash) && (auth.empty? || (auth[:bearer].nil? && auth[:api_key].nil?))
+
+        auth
+      end
     end
   end
 end

data/lib/bsv/network/providers/gorilla_pool.rb

@@ -4,56 +4,78 @@ module BSV
   module Network
     module Providers
       # GorillaPool returns pre-configured Provider instances using the GorillaPool
-      # ARCADE infrastructure for ARC and Chaintracks, and the GorillaPool Ordinals
-      # API for transaction and merkle path lookups.
+      # ARCADE infrastructure for ARC and Chaintracks, the GorillaPool Ordinals
+      # API for transaction and merkle path lookups, and JungleBus for indexed
+      # transaction data and block headers.
       #
-      # Mainnet composes three protocols:
+      # Mainnet composes four protocols:
       # - ARC at +https://arcade.gorillapool.io+
       # - Chaintracks at +https://arcade.gorillapool.io+
       # - Ordinals at +https://ordinals.gorillapool.io+
+      # - JungleBus at +https://junglebus.gorillapool.io+
       #
-      # Testnet provides ARC only at +https://testnet.arcade.gorillapool.io+.
+      # Testnet provides ARC and Chaintracks at +https://testnet.arcade.gorillapool.io+.
       #
       # == Example
       #
       #   provider = BSV::Network::Providers::GorillaPool.mainnet
       #   provider.call(:broadcast, tx)
       #
-      #   provider = BSV::Network::Providers::GorillaPool.testnet(api_key: 'my-key')
+      #   provider = BSV::Network::Providers::GorillaPool.mainnet(auth: { bearer: 'token' })
       #   provider.call(:broadcast, tx)
+      #
+      #   # Legacy api_key: shorthand — still supported
+      #   provider = BSV::Network::Providers::GorillaPool.testnet(api_key: 'my-key')
       class GorillaPool
-        # Returns a mainnet Provider configured with ARC, Chaintracks, and Ordinals.
+        # Default requests-per-second limit for unauthenticated use.
+        DEFAULT_RATE_LIMIT = 3
+
+        # Returns a mainnet Provider configured with ARC, Chaintracks, Ordinals, and JungleBus.
+        #
+        # Auth is forwarded to all four protocols so each can authenticate independently.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.mainnet(**opts)
-          common = opts.slice(:api_key, :http_client)
-          Provider.new('GorillaPool') do |p|
-            p.protocol Protocols::ARC,         base_url: 'https://arcade.gorillapool.io', **opts
+        def self.mainnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          common = opts.slice(:api_key, :http_client).merge(auth: auth)
+          Provider.new('GorillaPool', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC,         base_url: 'https://arcade.gorillapool.io', auth: auth, **opts
             p.protocol Protocols::Chaintracks, base_url: 'https://arcade.gorillapool.io', **common
             p.protocol Protocols::Ordinals,    base_url: 'https://ordinals.gorillapool.io', **common
+            p.protocol Protocols::JungleBus,   base_url: 'https://junglebus.gorillapool.io', **common
           end
         end
 
         # Returns a testnet Provider configured with ARC and Chaintracks.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # Auth is forwarded to both protocols.
+        #
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.testnet(**opts)
-          common = opts.slice(:api_key, :http_client)
-          Provider.new('GorillaPool') do |p|
-            p.protocol Protocols::ARC,         base_url: 'https://testnet.arcade.gorillapool.io', **opts
+        def self.testnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          common = opts.slice(:api_key, :http_client).merge(auth: auth)
+          Provider.new('GorillaPool', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC,         base_url: 'https://testnet.arcade.gorillapool.io', auth: auth, **opts
             p.protocol Protocols::Chaintracks, base_url: 'https://testnet.arcade.gorillapool.io', **common
           end
         end
 
         # Returns a mainnet or testnet Provider depending on the +testnet:+ flag.
         #
-        # @param testnet [Boolean] when true, returns the testnet Provider
-        # @param opts    [Hash]    keyword arguments forwarded to each protocol constructor
+        # @param testnet    [Boolean] when true, returns the testnet Provider
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.default(testnet: false, **opts)
-          testnet ? testnet(**opts) : mainnet(**opts)
+        def self.default(testnet: false, auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          kwargs = { auth: auth, rate_limit: rate_limit, **opts }
+          testnet ? testnet(**kwargs) : mainnet(**kwargs)
         end
       end
     end

data/lib/bsv/network/providers/taal.rb

@@ -14,42 +14,65 @@ module BSV
       # To use TAALBinary directly, call +provider.protocol_for(:broadcast)+ on the
       # TAALBinary instance via +provider.protocols.last+, or build a custom Provider.
       #
+      # TAAL requires an API key for production use. The default rate limit is +nil+
+      # (unconstrained) because the effective limit depends on the subscription tier.
+      #
       # There is no TAAL testnet default — TAAL does not publish a supported testnet ARC URL.
       #
       # == Example
       #
-      #   provider = BSV::Network::Providers::TAAL.mainnet(api_key: 'mainnet_...')
+      #   provider = BSV::Network::Providers::TAAL.mainnet(auth: { bearer: 'mainnet_...' })
       #   provider.call(:broadcast, tx)
+      #
+      #   # Legacy api_key: shorthand — still supported
+      #   provider = BSV::Network::Providers::TAAL.mainnet(api_key: 'mainnet_...')
       class TAAL
+        # Default requests-per-second limit.
+        # +nil+ because the effective limit depends on the TAAL subscription tier.
+        DEFAULT_RATE_LIMIT = nil
+
         # Returns a mainnet Provider configured with ARC and TAALBinary.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # Auth is forwarded to both protocols. ARC uses Bearer tokens;
+        # TAALBinary uses raw API keys. Each protocol's constructor handles
+        # the translation appropriate to its endpoint.
+        #
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+ (nil)
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.mainnet(**opts)
-          common = opts.slice(:api_key, :http_client)
-          Provider.new('TAAL') do |p|
-            p.protocol Protocols::ARC, base_url: 'https://arc.taal.com', **opts
-            p.protocol Protocols::TAALBinary, base_url: 'https://api.taal.com', **common
+        def self.mainnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          common = opts.slice(:api_key, :http_client).merge(auth: auth)
+          Provider.new('TAAL', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC,        base_url: 'https://arc.taal.com',  auth: auth, **opts
+            p.protocol Protocols::TAALBinary, base_url: 'https://api.taal.com',  **common
           end
         end
 
         # Returns a testnet Provider configured with ARC only.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and ARC protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+ (nil)
+        # @param opts       [Hash] keyword arguments forwarded to the ARC protocol constructor
         # @return [Provider]
-        def self.testnet(**opts)
-          Provider.new('TAAL') do |p|
-            p.protocol Protocols::ARC, base_url: 'https://arc-test.taal.com', **opts
+        def self.testnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { bearer: opts[:api_key] } : :none)
+          Provider.new('TAAL', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::ARC, base_url: 'https://arc-test.taal.com', auth: auth, **opts
           end
         end
 
         # Returns a mainnet or testnet Provider depending on the +testnet:+ flag.
         #
-        # @param testnet [Boolean] when true, returns the testnet Provider
-        # @param opts    [Hash]    keyword arguments forwarded to each protocol constructor
+        # @param testnet    [Boolean] when true, returns the testnet Provider
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and all protocols
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+ (nil)
+        # @param opts       [Hash] keyword arguments forwarded to each protocol constructor
         # @return [Provider]
-        def self.default(testnet: false, **opts)
-          testnet ? testnet(**opts) : mainnet(**opts)
+        def self.default(testnet: false, auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          kwargs = { auth: auth, rate_limit: rate_limit, **opts }
+          testnet ? testnet(**kwargs) : mainnet(**kwargs)
         end
       end
     end

data/lib/bsv/network/providers/whats_on_chain.rb

@@ -15,55 +15,76 @@ module BSV
       #   provider = BSV::Network::Providers::WhatsOnChain.mainnet
       #   provider.call(:get_tx, 'abc123...')
       #
-      #   provider = BSV::Network::Providers::WhatsOnChain.testnet(api_key: 'my-key')
+      #   provider = BSV::Network::Providers::WhatsOnChain.mainnet(auth: { api_key: 'my-key' })
       #   provider.call(:broadcast, tx)
+      #
+      #   # Legacy api_key: shorthand — still supported
+      #   provider = BSV::Network::Providers::WhatsOnChain.testnet(api_key: 'my-key')
       class WhatsOnChain
+        # Default requests-per-second limit for unauthenticated use.
+        DEFAULT_RATE_LIMIT = 3
+
         # Returns a mainnet Provider configured with WoCREST.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST protocol constructor
         # @return [Provider]
-        def self.mainnet(**opts)
-          Provider.new('WhatsOnChain') do |p|
-            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/main', **opts
+        def self.mainnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { api_key: opts[:api_key] } : :none)
+          Provider.new('WhatsOnChain', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/main',
+                                           auth: auth, **opts
           end
         end
 
         # Returns a testnet Provider configured with WoCREST.
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST protocol constructor
         # @return [Provider]
-        def self.testnet(**opts)
-          Provider.new('WhatsOnChain') do |p|
-            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/test', **opts
+        def self.testnet(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { api_key: opts[:api_key] } : :none)
+          Provider.new('WhatsOnChain', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/test',
+                                           auth: auth, **opts
           end
         end
 
         # Returns a Provider for the BSV Scaling Test Network (STN).
         #
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST protocol constructor
         # @return [Provider]
-        def self.stn(**opts)
-          Provider.new('WhatsOnChain') do |p|
-            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/stn', **opts
+        def self.stn(auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          resolved_auth = auth || (opts[:api_key] ? { api_key: opts[:api_key] } : :none)
+          Provider.new('WhatsOnChain', auth: resolved_auth, rate_limit: rate_limit) do |p|
+            p.protocol Protocols::WoCREST, base_url: 'https://api.whatsonchain.com/v1/bsv/stn',
+                                           auth: auth, **opts
           end
         end
 
         # Returns a Provider for the given network.
         #
-        # @param testnet [Boolean] when true, returns the testnet Provider
-        # @param network [Symbol, nil] explicit network (:main, :test, :stn) — overrides +testnet:+
-        # @param opts [Hash] keyword arguments forwarded to each protocol constructor
+        # @param testnet    [Boolean] when true, returns the testnet Provider
+        # @param network    [Symbol, nil] explicit network (:main, :test, :stn) — overrides +testnet:+
+        # @param auth       [Hash, Symbol, nil] auth config forwarded to Provider and WoCREST protocol
+        # @param rate_limit [Numeric, nil] requests per second; defaults to +DEFAULT_RATE_LIMIT+
+        # @param opts       [Hash] keyword arguments forwarded to the WoCREST protocol constructor
         # @return [Provider]
-        def self.default(testnet: false, network: nil, **opts)
+        def self.default(testnet: false, network: nil, auth: nil, rate_limit: DEFAULT_RATE_LIMIT, **opts)
+          kwargs = { auth: auth, rate_limit: rate_limit, **opts }
           if network
             case network.to_sym
-            when :main, :mainnet then mainnet(**opts)
-            when :test, :testnet then testnet(**opts)
-            when :stn then stn(**opts)
+            when :main, :mainnet then mainnet(**kwargs)
+            when :test, :testnet then testnet(**kwargs)
+            when :stn then stn(**kwargs)
             else raise ArgumentError, "unknown network: #{network}"
             end
           else
-            testnet ? testnet(**opts) : mainnet(**opts)
+            testnet ? testnet(**kwargs) : mainnet(**kwargs)
           end
         end
       end

data/lib/bsv/network/utxo.rb

@@ -5,10 +5,16 @@ module BSV
     class UTXO
       attr_reader :tx_hash, :tx_pos, :satoshis, :height
 
-      def initialize(tx_hash:, tx_pos:, satoshis:, height: nil)
+      # @param tx_hash  [String]  transaction ID
+      # @param tx_pos   [Integer] output index
+      # @param satoshis [Integer] output value in satoshis (accepts +value+ as alias)
+      # @param height   [Integer, nil] block height (0 or nil = unconfirmed)
+      def initialize(tx_hash:, tx_pos:, satoshis: nil, value: nil, height: nil)
         @tx_hash = tx_hash
         @tx_pos = tx_pos
-        @satoshis = satoshis
+        @satoshis = satoshis || value
+        raise ArgumentError, 'satoshis or value is required' if @satoshis.nil?
+
         @height = height
       end
 

data/lib/bsv/overlay/lookup_resolver.rb

@@ -203,7 +203,7 @@ module BSV
 
         # Get the last (subject) transaction — typically the most recent entry
         beef_tx = beef.transactions.last
-        return nil unless beef_tx&.transaction
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
         tx     = beef_tx.transaction
         txout  = tx.outputs[output_index]
@@ -334,16 +334,17 @@ module BSV
         beef_data    = output['beef'] || output[:beef]
         output_index = (output['outputIndex'] || output[:output_index] || 0).to_i
 
-        txid =
+        # Overlay API boundary: outpoint key uses display-order hex txid
+        dtxid_hex =
           begin
             beef = parse_beef(beef_data)
             last = beef&.transactions&.last
-            last&.transaction&.txid
+            last&.dtxid
           rescue StandardError
             nil
           end
 
-        txid ? "#{txid}.#{output_index}" : output.object_id.to_s
+        dtxid_hex ? "#{dtxid_hex}.#{output_index}" : output.object_id.to_s
       end
 
       # ---- Validation ----

data/lib/bsv/overlay/topic_broadcaster.rb

@@ -110,7 +110,7 @@ module BSV
 
         OverlayBroadcastResult.new(
           status: 'success',
-          txid: tx.txid_hex,
+          txid: tx.txid_hex, # Overlay API boundary: display-order hex txid for the broadcast result
           message: "Sent to #{successful.size} Overlay Service host(s)."
         )
       end
@@ -199,7 +199,7 @@ module BSV
         return nil unless beef
 
         beef_tx = beef.transactions.last
-        return nil unless beef_tx&.transaction
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
         tx    = beef_tx.transaction
         txout = tx.outputs[output_index]

data/lib/bsv/overlay/types.rb

@@ -82,6 +82,7 @@ module BSV
       # @return [String] result status ('success' or 'error')
       attr_reader :status
 
+      # Overlay API boundary: display-order hex txid echoed from the broadcast response.
       # @return [String, nil] transaction identifier (present on success)
       attr_reader :txid
 
@@ -101,6 +102,7 @@ module BSV
       # @param description [String, nil]
       def initialize(status:, txid: nil, message: nil, code: nil, description: nil)
         @status = status
+        BSV::Primitives::Hex.validate_dtxid_hex!(txid, name: 'overlay broadcast txid') if txid
         @txid = txid
         @message = message
         @code = code

data/lib/bsv/primitives/hex.rb

@@ -72,6 +72,70 @@ module BSV
       def self.encode(bytes)
         bytes.unpack1('H*')
       end
+
+      # Validate that +value+ is a 32-byte wire-order transaction ID.
+      #
+      # @param value [String] expected 32-byte binary string
+      # @param name [String] label for the error message (e.g. +'prev_wtxid'+)
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 32-byte binary string
+      def self.validate_wtxid!(value, name: 'wtxid')
+        unless value.is_a?(String) && value.bytesize == 32
+          hint = if value.is_a?(String) && value.bytesize == 64 && value.match?(HEX_RE)
+                   ' (looks like a hex txid — use wtxid_from_hex to convert)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.bytesize}-byte string" : value.class.to_s
+          raise ArgumentError,
+                "expected 32-byte wire-order wtxid for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
+
+      # Validate that +value+ is a 32-byte binary hash.
+      #
+      # General-purpose validator for any 32-byte hash (merkle nodes, roots,
+      # etc.) — not specific to transaction IDs. For txid-specific validation
+      # use {.validate_wtxid!} or {.validate_dtxid_hex!} instead.
+      #
+      # @param value [String] expected 32-byte binary string
+      # @param name [String] label for the error message
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 32-byte binary string
+      def self.validate_hash32!(value, name: 'hash')
+        unless value.is_a?(String) && value.bytesize == 32
+          hint = if value.is_a?(String) && value.bytesize == 64 && value.match?(HEX_RE)
+                   ' (looks like hex — decode it first)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.bytesize}-byte string" : value.class.to_s
+          raise ArgumentError,
+                "expected 32-byte hash for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
+
+      # Validate that +value+ is a 64-character display-order hex transaction ID.
+      #
+      # @param value [String] expected 64-char hex string
+      # @param name [String] label for the error message (e.g. +'dtxid_hex'+)
+      # @return [String] the input value (pass-through for chaining)
+      # @raise [ArgumentError] if +value+ is not a 64-char hex string
+      def self.validate_dtxid_hex!(value, name: 'dtxid_hex')
+        unless value.is_a?(String) && value.length == 64 && value.match?(HEX_RE)
+          hint = if value.is_a?(String) && value.bytesize == 32 && !value.match?(HEX_RE)
+                   ' (looks like binary bytes — use dtxid_hex or unpack to convert)'
+                 else
+                   ''
+                 end
+          size = value.is_a?(String) ? "#{value.length}-char string" : value.class.to_s
+          raise ArgumentError,
+                "expected 64-char display-order hex for #{name}, got #{size}#{hint}"
+        end
+        value
+      end
     end
   end
 end

data/lib/bsv/registry/client.rb

@@ -155,6 +155,7 @@ module BSV
         verify_ownership(registered_definition)
 
         definition_type = registered_definition.definition_type
+        # Registry API boundary: outpoint uses display-order hex txid from RegisteredDefinition
         outpoint = "#{registered_definition.txid}.#{registered_definition.output_index}"
 
         create_result = @wallet.create_action(
@@ -405,21 +406,21 @@ module BSV
         return nil if output_idx.negative? || beef_raw.nil?
 
         beef = BSV::Transaction::Beef.from_binary(beef_raw)
-        tx   = beef.transactions.last&.transaction
-        return nil unless tx
+        beef_tx = beef.transactions.last
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
-        locking_script = tx.outputs[output_idx]&.locking_script
+        locking_script = beef_tx.transaction.outputs[output_idx]&.locking_script
         return nil unless locking_script
 
         definition_data = parse_locking_script(definition_type, locking_script)
 
         RegisteredDefinition.new(
           definition_data: definition_data,
-          txid: tx.txid_hex,
+          txid: beef_tx.transaction.txid_hex, # Registry API boundary: display-order hex txid
           output_index: output_idx,
           locking_script: locking_script.to_hex,
           beef: beef_raw,
-          satoshis: tx.outputs[output_idx].satoshis
+          satoshis: beef_tx.transaction.outputs[output_idx].satoshis
         )
       end
 
@@ -434,13 +435,14 @@ module BSV
         outpoint_str = output[:outpoint] || output['outpoint']
         return nil unless outpoint_str
 
+        # Registry API boundary: outpoint string uses display-order hex txid by convention
         txid, output_idx_str = outpoint_str.split('.')
         output_idx = output_idx_str.to_i
 
-        tx = beef.transactions.last&.transaction
-        return nil unless tx
+        beef_tx = beef.transactions.last
+        return nil if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
 
-        locking_script = tx.outputs[output_idx]&.locking_script
+        locking_script = beef_tx.transaction.outputs[output_idx]&.locking_script
         return nil unless locking_script
 
         definition_data = parse_locking_script(definition_type, locking_script)

data/lib/bsv/registry/types.rb

@@ -188,6 +188,7 @@ module BSV
       # @return [String] the definition type (see {DefinitionType})
       attr_reader :definition_type
 
+      # Registry API boundary: display-order hex txid from the outpoint string held in the registry token.
       # @return [String] transaction ID of the containing UTXO
       attr_reader :txid
 
@@ -216,6 +217,7 @@ module BSV
       def initialize(definition_data:, txid:, output_index:, locking_script:, beef:, satoshis: 1)
         @definition_data = definition_data
         @definition_type = definition_data.definition_type
+        BSV::Primitives::Hex.validate_dtxid_hex!(txid, name: 'registry definition txid')
         @txid            = txid
         @output_index    = output_index
         @locking_script  = locking_script

data/lib/bsv/script/interpreter/interpreter.rb

@@ -89,10 +89,12 @@ module BSV
 
       def execute
         scripts = [@unlock_script, @lock_script]
+        script_names = %w[unlock_script lock_script]
 
         scripts.each_with_index do |script, script_idx|
           @current_script = script
           chunks = script.chunks
+          BSV.logger&.debug { "[Interpreter] === #{script_names[script_idx]} (#{chunks.length} chunks) ===" }
 
           chunks.each_with_index do |chunk, chunk_idx|
             @current_chunk_idx = chunk_idx
@@ -115,6 +117,7 @@ module BSV
         end
 
         check_final_stack
+        BSV.logger&.debug { "[Interpreter] final stack: #{@dstack.length} items -> success" }
         true
       end
 
@@ -156,6 +159,10 @@ module BSV
           return
         end
 
+        BSV.logger&.debug do
+          name = Opcodes.name_for(opcode) || format('0x%02x', opcode)
+          "[Interpreter]   #{name} (stack: #{@dstack.length})"
+        end
         dispatch_opcode(opcode, chunk)
       end
 

data/lib/bsv/script/interpreter/operations/crypto.rb

@@ -126,7 +126,13 @@ module BSV
 
             pubkey = BSV::Primitives::PublicKey.from_bytes(pubkey_bytes)
             hash = @tx.sighash(@input_index, sighash_type, subscript: sub_script)
-            pubkey.verify(hash, sig)
+            result = pubkey.verify(hash, sig)
+            BSV.logger&.debug do
+              pk_hex = pubkey_bytes.unpack1('H*')
+              "[Interpreter] CHECKSIG: sighash_type=0x#{format('%02x', sighash_type)} " \
+                "pubkey=#{pk_hex[0, 8]}...#{pk_hex[-4..]} result=#{result}"
+            end
+            result
           rescue ArgumentError
             false
           end