bsv-wallet 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 233e4c969fea0e8bb52110ffffe9d034a953854ccb1098c0a3dd3eb76bb2c034
-  data.tar.gz: e11ab6c70e949cbe62593f620d0367225e80ac84a144f94b07418d02e9383466
+  metadata.gz: c71d9a7e4b68e5d47c4d95e3a8bcd6c23c698a92ca3faa4809a9a7abf1171b8e
+  data.tar.gz: f61618ef74ba89eae855dc710244f5a9208bff34a2244f4bb2ab6425d6774fea
 SHA512:
-  metadata.gz: 974ffa3042e2bb4fe3c9f7ec94d8503c55ed20e94d5a808a667700339fbb5151eec6b12c185238353ccfd40e62f197477081fdb7b6b9f9ce75da4598a4536b90
-  data.tar.gz: 0af0b5d238c57a1b640ea243b2bce0e5e33fd55932354689a62b1c05dfe3b41d776fdfcd5fe245fa3973de98632d6f0985bbfc4bed99b4d2527494dc16fc2f6f
+  metadata.gz: 9c9d6badbfaac1bb19ed0bf5745ccfe21aba5372822e692be72f1065df56175481277e8f1b41daf4c17dd0acc758e43a2dcf73d4e8c96147d982dafd7b7a7ca3
+  data.tar.gz: 161733d4e9c277c55d4e3b1d89eab89bf156d066575c3f924e066c636d55f65606cd1e4df7afdbbdf0ff8cea615d5d6c09c30aafc63773294370c22659a3bf85

data/CHANGELOG.md

