solace 0.0.10 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 669a517f72b280a594613b55fcd3e86c6e0f7ef9ba3d6633b0edfbd5dc5b0a0c
-  data.tar.gz: a542d3ce4edaeb81d3c6e8aee35fadfb9df4a4cd5a618f9f643ac46544f4cc65
+  metadata.gz: a9bca105aef6d20a1a5b6d5dc6b2fce8c7a8523c9a2a24afd3ad15bf36efbb55
+  data.tar.gz: e6a70370368a4822249bf7c912f70f54a02ce5389ef128e40acdc769b315ebae
 SHA512:
-  metadata.gz: c43a013d3007b0853a5501c96dc7b2e737b0aefa5d35844008127ddcdfd59c0770e4ceaf9db99086aa69c294ae20563b022b3d6e370be84701c9fe8a453ce25d
-  data.tar.gz: 42eab84e19bf00741e1c29a50facb39966f3020a005c2baa3ee63d545d6a43bcc267cb86d17ba09cb05be6d64875504c9a557275f9c365f6ce5764ce95501baf
+  metadata.gz: 44fc38f19753ed736c05e1ba58bc7799fbe96d736553e3df220cfa38cae60a0dc2d2ecb3459990300efc108d56b9ec0ae8ce4fc552c39b31cf668e54878f52bd
+  data.tar.gz: 4ffe860837dc85e925f308fdff68129ba01cdc41fb192495af4926bbd91328c62847f862c2847a819c9615cd1b223d512910a421713ee64f9b038bee25def482

data/CHANGELOG

@@ -1,46 +1,139 @@
 # 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. 
+
+1.
 
 ### Changed
