bsv-sdk 0.23.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce9ccc589a407c6ad98d92e40b9ac05925f3fbf32cc73aa235b9fd9a35b7ad43
-  data.tar.gz: 46992e9ea4f2465c4ca80ad2bb84e2591426610b46d1eea72e11171efdc271bf
+  metadata.gz: 9a0dbc7f524004e1db715058dd17d336e62f99687239ec4c7807512d730e6ef5
+  data.tar.gz: 45b1fc354cbfe718a38e01c0d4896d537600d188bba909f351da1bc17bac66c6
 SHA512:
-  metadata.gz: ac7da8fbd4e5cb9e0385bb3035dc34d44460232afe826b095d19cccc04faece15cd090045c49d7d176f68d7ba98b5a16105812c66ae8ac27d657df8682b8c499
-  data.tar.gz: 1b6946dd9762ac777aa8d1fff4392c96e30cfabd5c6b14f3eba7a8997e7ef0f8d5eca86383c131dfb479ce7f6ac94b7049bc50490edde5b0ff6b6994d8392629
+  metadata.gz: 6e212bf3c077ab32a6d5187c0e3cbd93fd61f26844d40dce31b28c0574a1111db3a081dd0d843be90dc682779ede74ece03f0f7eccc0eec930a372306cdc3ca2
+  data.tar.gz: ec1e1b2e0c7b5ae142b52cb1863000fd262d0c1dc30346c2a7d412af2e1f66cbc3057c864bc9d6229737be59c30eae2eaf6d7fee7c296a9393c6e0f8b636b558

data/CHANGELOG.md

