bsv-sdk 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a76170f9d5dcdfc76945c20c541b556a02f3fb5a7214a8d6f777eb589f048461
-  data.tar.gz: 57176276d41d430d654682dd22aef0f93bee9e2e3c57d4fb76d435dbd8c3e705
+  metadata.gz: 6bb4b97822f38d793a308e9beddc94bd90e64457bda8f1782875ddcd8a1ff1f3
+  data.tar.gz: 85009a67a04ee1264acd883224ea418ed46558629a18db3d1757486cc544852d
 SHA512:
-  metadata.gz: fb7257bda0b14c14ab55d8da3a19fdc27a8eca113cfeb857487079d4e0f042ebbaef184e81382d50aed7a9efd69dc4d2cb2d77594b6e1ae5f3f6d047c01d2ab9
-  data.tar.gz: 20f9e8fe53476ddd87900d1b58d00811da403703d5ae8cf6dc0f6d4a4836ab8a12e42ddce88c7323bd281e710770f4b7b6805cb842ab4f164c4b17559afa46e7
+  metadata.gz: 85e2958f6bb6af774b2ca06e5187bbc1c756546e322430375108617b4675e6e5d5373aa8d93fd4504327d3c48e29507a2caea566d0b9af5e16c3fdd089bc2fbc
+  data.tar.gz: 56797e445e8996c2a41e85484e49f53b3568eaebeaf01de39a1e919c6949f40b172236ad5bd89fbc77eb9405a532653c9ab1972e696e699d6410e503318360d7

