bsv-sdk 0.20.0 → 0.22.0

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +list_outputs+ call (call byte 6).
+      #
+      # Args wire layout:
+      #   [varint-str: basket]
+      #   [string-slice: tags]  nil → NegativeOne
+      #   [1 byte: tag_query_mode]  1=all, 2=any, 0xFF=nil
+      #   [1 byte: include]  1=locking_scripts, 2=entire_transactions, 0xFF=nil
+      #   [optional_bool: include_custom_instructions]
+      #   [optional_bool: include_tags]
+      #   [optional_bool: include_labels]
+      #   [optional_uint32: limit]
+      #   [optional_uint32: offset]
+      #   [optional_bool: seek_permission]
+      #
+      # Result wire layout:
+      #   [varint: total_outputs]
+      #   [varint: beef_len, or NegativeOne if nil][beef bytes]
+      #   per output:
+      #     [32-byte wire txid][varint vout]
+      #     [varint: satoshis]
+      #     [varint: locking_script_len, or NegativeOne][script bytes]
+      #     [varint-str: custom_instructions]  0-length string if nil
+      #     [string-slice: tags]
+      #     [string-slice: labels]
+      module ListOutputs
+        TAG_QUERY_MODE_ALL = 1
+        TAG_QUERY_MODE_ANY = 2
+        INCLUDE_LOCKING_SCRIPTS     = 1
+        INCLUDE_ENTIRE_TRANSACTIONS = 2
+        NEGATIVE_ONE_BYTE = 0xFF
+
+        module_function
+
+        def serialize_args(args)
+          w = Wire::Writer.new
+          w.write_str_with_varint_len(args.fetch(:basket, ''))
+          w.write_string_slice(args[:tags])
+
+          mode_byte = case args[:tag_query_mode]
+                      when :all then TAG_QUERY_MODE_ALL
+                      when :any then TAG_QUERY_MODE_ANY
+                      else           NEGATIVE_ONE_BYTE
+                      end
+          w.write_byte(mode_byte)
+
+          include_byte = case args[:include]
+                         when :locking_scripts      then INCLUDE_LOCKING_SCRIPTS
+                         when :entire_transactions  then INCLUDE_ENTIRE_TRANSACTIONS
+                         else                            NEGATIVE_ONE_BYTE
+                         end
+          w.write_byte(include_byte)
+
+          w.write_optional_bool(args[:include_custom_instructions])
+          w.write_optional_bool(args[:include_tags])
+          w.write_optional_bool(args[:include_labels])
+          w.write_optional_uint32(args[:limit])
+          w.write_optional_uint32(args[:offset])
+          w.write_optional_bool(args[:seek_permission])
+          w.buf
+        end
+
+        def deserialize_args(bytes)
+          r = Wire::Reader.new(bytes)
+          basket = r.read_str_with_varint_len
+          tags   = r.read_string_slice
+
+          mode = case r.read_byte
+                 when TAG_QUERY_MODE_ALL then :all
+                 when TAG_QUERY_MODE_ANY then :any
+                 end
+
+          inc = case r.read_byte
+                when INCLUDE_LOCKING_SCRIPTS     then :locking_scripts
+                when INCLUDE_ENTIRE_TRANSACTIONS then :entire_transactions
+                end
+
+          {
+            basket: basket,
+            tags: tags,
+            tag_query_mode: mode,
+            include: inc,
+            include_custom_instructions: r.read_optional_bool,
+            include_tags: r.read_optional_bool,
+            include_labels: r.read_optional_bool,
+            limit: r.read_optional_uint32,
+            offset: r.read_optional_uint32,
+            seek_permission: r.read_optional_bool
+          }
+        end
+
+        def serialize_result(result)
+          w = Wire::Writer.new
+          outputs = result[:outputs] || []
+          w.write_varint(outputs.length)
+
+          beef = result[:beef]
+          if beef
+            w.write_int_bytes(beef.b)
+          else
+            w.write_negative_one
+          end
+
+          outputs.each do |output|
+            outpoint = output[:outpoint] || ''
+            txid_hex, vout = outpoint.to_s.split('.', 2)
+            w.write_outpoint(txid_hex.to_s, vout.to_i)
+            w.write_varint(output[:satoshis].to_i)
+            locking_script = output[:locking_script]
+            if locking_script && !locking_script.empty?
+              w.write_int_bytes(locking_script.b)
+            else
+              w.write_negative_one
+            end
+            w.write_optional_string(output[:custom_instructions])
+            w.write_string_slice(output[:tags])
+            w.write_string_slice(output[:labels])
+          end
+          w.buf
+        end
+
+        def deserialize_result(bytes)
+          r = Wire::Reader.new(bytes)
+          total_outputs = r.read_varint
+
+          beef_len = r.read_varint
+          beef = if beef_len == 0xFFFF_FFFF_FFFF_FFFF
+                   nil
+                 else
+                   r.read_bytes(beef_len)
+                 end
+
+          outputs = total_outputs.times.map do
+            outpoint_data = r.read_outpoint
+            outpoint = "#{outpoint_data[:txid_hex]}.#{outpoint_data[:vout]}"
+            satoshis = r.read_varint
+            locking_script_len = r.read_varint
+            locking_script = if locking_script_len == 0xFFFF_FFFF_FFFF_FFFF
+                               nil
+                             else
+                               r.read_bytes(locking_script_len)
+                             end
+            custom_instructions = r.read_optional_string
+            tags   = r.read_string_slice
+            labels = r.read_string_slice
+
+            {
+              outpoint: outpoint,
+              satoshis: satoshis,
+              locking_script: locking_script,
+              custom_instructions: custom_instructions,
+              tags: tags,
+              labels: labels,
+              spendable: true
+            }
+          end
+
+          { total_outputs: total_outputs, beef: beef, outputs: outputs }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +prove_certificate+ call (call byte 19).
+      #
+      # Args wire layout (matches go-sdk SerializeProveCertificateArgs):
+      #   [32 bytes: cert.type]
+      #   [33 bytes: cert.subject pubkey]
+      #   [32 bytes: cert.serial_number]
+      #   [33 bytes: cert.certifier pubkey]
+      #   [36 bytes: cert.revocation_outpoint]
+      #   [varint-int: cert.signature bytes] (0-length if nil)
+      #   [varint: field_count] per field: [varint-int name_bytes][varint-int value_bytes]
+      #   [varint: fields_to_reveal_count] per field: [varint-int name_bytes]
+      #   [33 bytes: verifier pubkey]
+      #   [privileged params]
+      #
+      # Result wire layout:
+      #   [varint: keyring_count] per entry: [varint-int key_bytes][varint-int base64 bytes]
+      module ProveCertificate
+        CERT_TYPE_SIZE = 32
+        SERIAL_SIZE    = 32
+        PUBKEY_SIZE    = 33
+
+        module_function
+
+        def serialize_args(args)
+          w = Wire::Writer.new
+          cert = args[:certificate] || {}
+
+          type_bytes = Base64.strict_decode64(cert[:type].to_s)
+          w.write_bytes(type_bytes.ljust(CERT_TYPE_SIZE, "\x00").byteslice(0, CERT_TYPE_SIZE))
+          w.write_bytes([cert[:subject].to_s].pack('H*'))
+
+          serial_bytes = Base64.strict_decode64(cert[:serial_number].to_s)
+          w.write_bytes(serial_bytes.ljust(SERIAL_SIZE, "\x00").byteslice(0, SERIAL_SIZE))
+          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(Certificate::NULL_TXID_HEX, 0)
+          else
+            txid_hex, vout = outpoint_str.split('.', 2)
+            w.write_outpoint(txid_hex.to_s, vout.to_i)
+          end
+
+          sig = cert[:signature]
+          if sig && !sig.to_s.empty?
+            w.write_int_bytes([sig.to_s].pack('H*'))
+          else
+            w.write_int_bytes(''.b)
+          end
+
+          fields = cert[:fields] || {}
+          w.write_varint(fields.length)
+          fields.keys.sort.each do |k|
+            w.write_int_bytes(k.b)
+            w.write_int_bytes(fields[k].to_s.b)
+          end
+
+          fields_to_reveal = args[:fields_to_reveal] || []
+          w.write_varint(fields_to_reveal.length)
+          fields_to_reveal.each { |f| w.write_int_bytes(f.to_s.b) }
+
+          w.write_bytes([args[:verifier].to_s].pack('H*'))
+
+          Common.write_privileged_params(w, args[:privileged], args[:privileged_reason])
+          w.buf
+        end
+
+        def deserialize_args(bytes)
+          r = Wire::Reader.new(bytes)
+
+          type_raw   = r.read_bytes(CERT_TYPE_SIZE)
+          subject    = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+          serial_raw = r.read_bytes(SERIAL_SIZE)
+          certifier  = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+
+          outpoint_data = r.read_outpoint
+          revocation_outpoint = "#{outpoint_data[:txid_hex]}.#{outpoint_data[:vout]}"
+
+          sig_bytes = r.read_int_bytes
+          signature = sig_bytes.empty? ? nil : sig_bytes.unpack1('H*')
+
+          field_count = r.read_varint
+          fields = {}
+          field_count.times do
+            k = r.read_int_bytes.force_encoding('UTF-8')
+            v = r.read_int_bytes.force_encoding('UTF-8')
+            fields[k] = v
+          end
+
+          fields_to_reveal_count = r.read_varint
+          fields_to_reveal = fields_to_reveal_count.times.map do
+            r.read_int_bytes.force_encoding('UTF-8')
+          end
+
+          verifier = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+          privileged, privileged_reason = Common.read_privileged_params(r)
+
+          {
+            certificate: {
+              type: Base64.strict_encode64(type_raw),
+              subject: subject,
+              serial_number: Base64.strict_encode64(serial_raw),
+              certifier: certifier,
+              revocation_outpoint: revocation_outpoint,
+              signature: signature,
+              fields: fields
+            },
+            fields_to_reveal: fields_to_reveal,
+            verifier: verifier,
+            privileged: privileged,
+            privileged_reason: privileged_reason
+          }
+        end
+
+        def serialize_result(result)
+          w = Wire::Writer.new
+          keyring = result[:keyring_for_verifier] || {}
+          w.write_varint(keyring.length)
+          keyring.keys.sort.each do |k|
+            w.write_int_bytes(k.to_s.b)
+            w.write_int_from_base64(keyring[k].to_s)
+          end
+          w.buf
+        end
+
+        def deserialize_result(bytes)
+          r = Wire::Reader.new(bytes)
+          count = r.read_varint
+          keyring = {}
+          count.times do
+            k = r.read_int_bytes.force_encoding('UTF-8')
+            keyring[k] = r.read_base64_int
+          end
+          { keyring_for_verifier: keyring }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +relinquish_certificate+ call (call byte 20).
+      #
+      # Args wire layout:
+      #   [32 bytes: type]
+      #   [32 bytes: serial_number]
+      #   [33 bytes: certifier pubkey]
+      #
+      # Result wire layout:
+      #   [empty — relinquished is implicit from the frame error byte]
+      module RelinquishCertificate
+        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))
+          serial_bytes = Base64.strict_decode64(args[:serial_number].to_s)
+          w.write_bytes(serial_bytes.ljust(SERIAL_SIZE, "\x00").byteslice(0, SERIAL_SIZE))
+          w.write_bytes([args[:certifier].to_s].pack('H*'))
+          w.buf
+        end
+
+        def deserialize_args(bytes)
+          r = Wire::Reader.new(bytes)
+          type_raw   = r.read_bytes(CERT_TYPE_SIZE)
+          serial_raw = r.read_bytes(SERIAL_SIZE)
+          certifier  = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+          {
+            type: Base64.strict_encode64(type_raw),
+            serial_number: Base64.strict_encode64(serial_raw),
+            certifier: certifier
+          }
+        end
+
+        def serialize_result(_result)
+          ''.b
+        end
+
+        def deserialize_result(_bytes)
+          { relinquished: true }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +relinquish_output+ call (call byte 7).
+      #
+      # Args wire layout:
+      #   [varint-str: basket]
+      #   [32-byte wire txid][varint vout]
+      #
+      # Result wire layout:
+      #   [empty — relinquished is implicit from the frame error byte]
+      module RelinquishOutput
+        module_function
+
+        def serialize_args(args)
+          Wire::Validation.outpoint_string!('output', args[:output].to_s)
+          txid_hex, vout = args[:output].to_s.split('.', 2)
+          w = Wire::Writer.new
+          w.write_str_with_varint_len(args.fetch(:basket, ''))
+          w.write_outpoint(txid_hex, vout.to_i)
+          w.buf
+        end
+
+        def deserialize_args(bytes)
+          r = Wire::Reader.new(bytes)
+          basket = r.read_str_with_varint_len
+          outpoint_data = r.read_outpoint
+          output = "#{outpoint_data[:txid_hex]}.#{outpoint_data[:vout]}"
+          { basket: basket, output: output }
+        end
+
+        def serialize_result(_result)
+          ''.b
+        end
+
+        def deserialize_result(_bytes)
+          { relinquished: true }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +reveal_counterparty_key_linkage+ call (call byte 9).
+      #
+      # Port of go-sdk/wallet/serializer/reveal_counterparty_key_linkage.go.
+      module RevealCounterpartyKeyLinkage
+        PUBKEY_SIZE = 33
+
+        # Args wire layout:
+        #   [privileged params]
+        #   [33 bytes: counterparty compressed pubkey]
+        #   [33 bytes: verifier compressed pubkey]
+        module Args
+          module_function
+
+          def serialize(args)
+            counterparty = args[:counterparty]
+            verifier     = args[:verifier]
+            raise BSV::Wallet::InvalidParameterError.new('counterparty', 'a 33-byte binary pubkey or 66-char hex') unless counterparty
+            raise BSV::Wallet::InvalidParameterError.new('verifier', 'a 33-byte binary pubkey or 66-char hex') unless verifier
+
+            w = BSV::Wallet::Wire::Writer.new
+            Common.write_privileged_params(w, args[:privileged], args[:privileged_reason])
+            w.write_bytes(pubkey_bytes(counterparty))
+            w.write_bytes(pubkey_bytes(verifier))
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            privileged, reason = Common.read_privileged_params(r)
+            counterparty = r.read_bytes(PUBKEY_SIZE)
+            verifier     = r.read_bytes(PUBKEY_SIZE)
+            {
+              privileged: privileged,
+              privileged_reason: reason,
+              counterparty: counterparty,
+              verifier: verifier
+            }
+          end
+
+          def pubkey_bytes(value)
+            return value.b if value.is_a?(String) && value.bytesize == PUBKEY_SIZE
+
+            [value.to_s].pack('H*')
+          end
+          private_class_method :pubkey_bytes
+        end
+
+        # Result wire layout:
+        #   [33 bytes: prover pubkey]
+        #   [33 bytes: verifier pubkey]
+        #   [33 bytes: counterparty pubkey]
+        #   [VarInt revelation_time_len][revelation_time bytes]
+        #   [VarInt encrypted_linkage_len][encrypted_linkage bytes]
+        #   [VarInt encrypted_linkage_proof_len][encrypted_linkage_proof bytes]
+        module Result
+          module_function
+
+          def serialize(result)
+            w = BSV::Wallet::Wire::Writer.new
+            w.write_bytes(pubkey_bytes(result[:prover]))
+            w.write_bytes(pubkey_bytes(result[:verifier]))
+            w.write_bytes(pubkey_bytes(result[:counterparty]))
+            w.write_str_with_varint_len(result[:revelation_time].to_s)
+            encrypted_linkage = Common.to_binary(result[:encrypted_linkage])
+            w.write_varint(encrypted_linkage.bytesize)
+            w.write_bytes(encrypted_linkage)
+            encrypted_linkage_proof = Common.to_binary(result[:encrypted_linkage_proof])
+            w.write_varint(encrypted_linkage_proof.bytesize)
+            w.write_bytes(encrypted_linkage_proof)
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            prover       = r.read_bytes(PUBKEY_SIZE)
+            verifier     = r.read_bytes(PUBKEY_SIZE)
+            counterparty = r.read_bytes(PUBKEY_SIZE)
+            revelation_time = r.read_str_with_varint_len
+            el_len = r.read_varint
+            encrypted_linkage = r.read_bytes(el_len)
+            elp_len = r.read_varint
+            encrypted_linkage_proof = r.read_bytes(elp_len)
+            {
+              prover: prover,
+              verifier: verifier,
+              counterparty: counterparty,
+              revelation_time: revelation_time,
+              encrypted_linkage: encrypted_linkage,
+              encrypted_linkage_proof: encrypted_linkage_proof
+            }
+          end
+
+          def pubkey_bytes(value)
+            return value.b if value.is_a?(String) && value.bytesize == PUBKEY_SIZE
+
+            [value.to_s].pack('H*')
+          end
+          private_class_method :pubkey_bytes
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +reveal_specific_key_linkage+ call (call byte 10).
+      #
+      # Port of go-sdk/wallet/serializer/reveal_specific_key_linkage.go.
+      module RevealSpecificKeyLinkage
+        PUBKEY_SIZE = 33
+
+        # Args wire layout:
+        #   [key-related params: protocol + key_id + counterparty + privileged]
+        #   [33 bytes: verifier compressed pubkey]
+        module Args
+          module_function
+
+          def serialize(args)
+            verifier = args[:verifier]
+            raise BSV::Wallet::InvalidParameterError.new('verifier', 'a 33-byte binary pubkey or 66-char hex') unless verifier
+
+            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]
+            )
+            w.write_bytes(pubkey_bytes(verifier))
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            params   = Common.read_key_related_params(r)
+            verifier = r.read_bytes(PUBKEY_SIZE)
+            params.merge(verifier: verifier)
+          end
+
+          def pubkey_bytes(value)
+            return value.b if value.is_a?(String) && value.bytesize == PUBKEY_SIZE
+
+            [value.to_s].pack('H*')
+          end
+          private_class_method :pubkey_bytes
+        end
+
+        # Result wire layout:
+        #   [33 bytes: prover pubkey]
+        #   [33 bytes: verifier pubkey]
+        #   [33 bytes: counterparty pubkey]
+        #   [1 byte: security_level][VarInt protocol_name_len][protocol_name bytes]
+        #   [VarInt key_id_len][key_id bytes]
+        #   [VarInt encrypted_linkage_len][encrypted_linkage bytes]
+        #   [VarInt encrypted_linkage_proof_len][encrypted_linkage_proof bytes]
+        #   [1 byte: proof_type]
+        module Result
+          module_function
+
+          def serialize(result)
+            w = BSV::Wallet::Wire::Writer.new
+            w.write_bytes(pubkey_bytes(result[:prover]))
+            w.write_bytes(pubkey_bytes(result[:verifier]))
+            w.write_bytes(pubkey_bytes(result[:counterparty]))
+            Common.write_protocol(w, result[:protocol_id])
+            key_id_bytes = result[:key_id].to_s.b
+            w.write_varint(key_id_bytes.bytesize)
+            w.write_bytes(key_id_bytes)
+            encrypted_linkage = Common.to_binary(result[:encrypted_linkage])
+            w.write_varint(encrypted_linkage.bytesize)
+            w.write_bytes(encrypted_linkage)
+            encrypted_linkage_proof = Common.to_binary(result[:encrypted_linkage_proof])
+            w.write_varint(encrypted_linkage_proof.bytesize)
+            w.write_bytes(encrypted_linkage_proof)
+            w.write_byte(result[:proof_type].to_i)
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            prover       = r.read_bytes(PUBKEY_SIZE)
+            verifier     = r.read_bytes(PUBKEY_SIZE)
+            counterparty = r.read_bytes(PUBKEY_SIZE)
+            protocol_id  = Common.read_protocol(r)
+            key_id_len   = r.read_varint
+            key_id       = r.read_bytes(key_id_len).force_encoding('UTF-8')
+            el_len = r.read_varint
+            encrypted_linkage = r.read_bytes(el_len)
+            elp_len = r.read_varint
+            encrypted_linkage_proof = r.read_bytes(elp_len)
+            proof_type = r.read_byte
+            {
+              prover: prover,
+              verifier: verifier,
+              counterparty: counterparty,
+              protocol_id: protocol_id,
+              key_id: key_id,
+              encrypted_linkage: encrypted_linkage,
+              encrypted_linkage_proof: encrypted_linkage_proof,
+              proof_type: proof_type
+            }
+          end
+
+          def pubkey_bytes(value)
+            return value.b if value.is_a?(String) && value.bytesize == PUBKEY_SIZE
+
+            [value.to_s].pack('H*')
+          end
+          private_class_method :pubkey_bytes
+        end
+      end
+    end
+  end
+end