bsv-sdk 0.23.1 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce9ccc589a407c6ad98d92e40b9ac05925f3fbf32cc73aa235b9fd9a35b7ad43
-  data.tar.gz: 46992e9ea4f2465c4ca80ad2bb84e2591426610b46d1eea72e11171efdc271bf
+  metadata.gz: ac0ee4456475effef9fa92627f77e4b973cfe834efda2f936725074c35060f95
+  data.tar.gz: acd91340c476db84531efd41003ea068e3b5029cbb63e74bab782d17b48694d5
 SHA512:
-  metadata.gz: ac7da8fbd4e5cb9e0385bb3035dc34d44460232afe826b095d19cccc04faece15cd090045c49d7d176f68d7ba98b5a16105812c66ae8ac27d657df8682b8c499
-  data.tar.gz: 1b6946dd9762ac777aa8d1fff4392c96e30cfabd5c6b14f3eba7a8997e7ef0f8d5eca86383c131dfb479ce7f6ac94b7049bc50490edde5b0ff6b6994d8392629
+  metadata.gz: 02fffbfda10161282e87c26d8be157377a3b3861830b2891fe1331a3ea4b51e2743bc707fd01c8f3b1a5921173037d70322259c3d8dda39ea7caeffd2ee3cfd5
+  data.tar.gz: 0b4d5dea8e5b447d98603150a8873f14f8e24b7b75377fa5baa43bf497fedb62c11865ccc96eb15f78c49323987b896290955b483169dec065a307f468f3e584

data/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.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/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 [BSV::Transaction::Tx]
         # @return [Hash]
         def self.transaction_to_h(tx)
           {

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

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::Transaction] the transaction to broadcast
+      # @param tx [BSV::Transaction::Tx] the transaction to broadcast
       # @return [OverlayBroadcastResult]
       def broadcast(tx)
         beef = serialise_beef(tx)

data/lib/bsv/overlay/types.rb

@@ -108,6 +108,43 @@ module BSV
         @code = code
         @description = description
       end
+
+      # @return [Boolean] true when the broadcast reached at least one
+      #   competent host and satisfied any acknowledgement requirements.
+      def success?
+        @status == 'success'
+      end
+
+      # Raise the appropriate {OverlayError} subclass when {#success?} is
+      # false. Lets callers treat a broadcast failure as an exception rather
+      # than silently swallowing the result object — used by Identity and
+      # Registry clients which terminate on broadcast failure regardless.
+      #
+      # @return [self] when the result is a success (chainable)
+      # @raise [NoCompetentHostsError] for +ERR_NO_HOSTS_INTERESTED+
+      # @raise [AllHostsRejectedError] for +ERR_ALL_HOSTS_REJECTED+
+      # @raise [AcknowledgementError] for +ERR_REQUIRE_ACK_*_FAILED+
+      # @raise [OverlayError] for any other non-success status
+      def raise_if_error!
+        return self if success?
+
+        message = [@code, @description].compact.join(': ')
+        raise error_class_for_code, message
+      end
+
+      private
+
+      def error_class_for_code
+        case @code
+        when 'ERR_NO_HOSTS_INTERESTED' then NoCompetentHostsError
+        when 'ERR_ALL_HOSTS_REJECTED' then AllHostsRejectedError
+        when 'ERR_REQUIRE_ACK_FROM_ANY_HOST_FAILED',
+             'ERR_REQUIRE_ACK_FROM_ALL_HOSTS_FAILED',
+             'ERR_REQUIRE_ACK_FROM_SPECIFIC_HOSTS_FAILED'
+          AcknowledgementError
+        else OverlayError
+        end
+      end
     end
   end
 end

data/lib/bsv/registry/client.rb

@@ -50,7 +50,9 @@ module BSV
       # @param data [BasketDefinitionData, ProtocolDefinitionData, CertificateDefinitionData]
       #   structured definition data
       # @return [BSV::Overlay::OverlayBroadcastResult]
