solace 0.0.10 → 0.1.0

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
@@ -69,6 +75,27 @@ module Solace
       }
     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 +124,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 +170,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 +194,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 +239,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 +254,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 +289,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 +319,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.
       #

data/lib/solace/programs/associated_token_account.rb

@@ -24,20 +24,21 @@ module Solace
     #   # Create an associated token account
     #   result = program.create_associated_token_account(
     #     payer: payer,
+    #     funder: funder,
     #     owner: owner,
     #     mint: mint
     #   )
     #
     #   # Wait for the transaction to be finalized
-    #   @connection.wait_for_confirmed_signature('finalized') { result['result'] }
+    #   connection.wait_for_confirmed_signature('finalized') { result['result'] }
     #
     # @since 0.0.2
     class AssociatedTokenAccount < Base
       class << self
         # Gets the address of an associated token account.
         #
-        # @param owner [Solace::Keypair, Solace::PublicKey] The keypair of the owner.
-        # @param mint [Solace::Keypair, Solace::PublicKey] The keypair of the mint.
+        # @param owner [Keypair, PublicKey] The keypair of the owner.
+        # @param mint [Keypair, PublicKey] The keypair of the mint.
         # @return [String] The address of the associated token account.
         def get_address(owner:, mint:)
           Solace::Utils::PDA.find_program_address(
@@ -68,48 +69,76 @@ module Solace
 
       # Gets the address of an associated token account, creating it if it doesn't exist.
       #
-      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
-      # @param owner [Solace::Keypair, Solace::PublicKey] The keypair of the owner.
-      # @param mint [Solace::Keypair, Solace::PublicKey] The keypair of the mint.
-      # @param commitment [String] The commitment level for the get_account_info call.
+      # @param payer [Keypair] The keypair that will pay for fees and rent.
+      # @param funder [Keypair] The keypair that will pay for rent of the new associated token account.
+      # @param owner [Keypair, PublicKey] The keypair of the owner.
+      # @param mint [Keypair, PublicKey] The keypair of the mint.
       # @return [String] The address of the associated token account
-      def get_or_create_address(payer:, owner:, mint:, commitment: 'confirmed')
-        ata_address, _bump = get_address(owner: owner, mint: mint)
+      def get_or_create_address(
+        payer:,
+        funder:,
+        owner:,
+        mint:
+      )
+        ata_address, = get_address(owner: owner, mint: mint)
 
-        account_balance = @connection.get_account_info(ata_address)
+        account_balance = connection.get_account_info(ata_address)
 
         return ata_address unless account_balance.nil?
 
-        response = create_associated_token_account(payer: payer, owner: owner, mint: mint)
-
-        raise 'Failed to create associated token account' unless response['result']
+        tx = create_associated_token_account(
+          payer: payer,
+          funder: funder,
+          owner: owner,
+          mint: mint
+        )
 
-        @connection.wait_for_confirmed_signature(commitment) { response }
+        connection.wait_for_confirmed_signature { tx.signature }
 
         ata_address
       end
 
       # Creates a new associated token account.
       #
-      # @param options [Hash] Options for calling the prepare_create_associated_token_account method.
-      # @return [String] The signature of the transaction.
-      def create_associated_token_account(**options)
-        tx = prepare_create_associated_token_account(**options)
+      # @param payer [#to_s, Keypair] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction before sending it.
+      # @param execute [Boolean] Whether to send the transaction to the cluster.
+      # @param composer_opts [Hash] Options for calling the compose_create_associated_token_account method.
+      # @return [Transaction] The created or sent transaction.
+      def create_associated_token_account(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_create_associated_token_account(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:funder]
+          )
 
-        tx.sign(options[:payer])
+          connection.send_transaction(tx.serialize) if execute
+        end
 
-        @connection.send_transaction(tx.serialize)
+        tx
       end
 
       # Prepares a new associated token account and returns the signed transaction.
       #
-      # @param owner [Solace::Keypair, Solace::PublicKey] The keypair of the owner.
-      # @param mint [Solace::Keypair, Solace::PublicKey] The keypair of the mint.
-      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
-      # @return [Solace::Transaction] The signed transaction.
-      #
-      def prepare_create_associated_token_account(
-        payer:,
+      # @param owner [#to_s, PublicKey] The keypair of the owner.
+      # @param mint [#to_s, PublicKey] The keypair of the mint.
+      # @param funder [#to_s, PublicKey] The keypair that will pay for rent of the new associated token account.
+      # @return [Transaction] The signed transaction.
+      def compose_create_associated_token_account(
+        funder:,
         owner:,
         mint:
       )
@@ -118,15 +147,13 @@ module Solace
         ix = Solace::Composers::AssociatedTokenAccountProgramCreateAccountComposer.new(
           mint: mint,
           owner: owner,
-          funder: payer,
+          funder: funder,
           ata_address: ata_address
         )
 
         TransactionComposer
           .new(connection: connection)
-          .set_fee_payer(payer)
           .add_instruction(ix)
-          .compose_transaction
       end
     end
   end

data/lib/solace/programs/base.rb

@@ -3,6 +3,29 @@
 # lib/solace/programs/base.rb
 
 module Solace
+  # The Programs module contains high-level interfaces to Solana on-chain programs.
+  #
+  # Programs in this module provide convenient methods for interacting with
+  # on-chain programs without needing to manually construct instructions or
+  # manage account ordering. They serve as a bridge between the low-level
+  # instruction builders and high-level application code.
+  #
+  # Each program class corresponds to a specific on-chain program:
+  # - {Solace::Programs::SplToken} - SPL Token Program
+  # - {Solace::Programs::AssociatedTokenAccount} - Associated Token Account Program
+  #
+  # @example Using a program interface
+  #   token_program = Solace::Programs::SplToken.new(connection)
+  #   token_program.transfer(
+  #     to:,
+  #     from:,
+  #     owner:,
+  #     amount:
+  #   )
+  #
+  # @see Solace::Programs::SplToken
+  # @see Solace::Programs::AssociatedTokenAccount
+  # @since 0.0.2
   module Programs
     # Base class for program-specific clients.
     #