@@ -5,6 +5,28 @@ 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

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

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module BSV
+  module Wallet
+    module Substrates
+      # Binary wire transport that transmits BRC-100 wallet wire messages over HTTP.
+      #
+      # Implements the single-method WalletWire interface: given a raw binary frame
+      # (as an Array of byte integers), parses the call code, maps it to a URL path,
+      # and POSTs the payload to the remote wallet endpoint.
+      #
+      # @example
+      #   wire = BSV::Wallet::Substrates::HTTPWalletWire.new('http://localhost:3301')
+      #   response_bytes = wire.transmit_to_wallet(frame_bytes)
+      class HTTPWalletWire
+        # @param base_url [String] the base URL of the remote wallet (e.g. 'http://localhost:3301')
+        # @param originator [String, nil] FQDN of the calling application (sent as Origin header)
+        # @param http_client [#call, nil] injectable HTTP client for testing; nil uses Net::HTTP
+        def initialize(base_url, originator: nil, http_client: nil)
+          @base_url = base_url
+          @originator = originator
+          @http_client = http_client
+        end
+
+        # Transmits a binary wallet wire message to the remote wallet.
+        #
+        # Parses the call code from byte 0, reads the originator from the header,
+        # and POSTs the remaining payload bytes to the appropriate URL path.
+        #
+        # @param message [Array<Integer>] raw wire frame as array of byte integers
+        # @return [Array<Integer>] response body as array of byte integers
+        # @raise [ArgumentError] if the message is empty or contains an unknown call code
+        # @raise [RuntimeError] if the HTTP response indicates an error (non-2xx)
+        def transmit_to_wallet(message)
+          raise ArgumentError, 'message must not be empty' if message.nil? || message.empty?
+
+          call_code = message[0]
+          call_name = BSV::Wallet::Wire::Serializer::METHODS_BY_CODE[call_code]
+          raise ArgumentError, "unknown call code: #{call_code}" if call_name.nil?
+
+          originator_length = message[1] || 0
+          originator = message[2, originator_length].pack('C*').force_encoding('UTF-8') if originator_length.positive?
+
+          payload_start = 2 + originator_length
+          payload = message[payload_start..] || []
+
+          camel_name = BSV::WireFormat.snake_to_camel(call_name.to_s)
+          url = "#{@base_url}/#{camel_name}"
+
+          response_body = post_binary(url, payload, originator || @originator)
+          response_body.bytes.to_a
+        end
+
+        private
+
+        def post_binary(url, payload_bytes, originator)
+          uri = URI.parse(url)
+          body = payload_bytes.pack('C*')
+
+          if @http_client
+            @http_client.call(uri, body, originator)
+          else
+            perform_request(uri, body, originator)
+          end
+        end
+
+        def perform_request(uri, body, originator)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+            request = Net::HTTP::Post.new(uri.request_uri)
+            request['Content-Type'] = 'application/octet-stream'
+            request['Origin'] = originator if originator && !originator.empty?
+            request.body = body
+            response = http.request(request)
+            raise "HTTPWalletWire: HTTP #{response.code} from #{uri}" unless response.is_a?(Net::HTTPSuccess)
+
+            response.body || ''
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Substrates
+      # BRC-100 wallet Interface implementation that transmits calls over a binary wire transport.
+      #
+      # Serialises each Interface method call into a binary wire frame via
+      # {BSV::Wallet::Wire::Serializer}, transmits it via a wire transport (any object
+      # responding to `#transmit_to_wallet`), then deserialises the response.
+      #
+      # The wire transport is duck-typed — any object that accepts
+      # `transmit_to_wallet(message)` where +message+ is an Array of byte integers
+      # and returns an Array of byte integers qualifies. The canonical wire transport
+      # is {HTTPWalletWire}.
+      #
+      # @example Using with HTTPWalletWire
+      #   wire = BSV::Wallet::Substrates::HTTPWalletWire.new('http://localhost:3301')
+      #   wallet = BSV::Wallet::Substrates::WalletWireTransceiver.new(wire, originator: 'myapp.example.com')
+      #   result = wallet.get_public_key({ identity_key: true })
+      #   # => { public_key: '02abc...' }
+      class WalletWireTransceiver
+        include BSV::Wallet::Interface
+
+        # @param wire [#transmit_to_wallet] wire transport (duck-typed)
+        # @param originator [String, nil] default FQDN of the originating application;
+        #   may be overridden per-call via the method-level originator keyword argument
+        def initialize(wire, originator: nil)
+          @wire = wire
+          @originator = originator
+        end
+
+        def create_action(args, originator: nil)
+          transmit(:create_action, args, originator || @originator)
+        end
+
+        def sign_action(args, originator: nil)
+          transmit(:sign_action, args, originator || @originator)
+        end
+
+        def abort_action(args, originator: nil)
+          transmit(:abort_action, args, originator || @originator)
+        end
+
+        def list_actions(args, originator: nil)
+          transmit(:list_actions, args, originator || @originator)
+        end
+
+        def internalize_action(args, originator: nil)
+          transmit(:internalize_action, args, originator || @originator)
+        end
+
+        def list_outputs(args, originator: nil)
+          transmit(:list_outputs, args, originator || @originator)
+        end
+
+        def relinquish_output(args, originator: nil)
+          transmit(:relinquish_output, args, originator || @originator)
+        end
+
+        def get_public_key(args, originator: nil)
+          transmit(:get_public_key, args, originator || @originator)
+        end
+
+        def reveal_counterparty_key_linkage(args, originator: nil)
+          transmit(:reveal_counterparty_key_linkage, args, originator || @originator)
+        end
+
+        def reveal_specific_key_linkage(args, originator: nil)
+          transmit(:reveal_specific_key_linkage, args, originator || @originator)
+        end
+
+        def encrypt(args, originator: nil)
+          transmit(:encrypt, args, originator || @originator)
+        end
+
+        def decrypt(args, originator: nil)
+          transmit(:decrypt, args, originator || @originator)
+        end
+
+        def create_hmac(args, originator: nil)
+          transmit(:create_hmac, args, originator || @originator)
+        end
+
+        def verify_hmac(args, originator: nil)
+          transmit(:verify_hmac, args, originator || @originator)
+        end
+
+        def create_signature(args, originator: nil)
+          transmit(:create_signature, args, originator || @originator)
+        end
+
+        def verify_signature(args, originator: nil)
+          transmit(:verify_signature, args, originator || @originator)
+        end
+
+        def acquire_certificate(args, originator: nil)
+          transmit(:acquire_certificate, args, originator || @originator)
+        end
+
+        def list_certificates(args, originator: nil)
+          transmit(:list_certificates, args, originator || @originator)
+        end
+
+        def prove_certificate(args, originator: nil)
+          transmit(:prove_certificate, args, originator || @originator)
+        end
+
+        def relinquish_certificate(args, originator: nil)
+          transmit(:relinquish_certificate, args, originator || @originator)
+        end
+
+        def discover_by_identity_key(args, originator: nil)
+          transmit(:discover_by_identity_key, args, originator || @originator)
+        end
+
+        def discover_by_attributes(args, originator: nil)
+          transmit(:discover_by_attributes, args, originator || @originator)
+        end
+
+        def is_authenticated(args = {}, originator: nil)
+          transmit(:is_authenticated, args, originator || @originator)
+        end
+
+        def wait_for_authentication(args = {}, originator: nil)
+          transmit(:wait_for_authentication, args, originator || @originator)
+        end
+
+        def get_height(args = {}, originator: nil)
+          transmit(:get_height, args, originator || @originator)
+        end
+
+        def get_header_for_height(args, originator: nil)
+          transmit(:get_header_for_height, args, originator || @originator)
+        end
+
+        def get_network(args = {}, originator: nil)
+          transmit(:get_network, args, originator || @originator)
+        end
+
+        def get_version(args = {}, originator: nil)
+          transmit(:get_version, args, originator || @originator)
+        end
+
+        private
+
+        # Serialises +method_name+ and +args+ into a binary wire frame, transmits it
+        # via the wire transport, and deserialises the response.
+        #
+        # Error responses (non-zero first byte) are parsed and raised as {WalletError}
+        # by {BSV::Wallet::Wire::Serializer.deserialize_response}.
+        #
+        # @param method_name [Symbol] BRC-100 method name (snake_case)
+        # @param args [Hash] method arguments
+        # @param orig [String, nil] FQDN of the originating application
+        # @return [Hash] deserialised result
+        def transmit(method_name, args, orig)
+          frame = BSV::Wallet::Wire::Serializer.serialize_request(
+            method_name, args || {}, originator: orig.to_s
+          )
+          response_bytes = @wire.transmit_to_wallet(frame.bytes.to_a)
+          response_binary = response_bytes.pack('C*')
+          BSV::Wallet::Wire::Serializer.deserialize_response(method_name, response_binary)
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/substrates.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # BRC-100 wallet substrates — alternative transport layers for the wallet interface.
+    #
+    # Substrates are raw transport adapters. They are not full Wallet::Interface implementations;
+    # instead they provide the low-level connectivity that a WalletWireTransceiver or
+    # HTTPWalletJSON wraps to expose the full interface.
+    module Substrates
+      autoload :HTTPWalletJSON, 'bsv/wallet_interface/substrates/http_wallet_json'
+      autoload :HTTPWalletWire, 'bsv/wallet_interface/substrates/http_wallet_wire'
+      autoload :WalletWireTransceiver, 'bsv/wallet_interface/substrates/wallet_wire_transceiver'
+    end
+  end
+end

