bsv-sdk 0.19.1 → 0.22.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +verify_hmac+ call (call byte 14).
+      #
+      # Port of go-sdk/wallet/serializer/verify_hmac.go.
+      module VerifyHmac
+        HMAC_SIZE = 32
+
+        # Args wire layout:
+        #   [key-related params]
+        #   [32 bytes: HMAC]
+        #   [VarInt data_len][data bytes]
+        #   [optional_bool seek_permission]
+        module Args
+          module_function
+
+          def serialize(args)
+            hmac = Common.to_binary(args[:hmac])
+            raise BSV::Wallet::InvalidParameterError.new('hmac', "exactly #{HMAC_SIZE} bytes") unless hmac.bytesize == HMAC_SIZE
+
+            w = BSV::Wallet::Wire::Writer.new
+            Common.write_key_related_params(
+              w,
+              protocol_id: args[:protocol_id],
+              key_id: args[:key_id],
+              counterparty: args[:counterparty],
+              privileged: args[:privileged],
+              privileged_reason: args[:privileged_reason]
+            )
+            w.write_bytes(hmac)
+            data = Common.to_binary(args[:data])
+            w.write_varint(data.bytesize)
+            w.write_bytes(data)
+            w.write_optional_bool(args[:seek_permission])
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            params = Common.read_key_related_params(r)
+            hmac = r.read_bytes(HMAC_SIZE)
+            data_len = r.read_varint
+            data = r.read_bytes(data_len)
+            seek_permission = r.read_optional_bool
+            params.merge(hmac: hmac, data: data, seek_permission: seek_permission)
+          end
+        end
+
+        # Result wire layout: empty — success implies valid.
+        module Result
+          module_function
+
+          def serialize(_result)
+            ''.b
+          end
+
+          def deserialize(_bytes)
+            { valid: true }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +verify_signature+ call (call byte 16).
+      #
+      # Port of go-sdk/wallet/serializer/verify_signature.go.
+      module VerifySignature
+        HASH_SIZE = 32
+
+        # Args wire layout:
+        #   [key-related params]
+        #   [optional_bool for_self]
+        #   [VarInt sig_len][DER signature bytes]
+        #   [1 byte: data-type flag — 1=data, 2=hash_to_directly_verify]
+        #   If flag=1: [VarInt data_len][data bytes]
+        #   If flag=2: [32 bytes: hash]
+        #   [optional_bool seek_permission]
+        module Args
+          module_function
+
+          def serialize(args)
+            data = args[:data] && Common.to_binary(args[:data])
+            hash = args[:hash_to_directly_verify] && Common.to_binary(args[:hash_to_directly_verify])
+            sig  = args[:signature] && Common.to_binary(args[:signature])
+
+            if data && hash
+              raise BSV::Wallet::InvalidParameterError.new(
+                'data and hash_to_directly_verify',
+                'not both provided — supply one or the other'
+              )
+            end
+            raise BSV::Wallet::InvalidParameterError.new('data or hash_to_directly_verify', 'present') unless data || hash
+            raise BSV::Wallet::InvalidParameterError.new('signature', 'present') unless sig
+
+            w = BSV::Wallet::Wire::Writer.new
+            Common.write_key_related_params(
+              w,
+              protocol_id: args[:protocol_id],
+              key_id: args[:key_id],
+              counterparty: args[:counterparty],
+              privileged: args[:privileged],
+              privileged_reason: args[:privileged_reason]
+            )
+
+            w.write_optional_bool(args[:for_self])
+
+            w.write_varint(sig.bytesize)
+            w.write_bytes(sig)
+
+            if data
+              w.write_byte(1)
+              w.write_varint(data.bytesize)
+              w.write_bytes(data)
+            else
+              w.write_byte(2)
+              w.write_bytes(hash)
+            end
+
+            w.write_optional_bool(args[:seek_permission])
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            params = Common.read_key_related_params(r)
+            for_self = r.read_optional_bool
+            sig_len = r.read_varint
+            signature = r.read_bytes(sig_len)
+            flag = r.read_byte
+            payload = case flag
+                      when 1
+                        len = r.read_varint
+                        { data: r.read_bytes(len) }
+                      when 2
+                        { hash_to_directly_verify: r.read_bytes(HASH_SIZE) }
+                      else
+                        raise ArgumentError, "invalid data-type flag: #{flag}"
+                      end
+            seek_permission = r.read_optional_bool
+            params.merge(for_self: for_self, signature: signature).merge(payload).merge(seek_permission: seek_permission)
+          end
+        end
+
+        # Result wire layout: empty — success implies valid.
+        module Result
+          module_function
+
+          def serialize(_result)
+            ''.b
+          end
+
+          def deserialize(_bytes)
+            { valid: true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/serializer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Registry of per-call BRC-103 binary serialisers.
+    #
+    # Each table maps a Wire::Calls constant to the module_function on the
+    # matching Serializer sub-module. Other developer agents populate their
+    # tiers in parallel — add one entry per call, one line each.
+    module Serializer
+      autoload :Common,                       'bsv/wallet/serializer/common'
+
+      # Crypto tier (call bytes 8-16)
+      autoload :GetPublicKey,                 'bsv/wallet/serializer/get_public_key'
+      autoload :RevealCounterpartyKeyLinkage, 'bsv/wallet/serializer/reveal_counterparty_key_linkage'
+      autoload :RevealSpecificKeyLinkage,     'bsv/wallet/serializer/reveal_specific_key_linkage'
+      autoload :Encrypt,                      'bsv/wallet/serializer/encrypt'
+      autoload :Decrypt,                      'bsv/wallet/serializer/decrypt'
+      autoload :CreateHmac,                   'bsv/wallet/serializer/create_hmac'
+      autoload :VerifyHmac,                   'bsv/wallet/serializer/verify_hmac'
+      autoload :CreateSignature,              'bsv/wallet/serializer/create_signature'
+      autoload :VerifySignature,              'bsv/wallet/serializer/verify_signature'
+
+      # Trivial tier (call bytes 23-28)
+      autoload :GetNetwork,               'bsv/wallet/serializer/get_network'
+      autoload :GetVersion,               'bsv/wallet/serializer/get_version'
+      autoload :GetHeight,                'bsv/wallet/serializer/get_height'
+      autoload :GetHeaderForHeight,       'bsv/wallet/serializer/get_header_for_height'
+      autoload :IsAuthenticated,          'bsv/wallet/serializer/status'
+      autoload :WaitForAuthentication,    'bsv/wallet/serializer/status'
+      autoload :CreateActionArgs,           'bsv/wallet/serializer/create_action_args'
+      autoload :CreateActionResult,         'bsv/wallet/serializer/create_action_result'
+      autoload :SignActionArgs,             'bsv/wallet/serializer/sign_action_args'
+      autoload :SignActionResult,           'bsv/wallet/serializer/sign_action_result'
+      autoload :AbortAction,               'bsv/wallet/serializer/abort_action'
+      autoload :InternalizeActionArgs,     'bsv/wallet/serializer/internalize_action'
+      autoload :InternalizeActionResult,   'bsv/wallet/serializer/internalize_action'
+      autoload :ListActionsArgs,           'bsv/wallet/serializer/list_actions'
+      autoload :ListActionsResult,         'bsv/wallet/serializer/list_actions'
+      autoload :Certificate,               'bsv/wallet/serializer/certificate'
+      autoload :DiscoverCertificatesResult, 'bsv/wallet/serializer/discover_certificates_result'
+      autoload :ListOutputs,               'bsv/wallet/serializer/list_outputs'
+      autoload :RelinquishOutput,          'bsv/wallet/serializer/relinquish_output'
+      autoload :AcquireCertificate,        'bsv/wallet/serializer/acquire_certificate'
+      autoload :ListCertificates,          'bsv/wallet/serializer/list_certificates'
+      autoload :ProveCertificate,          'bsv/wallet/serializer/prove_certificate'
+      autoload :RelinquishCertificate,     'bsv/wallet/serializer/relinquish_certificate'
+      autoload :DiscoverByIdentityKey,     'bsv/wallet/serializer/discover_by_identity_key'
+      autoload :DiscoverByAttributes,      'bsv/wallet/serializer/discover_by_attributes'
+
+      # Client-side: serialise outgoing args for each call.
+      SERIALIZE_ARGS = {
+        Wire::Calls::GET_PUBLIC_KEY => GetPublicKey::Args.method(:serialize),
+        Wire::Calls::REVEAL_COUNTERPARTY_KEY_LINKAGE => RevealCounterpartyKeyLinkage::Args.method(:serialize),
+        Wire::Calls::REVEAL_SPECIFIC_KEY_LINKAGE => RevealSpecificKeyLinkage::Args.method(:serialize),
+        Wire::Calls::ENCRYPT => Encrypt::Args.method(:serialize),
+        Wire::Calls::DECRYPT => Decrypt::Args.method(:serialize),
+        Wire::Calls::CREATE_HMAC => CreateHmac::Args.method(:serialize),
+        Wire::Calls::VERIFY_HMAC => VerifyHmac::Args.method(:serialize),
+        Wire::Calls::CREATE_SIGNATURE => CreateSignature::Args.method(:serialize),
+        Wire::Calls::VERIFY_SIGNATURE => VerifySignature::Args.method(:serialize),
+        Wire::Calls::GET_NETWORK => GetNetwork::Args.method(:serialize),
+        Wire::Calls::GET_VERSION => GetVersion::Args.method(:serialize),
+        Wire::Calls::GET_HEIGHT => GetHeight::Args.method(:serialize),
+        Wire::Calls::GET_HEADER_FOR_HEIGHT => GetHeaderForHeight::Args.method(:serialize),
+        Wire::Calls::IS_AUTHENTICATED => IsAuthenticated::Args.method(:serialize),
+        Wire::Calls::WAIT_FOR_AUTHENTICATION => WaitForAuthentication::Args.method(:serialize),
+        Wire::Calls::CREATE_ACTION => CreateActionArgs.method(:serialize),
+        Wire::Calls::SIGN_ACTION => SignActionArgs.method(:serialize),
+        Wire::Calls::ABORT_ACTION => AbortAction.method(:serialize_args),
+        Wire::Calls::INTERNALIZE_ACTION => InternalizeActionArgs.method(:serialize),
+        Wire::Calls::LIST_ACTIONS => ListActionsArgs.method(:serialize),
+        Wire::Calls::LIST_OUTPUTS => ListOutputs.method(:serialize_args),
+        Wire::Calls::RELINQUISH_OUTPUT => RelinquishOutput.method(:serialize_args),
+        Wire::Calls::ACQUIRE_CERTIFICATE => AcquireCertificate.method(:serialize_args),
+        Wire::Calls::LIST_CERTIFICATES => ListCertificates.method(:serialize_args),
+        Wire::Calls::PROVE_CERTIFICATE => ProveCertificate.method(:serialize_args),
+        Wire::Calls::RELINQUISH_CERTIFICATE => RelinquishCertificate.method(:serialize_args),
+        Wire::Calls::DISCOVER_BY_IDENTITY_KEY => DiscoverByIdentityKey.method(:serialize_args),
+        Wire::Calls::DISCOVER_BY_ATTRIBUTES => DiscoverByAttributes.method(:serialize_args)
+      }.freeze
+
+      # Client-side: deserialise incoming result payload for each call.
+      DESERIALIZE_RESULT = {
+        Wire::Calls::GET_PUBLIC_KEY => GetPublicKey::Result.method(:deserialize),
+        Wire::Calls::REVEAL_COUNTERPARTY_KEY_LINKAGE => RevealCounterpartyKeyLinkage::Result.method(:deserialize),
+        Wire::Calls::REVEAL_SPECIFIC_KEY_LINKAGE => RevealSpecificKeyLinkage::Result.method(:deserialize),
+        Wire::Calls::ENCRYPT => Encrypt::Result.method(:deserialize),
+        Wire::Calls::DECRYPT => Decrypt::Result.method(:deserialize),
+        Wire::Calls::CREATE_HMAC => CreateHmac::Result.method(:deserialize),
+        Wire::Calls::VERIFY_HMAC => VerifyHmac::Result.method(:deserialize),
+        Wire::Calls::CREATE_SIGNATURE => CreateSignature::Result.method(:deserialize),
+        Wire::Calls::VERIFY_SIGNATURE => VerifySignature::Result.method(:deserialize),
+        Wire::Calls::GET_NETWORK => GetNetwork::Result.method(:deserialize),
+        Wire::Calls::GET_VERSION => GetVersion::Result.method(:deserialize),
+        Wire::Calls::GET_HEIGHT => GetHeight::Result.method(:deserialize),
+        Wire::Calls::GET_HEADER_FOR_HEIGHT => GetHeaderForHeight::Result.method(:deserialize),
+        Wire::Calls::IS_AUTHENTICATED => IsAuthenticated::Result.method(:deserialize),
+        Wire::Calls::WAIT_FOR_AUTHENTICATION => WaitForAuthentication::Result.method(:deserialize),
+        Wire::Calls::CREATE_ACTION => CreateActionResult.method(:deserialize),
+        Wire::Calls::SIGN_ACTION => SignActionResult.method(:deserialize),
+        Wire::Calls::ABORT_ACTION => AbortAction.method(:deserialize_result),
+        Wire::Calls::INTERNALIZE_ACTION => InternalizeActionResult.method(:deserialize),
+        Wire::Calls::LIST_ACTIONS => ListActionsResult.method(:deserialize),
+        Wire::Calls::LIST_OUTPUTS => ListOutputs.method(:deserialize_result),
+        Wire::Calls::RELINQUISH_OUTPUT => RelinquishOutput.method(:deserialize_result),
+        Wire::Calls::ACQUIRE_CERTIFICATE => AcquireCertificate.method(:deserialize_result),
+        Wire::Calls::LIST_CERTIFICATES => ListCertificates.method(:deserialize_result),
+        Wire::Calls::PROVE_CERTIFICATE => ProveCertificate.method(:deserialize_result),
+        Wire::Calls::RELINQUISH_CERTIFICATE => RelinquishCertificate.method(:deserialize_result),
+        Wire::Calls::DISCOVER_BY_IDENTITY_KEY => DiscoverByIdentityKey.method(:deserialize_result),
+        Wire::Calls::DISCOVER_BY_ATTRIBUTES => DiscoverByAttributes.method(:deserialize_result)
+      }.freeze
+
+      # Server-side: deserialise incoming args payload for each call.
+      DESERIALIZE_ARGS = {
+        Wire::Calls::GET_PUBLIC_KEY => GetPublicKey::Args.method(:deserialize),
+        Wire::Calls::REVEAL_COUNTERPARTY_KEY_LINKAGE => RevealCounterpartyKeyLinkage::Args.method(:deserialize),
+        Wire::Calls::REVEAL_SPECIFIC_KEY_LINKAGE => RevealSpecificKeyLinkage::Args.method(:deserialize),
+        Wire::Calls::ENCRYPT => Encrypt::Args.method(:deserialize),
+        Wire::Calls::DECRYPT => Decrypt::Args.method(:deserialize),
+        Wire::Calls::CREATE_HMAC => CreateHmac::Args.method(:deserialize),
+        Wire::Calls::VERIFY_HMAC => VerifyHmac::Args.method(:deserialize),
+        Wire::Calls::CREATE_SIGNATURE => CreateSignature::Args.method(:deserialize),
+        Wire::Calls::VERIFY_SIGNATURE => VerifySignature::Args.method(:deserialize),
+        Wire::Calls::GET_NETWORK => GetNetwork::Args.method(:deserialize),
+        Wire::Calls::GET_VERSION => GetVersion::Args.method(:deserialize),
+        Wire::Calls::GET_HEIGHT => GetHeight::Args.method(:deserialize),
+        Wire::Calls::GET_HEADER_FOR_HEIGHT => GetHeaderForHeight::Args.method(:deserialize),
+        Wire::Calls::IS_AUTHENTICATED => IsAuthenticated::Args.method(:deserialize),
+        Wire::Calls::WAIT_FOR_AUTHENTICATION => WaitForAuthentication::Args.method(:deserialize),
+        Wire::Calls::CREATE_ACTION => CreateActionArgs.method(:deserialize),
+        Wire::Calls::SIGN_ACTION => SignActionArgs.method(:deserialize),
+        Wire::Calls::ABORT_ACTION => AbortAction.method(:deserialize_args),
+        Wire::Calls::INTERNALIZE_ACTION => InternalizeActionArgs.method(:deserialize),
+        Wire::Calls::LIST_ACTIONS => ListActionsArgs.method(:deserialize),
+        Wire::Calls::LIST_OUTPUTS => ListOutputs.method(:deserialize_args),
+        Wire::Calls::RELINQUISH_OUTPUT => RelinquishOutput.method(:deserialize_args),
+        Wire::Calls::ACQUIRE_CERTIFICATE => AcquireCertificate.method(:deserialize_args),
+        Wire::Calls::LIST_CERTIFICATES => ListCertificates.method(:deserialize_args),
+        Wire::Calls::PROVE_CERTIFICATE => ProveCertificate.method(:deserialize_args),
+        Wire::Calls::RELINQUISH_CERTIFICATE => RelinquishCertificate.method(:deserialize_args),
+        Wire::Calls::DISCOVER_BY_IDENTITY_KEY => DiscoverByIdentityKey.method(:deserialize_args),
+        Wire::Calls::DISCOVER_BY_ATTRIBUTES => DiscoverByAttributes.method(:deserialize_args)
+      }.freeze
+
+      # Server-side: serialise outgoing result for each call.
+      SERIALIZE_RESULT = {
+        Wire::Calls::GET_PUBLIC_KEY => GetPublicKey::Result.method(:serialize),
+        Wire::Calls::REVEAL_COUNTERPARTY_KEY_LINKAGE => RevealCounterpartyKeyLinkage::Result.method(:serialize),
+        Wire::Calls::REVEAL_SPECIFIC_KEY_LINKAGE => RevealSpecificKeyLinkage::Result.method(:serialize),
+        Wire::Calls::ENCRYPT => Encrypt::Result.method(:serialize),
+        Wire::Calls::DECRYPT => Decrypt::Result.method(:serialize),
+        Wire::Calls::CREATE_HMAC => CreateHmac::Result.method(:serialize),
+        Wire::Calls::VERIFY_HMAC => VerifyHmac::Result.method(:serialize),
+        Wire::Calls::CREATE_SIGNATURE => CreateSignature::Result.method(:serialize),
+        Wire::Calls::VERIFY_SIGNATURE => VerifySignature::Result.method(:serialize),
+        Wire::Calls::GET_NETWORK => GetNetwork::Result.method(:serialize),
+        Wire::Calls::GET_VERSION => GetVersion::Result.method(:serialize),
+        Wire::Calls::GET_HEIGHT => GetHeight::Result.method(:serialize),
+        Wire::Calls::GET_HEADER_FOR_HEIGHT => GetHeaderForHeight::Result.method(:serialize),
+        Wire::Calls::IS_AUTHENTICATED => IsAuthenticated::Result.method(:serialize),
+        Wire::Calls::WAIT_FOR_AUTHENTICATION => WaitForAuthentication::Result.method(:serialize),
+        Wire::Calls::CREATE_ACTION => CreateActionResult.method(:serialize),
+        Wire::Calls::SIGN_ACTION => SignActionResult.method(:serialize),
+        Wire::Calls::ABORT_ACTION => AbortAction.method(:serialize_result),
+        Wire::Calls::INTERNALIZE_ACTION => InternalizeActionResult.method(:serialize),
+        Wire::Calls::LIST_ACTIONS => ListActionsResult.method(:serialize),
+        Wire::Calls::LIST_OUTPUTS => ListOutputs.method(:serialize_result),
+        Wire::Calls::RELINQUISH_OUTPUT => RelinquishOutput.method(:serialize_result),
+        Wire::Calls::ACQUIRE_CERTIFICATE => AcquireCertificate.method(:serialize_result),
+        Wire::Calls::LIST_CERTIFICATES => ListCertificates.method(:serialize_result),
+        Wire::Calls::PROVE_CERTIFICATE => ProveCertificate.method(:serialize_result),
+        Wire::Calls::RELINQUISH_CERTIFICATE => RelinquishCertificate.method(:serialize_result),
+        Wire::Calls::DISCOVER_BY_IDENTITY_KEY => DiscoverByIdentityKey.method(:serialize_result),
+        Wire::Calls::DISCOVER_BY_ATTRIBUTES => DiscoverByAttributes.method(:serialize_result)
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module BSV
+  module Wallet
+    module Substrates
+      # JSON-RPC-style HTTP substrate implementing BRC-100.
+      #
+      # Dispatches all 28 BRC-100 methods as JSON POST requests to
+      # {base_url}/v1/wallet/{methodNameInCamelCase}. Request bodies are
+      # deep-converted from snake_case to camelCase via {BSV::WireFormat.to_wire};
+      # responses are deep-converted back via {BSV::WireFormat.from_wire}.
+      #
+      # This substrate does NOT use the BRC-103 binary frame codec — it speaks
+      # plain JSON over HTTP, matching the Go SDK HTTPWalletJSON implementation.
+      #
+      # @example
+      #   client = BSV::Wallet::Substrates::HTTPWalletJSON.new(
+      #     base_url: 'https://wallet.example.com',
+      #     headers: { 'Authorization' => 'Bearer token' }
+      #   )
+      #   client.get_network  # => { network: 'mainnet' }
+      class HTTPWalletJSON
+        include Interface::BRC100
+
+        # Maps each BRC-100 Ruby method name to its camelCase wire name.
+        # authenticated? maps to isAuthenticated — the BRC-100 wire name uses the
+        # is_ prefix convention; the Ruby predicate suffix is dropped for the lookup.
+        WIRE_METHOD_NAMES = Wire::Calls::CALL_TO_METHOD.each_with_object({}) do |(call_byte, ruby_method), map|
+          snake = call_byte == Wire::Calls::IS_AUTHENTICATED ? 'is_authenticated' : ruby_method.to_s
+          map[ruby_method] = BSV::WireFormat.snake_to_camel(snake)
+        end.freeze
+
+        # @param base_url [String] wallet base URL (e.g. 'https://wallet.example')
+        # @param http_client [#request, nil] injectable HTTP client for testing;
+        #   must respond to +#request(uri, net_http_request)+. Defaults to +Net::HTTP+.
+        # @param headers [Hash] additional headers merged into every request
+        def initialize(base_url:, http_client: nil, headers: {})
+          @base_url    = base_url.to_s.chomp('/')
+          @http_client = http_client
+          @headers     = headers.transform_keys(&:to_s)
+        end
+
+        Wire::Calls::CALL_TO_METHOD.each_value do |method_name|
+          define_method(method_name) do |**args|
+            _dispatch(method_name, args)
+          end
+        end
+
+        private
+
+        def _dispatch(method_name, args)
+          wire_name = WIRE_METHOD_NAMES.fetch(method_name)
+          url       = URI.parse("#{@base_url}/v1/wallet/#{wire_name}")
+          body      = args.empty? ? {} : BSV::WireFormat.to_wire(args)
+
+          response = _post(url, body)
+          _handle_response(response)
+        end
+
+        def _post(url, body)
+          req = Net::HTTP::Post.new(url)
+          @headers.each { |k, v| req[k] = v }
+          req['Content-Type'] = 'application/json'
+          req['Accept']       = 'application/json'
+          req.body = body.to_json
+
+          _execute_request(url, req)
+        rescue BSV::Wallet::Error
+          raise
+        rescue StandardError => e
+          raise BSV::Wallet::Error.new("HTTP request failed: #{e.message}", code: 1)
+        end
+
+        def _execute_request(url, req)
+          if @http_client
+            @http_client.request(url, req)
+          else
+            Net::HTTP.start(url.host, url.port,
+                            use_ssl: url.scheme == 'https') { |conn| conn.request(req) }
+          end
+        end
+
+        def _handle_response(response)
+          status = response.code.to_i
+          raw    = response.body.to_s
+
+          if (200..299).cover?(status)
+            _parse_success(raw, status)
+          else
+            _raise_error(raw)
+          end
+        end
+
+        def _parse_success(raw, status)
+          return {} if status == 204 || raw.empty?
+
+          begin
+            parsed = JSON.parse(raw)
+          rescue JSON::ParserError => e
+            raise BSV::Wallet::Error.new("Invalid JSON in response: #{e.message}", code: 1)
+          end
+
+          return parsed unless parsed.is_a?(Hash)
+
+          BSV::WireFormat.from_wire(parsed)
+        end
+
+        def _raise_error(raw)
+          error_hash = begin
+            JSON.parse(raw)
+          rescue JSON::ParserError
+            {}
+          end
+
+          code    = error_hash['code'].to_i
+          message = error_hash['message'].to_s
+          stack   = error_hash['stack'].to_s
+          code    = 1 if code.zero?
+
+          raise BSV::Wallet.error_from_wire(code, message.empty? ? raw : message, stack)
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/substrates/http_wallet_wire.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module BSV
+  module Wallet
+    module Substrates
+      # Concrete {WalletWire} implementation over HTTP/HTTPS.
+      #
+      # Transmits binary BRC-103 request frames via HTTP POST to `{base_url}/wallet`
+      # using `Content-Type: application/octet-stream`, and returns the raw binary
+      # response body.
+      #
+      # The optional `http_client:` parameter accepts any object responding to
+      # `#request(uri, net_http_request)` — matching the injectable client
+      # convention used throughout this SDK. When omitted, `Net::HTTP` is used
+      # directly.
+      #
+      # @example Direct wire usage
+      #   wire   = BSV::Wallet::Substrates::HTTPWalletWire.new(base_url: 'https://wallet.example')
+      #   client = BSV::Wallet::WalletWireTransceiver.new(wire)
+      #   client.get_network  #=> { network: :mainnet }
+      #
+      # @example Convenience factory
+      #   client = BSV::Wallet::Substrates::HTTPWalletWire.client(base_url: 'https://wallet.example')
+      #   client.get_network  #=> { network: :mainnet }
+      class HTTPWalletWire
+        include WalletWire
+
+        # @param base_url [String] wallet base URL (e.g. 'https://wallet.example')
+        # @param http_client [#request, nil] injectable HTTP client for testing;
+        #   must respond to +#request(uri, net_http_request)+. Defaults to +Net::HTTP+.
+        # @param headers [Hash] additional headers merged into every request
+        def initialize(base_url:, http_client: nil, headers: {})
+          @uri         = build_uri(base_url)
+          @http_client = http_client
+          @headers     = headers.transform_keys(&:to_s)
+        end
+
+        # Convenience factory: wraps a new {HTTPWalletWire} in a {WalletWireTransceiver}.
+        #
+        # @param base_url [String]
+        # @param http_client [#request, nil]
+        # @param headers [Hash]
+        # @return [WalletWireTransceiver]
+        def self.client(base_url:, http_client: nil, headers: {})
+          WalletWireTransceiver.new(new(base_url: base_url, http_client: http_client, headers: headers))
+        end
+
+        # POST binary frame to `{base_url}/wallet` and return the binary response body.
+        #
+        # @param message [String] binary request frame (ASCII-8BIT)
+        # @return [String] binary result frame (ASCII-8BIT)
+        # @raise [BSV::Wallet::Error] on non-2xx HTTP status or network failure
+        def transmit_to_wallet(message)
+          http_post(message)
+        rescue BSV::Wallet::Error
+          raise
+        rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+               Net::OpenTimeout, Net::ReadTimeout, Net::HTTPError => e
+          raise BSV::Wallet::Error.new("wallet connection failed: #{e.message}", code: 1)
+        rescue StandardError => e
+          raise BSV::Wallet::Error.new("wallet request failed: #{e.message}", code: 1)
+        end
+
+        private
+
+        def build_uri(base_url)
+          normalised = base_url.to_s.chomp('/')
+          URI.parse("#{normalised}/wallet")
+        end
+
+        def http_post(body)
+          request = Net::HTTP::Post.new(@uri.path)
+          @headers.each { |k, v| request[k] = v }
+          request['Content-Type'] = 'application/octet-stream'
+          request.body = body.respond_to?(:b) ? body.b : body.pack('C*')
+
+          response = execute_request(request)
+
+          raise BSV::Wallet::Error.new("HTTP #{response.code}: #{response.body.to_s.strip}", code: 1) unless response.is_a?(Net::HTTPSuccess)
+
+          (response.body || '').b
+        end
+
+        def execute_request(request)
+          if @http_client
+            @http_client.request(@uri, request)
+          else
+            Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == 'https') do |http|
+              http.request(request)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/wallet_wire.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Abstract binary transport for BRC-103 wallet communication.
+    #
+    # Include this module and implement {#transmit_to_wallet} to provide a
+    # concrete transport (e.g. HTTP, in-process loopback, Unix socket).
+    module WalletWire
+      # Transmit a binary request frame to the wallet and return the binary result frame.
+      #
+      # @param message [String] binary request frame (ASCII-8BIT)
+      # @return [String] binary result frame (ASCII-8BIT)
+      # @raise [NotImplementedError] unless overridden by the including class
+      def transmit_to_wallet(message)
+        raise NotImplementedError, "#{self.class}#transmit_to_wallet is not implemented"
+      end
+    end
+  end
+end

data/lib/bsv/wallet/wallet_wire_processor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Server-side BRC-103 dispatcher.
+    #
+    # Takes any {Interface::BRC100} implementation and exposes it as a
+    # {WalletWire}. Decodes incoming binary request frames, dispatches to the
+    # wallet, serialises the result, and returns a binary result frame.
+    #
+    # Error boundary: any {Error} from the wallet is serialised into an error
+    # frame so the client can rehydrate it. Any other {StandardError} is wrapped
+    # in {Error} (code 1) before framing — the processor never lets a Ruby
+    # exception propagate past this boundary.
+    #
+    # @example Wrap a ProtoWallet for loopback testing
+    #   processor = BSV::Wallet::WalletWireProcessor.new(proto_wallet)
+    #   transceiver = BSV::Wallet::WalletWireTransceiver.new(processor)
+    class WalletWireProcessor
+      include WalletWire
+
+      # @param wallet [Interface::BRC100] any BRC-100 wallet implementation
+      def initialize(wallet)
+        @wallet = wallet
+      end
+
+      # Process a binary request frame and return a binary result frame.
+      #
+      # @param request_bytes [String] binary request frame
+      # @return [String] binary result frame (success or error)
+      def transmit_to_wallet(request_bytes)
+        req = Wire::Frame.read_request(request_bytes)
+        call_byte = req[:call]
+
+        method_name = Wire::Calls::CALL_TO_METHOD.fetch(call_byte) do
+          raise Error.new("unknown call byte: #{call_byte}", code: 1)
+        end
+
+        serialize_result = Serializer::SERIALIZE_RESULT.fetch(call_byte) do
+          raise Error.new("no result serialiser for call #{call_byte}", code: 1)
+        end
+
+        args = Serializer::DESERIALIZE_ARGS.fetch(call_byte) do
+          raise Error.new("no args deserialiser for call #{call_byte}", code: 1)
+        end.call(req[:params])
+
+        args[:originator] = req[:originator] unless req[:originator].empty?
+
+        result  = @wallet.public_send(method_name, **args)
+        payload = serialize_result.call(result)
+        Wire::Frame.write_result(payload: payload)
+      rescue NotImplementedError => e
+        Wire::Frame.write_error(error: UnsupportedActionError.new(e.message.to_s))
+      rescue Error => e
+        Wire::Frame.write_error(error: e)
+      rescue StandardError => e
+        Wire::Frame.write_error(error: Error.new(e.message.to_s, code: 1))
+      end
+    end
+  end
+end