solace 0.0.2 → 0.0.5

data/lib/solace/composers/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # A Base class for all composers
+    #
+    # @since 0.0.3
+    class Base
+      # @!attribute  params
+      #   The params for the composer
+      #
+      # @return [Hash] The parameters passed to the composer
+      attr_reader :params
+
+      # @!attribute  account_context
+      #   The account_context for the composer
+      #
+      # @return [Utils::AccountContext] The AccountContext instance for the composer
+      attr_reader :account_context
+
+      # Initialize the composer
+      #
+      # @param params [Hash] Parameters to pass to the composer constructor
+      def initialize(params)
+        @params = params
+        @account_context = Utils::AccountContext.new
+        setup_accounts
+      end
+
+      # Setup accounts required for this instruction
+      #
+      # @return [void]
+      def setup_accounts
+        raise NotImplementedError, 'Subclasses must implement setup_accounts method'
+      end
+
+      # Build instruction with resolved account indices
+      #
+      # @return [void]
+      def build_instruction(indices)
+        raise NotImplementedError, 'Subclasses must implement build_instruction method'
+      end
+    end
+  end
+end

data/lib/solace/composers/spl_token_program_transfer_checked_composer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a SPL Token Program `TransferChecked` instruction.
+    #
+    # This composer resolves and orders the required accounts for a `TransferChecked` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::SplToken::TransferCheckedInstruction`).
+    #
+    # It is used for transferring SPL tokens with decimal precision and validation checks.
+    #
+    # Required accounts:
+    # - **From**: source token account (writable, non-signer)
+    # - **To**: destination token account (writable, non-signer)
+    # - **Mint**: mint address (readonly, non-signer)
+    # - **Authority**: token owner (writable, signer)
+    # - **Program**: SPL Token program (readonly, non-signer)
+    #
+    # @example Compose and build a transfer_checked instruction
+    #   composer = SplTokenProgramTransferCheckedComposer.new(
+    #     from: from_address,
+    #     to: to_address,
+    #     mint: mint_address,
+    #     authority: authority_pubkey,
+    #     amount: 1_000_000,
+    #     decimals: 6
+    #   )
+    #
+    # @see Instructions::SplToken::TransferCheckedInstruction
+    # @since 0.0.3
+    class SplTokenProgramTransferCheckedComposer < Base
+      # Extracts the to address from the params
+      #
+      # @return [String] The to address
+      def to
+        params[:to].is_a?(String) ? params[:to] : params[:to].address
+      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
+      end
+
+      # Extracts the authority address from the params
+      #
+      # The authority is the owner of the token account
+      #
+      # @return [String] The authority address
+      def authority
+        params[:authority].is_a?(String) ? params[:authority] : params[:authority].address
+      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
+      end
+
+      # Returns the spl token program id
+      #
+      # @return [String] The spl token program id
+      def spl_token_program
+        Constants::TOKEN_PROGRAM_ID
+      end
+
+      # Returns the lamports to transfer
+      #
+      # @return [Integer] The lamports to transfer
+      def amount
+        params[:amount]
+      end
+
+      # Returns the decimals for the mint of the token
+      #
+      # @return [Integer] The decimals for the mint
+      def decimals
+        params[:decimals]
+      end
+
+      # Setup accounts required for transfer instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_signer(authority)
+        account_context.add_writable_nonsigner(to)
+        account_context.add_writable_nonsigner(from)
+        account_context.add_readonly_nonsigner(mint)
+        account_context.add_readonly_nonsigner(spl_token_program)
+      end
+
+      # Build instruction with resolved account indices
+      #
+      # @param account_context [Utils::AccountContext] The account context
+      # @return [Solace::Instruction]
+      def build_instruction(account_context)
+        Instructions::SplToken::TransferCheckedInstruction.build(
+          amount: amount,
+          decimals: decimals,
+          to_index: account_context.index_of(to),
+          from_index: account_context.index_of(from),
+          mint_index: account_context.index_of(mint),
+          authority_index: account_context.index_of(authority),
+          program_index: account_context.index_of(spl_token_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/system_program_transfer_composer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a system program transfer instruction.
+    #
+    # This composer resolves and orders the required accounts for a `Transfer` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::SystemProgram::TransferInstruction`).
+    #
+    # It is used for transferring lamports from one account to another.
+    #
+    # Required accounts:
+    # - **From**: source account (writable, signer)
+    # - **To**: destination account (writable, non-signer)
+    # - **Program**: System program (readonly, non-signer)
+    #
+    # @example Compose and build a transfer instruction
+    #   composer = SystemProgramTransferComposer.new(
+    #     from: from_address,
+    #     to: to_address,
+    #     lamports: 1_000_000
+    #   )
+    #
+    # @see Instructions::SystemProgram::TransferInstruction
+    # @since 0.0.3
+    class SystemProgramTransferComposer < Base
+      # Extracts the to address from the params
+      #
+      # @return [String] The to address
+      def to
+        params[:to].is_a?(String) ? params[:to] : params[:to].address
+      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
+      end
+
+      # Returns the system program id
+      #
+      # @return [String] The system program id
+      def system_program
+        Solace::Constants::SYSTEM_PROGRAM_ID
+      end
+
+      # Returns the lamports to transfer
+      #
+      # @return [Integer] The lamports to transfer
+      def lamports
+        params[:lamports]
+      end
+
+      # Setup accounts required for transfer instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_signer(from)
+        account_context.add_writable_nonsigner(to)
+        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)
+        Instructions::SystemProgram::TransferInstruction.build(
+          lamports: lamports,
+          to_index: account_context.index_of(to),
+          from_index: account_context.index_of(from),
+          program_index: account_context.index_of(system_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/concerns/binary_serializable.rb

@@ -2,7 +2,24 @@
 
 module Solace
   module Concerns
+    # Adds binary serialization support to a class
+    #
+    # Transactions, Messages, Instructions, and AddressLookupTables are all binary serializable.
+    # These classes use this concern to add binary serialization support.
+    #
+    # @see Solace::Transaction
+    # @see Solace::Message
+    # @see Solace::Instruction
+    # @see Solace::AddressLookupTable
+    # @since 0.0.1
     module BinarySerializable
+      # Include the module
+      #
+      # @param base [Class] The base class to include the module into
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
       # Returns the binary decoded from the serialized string
       #
       # Expects the class to have a `serialize` method that returns a base64 string.
@@ -25,6 +42,28 @@ module Solace
       def to_bytes
         to_binary.bytes
       end
+
+      # Serializes the record to a binary format
+      #
+      # @return [String] The serialized record (binary)
+      def serialize
+        self.class::SERIALIZER.new(self).call
+      rescue NameError => e
+        raise "SERIALIZER must be defined: #{e.message}"
+      end
+
+      # Class methods for binary serializable
+      module ClassMethods
+        # Parse record from bytestream
+        #
+        # @param stream [IO, StringIO] The input to read bytes from.
+        # @return [Solace::Instruction] Parsed instruction instance
+        def deserialize(stream)
+          self::DESERIALIZER.new(stream).call
+        rescue NameError => e
+          raise "DESERIALIZER must be defined: #{e.message}"
+        end
+      end
     end
   end
 end

data/lib/solace/connection.rb

@@ -5,62 +5,69 @@ require 'json'
 require 'uri'
 
 module Solace
+  # Connection to a Solana RPC node
+  #
+  # This class provides methods for sending JSON-RPC requests to a Solana RPC node and parsing responses.
+  # It includes methods for sending transactions, getting account information, and getting blockhashes.
+  #
+  # @example
+  #   # Initialize the connection
+  #   connection = Solace::Connection.new('http://localhost:8899', commitment: 'confirmed')
+  #
+  #   # Get account information
+  #   connection.get_account_info(account.address)
+  #
+  #   # Request an airdrop
+  #   result = connection.request_airdrop(account.address, 1000000)
+  #
+  #   # Wait for the transaction to be finalized
+  #   connection.wait_for_confirmed_signature('finalized') { result['result'] }
+  #
+  # @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
 
-    # !const default options
-    DEFAULT_OPTIONS = {
-      encoding: 'base64',
-      commitment: 'confirmed'
-    }.freeze
+    # @!attribute [r] default_options
+    #   The default options for RPC requests
+    attr_reader :default_options
 
     # Initialize the connection with a default or custom RPC URL
     #
     # @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')
-      @rpc_url = rpc_url
+    def initialize(rpc_url = 'http://localhost:8899', commitment: 'confirmed')
       @request_id = nil
+      @rpc_url = rpc_url
+
+      # Set default options
+      @default_options = {
+        commitment: commitment,
+        encoding: 'base64'
+      }
     end
 
-    # Make an RPC request to the Solana node
+    # Sends a JSON-RPC request to the configured Solana RPC server.
     #
-    # @param method [String] The RPC method to call
-    # @param params [Array] Parameters for the RPC method
-    # @return [Object] Result of the RPC call
+    # @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
     def 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
-
-      res = Net::HTTP.start(
-        uri.hostname,
-        uri.port,
-        use_ssl: uri.scheme == 'https'
-      ) do |http|
-        http.request(req)
-      end
-
-      raise "RPC error: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
-
-      JSON.parse(res.body)
+      request = build_rpc_request(method, params)
+      response = perform_http_request(request)
+      handle_rpc_response(response)
     end
 
     # Request an airdrop of lamports to a given address
     #
     # @param pubkey [String] The public key of the account to receive the airdrop
     # @param lamports [Integer] Amount of lamports to airdrop
+    # @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(
@@ -68,7 +75,7 @@ module Solace
         [
           pubkey,
           lamports,
-          DEFAULT_OPTIONS.merge(options)
+          default_options.merge(options)
         ]
       )
     end
@@ -97,7 +104,7 @@ module Solace
         'getAccountInfo',
         [
           pubkey,
-          DEFAULT_OPTIONS
+          default_options
         ]
       )['result']
 
@@ -115,7 +122,21 @@ module Solace
         'getBalance',
         [
           pubkey,
-          DEFAULT_OPTIONS
+          default_options
+        ]
+      )['result']['value']
+    end
+
+    # Get the balance of a token account
+    #
+    # @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']
     end
