solace 0.0.2 → 0.0.5

data/lib/solace/transaction_composer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# lib/solace/transaction_composer.rb
+module Solace
+  # Composes multi-instruction transactions with automatic account management
+  #
+  # @example
+  #   # Initialize a transaction composer
+  #   composer = Solace::TransactionComposer.new(connection: connection)
+  #
+  #   # Add an instruction composer
+  #   composer.add_instruction(
+  #     Solace::Composers::SystemProgramTransferComposer.new(
+  #       to: 'pubkey1',
+  #       from: 'pubkey2',
+  #       lamports: 100
+  #     )
+  #   )
+  #
+  #   # Add another instruction composer
+  #   composer.add_instruction(
+  #     Solace::Composers::SplTokenProgramTransferCheckedComposer.new(
+  #       from: 'pubkey4',
+  #       to: 'pubkey5',
+  #       mint: 'pubkey6',
+  #       authority: 'pubkey7',
+  #       amount: 1_000_000,
+  #       decimals: 6
+  #     )
+  #   )
+  #
+  #   # Set the fee payer
+  #   composer.set_fee_payer('pubkey8')
+  #
+  #   # Compose the transaction
+  #   tx = composer.compose_transaction
+  #
+  #   # Sign the transaction with all required signers
+  #   tx.sign(*required_signers)
+  #
+  # @since 0.0.1
+  class TransactionComposer
+    # @!attribute connection
+    #   The connection to the Solana cluster
+    attr_reader :connection
+
+    # @!attribute context
+    #   The account context
+    attr_reader :context
+
+    # @!attribute instruction_composers
+    #   The instruction composers
+    attr_reader :instruction_composers
+
+    # Initialize the composer
+    #
+    # @param connection [Solace::Connection] The connection to the Solana cluster
+    def initialize(connection:)
+      @connection = connection
+      @instruction_composers = []
+      @context = Utils::AccountContext.new
+    end
+
+    # Add an instruction composer to the transaction
+    #
+    # @param composer [Composers::Base] The instruction composer
+    # @return [TransactionComposer] Self for chaining
+    def add_instruction(composer)
+      merge_accounts(composer.account_context)
+      instruction_composers << composer
+      self
+    end
+
+    # Set the fee payer for the transaction
+    #
+    # @param pubkey [String, Solace::PublicKey, Solace::Keypair] The fee payer pubkey
+    # @return [TransactionComposer] Self for chaining
+    def set_fee_payer(pubkey)
+      context.set_fee_payer(pubkey)
+      self
+    end
+
+    # Compose the final transaction
+    #
+    # @return [Solace::Transaction] The composed transaction (unsigned)
+    def compose_transaction
+      context.compile
+
+      message = Solace::Message.new(
+        header: context.header,
+        accounts: context.accounts,
+        instructions: build_instructions,
+        recent_blockhash: connection.get_latest_blockhash
+      )
+
+      Solace::Transaction.new(message: message)
+    end
+
+    private
+
+    # Build all instructions with resolved indices
+    #
+    # @return [Array<Solace::Instruction>] The built instructions
+    def build_instructions
+      instruction_composers.map { _1.build_instruction(context) }
+    end
+
+    # Merge all accounts from another AccountContext into this one
+    #
+    # @param account_context [AccountContext] The other context to merge from
+    def merge_accounts(account_context)
+      context.merge_from(account_context)
+    end
+  end
+end

