solace 0.0.2

data/lib/solace/public_key.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# =============================
+# PublicKey
+# =============================
+#
+# Represents a Solana Ed25519 Public Key
+# Provides utility methods for encoding, decoding, and validation
+module Solace
+  class PublicKey
+    include Solace::Utils::PDA
+
+    # !@const LENGTH
+    #   The length of a Solana public key in bytes
+    #
+    # @return [Integer] The length of a public key
+    LENGTH = 32
+
+    # !@const MAX_BUMP_SEED
+    #   The maximum seed value for a Program Derived Address
+    #
+    # @return [Integer] The maximum seed value
+    MAX_BUMP_SEED = 255
+
+    # !@const PDA_MARKER
+    #   The marker for a Program Derived Address
+    #
+    # @return [String] The marker for a PDA
+    PDA_MARKER = 'ProgramDerivedAddress'
+
+    # !@attribute bytes
+    #   @return [Array<Integer>] The bytes of the public key
+    attr_reader :bytes
+
+    # Initialize with a 32-byte array or string
+    #
+    # @param bytes [String, Array<Integer>] 32-byte array or string
+    # @return [PublicKey]
+    def initialize(bytes)
+      raise ArgumentError, "Public key must be #{LENGTH} bytes" unless bytes.length == LENGTH
+
+      @bytes = bytes.freeze
+    end
+
+    # Return the base58 representation of the public key
+    #
+    # @return [String]
+    def to_base58
+      Solace::Utils::Codecs.bytes_to_base58(@bytes)
+    end
+
+    # String representation (base58)
+    #
+    # @return [String]
+    def to_s
+      to_base58
+    end
+
+    # Compare two public keys for equality
+    #
+    # @param other [PublicKey]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Solace::PublicKey) && other.bytes == bytes
+    end
+
+    # Return the public key as a byte array
+    #
+    # @return [Array<Integer>]
+    def to_bytes
+      @bytes.dup
+    end
+  end
+end

data/lib/solace/serializable_record.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Solace
+  class SerializableRecord
+    include Solace::Concerns::BinarySerializable
+
+    # Parse instruction from io stream
+    #
+    # @param io [IO or StringIO] The input to read bytes from.
+    # @return [Solace::Instruction] Parsed instruction object
+    def self.deserialize(io)
+      self::DESERIALIZER.call(io)
+    rescue NameError => e
+      raise "DESERIALIZER must be defined: #{e.message}"
+    end
+
+    # Serializes the transaction to a binary format
+    #
+    # @return [String] The serialized transaction (binary)
+    def serialize
+      self.class::SERIALIZER.call(self)
+    rescue NameError => e
+      raise "SERIALIZER must be defined: #{e.message}"
+    end
+  end
+end

data/lib/solace/serializers/address_lookup_table_deserializer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# =============================
+# Address Lookup Table Deserializer
+# =============================
+#
+# Deserializes a Solana address lookup table from a binary format.
+module Solace
+  module Serializers
+    class AddressLookupTableDeserializer < Solace::Serializers::BaseDeserializer
+      # @!attribute record_class
+      #   The class of the record being deserialized
+      #
+      # @return [Class] The class of the record
+      self.record_class = Solace::AddressLookupTable
+
+      # @!attribute steps
+      #   An ordered list of methods to deserialize the address lookup table
+      #
+      # @return [Array] The steps to deserialize the address lookup table
+      self.steps = %i[
+        next_extract_account
+        next_extract_writable_indexes
+        next_extract_readonly_indexes
+      ]
+
+      # Extract the account key from the transaction
+      #
+      # The BufferLayout is:
+      #   - [Account key (32 bytes)]
+      #
+      # @return [String] The account key
+      def next_extract_account
+        record.account = Codecs.bytes_to_base58 io.read(32).bytes
+      end
+
+      # Extract the writable indexes from the transaction
+      #
+      # The BufferLayout is:
+      #   - [Number of writable indexes (compact u16)]
+      #   - [Writable indexes (variable length u8)]
+      #
+      # @return [Array<Integer>] The writable indexes
+      def next_extract_writable_indexes
+        length, = Codecs.decode_compact_u16(io)
+        record.writable_indexes = io.read(length).unpack('C*')
+      end
+
+      # Extract the readonly indexes from the transaction
+      #
+      # The BufferLayout is:
+      #   - [Number of readonly indexes (compact u16)]
+      #   - [Readonly indexes (variable length u8)]
+      #
+      # @return [Array<Integer>] The readonly indexes
+      def next_extract_readonly_indexes
+        length, = Codecs.decode_compact_u16(io)
+        record.readonly_indexes = io.read(length).unpack('C*')
+      end
+    end
+  end
+end

