solace 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78ff45cbaff80411dfec8433e478a0b7a97caea5fb97ae6b8159e2ea7fa409fc
-  data.tar.gz: 13c025072948cc13dfc61d0d7c431df5ae4af90bcca76e239d1fff6cb0033d4f
+  metadata.gz: 73c15e6b362288fa1f3be0fd2793fcf43aff390deabe20f3264f22550cb67734
+  data.tar.gz: 1b036900c1306c1af4f4c0887a625d6a633a7cf4276c79c1a8b61754d7ffe593
 SHA512:
-  metadata.gz: 6d7dfe812cbe1a44275a6a62d36555cdf666e838d1ed37777efc9072bd91605ac4e0a8fca931a29405c387944c3bcef5c949022c21af762dfba09e7e6ab2530d
-  data.tar.gz: 181f9c5eb217ad0499b76f6e0052e3f9131d46c12c76583f8a3b1ad05d10274347158512e490656ed41c0c44a07b7645648b0e89b956de8691bf2b4916eebdd6
+  metadata.gz: 422a09d627bbf0e9bb59f3183f4a1ad34904a14996291555ff7c83717554c0915c4ba1d93c689b852cb9d9fab024cfd0e491c0443b332a6dc6f448028c48e000
+  data.tar.gz: a185276e03d031c72c7a78b11db5fd3a9b1d1fa6388758b41c20fad66241aa14b44e5188caace7d0bffaf498c03834d4fe73461754834c3a33e412a13544bf1c

data/CHANGELOG

