solace 0.1.4 → 0.1.6

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
@@ -73,7 +74,7 @@ module Solace
       # Set default options for rpc requests
       @default_options = {
         commitment: commitment,
-        encoding: encoding
+        encoding:   encoding
       }
     end
 
@@ -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
@@ -247,9 +266,9 @@ module Solace
     # @return [Hash] The options for the send_transaction call
     def build_send_transaction_options(overrides)
       {
-        skipPreflight: false,
-        encoding: default_options[:encoding],
-        commitment: default_options[:commitment],
+        skipPreflight:       false,
+        encoding:            default_options[:encoding],
+        commitment:          default_options[:commitment],
         preflightCommitment: default_options[:commitment]
       }.merge(overrides)
     end
@@ -288,7 +307,7 @@ module Solace
       raise ArgumentError, 'Block required' unless block_given?
 
       signature = extract_signature_from(yield)
-      deadline = monotonic_deadline(timeout)
+      deadline  = monotonic_deadline(timeout)
 
       # Wait for confirmation
       until deadline_passed?(deadline)
@@ -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/errors/confirmation_timeout.rb

@@ -26,9 +26,9 @@ module Solace
       # @param [Integer] timeout The time out reached
       def initialize(message, signature:, commitment:, timeout:)
         super(message)
-        @signature = signature
+        @signature  = signature
         @commitment = commitment
-        @timeout = timeout
+        @timeout    = timeout
       end
 
       # Formats a confirmation timeout error
@@ -40,9 +40,9 @@ module Solace
       def self.format(signature, commitment, timeout)
         new(
           "Timed out waiting for signature #{signature} at commitment=#{commitment} after #{timeout}s",
-          signature: signature,
+          signature:  signature,
           commitment: commitment,
-          timeout: timeout
+          timeout:    timeout
         )
       end
     end

data/lib/solace/errors/rpc_error.rb

@@ -28,9 +28,9 @@ module Solace
       # @param [Object] rpc_data The JSON-RPC error data
       def initialize(message, rpc_code:, rpc_message:, rpc_data: nil)
         super(message)
-        @rpc_code = rpc_code
+        @rpc_code    = rpc_code
         @rpc_message = rpc_message
-        @rpc_data = rpc_data
+        @rpc_data    = rpc_data
       end
 
       # Formats a response to an error
@@ -40,8 +40,8 @@ module Solace
       def self.format_response(response)
         new(
           "RPC error #{response['error']['code']}: #{response['error']['message']}",
-          rpc_data: response['error']['data'],
-          rpc_code: response['error']['code'],
+          rpc_data:    response['error']['data'],
+          rpc_code:    response['error']['code'],
           rpc_message: response['error']['message']
         )
       end

data/lib/solace/instructions/associated_token_account/create_account_instruction.rb

@@ -63,7 +63,7 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [
+            ix.accounts      = [
               funder_index,
               associated_token_account_index,
               owner_index,
@@ -71,6 +71,7 @@ module Solace
               system_program_index,
               token_program_index
             ]
+
             ix.data = data
           end
         end

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

@@ -30,8 +30,8 @@ module Solace
         def self.build(account_index:, destination_index:, authority_index:, program_index:)
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [account_index, destination_index, authority_index]
-            ix.data = data
+            ix.accounts      = [account_index, destination_index, authority_index]
+            ix.data          = data
           end
         end
 

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

@@ -47,8 +47,8 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [account_index, mint_index, owner_index, rent_sysvar_index]
-            ix.data = data
+            ix.accounts      = [account_index, mint_index, owner_index, rent_sysvar_index]
+            ix.data          = data
           end
         end
 

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

@@ -49,8 +49,8 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [mint_account_index, rent_sysvar_index]
-            ix.data = data(decimals, mint_authority, freeze_authority)
+            ix.accounts      = [mint_account_index, rent_sysvar_index]
+            ix.data          = data(decimals, mint_authority, freeze_authority)
           end
         end
 

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

@@ -39,8 +39,8 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [mint_index, destination_index, mint_authority_index]
-            ix.data = data(amount)
+            ix.accounts      = [mint_index, destination_index, mint_authority_index]
+            ix.data          = data(amount)
           end
         end
 

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
@@ -50,8 +50,8 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [from_index, mint_index, to_index, authority_index]
-            ix.data = data(amount, decimals)
+            ix.accounts      = [from_index, mint_index, to_index, authority_index]
+            ix.data          = data(amount, decimals)
           end
         end
 

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

@@ -60,8 +60,8 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [source_index, destination_index, owner_index]
-            ix.data = data(amount)
+            ix.accounts      = [source_index, destination_index, owner_index]
+            ix.data          = data(amount)
           end
         end
 

data/lib/solace/instructions/system_program/create_account_instruction.rb

@@ -73,8 +73,8 @@ module Solace
         )
           Solace::Instruction.new.tap do |ix|
             ix.program_index = system_program_index