data/lib/solace/serializers/address_lookup_table_serializer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# =============================
+# Address Lookup Table Serializer
+# =============================
+#
+# Serializes a Solana address lookup table to a binary format.
+module Solace
+  module Serializers
+    class AddressLookupTableSerializer < Solace::Serializers::BaseSerializer
+      # @!attribute steps
+      #   An ordered list of methods to serialize the address lookup table
+      #
+      # @return [Array] The steps to serialize the address lookup table
+      self.steps = %i[
+        encode_account
+        encode_writable_indexes
+        encode_readonly_indexes
+      ]
+
+      # Encodes the account of the address lookup table
+      #
+      # The BufferLayout is:
+      #   - [Account key (32 bytes)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded account
+      def encode_account
+        Codecs.base58_to_bytes(record.account)
+      end
+
+      # Encodes the writable indexes of the address lookup table
+      #
+      # The BufferLayout is:
+      #   - [Number of writable indexes (compact u16)]
+      #   - [Writable indexes (variable length u8)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded writable indexes
+      def encode_writable_indexes
+        Codecs.encode_compact_u16(record.writable_indexes.size).bytes + record.writable_indexes
+      end
+
+      # Encodes the readonly indexes of the address lookup table
+      #
+      # The BufferLayout is:
+      #   - [Number of readonly indexes (compact u16)]
+      #   - [Readonly indexes (variable length u8)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded readonly indexes
+      def encode_readonly_indexes
+        Codecs.encode_compact_u16(record.readonly_indexes.size).bytes + record.readonly_indexes
+      end
+    end
+  end
+end

data/lib/solace/serializers/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Solace
+  module Serializers
+    class Base
+      include Solace::Utils
+
+      # Proxy method to call the serializer and create a new instance
+      #
+      # @return [String] The serialized record (base64)
+      def self.call(*args, **kwargs)
+        new(*args, **kwargs).call
+      end
+
+      # Serializes the record
+      #
+      # @return [String] The serialized record (base64)
+      def call
+        bin = self.class::STEPS
+              .map { |m| send(m) }
+              .flatten
+              .compact
+              .pack('C*')
+
+        Base64.strict_encode64(bin)
+      rescue NameError => e
+        raise "STEPS must be defined: #{e.message}"
+      end
+    end
+  end
+end

