solace 0.0.10 → 0.1.1

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.

data/lib/solace/transaction_composer.rb

@@ -2,7 +2,16 @@
 
 # lib/solace/transaction_composer.rb
 module Solace
-  # Composes multi-instruction transactions with automatic account management
+  # Composes transactions with automatic account management and instruction building.
+  #
+  # This class allows you to add multiple instruction composers, manage account contexts,
+  # and build a complete transaction in a flexible way. It is a high-level abstraction over
+  # the process of creating Solana transactions, making it easier to work with complex
+  # transaction scenarios.
+  #
+  # For most use cases, you will create an instance of this class, add instruction composers,
+  # and then call the `compose_transaction` method to build the final transaction. That said,
+  # all of the individual pieces are also accessible for more advanced use cases.
   #
   # @example
   #   # Initialize a transaction composer
@@ -38,6 +47,18 @@ module Solace
   #   # Sign the transaction with all required signers
   #   tx.sign(*required_signers)
   #
+  # @example
+  #   # Chaining methods will return the composer itself for further modifications. The add, prepend,
+  #   # and insert methods allow for dynamic insertion of instruction composers at required positions.
+  #   transaction_composer = Solace::TransactionComposer
+  #     .new(connection: connection)
+  #     .add_instruction(instruction_composer_1)
+  #     .prepend_instruction(instruction_composer_2)
+  #     .insert_instruction(1, instruction_composer_3)
+  #     .set_fee_payer(fee_payer_pubkey)
+  #     .compose_transaction
+  #
+  # @see Solace::Composers::Base
   # @since 0.0.6
   class TransactionComposer
     # @!attribute connection
@@ -71,9 +92,62 @@ module Solace
       self
     end
 
+    # Prepend an instruction composer to the transaction
+    #
+    # @param composer [Composers::Base] The instruction composer
+    # @return [TransactionComposer] Self for chaining
+    #
+    # @since 0.1.0
+    def prepend_instruction(composer)
+      merge_accounts(composer.account_context)
+      instruction_composers.unshift(composer)
+      self
+    end
+
+    # Insert an instruction composer at a specific index
+    #
+    # @param index [Integer] The index to insert at
+    # @param composer [Composers::Base] The instruction composer
+    # @return [TransactionComposer] Self for chaining
+    #
+    # @since 0.1.0
+    def insert_instruction(index, composer)
+      merge_accounts(composer.account_context)
+      instruction_composers.insert(index, composer)
+      self
+    end
+
+    # Merge another TransactionComposer into this one
+    #
+    # @param other [TransactionComposer] The other composer to merge
+    # @param placement [Symbol] :add to append, :prepend to prepend
+    # @param index [Integer, nil] The index to insert at if placement is :insert
+    # @return [TransactionComposer] Self for chaining
+    #
+    # @since 0.1.0
+    def merge(other, placement: :add, index: nil)
+      merge_accounts(other.context)
+
+      case placement
+      when :add
+        # Appends the other's instruction composers to this one's list
+        instruction_composers.concat(other.instruction_composers)
+      when :insert
+        # Inserts the other's instruction composers at the specified index
+        instruction_composers.insert(index, *other.instruction_composers)
+      when :prepend
+        # Prepends the other's instruction composers to this one's list
+        instruction_composers.unshift(*other.instruction_composers)
+      else
+        raise ArgumentError, "Invalid placement option: #{placement}"
+      end
+
+      self
+    end
+
     # Set the fee payer for the transaction
     #
-    # @param pubkey [String, Solace::PublicKey, Solace::Keypair] The fee payer pubkey
+    # @param pubkey [#to_s, PublicKey] The fee payer pubkey
     # @return [TransactionComposer] Self for chaining
     def set_fee_payer(pubkey)
       context.set_fee_payer(pubkey.to_s)
@@ -82,7 +156,7 @@ module Solace
 
     # Compose the final transaction
     #
-    # @return [Solace::Transaction] The composed transaction (unsigned)
+    # @return [Transaction] The composed transaction (unsigned)
     def compose_transaction
       context.compile
 

data/lib/solace/utils/account_context.rb

@@ -199,7 +199,7 @@ module Solace
 
       # Add or merge an account into the context
       #
-      # @param pubkey [String, Solace::PublicKey, Solace::Keypair] The public key of the account
+      # @param pubkey [#to_s, PublicKey] The public key of the account
       # @param signer [Boolean] Whether the account is a signer
       # @param writable [Boolean] Whether the account is writable
       # @param [Boolean] fee_payer

data/lib/solace/utils/codecs.rb

@@ -6,6 +6,23 @@ require 'base58'
 require 'stringio'
 
 module Solace
+  # The Utils module contains utility classes and helper methods used throughout
+  # the Solace gem.
+  #
+  # This module provides foundational utilities that support the core functionality
+  # of the gem, including:
+  # - {Solace::Utils::AccountContext} - Account management for transactions
+  # - {Solace::Utils::Codecs} - Encoding and decoding utilities
+  # - {Solace::Utils::Curve25519Dalek} - Cryptographic operations via FFI
+  # - {Solace::Utils::PDA} - Program Derived Address generation
+  # - {Solace::Utils::RPCClient} - Low-level RPC communication
+  #
+  # These utilities are primarily used internally by other parts of the gem, but
+  # can also be used directly for advanced use cases.
+  #
+  # @see Solace::Connection
+  # @see Solace::Keypair
+  # @since 0.0.1
   module Utils
     # Module for encoding and decoding data
     #