@@ -5,6 +5,85 @@ 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.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
+- **`BSV::Transaction::Transaction` renamed to `BSV::Transaction::Tx`** (#795). Class only;
+  module `BSV::Transaction` and peer classes (`TransactionInput`, `TransactionOutput`,
+  `ChainTracker`, `Beef`, etc.) unchanged. No compat alias — pre-1.0 clean break.
+  Downstream consumers update with `s/BSV::Transaction::Transaction/BSV::Transaction::Tx/g`.
+- **`BSV::Wallet::WalletWireTransceiver` pubkey results are now 66-char hex** (#798),
+  matching the BRC-100 `PubKeyHex` contract and `ProtoWallet`'s direct-call shape.
+  Affects `get_public_key`, `reveal_counterparty_key_linkage`, `reveal_specific_key_linkage`.
+  Wire bytes remain 33-byte compressed binary; only the deserialised Ruby return shape
+  changed. See ADR-001 for the rationale.
+- **`BSV::Identity::Client` and `BSV::Registry::Client` raise `BSV::Overlay::OverlayError`
+  subclasses on overlay broadcast failure** (#802) — `publicly_reveal_attributes`,
+  `revoke_certificate_revelation`, `register_definition`, `sign_and_broadcast` previously
+  returned a result hash and required callers to inspect `status` themselves.
+
+### Added
+- `BSV::Wallet::ProtoWallet::KeyDeriver#identity_key_bytes` — binary accessor for the
+  identity pubkey, alongside the hex `identity_key`. Mirrors the planned bsv-wallet
+  KeyDeriver shape.
+- `BSV::Overlay::OverlayBroadcastResult#success?` and `#raise_if_error!` — let callers
+  treat broadcast failure as an exception with the appropriate `OverlayError` subclass.
+- ADR-001 documenting the SDK's binary-internal rule and the public-key hex exception
+  (`docs/guides/wtxid-dtxid.md` extension + `.architecture/decisions/adrs/ADR-001-…`).
+
+### Fixed
+- `BSV::Network::Util.resolve_tx_hex` rejects empty input rather than silently producing
+  an empty `rawTx` broadcast (#799).
+- `BSV::Network::Protocol#default_call` converts transport-level exceptions
+  (`SocketError`, `Errno::ECONNREFUSED`, `Net::OpenTimeout`, `OpenSSL::SSL::SSLError`,
+  etc.) into structured `ProtocolResponse` with `http_success: false` and descriptive
+  `error_message`, rather than propagating raw exceptions to callers (#807).
+- `BSV::Auth::AuthPayload.serialize_request` raises `ArgumentError` for `request_nonce`
+  that isn't exactly 32 bytes, preventing malformed BRC-103 wire frames (#800).
+- `BSV::MCP::Tools::BroadcastP2pkh` rescues `StandardError` rather than just
+  `ArgumentError`, so non-`ArgumentError` exceptions from invalid WIF input (e.g.
+  `NoMethodError` on `nil`) return a structured MCP error instead of crashing the tool
+  handler (#801).
+- `BSV::Wallet::ProtoWallet#create_signature` / `#verify_signature` and matching wire
+  serialisers validate that `hash_to_directly_sign` / `hash_to_directly_verify` are
+  exactly 32 bytes, preventing malformed signatures (#805).
+- `BSV::Attest.verify` asserts that the provider's `fetch_transaction` returns a Tx-like
+  object before iterating, producing a clear `ArgumentError` instead of a low-signal
+  `NoMethodError` (#803).
+
+### Changed
+- Bitcoin Core script-vectors spec now enforces a bidirectional regression gate:
+  previously-failing vectors that now pass surface as failures so `known_failures.json`
+  stays honest. Cleaned out 101 stale entries (#806).
+
 ## 0.23.1 — 2026-06-06
 
 ### Fixed

data/README.md

@@ -86,7 +86,7 @@ pubkey_hash = priv_key.public_key.hash160
 locking_script = BSV::Script::Script.p2pkh_lock(pubkey_hash)
 
 # Create a transaction spending a UTXO
-tx = BSV::Transaction::Transaction.new
+tx = BSV::Transaction::Tx.new
 
 # Add an input referencing a previous transaction output
 input = BSV::Transaction::TransactionInput.new(

data/lib/bsv/auth/auth_payload.rb

@@ -34,6 +34,11 @@ module BSV
       # @param body [String, nil] request body bytes; nil encodes as ABSENT
       # @return [String] binary payload (ASCII-8BIT encoding)
       def serialize_request(request_nonce:, method:, path:, query:, headers:, body:)
+        unless request_nonce.is_a?(String) && request_nonce.bytesize == 32
+          got = request_nonce.respond_to?(:bytesize) ? "#{request_nonce.class}/#{request_nonce.bytesize}" : request_nonce.class
+          raise ArgumentError, "request_nonce must be a 32-byte binary string, got #{got}"
+        end
+
         buf = ''.b
 
         # 32-byte request nonce — written raw, no length prefix

data/lib/bsv/identity/client.rb

@@ -107,6 +107,8 @@ module BSV
       # @return [BSV::Overlay::OverlayBroadcastResult]
       # @raise [ArgumentError] if the certificate has no fields or fields_to_reveal is empty
       # @raise [RuntimeError] if certificate verification fails or create_action returns no tx
+      # @raise [BSV::Overlay::OverlayError] (or a subclass) if the overlay broadcast fails —
+      #   see {BSV::Overlay::OverlayBroadcastResult#raise_if_error!} for the mapping
       def publicly_reveal_attributes(certificate, fields_to_reveal:)
         fields = certificate[:fields] || certificate['fields'] || {}
         raise ArgumentError, 'Public reveal failed: Certificate has no fields to reveal!' if fields.empty?
@@ -169,8 +171,8 @@ module BSV
 
         raise 'Public reveal failed: failed to create action!' if create_result[:tx].nil?
 
-        tx = BSV::Transaction::Transaction.from_beef(create_result[:tx])
-        broadcaster_for_action.broadcast(tx)
+        tx = BSV::Transaction::Tx.from_beef(create_result[:tx])
+        broadcaster_for_action.broadcast(tx).raise_if_error!
       end
 
       # Revokes a publicly revealed certificate by spending the identity token.
@@ -182,6 +184,8 @@ module BSV
       # @param serial_number [String] Base64 serial number of the certificate revelation to revoke
       # @return [void]
       # @raise [RuntimeError] if the revelation cannot be found or the transaction cannot be created
+      # @raise [BSV::Overlay::OverlayError] (or a subclass) if the overlay broadcast fails —
+      #   see {BSV::Overlay::OverlayBroadcastResult#raise_if_error!} for the mapping
       def revoke_certificate_revelation(serial_number)
         question = BSV::Overlay::LookupQuestion.new(
           service: Constants::SERVICE,
@@ -232,7 +236,7 @@ module BSV
         raise 'Revoke failed: failed to create signable transaction' if create_result[:signable_transaction].nil?
 
         signable = create_result[:signable_transaction]
-        partial_tx = BSV::Transaction::Transaction.from_beef(signable[:tx])
+        partial_tx = BSV::Transaction::Tx.from_beef(signable[:tx])
 
         # Unlock via PushDrop
         template = BSV::Script::PushDropTemplate.new(wallet: @wallet, originator: @originator)
@@ -255,8 +259,8 @@ module BSV
 
         raise 'Revoke failed: failed to sign transaction' if sign_result[:tx].nil?
 
-        signed_tx = BSV::Transaction::Transaction.from_beef(sign_result[:tx])
-        broadcaster_for_action.broadcast(signed_tx)
+        signed_tx = BSV::Transaction::Tx.from_beef(sign_result[:tx])
+        broadcaster_for_action.broadcast(signed_tx).raise_if_error!
       end
 
       private

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/broadcast_p2pkh.rb

@@ -127,7 +127,10 @@ module BSV
             [::MCP::Content::Text.new(result.to_json)],
             structured_content: result
           )
-        rescue ArgumentError => e
+        rescue StandardError => e
+          # Catch broadly so MCP returns a structured error rather than
+          # crashing the tool handler on unexpected exception types
+          # (e.g. NoMethodError on nil WIF input, encoding errors, etc.).
           Helpers.error_response(e.message)
         end
 
@@ -150,7 +153,7 @@ module BSV
         # Build, fee-compute, and sign the transaction.
         # @api private
         def self.build_transaction(selected_utxos, satoshis, to_address, sender_address, private_key)
-          tx = BSV::Transaction::Transaction.new
+          tx = BSV::Transaction::Tx.new
 
           # Wire inputs with EF metadata (source_satoshis + source_locking_script)
           selected_utxos.each do |utxo|

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

@@ -48,7 +48,7 @@ module BSV
         )
 
         def self.call(hex:, **)
-          tx = BSV::Transaction::Transaction.from_hex(hex)
+          tx = BSV::Transaction::Tx.from_hex(hex)
           result = Helpers.transaction_to_h(tx)
 
           ::MCP::Tool::Response.new(

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

@@ -59,7 +59,7 @@ module BSV
             return Helpers.error_response(msg)
           end
 
-          tx = BSV::Transaction::Transaction.from_hex(fetch_result.data)
+          tx = BSV::Transaction::Tx.from_hex(fetch_result.data)
 
           result = {
             hex: tx.to_hex,

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::Transaction]
+        # @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/network/protocol.rb

@@ -2,6 +2,7 @@
 
 require 'net/http'
 require 'json'
+require 'openssl'
 require 'uri'
 
 module BSV
@@ -179,7 +180,17 @@ module BSV
 
         BSV.logger&.debug { "[Protocol] #{defn[:method].upcase} #{uri}" }
 
-        response = execute(uri, request)
+        begin
+          response = execute(uri, request)
+        rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+               Errno::EHOSTUNREACH, Errno::ENETUNREACH,
+               Net::OpenTimeout, Net::ReadTimeout,
+               Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+               OpenSSL::SSL::SSLError => e
+          BSV.logger&.debug { "[Protocol] transport error: #{e.class}: #{e.message}" }
+          return ProtocolResponse.new(nil, http_success: false,
+                                           error_message: "transport error: #{e.class}: #{e.message}")
+        end
 
         build_response(response, defn[:response])
       end

data/lib/bsv/network/util.rb

@@ -25,19 +25,27 @@ module BSV
       # length and contains only hex characters. This handles hex strings
       # tagged as ASCII-8BIT (e.g. read from IO in binary mode).
       #
+      # Empty input is rejected — an empty transaction cannot meaningfully
+      # be broadcast and any downstream `rawTx: ''` body is a sign of a
+      # caller bug, not valid traffic.
+      #
       # @param tx [String, #to_ef_hex, #to_hex] transaction in any supported form
       # @return [String] hex-encoded transaction
+      # @raise [ArgumentError] if `tx` is an empty string
       def self.resolve_tx_hex(tx)
         if tx.is_a?(String)
-          return tx if tx.match?(/\A[0-9a-fA-F]*\z/) && tx.length.even?
+          raise ArgumentError, 'tx cannot be empty — refusing to construct an empty broadcast' if tx.empty?
+          return tx if tx.match?(/\A[0-9a-fA-F]+\z/) && tx.length.even?
 
           return tx.unpack1('H*')
         end
 
-        tx.to_ef_hex
-      rescue ArgumentError => e
-        BSV.logger&.debug { "[Network::Util] EF serialisation failed: #{e.message} — falling back to raw hex" }
-        tx.to_hex
+        begin
+          tx.to_ef_hex
+        rescue ArgumentError => e
+          BSV.logger&.debug { "[Network::Util] EF serialisation failed: #{e.message} — falling back to raw hex" }
+          tx.to_hex
+        end
       end
     end
   end

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::Transaction] 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::Transaction] unused
+        # @param _tx [Transaction::Tx] unused
         # @param _input_index [Integer] unused
         # @return [Integer]
         def estimated_length(_tx, _input_index)