data/lib/solace/utils/account_context.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Solace
+  module Utils
+    # Utility for managing account context for composers
+    #
+    # This utility is used to manage the accounts in a transaction composer and instructions composer. It
+    # provides methods for managing the accounts and their permissions, as well as compiling the accounts
+    # into the final format required by the instruction builders. Concerns like deduplication and ordering
+    # are handled by this utility.
+    #
+    # @example Usage
+    #   # Create a new account context
+    #   context = Solace::Utils::AccountContext.new
+    #
+    #   # Add accounts
+    #   context.add_writable_signer('pubkey1')
+    #   context.add_readonly_nonsigner('pubkey2')
+    #
+    #   # Merge accounts from another context
+    #   context = context.merge_from(other_context)
+    #
+    #   # Set fee payer
+    #   context.set_fee_payer('pubkey3')
+    #
+    #   # Compile the accounts
+    #   context.compile
+    #
+    # @see Solace::TransactionComposer
+    # @see Solace::Composers::Base
+    # @since 0.0.3
+    class AccountContext
+      # @!attribute  DEFAULT_ACCOUNT
+      #   The default account data
+      #
+      # @return [Hash] The default account data with lowest level of permissions
+      DEFAULT_ACCOUNT = {
+        signer: false,
+        writable: false,
+        fee_payer: false
+      }.freeze
+
+      # @!attribute  header
+      #   The header for the transaction
+      #
+      # @return [Array<Integer>] The header for the transaction
+      attr_accessor :header
+
+      # @!attribute  accounts
+      #   The accounts in the transaction
+      #
+      # @return [Array<String>] The accounts
+      attr_accessor :accounts
+
+      # @!attribute  pubkey_account_map
+      #   The map of accounts
+      #
+      # @return [Hash] The map of accounts
+      attr_accessor :pubkey_account_map
+
+      # Initialize the account context
+      def initialize
+        @header = []
+        @accounts = []
+        @pubkey_account_map = {}
+      end
+
+      # Set the fee payer account
+      #
+      # @param pubkey [Solace::Keypair, Solace::PublicKey, String] The pubkey of the fee payer account
+      def set_fee_payer(pubkey)
+        merge_account(pubkey, signer: true, writable: true, fee_payer: true)
+      end
+
+      # Add a signer account
+      #
+      # @param pubkey [Solace::Keypair, Solace::PublicKey, String] The pubkey of the signer account
+      def add_writable_signer(pubkey)
+        merge_account(pubkey, signer: true, writable: true)
+      end
+
+      # Add a writable account
+      #
+      # @param pubkey [Solace::Keypair, Solace::PublicKey, String] The pubkey of the writable account
+      def add_writable_nonsigner(pubkey)
+        merge_account(pubkey, signer: false, writable: true)
+      end
+
+      # Add a readonly signer account
+      #
+      # @param pubkey [Solace::Keypair, Solace::PublicKey, String] The pubkey of the readonly signer account
+      def add_readonly_signer(pubkey)
+        merge_account(pubkey, signer: true, writable: false)
+      end
+
+      # Add a readonly account
+      #
+      # @param pubkey [Solace::Keypair, Solace::PublicKey, String] The pubkey of the readonly account
+      def add_readonly_nonsigner(pubkey)
+        merge_account(pubkey, signer: false, writable: false)
+      end
+
+      # Predicate to check if an account is a fee payer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a fee payer
+      def fee_payer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:fee_payer] }
+      end
+
+      # Predicate to check if an account is a signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a signer
+      def signer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:signer] }
+      end
+
+      # Predicate to check if an account is writable
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is writable
+      def writable?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:writable] }
+      end
+
+      # Predicate to check if an account is a writable signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a writable signer
+      def writable_signer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:signer] && acc[:writable] }
+      end
+
+      # Predicate to check if an account is writable and not a signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is writable and not a signer
+      def writable_nonsigner?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| !acc[:signer] && acc[:writable] }
+      end
+
+      # Predicate to check if an account is a readonly signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a readonly signer
+      def readonly_signer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:signer] && !acc[:writable] }
+      end
+
+      # Predicate to check if an account is readonly and not a signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is readonly and not a signer
+      def readonly_nonsigner?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| !acc[:signer] && !acc[:writable] }
+      end
+
+      # Merge all accounts from another AccountContext into this one
+      #
+      # @param other_context [AccountContext] The other context to merge from
+      def merge_from(other_context)
+        other_context.pubkey_account_map.each do |pubkey, data|
+          signer, writable, fee_payer = data.values_at(:signer, :writable, :fee_payer)
+          merge_account(pubkey, signer: signer, writable: writable, fee_payer: fee_payer)
+        end
+      end
+
+      # Compile accounts into final format
+      #
+      # Gets unique accounts and sorts them in the following order:
+      #   - Signers first (Solana requirement)
+      #   - Then writable accounts
+      #   - Then readonly accounts
+      #
+      # @return [Hash] The compiled accounts and header
+      def compile
+        self.header = calculate_header
+        self.accounts = order_accounts
+        self
+      end
+
+      # Index of a pubkey in the accounts array
+      #
+      # @param pubkey_str [String] The public key of the account
+      # @return [Integer] The index of the pubkey in the accounts array or -1 if not found
+      def index_of(pubkey_str)
+        indices[pubkey_str] || -1
+      end
+
+      # Get map of indicies for pubkeys in accounts array
+      #
+      # @return [Hash{String => Integer}] The indices of the pubkeys in the accounts array
+      def indices
+        accounts.each_with_index.to_h
+      end
+
+      private
+
+      # Add or merge an account into the context
+      #
+      # @param pubkey [String, Solace::PublicKey, Solace::Keypair] The public key of the account
+      # @param signer [Boolean] Whether the account is a signer
+      # @param writable [Boolean] Whether the account is writable
+      # @param [Boolean] fee_payer
+      def merge_account(pubkey, signer:, writable:, fee_payer: false)
+        pubkey_str = pubkey.is_a?(String) ? pubkey : pubkey.address
+
+        @pubkey_account_map[pubkey_str] ||= DEFAULT_ACCOUNT.dup
+        @pubkey_account_map[pubkey_str][:signer] ||= signer
+        @pubkey_account_map[pubkey_str][:writable] ||= writable
+        @pubkey_account_map[pubkey_str][:fee_payer] ||= fee_payer
+
+        self
+      end
+
+      # Order accounts by signer, writable, readonly signer, readonly
+      #
+      # @return [Array<String>] The ordered accounts
+      def order_accounts
+        @pubkey_account_map.keys.sort_by do |pubkey|
+          if fee_payer?(pubkey) then 0
+          elsif writable_signer?(pubkey) then 1
+          elsif readonly_signer?(pubkey) then 2
+          elsif writable_nonsigner?(pubkey) then 3
+          elsif readonly_nonsigner?(pubkey) then 4
+          else
+            raise ArgumentError, "Unknown account type for pubkey: #{pubkey}"
+          end
+        end
+      end
+
+      # Calculate the header for the transaction
+      #
+      # @note The header is an array of three integers:
+      #   - The number of signers (writable + readonly)
+      #   - The number of readonly signers
+      #   - The number of readonly unsigned accounts
+      #
+      # @return [Array] The header for the transaction
+      def calculate_header
+        @pubkey_account_map.keys.each_with_object([0, 0, 0]) do |pubkey, acc|
+          acc[0] += 1 if signer?(pubkey)
+
+          if readonly_signer?(pubkey) then acc[1] += 1
+          elsif readonly_nonsigner?(pubkey) then acc[2] += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solace/utils/codecs.rb

