bsv-sdk 0.20.0 → 0.23.0

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

data/lib/bsv/wallet/wallet_wire_transceiver.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Client-side BRC-103 transceiver.
+    #
+    # Implements every {Interface::BRC100} method by serialising the call
+    # arguments to a binary request frame, transmitting it over a {WalletWire},
+    # unframing the result, and deserialising the payload back to a Ruby hash.
+    #
+    # @example In-process loopback (testing / same-process use)
+    #   proto     = BSV::Wallet::ProtoWallet.new(key)
+    #   processor = BSV::Wallet::WalletWireProcessor.new(proto)
+    #   client    = BSV::Wallet::WalletWireTransceiver.new(processor)
+    #   client.get_public_key(identity_key: true)
+    #   #=> { public_key: "02..." }
+    #
+    # @example Over HTTP
+    #   wire   = BSV::Wallet::Substrates::HTTPWalletWire.new(base_url: 'https://wallet.example')
+    #   client = BSV::Wallet::WalletWireTransceiver.new(wire)
+    #
+    # Thread safety: each call is independent. The wire transport is the
+    # synchronisation boundary — concurrent calls are serialised only if the
+    # underlying wire implementation serialises them.
+    class WalletWireTransceiver
+      include Interface::BRC100
+
+      # @param wire [#transmit_to_wallet] any object that includes {WalletWire}
+      def initialize(wire)
+        @wire = wire
+      end
+
+      # Generate the 28 BRC-100 methods via metaprogramming.
+      #
+      # For each call byte → method name mapping in CALL_TO_METHOD, define a
+      # method that:
+      #   1. Extracts originator from kwargs (default '').
+      #   2. Serialises the args via the SERIALIZE_ARGS dispatch table.
+      #   3. Frames and transmits the binary request.
+      #   4. Unframes the result (raises on error frame).
+      #   5. Deserialises the payload via DESERIALIZE_RESULT.
+      Wire::Calls::CALL_TO_METHOD.each do |call_byte, method_name|
+        define_method(method_name) do |**args|
+          _dispatch(call_byte, args)
+        end
+      end
+
+      private
+
+      def _dispatch(call_byte, args)
+        originator = args[:originator].to_s
+        Wire::Validation.originator_domain!('originator', originator) unless originator.empty?
+        params  = Serializer::SERIALIZE_ARGS.fetch(call_byte).call(args)
+        frame   = Wire::Frame.write_request(call: call_byte, originator: originator, params: params)
+        reply   = @wire.transmit_to_wallet(frame)
+        payload = Wire::Frame.read_result(reply)
+        Serializer::DESERIALIZE_RESULT.fetch(call_byte).call(payload)
+      end
+    end
+  end
+end

data/lib/bsv/wallet/wire/calls.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Wire
+      # BRC-103 call byte constants and dispatch tables.
+      #
+      # Each constant maps to the corresponding Go SDK CallXxx constant in
+      # go-sdk/wallet/substrates/wallet_wire_calls.go. The CALL_TO_METHOD
+      # table maps each byte to the actual Ruby method name on Interface::BRC100.
+      #
+      # Note: call byte 23 maps to :authenticated? (predicate suffix preserved),
+      # not :is_authenticated, to match the existing Interface::BRC100 definition.
+      module Calls
+        CREATE_ACTION                    = 1
+        SIGN_ACTION                      = 2
+        ABORT_ACTION                     = 3
+        LIST_ACTIONS                     = 4
+        INTERNALIZE_ACTION               = 5
+        LIST_OUTPUTS                     = 6
+        RELINQUISH_OUTPUT                = 7
+        GET_PUBLIC_KEY                   = 8
+        REVEAL_COUNTERPARTY_KEY_LINKAGE  = 9
+        REVEAL_SPECIFIC_KEY_LINKAGE      = 10
+        ENCRYPT                          = 11
+        DECRYPT                          = 12
+        CREATE_HMAC                      = 13
+        VERIFY_HMAC                      = 14
+        CREATE_SIGNATURE                 = 15
+        VERIFY_SIGNATURE                 = 16
+        ACQUIRE_CERTIFICATE              = 17
+        LIST_CERTIFICATES                = 18
+        PROVE_CERTIFICATE                = 19
+        RELINQUISH_CERTIFICATE           = 20
+        DISCOVER_BY_IDENTITY_KEY         = 21
+        DISCOVER_BY_ATTRIBUTES           = 22
+        IS_AUTHENTICATED                 = 23
+        WAIT_FOR_AUTHENTICATION          = 24
+        GET_HEIGHT                       = 25
+        GET_HEADER_FOR_HEIGHT            = 26
+        GET_NETWORK                      = 27
+        GET_VERSION                      = 28
+
+        CALL_TO_METHOD = {
+          CREATE_ACTION => :create_action,
+          SIGN_ACTION => :sign_action,
+          ABORT_ACTION => :abort_action,
+          LIST_ACTIONS => :list_actions,
+          INTERNALIZE_ACTION => :internalize_action,
+          LIST_OUTPUTS => :list_outputs,
+          RELINQUISH_OUTPUT => :relinquish_output,
+          GET_PUBLIC_KEY => :get_public_key,
+          REVEAL_COUNTERPARTY_KEY_LINKAGE => :reveal_counterparty_key_linkage,
+          REVEAL_SPECIFIC_KEY_LINKAGE => :reveal_specific_key_linkage,
+          ENCRYPT => :encrypt,
+          DECRYPT => :decrypt,
+          CREATE_HMAC => :create_hmac,
+          VERIFY_HMAC => :verify_hmac,
+          CREATE_SIGNATURE => :create_signature,
+          VERIFY_SIGNATURE => :verify_signature,
+          ACQUIRE_CERTIFICATE => :acquire_certificate,
+          LIST_CERTIFICATES => :list_certificates,
+          PROVE_CERTIFICATE => :prove_certificate,
+          RELINQUISH_CERTIFICATE => :relinquish_certificate,
+          DISCOVER_BY_IDENTITY_KEY => :discover_by_identity_key,
+          DISCOVER_BY_ATTRIBUTES => :discover_by_attributes,
+          IS_AUTHENTICATED => :authenticated?,
+          WAIT_FOR_AUTHENTICATION => :wait_for_authentication,
+          GET_HEIGHT => :get_height,
+          GET_HEADER_FOR_HEIGHT => :get_header_for_height,
+          GET_NETWORK => :get_network,
+          GET_VERSION => :get_version
+        }.freeze
+
+        METHOD_TO_CALL = CALL_TO_METHOD.invert.freeze
+      end
+    end
+  end
+end