bsv-sdk 0.20.0 → 0.23.0

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

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