bsv-sdk 0.12.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1a0e79613d6d5f390c6af210d0e0ad5fe92925b684c5bbe1a6ddffa5ebcf3f5
-  data.tar.gz: ee4726af0c27f6ecbe11f3483a4c2a9e4195b9f46a15b4c68270b614372759ca
+  metadata.gz: 4532a163439721455da80290d8b02342e597a01bb1e00b259d13343f8f9bd592
+  data.tar.gz: b7cfda4a8084b96c28f34afb6829fcba9f5be0dabb01fca536147bfe2c66bad8
 SHA512:
-  metadata.gz: e9e60d630f8342707559a591f9e26c28e331fe52e4a5a044c2ca20064bc29ecfd261e674772e38bdd15dc28db276bb6669de4950abfe0035e3aca35bba308f37
-  data.tar.gz: 1263e9a72388a55792ed26437fbc192c4f3cad40fcfaae86b2b5543d021a506413ffb81fbaf918542992caaaa508aa9e77edec2053c6f4a4e8a7d3d1f3acea91
+  metadata.gz: ed0b97db3cec8503eba509f232a463d8566373b34ccaf5fe7cd130a72e712cde17b083b4ce94ef64fa84786d6e6aec8965423ca6b8a7471ada70ebd522956e2a
+  data.tar.gz: 0747a93bef059a8eccf0f504e703d20ddc875f8c562db8f01d3af4050bf7562deb262eb4494db4d98b78665f91274ed77754fa76e99254b8592b7e0f1526aa13

