bsv-sdk 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c528b336af4735e247429423231a5c6a0dd681718e94d7a3d9598b65b75a6a0
-  data.tar.gz: 21efe7a43b3ba356953af1668cb35227d9c72bd3b17a1f08a54fac2f55f0d577
+  metadata.gz: 6bb4b97822f38d793a308e9beddc94bd90e64457bda8f1782875ddcd8a1ff1f3
+  data.tar.gz: 85009a67a04ee1264acd883224ea418ed46558629a18db3d1757486cc544852d
 SHA512:
-  metadata.gz: 94b507d613413fbb96ab08f72d5db324ea33626f0f32af34f248b7d3133bd847aff1527de7ea1e68c1a1cbc1f5140f7654d4be99726348d85b852483ea00519a
-  data.tar.gz: 71c1fd8a86414cce69c1c4ec4fe1df52bab863c624ba70b806f37e2e016968eca9ac0244c42b0d52407c1817f56d9133403d3aec04a41bb39766776eb4b8c108
+  metadata.gz: 85e2958f6bb6af774b2ca06e5187bbc1c756546e322430375108617b4675e6e5d5373aa8d93fd4504327d3c48e29507a2caea566d0b9af5e16c3fdd089bc2fbc
+  data.tar.gz: 56797e445e8996c2a41e85484e49f53b3568eaebeaf01de39a1e919c6949f40b172236ad5bd89fbc77eb9405a532653c9ab1972e696e699d6410e503318360d7

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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

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,8 +203,10 @@ 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

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
 

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/network/broadcast_error.rb

@@ -8,6 +8,7 @@ module BSV
 
       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

@@ -7,7 +7,9 @@ module BSV
       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

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

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BSV
+  module Network
+    module Protocols
+      # JungleBus implements the GorillaPool JungleBus REST API as a Protocol
+      # subclass.
+      #
+      # JungleBus is a blockchain indexer that indexes all BSV transactions and
+      # provides parsed transaction data, address lookups, and block headers.
+      # The +get_tx+ endpoint returns both the full transaction (base64-encoded)
+      # and a TSC merkle proof in a single call.
+      #
+      # == Usage
+      #
+      #   jb = BSV::Network::Protocols::JungleBus.new(
+      #     base_url: 'https://junglebus.gorillapool.io'
+      #   )
+      #   result = jb.call(:get_tx, 'abc123...')
+      #   result.data['transaction']  # => base64-encoded raw tx
+      #   result.data['merkle_proof'] # => base64-encoded TSC proof (or nil)
+      #
+      # @see https://junglebus.gorillapool.io/docs/ JungleBus API documentation
+      class JungleBus < Protocol
+        # Transaction — full tx with parsed metadata and merkle proof
+        endpoint :get_tx, :get, '/v1/transaction/get/{txid}', response: :json
+
+        # Address — transaction metadata for an address
+        endpoint :get_address_meta, :get, '/v1/address/get/{address}', response: :json_array
+
+        # Address — full transaction documents for an address.
+        # Note: this endpoint currently returns empty bodies for all addresses
+        # via the REST API. It may require a subscription to populate.
+        endpoint :get_address_txs, :get, '/v1/address/transactions/{address}', response: :json_array
+
+        # Block header by height or hash
+        endpoint :get_block_header, :get, '/v1/block_header/get/{height}', response: :json
+
+        # Block headers from a given height (supports ?limit=N, max 10000)
+        endpoint :get_block_headers, :get, '/v1/block_header/list/{height}', response: :json_array
+
+        # @param base_url    [String] base URL for the JungleBus API
+        # @param api_key     [String, nil] legacy 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, auth: nil, http_client: nil)
+          super
+        end
+      end
+    end
+  end
+end