data/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.18.0 — 2026-05-09
+
+### Breaking Changes
+- Eliminated display-order binary txid from public API — all methods now use `wtxid` (wire-order) internally (#690)
+
+### Added
+- Provider auth and rate limit metadata: `auth:`, `rate_limit:`, `authenticated?` on Provider; generic auth dispatch in Protocol `build_request` (#718)
+- JungleBus protocol: transaction lookup, address queries, block headers via GorillaPool JungleBus REST API (#717)
+- Ordinals protocol: fixed endpoint paths, added tx details, tx status, UTXOs, balance, spends, chain tip (#727)
+- Full WoC API coverage: expanded from 30 to 54 endpoints with complete address, script, UTXO, and analytics support (#715)
+- Integration tests for ARC, JungleBus, Ordinals, and WoCREST against live APIs (#726)
+- API documentation URLs in all protocol file headers (#730)
+
+### Fixed
+- Ordinals `get_tx` path corrected (`/hex` → `/raw`) and response handler fixed (binary, not JSON) (#727)
+- Auth normalisation: `{ bearer: nil }` and `{ api_key: nil }` treated as unauthenticated (#725)
+- WoC health endpoint path corrected (`/health` → `/woc`)
+- Bulk POST body formats and `get_utxos_all` path corrected for WoC
+- Lazy removal of expired sessions during identity-key lookup (#707)
+- Session TTL expiration added to SessionManager (#707)
+- Guard against nil source data and out-of-bounds input_index in sighash (#702)
+- Wire format deep conversion depth limit (#709)
+
+### Changed
+- BeefTx refactored to polymorphic subclass hierarchy with validated constructors (#692-698)
+- WoCREST `build_request` override removed — replaced by generic auth dispatch
+- MCP dependency bumped from ~> 0.12 to ~> 0.15 (#700)
+
+## 0.17.0 — 2026-05-02
+
+### Breaking Changes
+- Renamed `TransactionInput#prev_tx_id` to `#prev_wtxid` — all call sites must update (#678)
+- Renamed MerklePath parameters from `txid_hex` to `dtxid_hex` throughout (#681)
+
+### Added
+- `Transaction#wtxid` — wire-order transaction ID (raw SHA-256d bytes) (#673)
+- `Transaction#dtxid` / `#dtxid_hex` — display-order hex aliases (#680)
+- `TransactionInput#dtxid_hex` — display-order hex of the referenced transaction (#678)
+- `TransactionInput.wtxid_from_hex` — convert display-order hex to wire-order bytes (#678)
+- `Hex.validate_wtxid!` / `Hex.validate_dtxid_hex!` — runtime validation for wire/display txid formats (#685)
+- `Hex.validate_hash32!` — general-purpose 32-byte binary hash validator (#686)
+- `BSV.logger` — opt-in debug instrumentation with zero overhead when unused (#686)
+- Debug logging at txid conversions, sighash preimage, script interpreter, ARC broadcast, BEEF ancestry, and ProtoWallet key derivation (#686, #688)
+
+### Changed
+- All internal txid variables renamed to `wtxid` (wire-order) convention (#679)
+- BEEF internals enforce wire-order throughout — no byte-reversals inside the bundle (#675)
+- MerklePath `compute_root_hex` and `from_tsc` now validate hex input (#686)
+
+### Fixed
+- `BeefTx#dtxid` now returns hex string (was returning binary) (#677)
+- Certificate field naming aligned with BRC-52 convention (#677)
+
 ## 0.16.0 — 2026-05-01
 
 ### Breaking Changes

data/lib/bsv/auth/certificate.rb

@@ -81,6 +81,9 @@ module BSV
         buf << [@subject].pack('H*')
         buf << [@certifier].pack('H*')
 
+        # Certificate binary format: revocation outpoint txid stored in display byte
+        # order (matching TS and Go SDKs). Go encodes via WriteBytesReverse(wire_order),
+        # TS encodes via toArray(display_hex) — both produce identical display-order bytes.
         txid_hex, output_index_str = @revocation_outpoint.to_s.split('.', 2)
         buf << [txid_hex].pack('H*')
         buf << BSV::Transaction::VarInt.encode(output_index_str.to_i)
@@ -124,7 +127,8 @@ module BSV
         certifier_bytes = data.byteslice(pos, 33)
         pos += 33
 
-        txid_bytes = data.byteslice(pos, 32)
+        # Outpoint txid bytes — stored in display byte order (matching TS and Go SDKs).
+        outpoint_txid = data.byteslice(pos, 32)
         pos += 32
         output_index, vi_len = BSV::Transaction::VarInt.decode(data, pos)
         pos += vi_len
@@ -158,7 +162,7 @@ module BSV
           serial_number: Base64.strict_encode64(serial_bytes),
           subject: subject_bytes.unpack1('H*'),
           certifier: certifier_bytes.unpack1('H*'),
-          revocation_outpoint: "#{txid_bytes.unpack1('H*')}.#{output_index}",
+          revocation_outpoint: "#{outpoint_txid.unpack1('H*')}.#{output_index}",
           fields: fields,
           signature: signature
         )

data/lib/bsv/auth/get_verifiable_certificates.rb

@@ -21,7 +21,9 @@ module BSV
       #   - +:types+ [Hash] type (Base64 string) → array of field names to reveal
       # @param verifier_identity_key [String] the verifier's compressed public key hex
       # @return [Array<VerifiableCertificate>] list of verifiable certificates ready for
-      #   presentation, or +[]+ on any failure
+      #   presentation, or +[]+ when the wallet does not support certificate operations
+      # @raise [StandardError] propagates unexpected errors (network failures, key derivation
+      #   errors, etc.) to the caller — only +UnsupportedActionError+ is swallowed
       def get_verifiable_certificates(wallet, requested_certificates, verifier_identity_key)
         return [] unless wallet.respond_to?(:list_certificates) && wallet.respond_to?(:prove_certificate)
 
@@ -65,11 +67,9 @@ module BSV
             signature: cert[:signature] || cert['signature']
           )
         end
-      rescue StandardError
-        # Auto-fetch is best-effort: wallet may raise UnsupportedActionError,
-        # key derivation errors, or other failures. The peer protocol handles
-        # "no certificates" gracefully — the requesting peer enforces its own
-        # certificate requirements independently.
+      rescue BSV::Wallet::UnsupportedActionError
+        # Wallet does not implement certificate operations (e.g. ProtoWallet).
+        # Return empty — the requesting peer enforces its own requirements independently.
         []
       end
     end

data/lib/bsv/auth/peer.rb

@@ -488,7 +488,7 @@ module BSV
         signature   = fetch!(message, :signature)
 
         # Verify the echoed nonce is one we created
-        raise AuthError, "Nonce verification failed from peer: #{peer_key}" unless Nonce.verify(our_nonce, @wallet)
+        verify_nonce!(our_nonce, context: "initial response from peer: #{peer_key}")
 
         session = @session_manager.get_session(our_nonce)
         raise AuthError, "No pending session for nonce: #{our_nonce.inspect}" unless session
@@ -566,7 +566,7 @@ module BSV
         msg_nonce = fetch!(message, :nonce)
 
         # Verify the echoed nonce is one we created
-        raise AuthError, "Unable to verify nonce for general message from: #{peer_key}" unless Nonce.verify(our_nonce, @wallet)
+        verify_nonce!(our_nonce, context: "general message from: #{peer_key}")
 
         session = @session_manager.get_session(our_nonce)
         raise AuthError, "Session not found for nonce: #{our_nonce.inspect}" unless session
@@ -602,7 +602,7 @@ module BSV
         requested = message[:requested_certificates] || message['requested_certificates']
         signature = fetch!(message, :signature)
 
-        raise AuthError, "Unable to verify nonce for certificate request message from: #{peer_key}" unless Nonce.verify(our_nonce, @wallet)
+        verify_nonce!(our_nonce, context: "certificate request from: #{peer_key}")
 
         session = @session_manager.get_session(our_nonce)
         raise AuthError, "Session not found for nonce: #{our_nonce.inspect}" unless session
@@ -647,7 +647,7 @@ module BSV
         certs     = message[:certificates] || message['certificates'] || []
         signature = fetch!(message, :signature)
 
-        raise AuthError, "Unable to verify nonce for certificate response from: #{peer_key}" unless Nonce.verify(our_nonce, @wallet)
+        verify_nonce!(our_nonce, context: "certificate response from: #{peer_key}")
 
         session = @session_manager.get_session(our_nonce)
         raise AuthError, "Session not found for nonce: #{our_nonce.inspect}" unless session
@@ -773,6 +773,12 @@ module BSV
         certs.map { |c| c.respond_to?(:to_h) ? c.to_h : c }
       end
 
+      def verify_nonce!(nonce, context:)
+        return if Nonce.verify(nonce, @wallet)
+
+        raise AuthError, "Nonce verification failed for #{context}"
+      end
+
       def current_time_ms
         (Time.now.to_f * 1000).to_i
       end

data/lib/bsv/auth/session_manager.rb

@@ -9,9 +9,16 @@ module BSV
     # peer identity key are supported — the most recently updated session
     # is returned when looking up by identity key.
     #
+    # Sessions expire after +default_ttl+ seconds (default: 3600). Pass
+    # +default_ttl: nil+ to disable expiry entirely. Expired sessions are
+    # removed lazily on access; call {#sweep_expired} for proactive cleanup.
+    #
     # Matches the ts-sdk SessionManager dual-index design.
     class SessionManager
-      def initialize
+      # @param default_ttl [Integer, nil] seconds before a session expires;
+      #   +nil+ disables TTL entirely.
+      def initialize(default_ttl: 3600)
+        @default_ttl = default_ttl
         # session_nonce -> PeerSession
         @by_nonce    = {}
         # peer_identity_key -> Set of session_nonces
@@ -50,25 +57,40 @@ module BSV
       #
       # When the identifier is a session nonce, returns that exact session.
       # When the identifier is a peer identity key, returns the most recently
-      # updated session for that peer.
+      # updated non-expired session for that peer.
+      #
+      # Returns +nil+ if the session has expired (and removes it from the store).
       #
       # @param identifier [String]
       # @return [PeerSession, nil]
       def get_session(identifier)
         @mutex.synchronize do
           direct = @by_nonce[identifier]
-          return direct if direct
+          if direct
+            if expired_locked?(direct)
+              remove_session_locked(direct)
+              return nil
+            end
+            return direct
+          end
 
           nonces = @by_identity[identifier]
           return nil if nonces.nil? || nonces.empty?
 
           best = nil
+          expired_nonces = []
           nonces.each do |nonce|
             s = @by_nonce[nonce]
             next if s.nil?
 
+            if expired_locked?(s)
+              expired_nonces << s
+              next
+            end
+
             best = s if best.nil? || (s.last_update || 0) > (best.last_update || 0)
           end
+          expired_nonces.each { |s| remove_session_locked(s) }
           best
         end
       end
@@ -84,13 +106,53 @@ module BSV
       # @return [Boolean]
       def session?(identifier)
         @mutex.synchronize do
-          return true if @by_nonce.key?(identifier)
+          direct = @by_nonce[identifier]
+          if direct
+            if expired_locked?(direct)
+              remove_session_locked(direct)
+              return false
+            end
+            return true
+          end
 
           nonces = @by_identity[identifier]
-          !nonces.nil? && !nonces.empty?
+          return false if nonces.nil? || nonces.empty?
+
+          has_active = false
+          expired_sessions = []
+          nonces.each do |nonce|
+            s = @by_nonce[nonce]
+            next if s.nil?
+
+            if expired_locked?(s)
+              expired_sessions << s
+            else
+              has_active = true
+            end
+          end
+          expired_sessions.each { |s| remove_session_locked(s) }
+          has_active
         end
       end
 
+      # Removes all expired sessions from the store.
+      #
+      # Not called automatically — intended for use in long-running servers
+      # that want to proactively reclaim memory.
+      #
+      # @return [Integer] number of sessions removed
+      def sweep_expired
+        removed = 0
+        @mutex.synchronize do
+          expired = @by_nonce.values.select { |s| expired_locked?(s) }
+          expired.each do |s|
+            remove_session_locked(s)
+            removed += 1
+          end
+        end
+        removed
+      end
+
       private
 
       def add_session_locked(session)
@@ -115,6 +177,20 @@ module BSV
         nonces.delete(session.session_nonce)
         @by_identity.delete(session.peer_identity_key) if nonces.empty?
       end
+
+      # Must be called within @mutex.
+      def expired_locked?(session)
+        return false if @default_ttl.nil?
+
+        last = session.last_update
+        return true if last.nil? || last.zero?
+
+        current_time_ms - last > @default_ttl * 1000
+      end
+
+      def current_time_ms
+        (Time.now.to_f * 1000).to_i
+      end
     end
   end
 end

data/lib/bsv/identity/client.rb

@@ -203,10 +203,13 @@ module BSV
         raise 'Revoke failed: invalid outputIndex from overlay' if output_idx.negative?
 
         beef = BSV::Transaction::Beef.from_binary(beef_bytes)
-        tx   = beef.transactions.last&.transaction
-        raise 'Revoke failed: no transaction found in BEEF' unless tx
+        beef_tx = beef.transactions.last
+        raise 'Revoke failed: no transaction found in BEEF' if beef_tx.nil? || beef_tx.is_a?(BSV::Transaction::Beef::TxidOnlyEntry)
+
+        tx = beef_tx.transaction
         raise 'Revoke failed: outputIndex out of range' if output_idx >= tx.outputs.length
 
+        # Overlay API boundary: outpoint uses display-order hex txid as per overlay convention
         txid = tx.txid_hex
         outpoint = "#{txid}.#{output_idx}"
 

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

@@ -97,8 +97,8 @@ module BSV
 
           all_utxos = utxo_result.data.map do |entry|
             BSV::Network::UTXO.new(
-              tx_hash: entry[:tx_hash], tx_pos: entry[:tx_pos],
-              satoshis: entry[:satoshis], height: entry[:height]
+              tx_hash: entry['tx_hash'], tx_pos: entry['tx_pos'],
+              value: entry['value'], height: entry['height']
             )
           end
 
@@ -116,7 +116,7 @@ module BSV
           return Helpers.error_response("Broadcast failed: #{arc_result.message}") unless arc_result.success?
 
           result = {
-            txid: arc_result.data[:txid],
+            txid: arc_result.data[:txid], # MCP tool boundary: display-order hex from ARC response
             tx_status: arc_result.data[:tx_status],
             hex: tx.to_hex
           }
@@ -154,7 +154,7 @@ module BSV
           selected_utxos.each do |utxo|
             locking_script = p2pkh_lock_for(sender_address)
             input = BSV::Transaction::TransactionInput.new(
-              prev_tx_id: BSV::Transaction::TransactionInput.txid_from_hex(utxo.tx_hash),
+              prev_wtxid: BSV::Transaction::TransactionInput.wtxid_from_hex(utxo.tx_hash),
               prev_tx_out_index: utxo.tx_pos
             )
             input.source_satoshis = utxo.satoshis

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

@@ -71,8 +71,8 @@ module BSV
 
           utxos = utxo_result.data.map do |entry|
             BSV::Network::UTXO.new(
-              tx_hash: entry[:tx_hash], tx_pos: entry[:tx_pos],
-              satoshis: entry[:satoshis], height: entry[:height]
+              tx_hash: entry['tx_hash'], tx_pos: entry['tx_pos'],
+              value: entry['value'], height: entry['height']
             )
           end
 

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

@@ -62,8 +62,8 @@ module BSV
 
           utxos = utxo_result.data.map do |entry|
             BSV::Network::UTXO.new(
-              tx_hash: entry[:tx_hash], tx_pos: entry[:tx_pos],
-              satoshis: entry[:satoshis], height: entry[:height]
+              tx_hash: entry['tx_hash'], tx_pos: entry['tx_pos'],
+              value: entry['value'], height: entry['height']
             )
           end
 

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

@@ -25,7 +25,7 @@ module BSV
         # @return [Hash]
         def self.transaction_to_h(tx)
           {
-            txid: tx.txid_hex,
+            txid: tx.txid_hex, # MCP tool boundary: display-order hex for human consumption
             version: tx.version,
             lock_time: tx.lock_time,
             inputs: tx.inputs.each_with_index.map { |inp, i| input_to_h(inp, i) },
@@ -38,7 +38,7 @@ module BSV
         def self.input_to_h(input, _index)
           unlock_script = input.unlocking_script
           {
-            prev_txid: input.prev_tx_id.reverse.unpack1('H*'),
+            prev_txid: input.dtxid_hex,
             vout: input.prev_tx_out_index,
             script_hex: unlock_script ? unlock_script.to_hex : '',
             script_asm: unlock_script ? unlock_script.to_asm : '',

data/lib/bsv/network/broadcast_error.rb

@@ -3,10 +3,12 @@
 module BSV
   module Network
     class BroadcastError < StandardError
+      # ARC API boundary: display-order hex txid as returned by the ARC error response.
       attr_reader :status_code, :txid, :arc_status
 
       def initialize(message, status_code: nil, txid: nil, arc_status: nil)
         @status_code = status_code
+        BSV::Primitives::Hex.validate_dtxid_hex!(txid, name: 'ARC error txid') if txid
         @txid = txid
         @arc_status = arc_status
         super(message)

data/lib/bsv/network/broadcast_response.rb

@@ -3,10 +3,13 @@
 module BSV
   module Network
     class BroadcastResponse
+      # ARC API boundary: display-order hex txid as returned by the ARC broadcast endpoint.
       attr_reader :txid, :tx_status, :message, :extra_info, :block_hash, :block_height, :timestamp, :competing_txs
 
       def initialize(attrs = {})
-        @txid = attrs[:txid]
+        txid = attrs[:txid]
+        BSV::Primitives::Hex.validate_dtxid_hex!(txid, name: 'ARC broadcast txid') if txid
+        @txid = txid
         @tx_status = attrs[:tx_status]
         @message = attrs[:message]
         @extra_info = attrs[:extra_info]

data/lib/bsv/network/protocol.rb

@@ -103,14 +103,21 @@ module BSV
       @endpoints     = {}
       @subscriptions = {}
 
-      attr_reader :base_url, :api_key, :network, :http_client
+      attr_reader :base_url, :api_key, :auth, :network, :http_client
 
       # @param base_url    [String] base URL, may contain +{network}+ placeholder
-      # @param api_key     [String, nil] API key for authenticated requests
+      # @param api_key     [String, nil] legacy API key — sends +Authorization: Bearer <key>+
+      # @param auth        [Hash, Symbol, nil] auth config hash; takes precedence over +api_key:+.
+      #   Supported forms:
+      #   - +{ bearer: 'token' }+ → +Authorization: Bearer token+
+      #   - +{ api_key: 'key' }+ → +Authorization: key+ (no Bearer prefix, WoC style)
+      #   - +{ api_key: 'key', header: 'X-Custom' }+ → +X-Custom: key+
+      #   - +:none+ or +nil+ → no auth header
       # @param network     [String, Symbol, nil] network name (e.g. 'main', 'test')
       # @param http_client [Object, nil] injectable HTTP client (used in Task 3)
-      def initialize(base_url:, api_key: nil, network: nil, http_client: nil)
+      def initialize(base_url:, api_key: nil, auth: nil, network: nil, http_client: nil)
         @api_key     = api_key
+        @auth        = normalise_auth(auth)
         @network     = network
         @http_client = http_client
         @base_url    = build_base_url(base_url, network)
@@ -228,6 +235,14 @@ module BSV
 
       # Builds a Net::HTTP request for the given method, URI, and optional body.
       #
+      # Auth header dispatch (in priority order):
+      # 1. +auth:+ config hash takes precedence over the legacy +api_key:+ shorthand.
+      # 2. +{ bearer: 'token' }+ → +Authorization: Bearer token+
+      # 3. +{ api_key: 'key', header: 'X-Custom' }+ → +X-Custom: key+
+      # 4. +{ api_key: 'key' }+ → +Authorization: key+ (no Bearer prefix)
+      # 5. +auth: :none+ or no auth at all → no Authorization header set
+      # 6. Legacy +api_key:+ (no auth: provided) → +Authorization: Bearer api_key+
+      #
       # @param http_method [Symbol] +:get+ or +:post+
       # @param uri   [URI]
       # @param body  [String, nil] raw body for POST requests
@@ -240,7 +255,8 @@ module BSV
           else raise ArgumentError, "unsupported HTTP method: #{http_method}"
           end
 
-        request['Authorization'] = "Bearer #{@api_key}" if @api_key
+        apply_auth(request)
+
         if body && request.respond_to?(:body=)
           request.body = body
           request.content_type = 'application/json' unless request.content_type
@@ -248,6 +264,40 @@ module BSV
         request
       end
 
+      # Applies the auth header to the request based on the +auth:+ config or
+      # the legacy +api_key:+ shorthand.
+      #
+      # @param request [Net::HTTPRequest]
+      def apply_auth(request)
+        # auth: config takes precedence over legacy api_key:
+        if @auth != :none
+          auth = @auth
+          if auth[:bearer]
+            request['Authorization'] = "Bearer #{auth[:bearer]}"
+          elsif auth[:api_key]
+            header = auth[:header] || 'Authorization'
+            request[header] = auth[:api_key]
+          end
+        elsif @api_key
+          # Legacy shorthand: api_key: without auth: sends Bearer
+          request['Authorization'] = "Bearer #{@api_key}"
+        end
+      end
+
+      # 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
+
       # Executes the request via the injectable client or +Net::HTTP.start+.
       #
       # @param uri     [URI]
@@ -305,6 +355,8 @@ module BSV
           JSON.parse(body)
         when :json_array
           parsed = JSON.parse(body)
+          # Some providers (e.g. WoC) wrap arrays in { "result": [...] }
+          parsed = parsed['result'] if parsed.is_a?(Hash) && parsed.key?('result')
           raise TypeError, "expected Array, got #{parsed.class}" unless parsed.is_a?(Array)
 
           parsed

data/lib/bsv/network/protocols/arc.rb

@@ -24,6 +24,8 @@ module BSV
       #   result = arc.call(:broadcast, tx)
       #   result.success? # => true
       #   result.data[:txid] # => "abc123..."
+      #
+      # @see https://docs.gorillapool.io/arc/api.html ARC API v1 documentation
       class ARC < Protocol
         # ARC response statuses that indicate a transaction was NOT accepted.
         # Matches the TypeScript SDK's ARC broadcaster failure set.
@@ -45,16 +47,17 @@ module BSV
         endpoint :health,         :get,  '/v1/health',      response: :json
 
         # @param base_url      [String]      ARC base URL (may contain {network})
-        # @param api_key       [String, nil] optional bearer token
+        # @param api_key       [String, nil] legacy bearer token shorthand — use +auth:+ for new code
+        # @param auth          [Hash, Symbol, nil] auth config; takes precedence over +api_key:+
         # @param network       [String, nil] network name for base URL interpolation
         # @param deployment_id [String, nil] deployment identifier for the
         #   XDeployment-ID header; defaults to a per-instance random hex value
         # @param callback_url  [String, nil] optional X-CallbackUrl header value
         # @param callback_token [String, nil] optional X-CallbackToken header value
         # @param http_client   [#request, nil] injectable HTTP client for testing
-        def initialize(base_url:, api_key: nil, network: nil, deployment_id: nil,
+        def initialize(base_url:, api_key: nil, auth: nil, network: nil, deployment_id: nil,
                        callback_url: nil, callback_token: nil, http_client: nil)
-          super(base_url: base_url, api_key: api_key, network: network, http_client: http_client)
+          super(base_url: base_url, api_key: api_key, auth: auth, network: network, http_client: http_client)
           @deployment_id  = deployment_id || "bsv-ruby-sdk-#{SecureRandom.hex(8)}"
           @callback_url   = callback_url
           @callback_token = callback_token
@@ -138,7 +141,8 @@ module BSV
         # lacks source_satoshis / source_locking_script.
         def ef_hex_with_fallback(tx)
           tx.to_ef_hex
-        rescue ArgumentError
+        rescue ArgumentError => e
+          BSV.logger&.debug { "[ARC] EF serialisation failed: #{e.message} — falling back to raw hex" }
           tx.to_hex
         end
 
@@ -269,7 +273,7 @@ module BSV
         # same field set as broadcast responses rather than the raw parsed JSON.
         # Also checks for rejection status and missing txid (malformed 2xx).
         #
-        # @param txid [String] the transaction ID to query
+        # @param txid [String] ARC API boundary: display-order hex transaction ID to query
         # @return [Result::Success, Result::Error, Result::NotFound]
         def call_get_tx_status(txid, **)
           response = default_call(:get_tx_status, txid)
@@ -306,7 +310,7 @@ module BSV
         # @return [Hash]
         def arc_data_from(body)
           {
-            txid: body['txid'],
+            txid: body['txid'], # ARC API boundary: display-order hex from the ARC JSON response
             tx_status: body['txStatus'],
             message: body['title'],
             extra_info: body['extraInfo'],

data/lib/bsv/network/protocols/chaintracks.rb

@@ -22,15 +22,19 @@ module BSV
       #
       #   result = ct.call(:get_block_header, 800_000)
       #   result.data  # => { 'hash' => '...', 'height' => 800000, 'merkleRoot' => '...' }
+      #
+      # @note Chaintracks is an internal GorillaPool service; no public API documentation
+      #   is available.
       class Chaintracks < Protocol
         endpoint :get_block_header, :get, '/chaintracks/v2/header/height/{height}', response: :json
         endpoint :current_height,   :get, '/chaintracks/v2/tip',
                  response: ->(body) { JSON.parse(body)['height'] }
 
         # @param base_url    [String] base URL for the Chaintracks API
-        # @param api_key     [String, nil] optional Bearer API key
+        # @param api_key     [String, nil] legacy Bearer API key shorthand — use +auth:+ for new code
+        # @param auth        [Hash, Symbol, nil] auth config; takes precedence over +api_key:+
         # @param http_client [Object, nil] injectable HTTP client for testing
-        def initialize(base_url:, api_key: nil, http_client: nil)
+        def initialize(base_url:, api_key: nil, auth: nil, http_client: nil)
           super
         end
       end