data/lib/solace/serializers/base_deserializer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Solace
+  module Serializers
+    # Autoload deserializers
+    autoload :TransactionDeserializer, 'solace/serializers/transaction_deserializer'
+    autoload :MessageDeserializer, 'solace/serializers/message_deserializer'
+    autoload :InstructionDeserializer, 'solace/serializers/instruction_deserializer'
+    autoload :AddressLookupTableDeserializer, 'solace/serializers/address_lookup_table_deserializer'
+
+    # Base deserializer class
+    class BaseDeserializer < Serializers::Base
+      class << self
+        # @!attribute STEPS
+        #   An ordered list of methods to deserialize the record
+        #
+        # @return [Array] The steps to deserialize the record
+        attr_accessor :steps
+
+        # @!attribute RECORD_CLASS
+        #   The class of the record being deserialized
+        #
+        # @return [Class] The class of the record
+        attr_accessor :record_class
+      end
+
+      # @!attribute io
+      #   The input to read bytes from.
+      #
+      # @return [IO or StringIO] The input to read bytes from.
+      #
+      # @!attribute record
+      #   The record instance being deserialized.
+      #
+      # @return [Record] The deserialized record.
+      attr_reader :io, :record
+
+      # Initialize a new deserializer
+      #
+      # @param io [IO or StringIO] The input to read bytes from.
+      # @return [BaseDeserializer] The new deserializer object
+      def initialize(io)
+        @io = io
+        @record = self.class.record_class.new
+      end
+
+      # Deserializes the record
+      #
+      # @return [Record] The deserialized record
+      def call
+        self.class.steps.each { send(_1) }
+        record
+      end
+    end
+  end
+end

data/lib/solace/serializers/base_serializer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Solace
+  module Serializers
+    # Autoload serializers
+    autoload :TransactionSerializer, 'solace/serializers/transaction_serializer'
+    autoload :MessageSerializer, 'solace/serializers/message_serializer'
+    autoload :InstructionSerializer, 'solace/serializers/instruction_serializer'
+    autoload :AddressLookupTableSerializer, 'solace/serializers/address_lookup_table_serializer'
+
+    # Base serializer class
+    class BaseSerializer < Serializers::Base
+      class << self
+        # @!attribute STEPS
+        #   An ordered list of methods to deserialize the record
+        #
+        # @return [Array] The steps to deserialize the record
+        attr_accessor :steps
+      end
+
+      # @!attribute record
+      #   The record instance being serialized.
+      #
+      # @return [Record] The serialized record.
+      attr_reader :record
+
+      # Initialize a new serializer
+      #
+      # @param record [Record] The record to serialize
+      # @return [BaseSerializer] The new serializer object
+      def initialize(record)
+        @record = record
+      end
+
+      # Serializes the record
+      #
+      # @return [String] The serialized record (base64)
+      def call
+        bin = self.class
+                  .steps
+                  .map { |m| send(m) }
+                  .flatten
+                  .compact
+                  .pack('C*')
+
+        Base64.strict_encode64(bin)
+      rescue NameError => e
+        raise "STEPS must be defined: #{e.message}"
+      end
+    end
+  end
+end

data/lib/solace/serializers/instruction_deserializer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# =============================
+# Instruction Deserializer
+# =============================
+#
+# Deserializes a binary instruction into a Solace::Instruction object.
+module Solace
+  module Serializers
+    class InstructionDeserializer < Solace::Serializers::BaseDeserializer
+      # @!attribute record_class
+      #   The class of the record being deserialized
+      #
+      # @return [Class] The class of the record
+      self.record_class = Solace::Instruction
+
+      # @!attribute steps
+      #   An ordered list of methods to deserialize the instruction
+      #
+      # @return [Array] The steps to deserialize the instruction
+      self.steps = %i[
+        next_extract_program_index
+        next_extract_accounts
+        next_extract_data
+      ]
+
+      # Extracts the program index from the instruction
+      #
+      # The BufferLayout is:
+      #   - [Program index (1 byte)]
+      #
+      # @return [Integer] The program index
+      def next_extract_program_index
+        record.program_index = io.read(1).ord
+      end
+
+      # Extracts the accounts from the instruction
+      #
+      # The BufferLayout is:
+      #   - [Number of accounts (compact u16)]
+      #   - [Accounts (variable length u8)]
+      #
+      # @return [Array] The accounts
+      def next_extract_accounts
+        length, = Codecs.decode_compact_u16(io)
+        record.accounts = io.read(length).unpack('C*')
+      end
+
+      # Extracts the instruction data from the instruction
+      #
+      # The BufferLayout is:
+      #   - [Number of data bytes (compact u16)]
+      #   - [Data bytes (variable length u8)]
+      #
+      # @return [Array] The instruction data
+      def next_extract_data
+        length, = Codecs.decode_compact_u16(io)
+        record.data = io.read(length).unpack('C*')
+      end
+    end
+  end
+end