@@ -124,12 +145,13 @@ module Solace
     #
     # @param signature [String] The signature of the transaction
     # @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)
+          default_options.merge(options)
         ]
       )['result']
     end
@@ -143,7 +165,7 @@ module Solace
         'getSignatureStatuses',
         [
           signatures,
-          DEFAULT_OPTIONS.merge({ 'searchTransactionHistory' => true })
+          default_options.merge({ 'searchTransactionHistory' => true })
         ]
       )['result']
     end
@@ -152,12 +174,13 @@ module Solace
     #
     # @param transaction [Solace::Transaction] The transaction to send
     # @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)
+          default_options.merge(options)
         ]
       )
     end
@@ -172,16 +195,50 @@ module Solace
       # Get the signature from the block
       signature = yield
 
+      interval = 0.1
+
       # Wait for confirmation
       loop do
         status = get_signature_status([signature]).dig('value', 0)
 
         break if status && status['confirmationStatus'] == commitment
 
-        sleep 0.5
+        sleep interval
       end
 
       signature
     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]
+    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
+    end
+
+    def handle_rpc_response(response)
+      raise "RPC error: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/solace/constants.rb

@@ -7,46 +7,39 @@
 # @return [Module] Constants module
 module Solace
   module Constants
-    # @!const SYSTEM_PROGRAM_ID
+    # @!attribute SYSTEM_PROGRAM_ID
     #   The public key of the System Program (native SOL transfers, account creation, etc)
     #   This is the same across all Solana clusters