data/lib/bsv/wallet_interface/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module BSV
-  module WalletInterface
-    VERSION = '0.7.0'
+  module Wallet
+    VERSION = '0.8.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -45,6 +45,9 @@ module BSV
       # @return [BroadcastQueue] the broadcast queue used to dispatch transactions
       attr_reader :broadcast_queue
 
+      # @return [Interface, nil] the optional substrate for remote wallet delegation
+      attr_reader :substrate
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
       # @param storage [StorageAdapter] persistence adapter (default: FileStore).
       #   Use +storage: MemoryStore.new+ for tests.
@@ -54,6 +57,10 @@ module BSV
       # @param http_client [#request, nil] injectable HTTP client for certificate issuance
       # @param broadcaster [#broadcast, nil] optional broadcaster; any object responding to #broadcast(tx)
       # @param broadcast_queue [BroadcastQueue, nil] optional broadcast queue; defaults to InlineQueue
+      # @param substrate [Interface, nil] optional remote wallet substrate; when set, all Interface
+      #   methods delegate to the substrate instead of using local storage and key derivation.
+      #   Accepts any object implementing {Interface} (e.g. {Substrates::HTTPWalletJSON},
+      #   {Substrates::WalletWireTransceiver}).
       def initialize(
         key,
         storage: FileStore.new,
@@ -65,9 +72,11 @@ module BSV
         coin_selector: nil,
         change_generator: nil,
         broadcaster: nil,
-        broadcast_queue: nil
+        broadcast_queue: nil,
+        substrate: nil
       )
         super(key)