data/lib/solace/serializers/instruction_serializer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# =============================
+# Instruction Serializer
+# =============================
+#
+# Serializes a Solana instruction to a binary format.
+module Solace
+  module Serializers
+    class InstructionSerializer < Solace::Serializers::BaseSerializer
+      # @!attribute steps
+      #   An ordered list of methods to serialize the instruction
+      #
+      # @return [Array] The steps to serialize the instruction
+      self.steps = %i[
+        encode_program_index
+        encode_accounts
+        encode_data
+      ]
+
+      # Encodes the program index of the instruction
+      #
+      # The BufferLayout is:
+      #   - [Program index (u8)]
+      #
+      # @return [Integer] The bytes of the encoded program index
+      def encode_program_index
+        record.program_index
+      end
+
+      # Encodes the accounts of the instruction
+      #
+      # The BufferLayout is:
+      #   - [Number of accounts (compact u16)]
+      #   - [Accounts (variable length u8)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded accounts
+      def encode_accounts
+        Codecs.encode_compact_u16(record.accounts.size).bytes + record.accounts
+      end
+
+      # Encodes the data of the instruction
+      #
+      # The BufferLayout is:
+      #   - [Number of data bytes (compact u16)]
+      #   - [Data bytes (variable length u8)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded data
+      def encode_data
+        Codecs.encode_compact_u16(record.data.size).bytes + record.data
+      end
+    end
+  end
+end

data/lib/solace/serializers/message_deserializer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# =============================
+# Message Deserializer
+# =============================
+#
+# Deserializes a binary message into a Solace::Message object.
+module Solace
+  module Serializers
+    class MessageDeserializer < Solace::Serializers::BaseDeserializer
+      # @!attribute record_class
+      #   The class of the record being deserialized
+      #
+      # @return [Class] The class of the record
+      self.record_class = Solace::Message
+
+      # @!attribute steps
+      #   An ordered list of methods to deserialize the message
+      #
+      # @return [Array] The steps to deserialize the message
+      self.steps = %i[
+        next_extract_version
+        next_extract_message_header
+        next_extract_accounts
+        next_extract_recent_blockhash
+        next_extract_instructions
+        next_extract_address_lookup_table
+      ]
+
+      # Extract version from the message
+      #
+      # Checks for version prefix and extracts version. If the prefix is not found, it
+      # assumes a legacy message and sets no version.
+      #
+      # The BufferLayout is:
+      #   - [Version prefix (1 byte)]
+      #   - [Version (variable length)]
+      #
+      # @return [Integer] The version of the message
+      def next_extract_version
+        next_byte = io.read(1).unpack1('C')
+
+        if next_byte & 0x80 == 0x80
+          record.version = next_byte & 0x7F
+        else
+          io.seek(-1, IO::SEEK_CUR)
+          record.version = nil
+        end
+      end
+
+      # Extract message header from the message
+      #
+      # The BufferLayout is:
+      #   - [Message header (3 bytes)]
+      #
+      # @return [Array<Integer>] The message header of the message
+      def next_extract_message_header
+        record.header = io.read(3).bytes
+      end
+
+      # Extract account keys from the message
+      #
+      # The BufferLayout is:
+      #   - [Number of accounts (compact u16)]
+      #   - [Accounts (variable length u8)]
+      #
+      # @return [Array<String>] The account keys of the message
+      def next_extract_accounts
+        count, = Codecs.decode_compact_u16(io)
+        record.accounts = count.times.map do
+          Codecs.bytes_to_base58 io.read(32).bytes
+        end
+      end
+
+      # Extract recent blockhash from the message
+      #
+      # The BufferLayout is:
+      #   - [Recent blockhash (32 bytes)]
+      #
+      # @return [String] The recent blockhash of the message
+      def next_extract_recent_blockhash
+        record.recent_blockhash = Codecs.bytes_to_base58 io.read(32).bytes
+      end
+
+      # Extract instructions from the message
+      #
+      # The BufferLayout is:
+      #   - [Number of instructions (compact u16)]
+      #   - [Instructions (variable length)]
+      #
+      # @return [Array<Solace::Instruction>] The instructions of the message
+      def next_extract_instructions
+        count, = Codecs.decode_compact_u16(io)
+        record.instructions = count.times.map do
+          Solace::Instruction.deserialize(io)
+        end
+      end
+
+      # Extract address lookup table from the message
+      #
+      # The BufferLayout is:
+      #   - [Number of address lookup tables (compact u16)]
+      #   - [Address lookup tables (variable length)]
+      #
+      # @return [Array<Solace::AddressLookupTable>] The address lookup table of the message
+      def next_extract_address_lookup_table
+        return unless record.versioned?
+
+        count, = Codecs.decode_compact_u16(io)
+        record.address_lookup_tables = count.times.map do
+          Solace::AddressLookupTable.deserialize(io)
+        end
+      end
+    end
+  end
+end