-    # @return [String]
     SYSTEM_PROGRAM_ID = '11111111111111111111111111111111'
 
-    # @!const SYSVAR_RENT_PROGRAM_ID
+    # @!attribute SYSVAR_RENT_PROGRAM_ID
     #   The public key of the Rent Program
     #   This is the same across all Solana clusters
-    # @return [String]
     SYSVAR_RENT_PROGRAM_ID = 'SysvarRent111111111111111111111111111111111'
 
-    # @!const COMPUTE_BUDGET_PROGRAM_ID
+    # @!attribute COMPUTE_BUDGET_PROGRAM_ID
     #   The public key of the Compute Budget Program
     #   This is the same across all Solana clusters
-    # @return [String]
     COMPUTE_BUDGET_PROGRAM_ID = 'ComputeBudget111111111111111111111111111111'
 
-    # @!const TOKEN_PROGRAM_ID
+    # @!attribute TOKEN_PROGRAM_ID
     #   The public key of the SPL Token Program
     #   This is the same across all Solana clusters
-    # @return [String]
     TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
 
-    # @!const ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
+    # @!attribute ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
     #   The public key of the Associated Token Account Program
     #   This is the same across all Solana clusters
-    # @return [String]
     ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'
 
-    # @!const MEMO_PROGRAM_ID
+    # @!attribute MEMO_PROGRAM_ID
     #   The public key of the Memo Program
     #   This is the same across all Solana clusters