+        @substrate = substrate
         @storage = storage
         @network = network
         @chain_provider = chain_provider
@@ -110,7 +119,9 @@ module BSV
       #   UTXOs and generates change; requires +:outputs+ and no +:inputs+
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] finalised result or signable_transaction
-      def create_action(args, _originator: nil)
+      def create_action(args, originator: nil)
+        return @substrate.create_action(args, originator: originator) if @substrate
+
         validate_create_action!(args)
 
         send_with_txids = Array(args.dig(:options, :send_with))
@@ -156,7 +167,9 @@ module BSV
       # @option args [String] :reference base64 reference from create_action
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] with :txid and :tx (BEEF bytes)
-      def sign_action(args, _originator: nil)
+      def sign_action(args, originator: nil)
+        return @substrate.sign_action(args, originator: originator) if @substrate
+
         reference = args[:reference]
         pending = @pending[reference]
         raise WalletError, 'Transaction not found for the given reference' unless pending
@@ -185,7 +198,9 @@ module BSV
       # @option args [String] :reference base64 reference to abort
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] { aborted: true }
-      def abort_action(args, _originator: nil)
+      def abort_action(args, originator: nil)
+        return @substrate.abort_action(args, originator: originator) if @substrate
+
         reference = args[:reference]
         raise WalletError, 'Transaction not found for the given reference' unless @pending.key?(reference)
 
@@ -210,12 +225,14 @@ module BSV
       # @option args [Integer] :offset results to skip (default 0)
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] { total_actions: Integer, actions: Array }
-      def list_actions(args, _originator: nil)
+      def list_actions(args, originator: nil)
+        return @substrate.list_actions(args, originator: originator) if @substrate
+
         validate_list_actions!(args)
         query = build_action_query(args)
         total = @storage.count_actions(query)
         actions = @storage.find_actions(query)
-        { total_actions: total, actions: actions }
+        { total_actions: total, actions: strip_action_fields(actions, args) }
       end
 
       # Lists spendable outputs in a basket.
@@ -228,12 +245,14 @@ module BSV
       # @option args [Integer] :offset results to skip (default 0)
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] { total_outputs: Integer, outputs: Array }
-      def list_outputs(args, _originator: nil)
+      def list_outputs(args, originator: nil)
+        return @substrate.list_outputs(args, originator: originator) if @substrate
+
         validate_list_outputs!(args)
         query = build_output_query(args)
         total = @storage.count_outputs(query)
         outputs = @storage.find_outputs(query)
-        { total_outputs: total, outputs: outputs }
+        { total_outputs: total, outputs: strip_output_fields(outputs, args) }
       end
 
       # Removes an output from basket tracking.
@@ -243,7 +262,9 @@ module BSV
       # @option args [String] :output outpoint string
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] { relinquished: true }
-      def relinquish_output(args, _originator: nil)
+      def relinquish_output(args, originator: nil)
+        return @substrate.relinquish_output(args, originator: originator) if @substrate
+
         Validators.validate_basket!(args[:basket])
         Validators.validate_outpoint!(args[:output])
         raise WalletError, 'Output not found' unless @storage.delete_output(args[:output])
@@ -264,7 +285,9 @@ module BSV
       # @option args [Array<String>] :labels optional labels
       # @param _originator [String, nil] FQDN of the originating application
       # @return [Hash] { accepted: true }
-      def internalize_action(args, _originator: nil)
+      def internalize_action(args, originator: nil)
+        return @substrate.internalize_action(args, originator: originator) if @substrate
+
         validate_internalize_action!(args)
         beef_binary = args[:tx].pack('C*')
         beef = BSV::Transaction::Beef.from_binary(beef_binary)
@@ -290,7 +313,9 @@ module BSV
       #
       # @param _args [Hash] unused (empty hash)
       # @return [Hash] { height: Integer }
-      def get_height(_args = {}, _originator: nil)
+      def get_height(args = {}, originator: nil)
+        return @substrate.get_height(args, originator: originator) if @substrate
+
         { height: @chain_provider.get_height }
       end
 
@@ -299,7 +324,9 @@ module BSV
       # @param args [Hash]
       # @option args [Integer] :height block height
       # @return [Hash] { header: String } 80-byte hex-encoded block header