data/lib/solace/serializers/message_serializer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# =============================
+# Message Serializer
+# =============================
+#
+# Serializes a Solana message to a binary format.
+module Solace
+  module Serializers
+    class MessageSerializer < Solace::Serializers::BaseSerializer
+      # @!attribute steps
+      #   An ordered list of methods to serialize the message
+      #
+      # @return [Array] The steps to serialize the message
+      self.steps = %i[
+        encode_version
+        encode_message_header
+        encode_accounts
+        encode_recent_blockhash
+        encode_instructions
+        encode_address_lookup_table
+      ]
+
+      # Encodes the version of the message
+      #
+      # The BufferLayout is:
+      #   - [Version (1 byte)]
+      #
+      # @return [Array<Integer>] | nil The bytes of the encoded version
+      def encode_version
+        [0x80 | record.version] if record.versioned?
+      end
+
+      # Encodes the message header of the transaction
+      #
+      # The BufferLayout is:
+      #   - [Message header (3 bytes)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded message header
+      def encode_message_header
+        record.header
+      end
+
+      # Encodes the accounts of the transaction
+      #
+      # The BufferLayout is:
+      #   - [Number of accounts (compact u16)]
+      #   - [Accounts (variable length)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded accounts
+      def encode_accounts
+        Codecs.encode_compact_u16(record.accounts.size).bytes +
+          record.accounts.map { Codecs.base58_to_bytes(_1) }
+      end
+
+      # Encodes the recent blockhash of the transaction
+      #
+      # The BufferLayout is:
+      #   - [Recent blockhash (32 bytes)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded recent blockhash
+      def encode_recent_blockhash
+        raise 'Failed to serialize message: recent blockhash is nil' if record.recent_blockhash.nil?
+
+        Codecs.base58_to_bytes(record.recent_blockhash)
+      end
+
+      # Encodes the instructions of the transaction
+      #
+      # The BufferLayout is:
+      #   - [Number of instructions (compact u16)]
+      #   - [Instructions (variable length)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded instructions
+      def encode_instructions
+        Codecs.encode_compact_u16(record.instructions.size).bytes +
+          record.instructions.map(&:to_bytes)
+      end
+
+      # Encodes the address lookup table of the transaction
+      #
+      # The BufferLayout is:
+      #   - [Number of address lookup tables (compact u16)]
+      #   - [Address lookup tables (variable length)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded address lookup table
+      def encode_address_lookup_table
+        return unless record.versioned?
+
+        Codecs.encode_compact_u16(record.address_lookup_tables.size).bytes +
+          record.address_lookup_tables.map(&:to_bytes)
+      end
+    end
+  end
+end