solace 0.0.10 → 0.1.1

data/lib/solace/programs/associated_token_account.rb

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

data/lib/solace/programs/base.rb

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

data/lib/solace/programs/spl_token.rb

@@ -15,6 +15,7 @@ module Solace
     #   # Create an SPL Token mint
     #   result = program.create_mint(
     #     payer: payer,
+    #     funder: funder,
     #     decimals: 6,
     #     mint_keypair: mint_keypair,
     #     mint_authority: mint_authority,
@@ -22,11 +23,9 @@ module Solace
     #   )
     #
     #   # Wait for the transaction to be finalized
-    #   @connection.wait_for_confirmed_signature('finalized') { result['result'] }
+    #   connection.wait_for_confirmed_signature('finalized') { result['result'] }
     #
     # @since 0.0.2
-    #
-    # rubocop:disable Metrics/ClassLength
     class SplToken < Base
       # Initializes a new SPL Token client.
       #
@@ -37,189 +36,262 @@ module Solace
 
       # Creates a new SPL Token mint.
       #
-      # @param options [Hash] Options for calling the prepare_create_mint method.
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for calling the compose_create_mint method.
       # @return [String] The signature of the transaction.
-      def create_mint(**options)
-        tx = prepare_create_mint(**options)
+      def create_mint(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_create_mint(**composer_opts)
+
+        yield composer if block_given?
 
-        @connection.send_transaction(tx.serialize)
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:funder],
+            composer_opts[:mint_account]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+
+        tx
       end
 
-      # Prepares a new SPL Token mint and returns the signed transaction.
+      # Prepares a new SPL Token mint transaction.
       #
-      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
+      # @param funder [#to_s, PublicKey] The keypair that will pay for rent of the new mint account.
       # @param decimals [Integer] The number of decimal places for the token.
-      # @param mint_authority [String] The base58 public key for the mint authority.
-      # @param freeze_authority [String] (Optional) The base58 public key for the freeze authority.
-      # @param mint_keypair [Solace::Keypair] (Optional) The keypair for the new mint.
-      # @return [Solace::Transaction] The signed transaction.
-      #
+      # @param mint_authority [#to_s, PublicKey] The base58 public key for the mint authority.
+      # @param freeze_authority [#to_s, PublicKey] (Optional) The base58 public key for the freeze authority.
+      # @param mint_account [#to_s, PublicKey] (Optional) The keypair for the new mint.
+      # @return [TransactionComposer] A composer with required instructions.
       # rubocop:disable Metrics/MethodLength