-      def get_header_for_height(args, _originator: nil)
+      def get_header_for_height(args, originator: nil)
+        return @substrate.get_header_for_height(args, originator: originator) if @substrate
+
         raise InvalidParameterError.new('height', 'a positive Integer') unless args[:height].is_a?(Integer) && args[:height].positive?
 
         { header: @chain_provider.get_header(args[:height]) }
@@ -309,7 +336,9 @@ module BSV
       #
       # @param _args [Hash] unused (empty hash)
       # @return [Hash] { network: String } 'mainnet' or 'testnet'
-      def get_network(_args = {}, _originator: nil)
+      def get_network(args = {}, originator: nil)
+        return @substrate.get_network(args, originator: originator) if @substrate
+
         { network: @network }
       end
 
@@ -317,8 +346,10 @@ module BSV
       #
       # @param _args [Hash] unused (empty hash)
       # @return [Hash] { version: String } in vendor-major.minor.patch format
-      def get_version(_args = {}, _originator: nil)
-        { version: "bsv-wallet-#{BSV::WalletInterface::VERSION}" }
+      def get_version(args = {}, originator: nil)
+        return @substrate.get_version(args, originator: originator) if @substrate
+
+        { version: "bsv-wallet-#{BSV::Wallet::VERSION}" }
       end
 
       # Discovers on-chain UTXOs for the wallet's identity address and imports
@@ -427,7 +458,9 @@ module BSV
       #
       # @param _args [Hash] unused (empty hash)
       # @return [Hash] { authenticated: Boolean }
-      def is_authenticated(_args = {}, _originator: nil)
+      def is_authenticated(args = {}, originator: nil)
+        return @substrate.is_authenticated(args, originator: originator) if @substrate
+
         { authenticated: true }
       end
 
@@ -436,7 +469,9 @@ module BSV
       #
       # @param _args [Hash] unused (empty hash)
       # @return [Hash] { authenticated: true }
-      def wait_for_authentication(_args = {}, _originator: nil)
+      def wait_for_authentication(args = {}, originator: nil)
+        return @substrate.wait_for_authentication(args, originator: originator) if @substrate
+
         { authenticated: true }
       end
 
@@ -458,7 +493,9 @@ module BSV
       # @option args [String] :keyring_revealer pubkey hex or 'certifier' (required for direct)
       # @option args [Hash] :keyring_for_subject field_name => base64 key (required for direct)
       # @return [Hash] the stored certificate
-      def acquire_certificate(args, _originator: nil)
+      def acquire_certificate(args, originator: nil)
+        return @substrate.acquire_certificate(args, originator: originator) if @substrate
+
         validate_acquire_certificate!(args)
 
         cert = if args[:acquisition_protocol] == 'issuance'
@@ -479,7 +516,9 @@ module BSV
       # @option args [Integer] :limit max results (default 10)
       # @option args [Integer] :offset number to skip (default 0)
       # @return [Hash] { total_certificates:, certificates: [...] }
-      def list_certificates(args, _originator: nil)
+      def list_certificates(args, originator: nil)
+        return @substrate.list_certificates(args, originator: originator) if @substrate
+
         raise InvalidParameterError.new('certifiers', 'a non-empty Array') unless args[:certifiers].is_a?(Array) && !args[:certifiers].empty?
         raise InvalidParameterError.new('types', 'a non-empty Array') unless args[:types].is_a?(Array) && !args[:types].empty?
 
@@ -505,7 +544,9 @@ module BSV
       # @option args [Array<String>] :fields_to_reveal field names to reveal
       # @option args [String] :verifier verifier public key hex
       # @return [Hash] { keyring_for_verifier: { field_name => Array<Integer> } }
-      def prove_certificate(args, _originator: nil)
+      def prove_certificate(args, originator: nil)
+        return @substrate.prove_certificate(args, originator: originator) if @substrate
+
         cert_arg = args[:certificate]
         fields_to_reveal = args[:fields_to_reveal]
         verifier = args[:verifier]
