solace 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6a955af361ac7765d33c34560a09704730c8a394cd74e0bc17196d8cf3cb8eb
-  data.tar.gz: 3c86565b3f728bdd4b116dff1abc63125d187b2cc6d8b5fcb44c8444c2d15def
+  metadata.gz: 18749af83cf5133c767914f6321a473a710caa5b5c3c613529af9547d6fcd079
+  data.tar.gz: df4de15d443d6033ea92998f7af6450a0bbeae62b5eb389d86fa6ff839ee6f16
 SHA512:
-  metadata.gz: 489042853cdc2ca68d2e35abab66c26bb1363e9ae31fa9816203b6c267d9083361a006cc73610467581ed179999317f0fefc0b09460497d1ac6f10dcb273b5c2
-  data.tar.gz: bc66a1d998abf224a30365e44ea026b034437cbdc3cf09092bf45147510bf010d8d97178047ee485f088255d86a928a58a752694aa813595e5622d6bd66d1310
+  metadata.gz: 8e0aad6a855c4721363f353deeb46ecb68429995db8366f1f475ac98b25fe4caa2616b26f584316e0511e3f8ffb8e0fe7a22d97fea92e1904c6e70834d750477
+  data.tar.gz: 47b02239af795269f2e287fe598961b265283a303ac4c37fff0f4f29b6758a60511794dd85a85809edd390580b0aee9590c49a3420c1e0b2610bed4903d05017

data/CHANGELOG