- 
+
 ### Fixed
 ```
 
-## [0.0.10] - yyyy-mm-dd
-  
+Got it — here’s your changelog tidied up for clarity and consistency without changing any of the substance. I only fixed grammar/typos and tightened phrasing.
+
+---
+
+## [0.1.1] - 2025-05-11
+
 ### Added
-1. 
+
+1. Added support to inject encoding externally to get the data with respective encoding.
+
+## [0.1.0] - 2025-18-10
+
+**NOTE (Breaking):**
+All previous `prepare_*` Program methods have been renamed to `compose_*` and now return an **unsigned composer instance**. This enables composition and extensibility that weren’t possible when methods returned a signed transaction that was only editable via low-level manipulation.
+Additionally, unless explicitly required by a composer’s instruction, the `payer:` keyword has been removed from the new `compose_*` methods and is instead only used in their execution counterparts (e.g., `compose_mint_to` → `mint_to`). This allows specifying the fee payer when building the final transaction, while keeping composition steps payer-agnostic.
+
+### Added
+
+1. **`Solace::Tokens`** — a structured registry and lookup system for Solana token metadata.
+
+   - Developers can define token details via a YAML configuration file scoped by network (e.g., `mainnet`, `devnet`).
+   - Programmatic access to token metadata:
+
+     ```ruby
+     Solace::Tokens.load(path: 'tokens.yml', network: :devnet)
+     Solace::Tokens::USDC.decimals  # => 6
+     Solace::Tokens.fetch('USDC')   # => <Solace::Tokens::Token ...>
+     Solace::Tokens.where(decimals: 6)
+     ```
+
+   - Dynamically registers constants for each token symbol (`USDC`, `SOL`, etc.).
+   - Safety improvements to preserve internal constants (`Token`) during reloads.
+
+2. **`SystemProgramCreateAccountComposer`** — composer for building account creation flows via the Solana System Program.
+
+   - Wraps `SystemProgram::CreateAccountInstruction`.
+   - Handles lamport allocation, rent exemption, and ownership assignment.
+   - Simplifies creation of system-owned and program-owned accounts.
+
+3. **`SplTokenProgramInitializeMintComposer`** — composer for initializing new SPL Token mints.
+
+   - Wraps `SplToken::InitializeMintInstruction`.
+   - Supports decimals, mint authority, and optional freeze authority.
+   - Designed to pair with `SystemProgramCreateAccountComposer` for one-transaction mint creation.
+
+4. **`SplTokenProgramMintToComposer`** — composer for minting tokens to an ATA.
+
+   - Wraps `SplToken::MintToInstruction`.
+   - Supports minting tokens to a destination ATA.
+
+5. **`SplTokenProgramTransferComposer`** — composer for transferring tokens.
+
+   - Wraps `SplToken::TransferInstruction`.
+   - Supports sending SPL tokens.
+
+6. **`Solace::Connection`** — cached blockhash accessors.
+
+   - Added `last_fetched_blockhash` and `last_fetched_block_height`.
+   - Stores the most recently retrieved blockhash and corresponding `lastValidBlockHeight`.
+   - Enables reuse without re-fetching between sequential transactions.
+   - `get_latest_blockhash` now sets these values automatically.
+
+7. **`TransactionComposer`** — instruction ordering helpers.
+
+   - Added `prepend_instruction` and `insert_instruction` for finer control of instruction order.
+
+8. **`Transaction`** — signature helper.
+
+   - Added `transaction.signature` to get the signature from a signed transaction.
+
+9. **Program method options** — higher-level control.
+
+   - Added `execute`, `sign`, and a yield block to relevant Program methods for flow control and composer access.
 
 ### Changed
-2. Updated `build_instructions` method on `TransactionComposer` to flatten the array, allowing composers to return multiple instructions when relevant (i.e. creating an account and then writing to it).
-3. Changed get_latest_blockhash to use the expected comittment level by the connection or passed options and return array (blockhash and lastValidBlockheight)
-4. Changed default commitment level to `processed` in `Solace::Connection`.
+
+1. `TransactionComposer#build_instructions` now flattens arrays so composers can return multiple instructions (e.g., create an account then initialize it).
+
+2. `Connection#get_latest_blockhash` now uses the connection’s expected commitment (or provided options) and returns `[blockhash, lastValidBlockheight]`.
+
+3. Default commitment level changed to `processed` in `Solace::Connection`.
+
+4. SPL Program: renamed/adjusted kwargs for `compose_create_mint` and moved signing logic to `create_mint`.
+
+5. SPL Program: `compose_mint_to` moved signing logic to `mint_to`.
+
+6. SPL Program: `compose_transfer` moved signing logic to `transfer`.
+
+7. SPL Program: `create_mint`, `compose_create_mint`, and `compose_create_associated_token_account` now accept separate `funder` and `payer` keys. Both may be the same value, but splitting them allows one account to pay transaction fees while another covers rent exemption.
+
+8. All executable Program methods now return the **Solace transaction instance** instead of an encoded signature.
+
+9. Updated `test/bootstrap.rb` to use composers for setting up test fixtures in a single transaction.
 
 ### Fixed
 
+- Improved token loading safety in `Solace::Tokens` to prevent internal constant removal during reloads.
+
+---
+
 ## [0.0.9] - 2025-08-12
-  
+
 ### Added
+
 1. Added `get_program_accounts` to `Solace::Connection`.
 
 ### Changed
- 
+
 ### Fixed
+
 1. Removed use of the `try` method for supporting non-rails environments.
 
 ## [0.0.8] - 2025-08-11
-  
+
 ### Added
+
 1. Added `load` method to `Solace::Constants` to load constants from a YAML file. This method allows for loading constants from a YAML file (i.e. custom program addresses and mint accounts).
 2. Added `to_s` and `address` method to `Solace::Keypair` and `Solace::PublicKey` to return the public key as a Base58 string.
 3. Added `get_signature_status` and `get_signature_statuses` to `Solace::Connection`.
@@ -48,39 +141,46 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 5. Added `Errors` module to `Solace::Utils` to handle errors from the HTTP requests made to the Solana RPC node.
 
 ### Changed
+
 1. All methods that take a `Solace::Keypair` or `Solace::Pubkey` where an address is needed now also accept a plain string address. This prevents the need of creating instances of the classes when all that is needed is the address. This is with the exception of the low-level instruction builders, which only expect the correct data and indicies with no required casting.
 2. Changed `wait_for_confirmed_signature` method to accept a `timeout`, `interval`, and `commitment` arguments.
- 
+
 ### Fixed
