bsv-sdk 0.19.1 → 0.22.0

data/lib/bsv/primitives/curve.rb

@@ -98,21 +98,11 @@ module BSV
 
       # Add two curve points together.
       #
-      # Uses +Point#add+ where available (Ruby 3.0+ / OpenSSL 3), falling
-      # back to multi-scalar multiplication for Ruby 2.7 compatibility.
-      #
       # @param point_a [OpenSSL::PKey::EC::Point] first point
       # @param point_b [OpenSSL::PKey::EC::Point] second point
       # @return [OpenSSL::PKey::EC::Point] the sum of the two points
       def add_points(point_a, point_b)
-        if point_a.respond_to?(:add)
-          point_a.add(point_b)
-        else
-          # Ruby 2.7 / OpenSSL < 3: use multi-scalar mul
-          # point_a.mul(bns, points) = bns[0]*point_a + bns[1]*points[0] + ...
-          one = OpenSSL::BN.new('1')
-          point_a.mul([one, one], [point_b])
-        end
+        point_a.add(point_b)
       end
 
       # Extract the x-coordinate from a curve point as a big number.

data/lib/bsv/primitives/ecies.rb

@@ -210,14 +210,7 @@ module BSV
         def secure_compare(mac, expected)
           return false unless mac.bytesize == expected.bytesize
 
-          if OpenSSL.respond_to?(:fixed_length_secure_compare)
-            OpenSSL.fixed_length_secure_compare(mac, expected)
-          else
-            # Constant-time comparison for Ruby < 3.2
-            result = 0
-            mac.bytes.zip(expected.bytes) { |x, y| result |= x ^ y }
-            result.zero?
-          end
+          OpenSSL.fixed_length_secure_compare(mac, expected)
         end
 
         def derive_keys(private_key, public_key)

data/lib/bsv/primitives/hex.rb

@@ -22,7 +22,7 @@ module BSV
     module Hex
       # Matches an even number of hex characters (case-insensitive).
       # Empty string is valid (decodes to empty bytes).
-      HEX_RE = /\A(?:[0-9a-fA-F]{2})*\z/n.freeze
+      HEX_RE = /\A(?:[0-9a-fA-F]{2})*\z/n
       private_constant :HEX_RE
 
       # Test whether +str+ is valid hex (even-length, hex-only).

data/lib/bsv/script/script.rb

@@ -334,7 +334,7 @@ module BSV
       }.freeze
 
       # Reverse lookup: opcode → hash type symbol (excludes :raw).
-      RPUZZLE_OP_TO_TYPE = RPUZZLE_HASH_OPS.reject { |k, _| k == :raw }.invert.freeze
+      RPUZZLE_OP_TO_TYPE = RPUZZLE_HASH_OPS.except(:raw).invert.freeze
 
       # The fixed opcode prefix shared by all RPuzzle locking scripts.
       # OP_OVER OP_3 OP_SPLIT OP_NIP OP_1 OP_SPLIT OP_SWAP OP_SPLIT OP_DROP

data/lib/bsv/transaction/beef.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module BSV
   module Transaction
     # Background Evaluation Extended Format (BEEF) for SPV-ready transaction

data/lib/bsv/transaction/chain_tracker.rb

@@ -10,18 +10,21 @@ module BSV
     # chain tracker is the data source: an object the consumer provides
     # that can answer "is this merkle root valid for this block height?"
     #
-    # The SDK is deliberately unopinionated about where that answer comes
-    # from. A chain tracker backed by an in-memory hash is declarative.
-    # One that fetches from the network on cache miss and writes to a
-    # database is imperative. The verify methods don't care — they just
-    # ask the question. All imperative behaviour (fetching, caching,
-    # persisting) lives in the consumer's chain tracker implementation,
-    # not in the SDK.
+    # This class is a working default implementation that wraps a
+    # {BSV::Network::Provider} and dispatches via {Provider#call}. The
+    # provider must serve the +:get_block_header+ and +:current_height+
+    # commands (e.g. a provider configured with {Protocols::JungleBus}).
+    #
+    # Subclasses may override either or both methods to supply their own
+    # data source (in-memory hash, database cache, etc.) without touching
+    # the provider at all. The +provider+ argument is optional precisely to
+    # preserve this pattern — a subclass that overrides both methods never
+    # reaches the provider-dispatch path.
     #
     # Any object responding to +valid_root_for_height?+ and
     # +current_height+ satisfies this interface. Inheriting from this
     # class is optional — it exists to document the contract and provide
