solace 0.0.10 → 0.1.1

data/lib/solace/composers/system_program_create_account_composer.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating an account using the system program.
+    #
+    # This composer resolves and orders the required accounts for a `CreateAccount` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::SystemProgram::CreateAccountInstruction`).
+    #
+    # It is used for creating new accounts on the Solana blockchain.
+    #
+    # Required accounts:
+    # - **From**: funding account (writable, signer)
+    # - **Owner**: owner program id (readonly, non-signer)
+    # - **New Account**: new account to create (writable, signer)
+    #
+    # @example Compose and build a create account instruction
+    #   composer = SystemProgramCreateAccountComposer.new(
+    #     from: payer_address,
+    #     new_account: new_account_address,
+    #     owner: owner_address,
+    #     lamports: 1000,
+    #     space: 1024
+    #   )
+    #
+    # @see Instructions::SystemProgram::CreateAccountInstruction
+    # @since 0.1.0
+    class SystemProgramCreateAccountComposer < Base
+      # Extracts the to address from the params
+      #
+      # @return [String] The from address
+      def from
+        params[:from].to_s
+      end
+
+      # Extracts the new account address from the params
+      #
+      # @return [String] The new account address
+      def new_account
+        params[:new_account].to_s
+      end
+
+      # Returns the system program id
+      #
+      # @return [String] The system program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID.to_s
+      end
+
+      # Extracts the owner address from the params
+      #
+      # @return [String] The owner address
+      def owner
+        params[:owner].to_s
+      end
+
+      # Returns the lamports to transfer
+      #
+      # @return [Integer] The lamports to transfer
+      def lamports
+        params[:lamports]
+      end
+
+      # Returns the space to allocate
+      #
+      # @return [Integer] The space to allocate
+      def space
+        params[:space]
+      end
+
+      # Setup accounts required for create account instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_signer(from)
+        account_context.add_writable_signer(new_account)
+        account_context.add_readonly_nonsigner(system_program)
+      end
+
+      # Build instruction with resolved account indices
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction]
+      def build_instruction(account_context)
+        Solace::Instructions::SystemProgram::CreateAccountInstruction.build(
+          space: space,
+          lamports: lamports,
+          owner: owner,
+          from_index: account_context.index_of(from),
+          new_account_index: account_context.index_of(new_account),
+          system_program_index: account_context.index_of(system_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/connection.rb

@@ -42,6 +42,12 @@ module Solace
     #   The default options for RPC requests
     attr_reader :default_options
 
+    # Last fetched blockhash
+    attr_reader :last_fetched_blockhash
+
+    # Last fetched blockhash timestamp
+    attr_reader :last_fetched_block_height
+
     # Initialize the connection with a default or custom RPC URL
     #
     # @param rpc_url [String] The URL of the Solana RPC node
@@ -49,11 +55,13 @@ module Solace
     # @return [Solace::Connection] The connection object
     # @param [Integer] http_open_timeout The timeout for opening an HTTP connection
     # @param [Integer] http_read_timeout The timeout for reading an HTTP response
+    # @param [String] encoding The encoding for the RPC requests
     def initialize(
       rpc_url = 'http://localhost:8899',
       commitment: 'processed',
       http_open_timeout: 30,
-      http_read_timeout: 60
+      http_read_timeout: 60,
+      encoding: 'base64'
     )
       # Initialize the RPC client
       @rpc_client = Utils::RPCClient.new(
@@ -65,10 +73,31 @@ module Solace
       # Set default options for rpc requests
       @default_options = {
         commitment: commitment,
-        encoding: 'base64'
+        encoding: encoding
       }
     end
 
+    # Gets the version of the Solana node
+    #
+    # @return [Hash] The version information
+    def get_version
+      @rpc_client.rpc_request('getVersion')['result']
+    end
+
+    # Get the health status of the Solana node
+    #
+    # @return [String] The health status
+    def get_health
+      @rpc_client.rpc_request('getHealth')['result']
+    end
+
+    # Get the genesis hash of the Solana node
+    #
+    # @return [String] The genesis hash
+    def get_genesis_hash
+      @rpc_client.rpc_request('getGenesisHash')['result']
+    end
+
     # Request an airdrop of lamports to a given address
     #
     # @param pubkey [String] The public key of the account to receive the airdrop
@@ -97,12 +126,34 @@ module Solace
 
     # Get the latest blockhash from the Solana node
     #
+    # Stores the last fetched blockhash and last valid block height in the connection, as
+    # different clients may need to access these values.
+    #
+    # @example
+    #  # Initialize the connection
+    #  connection = Solace::Connection.new('http://localhost:8899', commitment: 'confirmed')
+    #
+    #  # Get the latest blockhash
+    #  blockhash, last_valid_block_height = connection.get_latest_blockhash
+    #
+    #  puts "Latest blockhash: #{blockhash}"
+    #  puts "Last valid block height: #{last_valid_block_height}"
+    #
+    #  # Access the last fetched blockhash and height from the connection
+    #  puts "Stored blockhash: #{connection.last_fetched_blockhash}"
+    #  puts "Stored last valid block height: #{connection.last_fetched_block_height}"
+    #
     # @return [Array<String, Integer>] The latest blockhash and lastValidBlockHeight
     def get_latest_blockhash
-      @rpc_client
-        .rpc_request('getLatestBlockhash', [build_get_latest_blockhash_options])
-        .dig('result', 'value')
-        .values_at('blockhash', 'lastValidBlockHeight')
+      result = @rpc_client
+               .rpc_request('getLatestBlockhash', [build_get_latest_blockhash_options])
+               .dig('result', 'value')
+
+      # Set the last fetched blockhash and last valid block height in the connection
+      @last_fetched_blockhash, @last_fetched_block_height = result.values_at('blockhash', 'lastValidBlockHeight')
+
+      # Return the blockhash and last valid block height
+      [@last_fetched_blockhash, @last_fetched_block_height]
     end
 
     # Get the minimum required lamports for rent exemption
@@ -121,6 +172,14 @@ module Solace
       @rpc_client.rpc_request('getAccountInfo', [pubkey, default_options]).dig('result', 'value')
     end
 
+    # Get multiple accounts information from the Solana node
+    #
+    # @param pubkeys [Array<String>] The public keys of the accounts
+    # @return [Array<Object>] The accounts information
+    def get_multiple_accounts(pubkeys)
+      @rpc_client.rpc_request('getMultipleAccounts', [pubkeys, default_options]).dig('result', 'value')
+    end
+
     # Get the balance of a specific account
     #
     # @param pubkey [String] The public key of the account
@@ -137,10 +196,19 @@ module Solace
       @rpc_client.rpc_request('getTokenAccountBalance', [token_account, default_options]).dig('result', 'value')
     end
 
+    # Gets the token accounts by owner
+    #
+    # @param owner [String] The public key of the owner
+    # @return [Array<Hash>] The token accounts owned by the owner for the specified mint
+    def get_token_accounts_by_owner(owner)
+      params = [owner, { programId: Constants::TOKEN_PROGRAM_ID }, default_options]
+      @rpc_client.rpc_request('getTokenAccountsByOwner', params).dig('result', 'value')
+    end
+
     # Get the transaction by signature
     #
     # @param signature [String] The signature of the transaction
-    # @return [Solace::Transaction] The transaction object
+    # @return [Transaction] The transaction object
     # @param [Hash{Symbol => Object}] options
     def get_transaction(signature, options = { maxSupportedTransactionVersion: 0 })
       @rpc_client.rpc_request('getTransaction', [signature, default_options.merge(options)])['result']
@@ -173,9 +241,9 @@ module Solace
       get_signature_statuses([signature])
     end
 
-    # Builds send_tranaction options
+    # Builds send_transaction options
     #
-    # @params [Hash] The overrides for the options
+    # @param overrides[Hash] The overrides for the options
     # @return [Hash] The options for the send_transaction call
     def build_send_transaction_options(overrides)
       {
@@ -188,13 +256,22 @@ module Solace
 
     # Send a transaction to the Solana node
     #
-    # @param transaction [Solace::Transaction] The transaction to send
+    # @param transaction [Transaction] The transaction to send
     # @param [Hash{Symbol => Object}] overrides
     # @return [String] The signature of the transaction
     def send_transaction(transaction, overrides = {})
       @rpc_client.rpc_request('sendTransaction', [transaction, build_send_transaction_options(overrides)])
     end
 
+    # Simulate a transaction on the Solana node
+    #
+    # @param transaction [Transaction] The transaction to simulate
+    # @param [Hash{Symbol => Object}] overrides
+    # @return [Object] The result of the simulation
+    def simulate_transaction(transaction, overrides = {})
+      @rpc_client.rpc_request('simulateTransaction', [transaction, build_send_transaction_options(overrides)])
+    end
+
     # Wait until the yielded signature reaches the desired commitment or timeout.
     #
     # @param commitment [String] One of "processed", "confirmed", "finalized"
@@ -214,7 +291,7 @@ module Solace
       deadline = monotonic_deadline(timeout)
 
       # Wait for confirmation
-      until dealine_passed?(deadline)
+      until deadline_passed?(deadline)
         return signature if commitment_reached?(signature, commitment)
 
         sleep interval
@@ -244,15 +321,15 @@ module Solace
 
     # Checks if a timeout deadline has been reached
     #
-    # @params deadline [Integer] The deadline for the timeout
-    # @return [boolean] whether the dealine has passed
-    def dealine_passed?(deadline)
+    # @param deadline [Integer] The deadline for the timeout
+    # @return [Boolean] whether the deadline has passed
+    def deadline_passed?(deadline)
       Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
     end
 
     # Sets a deadline given a timeout in seconds
     #
-    # @params seconds [Integer] The seconds for the deadline
+    # @param seconds [Integer] The seconds for the deadline
     # @return [Integer] The deadline in seconds
     def monotonic_deadline(seconds)
       Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds

data/lib/solace/errors/confirmation_timeout.rb

@@ -2,7 +2,21 @@
 
 module Solace
   module Errors
-    # Waiting for confirmation exceeded timeout
+    # Raised when a transaction confirmation times out.
+    #
+    # This error is raised when waiting for a transaction to be confirmed by the
+    # network exceeds the specified timeout period. This can happen when the
+    # network is congested, the transaction fee is too low, or the transaction
+    # was not successfully processed by the validators.
+    #
+    # @example Handling confirmation timeout
+    #   begin
+    #     connection.wait_for_confirmed_signature(signature, timeout: 30)
+    #   rescue Solace::Errors::ConfirmationTimeout => e
+    #     puts "Transaction confirmation timed out: #{e.message}"
+    #   end
+    #
+    # @since 0.0.1
     class ConfirmationTimeout < StandardError
       attr_reader :signature, :commitment, :timeout
 
@@ -19,9 +33,9 @@ module Solace
 
       # Formats a confirmation timeout error
       #
-      # @params [String] signature The signature of the transaction
-      # @params [String] commitment The commitment level not reached
-      # @params [Integer] timeout The time out reached
+      # @param signature [String] The signature of the transaction
+      # @param commitment [String] The commitment level not reached
+      # @param timeout [Integer] The time out reached
       # @return [Solace::Errors::ConfirmationTimeout] The formatted error
       def self.format(signature, commitment, timeout)
         new(

data/lib/solace/errors/http_error.rb

@@ -2,7 +2,22 @@
 
 module Solace
   module Errors
-    # Non-2xx HTTP or low-level network issues
+    # Raised when an HTTP request to the RPC node fails.
+    #
+    # This error is raised for network-level failures when communicating with the
+    # Solana RPC node, including connection timeouts, DNS resolution failures,
+    # and HTTP protocol errors. This is distinct from RPC-level errors, which are
+    # raised as {Solace::Errors::RPCError}.
+    #
+    # @example Handling HTTP errors
+    #   begin
+    #     connection.get_account_info(address)
+    #   rescue Solace::Errors::HTTPError => e
+    #     puts "Network error: #{e.message}"
+    #   end
+    #
+    # @see Solace::Errors::RPCError
+    # @since 0.0.1
     class HTTPError < StandardError
       attr_reader :code, :body
 

data/lib/solace/errors/parse_error.rb

@@ -2,7 +2,21 @@
 
 module Solace
   module Errors
-    # JSON parsing failed
+    # Raised when parsing or deserializing data fails.
+    #
+    # This error is raised when the gem encounters data that cannot be properly
+    # parsed or deserialized, such as malformed JSON responses from the RPC node,
+    # invalid binary data, or unexpected data structures. This typically indicates
+    # either a bug in the gem or an incompatibility with the RPC node's response format.
+    #
+    # @example Handling parse errors
+    #   begin
+    #     transaction = Solace::Transaction.deserialize(binary_data)
+    #   rescue Solace::Errors::ParseError => e
+    #     puts "Failed to parse transaction: #{e.message}"
+    #   end
+    #
+    # @since 0.0.1
     class ParseError < StandardError
       attr_reader :body
 

data/lib/solace/errors/rpc_error.rb

@@ -2,7 +2,23 @@
 
 module Solace
   module Errors
-    # JSON-RPC returned an "error" object
+    # Raised when the RPC node returns an error response.
+    #
+    # This error is raised when the Solana RPC node successfully processes the HTTP
+    # request but returns an error in the JSON-RPC response. This includes errors
+    # like invalid parameters, insufficient funds, blockhash not found, and other
+    # RPC method-specific errors. The error message and code from the RPC response
+    # are included in the exception.
+    #
+    # @example Handling RPC errors
+    #   begin
+    #     connection.send_transaction(transaction)
+    #   rescue Solace::Errors::RPCError => e
+    #     puts "RPC error (code #{e.code}): #{e.message}"
+    #   end
+    #
+    # @see Solace::Errors::HTTPError
+    # @since 0.0.1
     class RPCError < StandardError
       attr_reader :rpc_code, :rpc_message, :rpc_data
 

data/lib/solace/errors.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 module Solace
-  # Error handling module
+  # The Errors module contains custom exception classes for the Solace gem.
   #
-  # This module provides error classes for handling different types of errors that may occur during
-  # Solana RPC requests and processing transactions.
+  # These exceptions provide specific error handling for various failure scenarios
+  # when interacting with the Solana blockchain, including:
+  # - {Solace::Errors::HTTPError} - HTTP communication failures
+  # - {Solace::Errors::RPCError} - RPC method errors returned by the node
+  # - {Solace::Errors::ParseError} - Data parsing and deserialization errors
+  # - {Solace::Errors::ConfirmationTimeout} - Transaction confirmation timeouts
   #
+  # @see Solace::Connection
   # @since 0.0.8
   module Errors
     # JSON-RPC Errors

data/lib/solace/instructions/associated_token_account/create_associated_token_account_instruction.rb

@@ -2,6 +2,15 @@
 
 module Solace
   module Instructions
+    # The AssociatedTokenAccount module contains instruction builders for the
+    # Associated Token Account Program.
+    #
+    # The Associated Token Account (ATA) Program provides a deterministic way to
+    # derive token account addresses for a given wallet and mint. This ensures that
+    # each wallet has a single, predictable token account for each token type.
+    #
+    # @see https://spl.solana.com/associated-token-account
+    # @since 0.0.2
     module AssociatedTokenAccount
       # Instruction for creating an Associated Token Account.
       #
@@ -18,8 +27,6 @@ module Solace
       #     token_program_index: 5,
       #     program_index: 6
       #   )
-      #
-      # @since 0.0.2
       class CreateAssociatedTokenAccountInstruction
         # !@const INSTRUCTION_INDEX
         #   Instruction index for CreateAssociatedTokenAccount

data/lib/solace/instructions/spl_token/initialize_mint_instruction.rb

@@ -18,7 +18,6 @@ module Solace
       #     program_index: 3
       #   )
       #
-      # @see Solace::Instructions::SystemProgram::CreateAccountInstruction
       # @since 0.0.2
       class InitializeMintInstruction
         # Instruction index for Initialize Mint

data/lib/solace/instructions/spl_token/transfer_instruction.rb

@@ -2,6 +2,27 @@
 
 module Solace
   module Instructions
+    # The SplToken module contains instruction builders for the SPL Token Program.
+    #
+    # The SPL Token Program is Solana's standard for fungible and non-fungible tokens.
+    # It provides instructions for creating token mints, creating token accounts,
+    # minting tokens, transferring tokens, and managing token authorities.
+    #
+    # This module contains classes that build the low-level instruction data required
+    # to interact with the SPL Token Program. Each class corresponds to a specific
+    # instruction in the program.
+    #
+    # @example Building a transfer instruction
+    #   instruction = Solace::Instructions::SplToken::TransferInstruction.build(
+    #     source_index: 0,
+    #     destination_index: 1,
+    #     owner_index: 2,
+    #     program_index: 3,
+    #     amount: 1_000_000
+    #   )
+    #
+    # @see https://spl.solana.com/token
+    # @since 0.0.2
     module SplToken
       # Instruction for transferring SPL tokens.
       #

data/lib/solace/instructions/system_program/create_account_instruction.rb

@@ -1,6 +1,36 @@
 # frozen_string_literal: true
 
 module Solace
+  # The Instructions module contains low-level instruction builders for Solana programs.
+  #
+  # Instructions are the fundamental building blocks of Solana transactions. Each
+  # instruction represents a single operation to be executed by an on-chain program.
+  # The classes in this module build the binary instruction data and specify the
+  # accounts required for each operation.
+  #
+  # Instructions are organized by program:
+  # - {Solace::Instructions::SystemProgram} - System Program instructions
+  # - {Solace::Instructions::SplToken} - SPL Token Program instructions
+  # - {Solace::Instructions::AssociatedTokenAccount} - Associated Token Account Program instructions
+  #
+  # Being a low-level primitive, you must build instructions manually.
+  #
+  # @example Building a system transfer instruction
+  #
+  #   # Assuming the transaction's accounts are ordered as follows:
+  #   accounts = %w[from_address to_address system_program_id]
+  #
+  #   # Build the instruction by specifying the account indices directly
+  #   instruction = Solace::Instructions::SystemProgram::TransferInstruction.build(
+  #     from_index: 0,
+  #     to_index: 1,
+  #     program_index: 2,
+  #     lamports: 1_000_000
+  #   )
+  #
+  # @see Solace::Instruction
+  # @see Solace::Composers
+  # @since 0.0.1
   module Instructions
     module SystemProgram
       # Instruction for creating a new account.

data/lib/solace/instructions/system_program/transfer_instruction.rb

@@ -2,6 +2,17 @@
 
 module Solace
   module Instructions
+    # The SystemProgram module contains instruction builders for the System Program.
+    #
+    # The System Program is Solana's native program for fundamental operations like
+    # creating accounts, transferring SOL, and allocating account data. It is the
+    # only program that can create new accounts and assign them to other programs.
+    #
+    # This module contains classes that build the low-level instruction data required
+    # to interact with the System Program.
+    #
+    # @see https://docs.solana.com/developing/runtime-facilities/programs#system-program
+    # @since 0.0.1
     module SystemProgram
       # Instruction for transferring SOL.
       #