bsv-sdk 0.20.0 → 0.22.0

data/lib/bsv/wallet/serializer/common.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # Shared binary encoding helpers for BRC-103 per-call serializers.
+      #
+      # Port of the shared helpers in go-sdk/wallet/serializer/serializer.go.
+      # All methods operate on BSV::Wallet::Wire::Writer / Reader instances.
+      module Common
+        COUNTERPARTY_SELF    = 11 # 0x0B
+        COUNTERPARTY_ANYONE  = 12 # 0x0C
+        PUBKEY_SIZE          = 33 # compressed secp256k1 public key
+
+        module_function
+
+        # Coerce a byte payload to a binary String (ASCII-8BIT encoding).
+        #
+        # Accepts either an Array<Integer> (as returned by ProtoWallet) or a
+        # String. Serialisers use this so they remain compatible with both the
+        # in-process wallet interface (Arrays) and the wire interface (Strings).
+        def to_binary(bytes)
+          return ''.b if bytes.nil?
+          return bytes.pack('C*').b if bytes.is_a?(Array)
+
+          bytes.b
+        end
+
+        # Encode a BRC-43 protocol ID: [security_level (0-2), protocol_name].
+        #
+        # Wire format: 1-byte security level + varint-len string.
+        def write_protocol(writer, protocol_id)
+          level, name = protocol_id
+          writer.write_byte(level.to_i)
+          writer.write_str_with_varint_len(name.to_s)
+        end
+
+        def read_protocol(reader)
+          level = reader.read_byte
+          name  = reader.read_str_with_varint_len
+          [level, name]
+        end
+
+        # Encode a counterparty: 'self' | 'anyone' | 66-char hex compressed pubkey.
+        #
+        # Wire format:
+        #   0x0B — self
+        #   0x0C — anyone
+        #   02/03 <32 bytes> — specific pubkey (first byte is the prefix of the 33-byte key)
+        def write_counterparty(writer, counterparty)
+          case counterparty
+          when 'self'
+            writer.write_byte(COUNTERPARTY_SELF)
+          when 'anyone'
+            writer.write_byte(COUNTERPARTY_ANYONE)
+          else
+            writer.write_bytes([counterparty].pack('H*'))
+          end
+        end
+
+        def read_counterparty(reader)
+          first = reader.read_byte
+          case first
+          when COUNTERPARTY_SELF
+            'self'
+          when COUNTERPARTY_ANYONE
+            'anyone'
+          else
+            rest = reader.read_bytes(PUBKEY_SIZE - 1)
+            ([first].pack('C') + rest).unpack1('H*')
+          end
+        end
+
+        # Encode privileged flag + privileged_reason.
+        #
+        # Wire format: optional_bool (0xFF=nil, 0x00=false, 0x01=true) + reason as varint-len string,
+        # or 0xFF if reason is nil/empty (NegativeOneByte sentinel).
+        def write_privileged_params(writer, privileged, privileged_reason)
+          writer.write_optional_bool(privileged)
+          reason = privileged_reason.to_s
+          if reason.empty?
+            writer.write_byte(0xFF)
+          else
+            writer.write_str_with_varint_len(reason)
+          end
+        end
+
+        def read_privileged_params(reader)
+          privileged = reader.read_optional_bool
+          # 0xFF as the leading byte is the nil-reason sentinel. Otherwise the
+          # bytes start a Bitcoin varint length prefix (which can be 0xFD or
+          # 0xFE for reasons >= 253 bytes; 0xFF would only collide if the
+          # reason exceeded 4 GiB, which the protocol does not permit).
+          if reader.peek_byte == 0xFF
+            reader.read_byte
+            [privileged, nil]
+          else
+            [privileged, reader.read_str_with_varint_len]
+          end
+        end
+
+        # Encode key-related params: protocol + key_id + counterparty + privileged params.
+        def write_key_related_params(writer, protocol_id:, key_id:, counterparty:,
+                                     privileged: nil, privileged_reason: nil)
+          write_protocol(writer, protocol_id)
+          writer.write_str_with_varint_len(key_id.to_s)
+          write_counterparty(writer, counterparty)
+          write_privileged_params(writer, privileged, privileged_reason)
+        end
+
+        def read_key_related_params(reader)
+          protocol_id       = read_protocol(reader)
+          key_id            = reader.read_str_with_varint_len
+          counterparty      = read_counterparty(reader)
+          privileged, reason = read_privileged_params(reader)
+          {
+            protocol_id: protocol_id,
+            key_id: key_id,
+            counterparty: counterparty,
+            privileged: privileged,
+            privileged_reason: reason
+          }
+        end
+
+        # Encode a list of outpoints (varint count + 32-byte wire-order txid + varint vout each).
+        # Returns nil bytes for nil input.
+        # @param outpoints [Array<String>, nil] array of "txid_hex.vout" strings
+        # @return [String, nil] binary or nil
+        def encode_outpoints(outpoints)
+          return nil if outpoints.nil?
+
+          w = Wire::Writer.new
+          w.write_varint(outpoints.length)
+          outpoints.each do |op|
+            txid_hex, vout = op.split('.')
+            w.write_bytes([txid_hex].pack('H*'))
+            w.write_varint(vout.to_i)
+          end
+          w.buf
+        end
+
+        # Decode a list of outpoints from binary (encoded as encode_outpoints).
+        # @param bytes [String, nil] binary data
+        # @return [Array<String>, nil] array of "txid_hex.vout" strings
+        def decode_outpoints(bytes)
+          return nil if bytes.nil? || bytes.b.empty?
+
+          r = Wire::Reader.new(bytes)
+          count = r.read_varint
+          return nil if count == 0xFFFF_FFFF_FFFF_FFFF
+
+          count.times.map do
+            txid_hex = r.read_bytes(32).unpack1('H*')
+            vout = r.read_varint
+            "#{txid_hex}.#{vout}"
+          end
+        end
+
+        # Send-with result status codes (Go status.go).
+        SEND_WITH_STATUS_UNPROVEN = 1
+        SEND_WITH_STATUS_SENDING  = 2
+        SEND_WITH_STATUS_FAILED   = 3
+
+        SEND_WITH_STATUS_CODES = {
+          unproven: SEND_WITH_STATUS_UNPROVEN,
+          sending: SEND_WITH_STATUS_SENDING,
+          failed: SEND_WITH_STATUS_FAILED
+        }.freeze
+
+        SEND_WITH_CODE_STATUSES = SEND_WITH_STATUS_CODES.invert.freeze
+
+        # Write a send_with_results array: varint count + txid (32 bytes) + status byte each.
+        # nil or empty → writes 0 count.
+        # @param writer [Wire::Writer]
+        # @param results [Array<Hash>, nil] array of { txid: String, status: Symbol }
+        def write_send_with_results(writer, results)
+          arr = results || []
+          writer.write_varint(arr.length)
+          arr.each do |res|
+            writer.write_bytes([res[:txid]].pack('H*'))
+            code = SEND_WITH_STATUS_CODES.fetch(res[:status]) do
+              raise ArgumentError, "invalid send_with status: #{res[:status]}"
+            end
+            writer.write_byte(code)
+          end
+        end
+
+        # Read a send_with_results array.
+        # @param reader [Wire::Reader]
+        # @return [Array<Hash>, nil]
+        def read_send_with_results(reader)
+          count = reader.read_varint
+          return nil if count.zero?
+
+          count.times.map do
+            txid_hex = reader.read_bytes(32).unpack1('H*')
+            code = reader.read_byte
+            status = SEND_WITH_CODE_STATUSES.fetch(code) do
+              raise ArgumentError, "invalid send_with status code: #{code}"
+            end
+            { txid: txid_hex, status: status }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/serializer/create_action_args.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for create_action args (call byte 1).
+      #
+      # Wire layout (port of go-sdk/wallet/serializer/create_action_args.go):
+      #   [string]          description
+      #   [optional_bytes]  input_beef (NegativeOne = nil)
+      #   [inputs]          NegativeOne | varint_count + input_record…
+      #   [outputs]         NegativeOne | varint_count + output_record…
+      #   [optional_uint32] lock_time
+      #   [optional_uint32] version
+      #   [string_slice]    labels
+      #   [options_block]   0x00 = absent | 0x01 + fields
+      #
+      # Input record:
+      #   [32 bytes] outpoint txid (wire order)
+      #   [varint]   outpoint vout
+      #   [int_bytes or NegativeOne + varint] unlocking_script or length placeholder
+      #   [string]   input_description
+      #   [optional_uint32] sequence_number
+      #
+      # Output record:
+      #   [int_bytes] locking_script
+      #   [varint]    satoshis
+      #   [string]    output_description
+      #   [optional_string] basket
+      #   [optional_string] custom_instructions
+      #   [string_slice] tags
+      #
+      # Options block (after 0x01 presence byte):
+      #   [optional_bool] sign_and_process
+      #   [optional_bool] accept_delayed_broadcast
+      #   [0x01 or 0xFF]     trust_self (1=known, 0xFF=absent)
+      #   [txid_slice]       known_txids
+      #   [optional_bool] return_txid_only
+      #   [optional_bool] no_send
+      #   [optional_bytes]   no_send_change (encoded outpoints, NegativeOne = nil)
+      #   [txid_slice]       send_with
+      #   [optional_bool] randomize_outputs
+      module CreateActionArgs
+        TRUST_SELF_KNOWN = 1
+
+        module_function
+
+        # @param args [Hash]
+        # @return [String] binary
+        def serialize(args)
+          w = Wire::Writer.new
+
+          w.write_string(args[:description].to_s)
+          input_beef = args[:input_beef]
+          if input_beef.nil? || input_beef.b.empty?
+            w.write_negative_one
+          else
+            w.write_int_bytes(input_beef)
+          end
+
+          serialize_inputs(w, args[:inputs])
+          serialize_outputs(w, args[:outputs])
+
+          w.write_optional_uint32(args[:lock_time])
+          w.write_optional_uint32(args[:version])
+          w.write_string_slice(args[:labels])
+
+          serialize_options(w, args[:options])
+
+          w.buf
+        end
+
+        # @param bytes [String] binary
+        # @return [Hash]
+        def deserialize(bytes)
+          raise ArgumentError, 'empty message' if bytes.b.empty?
+
+          r = Wire::Reader.new(bytes)
+
+          description = r.read_string
+          input_beef  = r.read_int_bytes
+          input_beef  = nil if input_beef.empty?
+
+          inputs  = deserialize_inputs(r)
+          outputs = deserialize_outputs(r)
+
+          lock_time = r.read_optional_uint32
+          version   = r.read_optional_uint32
+          labels    = r.read_string_slice
+
+          options = deserialize_options(r)
+
+          result = { description: description }
+          result[:input_beef] = input_beef unless input_beef.nil?
+          result[:inputs]  = inputs  unless inputs.nil?
+          result[:outputs] = outputs unless outputs.nil?
+          result[:lock_time] = lock_time unless lock_time.nil?
+          result[:version]   = version   unless version.nil?
+          result[:labels]    = labels    unless labels.nil?
+          result[:options]   = options   unless options.nil?
+          result
+        end
+
+        def serialize_inputs(writer, inputs)
+          if inputs.nil?
+            writer.write_negative_one
+            return
+          end
+
+          writer.write_varint(inputs.length)
+          inputs.each do |inp|
+            txid_hex, vout = inp[:outpoint].split('.')
+            writer.write_bytes([txid_hex].pack('H*'))
+            writer.write_varint(vout.to_i)
+
+            script = inp[:unlocking_script]
+            if script && !script.b.empty?
+              writer.write_int_bytes(script)
+            else
+              writer.write_negative_one
+              writer.write_varint(inp[:unlocking_script_length].to_i)
+            end
+
+            writer.write_string(inp[:input_description].to_s)
+            writer.write_optional_uint32(inp[:sequence_number])
+          end
+        end
+
+        def serialize_outputs(writer, outputs)
+          if outputs.nil?
+            writer.write_negative_one
+            return
+          end
+
+          writer.write_varint(outputs.length)
+          outputs.each do |out|
+            writer.write_int_bytes(out[:locking_script])
+            writer.write_varint(out[:satoshis].to_i)
+            writer.write_string(out[:output_description].to_s)
+            writer.write_optional_string(out[:basket])
+            writer.write_optional_string(out[:custom_instructions])
+            writer.write_string_slice(out[:tags])
+          end
+        end
+
+        def serialize_options(writer, opts)
+          if opts.nil?
+            writer.write_byte(0)
+            return
+          end
+
+          writer.write_byte(1)
+          writer.write_optional_bool(opts[:sign_and_process])
+          writer.write_optional_bool(opts[:accept_delayed_broadcast])
+
+          if opts[:trust_self] == :known
+            writer.write_byte(TRUST_SELF_KNOWN)
+          else
+            writer.write_byte(0xFF)
+          end
+
+          writer.write_txid_slice(opts[:known_txids])
+          writer.write_optional_bool(opts[:return_txid_only])
+          writer.write_optional_bool(opts[:no_send])
+
+          no_send_change_bytes = Common.encode_outpoints(opts[:no_send_change])
+          writer.write_int_bytes(no_send_change_bytes)
+
+          writer.write_txid_slice(opts[:send_with])
+          writer.write_optional_bool(opts[:randomize_outputs])
+        end
+
+        def deserialize_inputs(reader)
+          count = reader.read_varint
+          return nil if count == 0xFFFF_FFFF_FFFF_FFFF
+
+          count.times.map do
+            txid_hex = reader.read_bytes(32).unpack1('H*')
+            vout     = reader.read_varint
+            outpoint = "#{txid_hex}.#{vout}"
+
+            script_len = reader.read_varint
+            inp = { outpoint: outpoint }
+
+            if script_len == 0xFFFF_FFFF_FFFF_FFFF
+              length = reader.read_varint
+              inp[:unlocking_script_length] = length
+            else
+              script = reader.read_bytes(script_len)
+              inp[:unlocking_script] = script
+              inp[:unlocking_script_length] = script_len
+            end
+
+            inp[:input_description] = reader.read_string
+            seq = reader.read_optional_uint32
+            inp[:sequence_number] = seq unless seq.nil?
+            inp
+          end
+        end
+
+        def deserialize_outputs(reader)
+          count = reader.read_varint
+          return nil if count == 0xFFFF_FFFF_FFFF_FFFF
+
+          count.times.map do
+            script   = reader.read_int_bytes
+            satoshis = reader.read_varint
+            out_desc = reader.read_string
+            basket   = reader.read_optional_string
+            custom   = reader.read_optional_string
+            tags     = reader.read_string_slice
+
+            out = { locking_script: script, satoshis: satoshis, output_description: out_desc }
+            out[:basket]              = basket unless basket.nil?
+            out[:custom_instructions] = custom unless custom.nil?
+            out[:tags]                = tags   unless tags.nil?
+            out
+          end
+        end
+
+        def deserialize_options(reader)
+          return nil if reader.read_byte != 1
+
+          opts = {}
+
+          sign_and_process         = reader.read_optional_bool
+          accept_delayed_broadcast = reader.read_optional_bool
+
+          trust_byte = reader.read_byte
+          trust_self = trust_byte == TRUST_SELF_KNOWN ? :known : nil
+
+          known_txids = reader.read_txid_slice
+          return_txid_only = reader.read_optional_bool
+          no_send          = reader.read_optional_bool
+
+          no_send_change_bytes = reader.read_int_bytes
+          no_send_change = Common.decode_outpoints(no_send_change_bytes.empty? ? nil : no_send_change_bytes)
+
+          send_with          = reader.read_txid_slice
+          randomize_outputs  = reader.read_optional_bool
+
+          opts[:sign_and_process]          = sign_and_process         unless sign_and_process.nil?
+          opts[:accept_delayed_broadcast]  = accept_delayed_broadcast unless accept_delayed_broadcast.nil?
+          opts[:trust_self]                = trust_self                unless trust_self.nil?
+          opts[:known_txids]               = known_txids               unless known_txids.nil?
+          opts[:return_txid_only]          = return_txid_only          unless return_txid_only.nil?
+          opts[:no_send]                   = no_send                   unless no_send.nil?
+          opts[:no_send_change]            = no_send_change            unless no_send_change.nil?
+          opts[:send_with]                 = send_with                 unless send_with.nil?
+          opts[:randomize_outputs]         = randomize_outputs         unless randomize_outputs.nil?
+          opts
+        end
+
+        private_class_method :serialize_inputs, :serialize_outputs, :serialize_options,
+                             :deserialize_inputs, :deserialize_outputs, :deserialize_options
+      end
+    end
+  end
+end