-    # clear error messages when methods are missing.
+    # a ready-to-use provider-backed implementation.
     #
     # @example In-memory chain tracker (test / declarative)
     #   class HashTracker < BSV::Transaction::ChainTracker
@@ -38,23 +41,81 @@ module BSV
     #       header.merkle_root == root
     #     end
     #   end
+    #
+    # @example Provider-backed (default impl)
+    #   tracker = BSV::Transaction::ChainTracker.default
+    #   tracker.valid_root_for_height?('abcd...', 800_000)
+    #
+    # @example Testnet
+    #   tracker = BSV::Transaction::ChainTracker.default(testnet: true)
+    #   tracker.current_height
     class ChainTracker
+      # @return [BSV::Network::Provider, nil] the underlying provider, if any
+      attr_reader :provider
+
+      # Return a default ChainTracker backed by the GorillaPool provider.
+      #
+      # @param testnet [Boolean] when true, uses the testnet provider
+      # @return [ChainTracker]
+      def self.default(testnet: false)
+        new(BSV::Network::Providers::GorillaPool.default(testnet: testnet))
+      end
+
+      # @param provider [BSV::Network::Provider, nil] provider serving +:get_block_header+
+      #   and +:current_height+. Optional when the subclass overrides both methods.
+      def initialize(provider = nil)
+        @provider = provider
+      end
+
       # Verify that a merkle root is valid for the given block height.
       #
+      # Dispatches +:get_block_header+ to the configured provider. Returns +false+
+      # on 404 (block not found). Normalises the merkle root field name from any
+      # of +merkleroot+, +merkleRoot+, or +merkle_root+.
+      #
       # @param root [String] merkle root as a hex string
       # @param height [Integer] block height
       # @return [Boolean] true if the root matches the block at the given height
-      # @raise [NotImplementedError] if not overridden by a subclass
-      def valid_root_for_height?(_root, _height)
-        raise NotImplementedError, "#{self.class}#valid_root_for_height? must be implemented"
+      # @raise [RuntimeError] when no provider is configured
+      # @raise [RuntimeError] on network or API error
+      def valid_root_for_height?(root, height)
+        raise 'ChainTracker requires a provider when used directly' if @provider.nil?
+
+        result = @provider.call(:get_block_header, height)
+        return false if result.http_not_found?
+        raise result.error_message.to_s unless result.http_success?
+
+        actual = normalise_merkle_root(result.data)
+        return false unless actual
+
+        actual.casecmp(root).zero?
       end
 
       # Return the current blockchain height.
       #
+      # Dispatches +:current_height+ to the configured provider.
+      #
       # @return [Integer] the height of the chain tip
-      # @raise [NotImplementedError] if not overridden by a subclass
+      # @raise [RuntimeError] when no provider is configured
+      # @raise [RuntimeError] on network or API error
       def current_height
-        raise NotImplementedError, "#{self.class}#current_height must be implemented"
+        raise 'ChainTracker requires a provider when used directly' if @provider.nil?
+
+        result = @provider.call(:current_height)
+        return result.data if result.http_success?
+
+        raise result.error_message.to_s
+      end
+
+      private
+
+      # Field-name diversity belongs at the Protocols::* layer; this is a
+      # transitional shim until the wire protocols return canonical shapes.
+      # See #791.
+      def normalise_merkle_root(body)
+        return nil unless body.is_a?(Hash)
+
+        body['merkleroot'] || body['merkleRoot'] || body['merkle_root']
       end
     end
   end

data/lib/bsv/transaction/chain_trackers/whats_on_chain.rb

@@ -20,10 +20,10 @@ module BSV
         # Returns a WhatsOnChain chain tracker using the provider default.
         #
         # @param testnet [Boolean] when true, uses the testnet endpoint
-        # @param opts [Hash] forwarded to the underlying protocol (e.g. +api_key:+, +http_client:+)
+        # @param ** [Hash] forwarded to the underlying protocol (e.g. +api_key:+, +http_client:+)
         # @return [WhatsOnChain]
-        def self.default(testnet: false, **opts)
-          provider = BSV::Network::Providers::WhatsOnChain.default(testnet: testnet, **opts)
+        def self.default(testnet: false, **)
+          provider = BSV::Network::Providers::WhatsOnChain.default(testnet: testnet, **)
           new(protocol: provider.protocol_for(:valid_root))
         end
 

data/lib/bsv/transaction/chain_trackers.rb