@@ -7,206 +7,134 @@ require 'stringio'
 
 module Solace
   module Utils
+    # Module for encoding and decoding data
+    #
+    # @since 0.0.1
     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
-      #
+      # @param base64 [String] The base64 string to decode
+      # @return [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
+      # Encodes a compact-u16 value in a compact form (shortvec)
       #
-      # Returns:
-      #   String: The compactly encoded u16 value
-      #
-      def self.encode_compact_u16(n)
+      # @param u16 [Integer] The compact-u16 value to encode
+      # @return [String] The compactly encoded compact-u16 value
+      def self.encode_compact_u16(u16)
         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
+          if (u16 >> 7).zero?
+            out << u16
             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
+          # 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 << ((u16 & 0x7F) | 0x80)
+          u16 >>= 7
         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.
+      # Reads bytes one at a time, accumulating the result until the MSB is 0.
       #
-      def self.decode_compact_u16(io)
+      # @param stream [IO, StringIO] The input to read bytes from.
+      # @return [Integer, Integer] The decoded value and the number of bytes read.
+      def self.decode_compact_u16(stream)
         value = 0
         shift = 0
         bytes_read = 0
+
         loop do
-          byte = io.read(1)
+          byte = stream.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?
+          break if byte.nobits?(0x80)
 
           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
+      # @param u64 [Integer] The u64 value to encode
+      # @return [String] The little-endian encoded u64 value
+      def self.encode_le_u64(u64)
+        [u64].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<')
+      # @param stream [IO, StringIO] The input to read bytes from.
+      # @return [Integer] The decoded u64 value
+      def self.decode_le_u64(stream)
+        stream.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
-      #
+      # @param binary [String] The bytes to encode
+      # @return [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
-      #
+      # @param string [String] The Base58 encoded string
+      # @return [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
-      #
+      # @param bytes [String] The bytes to encode
+      # @return [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
-      #
+      # @param string [String] The Base58 encoded string
+      # @return [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
-      #
+      # @param string [String] The string to check
+      # @return [Boolean] True if the string is a valid Base58 string, false otherwise
       def self.valid_base58?(string)
         return false if string.nil? || string.empty?
 

data/lib/solace/utils/curve25519_dalek.rb

@@ -5,6 +5,14 @@ require 'ffi'
 
 module Solace
   module Utils
+    # Module for interacting with the Curve25519 Dalek library
+    #
+    # This module provides a wrapper around the Curve25519 Dalek library, which is a pure-Rust
+    # implementation of the Curve25519 elliptic curve. It uses FFI to interface with the native
+    # rust library when checking if a point is on the curve.
+    #
+    # @see Solace::Utils::PDA
+    # @since 0.0.2
     module Curve25519Dalek
       extend FFI::Library
 
@@ -22,8 +30,7 @@ module Solace
                 else raise 'Unsupported platform'
                 end
 
-      # The path to the native library
-      #
+      # !@attribute LIB_PATH
       # @return [String] The path to the native library
       LIB_PATH = File.expand_path(libfile, __dir__)
 
@@ -31,8 +38,6 @@ module Solace
       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