bsv-sdk 0.19.1 → 0.22.0

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +acquire_certificate+ call (call byte 17).
+      #
+      # Args wire layout:
+      #   [32 bytes: type]
+      #   [33 bytes: certifier pubkey]
+      #   [varint: field_count] per field: [varint-str key][varint-str value]
+      #   [privileged params]
+      #   [1 byte: acquisition_protocol]  1=direct, 2=issuance
+      #   If direct:
+      #     [32 bytes: serial_number]
+      #     [36 bytes: revocation_outpoint]
+      #     [varint: sig_len][sig bytes]
+      #     [keyring_revealer: 0x0B or 33-byte pubkey]
+      #     [varint: keyring_count] per entry: [varint-str key][varint-int base64_value]
+      #   If issuance:
+      #     [varint-str: certifier_url]
+      #
+      # Result wire layout:
+      #   [inline Certificate bytes (type+serial+subject+certifier+outpoint+fields+sig)]
+      module AcquireCertificate
+        ACQUISITION_DIRECT   = 1
+        ACQUISITION_ISSUANCE = 2
+        KEYRING_REVEALER_CERTIFIER = 11 # 0x0B — matches Go keyRingRevealerCertifier
+
+        CERT_TYPE_SIZE = 32
+        SERIAL_SIZE    = 32
+        PUBKEY_SIZE    = 33
+
+        module_function
+
+        def serialize_args(args)
+          w = Wire::Writer.new
+
+          type_bytes = Base64.strict_decode64(args[:type].to_s)
+          w.write_bytes(type_bytes.ljust(CERT_TYPE_SIZE, "\x00").byteslice(0, CERT_TYPE_SIZE))
+          w.write_bytes([args[:certifier].to_s].pack('H*'))
+
+          fields = args[:fields] || {}
+          w.write_varint(fields.length)
+          fields.keys.sort.each do |k|
+            w.write_str_with_varint_len(k)
+            w.write_str_with_varint_len(fields[k].to_s)
+          end
+
+          Common.write_privileged_params(w, args[:privileged], args[:privileged_reason])
+
+          case args[:acquisition_protocol]
+          when :direct
+            w.write_byte(ACQUISITION_DIRECT)
+            serial_bytes = Base64.strict_decode64(args[:serial_number].to_s)
+            w.write_bytes(serial_bytes.ljust(SERIAL_SIZE, "\x00").byteslice(0, SERIAL_SIZE))
+
+            outpoint_str = args[:revocation_outpoint].to_s
+            txid_hex, vout = outpoint_str.split('.', 2)
+            w.write_outpoint(txid_hex.to_s, vout.to_i)
+
+            sig = args[:signature]
+            if sig && !sig.to_s.empty?
+              sig_bytes = [sig.to_s].pack('H*')
+              w.write_int_bytes(sig_bytes)
+            else
+              w.write_varint(0)
+            end
+
+            revealer = args[:keyring_revealer]
+            if revealer == :certifier || (revealer.is_a?(Hash) && revealer[:certifier])
+              w.write_byte(KEYRING_REVEALER_CERTIFIER)
+            else
+              pubkey_hex = revealer.is_a?(Hash) ? revealer[:pub_key].to_s : revealer.to_s
+              w.write_bytes([pubkey_hex].pack('H*'))
+            end
+
+            keyring = args[:keyring_for_subject] || {}
+            w.write_varint(keyring.length)
+            keyring.keys.sort.each do |k|
+              w.write_str_with_varint_len(k)
+              w.write_int_from_base64(keyring[k].to_s)
+            end
+          when :issuance
+            w.write_byte(ACQUISITION_ISSUANCE)
+            w.write_str_with_varint_len(args[:certifier_url].to_s)
+          else
+            raise ArgumentError, "invalid acquisition_protocol: #{args[:acquisition_protocol].inspect}"
+          end
+
+          w.buf
+        end
+
+        def deserialize_args(bytes)
+          r = Wire::Reader.new(bytes)
+
+          type_raw  = r.read_bytes(CERT_TYPE_SIZE)
+          certifier = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+
+          field_count = r.read_varint
+          fields = {}
+          field_count.times do
+            k = r.read_str_with_varint_len
+            v = r.read_str_with_varint_len
+            fields[k] = v
+          end
+
+          privileged, privileged_reason = Common.read_privileged_params(r)
+
+          protocol_byte = r.read_byte
+          acquisition_protocol = case protocol_byte
+                                 when ACQUISITION_DIRECT   then :direct
+                                 when ACQUISITION_ISSUANCE then :issuance
+                                 else raise ArgumentError, "invalid acquisition protocol byte: #{protocol_byte}"
+                                 end
+
+          result = {
+            type: Base64.strict_encode64(type_raw),
+            certifier: certifier,
+            fields: fields,
+            privileged: privileged,
+            privileged_reason: privileged_reason,
+            acquisition_protocol: acquisition_protocol
+          }
+
+          if acquisition_protocol == :direct
+            serial_raw = r.read_bytes(SERIAL_SIZE)
+            result[:serial_number] = Base64.strict_encode64(serial_raw)
+
+            outpoint_data = r.read_outpoint
+            result[:revocation_outpoint] = "#{outpoint_data[:txid_hex]}.#{outpoint_data[:vout]}"
+
+            sig_len = r.read_varint
+            result[:signature] = sig_len.positive? ? r.read_bytes(sig_len).unpack1('H*') : nil
+
+            revealer_byte = r.read_byte
+            if revealer_byte == KEYRING_REVEALER_CERTIFIER
+              result[:keyring_revealer] = { certifier: true }
+            else
+              rest = r.read_bytes(PUBKEY_SIZE - 1)
+              result[:keyring_revealer] = { pub_key: ([revealer_byte].pack('C') + rest).unpack1('H*') }
+            end
+
+            keyring_count = r.read_varint
+            keyring = {}
+            keyring_count.times do
+              k = r.read_str_with_varint_len
+              keyring[k] = r.read_base64_int
+            end
+            result[:keyring_for_subject] = keyring
+          else
+            result[:certifier_url] = r.read_str_with_varint_len
+          end
+
+          result
+        end
+
+        def serialize_result(result)
+          Certificate.serialize_certificate(result[:certificate] || result, include_signature: true)
+        end
+
+        def deserialize_result(bytes)
+          cert = Certificate.deserialize_certificate(bytes)
+          { certificate: cert }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Wallet
+    module Serializer
+      # Shared BRC-103 wire codec for Certificate and IdentityCertificate.
+      #
+      # Certificate wire layout (matches go-sdk serializeCertificate):
+      #   [32 bytes: type (raw bytes decoded from Base64)]
+      #   [32 bytes: serial_number (raw bytes decoded from Base64)]
+      #   [33 bytes: subject compressed pubkey]
+      #   [33 bytes: certifier compressed pubkey]
+      #   [32 bytes + varint: revocation_outpoint (display-order txid + varint vout)]
+      #   [varint: field_count]
+      #   per field: [varint-len name][varint-len value]
+      #   [remaining: DER signature bytes (absent if no signature)]
+      #
+      # IdentityCertificate additionally appends:
+      #   [varint-int: serialised Certificate bytes (int-prefixed)]
+      #   [varint-str: certifier_info.name]
+      #   [varint-str: certifier_info.icon_url]
+      #   [varint-str: certifier_info.description]
+      #   [1 byte: certifier_info.trust]
+      #   [varint: keyring_count] per entry: [varint-str key][varint-int raw_bytes]
+      #   [varint: decrypted_fields_count] per entry: [varint-str key][varint-str value]
+      module Certificate
+        CERT_TYPE_SIZE   = 32
+        SERIAL_SIZE      = 32
+        PUBKEY_SIZE      = 33
+
+        # NULL outpoint used when revocation_outpoint is nil.
+        NULL_TXID_HEX = '00' * 32
+
+        module_function
+
+        # Serialise a certificate Hash to binary.
+        #
+        # @param cert [Hash] with keys: :type (Base64), :serial_number (Base64),
+        #   :subject (hex pubkey), :certifier (hex pubkey),
+        #   :revocation_outpoint (String "txid.vout" or nil),
+        #   :fields (Hash<String,String>), :signature (hex bytes or nil)
+        # @param include_signature [Boolean] whether to append signature bytes
+        # @return [String] binary
+        def serialize_certificate(cert, include_signature: true)
+          w = Wire::Writer.new
+
+          type_bytes   = Base64.strict_decode64(cert[:type].to_s)
+          serial_bytes = Base64.strict_decode64(cert[:serial_number].to_s)
+
+          w.write_bytes(type_bytes.ljust(CERT_TYPE_SIZE, "\x00").byteslice(0, CERT_TYPE_SIZE))
+          w.write_bytes(serial_bytes.ljust(SERIAL_SIZE, "\x00").byteslice(0, SERIAL_SIZE))
+          w.write_bytes([cert[:subject].to_s].pack('H*'))
+          w.write_bytes([cert[:certifier].to_s].pack('H*'))
+
+          outpoint_str = cert[:revocation_outpoint].to_s
+          if outpoint_str.empty? || outpoint_str == '.'
+            w.write_outpoint(NULL_TXID_HEX, 0)
+          else
+            txid_hex, vout = outpoint_str.split('.', 2)
+            w.write_outpoint(txid_hex.to_s, vout.to_i)
+          end
+
+          fields = cert[:fields] || {}
+          w.write_varint(fields.length)
+          fields.keys.sort.each do |name|
+            w.write_str_with_varint_len(name)
+            w.write_str_with_varint_len(fields[name].to_s)
+          end
+
+          w.write_bytes([cert[:signature].to_s].pack('H*')) if include_signature && cert[:signature] && !cert[:signature].empty?
+
+          w.buf
+        end
+
+        # Deserialise a certificate from binary.
+        #
+        # @param bytes [String] binary
+        # @return [Hash]
+        def deserialize_certificate(bytes)
+          r = Wire::Reader.new(bytes)
+          type_raw   = r.read_bytes(CERT_TYPE_SIZE)
+          serial_raw = r.read_bytes(SERIAL_SIZE)
+          subject    = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+          certifier  = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+
+          outpoint_data       = r.read_outpoint
+          revocation_outpoint = "#{outpoint_data[:txid_hex]}.#{outpoint_data[:vout]}"
+
+          field_count = r.read_varint
+          fields = {}
+          field_count.times do
+            name  = r.read_str_with_varint_len
+            value = r.read_str_with_varint_len
+            fields[name] = value
+          end
+
+          sig_bytes = r.read_remaining
+          signature = sig_bytes.empty? ? nil : sig_bytes.unpack1('H*')
+
+          {
+            type: Base64.strict_encode64(type_raw),
+            serial_number: Base64.strict_encode64(serial_raw),
+            subject: subject,
+            certifier: certifier,
+            revocation_outpoint: revocation_outpoint,
+            fields: fields,
+            signature: signature
+          }
+        end
+
+        # Serialise an IdentityCertificate (used by discover_* result).
+        #
+        # @param cert [Hash] all Certificate fields plus:
+        #   :certifier_info ({ name:, icon_url:, description:, trust: })
+        #   :publicly_revealed_keyring (Hash<String,Base64>)
+        #   :decrypted_fields (Hash<String,String>)
+        def serialize_identity_certificate(cert)
+          w = Wire::Writer.new
+
+          cert_bytes = serialize_certificate(cert, include_signature: true)
+          w.write_int_bytes(cert_bytes)
+
+          info = cert[:certifier_info] || {}
+          w.write_str_with_varint_len(info[:name].to_s)
+          w.write_str_with_varint_len(info[:icon_url].to_s)
+          w.write_str_with_varint_len(info[:description].to_s)
+          w.write_byte((info[:trust] || 0).to_i & 0xFF)
+
+          keyring = cert[:publicly_revealed_keyring] || {}
+          w.write_varint(keyring.length)
+          keyring.keys.sort.each do |k|
+            w.write_str_with_varint_len(k)
+            w.write_int_from_base64(keyring[k].to_s)
+          end
+
+          dec_fields = cert[:decrypted_fields] || {}
+          w.write_varint(dec_fields.length)
+          dec_fields.keys.sort.each do |k|
+            w.write_str_with_varint_len(k)
+            w.write_str_with_varint_len(dec_fields[k].to_s)
+          end
+
+          w.buf
+        end
+
+        # Deserialise an IdentityCertificate from a Reader (reads inline, not length-prefixed).
+        #
+        # @param reader [Wire::Reader]
+        # @return [Hash]
+        def deserialize_identity_certificate(reader)
+          cert_bytes = reader.read_int_bytes
+          cert = deserialize_certificate(cert_bytes)
+
+          cert[:certifier_info] = {
+            name: reader.read_str_with_varint_len,
+            icon_url: reader.read_str_with_varint_len,
+            description: reader.read_str_with_varint_len,
+            trust: reader.read_byte
+          }
+
+          keyring_len = reader.read_varint
+          keyring = {}
+          keyring_len.times do
+            k = reader.read_str_with_varint_len
+            keyring[k] = reader.read_base64_int
+          end
+          cert[:publicly_revealed_keyring] = keyring
+
+          dec_len = reader.read_varint
+          dec_fields = {}
+          dec_len.times do
+            k = reader.read_str_with_varint_len
+            dec_fields[k] = reader.read_str_with_varint_len
+          end
+          cert[:decrypted_fields] = dec_fields
+
+          cert
+        end
+      end
+    end
+  end
+end

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