@@ -5,16 +5,6 @@ module BSV
     # Namespace for chain tracker implementations.
     module ChainTrackers
       autoload :WhatsOnChain, 'bsv/transaction/chain_trackers/whats_on_chain'
-      autoload :Chaintracks,  'bsv/transaction/chain_trackers/chaintracks'
-
-      # Return a default chain tracker backed by the Arcade/GorillaPool Chaintracks API.
-      #
-      # @param testnet [Boolean] use the testnet endpoint when true
-      # @param opts [Hash] forwarded to the underlying tracker (e.g. +api_key:+)
-      # @return [Chaintracks]
-      def self.default(testnet: false, **opts)
-        Chaintracks.default(testnet: testnet, **opts)
-      end
     end
   end
 end

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

@@ -16,7 +16,7 @@ module BSV
       #
       # @example
       #   model = BSV::Transaction::FeeModels::LivePolicy.new(
-      #     arc_url: 'https://arcade.gorillapool.io',
+      #     arc_url: 'https://arc.taal.com',
       #     fallback_rate: 50
       #   )
       #   fee = model.compute_fee(transaction)
@@ -34,18 +34,20 @@ module BSV
 
         DEFAULT_FALLBACK_RATE = 100
 
-        # Returns a LivePolicy with sensible defaults (GorillaPool ARC,
-        # 100 sat/kB fallback, 5-minute cache).
+        # TAAL still runs a public ARC instance that serves /v1/policy.
+        # Full policy access may require a TAAL API key.
+        TAAL_ARC_URL = 'https://arc.taal.com'
+
+        # Returns a LivePolicy using TAAL ARC for fee policy, 100 sat/kB fallback,
+        # and a 5-minute cache.
         #
-        # @param api_key [String, nil] optional ARC API key
+        # @param api_key [String, nil] optional TAAL API key for authenticated policy access
         # @return [LivePolicy]
         def self.default(api_key: nil)
-          provider = BSV::Network::Providers::GorillaPool.mainnet
-          arc_protocol = provider.protocol_for(:broadcast)
-          new(arc_url: arc_protocol.base_url, fallback_rate: DEFAULT_FALLBACK_RATE, api_key: api_key)
+          new(arc_url: TAAL_ARC_URL, fallback_rate: DEFAULT_FALLBACK_RATE, api_key: api_key)
         end
 
-        # @param arc_url [String] ARC base URL (e.g. 'https://arcade.gorillapool.io')
+        # @param arc_url [String] ARC base URL (e.g. 'https://arc.taal.com')
         # @param fallback_rate [Integer] sat/kB to use when fetch fails (default: 100)
         # @param cache_ttl [Integer] seconds to cache a fetched rate (default: 300)
         # @param api_key [String, nil] optional Bearer token for ARC authentication

data/lib/bsv/transaction/merkle_path.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module BSV
   module Transaction
     # A BRC-74 merkle path (BUMP — Bitcoin Unified Merkle Path).

data/lib/bsv/version.rb

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

data/lib/bsv/wallet/errors.rb

@@ -3,44 +3,88 @@
 module BSV
   module Wallet
     # Base error for all wallet operations. Carries a machine-readable code
-    # per the BRC-100 error structure.
+    # per the BRC-100 error structure and a wire-protocol stack string.
     class Error < StandardError
-      attr_reader :code
+      attr_reader :code, :wallet_stack
 
-      def initialize(message, code = 1)
+      def initialize(message = nil, code: 1, stack: '')
         @code = code
-        super(message)
+        @wallet_stack = stack
+        super(message || '')
       end
-    end
 
-    # Raised when a required parameter is missing or invalid.
-    class InvalidParameterError < Error
-      attr_reader :parameter
+      # Serialise to a hash suitable for embedding in a wire result frame.
+      # Never leaks Ruby's internal backtrace — only the wallet_stack string.
+      def to_wire
+        { code: code, message: message.to_s, stack: wallet_stack.to_s }
+      end
+    end
 
-      def initialize(parameter, must_be = 'valid')
-        @parameter = parameter
-        super("the #{parameter} parameter must be #{must_be}", 6)
+    # Code 2 — operation not supported by this wallet implementation.
+    class UnsupportedActionError < Error
+      def initialize(message = 'this method is not supported by this wallet implementation', stack: '')
+        super(message, code: 2, stack: stack)
       end
     end
 
-    # Raised when an HMAC fails to verify.
+    # Code 3 — HMAC verification failed.
     class InvalidHmacError < Error