-    # @return [String]
     MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'
 
-    # @!const ADDRESS_LOOKUP_TABLE_PROGRAM_ID
+    # @!attribute ADDRESS_LOOKUP_TABLE_PROGRAM_ID
     #   The public key of the Address Lookup Table Program
     #   This is the same across all Solana clusters
-    # @return [String]
     ADDRESS_LOOKUP_TABLE_PROGRAM_ID = 'AddressLookupTab1e1111111111111111111111111'
   end
 end

data/lib/solace/instruction.rb

@@ -1,37 +1,48 @@
 # frozen_string_literal: true
 
-# =============================
-# Instruction
-# =============================
-#
-# Class representing a Solana instruction.
-#
-# The BufferLayout is:
-#   - [Program index (1 byte)]
-#   - [Number of accounts (compact u16)]
-#   - [Accounts (variable length)]
-#   - [Data length (compact u16)]
-#   - [Data (variable length)]
-#
 module Solace
-  class Instruction < Solace::SerializableRecord
-    # @!const SERIALIZER
+  # Class representing a Solana instruction.
+  #
+  # Handles serialization and deserialization of instruction fields. Instructions are used to
+  # encode the data that is sent to a program on the Solana blockchain. Instructions are part of
+  # transaction messages. All instruction builders and instruction composers return an instance of
+  # this class.
+  #
+  # The BufferLayout is:
+  #   - [Program index (1 byte)]
+  #   - [Number of accounts (compact u16)]
+  #   - [Accounts (variable length)]
+  #   - [Data length (compact u16)]
+  #   - [Data (variable length)]
+  #
+  # @example
+  #   instruction = Solace::Instruction.new(
+  #     program_index: 0,
+  #     accounts: [1, 2, 3],
+  #     data: [4, 5, 6]
+  #   )
+  #
+  # @since 0.0.1
+  class Instruction
+    include Solace::Concerns::BinarySerializable
+
+    # @!attribute SERIALIZER
     #   @return [Solace::Serializers::InstructionSerializer] The serializer for the instruction
     SERIALIZER = Solace::Serializers::InstructionSerializer
 
-    # @!const DESERIALIZER
+    # @!attribute DESERIALIZER
     #   @return [Solace::Serializers::InstructionDeserializer] The deserializer for the instruction
     DESERIALIZER = Solace::Serializers::InstructionDeserializer
 
-    # @!attribute [rw] program_index
+    # @!attribute  [rw] program_index
     #   @return [Integer] The program index of the instruction
     attr_accessor :program_index
 
-    # @!attribute [rw] accounts
+    # @!attribute  [rw] accounts
     #   @return [Array<Integer>] The accounts of the instruction
     attr_accessor :accounts
 
-    # @!attribute [rw] data
+    # @!attribute  [rw] data
     #   @return [Array<Integer>] The instruction data
     attr_accessor :data
   end

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

@@ -3,8 +3,23 @@
 module Solace
   module Instructions
     module AssociatedTokenAccount
-      # A class to build the CreateAssociatedTokenAccount instruction for the Associated Token Account Program.
-      # This is a special "all-in-one" instruction that creates and initializes the account.
+      # Instruction for creating an Associated Token Account.
+      #
+      # This is a special "all-in-one" instruction that creates and initializes the account. It
+      # is used to create an Associated Token Account (ATA) for a given mint and owner.
+      #
+      # @example Build a CreateAssociatedTokenAccount instruction
+      #   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
+      #   )
+      #
+      # @since 0.0.2
       class CreateAssociatedTokenAccountInstruction
         # !@const INSTRUCTION_INDEX
         #   Instruction index for CreateAssociatedTokenAccount
@@ -65,4 +80,4 @@ module Solace
       end
     end
   end
-end
+end