solace 0.0.10 → 0.1.0

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

data/lib/solace/tokens.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Solace
+  # Represents a Solana token with its metadata.
+  #
+  # A tokens 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.
+  #
+  # @example Load tokens for the 'mainnet' network
+  #   Solace::Tokens.load(path: 'path/to/tokens.yml', network: 'mainnet')
+  #
+  # @example Access a specific token
+  #   usdc = Solace::Tokens.fetch('USDC')
+  #   puts usdc.address
+  #
+  # @example Query tokens by criteria
+  #   stablecoins = Solace::Tokens.where(type: 'stablecoin')
+  #
+  # @since 0.1.0
+  module Tokens
+    autoload :Token, File.expand_path('tokens/token', __dir__)
+
+    # Load tokens from a YAML file for a specific network
+    #
+    # @param path [String] Path to the YAML file
+    # @param network [String, Symbol] Network name (e.g., 'mainnet', 'testnet')
+    # @return [void]
+    def self.load(path:, network:)
+      data = YAML.load_file(path)
+      tokens = data.fetch(network.to_s) do
+        raise ArgumentError, "Network '#{network}' not found in config"
+      end
+
+      # Clear previous constants and registry
+      clear!
+
+      @registry = {}
+
+      tokens.each do |symbol, attrs|
+        token = Solace::Tokens::Token.new(symbol, attrs)
+        const_set(symbol, token)
+        @registry[symbol.to_s] = token
+      end
+    end
+
+    # Clear loaded tokens
+    #
+    # @return [void]
+    def self.clear!
+      (constants - [:Token]).each { |c| remove_const(c) }
+      @registry = {}
+    end
+
+    # Get all loaded tokens
+    #
+    # @return [Array<Solace::Tokens::Token>]
+    def self.all
+      @registry.values
+    end
+
+    # Fetch a token by its symbol
+    #
+    # @param symbol [String] The symbol of the token
+    # @return [Solace::Tokens::Token, nil] The token object or nil if not found
+    def self.fetch(symbol)
+      @registry[symbol.to_s]
+    end
+
+    # Query tokens based on criteria
+    #
+    # @param criteria [Hash{Symbol => Object}] Key-value pairs to filter tokens
+    # @return [Array<Solace::Tokens::Token>] Array of tokens matching the criteria
+    def self.where(criteria = {})
+      return all if criteria.empty?
+
+      normalized = criteria.transform_keys(&:to_sym)
+
+      all.select do |token|
+        normalized.all? { |k, v| token.metadata[k] == v }
+      end
+    end
+  end
+end

data/lib/solace/transaction.rb

@@ -6,17 +6,17 @@ module Solace
   #
   # Transactions are the basic building blocks of Solana. They contain a message and an array of signatures. The
   # message contains the instructions to be executed and the accounts that are used by the instructions. The signatures
-  # are the signatures of the accounts that are used by the instructions. This class provides methods for signing,
-  # serializing, and deserializing transactions.
+  # are the required signatures of the accounts that are used by the instructions. This class provides methods for
+  # signing, serializing, and deserializing transactions.
   #
   # The BufferLayout is:
-  #   - [Signatures (variable length)]
-  #   - [Version (1 byte)] (if versioned)
-  #   - [Message header (3 bytes)]
-  #   - [Account keys (variable length)]
-  #   - [Recent blockhash (32 bytes)]
-  #   - [Instructions (variable length)]
-  #   - [Address lookup table (variable length)] (if versioned)
+  #   - Signatures (variable length)
+  #   - Version (1 byte if versioned)
+  #   - Message header (3 bytes)
+  #   - Account keys (variable length)
+  #   - Recent blockhash (32 bytes)
+  #   - Instructions (variable length)
+  #   - Address lookup table (variable length if versioned)
   #
   # @example
   #   # Create a new transaction
@@ -32,31 +32,26 @@ module Solace
   class Transaction
     include Solace::Concerns::BinarySerializable
 
-    # @!attribute SERIALIZER
-    #   @return [Solace::Serializers::TransactionSerializer] The serializer for the transaction
+    # The serializer for the transaction
     SERIALIZER = Solace::Serializers::TransactionSerializer
 
-    # @!attribute DESERIALIZER
-    #   @return [Solace::Serializers::TransactionDeserializer] The deserializer for the transaction
+    # The deserializer for the transaction
     DESERIALIZER = Solace::Serializers::TransactionDeserializer
 
-    # @!attribute SIGNATURE_PLACEHOLDER
-    #   @return [String] Placeholder for a signature in the transaction
+    # Placeholder for a signature in the transaction
     SIGNATURE_PLACEHOLDER = Solace::Utils::Codecs.base58_to_binary('1' * 64)
 
-    # @!attribute  [rw] signatures
-    #   @return [Array<String>] Signatures of the transaction (binary)
+    # @return [Array<String>] Signatures of the transaction (binary)
     attr_accessor :signatures
 
-    # @!attribute  [rw] message
-    #   @return [Solace::Message] Message of the transaction
+    # @return [Solace::Message] Message of the transaction
     attr_accessor :message
 
     class << self
       # Deserialize a base64 encoded transaction into a Solace::Transaction object
       #
       # @param base64_tx [String] The base64 encoded transaction
-      # @return [Solace::Transaction] The deserialized transaction
+      # @return [Transaction] The deserialized transaction
       def from(base64_tx)
         DESERIALIZER.new(Solace::Utils::Codecs.base64_to_bytestream(base64_tx)).call
       end
@@ -64,7 +59,7 @@ module Solace
 
     # Initialize a new transaction
     #
-    # @return [Solace::Transaction] The new transaction object
+    # @return [Transaction] The new transaction object
     def initialize(
       signatures: [],
       message: Solace::Message.new
@@ -74,6 +69,14 @@ module Solace
       @message = message
     end
 
+    # Returns the first signature of the transaction (signature of the transaction fee payer)
+    #
+    # @return [String, nil] The first signature of the transaction or nil if there are no signatures
+    # @since 0.1.0
+    def signature
+      Utils::Codecs.binary_to_base58(signatures.first) unless signatures.empty?
+    end
+
     # Sign the transaction
     #
     # Calls sign_and_update_signatures for each keypair passed in.