bsv-sdk 0.19.1 → 0.22.0

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

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Wire
+      # BRC-103 request and result frame codec.
+      #
+      # Port of go-sdk/wallet/serializer/frame.go. Two frame types:
+      #
+      # Request frame (client → wallet):
+      #   [1 byte: call][1 byte: originator_len][originator_len bytes: UTF-8][remaining: params]
+      #
+      # Result frame (wallet → client):
+      #   [1 byte: error_code]
+      #   On success (0x00): [remaining bytes: payload]
+      #   On error (non-zero):
+      #     [VarInt: message_len][message bytes]
+      #     [VarInt: stack_len][stack bytes]
+      module Frame
+        # Maximum originator byte length enforced at write time.
+        # Matches the BRC-100 +OriginatorDomainNameStringUnder250Bytes+ branded
+        # type used by +Wire::Validation.originator_domain!+.
+        MAX_ORIGINATOR_BYTES = 250
+
+        module_function
+
+        # Encode a request frame.
+        #
+        # @param call [Integer] call byte (1..28)
+        # @param originator [String] originator domain (0..250 bytes UTF-8)
+        # @param params [String, nil] binary params payload
+        # @return [String] binary frame (ASCII-8BIT encoding)
+        # @raise [ArgumentError] if originator exceeds 250 bytes
+        def write_request(call:, originator:, params: nil)
+          originator_bytes = originator.to_s.b
+          if originator_bytes.bytesize > MAX_ORIGINATOR_BYTES
+            raise ArgumentError,
+                  "originator must be at most #{MAX_ORIGINATOR_BYTES} bytes, " \
+                  "got #{originator_bytes.bytesize}"
+          end
+
+          buf = String.new(encoding: 'BINARY')
+          buf << [call, originator_bytes.bytesize].pack('CC')
+          buf << originator_bytes
+          buf << params.b if params && !params.empty?
+          buf
+        end
+
+        # Decode a request frame.
+        #
+        # @param bytes [String] binary frame
+        # @return [Hash] { call: Integer, originator: String, params: String }
+        # @raise [ArgumentError] if the frame is truncated or malformed
+        def read_request(bytes)
+          data = bytes.b
+          raise ArgumentError, 'frame too short: need at least 2 bytes' if data.bytesize < 2
+
+          call = data.getbyte(0)
+          originator_len = data.getbyte(1)
+
+          if data.bytesize < 2 + originator_len
+            raise ArgumentError,
+                  "frame truncated: need #{2 + originator_len} bytes for originator, " \
+                  "got #{data.bytesize}"
+          end
+
+          originator = data.byteslice(2, originator_len).force_encoding('UTF-8')
+          raise ArgumentError, 'frame originator is not valid UTF-8' unless originator.valid_encoding?
+
+          params = data.byteslice(2 + originator_len, data.bytesize - 2 - originator_len) || ''.b
+
+          { call: call, originator: originator, params: params }
+        end
+
+        # Encode a success result frame.
+        #
+        # @param payload [String, nil] binary payload
+        # @return [String] binary frame
+        def write_result(payload: nil)
+          buf = String.new(encoding: 'BINARY')
+          buf << "\x00"
+          buf << payload.b if payload && !payload.empty?
+          buf
+        end
+
+        # Encode an error result frame.
+        #
+        # @param error [BSV::Wallet::Error] the error to encode
+        # @return [String] binary frame
+        def write_error(error:)
+          wire = error.to_wire
+          msg_bytes = wire[:message].to_s.b
+          stack_bytes = wire[:stack].to_s.b
+
+          buf = String.new(encoding: 'BINARY')
+          buf << [wire[:code]].pack('C')
+          buf << encode_varint(msg_bytes.bytesize)
+          buf << msg_bytes
+          buf << encode_varint(stack_bytes.bytesize)
+          buf << stack_bytes
+          buf
+        end
+
+        # Decode a result frame.
+        #
+        # @param bytes [String] binary frame
+        # @return [String] binary payload on success
+        # @raise [BSV::Wallet::Error] the appropriate subclass on error
+        # @raise [ArgumentError] if the frame is truncated or malformed
+        def read_result(bytes)
+          data = bytes.b
+          raise ArgumentError, 'result frame is empty' if data.empty?
+
+          code = data.getbyte(0)
+
+          return data.byteslice(1, data.bytesize - 1) || ''.b if code.zero?
+
+          offset = 1
+          msg_len, vi = decode_varint(data, offset)
+          offset += vi
+
+          raise ArgumentError, 'result frame truncated: message' if data.bytesize < offset + msg_len
+
+          message = data.byteslice(offset, msg_len).force_encoding('UTF-8')
+          raise ArgumentError, 'result frame error message is not valid UTF-8' unless message.valid_encoding?
+
+          offset += msg_len
+
+          stack_len, vi = decode_varint(data, offset)
+          offset += vi
+
+          raise ArgumentError, 'result frame truncated: stack' if data.bytesize < offset + stack_len
+
+          stack = data.byteslice(offset, stack_len).force_encoding('UTF-8')
+          raise ArgumentError, 'result frame stack is not valid UTF-8' unless stack.valid_encoding?
+
+          raise BSV::Wallet.error_from_wire(code, message, stack)
+        end
+
+        # @param n [Integer] unsigned integer
+        # @return [String] Bitcoin varint encoding
+        def encode_varint(n)
+          if n < 0xFD
+            [n].pack('C')
+          elsif n <= 0xFFFF
+            [0xFD, n].pack('Cv')
+          elsif n <= 0xFFFFFFFF
+            [0xFE, n].pack('CV')
+          else
+            [0xFF, n].pack('CQ<')
+          end
+        end
+
+        # @param data [String] binary data
+        # @param offset [Integer] byte offset
+        # @return [Array(Integer, Integer)] decoded value, bytes consumed
+        def decode_varint(data, offset = 0)
+          raise ArgumentError, "varint: need 1 byte at #{offset}" if offset >= data.bytesize
+
+          first = data.getbyte(offset)
+          case first
+          when 0..0xFC
+            [first, 1]
+          when 0xFD
+            raise ArgumentError, "varint: need 3 bytes at #{offset}" if data.bytesize < offset + 3
+
+            [data.byteslice(offset + 1, 2).unpack1('v'), 3]
+          when 0xFE
+            raise ArgumentError, "varint: need 5 bytes at #{offset}" if data.bytesize < offset + 5
+
+            [data.byteslice(offset + 1, 4).unpack1('V'), 5]
+          when 0xFF
+            raise ArgumentError, "varint: need 9 bytes at #{offset}" if data.bytesize < offset + 9
+
+            [data.byteslice(offset + 1, 8).unpack1('Q<'), 9]
+          end
+        end
+      end
+    end
+  end
+end