bsv-wallet 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 832766edaf4b3b59b4a5a2bdf47e997972b62336ddbf65614e5445f254615fa4
-  data.tar.gz: c2bb017e369d5b7497c134fde1d5fd729e8952cc8a11bb04c05eaa6ad7f6ebf2
+  metadata.gz: c71d9a7e4b68e5d47c4d95e3a8bcd6c23c698a92ca3faa4809a9a7abf1171b8e
+  data.tar.gz: f61618ef74ba89eae855dc710244f5a9208bff34a2244f4bb2ab6425d6774fea
 SHA512:
-  metadata.gz: b2861431435b2e6aa871cbb6dfdc020f8a1c010eef487606efa9f0d1de9f8bd5ef6c6f2384eea98c621d72bb9be0175e280de47ac927f3effb4b11e931528d0f
-  data.tar.gz: b08fc27ca7a74a3f98e9df12190d7198296d8e91527848edba41e288066fbc6e164d9b13e793666232489a8edae7dacc514340058542be7d99e060db4eb5e754
+  metadata.gz: 9c9d6badbfaac1bb19ed0bf5745ccfe21aba5372822e692be72f1065df56175481277e8f1b41daf4c17dd0acc758e43a2dcf73d4e8c96147d982dafd7b7a7ca3
+  data.tar.gz: 161733d4e9c277c55d4e3b1d89eab89bf156d066575c3f924e066c636d55f65606cd1e4df7afdbbdf0ff8cea615d5d6c09c30aafc63773294370c22659a3bf85

