solace 0.0.3 → 0.0.5

data/lib/solace/address_lookup_table.rb

@@ -1,20 +1,36 @@
 # encoding: ASCII-8BIT
 # frozen_string_literal: true
 
-# =============================
-# Address Lookup Table
-# =============================
-#
-# Class representing an address lookup table.
-#
-# The BufferLayout is:
-#   - [Account key (32 bytes)]
-#   - [Number of writable indexes (compact u16)]
-#   - [Writable indexes (variable length)]
-#   - [Number of readonly indexes (compact u16)]
-#   - [Readonly indexes (variable length)]
-#
 module Solace
+  # Represents a Solana Address Lookup Table account.
+  #
+  # This class models the internal structure of a deserialized address lookup table and provides
+  # access to the account key, writable indexes, and readonly indexes.
+  #
+  # It includes serialization and deserialization logic for encoding and decoding the table
+  # according to Solana’s buffer layout.
+  #
+  # ## Buffer Layout (in bytes):
+  # - `[account (32 bytes)]`
+  # - `[num_writable (compact-u16)]`
+  # - `[writable indexes]`
+  # - `[num_readonly (compact-u16)]`
+  # - `[readonly indexes]`
+  #
+  # Includes `BinarySerializable`, enabling methods like `#to_binary`, `#to_io`, and `#to_bytes`.
+  #
+  # @example Deserialize from base64
+  #   io = StringIO.new(base64)
+  #   table = Solace::AddressLookupTable.deserialize(io)
+  #
+  # @example Serialize to base64
+  #   table = Solace::AddressLookupTable.new
+  #   table.account = pubkey
+  #   table.writable_indexes = [1, 2]
+  #   table.readonly_indexes = [3, 4]
+  #   base64 = table.serialize
+  #
+  # @since 0.0.1
   class AddressLookupTable
     include Solace::Concerns::BinarySerializable
 
@@ -31,20 +47,20 @@ module Solace
     attr_accessor :readonly_indexes
 
     class << self
-      # Parse address lookup table from io stream
+      # Deserializes an address lookup table from io stream
       #
-      # @param io [IO or StringIO] The input to read bytes from.
+      # @param io [IO, StringIO] The input to read bytes from.
       # @return [Solace::AddressLookupTable] Parsed address lookup table object
       def deserialize(io)
-        Solace::Serializers::AddressLookupTableDeserializer.call(io)
+        Solace::Serializers::AddressLookupTableDeserializer.new(io).call
       end
     end
 
-    # Serialize the address lookup table
+    # Serializes the address lookup table
     #
     # @return [String] The serialized address lookup table (base64)
     def serialize
-      Solace::Serializers::AddressLookupTableSerializer.call(self)
+      Solace::Serializers::AddressLookupTableSerializer.new(self).call
     end
   end
 end

data/lib/solace/composers/base.rb

@@ -1,22 +1,27 @@
+# frozen_string_literal: true
+
 module Solace
   module Composers
+    # A Base class for all composers
+    #
+    # @since 0.0.3
     class Base
-      # @!attribute params
+      # @!attribute  params
       #   The params for the composer
-      # 
+      #
       # @return [Hash] The parameters passed to the composer
       attr_reader :params
-      
-      # @!attribute account_context
+
+      # @!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)
+      # @param params [Hash] Parameters to pass to the composer constructor
+      def initialize(params)
         @params = params
         @account_context = Utils::AccountContext.new
         setup_accounts
@@ -26,15 +31,15 @@ module Solace
       #
       # @return [void]
       def setup_accounts
-        raise NotImplementedError, "Subclasses must implement setup_accounts method"
+        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"
+        raise NotImplementedError, 'Subclasses must implement build_instruction method'
       end
     end
   end
-end
+end

data/lib/solace/composers/spl_token_program_transfer_checked_composer.rb

@@ -2,6 +2,33 @@
 
 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
       #
@@ -84,4 +111,3 @@ module Solace
     end
   end
 end
-

data/lib/solace/composers/system_program_transfer_composer.rb

@@ -2,6 +2,28 @@
 
 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
       #
@@ -56,4 +78,3 @@ module Solace
     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,72 +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