+
 1. Fixed `get_or_create_address` method in `Solace::Programs::AssociatedTokenAccount` to return the address of the associated token account if it already exists by checking if there is any data at the address.
 
 ## [0.0.7] - 2025-08-09
-  
+
 ### Added
+
 1. Added `AssociatedTokenAccountProgramCreateAccountComposer` with tests.
 
 ### Changed
-1. Updated `AssociatedTokenAccount` to use `AssociatedTokenAccountProgramCreateAccountComposer` and sign the transaction in the `create_associated_token_account` method instead of the `prepare_create_associated_token_account` method.
- 
+
+1. Updated `AssociatedTokenAccount` to use `AssociatedTokenAccountProgramCreateAccountComposer` and sign the transaction in the `create_associated_token_account` method instead of the `compose_create_associated_token_account` method.
+
 ### Fixed
 
 ## [0.0.6] - 2025-08-07
-  
+
 ### Added
+
 1. Added `from_address` method to `Solace::PublicKey`.
 2. Change docs on most methods to include an `@example` section.
 
 ### Changed
+
 1. Change `private_key` method on Keypair to `pivate_key_bytes`
 2. Change README to include a practical example of using composers.
- 
+
 ### Fixed
-1. Fix `encode_signatures` method in `Solace::Serializers::TransactionSerializer` to correctly count the number of signatures using the `num_required_signatures` field in the message.
 
+1. Fix `encode_signatures` method in `Solace::Serializers::TransactionSerializer` to correctly count the number of signatures using the `num_required_signatures` field in the message.
 
 ## [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`.
@@ -94,14 +194,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ### 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. 
+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/. 
+Soon, YARD documentation will be added to the SDK and published to https://solace-rb.github.io/solace/.
 
 Stay tuned.
- 
+
 ### Fixed
 
 N/A

data/README.md

@@ -1,4 +1,5 @@
 # Solace Ruby SDK Documentation
+
 A Ruby SDK for the Solana blockchain.
 
 ## Overview
@@ -10,9 +11,9 @@ Solace is a comprehensive Ruby SDK for interacting with the Solana blockchain. I
 The Solace SDK is organized into several key layers:
 
 ### 1. **Core Classes** (Low-Level)
-- **Keypair/PublicKey**: Ed25519 cryptographic operations
+- **Keypair, PublicKey**: Ed25519 cryptographic operations
 - **Connection**: RPC client for Solana nodes
-- **Transaction/Message/Instruction/AddressLookupTable**: Transaction building blocks
+- **Transaction, Message, Instruction, AddressLookupTable**: Transaction building blocks
 - **Serializers**: Binary serialization/deserialization system
 
 ### 2. **Instruction Builders** (Low-Level)
@@ -34,7 +35,8 @@ The Solace SDK is organized into several key layers:
 - **Codecs**: Base58/Base64 encoding, compact integers, little-endian encoding
 - **PDA**: Program Derived Address generation
 - **Curve25519**: Native curve operations via FFI
-- **More...**: Checkout `lib/solace/utils` 
+- **Token**: Classes for loading and accessing token data
+- **More...**: Checkout `lib/solace/utils`
 
 ## Core Components
 