-      def initialize(message = 'the provided HMAC is invalid')
-        super(message, 3)
+      def initialize(message = 'the provided HMAC is invalid', stack: '')
+        super(message, code: 3, stack: stack)
       end
     end
 
-    # Raised when a signature fails to verify.
+    # Code 4 — signature verification failed.
     class InvalidSignatureError < Error
-      def initialize(message = 'the provided signature is invalid')
-        super(message, 4)
+      def initialize(message = 'the provided signature is invalid', stack: '')
+        super(message, code: 4, stack: stack)
       end
     end
 
-    # Raised when an operation is not supported by this wallet implementation.
-    class UnsupportedActionError < Error
-      def initialize(method_name = 'this method')
-        super("#{method_name} is not supported by this wallet implementation", 2)
+    # Code 5 — wallet has insufficient funds for the requested operation.
+    class InsufficientFundsError < Error
+      def initialize(message = 'insufficient funds', stack: '')
+        super(message, code: 5, stack: stack)
+      end
+    end
+
+    # Code 6 — a required parameter is missing or invalid.
+    #
+    # Two calling conventions:
+    #   InvalidParameterError.new('pubkey', 'a hex string')  # raises "the pubkey parameter must be ..."
+    #   InvalidParameterError.new('raw message')              # wire-rehydration path
+    class InvalidParameterError < Error
+      attr_reader :parameter
+
+      def initialize(parameter, must_be = nil, stack: '')
+        @parameter = must_be ? parameter : nil
+        message = must_be ? "the #{parameter} parameter must be #{must_be}" : parameter
+        super(message, code: 6, stack: stack)
+      end
+    end
+
+    # Code 7 — actions require review before they can be processed.
+    class ReviewActionsError < Error
+      def initialize(message = 'actions require review', stack: '')
+        super(message, code: 7, stack: stack)
+      end
+    end
+
+    # Rehydrate a wire error frame into the appropriate subclass.
+    #
+    # @param code [Integer] error code byte from the result frame
+    # @param message [String] error message from the frame
+    # @param stack [String] stack trace from the frame (may be empty)
+    # @return [Error] an instance of the matching subclass
+    def self.error_from_wire(code, message, stack = '')
+      case code
+      when 2 then UnsupportedActionError.new(message, stack: stack)
+      when 3 then InvalidHmacError.new(message, stack: stack)
+      when 4 then InvalidSignatureError.new(message, stack: stack)
+      when 5 then InsufficientFundsError.new(message, stack: stack)
+      when 6 then InvalidParameterError.new(message, nil, stack: stack)
+      when 7 then ReviewActionsError.new(message, stack: stack)
+      else        Error.new(message, code: code, stack: stack)
       end
     end
   end

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

@@ -5,68 +5,26 @@ module BSV
     class ProtoWallet
       # Validation helpers for BRC-100 wallet method parameters.
       #
-      # Provides the subset of validators required by KeyDeriver and ProtoWallet.
-      # Raises +InvalidParameterError+ for any invalid input.
+      # Delegates to Wire::Validation — the single source of truth for all
+      # BRC-100 parameter validation. This module is retained for backwards
+      # compatibility with ProtoWallet's internal call sites.
       module Validators
         module_function
 
-        # Validates a BRC-43 protocol ID.
-        #
-        # Must be an Array of [Integer(0-2), String(5-400 chars)]. The name is
-        # normalized (stripped and downcased) before length/content checks.
-        #
-        # @param protocol_id [Object] the value to validate
-        # @raise [InvalidParameterError]
         def validate_protocol_id!(protocol_id)
-          unless protocol_id.is_a?(Array) && protocol_id.length == 2
-            raise InvalidParameterError.new('protocol_id', 'an Array of [security_level, protocol_name]')
-          end
-
-          level, name = protocol_id
-          raise InvalidParameterError.new('protocol_id security level', '0, 1, or 2') unless [0, 1, 2].include?(level)
-          raise InvalidParameterError.new('protocol_id name', 'a String') unless name.is_a?(String)
-
-          name = name.strip.downcase
-          max_length = name.start_with?('specific linkage revelation') ? 430 : 400
-          raise InvalidParameterError.new('protocol_id name', "between 5 and #{max_length} characters") if name.length < 5 || name.length > max_length
-
-          raise InvalidParameterError.new('protocol_id name', 'lowercase letters, numbers, and spaces only') unless name.match?(/\A[a-z0-9 ]+\z/)
-
-          raise InvalidParameterError.new('protocol_id name', 'free of consecutive spaces') if name.include?('  ')
+          Wire::Validation.wallet_protocol!('protocol_id', protocol_id)
         end
 
