solace 0.0.2

data/lib/solace/serializers/transaction_deserializer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# =============================
+# Transaction Deserializer
+# =============================
+#
+# Deserializes a binary transaction into a Solace::Transaction object.
+module Solace
+  module Serializers
+    class TransactionDeserializer < Solace::Serializers::BaseDeserializer
+      # @!attribute record_class
+      #   The class of the record being deserialized
+      #
+      # @return [Class] The class of the record
+      self.record_class = Solace::Transaction
+
+      # @!attribute steps
+      #   An ordered list of methods to deserialize the transaction
+      #
+      # @return [Array] The steps to deserialize the transaction
+      self.steps = %i[
+        next_extract_signatures
+        next_extract_message
+      ]
+
+      # Extract signatures from the transaction
+      #
+      # The BufferLayout is:
+      #   - [Number of signatures (compact u16)]
+      #   - [Signatures (variable length)]
+      #
+      # @return [Array] Array of base58 encoded signatures
+      def next_extract_signatures
+        count, = Codecs.decode_compact_u16(io)
+        record.signatures = count.times.map { io.read(64) }
+      end
+
+      # Extract the message from the transaction
+      #
+      # The BufferLayout is:
+      #   - [Message (variable length)]
+      #
+      # @return [Solace::Message] The deserialized message instance
+      def next_extract_message
+        record.message = Solace::Serializers::MessageDeserializer.call(io)
+      end
+    end
+  end
+end

data/lib/solace/serializers/transaction_serializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# =============================
+# Transaction Serializer
+# =============================
+#
+# Serializes a Solana transaction to a binary format.
+module Solace
+  module Serializers
+    class TransactionSerializer < Solace::Serializers::BaseSerializer
+      # @!const SIGNATURE_PLACEHOLDER
+      #   @return [String] Placeholder for a signature in the transaction
+      SIGNATURE_PLACEHOLDER = ([0] * 64).pack('C*')
+
+      # @!attribute steps
+      #   An ordered list of methods to serialize the transaction
+      #
+      # @return [Array] The steps to serialize the transaction
+      self.steps = %i[
+        encode_signatures
+        encode_message
+      ]
+
+      # Encodes the signatures of the transaction
+      #
+      # Iterates over the number sum number of signatures and either encodes or sets
+      # the placeholder for each expected index in the signatures array.
+      #
+      # The BufferLayout is:
+      #   - [Number of signatures (compact u16)]
+      #   - [Signatures (variable length)]
+      #
+      # @return [Array<Integer>] The bytes of the encoded signatures
+      def encode_signatures
+        Codecs.encode_compact_u16(record.signatures.size).bytes +
+          index_signatures(record.message.num_required_signatures)
+      end
+
+      # Encodes the message from the transaction
+      #
+      # @return [Array<Integer>] The bytes of the encoded message
+      def encode_message
+        record.message.to_bytes
+      end
+
+      private
+
+      # Index the signatures
+      #
+      # Positions the signatures by expected index and set placeholders for any missing signatures.
+      #
+      # @param num_required_signatures [Integer] The number of required signatures
+      #
+      # @return [Array<Integer>] The bytes of the encoded signatures
+      def index_signatures(num_required_signatures)
+        (0...num_required_signatures).map { (record.signatures[_1] || SIGNATURE_PLACEHOLDER).bytes }
+      end
+    end
+  end
+end

data/lib/solace/transaction.rb