-      def prepare_create_mint(
-        payer:,
+      def compose_create_mint(
+        funder:,
         decimals:,
         mint_authority:,
-        freeze_authority:,
-        mint_keypair: Solace::Keypair.generate
+        freeze_authority: nil,
+        mint_account: Solace::Keypair.generate
       )
-        accounts = [
-          payer.to_s,
-          mint_keypair.to_s,
-          Solace::Constants::SYSVAR_RENT_PROGRAM_ID,
-          Solace::Constants::TOKEN_PROGRAM_ID,
-          Solace::Constants::SYSTEM_PROGRAM_ID
-        ]
-
-        rent_lamports = @connection.get_minimum_lamports_for_rent_exemption(82)
-
-        create_account_ix = Solace::Instructions::SystemProgram::CreateAccountInstruction.build(
-          from_index: 0,
-          new_account_index: 1,
-          system_program_index: 4,
+        # Mint accounts need 82 bytes of space, and we need to fund it with enough lamports to be rent-exempt
+        rent_lamports = connection.get_minimum_lamports_for_rent_exemption(82)
+
+        # Build the account for the mint
+        create_account_ix = Composers::SystemProgramCreateAccountComposer.new(
+          from: funder,
+          new_account: mint_account,
+          owner: program_id,
           lamports: rent_lamports,
-          space: 82,
-          owner: program_id
+          space: 82
         )
 
-        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,
+        # Build the initialize mint composer
+        initialize_mint_ix = Composers::SplTokenProgramInitializeMintComposer.new(
           decimals: decimals,
-          mint_authority: mint_authority.to_s,
+          mint_account: mint_account,
+          mint_authority: mint_authority,
           freeze_authority: freeze_authority
         )
 
-        message = Message.new(
-          header: [2, 0, 3],
-          accounts: accounts,
-          recent_blockhash: @connection.get_latest_blockhash[0],
-          instructions: [create_account_ix, initialize_mint_ix]
-        )
-
-        tx = Transaction.new(message: message)
-        tx.sign(payer, mint_keypair)
-
-        tx
+        TransactionComposer
+          .new(connection: @connection)
+          .add_instruction(create_account_ix)
+          .add_instruction(initialize_mint_ix)
       end
       # rubocop:enable Metrics/MethodLength
 
       # Mint tokens to a token account
       #
-      # @param options [Hash] Options for calling the prepare_mint_to method.
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for calling the compose_mint_to method.
       # @return [String] The signature of the transaction.
-      def mint_to(**options)
-        tx = prepare_mint_to(**options)
+      def mint_to(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_mint_to(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
 
-        @connection.send_transaction(tx.serialize)
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:mint_authority]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+
+        tx
       end
 
       # Prepares a mint to instruction and returns the signed transaction.
       #
       # @param [Integer] amount The amount of tokens to mint.
-      # @param [PublicKey, Keypair, String] payer The payer of the transaction.
-      # @param [PublicKey, Keypair, String] mint The mint of the token.
-      # @param [PublicKey, Keypair, String] destination The destination of the token.
-      # @param [PublicKey, Keypair, String] mint_authority The mint authority of the token.
-      # @return [Solace::Transaction] The signed transaction.
+      # @param [#to_s, PublicKey] mint The mint of the token.
+      # @param [#to_s, PublicKey] destination The destination of the token.
+      # @param [#to_s, PublicKey] mint_authority The mint authority of the token.
+      # @return [TransactionComposer] A composer with required instructions.
       #
-      # rubocop:disable Metrics/MethodLength
-      def prepare_mint_to(
-        payer:,
+      # @param [Boolean] ensure_account
+      def compose_mint_to(
         mint:,
-        destination:,
         amount:,
+        destination:,
         mint_authority:
       )
-        accounts = [
-          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(
+        ix = Composers::SplTokenProgramMintToComposer.new(
           amount: amount,
-          mint_authority_index: 1,
-          mint_index: 2,
-          destination_index: 3,
-          program_index: 4
+          mint: mint,
+          destination: destination,
+          mint_authority: mint_authority
         )
 
-        message = Solace::Message.new(
-          header: [2, 0, 1],
-          accounts: accounts,
-          instructions: [ix],
-          recent_blockhash: connection.get_latest_blockhash[0]
-        )
-
-        tx = Solace::Transaction.new(message: message)
-        tx.sign(payer, mint_authority)
-
-        tx
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(ix)
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Transfers tokens from one account to another
       #
-      # @param options [Hash] Options for calling the prepare_transfer method.
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for calling the compose_transfer method.
       # @return [String] The signature of the transaction.
-      def transfer(**options)
-        tx = prepare_transfer(**options)
+      def transfer(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_transfer(**composer_opts)
+
+        yield composer if block_given?
 
-        @connection.send_transaction(tx.serialize)
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:owner]
+          )
+
+          connection.send_transaction(tx.serialize) if execute
+        end
+        tx
       end
 
       # Prepares a transfer instruction and returns the signed transaction.
       #
-      # @param payer [Solace::Keypair] The keypair that will pay for fees and rent.
-      # @param source [String] The source token account address.
-      # @param destination [String] The destination token account address.
+      # @param source [#to_s, PublicKey] The source token account address.
+      # @param destination [#to_s, PublicKey] The destination token account address.
       # @param amount [Integer] The number of tokens to transfer.
-      # @param owner [Solace::Keypair] The keypair of the owner of the source account.
-      # @return [Solace::Transaction] The signed transaction.
+      # @param owner [#to_s, PublicKey] The keypair of the owner of the source account.
+      # @return [TransactionComposer] A composer with required instructions.
       #
-      # rubocop:disable Metrics/MethodLength
-      def prepare_transfer(
+      def compose_transfer(
         amount:,
-        payer:,
         source:,
         destination:,
         owner:
       )
-        accounts = [
-          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(
+        ix = Composers::SplTokenProgramTransferComposer.new(
           amount: amount,
-          owner_index: 1,
-          source_index: 2,
-          destination_index: 3,
-          program_index: 4
+          owner: owner,
+          source: source,
+          destination: destination
         )
 
-        message = Solace::Message.new(
-          header: [2, 0, 1],
-          accounts: accounts,
-          instructions: [ix],
-          recent_blockhash: connection.get_latest_blockhash[0]
-        )
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(ix)
+      end
+
+      # Transfers tokens with decimal precision and validation checks
+      #
+      # @param payer [#to_s, PublicKey] The keypair that will pay for fees and rent.
+      # @param sign [Boolean] Whether to sign the transaction.
+      # @param execute [Boolean] Whether to execute the transaction.
+      # @param composer_opts [Hash] Options for calling the compose_transfer_checked method.
+      # @return [String] The signature of the transaction.
+      def transfer_checked(
+        payer:,
+        sign: true,
+        execute: true,
+        **composer_opts
+      )
+        composer = compose_transfer_checked(**composer_opts)
+
+        yield composer if block_given?
+
+        tx = composer
+             .set_fee_payer(payer)
+             .compose_transaction
+
+        if sign
+          tx.sign(
+            payer,
+            composer_opts[:authority]
+          )
 
-        tx = Solace::Transaction.new(message: message)
-        tx.sign(payer, owner)
+          connection.send_transaction(tx.serialize) if execute
+        end
 
         tx
       end
-      # rubocop:enable Metrics/MethodLength
+
+      # Prepares a transfer checked instruction and returns the signed transaction.
+      #
+      # @param amount [Integer] The number of tokens to transfer.
+      # @param decimals [Integer] The number of decimals for the token.
+      # @param from [#to_s, PublicKey] The source token account address.
+      # @param to [#to_s, PublicKey] The destination token account address.
+      # @param mint [#to_s, PublicKey] The mint address
+      # @param authority [#to_s, PublicKey] The keypair of the owner of the source account.
+      # @return [TransactionComposer] A composer with required instructions.
+      def compose_transfer_checked(
+        to:,
+        from:,
+        mint:,
+        authority:,
+        amount:,
+        decimals:
+      )
+        ix = Composers::SplTokenProgramTransferCheckedComposer.new(
+          to: to,
+          from: from,
+          mint: mint,
+          authority: authority,
+          amount: amount,
+          decimals: decimals
+        )
+
+        TransactionComposer
+          .new(connection: connection)
+          .add_instruction(ix)
+      end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/solace/serializers/base_serializer.rb

@@ -1,7 +1,35 @@
 # frozen_string_literal: true
 
 module Solace
-  # Serializers module
+  # The Serializers module contains classes for converting data structures to and
+  # from the binary format required by the Solana runtime.
+  #
+  # Solana transactions, messages, and instructions use a compact binary encoding
+  # for efficiency. The serializers in this module handle the conversion between
+  # Ruby objects and this binary format, including proper handling of:
+  # - Compact array encoding
+  # - Account key serialization
+  # - Instruction data packing
+  # - Message header construction
+  #
+  # Each serializer corresponds to a specific data structure:
+  # - {Solace::Serializers::TransactionSerializer} - Complete transactions
+  # - {Solace::Serializers::MessageSerializer} - Transaction messages
+  # - {Solace::Serializers::InstructionSerializer} - Individual instructions
+  # - {Solace::Serializers::AddressLookupTableSerializer} - Address lookup tables
+  #
+  # Each deserializer handles the inverse operation, converting binary data:
+  # - {Solace::Serializers::TransactionDeserializer}
+  # - {Solace::Serializers::MessageDeserializer}
+  # - {Solace::Serializers::InstructionDeserializer}
+  # - {Solace::Serializers::AddressLookupTableDeserializer}
+  #
+  # These utilities are primarily used internally by other parts of the gem, but
+  # can also be used directly for advanced use cases.
+  #
+  # @see Solace::Serializers::BaseSerializer
+  # @see Solace::Serializers::BaseDeserializer
+  # @since 0.0.1
   module Serializers
     # Autoload serializers
     autoload :TransactionSerializer, 'solace/serializers/transaction_serializer'

data/lib/solace/tokens/token.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Solace
+  module Tokens
+    # Represents a Solana token with its metadata.
+    #
+    # A token object encapsulates the symbol and associated metadata for a Solana token. It provides
+    # dynamic access to metadata attributes via method calls. This class is used within the Solace::Tokens
+    # module to represent individual tokens loaded from a YAML configuration file.
+    #
+    # @since 0.1.0
+    class Token
+      attr_reader :symbol, :metadata
+
+      # Initializes a new Token instance.
+      #
+      # @param symbol [String] The symbol of the token (e.g., 'USDC')
+      # @param metadata [Hash] A hash containing the token's metadata attributes
+      # @return [self] The initialized Token object
+      def initialize(symbol, metadata)
+        @symbol = symbol
+        @metadata = metadata.transform_keys(&:to_sym)
+      end
+
+      # Dynamically access metadata attributes.
+      #
+      # @param name [Symbol] The name of the metadata attribute
+      # @return [Object] The value of the metadata attribute if it exists
+      # @raise [NoMethodError] If the attribute does not exist
+      def method_missing(name, *)
+        return metadata[name] if metadata.key?(name)
+
+        super
+      end
+
+      # Check if a metadata attribute exists.
+      #
+      # @param name [Symbol] The name of the metadata attribute
+      # @param _include_private [Boolean] Whether to include private methods (not used)
+      # @return [Boolean] True if the attribute exists, false otherwise
+      def respond_to_missing?(name, _include_private = false)
+        metadata.key?(name) || super
+      end
+
+      # Returns a string representation of the Token object.
+      #
+      # @return [String] The string representation of the Token
+      def inspect
+        "#<Solace::Token #{symbol} #{metadata.inspect}>"
+      end
+    end
+  end
+end