bsv-sdk 0.19.1 → 0.22.0

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

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 wire codec for the +get_public_key+ call (call byte 8).
+      #
+      # Port of go-sdk/wallet/serializer/get_public_key.go.
+      module GetPublicKey
+        IDENTITY_KEY_FLAG = 1
+        PUBKEY_SIZE       = 33
+
+        # Args wire layout:
+        #   [1 byte: identity_key flag — 0=no, 1=yes]
+        #   If 0: [key-related params][optional_bool for_self]
+        #   If 1: [privileged params only]
+        #   [optional_bool seek_permission]
+        module Args
+          module_function
+
+          def serialize(args)
+            identity_key = args[:identity_key]
+            w = BSV::Wallet::Wire::Writer.new
+
+            if identity_key
+              w.write_byte(IDENTITY_KEY_FLAG)
+              Common.write_privileged_params(w, args[:privileged], args[:privileged_reason])
+            else
+              w.write_byte(0)
+              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_optional_bool(args[:for_self])
+            end
+
+            w.write_optional_bool(args[:seek_permission])
+            w.buf
+          end
+
+          def deserialize(bytes)
+            r = BSV::Wallet::Wire::Reader.new(bytes)
+            flag = r.read_byte
+
+            if flag == IDENTITY_KEY_FLAG
+              privileged, reason = Common.read_privileged_params(r)
+              seek_permission = r.read_optional_bool
+              {
+                identity_key: true,
+                privileged: privileged,
+                privileged_reason: reason,
+                seek_permission: seek_permission
+              }
+            else
+              params = Common.read_key_related_params(r)
+              for_self = r.read_optional_bool
+              seek_permission = r.read_optional_bool
+              params.merge(identity_key: false, for_self: for_self, seek_permission: seek_permission)
+            end
+          end
+        end
+
+        # Result wire layout:
+        #   [33 bytes: compressed public key]
+        module Result
+          module_function
+
+          def serialize(result)
+            pubkey = result[:public_key] || ''.b
+            pubkey.bytesize == PUBKEY_SIZE ? pubkey.b : [pubkey.to_s].pack('H*')
+          end
+
+          def deserialize(bytes)
+            raise ArgumentError, "public key too short: #{bytes.bytesize}" if bytes.bytesize < PUBKEY_SIZE
+
+            { public_key: bytes.byteslice(0, PUBKEY_SIZE) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for the get_version call (call byte 28).
+      #
+      # Wire format — result only (no args payload):
+      #   [N bytes] raw UTF-8 version string (no length prefix)
+      #
+      # Port of go-sdk/wallet/serializer/get_version.go — the Go SDK emits
+      # the string bytes directly, with no varint length prefix.
+      module GetVersion
+        module Args
+          module_function
+
+          def serialize(_args = {})
+            ''.b
+          end
+
+          def deserialize(_bytes)
+            {}
+          end
+        end
+
+        module Result
+          module_function
+
+          # @param result [Hash] { version: String }
+          # @return [String] binary (raw UTF-8 bytes)
+          def serialize(result)
+            result[:version].to_s.b
+          end
+
+          # @param bytes [String] binary
+          # @return [Hash] { version: String }
+          def deserialize(bytes)
+            { version: bytes.b.force_encoding('UTF-8') }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Serializer
+      # BRC-103 serialiser for internalize_action (call byte 5).
+      #
+      # Wire layout (port of go-sdk/wallet/serializer/internalize_action.go):
+      #   [varint + bytes] tx (BEEF) — length-prefixed raw bytes
+      #   [varint]         outputs count
+      #   For each output:
+      #     [varint]       output_index
+      #     [1 byte]       protocol: 0x01=wallet_payment, 0x02=basket_insertion
+      #     If wallet_payment:
+      #       [33 bytes]   sender_identity_key (compressed pubkey)
+      #       [int_bytes]  derivation_prefix
+      #       [int_bytes]  derivation_suffix
+      #     If basket_insertion:
+      #       [string]     basket
+      #       [optional_string] custom_instructions
+      #       [string_slice] tags
+      #   [string_slice]   labels
+      #   [string]         description
+      #   [optional_bool] seek_permission
+      #
+      # Result wire layout: empty (success is implicit from the frame error byte).
+      module InternalizeActionArgs
+        PROTOCOL_WALLET_PAYMENT   = 1
+        PROTOCOL_BASKET_INSERTION = 2
+        PUBKEY_SIZE               = 33
+
+        module_function
+
+        # @param args [Hash]
+        # @return [String] binary
+        def serialize(args)
+          w = Wire::Writer.new
+
+          tx = (args[:tx] || ''.b).b
+          w.write_varint(tx.bytesize)
+          w.write_bytes(tx)
+
+          outputs = args[:outputs] || []
+          w.write_varint(outputs.length)
+          outputs.each { |out| serialize_output(w, out) }
+
+          w.write_string_slice(args[:labels])
+          w.write_string(args[:description].to_s)
+          w.write_optional_bool(args[:seek_permission])
+
+          w.buf
+        end
+
+        # @param bytes [String] binary
+        # @return [Hash]
+        def deserialize(bytes)
+          r = Wire::Reader.new(bytes)
+
+          tx_len = r.read_varint
+          tx     = r.read_bytes(tx_len)
+
+          output_count = r.read_varint
+          outputs = output_count.times.map { deserialize_output(r) }
+
+          labels         = r.read_string_slice
+          description    = r.read_string
+          seek_permission = r.read_optional_bool
+
+          result = { tx: tx, outputs: outputs, description: description }
+          result[:labels] = labels unless labels.nil?
+          result[:seek_permission] = seek_permission unless seek_permission.nil?
+          result
+        end
+
+        def serialize_output(writer, out)
+          writer.write_varint(out[:output_index].to_i)
+
+          case out[:protocol]
+          when :wallet_payment
+            writer.write_byte(PROTOCOL_WALLET_PAYMENT)
+            payment = out[:payment_remittance] || {}
+            writer.write_bytes([payment[:sender_identity_key]].pack('H*'))
+            writer.write_int_bytes(payment[:derivation_prefix])
+            writer.write_int_bytes(payment[:derivation_suffix])
+          when :basket_insertion
+            writer.write_byte(PROTOCOL_BASKET_INSERTION)
+            insertion = out[:insertion_remittance] || {}
+            writer.write_string(insertion[:basket].to_s)
+            writer.write_optional_string(insertion[:custom_instructions])
+            writer.write_string_slice(insertion[:tags])
+          else
+            raise ArgumentError, "unknown internalize protocol: #{out[:protocol]}"
+          end
+        end
+
+        def deserialize_output(reader)
+          output_index = reader.read_varint
+          protocol_byte = reader.read_byte
+
+          case protocol_byte
+          when PROTOCOL_WALLET_PAYMENT
+            key_bytes  = reader.read_bytes(PUBKEY_SIZE)
+            prefix     = reader.read_int_bytes
+            suffix     = reader.read_int_bytes
+            {
+              output_index: output_index,
+              protocol: :wallet_payment,
+              payment_remittance: {
+                sender_identity_key: key_bytes.unpack1('H*'),
+                derivation_prefix: prefix,
+                derivation_suffix: suffix
+              }
+            }
+          when PROTOCOL_BASKET_INSERTION
+            basket  = reader.read_string
+            custom  = reader.read_optional_string
+            tags    = reader.read_string_slice
+            result  = {
+              output_index: output_index,
+              protocol: :basket_insertion,
+              insertion_remittance: { basket: basket }
+            }
+            result[:insertion_remittance][:custom_instructions] = custom unless custom.nil?
+            result[:insertion_remittance][:tags] = tags unless tags.nil?
+            result
+          else
+            raise ArgumentError, "invalid internalize protocol byte: #{protocol_byte}"
+          end
+        end
+
+        private_class_method :serialize_output, :deserialize_output
+      end
+
+      module InternalizeActionResult
+        module_function
+
+        # @param _result [Hash] ignored
+        # @return [String] empty binary
+        def serialize(_result = {})
+          ''.b
+        end
+
+        # @param _bytes [String] ignored
+        # @return [Hash] { accepted: true }
+        def deserialize(_bytes = nil)
+          { accepted: true }
+        end
+      end
+    end
+  end
+end