data/lib/solace/utils/pda.rb

@@ -5,13 +5,21 @@ require 'digest'
 
 module Solace
   module Utils
-    # Module for generating program addresses
+    # Raised when Program Derived Address (PDA) generation fails.
     #
-    # This module provides methods for generating program addresses from seeds and program IDs. It interfaces
-    # with the Curve25519 Dalek library to check if a point is on the curve. It also provides a method for
-    # converting seeds to bytes and a method for checking if a string looks like a base58 address.
+    # This error is raised when attempting to derive a PDA that is invalid, typically
+    # because the seeds and program ID combination results in a point that lies on
+    # the Ed25519 curve (PDAs must be off-curve). This is a rare occurrence but can
+    # happen with certain seed combinations.
     #
-    # @see Solace::Utils::Curve25519Dalek
+    # @example Handling invalid PDA
+    #   begin
+    #     pda = Solace::Utils::PDA.find_program_address(seeds, program_id)
+    #   rescue Solace::Utils::PDA::InvalidPDAError => e
+    #     puts "Failed to derive PDA: #{e.message}"
+    #   end
+    #
+    # @see Solace::Utils::PDA
     # @since 0.0.1
     module PDA
       # InvalidPDAError is an error raised when an invalid PDA is generated

data/lib/solace/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# Solace::VERSION is the version of the Solace gem
 module Solace
-  VERSION = '0.0.10'
+  # Latest version of the Solace gem.
+  # @since 0.1.1
+  VERSION = '0.1.1'
 end

data/lib/solace.rb

@@ -1,9 +1,37 @@
 # frozen_string_literal: true
 
-# 🏷️ Version
+# Solace is a Ruby gem for interacting with the Solana blockchain.
+#
+# This gem provides a comprehensive toolkit for building, signing, and sending
+# transactions to Solana RPC nodes. It includes utilities for managing keypairs,
+# composing complex instructions, serializing data, and interacting with
+# on-chain programs like the System Program, SPL Token Program, and Associated
+# Token Account Program.
+#
+# The gem is designed to be modular and extensible, with clear separation between
+# low-level primitives (instructions, serializers) and high-level abstractions
+# (composers, programs).
+#
+# @example Basic usage
+#   # Connect to a Solana RPC node
+#   connection = Solace::Connection.new('https://api.mainnet-beta.solana.com')
+#
+#   # Generate a keypair
+#   keypair = Solace::Keypair.generate
+#
+#   # Check balance
+#   balance = connection.get_balance(keypair.public_key)
+#
+# @see https://docs.solana.com/
+# @see https://github.com/zarpay/solace
+# @author Sebastian Scholl
+# @since 0.0.1
+module Solace; end
+
+# Version
 require_relative 'solace/version'
 
-# 🛠️ Helpers
+# Helpers
 require_relative 'solace/errors'
 require_relative 'solace/constants'
 require_relative 'solace/connection'
@@ -13,11 +41,14 @@ require_relative 'solace/utils/account_context'
 require_relative 'solace/utils/curve25519_dalek'
 require_relative 'solace/concerns/binary_serializable'
 
-# ✨ Serializers
+# Tokens
+require_relative 'solace/tokens'
+
+# Serializers
 require_relative 'solace/serializers/base_serializer'
 require_relative 'solace/serializers/base_deserializer'
 
-# 🧬 Primitives
+# Primitives
 require_relative 'solace/keypair'
 require_relative 'solace/public_key'
 require_relative 'solace/transaction'
@@ -30,16 +61,12 @@ require_relative 'solace/transaction_composer'
 require_relative 'solace/programs/base'
 require_relative 'solace/composers/base'
 
-# 📦 Composers
-#
-# Glob require all composers
+# Composers
 Dir[File.join(__dir__, 'solace/composers', '**', '*.rb')].each { |file| require file }
 
-# 📦 Instructions (Builders)
-#
-# Glob require all instructions
+# Instructions (Builders)
 Dir[File.join(__dir__, 'solace/instructions', '**', '*.rb')].each { |file| require file }
 
-# 📦 Programs
+# Programs
 require_relative 'solace/programs/spl_token'
 require_relative 'solace/programs/associated_token_account'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solace
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.1.1
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: tty-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Ruby library for working with Solana blockchain. Provides both low-level
   instruction builders and high-level program clients for interacting with Solana
   programs.
@@ -95,7 +109,11 @@ files:
 - lib/solace/address_lookup_table.rb
 - lib/solace/composers/associated_token_account_program_create_account_composer.rb
 - lib/solace/composers/base.rb
+- lib/solace/composers/spl_token_program_initialize_mint_composer.rb
+- lib/solace/composers/spl_token_program_mint_to_composer.rb
 - lib/solace/composers/spl_token_program_transfer_checked_composer.rb
+- lib/solace/composers/spl_token_program_transfer_composer.rb
+- lib/solace/composers/system_program_create_account_composer.rb
 - lib/solace/composers/system_program_transfer_composer.rb
 - lib/solace/concerns/binary_serializable.rb
 - lib/solace/connection.rb
@@ -130,6 +148,8 @@ files:
 - lib/solace/serializers/message_serializer.rb
 - lib/solace/serializers/transaction_deserializer.rb
 - lib/solace/serializers/transaction_serializer.rb
+- lib/solace/tokens.rb
+- lib/solace/tokens/token.rb
 - lib/solace/transaction.rb
 - lib/solace/transaction_composer.rb
 - lib/solace/utils/account_context.rb