-    #
-    # @return [String] The URL of the Solana RPC node
     attr_reader :rpc_url
 
     # @!attribute [r] default_options
     #   The default options for RPC requests
-    #
-    # @return [Hash] 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', commitment: 'confirmed')
       @request_id = nil
       @rpc_url = rpc_url
 
       # Set default options
-      @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(
@@ -148,6 +145,7 @@ 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',
@@ -176,6 +174,7 @@ 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',
@@ -201,13 +200,45 @@ module Solace
       # Wait for confirmation
       loop do
         status = get_signature_status([signature]).dig('value', 0)
-        
+
         break if status && status['confirmationStatus'] == commitment
-        
+
         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

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

@@ -1,11 +1,32 @@
+# frozen_string_literal: true
+
 # lib/solace/instructions/spl_token/initialize_account_instruction.rb
 
 module Solace
   module Instructions
     module SplToken
-      # A class to build the InitializeAccount instruction for the SPL Token Program.
+      # Instruction for initializing a new token account.
+      #
+      # This instruction is used to initialize a new token account for a given mint and owner. It
+      # is used in conjunction with the CreateAccount instruction to create and initialize a new
+      # token account. Note that the AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+      # is a special "all-in-one" instruction that creates and initializes the account in a single
+      # instruction.
+      #
+      # @example Build an InitializeAccount instruction
+      #   instruction = Solace::Instructions::SplToken::InitializeAccountInstruction.build(
+      #     account_index: 0,
+      #     mint_index: 1,
+      #     owner_index: 2,
+      #     rent_sysvar_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @see Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction
+      # @see Solace::Instructions::SystemProgram::CreateAccountInstruction
+      # @since 0.0.2
       class InitializeAccountInstruction
-        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
         #   Instruction index for SPL Token Program's InitializeAccount instruction.
         INSTRUCTION_INDEX = [1].freeze
 
@@ -43,4 +64,4 @@ module Solace
       end
     end
   end
-end
+end

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

@@ -3,6 +3,23 @@
 module Solace
   module Instructions
     module SplToken
+      # Instruction for initializing a new mint.
+      #
+      # This instruction is used to initialize a new mint for a given token. It is used in conjunction with the SystemProgram::CreateAccount
+      # instruction to create and initialize a new mint account.
+      #
+      # @example Build an InitializeMint instruction
+      #   instruction = Solace::Instructions::SplToken::InitializeMintInstruction.build(
+      #     decimals: 6,
+      #     mint_authority: mint_authority.address,
+      #     freeze_authority: freeze_authority.address,
+      #     rent_sysvar_index: 2,
+      #     mint_account_index: 1,
+      #     program_index: 3
+      #   )
+      #
+      # @see Solace::Instructions::SystemProgram::CreateAccountInstruction
+      # @since 0.0.2
       class InitializeMintInstruction
         # Instruction index for Initialize Mint
         INSTRUCTION_INDEX = [0].freeze
@@ -49,7 +66,7 @@ module Solace
         # @param decimals [Integer] Number of decimals for the token
         # @param mint_authority [String] Public key of the mint authority
         # @param freeze_authority [String, nil] Public key of the freeze authority
-        # @return [Array] 1-byte instruction index + 1-byte decimals + 32-byte mint authority + 1-byte freeze authority option + 32-byte freeze authority
+        # @return [Array<u8>] The instruction data
         def self.data(decimals, mint_authority, freeze_authority)
           INSTRUCTION_INDEX +
             [decimals] +

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

@@ -3,9 +3,22 @@
 module Solace
   module Instructions
     module SplToken
-      # A class to build the MintTo instruction for the SPL Token Program.
+      # Instruction for minting tokens to a token account.
+      #
+      # This instruction is used to mint tokens to a token account for a given mint and owner.
+      #
+      # @example Build a MintTo instruction
+      #   instruction = Solace::Instructions::SplToken::MintToInstruction.build(
+      #     amount: 100,
+      #     mint_index: 1,
+      #     mint_authority_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.0.2
       class MintToInstruction
-        # @!const [Array<Integer>] INSTRUCTION_INDEX
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
         #   Instruction index for SPL Token Program's MintTo instruction.
         INSTRUCTION_INDEX = [7].freeze
 
@@ -45,4 +58,4 @@ module Solace
       end
     end
   end
-end
+end