@@ -0,0 +1,98 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+# =============================
+# Transaction
+# =============================
+#
+# Class representing a Solana transaction.
+#
+# The BufferLayout is:
+#   - [Signatures (variable length)]
+#   - [Version (1 byte)] (if versioned)
+#   - [Message header (3 bytes)]
+#   - [Account keys (variable length)]
+#   - [Recent blockhash (32 bytes)]
+#   - [Instructions (variable length)]
+#   - [Address lookup table (variable length)] (if versioned)
+#
+module Solace
+  class Transaction < Solace::SerializableRecord
+    # @!const SERIALIZER
+    #   @return [Solace::Serializers::TransactionSerializer] The serializer for the transaction
+    SERIALIZER = Solace::Serializers::TransactionSerializer
+
+    # @!const DESERIALIZER
+    #   @return [Solace::Serializers::TransactionDeserializer] The deserializer for the transaction
+    DESERIALIZER = Solace::Serializers::TransactionDeserializer
+
+    # @!const SIGNATURE_PLACEHOLDER
+    #   @return [String] Placeholder for a signature in the transaction
+    SIGNATURE_PLACEHOLDER = Solace::Utils::Codecs.base58_to_binary('1' * 64)
+
+    # @!attribute [rw] signatures
+    #   @return [Array<String>] Signatures of the transaction (binary)
+    attr_accessor :signatures
+
+    # @!attribute [rw] message
+    #   @return [Solace::Message] Message of the transaction
+    attr_accessor :message
+
+    class << self
+      # Deserialize a base64 encoded transaction into a Solace::Transaction object
+      #
+      # @param base64_tx [String] The base64 encoded transaction
+      # @return [Solace::Transaction] The deserialized transaction
+      def from(base64_tx)
+        DESERIALIZER.call Solace::Utils::Codecs.base64_to_bytestream(base64_tx)
+      end
+    end
+
+    # Initialize a new transaction
+    #
+    # @return [Solace::Transaction] The new transaction object
+    def initialize(
+      signatures: [],
+      message: Solace::Message.new
+    )
+      @signatures = signatures
+      @message = message
+    end
+
+    # Sign the transaction
+    #
+    # Calls sign_and_update_signatures for each keypair passed in.
+    #
+    # @param keypairs [<Solace::Keypair>] The keypairs to sign the transaction with
+    # @return [Array<String>] The signatures of the transaction
+    def sign(*keypairs)
+      keypairs.map { |keypair| sign_and_update_signatures(keypair) }
+    end
+
+    private
+
+    # Sign message and update signatures
+    #
+    # Signs the transaction's message and updates the signatures array with the
+    # signature.
+    #
+    # @return [Array<String>] The signatures of the transaction
+    def sign_and_update_signatures(keypair)
+      keypair.sign(message.to_binary).tap { |signature| set_signature(keypair.address, signature) }
+    end
+
+    # Update the transaction signatures
+    #
+    # Updates the signatures array according to the accounts of the message.
+    #
+    # @param public_key [String] The public key of the signer
+    # @param signature [String] The signature to insert
+    def set_signature(public_key, signature)
+      index = message.accounts.index(public_key)
+
+      raise ArgumentError, 'Public key not found in transaction' if index.nil?
+
+      signatures[index] = signature
+    end
+  end
+end

