solace 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18aca49d63b09deffe93ba871b65d6b816a7c81863b0b0e2b2c2bd29ce709ce6
-  data.tar.gz: 810a45b1324aa282684e4a5d62ea48738ac2b33a6eb87538e2e0458ca2f54593
+  metadata.gz: b2d850b2d501a6bf777043a53e320a2bef57fee4ea47e9a2a08e3331e4695c8f
+  data.tar.gz: 80139c66611fb213d966db7f6ea7468a46fec9b8b6418917995c424627f2998b
 SHA512:
-  metadata.gz: 50eeac609077e873b361fdb8ed34459ccbed1b4e44d52ad911803350ea0d2f0e669fcfcb30bcddd6d20e9f54dade972a50907532a108dae7142ecca8475f42fb
-  data.tar.gz: 5fba491757746aa8fad865bae93941f3469148c6a5fc8cb5c984ebccb79934f1b1c3425184ab37ff2342f6215a1d5b1147a9d04f6d9225a96e7c6b34c38d8b0d
+  metadata.gz: 659cfcfef1750281cb209a0ef13398af0c56c77f0ebe2479380c09d1764cf83eb39c74a08a3fa6234ceb7e9fbd1e97b5abbdd281bee653c39e00c177fea4aa27
+  data.tar.gz: 9d79ebd0a3c418fca8933b533bd5588605a01338327aeb6b8ed5db831497ea5acd5597d5f82a63ed563ae2e857d84a78745a39c2e1b2750b9b5eb0d5d2e2da09

data/CHANGELOG

@@ -20,6 +20,23 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ---
 
+## 0.1.5 - 2026-06-13
+
+### Added
+
+1. Added Token-2022 program support
+2. Added integration tests for the Token-2022 composers
+
+### Changed
+
+1. Decoupled Token-2022 from the SPL composers via a shared mixin
+
+### Fixed
+
+1. Fixed `TransferChecked` instruction layout documentation
+
+---
+
 ## 0.1.3 - 2025-06-11
 
 ### Added

data/README.md