@@ -16,6 +16,32 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 ### Fixed
 ```
 
+## [0.0.8] - 2025-08-11
+  
+### Added
+1. Added `load` method to `Solace::Constants` to load constants from a YAML file. This method allows for loading constants from a YAML file (i.e. custom program addresses and mint accounts).
+2. Added `to_s` and `address` method to `Solace::Keypair` and `Solace::PublicKey` to return the public key as a Base58 string.
+3. Added `get_signature_status` and `get_signature_statuses` to `Solace::Connection`.
+4. Added `RPCClient` to `Solace::Utils` to handle HTTP requests to a Solana RPC node.
+5. Added `Errors` module to `Solace::Utils` to handle errors from the HTTP requests made to the Solana RPC node.
+
+### Changed
+1. All methods that take a `Solace::Keypair` or `Solace::Pubkey` where an address is needed now also accept a plain string address. This prevents the need of creating instances of the classes when all that is needed is the address. This is with the exception of the low-level instruction builders, which only expect the correct data and indicies with no required casting.
+2. Changed `wait_for_confirmed_signature` method to accept a `timeout`, `interval`, and `commitment` keyword arguments (breaking change on commitment).
+ 
+### Fixed
+1. Fixed `get_or_create_address` method in `Solace::Programs::AssociatedTokenAccount` to return the address of the associated token account if it already exists by checking if there is any data at the address.
+
+## [0.0.7] - 2025-08-09
+  
+### Added
+1. Added `AssociatedTokenAccountProgramCreateAccountComposer` with tests.
+
+### Changed
+1. Updated `AssociatedTokenAccount` to use `AssociatedTokenAccountProgramCreateAccountComposer` and sign the transaction in the `create_associated_token_account` method instead of the `prepare_create_associated_token_account` method.
+ 
+### Fixed
+
 ## [0.0.6] - 2025-08-07
   
 ### Added

data/lib/solace/composers/associated_token_account_program_create_account_composer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating an associated token account program create account instruction
+    #
+    # This composer resolves and orders the required accounts for a `CreateAssociatedTokenAccount` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction`).
+    #
+    # Required accounts:
+    # - **Funder**: the account that will pay for fees and rent.
+    # - **Owner**: the account that will own the new ATA.
+    # - **ATA**: the address of the new ATA.
+    # - **Mint**: the mint address of the token.
+    # - **System Program**: the system program id.
+    # - **Token Program**: the token program id.
+    # - **Associated Token Account Program**: the associated token account program id.
+    #
+    # @example Compose and build a create account instruction
+    #   composer = AssociatedTokenAccountProgramCreateAccountComposer.new(
+    #     funder: funder_address,
+    #     owner: owner_address,
+    #     ata_address: ata_address,
+    #     mint: mint_address
+    #   )
+    #
+    # @see Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+    # @since 0.0.7
+    class AssociatedTokenAccountProgramCreateAccountComposer < Base
+      # Extracts the owner address from the params
+      #
+      # @return [String] The owner address
+      def owner
+        params[:owner].to_s
+      end
+
+      # Extracts the mint address from the params
+      #
+      # @return [String] The mint address
+      def mint
+        params[:mint].to_s
+      end
+
+      # Extracts the ata_address from the params
+      #
+      # @return [String] The ata_address
+      def ata_address
+        params[:ata_address].to_s
+      end
+
+      # Extracts the funder address from the params
+      #
+      # @return [String] The funder address
+      def funder
+        params[:funder].to_s
+      end
+
+      # Extracts the system program id from the constants
+      #
+      # @return [String] The system program id
+      def system_program_id
+        Constants::SYSTEM_PROGRAM_ID.to_s
+      end
+
+      # Extracts the token program id from the constants
+      #
+      # @return [String] The token program id
+      def token_program_id
+        Constants::TOKEN_PROGRAM_ID.to_s
+      end
+
+      # Extracts the associated token account program id from the constants
+      #
+      # @return [String] The associated token account program id
+      def associated_token_account_program_id
+        Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID.to_s
+      end
+
+      # Setup accounts required for associated token account program create account instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts # rubocop:disable Metrics/AbcSize
+        account_context.add_writable_signer(funder)
+        account_context.add_writable_nonsigner(ata_address)
+        account_context.add_readonly_nonsigner(owner)
+        account_context.add_readonly_nonsigner(mint)
+        account_context.add_readonly_nonsigner(system_program_id)
+        account_context.add_readonly_nonsigner(token_program_id)
+        account_context.add_readonly_nonsigner(associated_token_account_program_id)
+      end
+
+      # Builds the instruction for the associated token account program create account instruction
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction] The instruction
+      def build_instruction(account_context)
+        Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction.build(
+          funder_index: account_context.index_of(funder),
+          owner_index: account_context.index_of(owner),
+          mint_index: account_context.index_of(mint),
+          associated_token_account_index: account_context.index_of(ata_address),
+          system_program_index: account_context.index_of(system_program_id),
+          token_program_index: account_context.index_of(token_program_id),
+          program_index: account_context.index_of(associated_token_account_program_id)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/spl_token_program_transfer_checked_composer.rb

@@ -34,14 +34,14 @@ module Solace
       #
       # @return [String] The to address
       def to
-        params[:to].is_a?(String) ? params[:to] : params[:to].address
+        params[:to].to_s
       end
 
       # Extracts the from address from the params
       #
       # @return [String] The from address
       def from
-        params[:from].is_a?(String) ? params[:from] : params[:from].address
+        params[:from].to_s
       end
 
       # Extracts the authority address from the params
@@ -50,21 +50,21 @@ module Solace
       #
       # @return [String] The authority address
       def authority
-        params[:authority].is_a?(String) ? params[:authority] : params[:authority].address
+        params[:authority].to_s
       end
 
       # Extracts the mint address from the params
       #
       # @return [String] The mint address
       def mint
-        params[:mint].is_a?(String) ? params[:mint] : params[:mint].address
+        params[:mint].to_s
       end
 
       # Returns the spl token program id
       #
       # @return [String] The spl token program id
       def spl_token_program
-        Constants::TOKEN_PROGRAM_ID
+        Constants::TOKEN_PROGRAM_ID.to_s
       end
 
       # Returns the lamports to transfer

data/lib/solace/composers/system_program_transfer_composer.rb

@@ -29,21 +29,21 @@ module Solace
       #
       # @return [String] The to address
       def to
-        params[:to].is_a?(String) ? params[:to] : params[:to].address
+        params[:to].to_s
       end
 
       # Extracts the from address from the params
       #
       # @return [String] The from address
       def from
-        params[:from].is_a?(String) ? params[:from] : params[:from].address
+        params[:from].to_s
       end
 
       # Returns the system program id
       #
       # @return [String] The system program id
       def system_program
-        Solace::Constants::SYSTEM_PROGRAM_ID
+        Solace::Constants::SYSTEM_PROGRAM_ID.to_s
       end
 
       # Returns the lamports to transfer

data/lib/solace/connection.rb

@@ -4,6 +4,9 @@ require 'net/http'
 require 'json'
 require 'uri'
 
+require 'solace/errors'
+require 'solace/utils/rpc_client'
+
 module Solace
   # Connection to a Solana RPC node
   #
@@ -23,13 +26,17 @@ module Solace
   #   # Wait for the transaction to be finalized
   #   connection.wait_for_confirmed_signature('finalized') { result['result'] }
   #
+  # @raise [
+  #   Solace::Errors::HTTPError,
+  #   Solace::Errors::ParseError,
+  #   Solace::Errors::RPCError,
+  #   Solace::Errors::ConfirmationTimeout
+  # ]
   # @since 0.0.1
-  #
-  # rubocop:disable Metrics/ClassLength
   class Connection
     # @!attribute [r] rpc_url
     #   The URL of the Solana RPC node
-    attr_reader :rpc_url
+    attr_reader :rpc_client
 
     # @!attribute [r] default_options
     #   The default options for RPC requests
@@ -40,11 +47,22 @@ module Solace
     # @param rpc_url [String] The URL of the Solana RPC node
     # @param commitment [String] The commitment level for RPC requests
     # @return [Solace::Connection] The connection object
-    def initialize(rpc_url = 'http://localhost:8899', commitment: 'confirmed')
-      @request_id = nil
-      @rpc_url = rpc_url
+    # @param [Integer] http_open_timeout The timeout for opening an HTTP connection
+    # @param [Integer] http_read_timeout The timeout for reading an HTTP response
+    def initialize(
+      rpc_url = 'http://localhost:8899',
+      commitment: 'confirmed',
+      http_open_timeout: 30,
+      http_read_timeout: 60
+    )
+      # Initialize the RPC client
+      @rpc_client = Utils::RPCClient.new(
+        rpc_url,
+        open_timeout: http_open_timeout,
+        read_timeout: http_read_timeout
+      )
 
-      # Set default options
+      # Set default options for rpc requests
       @default_options = {
         commitment: commitment,
         encoding: 'base64'
@@ -56,7 +74,12 @@ module Solace
     # @param method [String] the JSON-RPC method name
     # @param params [Array] the parameters for the RPC method
     # @return [Hash] the parsed JSON response
-    # @raise [RuntimeError] if the response is not successful
+    # @raise [
+    #   Solace::Errors::HTTPError,
+    #   Solace::Errors::ParseError,
+    #   Solace::Errors::RPCError,
+    #   Solace::Errors::ConfirmationTimeout
+    # ]
     def rpc_request(method, params = [])
       request = build_rpc_request(method, params)
       response = perform_http_request(request)
@@ -70,7 +93,7 @@ module Solace
     # @param [Hash{Symbol => Object}] options The options for the request
     # @return [String] The transaction signature of the airdrop
     def request_airdrop(pubkey, lamports, options = {})
-      rpc_request(
+      @rpc_client.rpc_request(
         'requestAirdrop',
         [
           pubkey,
@@ -84,7 +107,7 @@ module Solace
     #
     # @return [String] The latest blockhash
     def get_latest_blockhash
-      rpc_request('getLatestBlockhash')['result']['value']['blockhash']
+      @rpc_client.rpc_request('getLatestBlockhash').dig('result', 'value', 'blockhash')
     end
 
     # Get the minimum required lamports for rent exemption
@@ -92,7 +115,7 @@ module Solace
     # @param space [Integer] Number of bytes to allocate for the account
     # @return [Integer] The minimum required lamports
     def get_minimum_lamports_for_rent_exemption(space)
-      rpc_request('getMinimumBalanceForRentExemption', [space])['result']
+      @rpc_client.rpc_request('getMinimumBalanceForRentExemption', [space])['result']
     end
 
     # Get the account information from the Solana node
@@ -100,17 +123,7 @@ module Solace
     # @param pubkey [String] The public key of the account
     # @return [Object] The account information
     def get_account_info(pubkey)
-      response = rpc_request(
-        'getAccountInfo',
-        [
-          pubkey,
-          default_options
-        ]
-      )['result']
-
-      return if response.nil?
-
-      response['value']
+      @rpc_client.rpc_request('getAccountInfo', [pubkey, default_options]).dig('result', 'value')
     end
 
     # Get the balance of a specific account
@@ -118,13 +131,7 @@ module Solace
     # @param pubkey [String] The public key of the account
     # @return [Integer] The balance of the account
     def get_balance(pubkey)
-      rpc_request(
-        'getBalance',
-        [
-          pubkey,
-          default_options
-        ]
-      )['result']['value']
+      @rpc_client.rpc_request('getBalance', [pubkey, default_options]).dig('result', 'value')
     end
 
     # Get the balance of a token account
@@ -132,13 +139,7 @@ module Solace
     # @param token_account [String] The public key of the token account
     # @return [Hash] Token account balance information with amount and decimals
     def get_token_account_balance(token_account)
-      rpc_request(
-        'getTokenAccountBalance',
-        [
-          token_account,
-          default_options
-        ]
-      )['result']['value']
+      @rpc_client.rpc_request('getTokenAccountBalance', [token_account, default_options]).dig('result', 'value')
     end
 
     # Get the transaction by signature
@@ -147,27 +148,24 @@ module Solace
     # @return [Solace::Transaction] The transaction object
     # @param [Hash{Symbol => Object}] options
     def get_transaction(signature, options = { maxSupportedTransactionVersion: 0 })
-      rpc_request(
-        'getTransaction',
-        [
-          signature,
-          default_options.merge(options)
-        ]
-      )['result']
+      @rpc_client.rpc_request('getTransaction', [signature, default_options.merge(options)])['result']
     end
 
     # Get the signature status
     #
     # @param signatures [Array] The signatures of the transactions
     # @return [Object] The signature status
-    def get_signature_status(signatures)
-      rpc_request(
-        'getSignatureStatuses',
-        [
-          signatures,
-          default_options.merge({ 'searchTransactionHistory' => true })
-        ]
-      )['result']
+    def get_signature_statuses(signatures)
+      @rpc_client.rpc_request('getSignatureStatuses',
+                              [signatures, default_options.merge({ 'searchTransactionHistory' => true })])['result']
+    end
+
+    # Get the signature status
+    #
+    # @param signature [String] The signature of the transaction
+    # @return [Object] The signature status
+    def get_signature_status(signature)
+      get_signature_statuses([signature])
     end
 
     # Send a transaction to the Solana node
@@ -176,69 +174,70 @@ module Solace
     # @return [String] The signature of the transaction
     # @param [Hash{Symbol => Object}] options
     def send_transaction(transaction, options = {})
-      rpc_request(
-        'sendTransaction',
-        [
-          transaction,
-          default_options.merge(options)
-        ]
-      )
+      @rpc_client.rpc_request('sendTransaction', [transaction, default_options.merge(options)])
     end
 
-    # Wait for a confirmed signature from the transaction
+    # Wait until the yielded signature reaches the desired commitment or timeout.
     #
-    # @param commitment [String] The commitment level to wait for
-    # @return [Boolean] True if the transaction was confirmed, false otherwise
-    def wait_for_confirmed_signature(commitment = 'confirmed')
+    # @param commitment [String] One of "processed", "confirmed", "finalized"
+    # @param timeout [Numeric] seconds to wait before raising
+    # @param interval [Numeric] polling interval in seconds
+    # @yieldreturn [String, Hash] a signature string or a JSON-RPC hash with "result"
+    # @return [String] the signature when the commitment is reached
+    # @raise [ArgumentError, Errors::ConfirmationTimeout]
+    def wait_for_confirmed_signature(
+      commitment = 'confirmed',
+      timeout: 60,
+      interval: 0.1
+    )
       raise ArgumentError, 'Block required' unless block_given?
 
-      # Get the signature from the block
-      signature = yield
-
-      interval = 0.1
+      signature = extract_signature_from(yield)
+      deadline = monotonic_deadline(timeout)
 
       # Wait for confirmation
-      loop do
-        status = get_signature_status([signature]).dig('value', 0)
-
-        break if status && status['confirmationStatus'] == commitment
+      until dealine_passed?(deadline)
+        return signature if commitment_reached?(signature, commitment)
 
         sleep interval
       end
 
-      signature
+      raise Errors::ConfirmationTimeout.format(signature, commitment, timeout)
     end
 
     private
 
-    def build_rpc_request(method, params)
-      uri = URI(rpc_url)
-      req = Net::HTTP::Post.new(uri)
-      req['Accept'] = 'application/json'
-      req['Content-Type'] = 'application/json'
-      @request_id = SecureRandom.uuid
-
-      req.body = {
-        jsonrpc: '2.0',
-        id: @request_id,
-        method: method,
-        params: params
-      }.to_json
-
-      [uri, req]
+    # Confirms the commitment is reached
+    #
+    # @param signature [String] The signature of the transaction
+    # @param commitment [String] The commitment level not reached
+    # @return [Boolean] Whether the commitment is reached
+    def commitment_reached?(signature, commitment)
+      get_signature_status(signature).dig('value', 0, 'confirmationStatus') == commitment
     end
 
-    def perform_http_request((uri, req))
-      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
-        http.request(req)
-      end
+    # Extracts signature from given value
+    #
+    # @param value [String, Object] The result of the yielded block
+    # @return [String] The signature
+    def extract_signature_from(value)
+      value.is_a?(String) ? value : value['result']
     end
 
-    def handle_rpc_response(response)
-      raise "RPC error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+    # 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)
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+    end
 
-      JSON.parse(response.body)
+    # Sets a deadline given a timeout in seconds
+    #
+    # @params seconds [Integer] The seconds for the deadline
+    # @return [Integer] The deadline in seconds
+    def monotonic_deadline(seconds)
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/lib/solace/constants.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# Constants module
-#
-# Contains constants used across the library.
-#
-# @return [Module] Constants module
 module Solace
+  # Constants module
+  #
+  # Contains constants used across the library.
+  #
+  # @return [Module] Constants module
   module Constants
     # @!attribute SYSTEM_PROGRAM_ID
     #   The public key of the System Program (native SOL transfers, account creation, etc)
@@ -41,5 +41,63 @@ module Solace
     #   The public key of the Address Lookup Table Program
     #   This is the same across all Solana clusters
     ADDRESS_LOOKUP_TABLE_PROGRAM_ID = 'AddressLookupTab1e1111111111111111111111111'
+
+    # Loads the constants declared in a YAML file
+    #
+    # Developers require adding program addresses and mint accounts that will not
+    # be added directly to Solace. This method allows for loading those constants
+    # from a YAML file and extends the Constants module with them.
+    #
+    # The YAML file should be a hash of key-value pairs, where the key is the constant
+    # name and the value is the constant value.
+    #
+    # @example
+    #   # constants.yml
+    #   devnet:
+    #     my_program_id: some_devnet_program_id
+    #     squads_program_id: some_devnet_program_id
+    #     usdc_mint_account: some_devnet_program_id
+    #     usdt_mint_account: some_devnet_program_id
+    #
+    #   mainnet:
+    #     my_program_id: some_mainnet_program_id
+    #     squads_program_id: some_mainnet_program_id
+    #     usdc_mint_account: some_mainnet_program_id
+    #     usdt_mint_account: some_mainnet_program_id
+    #
+    # @example
+    #   Solace::Constants.load(
+    #     path: '/home/user/my-project/config/constants.yml',
+    #     namespace: 'devnet',
+    #     protect_overrides: false
+    #   )
+    #
+    #   Solace::Constants::MY_PROGRAM_ID
+    #   Solace::Constants::SQUADS_PROGRAM_ID
+    #   Solace::Constants::USDC_MINT_ACCOUNT
+    #   Solace::Constants::USDT_MINT_ACCOUNT
+    #
+    # @param path [String] The path to the YAML file
+    # @param namespace [String] The namespace to load the constants from
+    # @param protect_overrides [Boolean] Whether to protect constants that are already defined
+    # @return [void]
+    # @raise [ArgumentError] If protect_overrides is on and a constant is already defined
+    def self.load(
+      path:,
+      namespace: 'default',
+      protect_overrides: true
+    )
+      content = YAML.load_file(path)
+
+      content[namespace].each do |key, value|
+        if const_defined?(key.upcase)
+          raise ArgumentError, "Constant #{key} is already defined" if protect_overrides
+
+          remove_const(key.upcase)
+        end
+
+        const_set(key.upcase, value)
+      end
+    end
   end
 end

data/lib/solace/errors/confirmation_timeout.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Solace
+  module Errors
+    # Waiting for confirmation exceeded timeout
+    class ConfirmationTimeout < StandardError
+      attr_reader :signature, :commitment, :timeout
+
+      # @param [String] message The error message
+      # @param [String] signature The signature of the transaction
+      # @param [String] commitment The commitment level not reached
+      # @param [Integer] timeout The time out reached
+      def initialize(message, signature:, commitment:, timeout:)
+        super(message)
+        @signature = signature
+        @commitment = commitment
+        @timeout = timeout
+      end
+
+      # 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
+      # @return [Solace::Errors::ConfirmationTimeout] The formatted error
+      def self.format(signature, commitment, timeout)
+        new(
+          "Timed out waiting for signature #{signature} at commitment=#{commitment} after #{timeout}s",
+          signature: signature,
+          commitment: commitment,
+          timeout: timeout
+        )
+      end
+    end
+  end
+end

data/lib/solace/errors/http_error.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Solace
+  module Errors
+    # Non-2xx HTTP or low-level network issues
+    class HTTPError < StandardError
+      attr_reader :code, :body
+
+      # @param [String] message The error message
+      # @param [Integer] code The HTTP status code
+      # @param [String] body The HTTP response body
+      def initialize(message, code:, body: nil)
+        super(message)
+        @code = code
+        @body = body
+      end
+
+      # Formats a response to an error
+      #
+      # @param response [Net::HTTPResponse] The HTTP response
+      # @return [Solace::Errors::HTTPError] The formatted error
+      def self.format_response(response)
+        new("HTTP error: #{response.message}", code: response.code.to_i, body: response.body)
+      end
+
+      # Formats transport errors
+      #
+      # @param error [SocketError, IOError] The transport error
+      # @return [Solace::Errors::HTTPError] The formatted error
+      def self.format_transport_error(error)
+        new("HTTP transport error: #{error.message}", code: 0)
+      end
+
+      # Formats timeout errors
+      #
+      # @param error [Net::OpenTimeout, Net::ReadTimeout] The timeout error
+      # @return [Solace::Errors::HTTPError] The formatted error
+      def self.format_timeout_error(error)
+        new("HTTP timeout: #{error.class}", code: 408)
+      end
+    end
+  end
+end

data/lib/solace/errors/parse_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Solace
+  module Errors
+    # JSON parsing failed
+    class ParseError < StandardError
+      attr_reader :body
+
+      # @param [String] message The error message
+      # @param [Object] body The response body
+      def initialize(message, body:)
+        super(message)
+        @body = body
+      end
+
+      # Formats a response to an error
+      #
+      # @param error [JSON::ParserError] The JSON-RPC error
+      # @param [Object] response The response from the RPC
+      # @return [Solace::Errors::ParseError] The formatted error
+      def self.format_response(error, response)
+        new("Invalid JSON from RPC: #{error.message}", body: response.body)
+      end
+    end
+  end
+end

data/lib/solace/errors/rpc_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Solace
+  module Errors
+    # JSON-RPC returned an "error" object
+    class RPCError < StandardError
+      attr_reader :rpc_code, :rpc_message, :rpc_data
+
+      # @param [String] message The error message
+      # @param [Integer] rpc_code The JSON-RPC error code
+      # @param [String] rpc_message The JSON-RPC error message
+      # @param [Object] rpc_data The JSON-RPC error data
+      def initialize(message, rpc_code:, rpc_message:, rpc_data: nil)
+        super(message)
+        @rpc_code = rpc_code
+        @rpc_message = rpc_message
+        @rpc_data = rpc_data
+      end
+
+      # Formats a response to an error
+      #
+      # @param response [Hash] The JSON-RPC response
+      # @return [Solace::Errors::RPCError] The formatted error
+      def self.format_response(response)
+        new(
+          "RPC error #{response['error']['code']}: #{response['error']['message']}",
+          rpc_data: response['error']['data'],
+          rpc_code: response['error']['code'],
+          rpc_message: response['error']['message']
+        )
+      end
+
+      # @return [Hash] The error as a hash
+      def to_h = { code: rpc_code, message: rpc_message, data: rpc_data }
+    end
+  end
+end

data/lib/solace/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Solace
+  # Error handling module
+  #
+  # This module provides error classes for handling different types of errors that may occur during
+  # Solana RPC requests and processing transactions.
+  #
+  # @since 0.0.8
+  module Errors
+    # JSON-RPC Errors
+    require 'solace/errors/rpc_error'
+    require 'solace/errors/http_error'
+    require 'solace/errors/parse_error'
+    require 'solace/errors/confirmation_timeout'
+  end
+end

data/lib/solace/keypair.rb

@@ -132,13 +132,31 @@ module Solace
     # Returns the public key address as a Base58 string
     #
     # @example
-    #   pubkey_str = instance.address
+    #   pubkey_str = instance.to_base58
     #
     # @return [String] Base58 encoded public key
-    def address
+    def to_base58
       public_key.to_base58
     end
 
+    # Returns the public key address as a Base58 string
+    #
+    # @example
+    #   pubkey_str = instance.to_s
+    #
+    # @return [String] Base58 encoded public key
+    # @since 0.0.8
+    alias to_s to_base58
+
+    # Returns the public key address as a Base58 string
+    #
+    # @example
+    #   pubkey_str = instance.to_base58
+    #
+    # @return [String] Base58 encoded public key
+    # @since 0.0.8
+    alias address to_base58
+
     # Signs a message (string or binary)
     #
     # @example

data/lib/solace/programs/associated_token_account.rb

@@ -33,9 +33,9 @@ module Solace
         def get_address(owner:, mint:)
           Solace::Utils::PDA.find_program_address(
             [
-              owner.address,
+              owner.to_s,
               Solace::Constants::TOKEN_PROGRAM_ID,
-              mint.address
+              mint.to_s
             ],
             Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
           )
@@ -51,7 +51,7 @@ module Solace
 
       # Alias method for get_address
       #
-      # @option options [Hash] A hash of options for the get_address class method
+      # @param options [Hash] A hash of options for the get_address class method
       # @return [Array<String, Integer>] The address of the associated token account and the bump seed
       def get_address(**options)
         self.class.get_address(**options)
@@ -67,15 +67,15 @@ module Solace
       def get_or_create_address(payer:, owner:, mint:, commitment: 'confirmed')
         ata_address, _bump = get_address(owner: owner, mint: mint)
 
-        account_info = @connection.get_account_info(ata_address)
+        account_balance = @connection.get_account_info(ata_address)
 
-        return ata_address if account_info
+        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']
 
-        @connection.wait_for_confirmed_signature(commitment) { response['result'] }
+        @connection.wait_for_confirmed_signature(commitment) { response }
 
         ata_address
       end
@@ -87,6 +87,8 @@ module Solace
       def create_associated_token_account(**options)
         tx = prepare_create_associated_token_account(**options)
 
+        tx.sign(options[:payer])
+
         @connection.send_transaction(tx.serialize)
       end
 
@@ -97,7 +99,6 @@ module Solace
       # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
       # @return [Solace::Transaction] The signed transaction.
       #
-      # rubocop:disable Metrics/MethodLength
       def prepare_create_associated_token_account(
         payer:,
         owner:,
@@ -105,39 +106,21 @@ module Solace
       )
         ata_address, = get_address(owner: owner, mint: mint)
 
-        accounts = [
-          payer.address,
-          ata_address,
-          owner.address,
-          mint.address,
-          Solace::Constants::SYSTEM_PROGRAM_ID,
-          Solace::Constants::TOKEN_PROGRAM_ID,
-          Solace::Constants::ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
-        ]
-
-        instruction = Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction.build(
-          funder_index: 0,
-          associated_token_account_index: 1,
-          owner_index: 2,
-          mint_index: 3,
-          system_program_index: 4,
-          token_program_index: 5,
-          program_index: 6
-        )
-
-        message = Solace::Message.new(
-          header: [1, 0, 4],
-          accounts: accounts,
-          recent_blockhash: @connection.get_latest_blockhash,
-          instructions: [instruction]
-        )
-
-        tx = Solace::Transaction.new(message: message)
-        tx.sign(payer)
-
-        tx
+        TransactionComposer.new(connection: connection).try do |tx_composer|
+          tx_composer.set_fee_payer(payer)
+
+          tx_composer.add_instruction(
+            Solace::Composers::AssociatedTokenAccountProgramCreateAccountComposer.new(
+              mint: mint,
+              owner: owner,
+              funder: payer,
+              ata_address: ata_address
+            )
+          )
+
+          tx_composer.compose_transaction
+        end
       end
-      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/solace/programs/spl_token.rb

@@ -63,8 +63,8 @@ module Solace
         mint_keypair: Solace::Keypair.generate
       )
         accounts = [
-          payer.address,
-          mint_keypair.address,
+          payer.to_s,
+          mint_keypair.to_s,
           Solace::Constants::SYSVAR_RENT_PROGRAM_ID,
           Solace::Constants::TOKEN_PROGRAM_ID,
           Solace::Constants::SYSTEM_PROGRAM_ID
@@ -81,15 +81,15 @@ module Solace
           owner: program_id
         )
 
-        freeze_authority_address = freeze_authority.respond_to?(:address) ? freeze_authority.address : nil
+        freeze_authority = freeze_authority.to_s unless freeze_authority.nil?
 
         initialize_mint_ix = Solace::Instructions::SplToken::InitializeMintInstruction.build(
           mint_account_index: 1,
           rent_sysvar_index: 2,
           program_index: 3,
           decimals: decimals,
-          mint_authority: mint_authority.address,
-          freeze_authority: freeze_authority_address
+          mint_authority: mint_authority.to_s,
+          freeze_authority: freeze_authority
         )
 
         message = Message.new(
@@ -134,11 +134,11 @@ module Solace
         mint_authority:
       )
         accounts = [
-          payer.address,
-          mint_authority.address,
-          mint.address,
-          destination,
-          Solace::Constants::TOKEN_PROGRAM_ID
+          payer.to_s,
+          mint_authority.to_s,
+          mint.to_s,
+          destination.to_s,
+          Solace::Constants::TOKEN_PROGRAM_ID.to_s
         ]
 
         ix = Solace::Instructions::SplToken::MintToInstruction.build(
@@ -191,11 +191,11 @@ module Solace
         owner:
       )
         accounts = [
-          payer.address,
-          owner.address,
-          source,
-          destination,
-          Solace::Constants::TOKEN_PROGRAM_ID
+          payer.to_s,
+          owner.to_s,
+          source.to_s,
+          destination.to_s,
+          Solace::Constants::TOKEN_PROGRAM_ID.to_s
         ]
 
         ix = Solace::Instructions::SplToken::TransferInstruction.build(

data/lib/solace/public_key.rb

@@ -51,6 +51,7 @@ module Solace
     #   pubkey_str = instance.to_base58
     #
     # @return [String]
+    # @since 0.0.1
     def to_base58
       Solace::Utils::Codecs.bytes_to_base58(@bytes)
     end
@@ -61,9 +62,8 @@ module Solace
     #   pubkey_str = instance.to_s
     #
     # @return [String]
-    def to_s
-      to_base58
-    end
+    # @since 0.0.8
+    alias to_s to_base58
 
     # Return the address of the public key
     #
@@ -71,9 +71,8 @@ module Solace
     #   pubkey_str = instance.address
     #
     # @return [String]
-    def address
-      to_base58
-    end
+    # @since 0.0.8
+    alias address to_base58
 
     # Compare two public keys for equality
     #
@@ -82,6 +81,7 @@ module Solace
     #
     # @param other [PublicKey]
     # @return [Boolean]
+    # @since 0.0.1
     def ==(other)
       other.is_a?(Solace::PublicKey) && other.bytes == bytes
     end
@@ -92,6 +92,7 @@ module Solace
     #   pubkey_bytes = instance.to_bytes
     #
     # @return [Array<Integer>]
+    # @since 0.0.1
     def to_bytes
       @bytes.dup
     end
@@ -103,7 +104,10 @@ module Solace
       #   pubkey = Solace::PublicKey.from_address(address)
       #
       # @param address [String] The base58 address of the public key
-      # @return [PublicKey]
+      # @return [PublicKey] The public key instance
+      # @raise [ArgumentError] If the address is not a valid base58 string
+      #
+      # @since 0.0.6
       def from_address(address)
         new(Solace::Utils::Codecs.base58_to_bytes(address))
       end

data/lib/solace/transaction_composer.rb

@@ -38,7 +38,7 @@ module Solace
   #   # Sign the transaction with all required signers
   #   tx.sign(*required_signers)
   #
-  # @since 0.0.1
+  # @since 0.0.6
   class TransactionComposer
     # @!attribute connection
     #   The connection to the Solana cluster
@@ -76,7 +76,7 @@ module Solace
     # @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)
+      context.set_fee_payer(pubkey.to_s)
       self
     end
 

data/lib/solace/utils/rpc_client.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+require 'solace/errors'
+
+module Solace
+  module Utils
+    # RPCClient provides Net::HTTP based HTTP client for sending HTTP
+    # requests to a Solana RPC node and parsing responses.
+    #
+    # @since 0.0.8
+    class RPCClient
+      # @!attribute [r] url
+      #   The URL for the HTTP request
+      attr_reader :url
+
+      # @!attribute [r] open_timeout
+      #   The timeout for opening an HTTP connection
+      attr_reader :open_timeout
+
+      # @!attribute [r] read_timeout
+      #   The timeout for reading an HTTP response
+      attr_reader :read_timeout
+
+      # Initialize the connection with a default or custom RPC URL
+      #
+      # @param url [String] The URL of the Solana RPC node
+      # @param open_timeout [Integer] The timeout for opening an HTTP connection
+      # @param read_timeout [Integer] The timeout for reading an HTTP response
+      def initialize(
+        url,
+        open_timeout:,
+        read_timeout:
+      )
+        @url = url
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      # Sends a JSON-RPC request to the configured Solana RPC server.
+      #
+      # @param method [String] the JSON-RPC method name
+      # @param params [Array] the parameters for the RPC method
+      # @return [Hash] the parsed JSON response
+      # @raise [
+      #   Solace::Errors::HTTPError,
+      #   Solace::Errors::ParseError,
+      #   Solace::Errors::RPCError,
+      #   Solace::Errors::ConfirmationTimeout
+      # ]
+      def rpc_request(method, params = [])
+        request = build_rpc_request(method, params)
+        response = perform_http_request(*request)
+        handle_rpc_response(response)
+      end
+
+      private
+
+      # Builds a JSON-RPC request
+      #
+      # @param method [String] the JSON-RPC method name
+      # @param params [Array] the parameters for the RPC method
+      # @return [Array] the URI and request object
+      def build_rpc_request(method, params)
+        uri = URI(url)
+
+        req = Net::HTTP::Post.new(uri)
+        req['Accept'] = 'application/json'
+        req['Content-Type'] = 'application/json'
+        req.body = build_request_body(method, params)
+
+        [uri, req]
+      end
+
+      # Builds request body
+      #
+      # @param method [String] the JSON-RPC method name
+      # @param params [Array] the parameters for the RPC method
+      # @return [String] the request body
+      def build_request_body(method, params)
+        {
+          jsonrpc: '2.0',
+          id: SecureRandom.uuid,
+          method: method,
+          params: params
+        }.to_json
+      end
+
+      # Performs an HTTP request to the configured Solana RPC server.
+      #
+      # @param uri [URI] the URI for the HTTP request
+      # @param req [Net::HTTP::Post] the request object
+      # @return [Net::HTTPResponse] the HTTP response
+      # @raise [Solace::Errors::HTTPError]
+      def perform_http_request(uri, req)
+        Net::HTTP.start(
+          uri.hostname,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: open_timeout,
+          read_timeout: read_timeout
+        ) do |http|
+          http.request(req)
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise Errors::HTTPError.format_timeout_error(e)
+      rescue SocketError, IOError => e
+        raise Errors::HTTPError.format_transport_error(e)
+      end
+
+      # Handles the response from the HTTP request
+      #
+      # @param response [Net::HTTPResponse] The HTTP response
+      # @return [Hash] The parsed JSON response
+      # @raise [Solace::Errors::HTTPError]
+      # @raise [Solace::Errors::ParseError]
+      # @raise [Solace::Errors::RPCError]
+      def handle_rpc_response(response)
+        raise Errors::HTTPError.format_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+        json = JSON.parse(response.body)
+
+        raise Errors::RPCError.format_response(json) if json['error']
+
+        json
+      rescue JSON::ParserError => e
+        raise Errors::ParseError.format_response(e, response)
+      end
+    end
+  end
+end

data/lib/solace/version.rb

@@ -2,5 +2,5 @@
 
 # Solace::VERSION is the version of the Solace gem
 module Solace
-  VERSION = '0.0.6'
+  VERSION = '0.0.8'
 end

data/lib/solace.rb

@@ -4,6 +4,7 @@
 require_relative 'solace/version'
 
 # 🛠️ Helpers
+require_relative 'solace/errors'
 require_relative 'solace/constants'
 require_relative 'solace/connection'
 require_relative 'solace/utils/codecs'
@@ -25,9 +26,13 @@ require_relative 'solace/instruction'
 require_relative 'solace/address_lookup_table'
 require_relative 'solace/transaction_composer'
 
-# 📦 Composers (Builders)
+# Base Classes (Abstract classes)
+require_relative 'solace/programs/base'
+require_relative 'solace/composers/base'
+
+# 📦 Composers
 #
-# Glob require all instructions
+# Glob require all composers
 Dir[File.join(__dir__, 'solace/composers', '**', '*.rb')].each { |file| require file }
 
 # 📦 Instructions (Builders)
@@ -36,6 +41,5 @@ Dir[File.join(__dir__, 'solace/composers', '**', '*.rb')].each { |file| require
 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -93,12 +93,18 @@ files:
 - README.md
 - lib/solace.rb
 - lib/solace/address_lookup_table.rb
+- lib/solace/composers/associated_token_account_program_create_account_composer.rb
 - lib/solace/composers/base.rb
 - lib/solace/composers/spl_token_program_transfer_checked_composer.rb
 - lib/solace/composers/system_program_transfer_composer.rb
 - lib/solace/concerns/binary_serializable.rb
 - lib/solace/connection.rb
 - lib/solace/constants.rb
+- lib/solace/errors.rb
+- lib/solace/errors/confirmation_timeout.rb
+- lib/solace/errors/http_error.rb
+- lib/solace/errors/parse_error.rb
+- lib/solace/errors/rpc_error.rb
 - lib/solace/instruction.rb
 - lib/solace/instructions/associated_token_account/create_associated_token_account_instruction.rb
 - lib/solace/instructions/spl_token/initialize_account_instruction.rb
@@ -133,6 +139,7 @@ files:
 - lib/solace/utils/libcurve25519_dalek-macos/libcurve25519_dalek.dylib
 - lib/solace/utils/libcurve25519_dalek-windows/curve25519_dalek.dll
 - lib/solace/utils/pda.rb
+- lib/solace/utils/rpc_client.rb
 - lib/solace/version.rb
 homepage: https://github.com/sebscholl/solace
 licenses: