bsv-sdk 0.20.0 → 0.22.0

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

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Wallet
+    module Wire
+      # Binary read/write helpers with BRC-103 idioms.
+      #
+      # Thin wrappers over StringIO providing the specific encodings used across
+      # BRC-103 wire frames: varint strings, optional bools, satoshi LE uint64,
+      # and outpoints. Reuses BSV::Transaction::VarInt for the varint codec.
+
+      # Writer accumulates bytes into a binary string buffer.
+      class Writer
+        attr_reader :buf
+
+        def initialize
+          @buf = String.new(encoding: 'BINARY')
+        end
+
+        # Write a raw byte.
+        def write_byte(byte)
+          @buf << [byte].pack('C')
+        end
+
+        # Write raw bytes (binary string).
+        def write_bytes(bytes)
+          @buf << bytes.b
+        end
+
+        # Write a Bitcoin varint.
+        def write_varint(n)
+          @buf << BSV::Transaction::VarInt.encode(n)
+        end
+
+        # Write a UTF-8 string prefixed by its byte length as a varint.
+        def write_str_with_varint_len(str)
+          bytes = str.to_s.b
+          write_varint(bytes.bytesize)
+          write_bytes(bytes)
+        end
+
+        # Write an optional boolean as a single byte (Go/BRC-103 convention).
+        # nil → 0xFF, false → 0x00, true → 0x01
+        def write_optional_bool(value)
+          byte = case value
+                 when nil   then 0xFF
+                 when false then 0x00
+                 else            0x01
+                 end
+          write_byte(byte)
+        end
+
+        # Write a satoshi amount as 8-byte little-endian uint64.
+        def write_satoshis(n)
+          @buf << [n].pack('Q<')
+        end
+
+        # Write an outpoint: 32-byte display-order txid followed by varint vout.
+        #
+        # Go encodeOutpoint calls WriteBytesReverse(Txid[:]) which writes the
+        # wire-order (chainhash) bytes reversed — i.e. display order on the wire.
+        # The vout is a varint, not a fixed 4-byte LE integer.
+        #
+        # @param txid_hex [String] 64-char display-order hex txid
+        # @param vout [Integer] output index
+        def write_outpoint(txid_hex, vout)
+          BSV::Primitives::Hex.validate_dtxid_hex!(txid_hex)
+          @buf << [txid_hex].pack('H*')
+          write_varint(vout)
+        end
+
+        # Write the NegativeOne sentinel (MaxUint64 as a 9-byte varint: 9 × 0xFF).
+        # Used as a nil sentinel for optional fields in Go-compatible encoding.
+        def write_negative_one
+          write_varint(0xFFFF_FFFF_FFFF_FFFF)
+        end
+
+        # Write a varint length-prefixed byte array (WriteIntBytes in Go).
+        # @param bytes [String, nil] binary string; nil or empty → write varint 0
+        def write_int_bytes(bytes)
+          raw = bytes ? bytes.b : ''.b
+          write_varint(raw.bytesize)
+          write_bytes(raw)
+        end
+
+        # Write an optional uint32: nil → NegativeOne; else varint.
+        # @param n [Integer, nil]
+        def write_optional_uint32(n)
+          if n.nil?
+            write_negative_one
+          else
+            write_varint(n)
+          end
+        end
+
+        # Write an optional string: nil or empty → NegativeOne; else varint len + bytes.
+        # Matches Go WriteOptionalString.
+        # @param str [String, nil]
+        def write_optional_string(str)
+          if str.nil? || str.empty?
+            write_negative_one
+          else
+            write_str_with_varint_len(str)
+          end
+        end
+
+        # Write an array of strings: nil → NegativeOne; else varint count + each as optional string.
+        # Matches Go WriteStringSlice.
+        # @param arr [Array<String>, nil]
+        def write_string_slice(arr)
+          if arr.nil?
+            write_negative_one
+          else
+            write_varint(arr.length)
+            arr.each { |s| write_optional_string(s) }
+          end
+        end
+
+        # Write a string map (Hash<String,String>) sorted by key.
+        # Matches Go WriteStringMap.
+        # @param map [Hash, nil]
+        def write_string_map(map)
+          m = map || {}
+          write_varint(m.length)
+          m.keys.sort.each do |k|
+            write_str_with_varint_len(k)
+            write_str_with_varint_len(m[k])
+          end
+        end
+
+        # Write a binary value encoded as a Base64 string on the wire.
+        # Decodes the Base64 string and writes the raw bytes prefixed by varint length.
+        # @param base64_str [String] standard Base64-encoded string
+        def write_int_from_base64(base64_str)
+          raw = Base64.strict_decode64(base64_str)
+          write_int_bytes(raw)
+        end
+
+        # Write the privileged flag and reason (Go encodePrivilegedParams).
+        # privileged: nil → NegativeOneByte (0xFF), false → 0x00, true → 0x01.
+        # reason: nil or empty → NegativeOneByte; else varint len + bytes.
+        def write_privileged_params(privileged, reason)
+          # Go OptionalBool: nil=0xFF, false=0x00, true=0x01
+          byte = case privileged
+                 when nil   then 0xFF
+                 when false then 0x00
+                 else            0x01
+                 end
+          write_byte(byte)
+          if reason.nil? || reason.empty?
+            write_byte(0xFF)
+          else
+            write_str_with_varint_len(reason)
+          end
+        end
+
+        # Write a txid slice (array of 32-byte txids in wire order).
+        # nil → NegativeOne; else varint count + 32 raw bytes per txid.
+        # Txids are passed as 64-char display-order hex; written as-is (no byte reversal)
+        # to match Go WriteTxidSlice which writes txID[:] (wire-order bytes directly).
+        # @param txids [Array<String>, nil] 64-char display-order hex strings
+        def write_txid_slice(txids)
+          if txids.nil?
+            write_negative_one
+          else
+            write_varint(txids.length)
+            txids.each { |hex| write_bytes([hex].pack('H*')) }
+          end
+        end
+
+        # Write optional bytes with a 1-byte flag prefix (Go BytesOptionWithFlag).
+        # nil/empty → 0x00; else → 0x01 + varint_len + bytes (or fixed_size bytes).
+        # @param bytes [String, nil] binary data
+        # @param fixed_size [Integer, nil] if set, omit the varint length prefix
+        def write_optional_bytes_with_flag(bytes, fixed_size: nil)
+          raw = bytes ? bytes.b : ''.b
+          if raw.empty?
+            write_byte(0)
+          else
+            write_byte(1)
+            if fixed_size
+              write_bytes(raw)
+            else
+              write_int_bytes(raw)
+            end
+          end
+        end
+
+        # Write a varint-len string (always present, 0-length for nil/empty).
+        # Matches Go WriteString which always writes the length prefix.
+        # @param str [String, nil]
+        def write_string(str)
+          write_str_with_varint_len(str.to_s)
+        end
+      end
+
+      # Reader reads sequentially from a binary string.
+      class Reader
+        # @param data [String] binary data
+        def initialize(data)
+          @data = data.b
+          @pos = 0
+        end
+
+        # Read a single byte.
+        # @return [Integer]
+        def read_byte
+          raise ArgumentError, 'unexpected end of data reading byte' if @pos >= @data.bytesize
+
+          byte = @data.getbyte(@pos)
+          @pos += 1
+          byte
+        end
+
+        # Look at the next byte without consuming it.
+        # @return [Integer]
+        def peek_byte
+          raise ArgumentError, 'unexpected end of data peeking byte' if @pos >= @data.bytesize
+
+          @data.getbyte(@pos)
+        end
+
+        # Read +n+ raw bytes.
+        # @return [String] binary string
+        def read_bytes(n)
+          raise ArgumentError, "need #{n} bytes at offset #{@pos}, got #{remaining}" if remaining < n
+
+          slice = @data.byteslice(@pos, n)
+          @pos += n
+          slice
+        end
+
+        # Read a Bitcoin varint.
+        # @return [Integer]
+        def read_varint
+          value, consumed = BSV::Transaction::VarInt.decode(@data, @pos)
+          @pos += consumed
+          value
+        end
+
+        # Read a varint-prefixed UTF-8 string.
+        # @return [String]
+        # @raise [ArgumentError] if the bytes are not valid UTF-8
+        def read_str_with_varint_len
+          len = read_varint
+          str = read_bytes(len).force_encoding('UTF-8')
+          raise ArgumentError, 'varint-prefixed string is not valid UTF-8' unless str.valid_encoding?
+
+          str
+        end
+
+        # Read an optional boolean byte (Go/BRC-103 convention).
+        # 0xFF → nil, 0x00 → false, 0x01 → true
+        # @return [Boolean, nil]
+        def read_optional_bool
+          byte = read_byte
+          return nil if byte == 0xFF
+
+          byte == 0x01
+        end
+
+        # Read 8-byte little-endian uint64 satoshi amount.
+        # @return [Integer]
+        def read_satoshis
+          read_bytes(8).unpack1('Q<')
+        end
+
+        # Read an outpoint: 32-byte display-order txid + varint vout.
+        # @return [Hash] { txid_hex: String, vout: Integer }
+        def read_outpoint
+          txid_bytes = read_bytes(32)
+          vout = read_varint
+          { txid_hex: txid_bytes.unpack1('H*'), vout: vout }
+        end
+
+        # Remaining bytes.
+        def remaining
+          @data.bytesize - @pos
+        end
+
+        # Read all remaining bytes.
+        # @return [String] binary string
+        def read_remaining
+          slice = @data.byteslice(@pos, @data.bytesize - @pos) || ''.b
+          @pos = @data.bytesize
+          slice
+        end
+
+        # Whether the next varint is the NegativeOne sentinel (0xFFFF…).
+        # Peeks at the next byte without consuming it.
+        def next_negative_one?
+          @pos < @data.bytesize && @data.getbyte(@pos) == 0xFF
+        end
+
+        # Read a varint-length-prefixed byte array (ReadIntBytes in Go).
+        # @return [String] binary string
+        def read_int_bytes
+          len = read_varint
+          return ''.b if len == 0xFFFF_FFFF_FFFF_FFFF || len.zero?
+
+          read_bytes(len)
+        end
+
+        # Read an optional uint32: NegativeOne sentinel → nil; else varint → Integer.
+        # @return [Integer, nil]
+        def read_optional_uint32
+          val = read_varint
+          val == 0xFFFF_FFFF_FFFF_FFFF ? nil : val
+        end
+
+        # Read an optional string: NegativeOne sentinel → nil; else varint len + bytes.
+        # @return [String, nil]
+        def read_optional_string
+          val = read_varint
+          return nil if val == 0xFFFF_FFFF_FFFF_FFFF
+
+          read_bytes(val).force_encoding('UTF-8')
+        end
+
+        # Read an array of strings encoded as varint count + each optional string.
+        # NegativeOne sentinel count → nil.
+        # @return [Array<String>, nil]
+        def read_string_slice
+          count = read_varint
+          return nil if count == 0xFFFF_FFFF_FFFF_FFFF
+
+          count.times.map { read_optional_string || '' }
+        end
+
+        # Read a string map: varint count + key/value pairs (each varint-len-prefixed).
+        # @return [Hash<String,String>]
+        def read_string_map
+          count = read_varint
+          count.times.each_with_object({}) do |_, h|
+            k = read_str_with_varint_len
+            v = read_str_with_varint_len
+            h[k] = v
+          end
+        end
+
+        # Read a binary value and return it Base64-encoded.
+        # @return [String] Base64-encoded string
+        def read_base64_int
+          raw = read_int_bytes
+          Base64.strict_encode64(raw)
+        end
+
+        # Read privileged params (Go decodePrivilegedParams).
+        # @return [Array(Boolean|nil, String|nil)]
+        def read_privileged_params
+          privileged = read_optional_bool
+          first_byte = read_byte
+          if first_byte == 0xFF
+            [privileged, nil]
+          else
+            # Back up one byte and read as varint-prefixed string
+            @pos -= 1
+            reason = read_str_with_varint_len
+            [privileged, reason]
+          end
+        end
+
+        # Read a txid slice: NegativeOne → nil; else varint count + 32 bytes per txid.
+        # Go stores txids in wire order (txID[:]) — returned as hex without reversal.
+        # @return [Array<String>, nil]
+        def read_txid_slice
+          count = read_varint
+          return nil if count == 0xFFFF_FFFF_FFFF_FFFF
+
+          count.times.map { read_bytes(32).unpack1('H*') }
+        end
+
+        # Read optional bytes with a 1-byte flag prefix (Go BytesOptionWithFlag).
+        # 0x00 → nil; 0x01 → read varint_len + bytes (or fixed_size bytes).
+        # @param fixed_size [Integer, nil] if set, read exactly this many bytes (no varint)
+        # @return [String, nil] binary string or nil
+        def read_optional_bytes_with_flag(fixed_size: nil)
+          flag = read_byte
+          return nil if flag.zero?
+
+          if fixed_size
+            read_bytes(fixed_size)
+          else
+            read_int_bytes
+          end
+        end
+
+        # Read a varint-len string (always present, 0-length = empty string).
+        # Matches Go ReadString which returns "" for length 0 or NegativeOne.
+        # @return [String]
+        def read_string
+          len = read_varint
+          return '' if len.zero? || len == 0xFFFF_FFFF_FFFF_FFFF
+
+          read_bytes(len).force_encoding('UTF-8')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Wire
+      # Branded-type validators for BRC-100 parameters.
+      #
+      # Each method raises InvalidParameterError on failure and returns nil
+      # on success. Port of ts-sdk/src/wallet/validationHelpers.ts.
+      #
+      # The existing ProtoWallet::Validators module delegates here so there
+      # is a single source of truth for all parameter validation logic.
+      module Validation
+        module_function
+
+        MAX_SATOSHIS = 21_000_000 * (10**8)
+
+        # Validates that +value+ is a hex string (even length, hex chars only).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        # @param length [Integer, nil] expected number of hex chars (nil = any)
+        def hex_string!(name, value, length: nil)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          raise InvalidParameterError.new(name, 'a hex string (characters 0-9, a-f, A-F only)') unless value.match?(/\A[0-9a-fA-F]*\z/)
+
+          raise InvalidParameterError.new(name, 'a hex string with even number of characters') if value.length.odd?
+
+          return unless length && value.length != length
+
+          raise InvalidParameterError.new(name, "a #{length}-character hex string, got #{value.length}")
+        end
+
+        # Validates that +value+ is a Base64-encoded string.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def base64_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          return if value.match?(%r{\A[A-Za-z0-9+/]*={0,2}\z})
+
+          raise InvalidParameterError.new(name, 'a valid Base64 string')
+        end
+
+        # Validates an outpoint string in the form "<64-hex-txid>.<vout>".
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def outpoint_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          parts = value.split('.', 2)
+          raise InvalidParameterError.new(name, 'an outpoint string in the format <64-hex-txid>.<vout>') unless parts.length == 2
+
+          txid_hex, vout_str = parts
+
+          raise InvalidParameterError.new(name, 'an outpoint with a 64-character hex transaction ID') unless txid_hex.match?(/\A[0-9a-fA-F]{64}\z/)
+
+          raise InvalidParameterError.new(name, 'an outpoint with a non-negative integer output index') unless vout_str.match?(/\A\d+\z/)
+
+          vout = vout_str.to_i
+          return unless vout > 0xFFFFFFFF
+
+          raise InvalidParameterError.new(name, 'an outpoint with a vout that fits in a uint32 (0..4294967295)')
+        end
+
+        # Validates a compressed public key in hex form (66 chars, 02/03 prefix).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def pub_key_hex!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          return if value.match?(/\A0[23][0-9a-fA-F]{64}\z/)
+
+          raise InvalidParameterError.new(name, 'a 66-character compressed public key hex string (02 or 03 prefix)')
+        end
+
+        # Validates a description string (5..50 printable characters).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def description_5_to_50!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          len = value.length
+          raise InvalidParameterError.new(name, 'between 5 and 50 characters') if len < 5 || len > 50
+        end
+
+        # Validates a label string (1..150 characters, no spaces).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def label_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          len = value.length
+          raise InvalidParameterError.new(name, 'between 1 and 150 characters') if len < 1 || len > 150
+        end
+
+        # Validates a basket name (1..300 characters).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def basket_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          len = value.length
+          raise InvalidParameterError.new(name, 'between 1 and 300 characters') if len < 1 || len > 300
+        end
+
+        # Validates an originator domain (1..250 bytes UTF-8).
+        # The originator must fit in a single-byte length field in the wire frame.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def originator_domain!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          byte_len = value.bytesize
+          raise InvalidParameterError.new(name, 'at most 250 bytes') if byte_len > 250
+        end
+
+        # Validates a satoshi amount (0..21_000_000 * 10^8).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def satoshi_value!(name, value)
+          raise InvalidParameterError.new(name, 'a non-negative integer') unless value.is_a?(Integer)
+
+          return unless value.negative? || value > MAX_SATOSHIS
+
+          raise InvalidParameterError.new(name, "between 0 and #{MAX_SATOSHIS} satoshis")
+        end
+
+        # Validates a non-negative integer.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def positive_integer_or_zero!(name, value)
+          return if value.is_a?(Integer) && !value.negative?
+
+          raise InvalidParameterError.new(name, 'a non-negative integer')
+        end
+
+        # Validates a BRC-43 protocol name string (5..400 chars, lowercase).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def protocol_string_5_to_400!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          normalized = value.strip.downcase
+          max_length = normalized.start_with?('specific linkage revelation') ? 430 : 400
+
+          raise InvalidParameterError.new(name, "between 5 and #{max_length} characters") if normalized.length < 5 || normalized.length > max_length
+
+          raise InvalidParameterError.new(name, 'lowercase letters, numbers, and spaces only') unless normalized.match?(/\A[a-z0-9 ]+\z/)
+
+          return unless normalized.include?('  ')
+
+          raise InvalidParameterError.new(name, 'free of consecutive spaces')
+        end
+
+        # Validates a BRC-43 key ID string (1..800 bytes).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def key_id_string_1_to_800!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          byte_length = value.bytesize
+          raise InvalidParameterError.new(name, 'between 1 and 800 bytes') if byte_length < 1 || byte_length > 800
+        end
+
+        # Validates a wallet counterparty: 'self', 'anyone', or a 66-char hex pubkey.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def wallet_counterparty!(name, value)
+          return if %w[self anyone].include?(value)
+
+          pub_key_hex!(name, value)
+        end
+
+        # Validates a BRC-43 protocol ID: [security_level (0-2), protocol_name (5-400 chars)].
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def wallet_protocol!(name, value)
+          raise InvalidParameterError.new(name, 'an Array of [security_level, protocol_name]') unless value.is_a?(Array) && value.length == 2
+
+          level, proto_name = value
+          raise InvalidParameterError.new(name, 'a security level of 0, 1, or 2') unless [0, 1, 2].include?(level)
+
+          protocol_string_5_to_400!("#{name} protocol name", proto_name)
+        end
+
+        # Validates a certificate acquisition protocol: 'direct' or 'issuance'.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def acquisition_protocol!(name, value)
+          return if %w[direct issuance].include?(value)
+
+          raise InvalidParameterError.new(name, "'direct' or 'issuance'")
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/wire.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Wire
+      autoload :Frame,        'bsv/wallet/wire/frame'
+      autoload :Calls,        'bsv/wallet/wire/calls'
+      autoload :Validation,   'bsv/wallet/wire/validation'
+      autoload :Writer,       'bsv/wallet/wire/reader_writer'
+      autoload :Reader,       'bsv/wallet/wire/reader_writer'
+    end
+  end
+end