-      # @raise [RuntimeError] if the transaction cannot be created or broadcast
+      # @raise [RuntimeError] if 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 register_definition(definition_type, data)
         registry_operator = identity_key
         fields = build_pushdrop_fields(definition_type, data, registry_operator)
@@ -81,8 +83,8 @@ module BSV
 
         raise "Register failed: could not create #{definition_type} registration transaction" if create_result[:tx].nil?
 
-        tx = BSV::Transaction::Transaction.from_beef(normalise_beef(create_result[:tx]))
-        broadcaster_for(definition_type).broadcast(tx)
+        tx = BSV::Transaction::Tx.from_beef(normalise_beef(create_result[:tx]))
+        broadcaster_for(definition_type).broadcast(tx).raise_if_error!
       end
 
       # Resolves registry definitions of a given type using the overlay lookup service.
@@ -463,9 +465,12 @@ module BSV
       # @param definition_type [String]
       # @param create_result [Hash] result from wallet.create_action containing :signable_transaction
       # @return [BSV::Overlay::OverlayBroadcastResult]
+      # @raise [RuntimeError] if the transaction cannot be signed
+      # @raise [BSV::Overlay::OverlayError] (or a subclass) if the overlay broadcast fails —
+      #   see {BSV::Overlay::OverlayBroadcastResult#raise_if_error!} for the mapping
       def sign_and_broadcast(definition_type, create_result)
         signable   = create_result[:signable_transaction]