-            ix.accounts = [from_index, new_account_index]
-            ix.data = data(lamports, space, owner)
+            ix.accounts      = [from_index, new_account_index]
+            ix.data          = data(lamports, space, owner)
           end
         end
         # rubocop:enable Metrics/ParameterLists

data/lib/solace/instructions/system_program/transfer_instruction.rb

@@ -46,8 +46,8 @@ module Solace
         )
           Instruction.new.tap do |ix|
             ix.program_index = program_index
-            ix.accounts = [from_index, to_index]
-            ix.data = data(lamports)
+            ix.accounts      = [from_index, to_index]
+            ix.data          = data(lamports)
           end
         end
 

data/lib/solace/instructions/token_2022/close_account_instruction.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction builder for Token-2022 CloseAccount.
+      #
+      # Closes a Token-2022 token account and transfers all remaining lamports
+      # to a destination account. The token account must have a balance of zero.
+      #
+      # Instruction discriminator: 9
+      #
+      # Accounts:
+      # 1. [writable] Token account to close
+      # 2. [writable] Destination account to receive lamports
+      # 3. [signer]   Account authority
+      #
+      # @since 0.1.5
+      class CloseAccountInstruction
+        # Instruction discriminator for CloseAccount
+        INSTRUCTION_DISCRIMINATOR = [9].freeze
+
+        # Builds a CloseAccount instruction.
+        #
+        # @param account_index [Integer] Index of the token account to close
+        # @param destination_index [Integer] Index of the destination account
+        # @param authority_index [Integer] Index of the account authority
+        # @param program_index [Integer] Index of the Token-2022 program
+        # @return [Solace::Instruction] The constructed instruction
+        def self.build(account_index:, destination_index:, authority_index:, program_index:)
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [account_index, destination_index, authority_index]
+            ix.data          = data
+          end
+        end
+
+        # Builds the data for a CloseAccount instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #
+        # @return [Array] 1-byte instruction index
+        def self.data
+          INSTRUCTION_DISCRIMINATOR
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/initialize_account_instruction.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for initializing a new Token-2022 token account.
+      #
+      # Used in conjunction with the SystemProgram::CreateAccount instruction
+      # to create and initialize a new token account. For the common case of
+      # an associated token account, prefer
+      # {AssociatedTokenAccount::CreateAccountInstruction}.
+      #
+      # @example Build an InitializeAccount instruction
+      #   instruction = Solace::Instructions::Token2022::InitializeAccountInstruction.build(
+      #     account_index: 0,
+      #     mint_index: 1,
+      #     owner_index: 2,
+      #     rent_sysvar_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.1.5
+      class InitializeAccountInstruction
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for Token-2022's InitializeAccount instruction.
+        INSTRUCTION_INDEX = [1].freeze
+
+        # Builds a Token2022::InitializeAccount instruction.
+        #
+        # @param account_index [Integer] Index of the new token account in the transaction's accounts.
+        # @param mint_index [Integer] Index of the mint account in the transaction's accounts.
+        # @param owner_index [Integer] Index of the owner of the new account in the transaction's accounts.
+        # @param rent_sysvar_index [Integer] Index of the Rent Sysvar in the transaction's accounts.
+        # @param program_index [Integer] Index of the Token-2022 program in the transaction's accounts.
+        # @return [Solace::Instruction]
+        def self.build(
+          account_index:,
+          mint_index:,
+          owner_index:,
+          rent_sysvar_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [account_index, mint_index, owner_index, rent_sysvar_index]
+            ix.data          = data
+          end
+        end
+
+        # Builds the data for a Token2022::InitializeAccount instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #
+        # @return [Array] 1-byte instruction index
+        def self.data
+          INSTRUCTION_INDEX
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/initialize_mint_instruction.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for initializing a new Token-2022 mint.
+      #
+      # @example Build an InitializeMint instruction
+      #   instruction = Solace::Instructions::Token2022::InitializeMintInstruction.build(
+      #     decimals: 6,
+      #     mint_authority: mint_authority.address,
+      #     freeze_authority: freeze_authority.address,
+      #     rent_sysvar_index: 2,
+      #     mint_account_index: 1,
+      #     program_index: 3
+      #   )
+      #
+      # @since 0.1.5
+      class InitializeMintInstruction
+        # Instruction index for Initialize Mint
+        INSTRUCTION_INDEX = [0].freeze
+
+        # Builds a Solace::Instruction for initializing a Token-2022 mint.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Decimals (1 byte)]
+        #   - [Mint authority (32 bytes)]
+        #   - [Freeze authority option (1 byte)]
+        #   - [Freeze authority (32 bytes)]
+        #
+        # @param decimals [Integer] Number of decimals for the token
+        # @param mint_authority [String] Public key of the mint authority
+        # @param freeze_authority [String, nil] Public key of the freeze authority
+        # @param rent_sysvar_index [Integer] Index of the rent sysvar in the transaction's accounts
+        # @param mint_account_index [Integer] Index of the mint account in the transaction's accounts
+        # @param program_index [Integer] Index of the Token-2022 Program in the transaction's accounts
+        # @return [Solace::Instruction]
+        def self.build(
+          decimals:,
+          mint_authority:,
+          rent_sysvar_index:,
+          mint_account_index:,
+          freeze_authority: nil,
+          program_index: 2
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [mint_account_index, rent_sysvar_index]
+            ix.data          = data(decimals, mint_authority, freeze_authority)
+          end
+        end
+
+        # Instruction data for an initialize mint instruction.
+        #
+        # @param decimals [Integer] Number of decimals for the token
+        # @param mint_authority [String] Public key of the mint authority
+        # @param freeze_authority [String, nil] Public key of the freeze authority
+        # @return [Array<u8>] The instruction data
+        def self.data(decimals, mint_authority, freeze_authority)
+          INSTRUCTION_INDEX +
+            [decimals] +
+            Solace::Utils::Codecs.base58_to_bytes(mint_authority) +
+            (
+              if freeze_authority
+                [1] + Solace::Utils::Codecs.base58_to_bytes(freeze_authority)
+              else
+                [0]
+              end
+            )
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/mint_to_instruction.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for minting Token-2022 tokens to a token account.
+      #
+      # @example Build a MintTo instruction
+      #   instruction = Solace::Instructions::Token2022::MintToInstruction.build(
+      #     amount: 100,
+      #     mint_index: 1,
+      #     mint_authority_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.1.5
+      class MintToInstruction
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for Token-2022's MintTo instruction.
+        INSTRUCTION_INDEX = [7].freeze
+
+        # Builds a MintTo instruction.
+        #
+        # @param amount [Integer] The amount of tokens to mint.
+        # @param mint_index [Integer] The index of the mint account.
+        # @param destination_index [Integer] The index of the token account to mint to.
+        # @param mint_authority_index [Integer] The index of the mint authority account.
+        # @param program_index [Integer] The index of the Token-2022 Program.
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          mint_index:,
+          mint_authority_index:,
+          destination_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [mint_index, destination_index, mint_authority_index]
+            ix.data          = data(amount)
+          end
+        end
+
+        # Builds the data for a MintTo instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes)]
+        #
+        # @param amount [Integer] The amount of tokens to mint.
+        # @return [Array] 1-byte instruction index + 8-byte amount
+        def self.data(amount)
+          INSTRUCTION_INDEX + Solace::Utils::Codecs.encode_le_u64(amount).bytes
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    module Token2022
+      # Instruction for transferring Token-2022 tokens with decimal validation.
+      #
+      # @example Build a TransferChecked instruction
+      #   instruction = Solace::Instructions::Token2022::TransferCheckedInstruction.build(
+      #     amount: 100,
+      #     decimals: 6,
+      #     to_index: 1,
+      #     from_index: 2,
+      #     mint_index: 3,
+      #     authority_index: 4,
+      #     program_index: 5
+      #   )
+      #
+      # @since 0.1.5
+      class TransferCheckedInstruction
+        # Token-2022 instruction index for Transfer Checked
+        INSTRUCTION_INDEX = [12].freeze
+
+        # Builds a Solace::Instruction for transferring Token-2022 tokens.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes little-endian u64)]
+        #   - [Decimals (1 byte)]
+        #
+        # @param amount [Integer] Amount to transfer (in tokens, according to mint's decimals)
+        # @param decimals [Integer] Number of decimals for the token
+        # @param to_index [Integer] Index of the destination token account in the transaction's accounts
+        # @param from_index [Integer] Index of the source token account in the transaction's accounts
+        # @param mint_index [Integer] Index of the mint in the transaction's accounts
+        # @param authority_index [Integer] Index of the authority (owner) in the transaction's accounts
+        # @param program_index [Integer] Index of the Token-2022 Program in the transaction's accounts
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          decimals:,
+          to_index:,
+          from_index:,
+          mint_index:,
+          authority_index:,
+          program_index: 3
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [from_index, mint_index, to_index, authority_index]
+            ix.data          = data(amount, decimals)
+          end
+        end
+
+        # Instruction data for a TransferChecked instruction.
+        #
+        # @param amount [Integer] Amount to transfer
+        # @param decimals [Integer] Number of decimals for the token
+        # @return [Array] 1-byte instruction index + 8-byte amount + 1-byte decimals
+        def self.data(amount, decimals)
+          INSTRUCTION_INDEX +
+            Solace::Utils::Codecs.encode_le_u64(amount).bytes +
+            [decimals]
+        end
+      end
+    end
+  end
+end

data/lib/solace/instructions/token_2022/transfer_instruction.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Solace
+  module Instructions
+    # The Token2022 module contains instruction builders for the Token-2022 Program
+    # (formerly Token Extensions, +TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb+).
+    #
+    # Token-2022 is wire-compatible with the legacy SPL Token program for its
+    # base instructions (Transfer, TransferChecked, CloseAccount, MintTo,
+    # InitializeMint, InitializeAccount). The instruction discriminators and
+    # data layouts are identical; only the program the instruction targets
+    # differs. These builders are duplicated from the {SplToken} namespace so
+    # that each instruction is unambiguously bound to a single on-chain program.
+    #
+    # @see Solace::Instructions::SplToken
+    # @since 0.1.5
+    module Token2022
+      # Instruction for transferring tokens via the Token-2022 program.
+      #
+      # @example Build a Transfer instruction
+      #   instruction = Solace::Instructions::Token2022::TransferInstruction.build(
+      #     amount: 100,
+      #     owner_index: 1,
+      #     source_index: 2,
+      #     destination_index: 3,
+      #     program_index: 4
+      #   )
+      #
+      # @since 0.1.5
+      class TransferInstruction
+        # @!attribute [Array<Integer>] INSTRUCTION_INDEX
+        #   Instruction index for Token-2022's Transfer instruction.
+        INSTRUCTION_INDEX = [3].freeze
+
+        # Builds a Transfer instruction.
+        #
+        # @param amount [Integer] The amount of tokens to transfer.
+        # @param source_index [Integer] The index of the source token account.
+        # @param destination_index [Integer] The index of the destination token account.
+        # @param owner_index [Integer] The index of the source account's owner.
+        # @param program_index [Integer] The index of the Token-2022 Program.
+        # @return [Solace::Instruction]
+        def self.build(
+          amount:,
+          owner_index:,
+          source_index:,
+          destination_index:,
+          program_index:
+        )
+          Solace::Instruction.new.tap do |ix|
+            ix.program_index = program_index
+            ix.accounts      = [source_index, destination_index, owner_index]
+            ix.data          = data(amount)
+          end
+        end
+
+        # Builds the data for a Transfer instruction.
+        #
+        # The BufferLayout is:
+        #   - [Instruction Index (1 byte)]
+        #   - [Amount (8 bytes)]
+        #
+        # @param amount [Integer] The amount of tokens to transfer.
+        # @return [Array<Integer>] 1-byte instruction index + 8-byte amount
+        def self.data(amount)
+          INSTRUCTION_INDEX + Solace::Utils::Codecs.encode_le_u64(amount).bytes
+        end
+      end
+    end
+  end
+end