@@ -450,6 +450,66 @@ response = connection.send_transaction(transaction.serialize)
 connection.wait_for_confirmed_signature { response['result'] }
 ```
 
+## Development
+
+### Prerequisites
+
+- **Ruby** (matching `.ruby-version` / `Gemfile.lock`) and **Bundler**
+- **Solana CLI**, which provides `solana-test-validator` and `solana-keygen`. Install with:
+  ```bash
+  sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
+  ```
+  Then add the installer's PATH line to your shell profile (the installer prints the exact `export PATH=...` to use).
+
+### One-time setup
+
+```bash
+# Install Ruby dependencies
+bundle install
+
+# Generate the seven keypair fixtures the test suite expects.
+# test/fixtures/ is gitignored — each developer generates their own.
+mkdir -p test/fixtures
+for name in bob anna payer mint mint-2022 mint-authority fee-collector; do
+  solana-keygen new --no-bip39-passphrase --silent --force -o "test/fixtures/${name}.json"
+done
+
+# Bootstrap the local validator: airdrops SOL to the fixture accounts,
+# creates their ATAs, and creates the test mint. Spins up a
+# solana-test-validator on the side; ledger state persists in ./test-ledger.
+bundle exec rake bootstrap
+```
+
+If you ever need a clean slate, delete `test-ledger/` and re-run `rake bootstrap`.
+
+### Running the tests
+
+```bash
+bundle exec rake test
+```
+
+`rake test` spawns `solana-test-validator` automatically (re-using `./test-ledger`) and tears it down on exit. You can also run a single file:
+
+```bash
+bundle exec rake test test/solace/programs/spl_token_test.rb
+```
+
+To exercise the longer end-to-end flows in `test/usecases/`:
+
+```bash
+bundle exec rake usecases            # all usecases
+bundle exec rake usecases token_mint # a specific one
+```
+
+### Building & installing the gem locally
+
+```bash
+bundle exec rake build      # produces builds/solace-<version>.gem
+bundle exec rake install    # builds and `gem install`s it locally
+```
+
+The native curve25519 library is shipped pre-compiled in `lib/solace/utils/`. You only need `rake compile` (which invokes `cargo`) if you're modifying `ext/curve25519_dalek` — that target cross-builds for every supported platform and requires the corresponding Rust toolchains.
+
 ## Dependencies
 
 - **base58**: Base58 encoding/decoding

data/lib/solace/composers/associated_token_account_program_create_account_composer.rb

@@ -63,11 +63,12 @@ module Solace
         Constants::SYSTEM_PROGRAM_ID.to_s
       end
 
-      # Extracts the token program id from the constants
-      #
-      # @return [String] The token program id
+      # @return [String] The token program id baked into the ATA's create-account
+      #   instruction (defaults to legacy SPL Token; pass +params[:token_program_id]+
+      #   to create a Token-2022 ATA — note the derived ATA address differs too,
+      #   see {Programs::AssociatedTokenAccount.get_address}).
       def token_program_id
-        Constants::TOKEN_PROGRAM_ID.to_s
+        (params[:token_program_id] || Constants::TOKEN_PROGRAM_ID).to_s
       end
 
       # Extracts the associated token account program id from the constants

data/lib/solace/composers/token_2022_program_close_account_composer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a Token-2022 Program CloseAccount instruction.
+    #
+    # The CloseAccount instruction closes a token account and transfers remaining
+    # lamports to a destination account. The account must have a balance of zero tokens.
+    #
+    # Required accounts:
+    # - **Account**: token account to close (writable, non-signer)
+    # - **Destination**: account to receive lamports (writable, non-signer)
+    # - **Authority**: account authority (non-writable, signer)
+    #
+    # @example Compose and build a close account instruction
+    #   composer = Token2022ProgramCloseAccountComposer.new(
+    #     account: token_account_address,
+    #     destination: destination_address,
+    #     authority: authority_address
+    #   )
+    #
+    # @since 0.1.5
+    class Token2022ProgramCloseAccountComposer < Base
+      # Extracts the token account address from the params
+      #
+      # @return [String] The token account address
+      def account
+        params[:account].to_s
+      end
+
+      # Extracts the destination address from the params
+      #
+      # @return [String] The destination address
+      def destination
+        params[:destination].to_s
+      end
+
+      # Extracts the authority address from the params
+      #
+      # @return [String] The authority address
+      def authority
+        params[:authority].to_s
+      end
+
+      # @return [String] The Token-2022 program id.
+      def token_2022_program
+        Constants::TOKEN_2022_PROGRAM_ID.to_s
+      end
+
+      # Setup accounts required for close account instruction
+      # Called automatically during initialization
+      #
+      # @return [void]
+      def setup_accounts
+        account_context.add_writable_nonsigner(account)
+        account_context.add_writable_nonsigner(destination)
+        account_context.add_readonly_signer(authority)
+        account_context.add_readonly_nonsigner(token_2022_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::Token2022::CloseAccountInstruction.build(
+          account_index: account_context.index_of(account),
+          authority_index: account_context.index_of(authority),
+          destination_index: account_context.index_of(destination),
+          program_index: account_context.index_of(token_2022_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/token_2022_program_initialize_mint_composer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for initializing a mint via the Token-2022 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::Token2022::InitializeMintInstruction`).
+    #
+    # Required accounts:
+    # - **Mint Account**: the mint account to initialize (writable, non-signer)
+    # - **Rent Sysvar**: the rent sysvar (readonly, non-signer)
+    # - **Program**: Token-2022 program (readonly, non-signer)
+    #
+    # @example Compose and build an initialize_mint instruction
+    #  composer = Token2022ProgramInitializeMintComposer.new(
+    #    decimals: 6,
+    #    mint_authority: mint_authority_pubkey,
+    #    freeze_authority: freeze_authority_pubkey,
+    #    mint_account: mint_address,
+    #  )
+    #
+    # @see Instructions::Token2022::InitializeMintInstruction
+    # @since 0.1.5
+    class Token2022ProgramInitializeMintComposer < 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
+
+      # @return [String] The Token-2022 program id.
+      def token_2022_program
+        Constants::TOKEN_2022_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 the InitializeMint 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(token_2022_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::Token2022::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(token_2022_program),
+          decimals: decimals,
+          mint_authority: mint_authority,
+          freeze_authority: freeze_authority
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/token_2022_program_mint_to_composer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a MintTo instruction for the Token-2022 Program.
+    #
+    # This composer builds a MintTo instruction that can be added to a transaction to mint tokens
+    # to a specified token 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::Token2022ProgramMintToComposer.new(
+    #     mint: mint,
+    #     destination: destination,
+    #     mint_authority: mint_authority,
+    #     amount: 100
+    #   )
+    #
+    # @since 0.1.5
+    class Token2022ProgramMintToComposer < 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
+
+      # @return [String] The Token-2022 program id.
+      def token_2022_program
+        Constants::TOKEN_2022_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(token_2022_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::Token2022::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(token_2022_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/token_2022_program_transfer_checked_composer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a Token-2022 Program `TransferChecked` instruction.
+    #
+    # This composer resolves and orders the required accounts for a `TransferChecked` instruction,
+    # sets up their access permissions, and delegates construction to the appropriate
+    # instruction builder (`Instructions::Token2022::TransferCheckedInstruction`).
+    #
+    # Required accounts:
+    # - **From**: source token account (writable, non-signer)
+    # - **To**: destination token account (writable, non-signer)
+    # - **Mint**: mint address (readonly, non-signer)
+    # - **Authority**: token owner (writable, signer)
+    # - **Program**: Token-2022 program (readonly, non-signer)
+    #
+    # @example Compose and build a transfer_checked instruction
+    #   composer = Token2022ProgramTransferCheckedComposer.new(
+    #     from: from_address,
+    #     to: to_address,
+    #     mint: mint_address,
+    #     authority: authority_pubkey,
+    #     amount: 1_000_000,
+    #     decimals: 6
+    #   )
+    #
+    # @see Instructions::Token2022::TransferCheckedInstruction
+    # @since 0.1.5
+    class Token2022ProgramTransferCheckedComposer < Base
+      # Extracts the to address from the params
+      #
+      # @return [String] The to address
+      def to
+        params[:to].to_s
+      end
+
+      # Extracts the from address from the params
+      #
+      # @return [String] The from address
+      def from
+        params[:from].to_s
+      end
+
+      # Extracts the authority address from the params
+      #
+      # The authority is the owner of the token account
+      #
+      # @return [String] The authority address
+      def authority
+        params[:authority].to_s
+      end
+
+      # Extracts the mint address from the params
+      #
+      # @return [String] The mint address
+      def mint
+        params[:mint].to_s
+      end
+
+      # @return [String] The Token-2022 program id.
+      def token_2022_program
+        Constants::TOKEN_2022_PROGRAM_ID.to_s
+      end
+
+      # Returns the amount to transfer
+      #
+      # @return [Integer] The amount to transfer
+      def amount
+        params[:amount]
+      end
+
+      # Returns the decimals for the mint of the token
+      #
+      # @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_signer(authority)
+        account_context.add_writable_nonsigner(to)
+        account_context.add_writable_nonsigner(from)
+        account_context.add_readonly_nonsigner(mint)
+        account_context.add_readonly_nonsigner(token_2022_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::Token2022::TransferCheckedInstruction.build(
+          amount: amount,
+          decimals: decimals,
+          to_index: account_context.index_of(to),
+          from_index: account_context.index_of(from),
+          mint_index: account_context.index_of(mint),
+          authority_index: account_context.index_of(authority),
+          program_index: account_context.index_of(token_2022_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/composers/token_2022_program_transfer_composer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Solace
+  module Composers
+    # Composer for creating a Token-2022 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::Token2022::TransferInstruction`).
+    #
+    # 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 = Token2022ProgramTransferComposer.new(
+    #     amount: 1_000_000,
+    #     owner: owner_address,
+    #     source: source_address,
+    #     destination: destination_address,
+    #   )
+    #
+    # @see Instructions::Token2022::TransferInstruction
+    # @since 0.1.5
+    class Token2022ProgramTransferComposer < 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
+
+      # @return [String] The Token-2022 program id.
+      def token_2022_program
+        Constants::TOKEN_2022_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(token_2022_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::Token2022::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(token_2022_program)
+        )
+      end
+    end
+  end
+end

data/lib/solace/connection.rb

@@ -33,6 +33,7 @@ module Solace
   #   Solace::Errors::ConfirmationTimeout
   # ]
   # @since 0.0.1
+  # rubocop:disable Metrics/ClassLength
   class Connection
     # @!attribute [r] rpc_url
     #   The URL of the Solana RPC node
@@ -196,15 +197,33 @@ module Solace
       @rpc_client.rpc_request('getTokenAccountBalance', [token_account, default_options]).dig('result', 'value')
     end
 
-    # Gets the token accounts by owner
+    # Gets the token accounts by owner.
+    #
+    # Defaults to the legacy SPL Token program; pass
+    # +token_program_id: Solace::Constants::TOKEN_2022_PROGRAM_ID+ for Token-2022.
     #
     # @param owner [String] The public key of the owner
-    # @return [Array<Hash>] The token accounts owned by the owner for the specified mint
-    def get_token_accounts_by_owner(owner)
-      params = [owner, { programId: Constants::TOKEN_PROGRAM_ID }, default_options]
+    # @param token_program_id [String] The token program to filter by (defaults to legacy SPL Token)
+    # @return [Array<Hash>] The token accounts owned by the owner under the given token program
+    def get_token_accounts_by_owner(owner, token_program_id: Constants::TOKEN_PROGRAM_ID)
+      params = [owner, { programId: token_program_id }, default_options]
       @rpc_client.rpc_request('getTokenAccountsByOwner', params).dig('result', 'value')
     end
 
+    # Discovery-only helper: returns the program ID that owns a given mint.
+    #
+    # Use this to dispatch between {Constants::TOKEN_PROGRAM_ID} and
+    # {Constants::TOKEN_2022_PROGRAM_ID} when the mint's program is not known
+    # ahead of time. If you also need the rest of the mint's account data
+    # (decimals, supply, ...), call {#get_account_info} directly and read
+    # +'owner'+ yourself — calling both would cost two RPC roundtrips.
+    #
+    # @param mint [String] The mint address
+    # @return [String, nil] The program ID that owns the mint, or +nil+ if the account does not exist
+    def get_mint_program_id(mint)
+      get_account_info(mint)&.dig('owner')
+    end
+
     # Get the transaction by signature
     #
     # @param signature [String] The signature of the transaction
@@ -335,4 +354,5 @@ module Solace
       Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/solace/constants.rb

@@ -23,10 +23,16 @@ module Solace
     COMPUTE_BUDGET_PROGRAM_ID = 'ComputeBudget111111111111111111111111111111'
 
     # @!attribute TOKEN_PROGRAM_ID
-    #   The public key of the SPL Token Program
-    #   This is the same across all Solana clusters
+    #   The public key of the SPL Token Program (legacy).
+    #   This is the same across all Solana clusters.
     TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
 
+    # @!attribute TOKEN_2022_PROGRAM_ID
+    #   The public key of the Token-2022 Program (formerly Token Extensions).
+    #   This is the same across all Solana clusters. See {Programs::Token2022}
+    #   for the full description of how it relates to the legacy program.
+    TOKEN_2022_PROGRAM_ID = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb'
+
     # @!attribute ASSOCIATED_TOKEN_ACCOUNT_PROGRAM_ID
     #   The public key of the Associated Token Account Program
     #   This is the same across all Solana clusters

data/lib/solace/instructions/spl_token/transfer_checked_instruction.rb

@@ -29,7 +29,7 @@ module Solace
         # SPL Token Program transfer instruction layout:
         #   - 1 byte: instruction index (12 for transfer checked)
         #   - 8 bytes: amount (u64, little-endian)
-        #   - 8 bytes: decimals (u64, little-endian)
+        #   - 1 byte: decimals (u8)
         #
         # @param amount [Integer] Amount to transfer (in tokens, according to mint's decimals)
         # @param decimals [Integer] Number of decimals for the token