-        partial_tx = BSV::Transaction::Transaction.from_beef(normalise_beef(signable[:tx]))
+        partial_tx = BSV::Transaction::Tx.from_beef(normalise_beef(signable[:tx]))
 
         template = BSV::Script::PushDropTemplate.new(wallet: @wallet, originator: @originator)
         unlocker = template.unlock(
@@ -488,8 +493,8 @@ module BSV
 
         raise 'Revoke failed: could not sign transaction' if sign_result[:tx].nil?
 
-        signed_tx = BSV::Transaction::Transaction.from_beef(normalise_beef(sign_result[:tx]))
-        broadcaster_for(definition_type).broadcast(signed_tx)
+        signed_tx = BSV::Transaction::Tx.from_beef(normalise_beef(sign_result[:tx]))
+        broadcaster_for(definition_type).broadcast(signed_tx).raise_if_error!
       end
 
       # Verifies that the registered definition belongs to the current wallet.

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

@@ -70,7 +70,7 @@ module BSV
 
       # Verify a transaction input by evaluating its scripts.
       #
-      # @param tx [Transaction::Transaction] the transaction being verified
+      # @param tx [Transaction::Tx] the transaction being verified
       # @param input_index [Integer] the input index within the transaction
       # @param unlock_script [Script] the input's unlocking script
       # @param lock_script [Script] the previous output's locking script

data/lib/bsv/script/push_drop_template.rb

@@ -93,7 +93,7 @@ module BSV
         # the wallet's derived key, then returns a P2PKH unlock wrapped in a
         # PushDrop unlock (which is a pass-through).
         #
-        # @param tx [BSV::Transaction::Transaction] the spending transaction
+        # @param tx [BSV::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)
@@ -125,7 +125,7 @@ module BSV
 
         # Estimated byte length of the unlocking script.
         #
-        # @param _tx [BSV::Transaction::Transaction] unused
+        # @param _tx [BSV::Transaction::Tx] unused
         # @param _input_index [Integer] unused
         # @return [Integer]
         def estimated_length(_tx, _input_index)

data/lib/bsv/transaction/beef.rb

@@ -72,10 +72,10 @@ module BSV
 
       # A BEEF entry containing a raw transaction without a merkle proof.
       class RawTxEntry < BeefTx
-        # @return [Transaction] the transaction
+        # @return [Tx] the transaction
         attr_reader :transaction
 
-        # @param transaction [Transaction] the transaction
+        # @param transaction [Tx] the transaction
         # @raise [ArgumentError] if transaction is nil
         def initialize(transaction:)
           raise ArgumentError, 'RawTxEntry requires a transaction' if transaction.nil?
@@ -97,13 +97,13 @@ module BSV
 
       # A BEEF entry containing a raw transaction with an associated BUMP index.
       class ProvenTxEntry < BeefTx
-        # @return [Transaction] the transaction
+        # @return [Tx] the transaction
         attr_reader :transaction
 
         # @return [Integer] index into the BEEF bumps array
         attr_reader :bump_index
 
-        # @param transaction [Transaction] the transaction
+        # @param transaction [Tx] the transaction
         # @param bump_index [Integer] index into the bumps array
         # @raise [ArgumentError] if transaction or bump_index is nil
         def initialize(transaction:, bump_index:)
@@ -320,7 +320,7 @@ module BSV
       # Find a transaction in the bundle by its wire-order transaction ID.
       #
       # @param wtxid [String] 32-byte wire-order wtxid
-      # @return [Transaction, nil] the matching transaction, or nil
+      # @return [Tx, nil] the matching transaction, or nil
       def find_transaction(wtxid)
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         BSV.logger&.debug { "[Beef] find_transaction: #{wtxid.reverse.unpack1('H*')} in #{@transactions.length} entries" }
@@ -353,7 +353,7 @@ module BSV
       # Find a transaction with all source_transactions wired for signing.
       #
       # @param wtxid [String] 32-byte wire-order wtxid
-      # @return [Transaction, nil] the transaction with wired inputs, or nil
+      # @return [Tx, nil] the transaction with wired inputs, or nil
       def find_transaction_for_signing(wtxid)
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         tx = find_transaction(wtxid)
@@ -367,7 +367,7 @@ module BSV
       # and merkle paths) for atomic proof validation.
       #
       # @param wtxid [String] 32-byte wire-order wtxid
-      # @return [Transaction, nil] the transaction with full proof tree, or nil
+      # @return [Tx, nil] the transaction with full proof tree, or nil
       def find_atomic_transaction(wtxid)
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         tx = find_transaction(wtxid)
@@ -440,7 +440,7 @@ module BSV
       # (same txid) are upgraded if a stronger format is now available (F5.7):
       # TXID_ONLY → RAW_TX or RAW_TX_AND_BUMP; RAW_TX → RAW_TX_AND_BUMP.
       #
-      # @param tx [Transaction] the transaction to merge
+      # @param tx [Tx] the transaction to merge
       # @return [BeefTx] the (possibly existing or upgraded) BeefTx entry
       def merge_transaction(tx)
         wtxid = tx.wtxid
@@ -479,7 +479,7 @@ module BSV
       # @param bump_index [Integer, nil] optional BUMP index
       # @return [BeefTx] the new or upgraded BeefTx entry
       def merge_raw_tx(raw_bytes, bump_index: nil)
-        tx = Transaction.from_binary(raw_bytes)
+        tx = Tx.from_binary(raw_bytes)
 
         if bump_index
           unless bump_index.is_a?(Integer) && bump_index >= 0 && bump_index < @bumps.length
@@ -740,7 +740,7 @@ module BSV
             case format
             when FORMAT_TXID_ONLY
               # Wire stores txid in internal (little-endian / wire) byte order;
-              # store as-is in known_wtxid so it matches Transaction#wtxid.
+              # store as-is in known_wtxid so it matches Tx#wtxid.
               raise ArgumentError, 'truncated BEEF: not enough bytes for TXID_ONLY entry' if offset + 32 > data.bytesize
 
               known_wtxid = data.byteslice(offset, 32)
@@ -749,12 +749,12 @@ module BSV
             when FORMAT_RAW_TX_AND_BUMP
               bump_index, vi_size = VarInt.decode(data, offset)
               offset += vi_size
-              tx, consumed = Transaction.from_binary_with_offset(data, offset)
+              tx, consumed = Tx.from_binary_with_offset(data, offset)
               offset += consumed
               tx.merkle_path = beef.bumps[bump_index] if bump_index < beef.bumps.length
               beef.transactions << ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
             when FORMAT_RAW_TX
-              tx, consumed = Transaction.from_binary_with_offset(data, offset)
+              tx, consumed = Tx.from_binary_with_offset(data, offset)
               offset += consumed
               beef.transactions << RawTxEntry.new(transaction: tx)
             end
@@ -768,7 +768,7 @@ module BSV
           offset += vi_size
 
           num_txs.times do
-            tx, consumed = Transaction.from_binary_with_offset(data, offset)
+            tx, consumed = Tx.from_binary_with_offset(data, offset)
             offset += consumed
 
             has_bump = data.getbyte(offset)
@@ -821,7 +821,7 @@ module BSV
       #   RAW_TX    → RAW_TX_AND_BUMP (if bump now available)
       #
       # @param existing [BeefTx] the current entry in @transactions
-      # @param tx [Transaction, nil] the raw transaction (may be nil for TXID_ONLY → TXID_ONLY)
+      # @param tx [Tx, nil] the raw transaction (may be nil for TXID_ONLY → TXID_ONLY)
       # @param bump_index [Integer, nil] a BUMP index already validated against @bumps
       # @return [BeefTx, nil] the upgraded entry, or nil when no upgrade is needed
       def upgrade_beef_tx(existing, tx, bump_index: nil)

data/lib/bsv/transaction/chain_tracker.rb

@@ -4,7 +4,7 @@ module BSV
   module Transaction
     # Duck type for block header lookups used by the SDK's verify methods.
     #
-    # {Beef#verify}, {MerklePath#verify}, and {Transaction#verify} define
+    # {Beef#verify}, {MerklePath#verify}, and {Tx#verify} define
     # what a valid structure *is* — they walk trees, check proofs, and
     # compare roots. But they have no data source of their own. The
     # chain tracker is the data source: an object the consumer provides

data/lib/bsv/transaction/fee_model.rb

@@ -17,7 +17,7 @@ module BSV
     class FeeModel
       # Compute the fee for a transaction.
       #
-      # @param transaction [Transaction] the transaction to compute the fee for
+      # @param transaction [Tx] the transaction to compute the fee for
       # @return [Integer] the fee in satoshis
       # @raise [NotImplementedError] if not overridden by a subclass
       def compute_fee(_transaction)

data/lib/bsv/transaction/fee_models/live_policy.rb

@@ -66,7 +66,7 @@ module BSV
 
         # Compute the fee for a transaction using the latest ARC rate.
         #
-        # @param transaction [Transaction] the transaction to compute the fee for
+        # @param transaction [Tx] the transaction to compute the fee for
         # @return [Integer] the fee in satoshis
         def compute_fee(transaction)
           rate = current_rate

data/lib/bsv/transaction/fee_models/satoshis_per_kilobyte.rb

@@ -23,7 +23,7 @@ module BSV
 
         # Compute the fee for a transaction based on its estimated size.
         #
-        # @param transaction [Transaction] the transaction to compute the fee for
+        # @param transaction [Tx] the transaction to compute the fee for
         # @return [Integer] the fee in satoshis
         def compute_fee(transaction)
           size = transaction.estimated_size

data/lib/bsv/transaction/merkle_path.rb

@@ -450,7 +450,7 @@ module BSV
       # that the extracted path computes the same merkle root as the
       # source.
       #
-      # The primary use case is +Transaction#to_beef+: when a BUMP loaded
+      # The primary use case is +Tx#to_beef+: when a BUMP loaded
       # from a proof store carries +txid: true+ flags for transactions
       # that are not part of the current BEEF bundle, extracting only the
       # bundled txids strips the phantom flags (and the now-unneeded

data/lib/bsv/transaction/p2pkh.rb

@@ -24,7 +24,7 @@ module BSV
 
       # Generate the P2PKH unlocking script for the given input.
       #
-      # @param tx [Transaction] the transaction being signed
+      # @param tx [Tx] the transaction being signed
       # @param input_index [Integer] the input index to sign
       # @return [Script::Script] the unlocking script (signature + pubkey)
       def sign(tx, input_index)

data/lib/bsv/transaction/transaction_input.rb

@@ -26,7 +26,7 @@ module BSV
       # @return [Script::Script, nil] locking script of the source output (needed for sighash)
       attr_accessor :source_locking_script
 
-      # @return [Transaction, nil] the full source transaction (for BEEF wiring)
+      # @return [Tx, nil] the full source transaction (for BEEF wiring)
       attr_accessor :source_transaction
 
       # @return [UnlockingScriptTemplate, nil] template for deferred signing

data/lib/bsv/transaction/{transaction.rb → tx.rb}

@@ -10,12 +10,12 @@ module BSV
     # estimation.
     #
     # @example Build, sign, and serialise a transaction
-    #   tx = BSV::Transaction::Transaction.new
+    #   tx = BSV::Transaction::Tx.new
     #   tx.add_input(input)
     #   tx.add_output(output)
     #   tx.sign(0, private_key)
     #   tx.to_hex #=> "0100000001..."
-    class Transaction
+    class Tx
       # Estimated size of an unsigned P2PKH input in bytes.
       UNSIGNED_P2PKH_INPUT_SIZE = 148
 
@@ -144,7 +144,7 @@ module BSV
       # Deserialise a transaction from binary data.
       #
       # @param data [String] raw binary transaction
-      # @return [Transaction] the parsed transaction
+      # @return [Tx] the parsed transaction
       def self.from_binary(data)
         raise ArgumentError, "truncated transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
 
@@ -182,7 +182,7 @@ module BSV
       # Deserialise a transaction from a hex string.
       #
       # @param hex [String] hex-encoded transaction
-      # @return [Transaction] the parsed transaction
+      # @return [Tx] the parsed transaction
       def self.from_hex(hex)
         from_binary(BSV::Primitives::Hex.decode(hex, name: 'transaction hex'))
       end
@@ -190,7 +190,7 @@ module BSV
       # Deserialise a transaction from Extended Format (BRC-30) binary data.
       #
       # @param data [String] raw EF binary
-      # @return [Transaction] the parsed transaction with source data on inputs
+      # @return [Tx] the parsed transaction with source data on inputs
       # @raise [ArgumentError] if the EF marker is invalid
       def self.from_ef(data)
         raise ArgumentError, "truncated EF transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
@@ -250,7 +250,7 @@ module BSV
       # Deserialise a transaction from an Extended Format hex string.
       #
       # @param hex [String] hex-encoded EF transaction
-      # @return [Transaction] the parsed transaction with source data on inputs
+      # @return [Tx] the parsed transaction with source data on inputs
       def self.from_ef_hex(hex)
         from_ef(BSV::Primitives::Hex.decode(hex, name: 'EF transaction hex'))
       end
@@ -260,7 +260,7 @@ module BSV
       #
       # @param data [String] binary data containing the transaction
       # @param offset [Integer] byte offset to start reading from
-      # @return [Array(Transaction, Integer)] the transaction and bytes consumed
+      # @return [Array(Tx, Integer)] the transaction and bytes consumed
       def self.from_binary_with_offset(data, offset = 0)
         if data.bytesize < offset + 10
           raise ArgumentError, "truncated transaction: need at least 10 bytes at offset #{offset}, got #{data.bytesize - offset}"
@@ -331,7 +331,7 @@ module BSV
         bump_index_by_height = build_beef_bumps(beef, ancestors)
         BSV.logger&.debug do
           proven = ancestors.count(&:merkle_path)
-          "[Transaction] BEEF: #{ancestors.length} ancestors, #{proven} proven " \
+          "[Tx] BEEF: #{ancestors.length} ancestors, #{proven} proven " \
             "across #{bump_index_by_height.length} block heights"
         end
 
@@ -370,7 +370,7 @@ module BSV
       # +wire_source_transactions+ pass in +Beef.from_binary+.
       #
       # @param data [String] raw BEEF binary
-      # @return [Transaction, nil] the subject transaction with ancestry wired,
+      # @return [Tx, nil] the subject transaction with ancestry wired,
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef(data)
         beef = Beef.from_binary(data)
@@ -384,7 +384,7 @@ module BSV
       # Parse a BEEF hex string and return the subject transaction.
       #
       # @param hex [String] hex-encoded BEEF
-      # @return [Transaction, nil] the subject transaction with ancestry wired,
+      # @return [Tx, nil] the subject transaction with ancestry wired,
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef_hex(hex)
         from_beef(BSV::Primitives::Hex.decode(hex, name: 'BEEF hex'))
@@ -400,7 +400,7 @@ module BSV
       # @return [String] 32-byte transaction ID in wire byte order
       def wtxid
         id = BSV::Primitives::Digest.sha256d(to_binary)
-        BSV.logger&.debug { "[Transaction] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
+        BSV.logger&.debug { "[Tx] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
         id
       end
 
@@ -729,7 +729,7 @@ module BSV
       # @return [Integer] estimated fee in satoshis (rounded up)
       def estimated_fee(satoshis_per_byte: 0.1)
         unless self.class.instance_variable_get(:@_estimated_fee_warned)
-          warn '[DEPRECATION] BSV::Transaction::Transaction#estimated_fee is deprecated. ' \
+          warn '[DEPRECATION] BSV::Transaction::Tx#estimated_fee is deprecated. ' \
                'Use BSV::Transaction::FeeModels::SatoshisPerKilobyte.new.compute_fee(tx) instead.', uplevel: 1
           self.class.instance_variable_set(:@_estimated_fee_warned, true)
         end
@@ -913,12 +913,12 @@ module BSV
 
         if tx.merkle_path
           BSV.logger&.debug do
-            "[Transaction] ancestor: #{tx.dtxid_hex} proven at height #{tx.merkle_path.block_height} (leaf stop)"
+            "[Tx] ancestor: #{tx.dtxid_hex} proven at height #{tx.merkle_path.block_height} (leaf stop)"
           end
         else
           tx.inputs.each_with_index do |input, idx|
             unless input.source_transaction
-              BSV.logger&.debug { "[Transaction] ancestor: #{tx.dtxid_hex} input #{idx} has no source_transaction (skipped)" }
+              BSV.logger&.debug { "[Tx] ancestor: #{tx.dtxid_hex} input #{idx} has no source_transaction (skipped)" }
               next
             end
 

data/lib/bsv/transaction/unlocking_script_template.rb

@@ -14,7 +14,7 @@ module BSV
     class UnlockingScriptTemplate
       # Generate the unlocking script for a transaction input.
       #
-      # @param _tx [Transaction] the transaction being signed
+      # @param _tx [Tx] the transaction being signed
       # @param _input_index [Integer] the input index to sign
       # @return [Script::Script] the generated unlocking script
       # @raise [NotImplementedError] if not overridden by a subclass
@@ -24,7 +24,7 @@ module BSV
 
       # Estimate the unlocking script length in bytes (for fee estimation).
       #
-      # @param _tx [Transaction] the transaction
+      # @param _tx [Tx] the transaction
       # @param _input_index [Integer] the input index
       # @return [Integer] estimated script length in bytes
       # @raise [NotImplementedError] if not overridden by a subclass

data/lib/bsv/transaction.rb

@@ -3,7 +3,7 @@
 module BSV
   # Transaction building, signing, serialisation, and verification.
   #
-  # Provides the {Transaction::Transaction} class for constructing and signing
+  # Provides the {Transaction::Tx} class for constructing and signing
   # transactions, {Transaction::Beef} for BEEF (BRC-62/95/96) serialisation,
   # {Transaction::MerklePath} for BRC-74 merkle proofs, and
   # {Transaction::Sighash} constants for BIP-143 sighash computation.
@@ -21,6 +21,6 @@ module BSV
     autoload :Beef,                     'bsv/transaction/beef'
     autoload :UnlockingScriptTemplate,  'bsv/transaction/unlocking_script_template'
     autoload :P2PKH,                    'bsv/transaction/p2pkh'
-    autoload :Transaction,              'bsv/transaction/transaction'
+    autoload :Tx,                       'bsv/transaction/tx'
   end
 end

data/lib/bsv/version.rb

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

data/lib/bsv/wallet/proto_wallet/key_deriver.rb

@@ -34,6 +34,19 @@ module BSV
           @identity_key ||= @root_key.public_key.to_hex
         end
 
+        # Returns the identity public key as a 33-byte compressed binary string.
+        #
+        # Pubkeys are hex-canonical in this SDK (see ADR-001 — the documented
+        # exception to binary-internal), so {#identity_key} (hex) is the
+        # default. This binary accessor exists for the rare sites that need
+        # raw bytes (e.g. feeding +BSV::Primitives::Hash#hash160+) without
+        # round-tripping hex → binary at each call.
+        #
+        # @return [String] 33-byte compressed public key binary
+        def identity_key_bytes
+          @identity_key_bytes ||= @root_key.public_key.compressed
+        end
+
         # Derives a public key using BRC-42 key derivation.
         #
         # @param protocol_id [Array] [security_level, protocol_name]

data/lib/bsv/wallet/proto_wallet.rb

@@ -167,7 +167,7 @@ module BSV
         priv_key = @key_deriver.derive_private_key(protocol_id, key_id, counterparty)
 
         hash = if hash_to_directly_sign
-                 bytes_to_string(hash_to_directly_sign)
+                 validate_hash_32!(hash_to_directly_sign, 'hash_to_directly_sign')
                else
                  BSV::Primitives::Digest.sha256(bytes_to_string(data))
                end
@@ -203,7 +203,7 @@ module BSV
         )
 
         hash = if hash_to_directly_verify
-                 bytes_to_string(hash_to_directly_verify)
+                 validate_hash_32!(hash_to_directly_verify, 'hash_to_directly_verify')
                else
                  BSV::Primitives::Digest.sha256(bytes_to_string(data))
                end
@@ -347,6 +347,16 @@ module BSV
         bytes.is_a?(String) ? bytes.b : bytes.pack('C*')
       end
 
+      # Coerce a hash parameter to a 32-byte binary string, raising
+      # InvalidParameterError if the input has the wrong length. Accepts
+      # either a binary String or an Array<Integer> per BRC-100 convention.
+      def validate_hash_32!(value, name)
+        bytes = bytes_to_string(value)
+        raise InvalidParameterError.new(name, "exactly 32 bytes, got #{bytes.bytesize}") unless bytes.bytesize == 32
+
+        bytes
+      end
+
       # Normalise a public key argument to a 66-character compressed hex string.
       # Accepts either a 33-byte binary string or a 66-character hex string.
       def normalise_pubkey_hex(value)

data/lib/bsv/wallet/serializer/create_signature.rb

@@ -30,6 +30,13 @@ module BSV
             end
             raise BSV::Wallet::InvalidParameterError.new('data or hash_to_directly_sign', 'present') unless data || hash
 
+            if hash && hash.bytesize != HASH_SIZE
+              raise BSV::Wallet::InvalidParameterError.new(
+                'hash_to_directly_sign',
+                "exactly #{HASH_SIZE} bytes, got #{hash.bytesize}"
+              )
+            end
+
             w = BSV::Wallet::Wire::Writer.new
             Common.write_key_related_params(
               w,

data/lib/bsv/wallet/serializer/get_public_key.rb

@@ -66,6 +66,10 @@ module BSV
 
         # Result wire layout:
         #   [33 bytes: compressed public key]
+        #
+        # The wire bytes are 33-byte compressed binary by the BRC-103 protocol,
+        # but the Ruby return shape is hex per the BRC-100 PubKeyHex contract
+        # (ADR-001 — pubkeys are the documented hex exception to binary-internal).
         module Result
           module_function
 
@@ -77,7 +81,7 @@ module BSV
           def deserialize(bytes)
             raise ArgumentError, "public key too short: #{bytes.bytesize}" if bytes.bytesize < PUBKEY_SIZE
 
-            { public_key: bytes.byteslice(0, PUBKEY_SIZE) }
+            { public_key: bytes.byteslice(0, PUBKEY_SIZE).unpack1('H*') }
           end
         end
       end

data/lib/bsv/wallet/serializer/reveal_counterparty_key_linkage.rb

@@ -75,11 +75,14 @@ module BSV
             w.buf
           end
 
+          # Pubkey fields are returned as 66-char hex per the BRC-100 PubKeyHex
+          # contract (ADR-001 — pubkeys are the documented hex exception to
+          # binary-internal). Wire bytes stay 33-byte compressed binary.
           def deserialize(bytes)
             r = BSV::Wallet::Wire::Reader.new(bytes)
-            prover       = r.read_bytes(PUBKEY_SIZE)
-            verifier     = r.read_bytes(PUBKEY_SIZE)
-            counterparty = r.read_bytes(PUBKEY_SIZE)
+            prover       = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            verifier     = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            counterparty = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
             revelation_time = r.read_str_with_varint_len
             el_len = r.read_varint
             encrypted_linkage = r.read_bytes(el_len)

data/lib/bsv/wallet/serializer/reveal_specific_key_linkage.rb

@@ -78,11 +78,14 @@ module BSV
             w.buf
           end
 
+          # Pubkey fields are returned as 66-char hex per the BRC-100 PubKeyHex
+          # contract (ADR-001 — pubkeys are the documented hex exception to
+          # binary-internal). Wire bytes stay 33-byte compressed binary.
           def deserialize(bytes)
             r = BSV::Wallet::Wire::Reader.new(bytes)
-            prover       = r.read_bytes(PUBKEY_SIZE)
-            verifier     = r.read_bytes(PUBKEY_SIZE)
-            counterparty = r.read_bytes(PUBKEY_SIZE)
+            prover       = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            verifier     = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            counterparty = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
             protocol_id  = Common.read_protocol(r)
             key_id_len   = r.read_varint
             key_id       = r.read_bytes(key_id_len).force_encoding('UTF-8')

data/lib/bsv/wallet/serializer/verify_signature.rb

@@ -34,6 +34,13 @@ module BSV
             raise BSV::Wallet::InvalidParameterError.new('data or hash_to_directly_verify', 'present') unless data || hash
             raise BSV::Wallet::InvalidParameterError.new('signature', 'present') unless sig
 
+            if hash && hash.bytesize != HASH_SIZE
+              raise BSV::Wallet::InvalidParameterError.new(
+                'hash_to_directly_verify',
+                "exactly #{HASH_SIZE} bytes, got #{hash.bytesize}"
+              )
+            end
+
             w = BSV::Wallet::Wire::Writer.new
             Common.write_key_related_params(
               w,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.24.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -181,9 +181,9 @@ files:
 - lib/bsv/transaction/merkle_path.rb
 - lib/bsv/transaction/p2pkh.rb
 - lib/bsv/transaction/sighash.rb
-- lib/bsv/transaction/transaction.rb
 - lib/bsv/transaction/transaction_input.rb
 - lib/bsv/transaction/transaction_output.rb
+- lib/bsv/transaction/tx.rb
 - lib/bsv/transaction/unlocking_script_template.rb
 - lib/bsv/transaction/var_int.rb
 - lib/bsv/transaction/verification_error.rb