data/lib/solace/utils/codecs.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'rbnacl'
+require 'base58'
+require 'stringio'
+
+module Solace
+  module Utils
+    module Codecs
+      # =============================
+      # Helper: IO Stream
+      # =============================
+      #
+      # Creates a StringIO from a base64 string.
+      #
+      # Args:
+      #   base64 (String): The base64 string to decode
+      #
+      # Returns:
+      #   StringIO: A StringIO object containing the decoded bytes
+      #
+      def self.base64_to_bytestream(base64)
+        StringIO.new(Base64.decode64(base64))
+      end
+
+      # =============================
+      # Helper: Compact-u16 Encoding (ShortVec)
+      # =============================
+      #
+      # Encodes a u16 value in a compact form
+      #
+      # Args:
+      #   n (Integer): The u16 value to encode
+      #
+      # Returns:
+      #   String: The compactly encoded u16 value
+      #
+      def self.encode_compact_u16(n)
+        out = []
+        loop do
+          # In general, n >> 7 shifts the bits of n to the right by
+          # 7 positions, effectively dividing n by 128 and discarding
+          # the remainder (integer division). This is commonly used in
+          # encoding schemes to process one "byte" (7 bits) at a time.
+          if (n >> 7).zero?
+            out << n
+            break
+          else
+            # The expression out << ((n & 0x7F) | 0x80) is used in variable-length
+            # integer encoding, such as the compact-u16 encoding.
+            #
+            # n & 0x7F:
+            #   - 0x7F is 127 in decimal, or 0111 1111 in binary.
+            #   - n & 0x7F masks out all but the lowest 7 bits of n. This extracts the least significant 7 bits of n.
+            #
+            # (n & 0x7F) | 0x80:
+            #   - 0x80 is 128 in decimal, or 1000 0000 in binary.
+            #   - | (bitwise OR) sets the highest bit (the 8th bit) to 1.
+            #   - This is a signal that there are more bytes to come in the encoding (i.e., the value hasn't been fully encoded yet).
+            #
+            # out << ...:
+            #   - This appends the resulting byte to the out array.
+            out << ((n & 0x7F) | 0x80)
+            n >>= 7
+          end
+        end
+        out.pack('C*')
+      end
+
+      # =============================
+      # Helper: Compact-u16 Decoding (ShortVec)
+      # =============================
+      #
+      # Decodes a compact-u16 (ShortVec) value from an IO-like object.
+      # Reads bytes one at a time, accumulating the result until the MSB is 0.
+      #
+      # Args:
+      #   io (IO or StringIO): The input to read bytes from.
+      #
+      # Returns:
+      #   [Integer, Integer]: The decoded value and the number of bytes read.
+      #
+      def self.decode_compact_u16(io)
+        value = 0
+        shift = 0
+        bytes_read = 0
+        loop do
+          byte = io.read(1)
+          raise EOFError, 'Unexpected end of input while decoding compact-u16' unless byte
+
+          byte = byte.ord
+          value |= (byte & 0x7F) << shift
+          bytes_read += 1
+          break if (byte & 0x80).zero?
+
+          shift += 7
+        end
+        [value, bytes_read]
+      end
+
+      # =============================
+      # Helper: Little-Endian u64 Encoding
+      # =============================
+      #
+      # Encodes a u64 value in little-endian format
+      #
+      # Args:
+      #   n (Integer): The u64 value to encode
+      #
+      # Returns:
+      #   String: The little-endian encoded u64 value
+      #
+      def self.encode_le_u64(n)
+        [n].pack('Q<') # 64-bit little-endian
+      end
+
+      # =============================
+      # Helper: Little-Endian u64 Decoding
+      # =============================
+      #
+      # Decodes a little-endian u64 value from a sequence of bytes
+      #
+      # Args:
+      #   io (IO or StringIO): The input to read bytes from.
+      #
+      # Returns:
+      #   Integer: The decoded u64 value
+      #
+      def self.decode_le_u64(io)
+        io.read(8).unpack1('Q<')
+      end
+
+      # =============================
+      # Helper: Binary to Base58 Encoding
+      # =============================
+      #
+      # Encodes a sequence of bytes in Base58 format
+      #
+      # Args:
+      #   bytes (String): The bytes to encode
+      #
+      # Returns:
+      #   String: The Base58 encoded string
+      #
+      def self.binary_to_base58(binary)
+        Base58.binary_to_base58(binary, :bitcoin)
+      end
+
+      # =============================
+      # Helper: Base58 Decoding
+      # =============================
+      #
+      # Decodes a Base58 string into a binary string
+      #
+      # Args:
+      #   string (String): The Base58 encoded string
+      #
+      # Returns:
+      #   String: The decoded binary string
+      #
+      def self.base58_to_binary(string)
+        base58_to_bytes(string).pack('C*')
+      end
+
+      # =============================
+      # Helper: Base58 Encoding
+      # =============================
+      #
+      # Encodes a sequence of bytes in Base58 format
+      #
+      # Args:
+      #   bytes (String): The bytes to encode
+      #
+      # Returns:
+      #   String: The Base58 encoded string
+      #
+      def self.bytes_to_base58(bytes)
+        binary_to_base58(bytes.pack('C*'))
+      end
+
+      # =============================
+      # Helper: Base58 Decoding
+      # =============================
+      #
+      # Decodes a Base58 string into a sequence of bytes
+      #
+      # Args:
+      #   string (String): The Base58 encoded string
+      #
+      # Returns:
+      #   String: The decoded bytes
+      #
+      def self.base58_to_bytes(string)
+        Base58.base58_to_binary(string, :bitcoin).bytes
+      end
+
+      # =============================
+      # Helper: Base58 Validation
+      # =============================
+      #
+      # Checks if a string is a valid Base58 string
+      #
+      # Args:
+      #   string (String): The string to check
+      #
+      # Returns:
+      #   Boolean: True if the string is a valid Base58 string, false otherwise
+      #
+      def self.valid_base58?(string)
+        return false if string.nil? || string.empty?
+
+        Base58.decode(string)
+        true
+      rescue StandardError => _e
+        false
+      end
+    end
+  end
+end