data/lib/bsv/wallet.rb

@@ -8,9 +8,26 @@ module BSV
     require_relative 'wallet/errors'
     require_relative 'wallet/interface'
 
+    # Wire layer — BRC-103 frame codec, call enum, validators, reader/writer.
+    require_relative 'wallet/wire'
+
+    # Per-call BRC-103 serialisers and dispatch tables.
+    autoload :Serializer, 'bsv/wallet/serializer'
+
     # ProtoWallet — minimal crypto-only BRC-100 implementation.
     # Its internals (KeyDeriver, Validators) are scoped under ProtoWallet::
     # to avoid collision with bsv-wallet's own KeyDeriver.
     require_relative 'wallet/proto_wallet'
+
+    # BRC-103 transport layer.
+    autoload :WalletWire,             'bsv/wallet/wallet_wire'
+    autoload :WalletWireTransceiver,  'bsv/wallet/wallet_wire_transceiver'
+    autoload :WalletWireProcessor,    'bsv/wallet/wallet_wire_processor'
+
+    # BRC-103 transport substrates.
+    module Substrates
+      autoload :HTTPWalletWire, 'bsv/wallet/substrates/http_wallet_wire'
+      autoload :HTTPWalletJSON, 'bsv/wallet/substrates/http_wallet_json'
+    end
   end
 end