data/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.14.0 — 2026-04-22
+
+### Added
+- `BSV::Network::WhatsOnChain` expanded with `current_height`,
+  `get_block_header(height)`, and `valid_root_for_height?(root, height)` —
+  a single WhatsOnChain instance now serves as a complete chain data source
+  (#596)
+- BEEF-based SPV verification conformance tests (#607)
+
+### Changed
+- `Transaction#verify` now raises `VerificationError` for all failure modes:
+  `:script_failure` (wraps `ScriptError` with cause chaining),
+  `:missing_source` (replaces `ArgumentError`), `:invalid_merkle_proof`,
+  `:insufficient_fee`, and `:output_overflow`. Code rescuing `ArgumentError`
+  or `ScriptError` from `verify` must switch to `VerificationError` (#608)
+- Removed dead code: `BSV::Wallet::Wallet` (superseded by bsv-wallet gem's
+  `Client`), `BSV::Messages` (unused re-export alias), and duplicate
+  `BSV::Wallet::InsufficientFundsError` (#594)
+
+### Fixed
+- WhatsOnChain `valid_root_for_height?` YARD doc now correctly documents
+  that 404 returns `false` rather than raising
+
+## 0.13.0 — 2026-04-21
+
+### Added
+- Protocol layer: base class with declarative DSL, HTTP dispatch, and Result value types
+- WoCREST protocol with transaction detail, script query, exchange rate, fee, mempool, SPV, wallet, and address commands
+- ARC protocol with broadcast escape hatches and enriched response data
+- TAALBinary protocol with binary broadcast support
+- Chaintracks and Ordinals protocols with base_url override
+- Provider configuration container with block DSL and `.default(testnet:)` pattern
+- Provider introspection and capability matrix
+- Concrete provider defaults for GorillaPool, WhatsOnChain, and TAAL
+
+### Changed
+- Facades (ARC, WhatsOnChain, ChainTracker) hollowed out to delegate via Protocol
+- Removed `BSV::MAINNET_URL`/`TESTNET_URL` constants and ENV var reading — provider defaults are the single source of truth
+- Removed `BASE_URL` from protocols — `base_url:` is now mandatory
+- Wallet namespace reorganisation: `Store` and `BroadcastQueue` collaborators namespaced under `Client`
+- `ProtoWallet` and `WalletClient` replaced with `Client`
+
+### Fixed
+- Ruby 2.7 kwargs compatibility in `Protocol#call` and TAALBinary spec doubles
+- Nil-guard on WoCREST broadcast and ARC status metadata
+- ARC status rejection checks and TAALBinary nil-txid guard
+- `BSV::Wallet::Wallet` autoload failure in multi-gem setup
+- SimpleCov coverage gate now requires `COVERAGE=true` explicitly
+
 ## 0.12.1 — 2026-04-16
 
 ### Fixed

data/lib/bsv/auth/certificate.rb

@@ -21,7 +21,7 @@ module BSV
     #
     # Wallet parameters are duck-typed — any object responding to
     # +create_signature+, +verify_signature+, and +get_public_key+ is accepted.
-    # No direct dependency on +BSV::Wallet::ProtoWallet+ is introduced here.
+    # No direct dependency on +BSV::Wallet::Client+ is introduced here.
     #
     # @see https://hub.bsvblockchain.org/brc/wallet/0052 BRC-52
     class Certificate
@@ -166,17 +166,17 @@ module BSV
 
       # Verify the certificate's signature.
       #
-      # Uses a fresh +'anyone'+ ProtoWallet as the verifier, which matches the
+      # Uses a fresh +'anyone'+ Client as the verifier, which matches the
       # TS SDK behaviour. If no signature is present, raises +ArgumentError+.
       #
       # @param verifier_wallet [#verify_signature, nil] wallet to verify with;
-      #   defaults to +BSV::Wallet::ProtoWallet.new('anyone')+
+      #   defaults to +BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new)+
       # @return [Boolean] +true+ if the signature is valid
       # @raise [ArgumentError] if the certificate has no signature
       def verify(verifier_wallet = nil)
         raise ArgumentError, 'certificate has no signature to verify' if @signature.nil? || @signature.empty?
 
-        verifier_wallet ||= BSV::Wallet::ProtoWallet.new('anyone')
+        verifier_wallet ||= BSV::Wallet::Client.new('anyone', storage: BSV::Wallet::Store::Memory.new, allow_memory_store: true)
         preimage  = to_binary(include_signature: false)
         sig_bytes = [@signature].pack('H*').unpack('C*')
 

data/lib/bsv/auth/verifiable_certificate.rb

@@ -21,7 +21,7 @@ module BSV
     # - Counterparty: the certificate +subject+ public key
     #
     # Wallet parameters are duck-typed — any object responding to +:decrypt+
-    # is accepted. No direct dependency on +BSV::Wallet::ProtoWallet+ is
+    # is accepted. No direct dependency on +BSV::Wallet::Client+ is
     # introduced here.
     #
     # @see BSV::Auth::Certificate  base class

data/lib/bsv/network/arc.rb

@@ -1,35 +1,38 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'json'
-require 'uri'
-require 'securerandom'
-
 module BSV
   module Network
     # ARC broadcaster for submitting transactions to the BSV network.
     #
+    # This facade preserves the legacy public API contract while delegating all
+    # HTTP logic to +Protocols::ARC+. It translates +Result+ objects returned by
+    # the protocol into +BroadcastResponse+ instances or raised +BroadcastError+
+    # exceptions as required by consumer code.
+    #
     # Any object responding to #broadcast(tx) can serve as a broadcaster;
     # this class implements that contract using the ARC API.
-    #
-    # The HTTP client is injectable for testability. It must respond to
-    # #request(uri, request) and return an object with #code and #body.
     class ARC
       # Returns an ARC instance pointed at the GorillaPool public ARC endpoint.
       #
       # @param testnet [Boolean] when true, uses the GorillaPool testnet endpoint
-      # @param opts [Hash] forwarded to {#initialize} (e.g. +api_key:+, +callback_url:+)
+      # @param api_key [String, nil] optional bearer token for Authorization
+      # @param http_client [#request, nil] injectable HTTP client for testing
+      # @param opts [Hash] ARC-specific options forwarded to the protocol
+      #   (e.g. +deployment_id:+, +callback_url:+, +callback_token:+)
       # @return [ARC]
-      def self.default(testnet: false, **opts)
-        url = testnet ? TESTNET_URL : MAINNET_URL
-        new(url, **opts)
+      def self.default(testnet: false, api_key: nil, http_client: nil, **opts)
+        provider = Providers::GorillaPool.default(testnet: testnet)
+        arc_protocol = provider.protocol_for(:broadcast)
+        base_url = arc_protocol.base_url
+        new(
+          base_url,
+          api_key: api_key,
+          http_client: http_client,
+          **opts
+        )
       end
 
       # ARC response statuses that indicate the transaction was NOT accepted.
-      # Matches the TypeScript SDK's ARC broadcaster failure set (issue #305,
-      # finding F5.13). Prior to this fix, Ruby only recognised REJECTED and
-      # DOUBLE_SPEND_ATTEMPTED, silently treating INVALID / MALFORMED /
-      # MINED_IN_STALE_BLOCK responses as successful broadcasts.
       REJECTED_STATUSES = %w[
         REJECTED
         DOUBLE_SPEND_ATTEMPTED
@@ -38,10 +41,11 @@ module BSV
         MINED_IN_STALE_BLOCK
       ].freeze
 
-      # Substring match for orphan detection in txStatus or extraInfo fields.
-      ORPHAN_MARKER = 'ORPHAN'
-
-      # @param url [String] ARC base URL (without trailing slash)
+      # @param url_or_protocol [String, Protocols::ARC] ARC base URL (without
+      #   trailing slash) or a pre-configured +Protocols::ARC+ instance. When a
+      #   URL string is supplied, the remaining keyword arguments are forwarded to
+      #   the underlying protocol constructor. When a protocol instance is supplied,
+      #   all keyword arguments are ignored.
       # @param api_key [String, nil] optional bearer token for Authorization
       # @param deployment_id [String, nil] optional deployment identifier for
       #   the +XDeployment-ID+ header; defaults to a per-instance random value
@@ -50,246 +54,113 @@ module BSV
       # @param callback_token [String, nil] optional +X-CallbackToken+ for
       #   ARC status callback authentication
       # @param http_client [#request, nil] injectable HTTP client for testing
-      def initialize(url, api_key: nil, deployment_id: nil, callback_url: nil,
+      def initialize(url_or_protocol, api_key: nil, deployment_id: nil, callback_url: nil,
                      callback_token: nil, http_client: nil)
-        @url = url.chomp('/')
-        @api_key = api_key
-        @deployment_id = deployment_id || "bsv-ruby-sdk-#{SecureRandom.hex(8)}"
-        @callback_url = callback_url
-        @callback_token = callback_token
-        @http_client = http_client
+        @protocol =
+          if url_or_protocol.is_a?(String)
+            Protocols::ARC.new(
+              base_url: url_or_protocol,
+              api_key: api_key,
+              deployment_id: deployment_id,
+              callback_url: callback_url,
+              callback_token: callback_token,
+              http_client: http_client
+            )
+          else
+            url_or_protocol
+          end
       end
 
       # Submit a transaction to ARC.
       #
-      # The transaction is encoded as Extended Format (BRC-30) hex when every
-      # input has +source_satoshis+ and +source_locking_script+ populated,
-      # which lets ARC validate sighashes without fetching parents. Falls back
-      # to plain raw-tx hex when EF is unavailable.
-      #
       # @param tx [Transaction] the transaction to broadcast
-      # @param wait_for [String, nil] ARC wait condition — one of
-      #   'RECEIVED', 'STORED', 'ANNOUNCED_TO_NETWORK',
-      #   'SEEN_ON_NETWORK', or 'MINED'. When set, ARC holds the
-      #   connection open until the transaction reaches the requested
-      #   state (or times out). Defaults to nil (no wait).
-      # @param skip_fee_validation [Boolean, nil] when truthy, sends the
-      #   +X-SkipFeeValidation: true+ header, asking ARC to bypass its
-      #   minimum-fee check. Useful for zero-fee data transactions or
-      #   during local testing. Defaults to nil (fee validation applies).
-      # @param skip_script_validation [Boolean, nil] when truthy, sends the
-      #   +X-SkipScriptValidation: true+ header, asking ARC to bypass
-      #   script correctness checks. Defaults to nil (script validation
-      #   applies).
+      # @param wait_for [String, nil] ARC wait condition
+      # @param skip_fee_validation [Boolean, nil] when truthy, sends X-SkipFeeValidation header
+      # @param skip_script_validation [Boolean, nil] when truthy, sends X-SkipScriptValidation header
       # @return [BroadcastResponse]
       # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
       #   rejected/orphan +txStatus+
       def broadcast(tx, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
-        uri = URI("#{@url}/v1/tx")
-        request = build_post_request(uri, wait_for: wait_for,
-                                          skip_fee_validation: skip_fee_validation,
-                                          skip_script_validation: skip_script_validation)
-        request.body = JSON.generate(rawTx: raw_tx_hex(tx))
-
-        response = execute(uri, request)
-        handle_broadcast_response(response)
+        result = @protocol.call(
+          :broadcast, tx,
+          wait_for: wait_for,
+          skip_fee_validation: skip_fee_validation,
+          skip_script_validation: skip_script_validation
+        )
+        result_to_response!(result)
       end
 
       # Submit multiple transactions to ARC in a single batch request.
       #
-      # Each transaction is encoded as Extended Format (BRC-30) hex where
-      # possible, falling back to plain raw-tx hex per transaction independently.
-      #
-      # Returns a mixed array of {BroadcastResponse} and {BroadcastError} objects
-      # — one element per submitted transaction in the same order. Per-transaction
-      # rejections are returned as {BroadcastError} values rather than raised, so
-      # callers can inspect the full result set even when some transactions fail.
-      # Only HTTP-level errors (non-2xx) raise a {BroadcastError} for the whole
-      # batch.
+      # Returns a mixed array of {BroadcastResponse} and {BroadcastError} objects.
+      # Per-transaction rejections are returned as {BroadcastError} values rather
+      # than raised. Only HTTP-level errors raise a {BroadcastError} for the whole batch.
       #
       # @param txs [Array<Transaction>] transactions to broadcast
-      # @param wait_for [String, nil] ARC wait condition (see {#broadcast})
-      # @param skip_fee_validation [Boolean, nil] when truthy, sends
-      #   +X-SkipFeeValidation: true+ for the batch request
-      # @param skip_script_validation [Boolean, nil] when truthy, sends
-      #   +X-SkipScriptValidation: true+ for the batch request
+      # @param wait_for [String, nil] ARC wait condition
+      # @param skip_fee_validation [Boolean, nil]
+      # @param skip_script_validation [Boolean, nil]
       # @return [Array<BroadcastResponse, BroadcastError>]
-      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
-      #   malformed (non-array) response body
+      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status
       def broadcast_many(txs, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
-        return [] if txs.empty?
-
-        uri = URI("#{@url}/v1/txs")
-        request = build_post_request(uri, wait_for: wait_for,
-                                          skip_fee_validation: skip_fee_validation,
-                                          skip_script_validation: skip_script_validation)
-        request.body = JSON.generate(txs.map { |tx| { rawTx: raw_tx_hex(tx) } })
+        result = @protocol.call(
+          :broadcast_many, txs,
+          wait_for: wait_for,
+          skip_fee_validation: skip_fee_validation,
+          skip_script_validation: skip_script_validation
+        )
 
-        response = execute(uri, request)
-        handle_batch_response(response)
+        case result
+        when Result::Success
+          result.data.map { |item| item_to_response_or_error(item) }
+        else
+          raise broadcast_error_from_result(result)
+        end
       end
 
       # Query the status of a previously submitted transaction.
-      # Returns BroadcastResponse on success, raises BroadcastError on failure.
+      #
+      # @param txid [String] transaction ID to query
+      # @return [BroadcastResponse]
+      # @raise [BroadcastError] on failure
       def status(txid)
-        uri = URI("#{@url}/v1/tx/#{txid}")
-        request = Net::HTTP::Get.new(uri)
-        request['XDeployment-ID'] = @deployment_id
-        apply_auth_header(request)
-
-        response = execute(uri, request)
-        handle_broadcast_response(response)
+        result = @protocol.call(:get_tx_status, txid)
+        result_to_response!(result)
       end
 
       private
 
-      # Prefer Extended Format (BRC-30) hex so ARC can validate sighashes
-      # without fetching parent transactions. Falls back to plain raw-tx hex
-      # when any input lacks source_satoshis / source_locking_script.
-      def raw_tx_hex(tx)
-        tx.to_ef_hex
-      rescue ArgumentError
-        tx.to_hex
-      end
-
-      def build_post_request(uri, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
-        request = Net::HTTP::Post.new(uri)
-        request['Content-Type'] = 'application/json'
-        request['XDeployment-ID'] = @deployment_id
-        request['X-WaitFor'] = wait_for if wait_for
-        request['X-CallbackUrl'] = @callback_url if @callback_url
-        request['X-CallbackToken'] = @callback_token if @callback_token
-        request['X-SkipFeeValidation'] = 'true' if skip_fee_validation
-        request['X-SkipScriptValidation'] = 'true' if skip_script_validation
-        apply_auth_header(request)
-        request
-      end
-
-      def apply_auth_header(request)
-        request['Authorization'] = "Bearer #{@api_key}" if @api_key
-      end
-
-      def execute(uri, request)
-        if @http_client
-          @http_client.request(uri, request)
+      # Translate a single-tx Result into a BroadcastResponse or raise BroadcastError.
+      def result_to_response!(result)
+        case result
+        when Result::Success
+          BroadcastResponse.new(result.data)
         else
-          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
-            http.request(request)
-          end
+          raise broadcast_error_from_result(result)
         end
       end
 
-      def handle_broadcast_response(response)
-        body = parse_json(response.body)
-        code = response.code.to_i
-
-        unless (200..299).cover?(code)
-          raise BroadcastError.new(
-            body['detail'] || body['title'] || "HTTP #{code}",
-            status_code: code,
-            txid: body['txid']
-          )
-        end
-
-        if rejected_status?(body)
-          raise BroadcastError.new(
-            body['detail'] || body['title'] || body['txStatus'],
-            status_code: code,
-            txid: body['txid'],
-            arc_status: body['txStatus'].to_s.upcase
-          )
-        end
-
-        # A 2xx response without a txid is a malformed ARC reply —
-        # `parse_json` falls back to `{'detail' => raw}` on non-JSON,
-        # which would otherwise produce a `BroadcastResponse` full of
-        # `nil`s and `success? => true`. That's the same silent
-        # success-as-failure class of bug F5.13 closed for explicit
-        # error statuses; closing it here for shape corruption too.
-        unless body['txid']
-          raise BroadcastError.new(
-            'ARC returned a malformed 2xx response',
-            status_code: code
-          )
+      # Translate a per-item batch Result into a BroadcastResponse or BroadcastError
+      # (returned, not raised).
+      def item_to_response_or_error(item)
+        case item
+        when Result::Success
+          BroadcastResponse.new(item.data)
+        else
+          broadcast_error_from_result(item)
         end
-
-        build_response(body)
-      end
-
-      def rejected_status?(body)
-        # Case-insensitive match — the TypeScript reference
-        # (`ts-sdk/src/transaction/broadcasters/ARC.ts:155-166`) explicitly
-        # `.toUpperCase()`s both fields before membership / substring checks.
-        # ARC has a documented history of emitting values outside its own
-        # OpenAPI enum (e.g. `txStatus: "success"` for orphans in TS issue
-        # #105), so case normalisation is the defensive choice.
-        tx_status = body['txStatus'].to_s.upcase
-        return true if REJECTED_STATUSES.include?(tx_status)
-        return true if tx_status.include?(ORPHAN_MARKER)
-
-        extra_info = body['extraInfo'].to_s.upcase
-        return true if extra_info.include?(ORPHAN_MARKER)
-
-        false
       end
 
-      def parse_json(raw)
-        JSON.parse(raw)
-      rescue JSON::ParserError
-        { 'detail' => raw }
-      end
-
-      def build_response(body)
-        BroadcastResponse.new(
-          txid: body['txid'],
-          tx_status: body['txStatus'],
-          message: body['title'],
-          extra_info: body['extraInfo'],
-          block_hash: body['blockHash'],
-          block_height: body['blockHeight'],
-          timestamp: body['timestamp'],
-          competing_txs: body['competingTxs']
+      # Build a BroadcastError from a Result::Error or Result::NotFound.
+      def broadcast_error_from_result(result)
+        meta = result.metadata || {}
+        BroadcastError.new(
+          result.message,
+          status_code: meta[:status_code],
+          txid: meta[:txid],
+          arc_status: meta[:arc_status]
         )
       end
-
-      def handle_batch_response(response)
-        code = response.code.to_i
-        body = parse_json(response.body)
-
-        unless (200..299).cover?(code)
-          raise BroadcastError.new(
-            body['detail'] || body['title'] || "HTTP #{code}",
-            status_code: code
-          )
-        end
-
-        unless body.is_a?(Array)
-          raise BroadcastError.new(
-            'ARC returned a malformed batch response',
-            status_code: code
-          )
-        end
-
-        body.map { |item| build_response_or_error(item) }
-      end
-
-      def build_response_or_error(body)
-        if rejected_status?(body)
-          BroadcastError.new(
-            body['detail'] || body['title'] || body['txStatus'],
-            status_code: 200,
-            txid: body['txid'],
-            arc_status: body['txStatus'].to_s.upcase
-          )
-        elsif !body['txid']
-          BroadcastError.new(
-            'ARC returned a malformed 2xx response',
-            status_code: 200
-          )
-        else
-          build_response(body)
-        end
-      end
     end
   end
 end