data/lib/solace/utils/curve25519_dalek.rb

@@ -0,0 +1,59 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+require 'ffi'
+
+module Solace
+  module Utils
+    module Curve25519Dalek
+      extend FFI::Library
+
+      # Load the native library
+      #
+      # If the platform is not supported, a RuntimeError is raised. The native library
+      # can be built by compiling the Rust code in the root/ext directory.
+      #
+      # @return [String] The path to the native library
+      # @raise [RuntimeError] If the platform is not supported
+      libfile = case RUBY_PLATFORM
+                when /linux/ then 'libcurve25519_dalek-linux/libcurve25519_dalek.so'
+                when /darwin/ then 'libcurve25519_dalek-macos/libcurve25519_dalek.dylib'
+                when /mingw|mswin/ then 'libcurve25519_dalek-windows/curve25519_dalek.dll'
+                else raise 'Unsupported platform'
+                end
+
+      # The path to the native library
+      #
+      # @return [String] The path to the native library
+      LIB_PATH = File.expand_path(libfile, __dir__)
+
+      # Load the native library
+      ffi_lib LIB_PATH
+
+      # Attach the native function
+      #
+      # @return [FFI::Function] The native function
+      attach_function :is_on_curve, [:pointer], :int
+
+      # Checks if a point is on the curve
+      #
+      # @param bytes [Array] The bytes to check
+      # @return [Boolean] True if the point is on the curve, false otherwise
+      # @raise [ArgumentError] If the input is not 32 bytes
+      def self.on_curve?(bytes)
+        raise ArgumentError, 'Must be 32 bytes' unless bytes.bytesize == 32
+
+        FFI::MemoryPointer.new(:uchar, 32) do |ptr|
+          ptr.put_bytes(0, bytes)
+          result = Curve25519Dalek.is_on_curve(ptr)
+
+          case result
+          when 1 then return true
+          when 0 then return false
+          else raise "Unexpected return code from native is_on_curve: #{result}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solace/utils/pda.rb