-        # Validates a BRC-43 key ID.
-        #
-        # Must be a non-empty String of at most 800 bytes.
-        #
-        # @param key_id [Object] the value to validate
-        # @raise [InvalidParameterError]
         def validate_key_id!(key_id)
-          raise InvalidParameterError.new('key_id', 'a String') unless key_id.is_a?(String)
-
-          byte_length = key_id.bytesize
-          raise InvalidParameterError.new('key_id', 'between 1 and 800 bytes') if byte_length < 1 || byte_length > 800
+          Wire::Validation.key_id_string_1_to_800!('key_id', key_id)
         end
 
-        # Validates a counterparty: 'self', 'anyone', or a 66-char hex pubkey.
-        #
-        # @param counterparty [Object] the value to validate
-        # @raise [InvalidParameterError]
         def validate_counterparty!(counterparty)
-          return if %w[self anyone].include?(counterparty)
-
-          validate_pub_key_hex!(counterparty, 'counterparty')
+          Wire::Validation.wallet_counterparty!('counterparty', counterparty)
         end
 
-        # Validates a compressed public key in hex form (66 chars, 02/03/04 prefix).
-        #
-        # @param value [Object] the value to validate
-        # @param name [String] parameter name for error messages
-        # @raise [InvalidParameterError]
         def validate_pub_key_hex!(value, name = 'public_key')
-          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
-
-          raise InvalidParameterError.new(name, 'a 66-character hex string (compressed public key)') unless value.match?(/\A[0-9a-f]{66}\z/)
+          Wire::Validation.pub_key_hex!(name, value)
         end
       end
     end

data/lib/bsv/wallet/proto_wallet.rb

@@ -226,6 +226,8 @@ module BSV
       def reveal_counterparty_key_linkage(counterparty:, verifier:,
                                           privileged: false, privileged_reason: nil,
                                           originator: nil)
+        counterparty = normalise_pubkey_hex(counterparty)
+        verifier     = normalise_pubkey_hex(verifier)
         raise InvalidParameterError.new('counterparty', 'a specific public key hex, not "anyone"') if counterparty == 'anyone'
 
         Validators.validate_pub_key_hex!(verifier, 'verifier')
@@ -281,6 +283,8 @@ module BSV
       def reveal_specific_key_linkage(counterparty:, verifier:, protocol_id:, key_id:,
                                       privileged: false, privileged_reason: nil,
                                       originator: nil)
+        counterparty = normalise_pubkey_hex(counterparty)
+        verifier     = normalise_pubkey_hex(verifier)
         raise InvalidParameterError.new('counterparty', 'a specific public key hex, not "anyone"') if counterparty == 'anyone'
 
         Validators.validate_pub_key_hex!(verifier, 'verifier')
@@ -340,7 +344,16 @@ module BSV
       end
 
       def bytes_to_string(bytes)
-        bytes.pack('C*')
+        bytes.is_a?(String) ? bytes.b : bytes.pack('C*')
+      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)
+        return value if value.is_a?(String) && value.length == 66
+        return value.unpack1('H*') if value.is_a?(String) && value.bytesize == 33
+
+        value
       end
 
       def string_to_bytes(str)
@@ -350,13 +363,7 @@ module BSV
       def secure_compare(a, b)
         return false unless a.bytesize == b.bytesize
 
-        if OpenSSL.respond_to?(:fixed_length_secure_compare)
-          OpenSSL.fixed_length_secure_compare(a, b)
-        else
-          result = 0
-          a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
-          result.zero?
-        end
+        OpenSSL.fixed_length_secure_compare(a, b)
       end
     end
   end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +abort_action+ call (call byte 3).
+      #
+      # Args wire layout:
+      #   [remaining bytes: reference (raw binary)]
+      #
+      # Result wire layout:
+      #   [empty — success is implicit from the frame error byte]
+      module AbortAction
+        module_function
+
+        def serialize_args(args)
+          ref = args[:reference]
+          return ''.b if ref.nil? || ref.empty?
+
+          ref.b
+        end
+
+        def deserialize_args(bytes)
+          ref = bytes.b
+          { reference: ref.empty? ? nil : ref }
+        end
+
+        def serialize_result(_result)
+          ''.b
+        end
+
+        def deserialize_result(_bytes)
+          { aborted: true }
+        end
+      end
+    end
+  end
+end