@@ -0,0 +1,45 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+ 
+The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
+
+### Template
+
+```markdown
+## [VERSION] - yyyy-mm-dd
+  
+### Added
+1. 
+
+### Changed
+ 
+### Fixed
+```
+
+## [0.0.3] - 2025-07-30
+  
+### Added
+1. Moved `TransferCheckedInstruction` and `TransferInstruction` to `Solace::Instructions::SystemProgram` namespace.
+2. Added `get_token_account_balance` to `Solace::Connection`.
+3. Added `get_or_create_address` to `Solace::Programs::AssociatedTokenAccount`.
+4. Added Composer system for handling accounts and instructions in a higher level abstraction.
+5. Added `SystemProgramTransferComposer` to `Solace::Composers` namespace.
+6. Added `SplTokenProgramTransferCheckedComposer` to `Solace::Composers` namespace.
+7. Moved TransferCheckedInstruction to proper namespace `Solace::Instructions::SplToken::TransferCheckedInstruction`.
+8. Updated `get_or_create_address` to wait for confirmation before returning the address in `Solace::Programs::AssociatedTokenAccount`.
+9. Moved default options to instance variable in `Solace::Connection`.
+10. Moved test setup to `test/bootstrap.rb` and added rake task `bootstrap` to run it.
+
+### Changed
+
+THESE ARE BREAKING CHANGES FROM 0.0.2 TO 0.0.3. Solice is still in alpha and the API is subject to change. 
+
+There was a bit of a refactoring of the codebase to make it more maintainable and to make it easier to add new features. Additonally, the SDK now has `Composers` for handling accounts and instructions in a higher level abstraction. These composers are used in the tests and can be used in your own code as well.
+
+Soon, YARD documentation will be added to the SDK and published to https://solace-rb.github.io/solace/. 
+
+Stay tuned.
+ 
+### Fixed
+
+N/A

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sebastian Scholl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -174,7 +174,7 @@ Instruction builders are service objects that create specific instruction types.
 
 ```ruby
 # Build a SOL transfer instruction
-transfer_ix = Solace::Instructions::TransferInstruction.build(
+transfer_ix = Solace::Instructions::SystemProgram::TransferInstruction.build(
   lamports: 1_000_000,  # 0.001 SOL
   from_index: 0,        # Sender account index
   to_index: 1,          # Recipient account index
@@ -433,7 +433,7 @@ recipient = Solace::Keypair.generate
 connection.request_airdrop(payer.address, 1_000_000_000)
 
 # Build transfer instruction
-transfer_ix = Solace::Instructions::TransferInstruction.build(
+transfer_ix = Solace::Instructions::SystemProgram::TransferInstruction.build(
   lamports: 100_000_000,  # 0.1 SOL
   from_index: 0,
   to_index: 1,

data/lib/solace/composers/base.rb

@@ -0,0 +1,40 @@
+module Solace
+  module Composers
+    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,87 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    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,59 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    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/connection.rb

@@ -6,21 +6,31 @@ require 'uri'
 
 module Solace
   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
 
-    # !const default options
-    DEFAULT_OPTIONS = {
-      encoding: 'base64',
-      commitment: 'confirmed'
-    }.freeze
+    # @!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
     # @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
@@ -68,7 +78,7 @@ module Solace
         [
           pubkey,
           lamports,
-          DEFAULT_OPTIONS.merge(options)
+          default_options.merge(options)
         ]
       )
     end
@@ -97,7 +107,7 @@ module Solace
         'getAccountInfo',
         [
           pubkey,
-          DEFAULT_OPTIONS
+          default_options
         ]
       )['result']
 
@@ -115,7 +125,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
@@ -129,7 +153,7 @@ module Solace
         'getTransaction',
         [
           signature,
-          DEFAULT_OPTIONS.merge(options)
+          default_options.merge(options)
         ]
       )['result']
     end
@@ -143,7 +167,7 @@ module Solace
         'getSignatureStatuses',
         [
           signatures,
-          DEFAULT_OPTIONS.merge({ 'searchTransactionHistory' => true })
+          default_options.merge({ 'searchTransactionHistory' => true })
         ]
       )['result']
     end
@@ -157,7 +181,7 @@ module Solace
         'sendTransaction',
         [
           transaction,
-          DEFAULT_OPTIONS.merge(options)
+          default_options.merge(options)
         ]
       )
     end
@@ -172,15 +196,17 @@ 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
   end

data/lib/solace/instructions/base.rb

@@ -0,0 +1,21 @@
+module Solace
+  module Instructions
+    class Base
+      class << self
+        # Must implement build method
+        #
+        # @return [Solace::Instruction] The instruction
+        def build 
+          raise NotImplementedError, "Subclasses must implement build method"
+        end
+
+        # Must implement data method
+        #
+        # @return [Array<Integer>] The instruction data
+        def data
+          raise NotImplementedError, "Subclasses must implement data method"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SplToken
+      # Service object for building an SPL Token Program transfer instruction
+      class TransferCheckedInstruction
+        # SPL Token Program instruction index for Transfer Checked
+        INSTRUCTION_INDEX = [12].freeze
+
+        # Builds a Solace::Instruction for transferring SPL tokens
+        #
+        # SPL Token Program transfer instruction layout:
+        #   - 1 byte: instruction index (12 for transfer checked)
+        #   - 8 bytes: amount (u64, little-endian)
+        #   - 8 bytes: decimals (u64, little-endian)
+        #
+        # @param amount [Integer] Amount to transfer (in tokens, according to mint's decimals)
+        # @param decimals [Integer] Number of decimals for the token
+        # @param to_index [Integer] Index of the destination token account in the transaction's accounts
+        # @param from_index [Integer] Index of the source token account in the transaction's accounts
+        # @param mint_index [Integer] Index of the mint in the transaction's accounts
+        # @param authority_index [Integer] Index of the authority (owner) in the transaction's accounts
+        # @param program_index [Integer] Index of the SPL Token Program in the transaction's accounts (default: 3)
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          decimals:,
+          to_index:,
+          from_index:,
+          mint_index:,
+          authority_index:,
+          program_index: 3
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [from_index, mint_index, to_index, authority_index]
+            ix.data = data(amount, decimals)
+          end
+        end
+
+        # Instruction data for a token transfer instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes little-endian u64)]
+        #   - [Decimals (8 bytes little-endian u64)]
+        #
+        # @param amount [Integer] Amount to transfer
+        # @param decimals [Integer] Number of decimals for the token
+        # @return [Array] 1-byte instruction index + 8-byte amount + decimals
+        def self.data(amount, decimals)
+          INSTRUCTION_INDEX +
+            Solace::Utils::Codecs.encode_le_u64(amount).bytes +
+            [decimals]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module SystemProgram
+      # Service object for building a System Program transfer instruction
+      class TransferInstruction < Base
+        # Instruction ID for System Transfer
+        INSTRUCTION_ID = [2, 0, 0, 0].freeze
+
+        # Builds a Solace::Instruction for transferring SOL
+        #
+        # System Program transfer instruction layout:
+        #   - 4 bytes: instruction index (0 for transfer)
+        #   - 8 bytes: amount (u64, little-endian)
+        #
+        # @param lamports [Integer] Amount to transfer (in lamports)
+        # @param to_index [Integer] Index of the recipient in the transaction's accounts
+        # @param from_index [Integer] Index of the sender in the transaction's accounts
+        # @param program_index [Integer] Index of the program in the transaction's accounts (default: 2)
+        # @return [Solace::Instruction]
+        def self.build(
+          lamports:,
+          to_index:,
+          from_index:,
+          program_index: 2
+        )
+          Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts = [from_index, to_index]
+            ix.data = data(lamports)
+          end
+        end
+
+        # Instruction data for a transfer instruction
+        #
+        # The BufferLayout is:
+        #   - [Instruction ID (4 bytes)]
+        #   - [Amount (8 bytes little-endian u64)]
+        #
+        # @param lamports [Integer] Amount to transfer (in lamports)
+        # @return [Array] 4-byte instruction ID + 8-byte amount
+        def self.data(lamports)
+          INSTRUCTION_ID +
+            Utils::Codecs.encode_le_u64(lamports).bytes
+        end
+      end
+    end
+  end
+end

data/lib/solace/programs/associated_token_account.rb

@@ -36,6 +36,28 @@ module Solace
         self.class.get_address(**options)
       end
 
+      # 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 (required if account needs to be created).
+      # @param owner [Solace::Keypair || Solace::PublicKey] The keypair of the owner.
+      # @param mint [Solace::Keypair || Solace::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, _ = get_address(owner:, mint:)
+        
+        account_info = @connection.get_account_info(ata_address)
+        
+        return ata_address if account_info
+
+        response = create_associated_token_account(payer:, owner:, mint:)
+
+        raise "Failed to create associated token account" unless response['result']
+
+        @connection.wait_for_confirmed_signature(commitment) { response['result'] }
+        
+        ata_address
+      end
+
       # Creates a new associated token account.
       #
       # @param options [Hash] Options for calling the prepare_create_associated_token_account method.
@@ -53,9 +75,9 @@ module Solace
       # @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(
-        owner:,
-        mint:,
-        payer:
+        payer:, 
+        owner:, 
+        mint:
       )
         ata_address, _ = get_address(owner:, mint:)
 

data/lib/solace/transaction_composer.rb

@@ -0,0 +1,81 @@
+# lib/solace/transaction_composer.rb
+module Solace
+  # Composes multi-instruction transactions with automatic account management
+  class TransactionComposer
+
+    # @!attribute connection
+    #
+    # @return [Solace::Connection] The connection to the Solana cluster
+    attr_reader :connection
+
+    # @!attribute context
+    #
+    # @return [Utils::AccountContext] The account registry
+    attr_reader :context
+
+    # @!attribute instruction_composers
+    #
+    # @return [Array<Composers::Base>] The instruction composers
+    attr_reader :instruction_composers
+
+    # Initialize the composer
+    #
+    # @param connection [Solace::Connection] The connection to the Solana cluster
+    def initialize(connection:)
+      @connection = connection
+      @instruction_composers = []
+      @context = Utils::AccountContext.new
+    end
+    
+    # Add an instruction composer to the transaction
+    #
+    # @param composer [Composers::Base] The instruction composer
+    # @return [TransactionComposer] Self for chaining
+    def add_instruction(composer)
+      merge_accounts(composer.account_context)
+      instruction_composers << composer
+      self
+    end
+    
+    # Set the fee payer for the transaction
+    #
+    # @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)
+      self
+    end
+
+    # Compose the final transaction
+    #
+    # @return [Solace::Transaction] The composed transaction (unsigned)
+    def compose_transaction
+      context.compile
+
+      message = Solace::Message.new(
+        header: context.header,
+        accounts: context.accounts,
+        instructions: build_instructions,
+        recent_blockhash: connection.get_latest_blockhash,
+      )
+      
+      Solace::Transaction.new(message: message)
+    end    
+
+    private
+
+    # Build all instructions with resolved indices
+    #
+    # @return [Array<Solace::Instruction>] The built instructions
+    def build_instructions
+      instruction_composers.map { _1.build_instruction(context) }
+    end
+
+    # Merge all accounts from another AccountContext into this one
+    #
+    # @param account_context [AccountContext] The other context to merge from
+    def merge_accounts(account_context)
+      context.merge_from(account_context)
+    end
+  end
+end

data/lib/solace/utils/account_context.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Solace
+  module Utils
+    # Internal utility for managing account context in transaction building
+    # with automatic deduplication and sorting
+    class AccountContext
+      # @!attribute DEFAULT_ACCOUNT
+      #   The default account data
+      #
+      # @return [Hash] The default account data with lowest level of permissions
+      DEFAULT_ACCOUNT = {
+        signer: false,
+        writable: false,
+        fee_payer: false,
+      }
+      
+      # @!attribute header
+      #   The header for the transaction
+      #
+      # @return [Array<Integer>] The header for the transaction
+      attr_accessor :header
+      
+      # @!attribute accounts
+      #   The accounts in the transaction
+      #
+      # @return [Array<String>] The accounts
+      attr_accessor :accounts
+
+      # @!attribute pubkey_account_map
+      #   The map of accounts
+      #
+      # @return [Hash] The map of accounts
+      attr_accessor :pubkey_account_map
+
+      # Initialize the account context
+      def initialize
+        @header = []
+        @accounts = []
+        @pubkey_account_map = {}
+      end
+
+      # Set the fee payer account
+      #
+      # @param pubkey [Solace::Keypair | Solace::PublicKey | String] The pubkey of the fee payer account
+      def set_fee_payer(pubkey)
+        merge_account(pubkey, signer: true, writable: true, fee_payer: true)
+      end
+
+      # Add a signer account
+      #
+      # @param pubkey [Solace::Keypair | Solace::PublicKey | String] The pubkey of the signer account
+      def add_writable_signer(pubkey)
+        merge_account(pubkey, signer: true, writable: true)
+      end
+
+      # Add a writable account
+      #
+      # @param pubkey [Solace::Keypair | Solace::PublicKey | String] The pubkey of the writable account
+      def add_writable_nonsigner(pubkey)
+        merge_account(pubkey, signer: false, writable: true)
+      end
+      
+      # Add a readonly signer account
+      #
+      # @param pubkey [Solace::Keypair | Solace::PublicKey | String] The pubkey of the readonly signer account
+      def add_readonly_signer(pubkey)
+        merge_account(pubkey, signer: true, writable: false)
+      end
+      
+
+      # Add a readonly account
+      #
+      # @param pubkey [Solace::Keypair | Solace::PublicKey | String] The pubkey of the readonly account
+      def add_readonly_nonsigner(pubkey)
+        merge_account(pubkey, signer: false, writable: false)
+      end
+
+      # Predicate to check if an account is a fee payer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a fee payer
+      def fee_payer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:fee_payer] }
+      end
+
+      # Predicate to check if an account is a signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a signer
+      def signer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:signer] }
+      end
+
+      # Predicate to check if an account is writable
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is writable
+      def writable?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:writable] }
+      end
+      
+      # Predicate to check if an account is a writable signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a writable signer
+      def writable_signer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:signer] && acc[:writable] }
+      end
+      
+      # Predicate to check if an account is writable and not a signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is writable and not a signer
+      def writable_nonsigner?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| !acc[:signer] && acc[:writable] }
+      end
+
+      # Predicate to check if an account is a readonly signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is a readonly signer
+      def readonly_signer?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| acc[:signer] && !acc[:writable] }
+      end
+
+      # Predicate to check if an account is readonly and not a signer
+      #
+      # @param pubkey [String] The pubkey of the account
+      # @return [Boolean] Whether the account is readonly and not a signer
+      def readonly_nonsigner?(pubkey)
+        @pubkey_account_map[pubkey].try { |acc| !acc[:signer] && !acc[:writable] }
+      end
+      
+      # Merge all accounts from another AccountContext into this one
+      #
+      # @param other_context [AccountContext] The other context to merge from
+      def merge_from(other_context)
+        other_context.pubkey_account_map.each do |pubkey, data|
+          merge_account(
+            pubkey,
+            signer: data[:signer],
+            writable: data[:writable],
+            fee_payer: data[:fee_payer]
+          )
+        end
+      end
+
+      # Compile accounts into final format
+      # 
+      # Gets unique accounts and sorts them in the following order:
+      #   - Signers first (Solana requirement)
+      #   - Then writable accounts
+      #   - Then readonly accounts
+      #
+      # @return [Hash] The compiled accounts and header
+      def compile
+        self.header = calculate_header
+        self.accounts = order_accounts        
+        self
+      end
+      
+      # Index of a pubkey in the accounts array
+      #
+      # @param pubkey_str [String] The public key of the account
+      # @return [Integer] The index of the pubkey in the accounts array or -1 if not found
+      def index_of(pubkey_str)
+        indices[pubkey_str] || -1
+      end
+
+      # Get map of indicies for pubkeys in accounts array
+      #
+      # @return [Hash<String, Integer>] The indices of the pubkeys in the accounts array
+      def indices
+        accounts.each_with_index.to_h
+      end
+
+      private
+
+      # Add or merge an account into the context
+      #
+      # @param pubkey [String | Solace::PublicKey | Solace::Keypair] The public key of the account
+      # @param signer [Boolean] Whether the account is a signer
+      # @param writable [Boolean] Whether the account is writable
+      def merge_account(
+        pubkey,
+        signer:,
+        writable:,
+        fee_payer: false
+      )
+        pubkey_str = resolve_pubkey(pubkey)
+
+        @pubkey_account_map[pubkey_str] ||= DEFAULT_ACCOUNT.dup
+        @pubkey_account_map[pubkey_str][:signer] ||= signer
+        @pubkey_account_map[pubkey_str][:writable] ||= writable
+        @pubkey_account_map[pubkey_str][:fee_payer] ||= fee_payer
+        
+        self
+      end
+
+      # Order accounts by signer, writable, readonly signer, readonly
+      #
+      # @return [Array<String>] The ordered accounts
+      def order_accounts
+        @pubkey_account_map.keys.sort_by do |pubkey|
+          if fee_payer?(pubkey)
+            0
+          elsif writable_signer?(pubkey)
+            1
+          elsif readonly_signer?(pubkey)
+            2
+          elsif writable_nonsigner?(pubkey)
+            2
+          elsif readonly_nonsigner?(pubkey)
+            3
+          else
+            raise ArgumentError, "Unknown account type for pubkey: #{pubkey}"
+          end
+        end
+      end
+
+      # Calculate the header for the transaction
+      #
+      # @note The header is an array of three integers:
+      #   - The number of signers (writable + readonly)
+      #   - The number of readonly signers
+      #   - The number of readonly unsigned accounts
+      #
+      # @return [Array] The header for the transaction
+      def calculate_header
+        @pubkey_account_map.keys.reduce([0, 0, 0]) do |acc, pubkey|
+          acc[0] += 1 if signer?(pubkey)
+           
+          if readonly_signer?(pubkey)
+            acc[1] += 1
+          elsif readonly_nonsigner?(pubkey)
+            acc[2] += 1
+          end
+
+          acc
+        end
+      end
+
+      # Resolve the pubkey from a Solace::PublicKey or String
+      #
+      # @param pubkey [String|Solace::PublicKey] The pubkey to resolve
+      # @return [String] The resolved pubkey
+      def resolve_pubkey(pubkey)
+        pubkey.is_a?(String) ? pubkey : pubkey.address
+      end
+    end
+  end
+end

data/lib/solace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Solace
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/lib/solace.rb

@@ -8,6 +8,7 @@ require_relative 'solace/constants'
 require_relative 'solace/connection'
 require_relative 'solace/utils/codecs'
 require_relative 'solace/utils/pda'
+require_relative 'solace/utils/account_context'
 require_relative 'solace/utils/curve25519_dalek'
 require_relative 'solace/concerns/binary_serializable'
 
@@ -26,6 +27,12 @@ require_relative 'solace/transaction'
 require_relative 'solace/message'
 require_relative 'solace/instruction'
 require_relative 'solace/address_lookup_table'
+require_relative 'solace/transaction_composer'
+
+# 📦 Composers (Builders)
+# 
+# Glob require all instructions
+Dir[File.join(__dir__, 'solace/composers', '**', '*.rb')].sort.each { |file| require file }
 
 # 📦 Instructions (Builders)
 # 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -83,7 +83,7 @@ description: A Ruby library for working with Solana blockchain. Provides both lo
   instruction builders and high-level program clients for interacting with Solana
   programs.
 email:
-- sebastian@scholl.io
+- sebscholl@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -93,18 +93,22 @@ files:
 - README.md
 - lib/solace.rb
 - lib/solace/address_lookup_table.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/instruction.rb
 - lib/solace/instructions/associated_token_account/create_associated_token_account_instruction.rb
+- lib/solace/instructions/base.rb
 - lib/solace/instructions/spl_token/initialize_account_instruction.rb
 - lib/solace/instructions/spl_token/initialize_mint_instruction.rb
 - lib/solace/instructions/spl_token/mint_to_instruction.rb
+- lib/solace/instructions/spl_token/transfer_checked_instruction.rb
 - lib/solace/instructions/spl_token/transfer_instruction.rb
 - lib/solace/instructions/system_program/create_account_instruction.rb
-- lib/solace/instructions/transfer_checked_instruction.rb
-- lib/solace/instructions/transfer_instruction.rb
+- lib/solace/instructions/system_program/transfer_instruction.rb
 - lib/solace/keypair.rb
 - lib/solace/message.rb
 - lib/solace/programs/associated_token_account.rb
@@ -124,6 +128,8 @@ files:
 - lib/solace/serializers/transaction_deserializer.rb
 - lib/solace/serializers/transaction_serializer.rb
 - lib/solace/transaction.rb
+- lib/solace/transaction_composer.rb
+- lib/solace/utils/account_context.rb
 - lib/solace/utils/codecs.rb
 - lib/solace/utils/curve25519_dalek.rb
 - lib/solace/utils/libcurve25519_dalek-linux/libcurve25519_dalek.so

data/lib/solace/instructions/transfer_checked_instruction.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Solace
-  module Instructions
-    # Service object for building an SPL Token Program transfer instruction
-    class TransferCheckedInstruction
-      # SPL Token Program instruction index for Transfer Checked
-      INSTRUCTION_INDEX = [12].freeze
-
-      # Builds a Solace::Instruction for transferring SPL tokens
-      #
-      # SPL Token Program transfer instruction layout:
-      #   - 1 byte: instruction index (12 for transfer checked)
-      #   - 8 bytes: amount (u64, little-endian)
-      #   - 8 bytes: decimals (u64, little-endian)
-      #
-      # @param amount [Integer] Amount to transfer (in tokens, according to mint's decimals)
-      # @param decimals [Integer] Number of decimals for the token
-      # @param to_index [Integer] Index of the destination token account in the transaction's accounts
-      # @param from_index [Integer] Index of the source token account in the transaction's accounts
-      # @param mint_index [Integer] Index of the mint in the transaction's accounts
-      # @param authority_index [Integer] Index of the authority (owner) in the transaction's accounts
-      # @param program_index [Integer] Index of the SPL Token Program in the transaction's accounts (default: 3)
-      # @return [Solace::Instruction]
-      def self.build(
-        amount:,
-        decimals:,
-        to_index:,
-        from_index:,
-        mint_index:,
-        authority_index:,
-        program_index: 3
-      )
-        Solace::Instruction.new.tap do |ix|
-          ix.program_index = program_index
-          ix.accounts = [from_index, mint_index, to_index, authority_index]
-          ix.data = data(amount, decimals)
-        end
-      end
-
-      # Instruction data for a token transfer instruction
-      #
-      # The BufferLayout is:
-      #   - [Instruction Index (1 byte)]
-      #   - [Amount (8 bytes little-endian u64)]
-      #   - [Decimals (8 bytes little-endian u64)]
-      #
-      # @param amount [Integer] Amount to transfer
-      # @param decimals [Integer] Number of decimals for the token
-      # @return [Array] 1-byte instruction index + 8-byte amount + decimals
-      def self.data(amount, decimals)
-        INSTRUCTION_INDEX +
-          Solace::Utils::Codecs.encode_le_u64(amount).bytes +
-          [decimals]
-      end
-    end
-  end
-end

data/lib/solace/instructions/transfer_instruction.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Solace
-  module Instructions
-    # Service object for building a System Program transfer instruction
-    class TransferInstruction
-      # Instruction ID for System Transfer
-      INSTRUCTION_ID = [2, 0, 0, 0].freeze
-
-      # Builds a Solace::Instruction for transferring SOL
-      #
-      # System Program transfer instruction layout:
-      #   - 4 bytes: instruction index (0 for transfer)
-      #   - 8 bytes: amount (u64, little-endian)
-      #
-      # @param lamports [Integer] Amount to transfer (in lamports)
-      # @param to_index [Integer] Index of the recipient in the transaction's accounts
-      # @param from_index [Integer] Index of the sender in the transaction's accounts
-      # @param program_index [Integer] Index of the program in the transaction's accounts (default: 2)
-      # @return [Solace::Instruction]
-      def self.build(
-        lamports:,
-        to_index:,
-        from_index:,
-        program_index: 2
-      )
-        Solace::Instruction.new.tap do |ix|
-          ix.program_index = program_index
-          ix.accounts = [from_index, to_index]
-          ix.data = data(lamports)
-        end
-      end
-
-      # Instruction data for a transfer instruction
-      #
-      # The BufferLayout is:
-      #   - [Instruction ID (4 bytes)]
-      #   - [Amount (8 bytes little-endian u64)]
-      #
-      # @param lamports [Integer] Amount to transfer (in lamports)
-      # @return [Array] 4-byte instruction ID + 8-byte amount
-      def self.data(lamports)
-        INSTRUCTION_ID +
-          Solace::Utils::Codecs.encode_le_u64(lamports).bytes
-      end
-    end
-  end
-end