@@ -528,8 +569,8 @@ module BSV
           # Encrypt the keyring entry for the verifier
           encrypted = encrypt({
                                 plaintext: key_value.bytes,
-                                protocol_id: [2, 'certificate field revelation'],
-                                key_id: "#{cert_arg[:type]} #{cert_arg[:serial_number]} #{field_name}",
+                                protocol_id: [2, 'certificate field encryption'],
+                                key_id: "#{cert_arg[:serial_number]} #{field_name}",
                                 counterparty: verifier
                               })
           keyring_for_verifier[field_name] = encrypted[:ciphertext]
@@ -545,7 +586,9 @@ module BSV
       # @option args [String] :serial_number serial number
       # @option args [String] :certifier certifier public key hex
       # @return [Hash] { relinquished: true }
-      def relinquish_certificate(args, _originator: nil)
+      def relinquish_certificate(args, originator: nil)
+        return @substrate.relinquish_certificate(args, originator: originator) if @substrate
+
         deleted = @storage.delete_certificate(
           type: args[:type],
           serial_number: args[:serial_number],
@@ -566,7 +609,9 @@ module BSV
       # @option args [Integer] :limit max results (default 10)
       # @option args [Integer] :offset number to skip (default 0)
       # @return [Hash] { total_certificates:, certificates: [...] }
-      def discover_by_identity_key(args, _originator: nil)
+      def discover_by_identity_key(args, originator: nil)
+        return @substrate.discover_by_identity_key(args, originator: originator) if @substrate
+
         Validators.validate_pub_key_hex!(args[:identity_key], 'identity_key')
 
         query = { subject: args[:identity_key], limit: args[:limit] || 10, offset: args[:offset] || 0 }
@@ -585,7 +630,9 @@ module BSV
       # @option args [Integer] :limit max results (default 10)
       # @option args [Integer] :offset number to skip (default 0)
       # @return [Hash] { total_certificates:, certificates: [...] }
-      def discover_by_attributes(args, _originator: nil)
+      def discover_by_attributes(args, originator: nil)
+        return @substrate.discover_by_attributes(args, originator: originator) if @substrate
+
         raise InvalidParameterError.new('attributes', 'a non-empty Hash') unless args[:attributes].is_a?(Hash) && !args[:attributes].empty?
 
         query = { attributes: args[:attributes], limit: args[:limit] || 10, offset: args[:offset] || 0 }
@@ -594,6 +641,65 @@ module BSV
         { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
       end
 
+      # --- ProtoWallet crypto method overrides for substrate delegation ---
+      #
+      # When a substrate is configured, these methods delegate to it rather than
+      # performing local key derivation and cryptographic operations.
+
+      def get_public_key(args, originator: nil)
+        return @substrate.get_public_key(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def reveal_counterparty_key_linkage(args, originator: nil)
+        return @substrate.reveal_counterparty_key_linkage(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def reveal_specific_key_linkage(args, originator: nil)
+        return @substrate.reveal_specific_key_linkage(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def encrypt(args, originator: nil)
+        return @substrate.encrypt(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def decrypt(args, originator: nil)
+        return @substrate.decrypt(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def create_hmac(args, originator: nil)
+        return @substrate.create_hmac(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def verify_hmac(args, originator: nil)
+        return @substrate.verify_hmac(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def create_signature(args, originator: nil)
+        return @substrate.create_signature(args, originator: originator) if @substrate
+
+        super
+      end
+
+      def verify_signature(args, originator: nil)
+        return @substrate.verify_signature(args, originator: originator) if @substrate
+
+        super
+      end
+
       # Maximum ancestor depth to traverse when wiring source transactions.
       # Guards against stack overflow on pathologically deep or cyclic chains.
       ANCESTOR_DEPTH_CAP = 64
@@ -1436,6 +1542,47 @@ module BSV
         query
       end
 
+      # --- Include-flag stripping ---
+
+      def strip_action_fields(actions, args)
+        actions.map do |action|
+          a = action.dup
+          a.delete(:labels) unless args[:include_labels] == true
+          a.delete(:inputs) unless args[:include_inputs] == true
+
+          if a.key?(:inputs)
+            strip_src = args[:include_input_source_locking_scripts] != true
+            strip_unlock = args[:include_input_unlocking_scripts] != true
+            if strip_src || strip_unlock
+              a[:inputs] = a[:inputs].map do |i|
+                d = i.dup
+                d.delete(:source_locking_script) if strip_src
+                d.delete(:unlocking_script) if strip_unlock
+                d
+              end
+            end
+          end
+
+          a.delete(:outputs) unless args[:include_outputs] == true
+
+          if a.key?(:outputs) && args[:include_output_locking_scripts] != true
+            a[:outputs] = a[:outputs].map { |o| o.dup.tap { |h| h.delete(:locking_script) } }
+          end
+
+          a
+        end
+      end
+
+      def strip_output_fields(outputs, args)
+        outputs.map do |output|
+          o = output.dup
+          o.delete(:tags) unless args[:include_tags] == true
+          o.delete(:labels) unless args[:include_labels] == true
+          o.delete(:custom_instructions) unless args[:include_custom_instructions] == true
+          o
+        end
+      end
+
       # --- Internalize helpers ---
 
       def store_proofs_from_beef(beef)
@@ -1580,20 +1727,19 @@ module BSV
       end
 
       def acquire_via_issuance(args)
-        uri = URI(args[:certifier_url])
-        request = Net::HTTP::Post.new(uri)
-        request['Content-Type'] = 'application/json'
-        request.body = JSON.generate({
-                                       type: args[:type],
-                                       subject: @key_deriver.identity_key,
-                                       certifier: args[:certifier],
-                                       fields: args[:fields]
-                                     })
-
-        response = execute_http(uri, request)
-        code = response.code.to_i
+        response = auth_fetch_client.fetch(
+          args[:certifier_url],
+          method: 'POST',
+          headers: { 'content-type' => 'application/json' },
+          body: JSON.generate({
+                                type: args[:type],
+                                subject: @key_deriver.identity_key,
+                                certifier: args[:certifier],
+                                fields: args[:fields]
+                              })
+        )
 
-        raise WalletError, "Certificate issuance failed: HTTP #{code}" unless (200..299).cover?(code)
+        raise WalletError, "Certificate issuance failed: HTTP #{response.status}" unless (200..299).cover?(response.status)
 
         body = JSON.parse(response.body)
 
@@ -1619,6 +1765,10 @@ module BSV
         raise WalletError, 'Certificate issuance failed: invalid JSON response'
       end
 
+      def auth_fetch_client
+        @auth_fetch_client ||= BSV::Auth::AuthFetch.new(wallet: self)
+      end
+
       def execute_http(uri, request)
         if @http_client
           @http_client.request(uri, request)

data/lib/bsv/wallet_interface.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 module BSV
-  module WalletInterface
-    autoload :VERSION, 'bsv/wallet_interface/version'
-  end
-
   module Wallet
+    autoload :VERSION,          'bsv/wallet_interface/version'
+
     # BRC-100 Interface
     autoload :Interface,        'bsv/wallet_interface/interface'
     autoload :KeyDeriver,       'bsv/wallet_interface/key_deriver'
@@ -23,6 +21,7 @@ module BSV
     autoload :WhatsOnChainProvider,   'bsv/wallet_interface/whats_on_chain_provider'
     autoload :WalletClient,      'bsv/wallet_interface/wallet_client'
     autoload :Wire,              'bsv/wallet_interface/wire'
+    autoload :Substrates,        'bsv/wallet_interface/substrates'
     autoload :CertificateSignature, 'bsv/wallet_interface/certificate_signature'
     autoload :FeeModel,             'bsv/wallet_interface/fee_model'
     autoload :FeeEstimator,         'bsv/wallet_interface/fee_estimator'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -29,7 +29,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.11.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -39,7 +39,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.11.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -75,6 +75,10 @@ files:
 - lib/bsv/wallet_interface/proof_store.rb
 - lib/bsv/wallet_interface/proto_wallet.rb
 - lib/bsv/wallet_interface/storage_adapter.rb
+- lib/bsv/wallet_interface/substrates.rb
+- lib/bsv/wallet_interface/substrates/http_wallet_json.rb
+- lib/bsv/wallet_interface/substrates/http_wallet_wire.rb
+- lib/bsv/wallet_interface/substrates/wallet_wire_transceiver.rb
 - lib/bsv/wallet_interface/validators.rb
 - lib/bsv/wallet_interface/version.rb
 - lib/bsv/wallet_interface/wallet_client.rb