data/lib/bsv/wallet/serializer/create_action_result.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for create_action result (call byte 1).
+      #
+      # Wire layout (port of go-sdk/wallet/serializer/create_action_result.go):
+      #   [1 byte]           0x00 success sentinel (frame-level, already checked by Frame)
+      #   [flag + 32 bytes]  txid (wire-order) with flag byte: 0=absent, 1=present
+      #   [flag + int_bytes] tx (BEEF bytes) with flag byte: 0=absent, 1=present + varint_len
+      #   [optional_bytes]   no_send_change encoded outpoints (NegativeOne = nil)
+      #   [send_with_results] varint count + txid + status_byte each
+      #   [1 byte flag]      signable_transaction: 0=absent, 1=present
+      #   If signable_transaction present:
+      #     [int_bytes]      tx (BEEF bytes)
+      #     [int_bytes]      reference bytes
+      module CreateActionResult
+        module_function
+
+        # @param result [Hash]
+        # @return [String] binary
+        def serialize(result)
+          w = Wire::Writer.new
+          w.write_byte(0) # success sentinel
+
+          txid_bytes = result[:txid] ? [result[:txid]].pack('H*').reverse : nil
+          w.write_optional_bytes_with_flag(txid_bytes, fixed_size: 32)
+          w.write_optional_bytes_with_flag(result[:tx])
+
+          no_send_change_bytes = Common.encode_outpoints(result[:no_send_change])
+          w.write_int_bytes(no_send_change_bytes)
+
+          Common.write_send_with_results(w, result[:send_with_results])
+
+          signable = result[:signable_transaction]
+          if signable
+            w.write_byte(1)
+            w.write_int_bytes(signable[:tx])
+            w.write_int_bytes(signable[:reference])
+          else
+            w.write_byte(0)
+          end
+
+          w.buf
+        end
+
+        # @param bytes [String] binary
+        # @return [Hash]
+        def deserialize(bytes)
+          raise ArgumentError, 'empty response data' if bytes.b.empty?
+
+          r = Wire::Reader.new(bytes)
+
+          status = r.read_byte
+          raise ArgumentError, "response indicates failure: #{status}" unless status.zero?
+
+          txid_raw = r.read_optional_bytes_with_flag(fixed_size: 32)
+          txid_hex = txid_raw&.reverse&.unpack1('H*')
+          tx       = r.read_optional_bytes_with_flag
+
+          no_send_change_bytes = r.read_int_bytes
+          no_send_change = Common.decode_outpoints(no_send_change_bytes.empty? ? nil : no_send_change_bytes)
+
+          send_with_results = Common.read_send_with_results(r)
+
+          signable_flag = r.read_byte
+          signable_transaction = if signable_flag == 1
+                                   tx_bytes  = r.read_int_bytes
+                                   ref_bytes = r.read_int_bytes
+                                   { tx: tx_bytes, reference: ref_bytes }
+                                 end
+
+          result = {}
+          result[:txid]                = txid_hex            unless txid_hex.nil?
+          result[:tx]                  = tx                  unless tx.nil?
+          result[:no_send_change]      = no_send_change      unless no_send_change.nil?
+          result[:send_with_results]   = send_with_results   unless send_with_results.nil?
+          result[:signable_transaction] = signable_transaction unless signable_transaction.nil?
+          result
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/serializer/create_hmac.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +create_hmac+ call (call byte 13).
+      #
+      # Port of go-sdk/wallet/serializer/create_hmac.go.
+      module CreateHmac
+        HMAC_SIZE = 32
+
+        # Args wire layout:
+        #   [key-related params]
+        #   [VarInt data_len][data bytes]
+        #   [optional_bool seek_permission]
+        module Args
+          module_function
+
+          def serialize(args)
+            w = BSV::Wallet::Wire::Writer.new
+            Common.write_key_related_params(
+              w,
+              protocol_id: args[:protocol_id],
+              key_id: args[:key_id],
+              counterparty: args[:counterparty],
+              privileged: args[:privileged],
+              privileged_reason: args[:privileged_reason]
+            )
+            data = Common.to_binary(args[:data])
+            w.write_varint(data.bytesize)
+            w.write_bytes(data)
+            w.write_optional_bool(args[:seek_permission])
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            params = Common.read_key_related_params(r)
+            len = r.read_varint
+            data = r.read_bytes(len)
+            seek_permission = r.read_optional_bool
+            params.merge(data: data, seek_permission: seek_permission)
+          end
+        end
+
+        # Result wire layout:
+        #   [32 bytes: HMAC-SHA-256]
+        module Result
+          module_function
+
+          def serialize(result)
+            hmac = Common.to_binary(result[:hmac])
+            raise ArgumentError, "HMAC must be #{HMAC_SIZE} bytes, got #{hmac.bytesize}" unless hmac.bytesize == HMAC_SIZE
+
+            hmac
+          end
+
+          def deserialize(bytes)
+            raise ArgumentError, "HMAC result too short: #{bytes.bytesize}" if bytes.bytesize < HMAC_SIZE
+
+            { hmac: bytes.byteslice(0, HMAC_SIZE) }
+          end
+        end
+      end
+    end
+  end
+end