solace 0.0.10 → 0.1.0

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.0
+  VERSION = '0.1.0'
 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.0
 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