bsv-sdk 0.20.0 → 0.23.0

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

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +create_signature+ call (call byte 15).
+      #
+      # Port of go-sdk/wallet/serializer/create_signature.go.
+      module CreateSignature
+        HASH_SIZE = 32
+
+        # Args wire layout:
+        #   [key-related params]
+        #   [1 byte: data-type flag — 1=data, 2=hash_to_directly_sign]
+        #   If flag=1: [VarInt data_len][data bytes]
+        #   If flag=2: [32 bytes: hash]
+        #   [optional_bool seek_permission]
+        module Args
+          module_function
+
+          def serialize(args)
+            data = args[:data] && Common.to_binary(args[:data])
+            hash = args[:hash_to_directly_sign] && Common.to_binary(args[:hash_to_directly_sign])
+
+            if data && hash
+              raise BSV::Wallet::InvalidParameterError.new(
+                'data and hash_to_directly_sign',
+                'not both provided — supply one or the other'
+              )
+            end
+            raise BSV::Wallet::InvalidParameterError.new('data or hash_to_directly_sign', 'present') unless data || hash
+
+            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]
+            )
+
+            if data
+              w.write_byte(1)
+              w.write_varint(data.bytesize)
+              w.write_bytes(data)
+            else
+              w.write_byte(2)
+              w.write_bytes(hash)
+            end
+
+            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)
+            flag = r.read_byte
+            payload = case flag
+                      when 1
+                        len = r.read_varint
+                        { data: r.read_bytes(len) }
+                      when 2
+                        { hash_to_directly_sign: r.read_bytes(HASH_SIZE) }
+                      else
+                        raise ArgumentError, "invalid data-type flag: #{flag}"
+                      end
+            seek_permission = r.read_optional_bool
+            params.merge(payload).merge(seek_permission: seek_permission)
+          end
+        end
+
+        # Result wire layout:
+        #   [DER signature bytes — remaining payload]
+        module Result
+          module_function
+
+          def serialize(result)
+            Common.to_binary(result[:signature])
+          end
+
+          def deserialize(bytes)
+            { signature: bytes.b }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +decrypt+ call (call byte 12).
+      #
+      # Port of go-sdk/wallet/serializer/decrypt.go.
+      module Decrypt
+        # Args wire layout:
+        #   [key-related params]
+        #   [VarInt ciphertext_len][ciphertext 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]
+            )
+            ciphertext = Common.to_binary(args[:ciphertext])
+            w.write_varint(ciphertext.bytesize)
+            w.write_bytes(ciphertext)
+            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
+            ciphertext = r.read_bytes(len)
+            seek_permission = r.read_optional_bool
+            params.merge(ciphertext: ciphertext, seek_permission: seek_permission)
+          end
+        end
+
+        # Result wire layout:
+        #   [plaintext bytes — remaining payload]
+        module Result
+          module_function
+
+          def serialize(result)
+            Common.to_binary(result[:plaintext])
+          end
+
+          def deserialize(bytes)
+            { plaintext: bytes.b }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +discover_by_attributes+ call (call byte 22).
+      #
+      # Args wire layout:
+      #   [varint: attribute_count] per entry: [varint-int key_bytes][varint-int value_bytes]
+      #   [optional_uint32: limit]
+      #   [optional_uint32: offset]
+      #   [optional_bool: seek_permission]
+      #
+      # Result wire layout: see DiscoverCertificatesResult.
+      #
+      # Keys are written in sorted order (matching Go sort.Strings) to ensure
+      # deterministic encoding across SDK implementations.
+      module DiscoverByAttributes
+        module_function
+
+        def serialize_args(args)
+          w = Wire::Writer.new
+          attributes = args[:attributes] || {}
+          w.write_varint(attributes.length)
+          attributes.keys.sort.each do |k|
+            w.write_int_bytes(k.to_s.b)
+            w.write_int_bytes(attributes[k].to_s.b)
+          end
+          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)
+          count = r.read_varint
+          attributes = {}
+          count.times do
+            k = r.read_int_bytes.force_encoding('UTF-8')
+            v = r.read_int_bytes.force_encoding('UTF-8')
+            attributes[k] = v
+          end
+          limit           = r.read_optional_uint32
+          offset          = r.read_optional_uint32
+          seek_permission = r.read_optional_bool
+          { attributes: attributes, limit: limit, offset: offset,
+            seek_permission: seek_permission }
+        end
+
+        def serialize_result(result)
+          DiscoverCertificatesResult.serialize(result)
+        end
+
+        def deserialize_result(bytes)
+          DiscoverCertificatesResult.deserialize(bytes)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +discover_by_identity_key+ call (call byte 21).
+      #
+      # Args wire layout:
+      #   [33 bytes: identity_key compressed pubkey]
+      #   [optional_uint32: limit]
+      #   [optional_uint32: offset]
+      #   [optional_bool: seek_permission]
+      #
+      # Result wire layout: see DiscoverCertificatesResult.
+      module DiscoverByIdentityKey
+        PUBKEY_SIZE = 33
+
+        module_function
+
+        def serialize_args(args)
+          w = Wire::Writer.new
+          w.write_bytes([args[:identity_key].to_s].pack('H*'))
+          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)
+          identity_key = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+          limit           = r.read_optional_uint32
+          offset          = r.read_optional_uint32
+          seek_permission = r.read_optional_bool
+          { identity_key: identity_key, limit: limit, offset: offset,
+            seek_permission: seek_permission }
+        end
+
+        def serialize_result(result)
+          DiscoverCertificatesResult.serialize(result)
+        end
+
+        def deserialize_result(bytes)
+          DiscoverCertificatesResult.deserialize(bytes)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # Shared BRC-103 result codec for discover_by_identity_key and
+      # discover_by_attributes (both return the same shape).
+      #
+      # Result wire layout:
+      #   [varint: total_certificates]
+      #   per certificate: [IdentityCertificate inline bytes (int-prefixed base cert + meta)]
+      module DiscoverCertificatesResult
+        module_function
+
+        # @param result [Hash] { total_certificates:, certificates: [IdentityCert Hash, ...] }
+        # @return [String] binary
+        def serialize(result)
+          certs = result[:certificates] || []
+          w = Wire::Writer.new
+          w.write_varint(certs.length)
+          certs.each do |cert|
+            cert_bytes = Certificate.serialize_identity_certificate(cert)
+            w.write_bytes(cert_bytes)
+          end
+          w.buf
+        end
+
+        # @param bytes [String] binary
+        # @return [Hash] { total_certificates:, certificates: [...] }
+        def deserialize(bytes)
+          r = Wire::Reader.new(bytes)
+          total = r.read_varint
+          certs = total.times.map { Certificate.deserialize_identity_certificate(r) }
+          { total_certificates: total, certificates: certs }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +encrypt+ call (call byte 11).
+      #
+      # Port of go-sdk/wallet/serializer/encrypt.go.
+      module Encrypt
+        # Args wire layout:
+        #   [key-related params: protocol + key_id + counterparty + privileged]
+        #   [VarInt plaintext_len][plaintext 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]
+            )
+            plaintext = Common.to_binary(args[:plaintext])
+            w.write_varint(plaintext.bytesize)
+            w.write_bytes(plaintext)
+            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
+            plaintext = r.read_bytes(len)
+            seek_permission = r.read_optional_bool
+            params.merge(plaintext: plaintext, seek_permission: seek_permission)
+          end
+        end
+
+        # Result wire layout:
+        #   [ciphertext bytes — remaining payload]
+        module Result
+          module_function
+
+          def serialize(result)
+            Common.to_binary(result[:ciphertext])
+          end
+
+          def deserialize(bytes)
+            { ciphertext: bytes.b }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for the get_header_for_height call (call byte 26).
+      #
+      # Wire format:
+      #   Args:   [VarInt] height
+      #   Result: [80 bytes] raw block header
+      #
+      # Port of go-sdk/wallet/serializer/get_header.go.
+      module GetHeaderForHeight
+        HEADER_BYTES = 80
+
+        module Args
+          module_function
+
+          # @param args [Hash] { height: Integer }
+          # @return [String] binary (varint-encoded height)
+          def serialize(args)
+            BSV::Transaction::VarInt.encode(args[:height].to_i)
+          end
+
+          # @param bytes [String] binary
+          # @return [Hash] { height: Integer }
+          def deserialize(bytes)
+            raise BSV::Wallet::InvalidParameterError.new('get_header_for_height args', 'at least 1 byte') if bytes.b.empty?
+
+            height, = BSV::Transaction::VarInt.decode(bytes.b, 0)
+            { height: height }
+          end
+        end
+
+        module Result
+          module_function
+
+          # @param result [Hash] { header: String } — 80-byte binary block header
+          # @return [String] 80-byte binary
+          # @raise [InvalidParameterError] if header is not exactly 80 bytes
+          def serialize(result)
+            header = result[:header].to_s.b
+            unless header.bytesize == HEADER_BYTES
+              raise BSV::Wallet::InvalidParameterError.new(
+                'get_header_for_height result header',
+                "exactly #{HEADER_BYTES} bytes, got #{header.bytesize}"
+              )
+            end
+
+            header
+          end
+
+          # @param bytes [String] binary
+          # @return [Hash] { header: String }
+          # @raise [InvalidParameterError] if payload is not exactly 80 bytes
+          def deserialize(bytes)
+            data = bytes.b
+            unless data.bytesize == HEADER_BYTES
+              raise BSV::Wallet::InvalidParameterError.new(
+                'get_header_for_height result',
+                "exactly #{HEADER_BYTES} bytes, got #{data.bytesize}"
+              )
+            end
+
+            { header: data }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for the get_height call (call byte 25).
+      #
+      # Wire format — result only (no args payload):
+      #   [VarInt] block height (uint32 range)
+      #
+      # Port of go-sdk/wallet/serializer/get_height.go.
+      module GetHeight
+        module Args
+          module_function
+
+          def serialize(_args = {})
+            ''.b
+          end
+
+          def deserialize(_bytes)
+            {}
+          end
+        end
+
+        module Result
+          module_function
+
+          # @param result [Hash] { height: Integer }
+          # @return [String] binary (varint-encoded height)
+          def serialize(result)
+            BSV::Transaction::VarInt.encode(result[:height].to_i)
+          end
+
+          # @param bytes [String] binary
+          # @return [Hash] { height: Integer }
+          def deserialize(bytes)
+            raise BSV::Wallet::InvalidParameterError.new('get_height result', 'at least 1 byte') if bytes.b.empty?
+
+            height, = BSV::Transaction::VarInt.decode(bytes.b, 0)
+            { height: height }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for the get_network call (call byte 27).
+      #
+      # Wire format — result only (no args payload):
+      #   [1 byte] 0x00 = mainnet, 0x01 = testnet
+      module GetNetwork
+        # Args is always empty — get_network takes no parameters.
+        module Args
+          module_function
+
+          def serialize(_args = {})
+            ''.b
+          end
+
+          def deserialize(_bytes)
+            {}
+          end
+        end
+
+        module Result
+          MAINNET_CODE = 0
+          TESTNET_CODE = 1
+
+          module_function
+
+          # @param result [Hash] { network: :mainnet | :testnet }
+          # @return [String] 1-byte binary
+          # @raise [InvalidParameterError] if +:network+ is not :mainnet or :testnet
+          def serialize(result)
+            code = case result[:network]
+                   when :mainnet then MAINNET_CODE
+                   when :testnet then TESTNET_CODE
+                   else
+                     raise BSV::Wallet::InvalidParameterError.new(
+                       'network', ":mainnet or :testnet, got #{result[:network].inspect}"
+                     )
+                   end
+            [code].pack('C')
+          end
+
+          # @param bytes [String] 1-byte binary
+          # @return [Hash] { network: :mainnet | :testnet }
+          # @raise [InvalidParameterError] if the byte is not 0x00 or 0x01
+          def deserialize(bytes)
+            data = bytes.b
+            raise BSV::Wallet::InvalidParameterError.new('get_network result', 'exactly 1 byte') unless data.bytesize == 1
+
+            case data.getbyte(0)
+            when MAINNET_CODE then { network: :mainnet }
+            when TESTNET_CODE then { network: :testnet }
+            else
+              raise BSV::Wallet::InvalidParameterError.new(
+                'get_network result', "0x00 (mainnet) or 0x01 (testnet), got 0x#{data.unpack1('H*')}"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end