@@ -199,7 +201,7 @@ For more control, use "prepare" methods that return signed transactions without
 
 ```ruby
 # Prepare transaction without sending
-transaction = spl_token.prepare_create_mint(
+transaction = spl_token.compose_create_mint(
   payer: payer_keypair,
   decimals: 6,
   mint_authority: authority_keypair,
@@ -317,10 +319,10 @@ Composers are intended to be extended by developers with custom instruction comp
 class MyProgramComposer < Solace::Composers::Base
   # All keyword arguments are passed to the constructor and available
   # as a `params` hash.
-  # 
+  #
   # The setup_accounts method is called automatically by the transaction composer
-  # during compilation and should be used to add accounts to the account_context 
-  # with the appropriate access permissions. Conditional logic is fine here given 
+  # during compilation and should be used to add accounts to the account_context
+  # with the appropriate access permissions. Conditional logic is fine here given
   # and available params to determine the access permissions.
   def setup_accounts
     account_context.add_writable_signer(params[:from])
@@ -330,7 +332,7 @@ class MyProgramComposer < Solace::Composers::Base
 
   # The build_instruction method is called automatically by the transaction composer
   # during compilation and should be used to build the instruction using an instruction builder.
-  # 
+  #
   # The passed context to the build_instruction method provides the indices of all accounts
   # that were added to the account_context in the setup_accounts method. These are accessible
   # by the index_of method of the context using the account address as a parameter.

data/lib/solace/composers/base.rb

@@ -1,6 +1,41 @@
 # frozen_string_literal: true
 
 module Solace
+  # The Composers module contains classes responsible for building and ordering
+  # the accounts and instructions required for common Solana operations.
+  #
+  # Composers abstract away the complexity of account ordering, permission management,
+  # and instruction data construction. They provide a high-level interface for
+  # creating instructions that interact with on-chain programs. Each composer
+  # corresponds to a specific program instruction (e.g., transferring SOL,
+  # minting tokens, creating accounts).
+  #
+  # Composers handle:
+  # - Account resolution and ordering
+  # - Permission flags (signer, writable)
+  # - Account deduplication
+  # - Instruction data formatting
+  #
+  # @example Using a composer
+  #   # Initialize a transaction composer
+  #   composer = TransactionComposer.new(connection: connection)
+  #
+  #   # Create a transfer instruction composer
+  #   ix = Solace::Composers::SystemProgramTransferComposer.new(
+  #     from: sender.public_key,
+  #     to: recipient.public_key,
+  #     lamports: 1_000_000
+  #   )
+  #
+  #   # Add the instruction to the transaction composer and compose the transaction
+  #   tx = composer
+  #     .add_instruction(ix)
+  #     .set_fee_payer(sender.public_key)
+  #     .compose_transaction
+  #
+  # @see Solace::TransactionComposer
+  # @see Solace::Composers::Base
+  # @since 0.0.3
   module Composers
     # A Base class for all composers
     #

data/lib/solace/composers/spl_token_program_initialize_mint_composer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for initializing a mint via the SPL Token Program.
+    #
+    # This composer resolves and orders the required accounts for an `InitializeMint` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::SplToken::InitializeMintInstruction`).
+    #
+    # It is used for initializing a new SPL Token mint.
+    #
+    # Required accounts:
+    # - **Mint Account**: the mint account to initialize (writable, non-signer)
+    #
+    # @example Compose and build an initialize_mint instruction
+    #  composer = SplTokenProgramInitializeMintComposer.new(
+    #    decimals: 6,
+    #    mint_authority: mint_authority_pubkey,
+    #    freeze_authority: freeze_authority_pubkey,
+    #    mint_account: mint_address,
+    #  )
+    #
+    # @see Instructions::SplToken::InitializeMintInstruction
+    # @since 0.1.0
+    class SplTokenProgramInitializeMintComposer < Base
+      # Extracts the mint account address from the params
+      #
+      # @return [String] The mint account address
+      def mint_account
+        params[:mint_account].to_s
+      end
+
+      # Returns the rent sysvar address
+      #
+      # @return [String] The rent sysvar address
+      def rent_sysvar
+        Constants::SYSVAR_RENT_PROGRAM_ID.to_s
+      end
+
+      # Returns the spl token program id
+      #
+      # @return [String] The spl token program id
+      def spl_token_program
+        Constants::TOKEN_PROGRAM_ID.to_s
+      end
+
+      # Extracts the mint authority address from the params
+      #
+      # @return [String] The mint authority address
+      def mint_authority
+        params[:mint_authority].to_s
+      end
+
+      # Extracts the freeze authority address from the params
+      #
+      # @return [String] The freeze authority address
+      def freeze_authority
+        params[:freeze_authority]&.to_s
+      end
+
+      # Returns the decimals for the mint
+      #
+      # @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_nonsigner(mint_account)
+        account_context.add_readonly_nonsigner(rent_sysvar)
+        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::InitializeMintInstruction.build(
+          mint_account_index: account_context.index_of(mint_account),
+          rent_sysvar_index: account_context.index_of(rent_sysvar),
+          program_index: account_context.index_of(spl_token_program),
+          decimals: decimals,
+          mint_authority: mint_authority,
+          freeze_authority: freeze_authority
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/spl_token_program_mint_to_composer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a MintTo instruction for the SPL Token Program.
+    #
+    # This composer builds a MintTo instruction that can be added to a transaction to mint tokens
+    # to a specified token account. It is used to mint new tokens for a given mint and destination account.
+    #
+    # Required accounts:
+    #  - **Mint**: The mint account (writable, non-signer)
+    #  - **Destination**: The token account to mint to (writable, non-signer)
+    #  - **Mint Authority**: The mint authority account (readonly, signer)
+    #
+    # @example Build a MintTo instruction
+    #   composer = Solace::Composers::SplTokenProgramMintToComposer.new(
+    #     mint: mint,
+    #     destination: destination,
+    #     mint_authority: mint_authority,
+    #     amount: 100
+    #   )
+    #
+    # @since 0.1.0
+    class SplTokenProgramMintToComposer < Base
+      # Extracts the mint address from the params
+      #
+      # @return [String] The mint address
+      def mint
+        params[:mint].to_s
+      end
+
+      # Extracts the destination address from the params
+      #
+      # @return [String] The destination address
+      def destination
+        params[:destination].to_s
+      end
+
+      # Extracts the mint authority address from the params
+      #
+      # @return [String] The mint authority address
+      def mint_authority
+        params[:mint_authority].to_s
+      end
+
+      # Returns the spl token program id
+      #
+      # @return [String] The spl token program id
+      def spl_token_program
+        Constants::TOKEN_PROGRAM_ID.to_s
+      end
+
+      # Extracts the amount from the params
+      #
+      # @return [Integer] The amount
+      def amount
+        params[:amount].to_i
+      end
+
+      # Setup accounts required for MintTo instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_nonsigner(mint)
+        account_context.add_writable_nonsigner(destination)
+        account_context.add_readonly_signer(mint_authority)
+        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::MintToInstruction.build(
+          amount: amount,
+          mint_index: account_context.index_of(mint),
+          destination_index: account_context.index_of(destination),
+          mint_authority_index: account_context.index_of(mint_authority),
+          program_index: account_context.index_of(spl_token_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/spl_token_program_transfer_composer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a SPL Token Program Transfer instruction.
+    #
+    # This composer resolves and orders the required accounts for a `Transfer` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::SplToken::TransferInstruction`).
+    #
+    # It is used for transferring SPL tokens with decimal precision and validation checks.
+    #
+    # Required accounts:
+    # - **Owner**: token account owner (writable, signer)
+    # - **Source**: source token account (writable, non-signer)
+    # - **Destination**: destination token account (writable, non-signer)
+    #
+    # @example Compose and build a transfer instruction
+    #   composer = SplTokenProgramTransferComposer.new(
+    #     amount: 1_000_000,
+    #     owner: owner_address,
+    #     source: source_address,
+    #     destination: destination_address,
+    #   )
+    #
+    # @see Instructions::SplToken::TransferInstruction
+    # @since 0.1.0
+    class SplTokenProgramTransferComposer < Base
+      # Extracts the owner address from the params
+      #
+      # @return [String] The owner address
+      def owner
+        params[:owner].to_s
+      end
+
+      # Extracts the source associated token address from the params
+      #
+      # @return [String] The source associated token address
+      def source
+        params[:source].to_s
+      end
+
+      # Extracts the destination associated token address from the params
+      #
+      # @return [String] The destination associated token address
+      def destination
+        params[:destination].to_s
+      end
+
+      # Returns the spl token program id
+      #
+      # @return [String] The spl token program id
+      def spl_token_program
+        Constants::TOKEN_PROGRAM_ID.to_s
+      end
+
+      # Returns the lamports to transfer
+      #
+      # @return [Integer] The lamports to transfer
+      def amount
+        params[:amount]
+      end
+
+      # Setup accounts required for transfer instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_signer(owner)
+        account_context.add_writable_nonsigner(source)
+        account_context.add_writable_nonsigner(destination)
+        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::TransferInstruction.build(
+          amount: amount,
+          owner_index: account_context.index_of(owner),
+          source_index: account_context.index_of(source),
+          destination_index: account_context.index_of(destination),
+          program_index: account_context.index_of(spl_token_program)
+        )
+      end
+    end
+  end
+end