@@ -0,0 +1,100 @@
+# encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+require 'digest'
+
+module Solace
+  module Utils
+    module PDA
+      # !@class InvalidPDAError
+      #   An error raised when an invalid PDA is generated
+      #
+      # @return [StandardError]
+      class InvalidPDAError < StandardError; end
+
+      # !@const PDA_MARKER
+      #   The marker used in PDA calculations
+      #
+      # @return [String]
+      PDA_MARKER = 'ProgramDerivedAddress'
+
+      # !@const MAX_BUMP_SEED
+      #   The maximum seed value for PDA calculations
+      #
+      # @return [Integer]
+      MAX_BUMP_SEED = 255
+
+      # Finds a valid program address by trying different seeds
+      #
+      # @param seeds [Array] The seeds to use in the calculation
+      # @param program_id [String] The program ID to use in the calculation
+      # @return [Array] The program address and bump seed
+      # @raise [InvalidPDAError] If no valid program address is found
+      def self.find_program_address(seeds, program_id)
+        MAX_BUMP_SEED.downto(0) do |bump|
+          address = create_program_address(seeds + [bump], program_id)
+          return [address, bump]
+        rescue InvalidPDAError
+          next
+        end
+
+        raise 'Unable to find a valid program address'
+      end
+
+      # Creates a program address from seeds and program ID
+      #
+      # @param seeds [Array] The seeds to use in the calculation
+      # @param program_id [String] The program ID to use in the calculation
+      # @return [String] The program address
+      # @raise [InvalidPDAError] If the program address is invalid
+      def self.create_program_address(seeds, program_id)
+        seed_bytes = seeds.map { |seed| seed_to_bytes(seed) }.flatten
+
+        program_id_bytes = Solace::Utils::Codecs.base58_to_bytes(program_id)
+
+        combined = seed_bytes + program_id_bytes + PDA_MARKER.bytes
+
+        hash_bin = Digest::SHA256.digest(combined.pack('C*'))
+
+        raise InvalidPDAError if Solace::Utils::Curve25519Dalek.on_curve?(hash_bin)
+
+        Solace::Utils::Codecs.bytes_to_base58(hash_bin.bytes)
+      end
+
+      # Prepares a list of seeds for creating a program address
+      #
+      # @param seed [String, Integer, Array] The seed to prepare
+      # @return [Array] The prepared seeds
+      def self.seed_to_bytes(seed)
+        case seed
+        when String
+          if looks_like_base58_address?(seed)
+            Solace::Utils::Codecs.base58_to_bytes(seed)
+          else
+            seed.bytes
+          end
+        when Integer
+          if seed.between?(0, 255)
+            [seed]
+          else
+            seed.digits(256)
+          end
+        when Array
+          seed
+        else
+          seed.to_s.bytes
+        end
+      end
+
+      # Checks if a string looks like a base58 address
+      #
+      # @param string [String] The string to check
+      # @return [Boolean] True if the string looks like a base58 address, false otherwise
+      def self.looks_like_base58_address?(string)
+        string.length >= 32 &&
+          string.length <= 44 &&
+          Solace::Utils::Codecs.valid_base58?(string)
+      end
+    end
+  end
+end

data/lib/solace/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Solace
+  VERSION = '0.0.2'
+end

data/lib/solace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# 🏷️ Version
+require_relative 'solace/version'
+
+# 🛠️ Helpers
+require_relative 'solace/constants'
+require_relative 'solace/connection'
+require_relative 'solace/utils/codecs'
+require_relative 'solace/utils/pda'
+require_relative 'solace/utils/curve25519_dalek'
+require_relative 'solace/concerns/binary_serializable'
+
+# ✨ Serializers
+require_relative 'solace/serializers/base'
+require_relative 'solace/serializers/base_serializer'
+require_relative 'solace/serializers/base_deserializer'
+
+# Base classes
+require_relative 'solace/serializable_record'
+
+# 🧬 Primitives
+require_relative 'solace/keypair'
+require_relative 'solace/public_key'
+require_relative 'solace/transaction'
+require_relative 'solace/message'
+require_relative 'solace/instruction'
+require_relative 'solace/address_lookup_table'
+
+# 📦 Instructions (Builders)
+# 
+# Glob require all instructions
+Dir[File.join(__dir__, 'solace/instructions', '**', '*.rb')].sort.each { |file| require file }
+
+# 📦 Programs
+require_relative 'solace/programs/base'
+require_relative 'solace/programs/spl_token'
+require_relative 'solace/programs/associated_token_account'
+