data/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to the `bsv-wallet` 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.8.0 — 2026-04-15
+
+### Added
+- BRC-100 substrates: `HTTPWalletJSON` for JSON-over-HTTP, `HTTPWalletWire`
+  for binary transport, and `WalletWireTransceiver` Interface adapter (#449–#451)
+- `WalletClient` accepts `substrate:` constructor param for remote wallet
+  delegation — all Interface methods delegate to the substrate when set (#452)
+- `list_actions` and `list_outputs` honour `include_labels`, `include_inputs`,
+  and `include_outputs` flags (#448)
+- `acquire_certificate` uses `AuthFetch` for BRC-104 authenticated certificate
+  issuance (#453)
+
+### Fixed
+- `prove_certificate` now uses correct protocol ID (`'certificate field encryption'`)
+  and key ID format (`"#{serial_number} #{field_name}"`) matching TS/Go SDKs —
+  previously incompatible cross-SDK (#424)
+- Code review findings addressed for substrates and include flags
+
+### Changed
+- `BSV::WalletInterface` module removed — `VERSION` now lives in `BSV::Wallet::VERSION`
+  where all other wallet constants already reside
+
+## 0.7.0 — 2026-04-12
+
+### Added
+- Pluggable `BroadcastQueue` interface module — duck-typed, follows the `StorageAdapter` pattern
+- `InlineQueue` synchronous default adapter — consolidates broadcast and no-broadcaster paths
+- `WalletClient` accepts `broadcast_queue:` constructor parameter (auto-creates `InlineQueue` when not provided)
+- `BroadcastQueue.status_for_error` shared helper for consistent broadcast error mapping
+- Integration specs for broadcast/rollback flows (20 specs)
+- MemoryStore production warning — logs to stderr when `RACK_ENV`/`RAILS_ENV` is `production` or `staging`
+
+### Fixed
+- TOCTOU window on change outputs — stored as `:pending` directly, eliminating race with concurrent `auto_fund`
+- Broadcast promotion failure no longer deletes confirmed on-chain outputs — only broadcast failure triggers rollback
+
+### Changed
+- `accept_delayed_broadcast: true` no longer logs "not yet implemented" warning — handled by the queue adapter
+- MemoryStore demoted to test/development only (production use triggers a suppressible warning)
+
 ## 0.6.0 — 2026-04-12
 
 ### Added

data/lib/bsv/wallet_interface/broadcast_queue.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Duck-typed broadcast queue interface for wallet transaction dispatch.
+    #
+    # Include this module in broadcast queue adapters and override all instance
+    # methods that raise +NotImplementedError+. The +async?+ method may be
+    # overridden to return +true+ for adapters that defer execution to a
+    # background worker.
+    #
+    # == Payload contract
+    #
+    # The +enqueue+ method receives a +Hash+ with the following keys:
+    #
+    #   {
+    #     tx:                       BSV::Transaction,  # signed transaction object
+    #     txid:                     String,            # hex txid
+    #     beef_binary:              String,            # raw BEEF bytes
+    #     input_outpoints:          Array<String>,     # locked input outpoints (nil on finalize path)
+    #     change_outpoints:         Array<String>,     # change outpoints (nil on finalize path)
+    #     fund_ref:                 String,            # fund reference for rollback (nil on finalize path)
+    #     accept_delayed_broadcast: Boolean            # from caller options
+    #   }
+    #
+    # When +input_outpoints+ is +nil+, the caller is on the finalize path and
+    # the adapter must skip UTXO state transitions.
+    #
+    # == Example
+    #
+    #   class MyQueue
+    #     include BSV::Wallet::BroadcastQueue
+    #
+    #     def async?
+    #       true
+    #     end
+    #
+    #     def enqueue(payload)
+    #       MyWorker.perform_later(payload[:txid])
+    #       { txid: payload[:txid] }
+    #     end
+    #
+    #     def status(txid)
+    #       MyWorker.status_for(txid)
+    #     end
+    #   end
+    module BroadcastQueue
+      # Enqueues a transaction for broadcast and state promotion.
+      #
+      # For synchronous adapters this executes immediately and returns the
+      # result. For asynchronous adapters this persists the job and returns
+      # a partial result; the caller should treat the action as pending.
+      #
+      # @param _payload [Hash] broadcast payload (see module-level doc for keys)
+      # @return [Hash] result hash containing at minimum +:txid+
+      # @raise [NotImplementedError] unless overridden by the including class
+      def enqueue(_payload)
+        raise NotImplementedError, "#{self.class}#enqueue not implemented"
+      end
+
+      # Returns +false+ by default, indicating synchronous execution.
+      #
+      # Override and return +true+ in adapters that defer broadcast to a
+      # background worker (e.g. SolidQueue, Sidekiq).
+      #
+      # @return [Boolean]
+      def async?
+        false
+      end
+
+      # Returns the broadcast status for a previously enqueued transaction.
+      #
+      # @param _txid [String] hex transaction identifier
+      # @return [String, nil] the current status string, or +nil+ if unknown
+      # @raise [NotImplementedError] unless overridden by the including class
+      def status(_txid)
+        raise NotImplementedError, "#{self.class}#status not implemented"
+      end
+
+      # Maps a broadcast exception to a {ReviewActionResultStatus} string.
+      #
+      # This shared helper is extracted from +WalletClient#broadcast_status_for+
+      # so all queue adapters can produce consistent status strings without
+      # duplicating the mapping logic.
+      #
+      # @param error [StandardError] the exception raised during broadcast
+      # @return [String] one of +'doubleSpend'+, +'invalidTx'+, +'serviceError'+
+      def self.status_for_error(error)
+        return 'serviceError' unless error.is_a?(BSV::Network::BroadcastError)
+
+        arc_status = error.arc_status.to_s.upcase
+        return 'doubleSpend' if arc_status == 'DOUBLE_SPEND_ATTEMPTED'
+
+        invalid_statuses = %w[REJECTED INVALID MALFORMED MINED_IN_STALE_BLOCK]
+        return 'invalidTx' if invalid_statuses.include?(arc_status) || arc_status.include?('ORPHAN')
+
+        'serviceError'
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/inline_queue.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Synchronous broadcast queue adapter — the default for +WalletClient+.
+    #
+    # +InlineQueue+ replicates the current wallet broadcast behaviour exactly:
+    #
+    # * With a broadcaster: calls +broadcaster.broadcast+, promotes UTXO state on
+    #   success, rolls back on failure.
+    # * Without a broadcaster: promotes immediately and returns BEEF for the
+    #   caller to broadcast manually (backwards-compatible fallback).
+    #
+    # Because this adapter executes synchronously, +async?+ returns +false+ and
+    # the caller can rely on the returned hash containing the final result.
+    class InlineQueue
+      include BSV::Wallet::BroadcastQueue
+
+      # @param broadcaster [#broadcast, nil] broadcaster object; +nil+ disables broadcasting
+      # @param storage [StorageAdapter] wallet storage adapter
+      def initialize(storage:, broadcaster: nil)
+        @broadcaster = broadcaster
+        @storage = storage
+      end
+
+      # Returns +false+ — this adapter executes synchronously.
+      #
+      # @return [Boolean]
+      def async?
+        false
+      end
+
+      # Returns the broadcast status for a previously enqueued transaction.
+      #
+      # Delegates to storage and returns the action status field, or +nil+ if
+      # the action is not found.
+      #
+      # @param txid [String] hex transaction identifier
+      # @return [String, nil]
+      def status(txid)
+        actions = @storage.find_actions({ txid: txid, limit: 1, offset: 0 })
+        actions.first&.dig(:status)
+      end
+
+      # Broadcasts and promotes (or just promotes) a transaction synchronously.
+      #
+      # Dispatches to +broadcast_and_promote+ when a broadcaster is configured,
+      # or +promote_without_broadcast+ when none is present.
+      #
+      # @param payload [Hash] broadcast payload (see +BroadcastQueue+ module docs)
+      # @return [Hash] result hash containing at minimum +:txid+ and +:tx+
+      def enqueue(payload)
+        if @broadcaster
+          broadcast_and_promote(payload)
+        else
+          promote_without_broadcast(payload)
+        end
+      end
+
+      private
+
+      # Broadcasts the transaction and promotes storage state on success.
+      #
+      # On broadcast failure with outpoints present, rolls back all pending
+      # state (releases locked inputs, deletes change outputs, marks action
+      # failed). On failure without outpoints (finalize path), only updates
+      # the action status.
+      #
+      # INVARIANT: Only broadcast failure triggers rollback. If broadcast
+      # succeeds but promotion raises, the error propagates — confirmed
+      # on-chain outputs must never be deleted.
+      #
+      # @param payload [Hash] broadcast payload
+      # @return [Hash] result hash
+      def broadcast_and_promote(payload)
+        tx               = payload[:tx]
+        txid             = payload[:txid]
+        beef_binary      = payload[:beef_binary]
+        input_outpoints  = payload[:input_outpoints]
+        change_outpoints = payload[:change_outpoints]
+        fund_ref         = payload[:fund_ref]
+
+        begin
+          broadcast_result = @broadcaster.broadcast(tx)
+        rescue StandardError => e
+          if input_outpoints
+            rollback(input_outpoints, change_outpoints, txid, fund_ref)
+          elsif txid
+            @storage.update_action_status(txid, 'failed')
+          end
+          return {
+            txid: txid,
+            tx: beef_binary.unpack('C*'),
+            broadcast_error: e.message,
+            broadcast_status: BroadcastQueue.status_for_error(e)
+          }
+        end
+
+        # Broadcast succeeded — promote all pending state to final.
+        promote(input_outpoints, change_outpoints, txid)
+
+        result = {
+          txid: txid,
+          tx: beef_binary.unpack('C*'),
+          broadcast_result: broadcast_result,
+          broadcast_status: 'success'
+        }
+        result[:competing_txs] = broadcast_result.competing_txs if broadcast_result.respond_to?(:competing_txs) && broadcast_result.competing_txs
+        result
+      end
+
+      # Promotes UTXO state without broadcasting — backwards-compatible fallback
+      # used when no broadcaster is configured.
+      #
+      # If +accept_delayed_broadcast+ is set the action status is +unproven+;
+      # otherwise it is +completed+.
+      #
+      # @param payload [Hash] broadcast payload
+      # @return [Hash] result hash containing +:txid+ and +:tx+
+      def promote_without_broadcast(payload)
+        txid             = payload[:txid]
+        beef_binary      = payload[:beef_binary]
+        input_outpoints  = payload[:input_outpoints]
+        change_outpoints = payload[:change_outpoints]
+        delayed          = payload[:accept_delayed_broadcast]
+
+        final_status = delayed ? 'unproven' : 'completed'
+        promote(input_outpoints, change_outpoints, txid, status: final_status)
+
+        { txid: txid, tx: beef_binary.unpack('C*') }
+      end
+
+      # Promotes UTXO state: marks inputs as +:spent+, change as +:spendable+,
+      # and updates the action status.
+      #
+      # When +outpoints+ arguments are +nil+ (finalize path), UTXO transitions
+      # are skipped and only the action status is updated.
+      #
+      # @param input_outpoints [Array<String>, nil]
+      # @param change_outpoints [Array<String>, nil]
+      # @param txid [String, nil]
+      # @param status [String]
+      def promote(input_outpoints, change_outpoints, txid, status: 'completed')
+        Array(input_outpoints).each { |op| @storage.update_output_state(op, :spent) }
+        Array(change_outpoints).each { |op| @storage.update_output_state(op, :spendable) }
+        @storage.update_action_status(txid, status) if txid
+      end
+
+      # Rolls back a pending auto-funded action.
+      #
+      # Releases locked inputs (only those matching +fund_ref+), deletes phantom
+      # change outputs, and marks the action as +failed+.
+      #
+      # @param input_outpoints [Array<String>] outpoints locked as inputs
+      # @param change_outpoints [Array<String>] change outputs to delete
+      # @param txid [String, nil] action txid
+      # @param fund_ref [String] fund reference used when locking inputs
+      def rollback(input_outpoints, change_outpoints, txid, fund_ref)
+        Array(input_outpoints).each do |op|
+          outputs = @storage.find_outputs({ outpoint: op, include_spent: true, limit: 1, offset: 0 })
+          next if outputs.empty?
+          next unless outputs.first[:pending_reference] == fund_ref
+
+          @storage.update_output_state(op, :spendable)
+        end
+        Array(change_outpoints).each { |op| @storage.delete_output(op) }
+        @storage.update_action_status(txid, 'failed') if txid
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/memory_store.rb

@@ -2,9 +2,11 @@
 
 module BSV
   module Wallet
-    # In-memory storage adapter for testing and single-process use.
+    # In-memory storage adapter intended for testing and development only.
     #
     # Stores actions, outputs, and certificates in plain Ruby arrays.
+    # All data is lost when the process exits — do not use in production.
+    # Use PostgresStore (or another persistent adapter) for production wallets.
     #
     # Thread safety: a +Mutex+ serialises all state-mutating operations so that
     # concurrent threads cannot select and mark the same UTXO as pending.
@@ -12,9 +14,29 @@ module BSV
     #
     # NOTE: FileStore is NOT process-safe — concurrent processes share no
     # in-memory lock and may read stale state from disk.
+    #
+    # == Production Warning
+    #
+    # When +RACK_ENV+, +RAILS_ENV+, or +APP_ENV+ is set to +production+ or
+    # +staging+, a warning is emitted to stderr. Suppress it with either:
+    #
+    #   BSV_MEMORY_STORE_OK=1               # environment variable
+    #   MemoryStore.warn_in_production = false  # Ruby flag (e.g. in test setup)
     class MemoryStore
       include StorageAdapter
 
+      # Controls whether the production-environment warning is emitted.
+      # Set to +false+ in test suites to silence the warning globally.
+      #
+      # @return [Boolean]
+      def self.warn_in_production?
+        @warn_in_production != false
+      end
+
+      class << self
+        attr_writer :warn_in_production
+      end
+
       def initialize
         @actions = []
         @outputs = []
@@ -23,6 +45,12 @@ module BSV
         @transactions = {}
         @settings = {}
         @mutex = Mutex.new
+
+        return unless self.class.warn_in_production? && production_env?
+
+        warn '[bsv-wallet] MemoryStore is intended for testing only. ' \
+             'Use PostgresStore for production wallets. ' \
+             'Set BSV_MEMORY_STORE_OK=1 to silence this warning.'
       end
 
       def store_action(action_data)
@@ -255,6 +283,14 @@ module BSV
 
       private
 
+      # Returns true when the process is running in a production or staging
+      # environment and the operator has not explicitly acknowledged MemoryStore
+      # usage via the +BSV_MEMORY_STORE_OK+ environment variable.
+      def production_env?
+        env = ENV['RACK_ENV'] || ENV['RAILS_ENV'] || ENV.fetch('APP_ENV', nil)
+        env && %w[production staging].include?(env) && !ENV['BSV_MEMORY_STORE_OK']
+      end
+
       def filter_actions(query)
         results = @actions
         return results unless query[:labels]

data/lib/bsv/wallet_interface/substrates/http_wallet_json.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module BSV
+  module Wallet
+    module Substrates
+      # BRC-100 wallet substrate that delegates all Interface methods to a remote
+      # wallet server via JSON-over-HTTP (POST #{base_url}/#{camelCaseMethodName}).
+      #
+      # Key conversion is handled by {BSV::WireFormat}: Ruby snake_case symbol keys
+      # in args are converted to camelCase strings before the request, and the
+      # camelCase JSON response is converted back to snake_case symbol keys.
+      #
+      # @example
+      #   wallet = BSV::Wallet::Substrates::HTTPWalletJSON.new('http://localhost:3321',
+      #                                                         originator: 'myapp.example.com')
+      #   result = wallet.get_public_key({ identity_key: true })
+      #   # => { public_key: '02abc...' }
+      class HTTPWalletJSON
+        include BSV::Wallet::Interface
+
+        # Maps the 28 BRC-100 Interface method symbols to their camelCase HTTP endpoint names.
+        # Derived from Wire::Serializer::CALL_CODES keys via BSV::WireFormat.snake_to_camel.
+        METHOD_NAMES = BSV::Wallet::Wire::Serializer::CALL_CODES.keys.to_h do |sym|
+          [sym, BSV::WireFormat.snake_to_camel(sym.to_s)]
+        end.freeze
+
+        # @param base_url [String] base URL of the remote wallet server (e.g. 'http://localhost:3321')
+        # @param originator [String, nil] FQDN of the originating application (sent as Origin/Originator headers)
+        # @param http_client [Object, nil] injectable HTTP client for testing; must respond to
+        #   `start(uri, &block)` returning a Net::HTTP-compatible response
+        def initialize(base_url, originator: nil, http_client: nil)
+          @base_url = base_url
+          @originator = originator
+          @http_client = http_client
+        end
+
+        # Per-call originator is accepted for Interface conformance but not forwarded.
+        # The Origin header uses the constructor-level @originator for the lifetime of
+        # the connection — matching the TS SDK's HTTPWalletJSON, which also ignores per-call
+        # originator. WalletWireTransceiver supports per-call originator because the wire
+        # frame encodes it per-message; HTTP substrates identify by connection, not by call.
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        def create_action(args, originator: nil)
+          call(METHOD_NAMES[:create_action], args)
+        end
+
+        def sign_action(args, originator: nil)
+          call(METHOD_NAMES[:sign_action], args)
+        end
+
+        def abort_action(args, originator: nil)
+          call(METHOD_NAMES[:abort_action], args)
+        end
+
+        def list_actions(args, originator: nil)
+          call(METHOD_NAMES[:list_actions], args)
+        end
+
+        def internalize_action(args, originator: nil)
+          call(METHOD_NAMES[:internalize_action], args)
+        end
+
+        def list_outputs(args, originator: nil)
+          call(METHOD_NAMES[:list_outputs], args)
+        end
+
+        def relinquish_output(args, originator: nil)
+          call(METHOD_NAMES[:relinquish_output], args)
+        end
+
+        def get_public_key(args, originator: nil)
+          call(METHOD_NAMES[:get_public_key], args)
+        end
+
+        def reveal_counterparty_key_linkage(args, originator: nil)
+          call(METHOD_NAMES[:reveal_counterparty_key_linkage], args)
+        end
+
+        def reveal_specific_key_linkage(args, originator: nil)
+          call(METHOD_NAMES[:reveal_specific_key_linkage], args)
+        end
+
+        def encrypt(args, originator: nil)
+          call(METHOD_NAMES[:encrypt], args)
+        end
+
+        def decrypt(args, originator: nil)
+          call(METHOD_NAMES[:decrypt], args)
+        end
+
+        def create_hmac(args, originator: nil)
+          call(METHOD_NAMES[:create_hmac], args)
+        end
+
+        def verify_hmac(args, originator: nil)
+          call(METHOD_NAMES[:verify_hmac], args)
+        end
+
+        def create_signature(args, originator: nil)
+          call(METHOD_NAMES[:create_signature], args)
+        end
+
+        def verify_signature(args, originator: nil)
+          call(METHOD_NAMES[:verify_signature], args)
+        end
+
+        def acquire_certificate(args, originator: nil)
+          call(METHOD_NAMES[:acquire_certificate], args)
+        end
+
+        def list_certificates(args, originator: nil)
+          call(METHOD_NAMES[:list_certificates], args)
+        end
+
+        def prove_certificate(args, originator: nil)
+          call(METHOD_NAMES[:prove_certificate], args)
+        end
+
+        def relinquish_certificate(args, originator: nil)
+          call(METHOD_NAMES[:relinquish_certificate], args)
+        end
+
+        def discover_by_identity_key(args, originator: nil)
+          call(METHOD_NAMES[:discover_by_identity_key], args)
+        end
+
+        def discover_by_attributes(args, originator: nil)
+          call(METHOD_NAMES[:discover_by_attributes], args)
+        end
+
+        def is_authenticated(args = {}, originator: nil)
+          call(METHOD_NAMES[:is_authenticated], args)
+        end
+
+        def wait_for_authentication(args = {}, originator: nil)
+          call(METHOD_NAMES[:wait_for_authentication], args)
+        end
+
+        def get_height(args = {}, originator: nil)
+          call(METHOD_NAMES[:get_height], args)
+        end
+
+        def get_header_for_height(args, originator: nil)
+          call(METHOD_NAMES[:get_header_for_height], args)
+        end
+
+        def get_network(args = {}, originator: nil)
+          call(METHOD_NAMES[:get_network], args)
+        end
+
+        def get_version(args = {}, originator: nil)
+          call(METHOD_NAMES[:get_version], args)
+        end
+
+        # rubocop:enable Lint/UnusedMethodArgument
+
+        private
+
+        # Posts args to the remote wallet endpoint for the given camelCase method name.
+        #
+        # Outbound: converts snake_case symbol keys to camelCase strings via WireFormat.to_wire.
+        # Inbound:  converts camelCase string keys to snake_case symbols via WireFormat.from_wire.
+        # Errors:   non-2xx response raises the appropriate WalletError subclass.
+        #
+        # @param method_name [String] camelCase endpoint name (e.g. 'getPublicKey')
+        # @param args [Hash] method arguments (snake_case symbol keys)
+        # @return [Hash] response with snake_case symbol keys
+        def call(method_name, args)
+          args ||= {}
+          wire_args = BSV::WireFormat.to_wire(args)
+          body = JSON.generate(wire_args)
+
+          uri = build_uri(method_name)
+          headers = build_headers
+
+          response = execute_request(uri, body, headers)
+
+          handle_response(response, method_name, args)
+        end
+
+        def build_uri(method_name)
+          URI.parse("#{@base_url}/#{method_name}")
+        end
+
+        def build_headers
+          h = {
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json'
+          }
+
+          if @originator
+            origin_value = to_origin_header(@originator)
+            h['Origin']      = origin_value
+            h['Originator']  = origin_value
+          end
+
+          h
+        end
+
+        # Converts an originator domain to a full Origin header value.
+        # Prepends 'http://' if no scheme is present (matching TS SDK toOriginHeader).
+        def to_origin_header(originator)
+          return originator if originator.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+
+          "http://#{originator}"
+        end
+
+        def execute_request(uri, body, headers)
+          if @http_client
+            @http_client.post(uri, body, headers)
+          else
+            Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+              request = Net::HTTP::Post.new(uri.request_uri, headers)
+              request.body = body
+              http.request(request)
+            end
+          end
+        end
+
+        def handle_response(response, method_name, args)
+          code = response.code.to_i
+
+          unless (200..299).cover?(code)
+            data = begin
+              parse_json_body(response.body)
+            rescue JSON::ParserError
+              nil
+            end
+            raise_error_response(code, data, method_name, args)
+          end
+
+          data = parse_json_body(response.body)
+          return {} if data.nil?
+
+          data.is_a?(Hash) ? BSV::WireFormat.from_wire(data) : data
+        end
+
+        def parse_json_body(body)
+          return nil if body.nil? || body.empty?
+
+          JSON.parse(body)
+        end
+
+        def raise_error_response(code, data, method_name, _args)
+          if code == 400 && data.is_a?(Hash) && data['isError']
+            case data['code']
+            when 5
+              raise BSV::Wallet::WalletError.new(data['message'] || 'Review actions required', 5)
+            when 6
+              raise BSV::Wallet::InvalidParameterError, data['parameter'] || 'unknown'
+            when 7
+              raise BSV::Wallet::InsufficientFundsError, data['message']
+            end
+          end
+
+          message = (data.is_a?(Hash) && data['message']) ||
+                    "HTTP #{code} error calling #{method_name}"
+          raise BSV::Wallet::WalletError, message
+        end
+      end
+    end
+  end
+end