solace 0.0.3 → 0.0.5

data/lib/solace/utils/account_context.rb

@@ -2,32 +2,57 @@
 
 module Solace
   module Utils
-    # Internal utility for managing account context in transaction building
-    # with automatic deduplication and sorting
+    # 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
+      # @!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,
-      }
-      
-      # @!attribute header
+        fee_payer: false
+      }.freeze
+
+      # @!attribute  header
       #   The header for the transaction
       #
       # @return [Array<Integer>] The header for the transaction
       attr_accessor :header
-      
-      # @!attribute accounts
+
+      # @!attribute  accounts
       #   The accounts in the transaction
       #
       # @return [Array<String>] The accounts
       attr_accessor :accounts
 
-      # @!attribute pubkey_account_map
+      # @!attribute  pubkey_account_map
       #   The map of accounts
       #
       # @return [Hash] The map of accounts
@@ -42,36 +67,35 @@ module Solace
 
       # Set the fee payer account
       #
-      # @param pubkey [Solace::Keypair | Solace::PublicKey | String] The pubkey of 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
+      # @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
+      # @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
+      # @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
+      # @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
@@ -99,7 +123,7 @@ module Solace
       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
@@ -107,7 +131,7 @@ module Solace
       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
@@ -131,23 +155,19 @@ module Solace
       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|
-          merge_account(
-            pubkey,
-            signer: data[:signer],
-            writable: data[:writable],
-            fee_payer: data[:fee_payer]
-          )
+          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
@@ -156,10 +176,10 @@ module Solace
       # @return [Hash] The compiled accounts and header
       def compile
         self.header = calculate_header
-        self.accounts = order_accounts        
+        self.accounts = order_accounts
         self
       end
-      
+
       # Index of a pubkey in the accounts array
       #
       # @param pubkey_str [String] The public key of the account
@@ -170,7 +190,7 @@ module Solace
 
       # Get map of indicies for pubkeys in accounts array
       #
-      # @return [Hash<String, Integer>] The indices of the pubkeys in the accounts array
+      # @return [Hash{String => Integer}] The indices of the pubkeys in the accounts array
       def indices
         accounts.each_with_index.to_h
       end
@@ -179,22 +199,18 @@ module Solace
 
       # Add or merge an account into the context
       #
-      # @param pubkey [String | Solace::PublicKey | Solace::Keypair] The public key of the account
+      # @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
-      def merge_account(
-        pubkey,
-        signer:,
-        writable:,
-        fee_payer: false
-      )
-        pubkey_str = resolve_pubkey(pubkey)
+      # @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
 
@@ -203,16 +219,11 @@ module Solace
       # @return [Array<String>] The ordered accounts
       def order_accounts
         @pubkey_account_map.keys.sort_by do |pubkey|
-          if fee_payer?(pubkey)
-            0
-          elsif writable_signer?(pubkey)
-            1
-          elsif readonly_signer?(pubkey)
-            2
-          elsif writable_nonsigner?(pubkey)
-            2
-          elsif readonly_nonsigner?(pubkey)
-            3
+          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
@@ -228,26 +239,14 @@ module Solace
       #
       # @return [Array] The header for the transaction
       def calculate_header
-        @pubkey_account_map.keys.reduce([0, 0, 0]) do |acc, pubkey|
+        @pubkey_account_map.keys.each_with_object([0, 0, 0]) do |pubkey, acc|
           acc[0] += 1 if signer?(pubkey)
-           
-          if readonly_signer?(pubkey)
-            acc[1] += 1
-          elsif readonly_nonsigner?(pubkey)
-            acc[2] += 1
-          end
 
-          acc
+          if readonly_signer?(pubkey) then acc[1] += 1
+          elsif readonly_nonsigner?(pubkey) then acc[2] += 1
+          end
         end
       end
-
-      # Resolve the pubkey from a Solace::PublicKey or String
-      #
-      # @param pubkey [String|Solace::PublicKey] The pubkey to resolve
-      # @return [String] The resolved pubkey
-      def resolve_pubkey(pubkey)
-        pubkey.is_a?(String) ? pubkey : pubkey.address
-      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

data/lib/solace/utils/pda.rb

@@ -5,27 +5,34 @@ require 'digest'
 
 module Solace
   module Utils
+    # Module for generating program addresses
+    #
+    # This module provides methods for generating program addresses from seeds and program IDs. It interfaces
+    # with the Curve25519 Dalek library to check if a point is on the curve. It also provides a method for
+    # converting seeds to bytes and a method for checking if a string looks like a base58 address.
+    #
+    # @see Solace::Utils::Curve25519Dalek
+    # @since 0.0.1
     module PDA
-      # !@class InvalidPDAError
-      #   An error raised when an invalid PDA is generated
-      #
-      # @return [StandardError]
+      # InvalidPDAError is an error raised when an invalid PDA is generated
       class InvalidPDAError < StandardError; end
 
-      # !@const PDA_MARKER
-      #   The marker used in PDA calculations
-      #
-      # @return [String]
+      # !@attribute PDA_MARKER
+      # PDA_MARKER is the marker used in PDA calculations
       PDA_MARKER = 'ProgramDerivedAddress'
 
-      # !@const MAX_BUMP_SEED
-      #   The maximum seed value for PDA calculations
-      #
-      # @return [Integer]
+      # !@attribute MAX_BUMP_SEED
+      # The maximum seed value for PDA calculations
       MAX_BUMP_SEED = 255
 
       # Finds a valid program address by trying different seeds
       #
+      # @example Find a PDA with bump seed
+      #   seeds = ['metadata', mint_address, 'edition']
+      #   program_id = 'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s'
+      #
+      #   address, bump = Solace::Utils::PDA.find_program_address(seeds, 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 [Array] The program address and bump seed
@@ -68,17 +75,9 @@ module Solace
       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
+          looks_like_base58_address?(seed) ? Solace::Utils::Codecs.base58_to_bytes(seed) : seed.bytes
         when Integer
-          if seed.between?(0, 255)
-            [seed]
-          else
-            seed.digits(256)
-          end
+          seed.between?(0, 255) ? [seed] : seed.digits(256)
         when Array
           seed
         else
@@ -91,8 +90,7 @@ module Solace
       # @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 &&
+        string.length.between?(32, 44) &&
           Solace::Utils::Codecs.valid_base58?(string)
       end
     end

data/lib/solace/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Solace::VERSION is the version of the Solace gem
 module Solace
-  VERSION = '0.0.3'
+  VERSION = '0.0.5'
 end

data/lib/solace.rb

@@ -13,13 +13,9 @@ 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'
@@ -30,17 +26,16 @@ require_relative 'solace/address_lookup_table'
 require_relative 'solace/transaction_composer'
 
 # 📦 Composers (Builders)
-# 
+#
 # Glob require all instructions
-Dir[File.join(__dir__, 'solace/composers', '**', '*.rb')].sort.each { |file| require file }
+Dir[File.join(__dir__, 'solace/composers', '**', '*.rb')].each { |file| require file }
 
 # 📦 Instructions (Builders)
-# 
+#
 # Glob require all instructions
-Dir[File.join(__dir__, 'solace/instructions', '**', '*.rb')].sort.each { |file| require file }
+Dir[File.join(__dir__, 'solace/instructions', '**', '*.rb')].each { |file| require file }
 
 # 📦 Programs
 require_relative 'solace/programs/base'
 require_relative 'solace/programs/spl_token'
 require_relative 'solace/programs/associated_token_account'
-