solana-ruby-kit 0.1.9 → 7.0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d26df33c1471059cde38ac46ec2604e0c26ffc8d64c580de4171396516530fd
-  data.tar.gz: dba1b05e818b10e8fa7692f6ae4af89c3946bcd19707be52cfdfd1c503e81b63
+  metadata.gz: 950ad695ca0d9971314172207d974e747cf35c5dfec1210fb32882f0517306f8
+  data.tar.gz: ce0c4c171c78ca202a35bbacdd74630bb24afd3a438c7ebe7669b5cb56ee9a71
 SHA512:
-  metadata.gz: 56674f680f3059cd3247591fe2a14f303853b8806e251f4c147de90fb4ff7ebcea498394a2650aab40089d3cb5e52b10686cd3c5797e171c230a21ef05602eb3
-  data.tar.gz: b57dd91be86b034b1a207c809a04c38ca045700f608e4481ac125536d546f21f68e796f01930259a5054ea5ecf72f020f9260d4b63f6661dd177525c32ab924d
+  metadata.gz: 7d356ad614cfe6990a0df08121f6db68dcdf4e72b19979bd01a56233a1fccc699a16ee716c2e12d33b4de5c34792cc627fd0e273bfefce73a7144f70fff37ddf
+  data.tar.gz: b866ff957a09ba7dc4ab26708ea1311b2c8a283e992f972351c173187a47d905b6ba62483beefd0f5b2c9d46f9ecdd8574bba1f4491e96771abdc9c75417f7ee

data/lib/solana/ruby/kit/errors.rb

@@ -56,6 +56,10 @@ module Solana::Ruby::Kit
     TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS
     TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING
     TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND
+    # context: { index: }
+    TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE = :SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE
+    # context: { unsupported_version: }
+    TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED            = :SOLANA_ERROR__TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED
     TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE     = :SOLANA_ERROR__TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE
     TRANSACTIONS__BLOCKHASH_NOT_FOUND                    = :SOLANA_ERROR__TRANSACTIONS__BLOCKHASH_NOT_FOUND
     TRANSACTIONS__FAILED_TRANSACTION_PLAN                = :SOLANA_ERROR__TRANSACTIONS__FAILED_TRANSACTION_PLAN
@@ -118,6 +122,16 @@ module Solana::Ruby::Kit
     INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE      = :SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE
     INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN               = :SOLANA_ERROR__INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN
     INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN   = :SOLANA_ERROR__INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN
+    # context: { max_instructions:, transaction_instruction_limit: }
+    INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION = :SOLANA_ERROR__INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION
+    # context: { max_instructions:, num_instructions: }
+    INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED = :SOLANA_ERROR__INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED
+
+    # ── Transaction introspection ────────────────────────────────────────────
+    TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION
+    TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE
+    # context: { needed_bytes: }
+    TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE
 
     # ── Wallet Standard ───────────────────────────────────────────────────────
     WALLET_STANDARD__INVALID_WIRE_FORMAT             = :SOLANA_ERROR__WALLET_STANDARD__INVALID_WIRE_FORMAT
@@ -125,6 +139,7 @@ module Solana::Ruby::Kit
 
     # ── Subscribable ──────────────────────────────────────────────────────────
     SUBSCRIBABLE__RETRY_NOT_SUPPORTED                     = :SOLANA_ERROR__SUBSCRIBABLE__RETRY_NOT_SUPPORTED
+    SUBSCRIBABLE__STREAM_CLOSED_WITHOUT_ERROR             = :SOLANA_ERROR__SUBSCRIBABLE__STREAM_CLOSED_WITHOUT_ERROR
 
     # ── Fixed-points ──────────────────────────────────────────────────────────
     FIXED_POINTS__STRICT_MODE_PRECISION_LOSS              = :SOLANA_ERROR__FIXED_POINTS__STRICT_MODE_PRECISION_LOSS
@@ -184,7 +199,9 @@ module Solana::Ruby::Kit
         TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE        => 'Transaction version %{version} is out of range',
         TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS => 'Failed to decompile address lookup table contents',
         TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING => 'Failed to decompile transaction: fee payer is missing',
-        TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND => 'Failed to decompile instruction: program address not found',
+        TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND => 'Failed to decompile instruction: program address not found at index %{index}',
+        TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE => 'Failed to decompile instruction: account index %{index} is out of range',
+        TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED        => 'Transaction version %{unsupported_version} is not supported',
         TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE => 'Transaction simulation failed: %{message}',
         TRANSACTIONS__BLOCKHASH_NOT_FOUND                => 'Blockhash not found',
         TRANSACTIONS__FAILED_TRANSACTION_PLAN            => 'Failed to execute transaction plan',
@@ -245,9 +262,17 @@ module Solana::Ruby::Kit
         INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE    => 'Message packer is already complete; no more instructions to pack',
         INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN             => 'Instruction plan is empty and produced no transaction messages',
         INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN => 'Failed to execute transaction plan',
+        INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION => 'The configured maximum of %{max_instructions} instructions per transaction is invalid. It must be a positive integer no greater than the transaction format limit of %{transaction_instruction_limit} instructions per transaction.',
+        INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED => 'Planning this transaction message would require %{num_instructions} instructions, which exceeds the configured maximum of %{max_instructions} instructions per transaction.',
+
+        # Transaction introspection
+        TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION => "Cannot decode a 'jsonParsed'-encoded getTransaction response; its instructions are pre-parsed and lack raw bytes. Fetch with encoding: 'json' or 'base64' instead.",
+        TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE => 'Unrecognized getTransaction response shape; expected a base64, base58, or json-encoded transaction.',
+        TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE => 'Malformed compiled transaction message: expected at least %{needed_bytes} byte(s)',
 
         # Subscribable
         SUBSCRIBABLE__RETRY_NOT_SUPPORTED              => 'This reactive store does not support retry(); use create_reactive_store_from_data_publisher_factory for a retryable store',
+        SUBSCRIBABLE__STREAM_CLOSED_WITHOUT_ERROR      => 'The stream store closed in an error state but did not report an error.',
 
         # Fixed-points
         FIXED_POINTS__STRICT_MODE_PRECISION_LOSS       => 'Value has more than 9 fractional digits and cannot be represented exactly as a Sol amount',

data/lib/solana/ruby/kit/instruction_plans/instruction_plan.rb

@@ -5,6 +5,7 @@ require_relative '../errors'
 require_relative '../instructions/instruction'
 require_relative '../transaction_messages/transaction_message'
 require_relative '../transactions/compiler'
+require_relative 'max_instructions'
 
 module Solana::Ruby::Kit
   module InstructionPlans
@@ -68,9 +69,17 @@ module Solana::Ruby::Kit
       # Packs as many instructions as possible into +message+ and returns the
       # updated message. Raises SolanaError if the message is too small or the
       # packer is already done.
-      sig { params(message: TransactionMessages::TransactionMessage).returns(TransactionMessages::TransactionMessage) }
-      def pack_message_to_capacity(message)
-        @pack_proc.call(message)
+      #
+      # +max_instructions+ caps the number of top-level instructions allowed in the
+      # returned message (defaults to 16; must be a positive integer no greater than 64).
+      sig do
+        params(
+          message:          TransactionMessages::TransactionMessage,
+          max_instructions: T.nilable(Integer)
+        ).returns(TransactionMessages::TransactionMessage)
+      end
+      def pack_message_to_capacity(message, max_instructions: nil)
+        @pack_proc.call(message, max_instructions)
       end
     end
 
@@ -122,11 +131,15 @@ module Solana::Ruby::Kit
           offset = T.let(0, Integer)
           MessagePacker.new(
             done_proc: -> { offset >= total_length },
-            pack_proc:  ->(message) {
+            pack_proc:  ->(message, max_instructions) {
               if offset >= total_length
                 Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE)
               end
 
+              InstructionPlans.assert_valid_max_instructions_per_transaction(max_instructions)
+              resolved_max = InstructionPlans.resolve_max_instructions(max_instructions)
+              InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, resolved_max)
+
               base_ix    = get_instruction.call(offset, 0)
               with_base  = TransactionMessages.append_instructions(message, [base_ix])
               base_size  = Transactions.get_transaction_message_size(with_base)
@@ -164,18 +177,30 @@ module Solana::Ruby::Kit
           idx = T.let(0, Integer)
           MessagePacker.new(
             done_proc: -> { idx >= instructions.length },
-            pack_proc:  ->(message) {
+            pack_proc:  ->(message, max_instructions) {
               if idx >= instructions.length
                 Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE)
               end
 
+              InstructionPlans.assert_valid_max_instructions_per_transaction(max_instructions)
+              resolved_max = InstructionPlans.resolve_max_instructions(max_instructions)
+              InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, resolved_max)
+
               original_size = Transactions.get_transaction_message_size(message)
               packed        = T.let(message, TransactionMessages::TransactionMessage)
               start_idx     = idx
 
               (idx...instructions.length).each do |i|
-                packed = TransactionMessages.append_instructions(packed, [instructions[i]])
-                size   = Transactions.get_transaction_message_size(packed)
+                # Stop once the message is full, before compiling a message that would exceed
+                # the instruction limit (which would raise). The assertion above guarantees at
+                # least the first instruction fits, so reaching the limit here is a graceful stop.
+                if packed.instructions.length >= resolved_max
+                  idx = i
+                  return packed
+                end
+
+                next_packed = TransactionMessages.append_instructions(packed, [instructions[i]])
+                size        = Transactions.get_transaction_message_size(next_packed)
 
                 if size > Transactions::TRANSACTION_SIZE_LIMIT
                   if i == start_idx
@@ -190,6 +215,8 @@ module Solana::Ruby::Kit
                   idx = i
                   return packed
                 end
+
+                packed = next_packed
               end
 
               idx = instructions.length

data/lib/solana/ruby/kit/instruction_plans/max_instructions.rb

@@ -0,0 +1,59 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # The default maximum number of top-level instructions per planned transaction message.
+    #
+    # Intentionally lower than the transaction format's instruction limit to leave headroom
+    # for inner instructions (CPIs), which are not visible at planning time.
+    DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION = T.let(16, Integer)
+
+    # The hard maximum number of top-level instructions the transaction format can encode.
+    TRANSACTION_INSTRUCTION_LIMIT = T.let(64, Integer)
+
+    module_function
+
+    # Resolves the effective maximum number of instructions allowed in a transaction message,
+    # falling back to the default when no value is provided.
+    # Mirrors `resolveMaxInstructions(maxInstructions)`.
+    sig { params(max_instructions: T.nilable(Integer)).returns(Integer) }
+    def resolve_max_instructions(max_instructions)
+      max_instructions || DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION
+    end
+
+    # Asserts that a configured maximum number of instructions per transaction is valid.
+    # +nil+ is allowed and falls back to the default.
+    # Mirrors `assertValidMaxInstructionsPerTransaction(maxInstructions)`.
+    sig { params(max_instructions: T.nilable(Integer)).void }
+    def assert_valid_max_instructions_per_transaction(max_instructions)
+      return if max_instructions.nil?
+
+      if max_instructions <= 0 || max_instructions > TRANSACTION_INSTRUCTION_LIMIT
+        Kernel.raise SolanaError.new(
+          SolanaError::INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION,
+          {
+            max_instructions:              max_instructions,
+            transaction_instruction_limit: TRANSACTION_INSTRUCTION_LIMIT
+          }
+        )
+      end
+    end
+
+    # Raises if +num_instructions+ exceeds +max_instructions+.
+    # Mirrors `assertMaxInstructionsPerTransaction(numInstructions, maxInstructions)`.
+    sig { params(num_instructions: Integer, max_instructions: Integer).void }
+    def assert_max_instructions_per_transaction(num_instructions, max_instructions)
+      return if num_instructions <= max_instructions
+
+      Kernel.raise SolanaError.new(
+        SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED,
+        { max_instructions: max_instructions, num_instructions: num_instructions }
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/instruction_plans/transaction_planner.rb

@@ -23,27 +23,45 @@ module Solana::Ruby::Kit
     #     Called after instructions are appended to a message. Must return the
     #     (possibly further updated) message. Defaults to identity.
     #
-    # The returned planner is a lambda: planner.call(instruction_plan) -> TransactionPlan
+    #   max_instructions_per_transaction: Integer  (optional)
+    #     Maximum number of top-level instructions allowed in each planned transaction.
+    #     Must be a positive integer no greater than 64. Defaults to 16. Can be overridden
+    #     per-call via the returned planner's `max_instructions_per_transaction:` kwarg.
+    #
+    # The returned planner is a lambda:
+    #   planner.call(instruction_plan, max_instructions_per_transaction: nil) -> TransactionPlan
     #
     # Mirrors `createTransactionPlanner(config)` from @solana/instruction-plans.
     # NOTE: Ruby translation is synchronous; abort-signal support is omitted.
     sig do
       params(
-        create_transaction_message:     T.untyped,
-        on_transaction_message_updated: T.untyped
+        create_transaction_message:        T.untyped,
+        on_transaction_message_updated:    T.untyped,
+        max_instructions_per_transaction:  T.nilable(Integer)
       ).returns(T.untyped)
     end
     def create_transaction_planner(
       create_transaction_message:,
-      on_transaction_message_updated: ->(msg) { msg }
+      on_transaction_message_updated: ->(msg) { msg },
+      max_instructions_per_transaction: nil
     )
       ctx = {
         create_transaction_message:     create_transaction_message,
         on_transaction_message_updated: on_transaction_message_updated
       }
+      config_max_instructions_per_transaction = max_instructions_per_transaction
+
+      ->(instruction_plan, max_instructions_per_transaction: nil) {
+        resolved_max = max_instructions_per_transaction || config_max_instructions_per_transaction
+
+        # Reject up front any configured maximum the transaction format could never satisfy,
+        # rather than discovering it mid-plan when a message fails to compile.
+        InstructionPlans.assert_valid_max_instructions_per_transaction(resolved_max)
 
-      ->(instruction_plan) {
-        mutable = planner_traverse(instruction_plan, ctx.merge(parent: nil, parent_candidates: []))
+        mutable = planner_traverse(
+          instruction_plan,
+          ctx.merge(parent: nil, parent_candidates: [], max_instructions_per_transaction: resolved_max)
+        )
         Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN) unless mutable
         planner_freeze(mutable)
       }
@@ -136,7 +154,7 @@ module Solana::Ruby::Kit
       candidates = ctx[:parent_candidates].dup
 
       until packer.done?
-        predicate = ->(msg) { packer.pack_message_to_capacity(msg) }
+        predicate = ->(msg) { packer.pack_message_to_capacity(msg, max_instructions: ctx[:max_instructions_per_transaction]) }
         candidate = planner_select_and_mutate_candidate(ctx, candidates, &predicate)
         unless candidate
           msg      = planner_create_new_message(ctx, &predicate)
@@ -162,11 +180,18 @@ module Solana::Ruby::Kit
         begin
           updated = ctx[:on_transaction_message_updated].call(predicate.call(candidate[:message]))
           if Transactions.get_transaction_message_size(updated) <= Transactions::TRANSACTION_SIZE_LIMIT
+            InstructionPlans.assert_max_instructions_per_transaction(
+              updated.instructions.length,
+              InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+            )
             candidate[:message] = updated
             return candidate
           end
         rescue SolanaError => e
-          next if e.code == SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN
+          next if [
+            SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+            SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED
+          ].include?(e.code)
           Kernel.raise
         end
       end
@@ -187,6 +212,11 @@ module Solana::Ruby::Kit
         )
       end
 
+      InstructionPlans.assert_max_instructions_per_transaction(
+        updated_msg.instructions.length,
+        InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+      )
+
       updated_msg
     end
 
@@ -205,11 +235,21 @@ module Solana::Ruby::Kit
               num_free_bytes:     Transactions::TRANSACTION_SIZE_LIMIT - base_size }
           )
         end
+        InstructionPlans.assert_max_instructions_per_transaction(
+          updated.instructions.length,
+          InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+        )
         updated
       when :message_packer
         packer = plan.get_message_packer.call
         msg    = message
-        msg    = packer.pack_message_to_capacity(msg) until packer.done?
+        until packer.done?
+          msg = packer.pack_message_to_capacity(msg, max_instructions: ctx[:max_instructions_per_transaction])
+          InstructionPlans.assert_max_instructions_per_transaction(
+            msg.instructions.length,
+            InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+          )
+        end
         msg
       else
         Kernel.raise SolanaError.new(

data/lib/solana/ruby/kit/instruction_plans.rb

@@ -3,6 +3,7 @@
 
 # Mirrors @solana/instruction-plans.
 # An InstructionPlan describes operations that may span multiple transactions.
+require_relative 'instruction_plans/max_instructions'
 require_relative 'instruction_plans/instruction_plan'
 require_relative 'instruction_plans/transaction_plan'
 require_relative 'instruction_plans/transaction_plan_result'

data/lib/solana/ruby/kit/rpc/api/get_inflation_reward.rb

@@ -9,7 +9,9 @@ module Solana::Ruby::Kit
       InflationReward = T.let(
         Struct.new(
           :amount,         # Integer (Lamports) — reward credited
-          :commission,     # Integer — vote account commission at reward time
+          :commission,     # Integer, nilable — vote account commission at reward time;
+                           #   null once the vote account reports commission through
+                           #   getVoteAccounts' inflationRewardsCommissionBps instead
           :effective_slot, # Integer — slot in which rewards were delivered
           :epoch,          # Integer — epoch for which reward occurred
           :post_balance,   # Integer (Lamports) — post-reward account balance
@@ -46,7 +48,7 @@ module Solana::Ruby::Kit
 
             InflationReward.new(
               amount:         Kernel.Integer(entry['amount']),
-              commission:     Kernel.Integer(entry['commission']),
+              commission:     entry['commission'] ? Kernel.Integer(entry['commission']) : nil,
               effective_slot: Kernel.Integer(entry['effectiveSlot']),
               epoch:          Kernel.Integer(entry['epoch']),
               post_balance:   Kernel.Integer(entry['postBalance'])

data/lib/solana/ruby/kit/rpc/api/get_transactions_for_address.rb

@@ -0,0 +1,208 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # One signature-level entry returned by getTransactionsForAddress when
+      # `transaction_details` is `:signatures`.
+      # Mirrors TypeScript's GetTransactionsForAddressSignature.
+      TransactionsForAddressSignature = T.let(
+        Struct.new(
+          :block_time,          # Integer | nil — Unix timestamp of block production, nil if unavailable
+          :confirmation_status, # Symbol | nil — :processed, :confirmed, or :finalized
+          :err,                 # Hash | nil — transaction error, nil if succeeded
+          :memo,                # String | nil — memo associated with the transaction
+          :signature,           # String — base-58 encoded transaction signature
+          :slot,                # Integer — slot containing the transaction
+          :transaction_index,   # Integer — 0-based index within the block
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # The result envelope shared by every mode of getTransactionsForAddress.
+      #
+      # `data` holds the matching transactions in the requested sort order. Its
+      # element type depends on `transaction_details`: TransactionsForAddressSignature
+      # structs for `:signatures`, and raw (String-keyed) response hashes for
+      # `:full` — the same shape `Rpc::Api::GetTransaction#get_transaction`
+      # returns, so each element can be handed straight to
+      # `TransactionIntrospection.decode_transaction_from_rpc_response`.
+      #
+      # `pagination_token` is the cursor to pass back as `pagination_token` on a
+      # subsequent call, or nil when there are no more results.
+      #
+      # Mirrors TypeScript's GetTransactionsForAddressApiResponse.
+      TransactionsForAddressPage = T.let(
+        Struct.new(
+          :data,             # Array<TransactionsForAddressSignature> | Array<Hash>
+          :pagination_token, # String | nil — cursor for the next page
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # Returns confirmed transactions that load the given address, with
+      # server-side filtering, sorting, and cursor-based pagination.
+      #
+      # This combines the discovery step of getSignaturesForAddress with
+      # filtering and pagination the server applies itself. Note: check your RPC
+      # provider for support for this method.
+      #
+      # Mirrors TypeScript's GetTransactionsForAddressApi.getTransactionsForAddress.
+      # See https://solana.com/docs/rpc/http/gettransactionsforaddress
+      module GetTransactionsForAddress
+        extend T::Sig
+
+        # Maps the snake_case keys of a Ruby +filters+ hash onto the wire names.
+        # Comparison operators (:eq, :gt, :gte, :lt, :lte) pass through as-is.
+        FILTER_KEYS = T.let(
+          {
+            block_time:     'blockTime',
+            signature:      'signature',
+            slot:           'slot',
+            status:         'status',
+            token_accounts: 'tokenAccounts'
+          }.freeze,
+          T::Hash[Symbol, String]
+        )
+
+        COMPARISON_KEYS = T.let(%i[eq gt gte lt lte].freeze, T::Array[Symbol])
+
+        # @param address [String] base-58 address to search for.
+        # @param transaction_details [Symbol] :signatures (default) or :full.
+        # @param encoding [String, nil] 'base58', 'base64', 'json' (server default),
+        #   or 'jsonParsed'. Only valid with `transaction_details: :full`.
+        # @param max_supported_transaction_version [Integer, nil] newest transaction
+        #   version to accept. Omit to receive only legacy transactions (in which
+        #   case no `version` is returned). Only valid with `transaction_details: :full`.
+        # @param commitment [Symbol, nil] :confirmed or :finalized. This method does
+        #   not support :processed.
+        # @param filters [Hash, nil] server-side filters, combined with AND. Supports
+        #   `block_time:` ({eq/gt/gte/lt/lte}), `signature:` ({gt/gte/lt/lte}),
+        #   `slot:` ({gt/gte/lt/lte}), `status:` (:any, :succeeded, :failed), and
+        #   `token_accounts:` (:none, :balance_changed, :all).
+        # @param limit [Integer, nil] max results. The server caps this at 1000 for
+        #   `:signatures` and 100 for `:full`.
+        # @param min_context_slot [Integer, nil] reject data older than this slot.
+        # @param pagination_token [String, nil] cursor from a previous response's
+        #   `pagination_token`, formatted "<slot>:<position>".
+        # @param sort_order [Symbol, nil] :desc (newest first, server default) or :asc.
+        # @return [TransactionsForAddressPage]
+        sig do
+          params(
+            address:                            String,
+            transaction_details:                Symbol,
+            encoding:                           T.nilable(String),
+            max_supported_transaction_version:  T.nilable(Integer),
+            commitment:                         T.nilable(Symbol),
+            filters:                            T.nilable(T::Hash[Symbol, T.untyped]),
+            limit:                              T.nilable(Integer),
+            min_context_slot:                   T.nilable(Integer),
+            pagination_token:                   T.nilable(String),
+            sort_order:                         T.nilable(Symbol)
+          ).returns(T.untyped)
+        end
+        def get_transactions_for_address(
+          address,
+          transaction_details:               :signatures,
+          encoding:                          nil,
+          max_supported_transaction_version: nil,
+          commitment:                        nil,
+          filters:                           nil,
+          limit:                             nil,
+          min_context_slot:                  nil,
+          pagination_token:                  nil,
+          sort_order:                        nil
+        )
+          unless %i[signatures full].include?(transaction_details)
+            Kernel.raise ArgumentError, "transaction_details must be :signatures or :full, got #{transaction_details.inspect}"
+          end
+
+          # The RPC rejects `processed` for this method; TypeScript encodes that
+          # as `Exclude<Commitment, 'processed'>`, so fail fast here too.
+          if commitment == :processed
+            Kernel.raise ArgumentError, 'getTransactionsForAddress does not support the :processed commitment'
+          end
+
+          if transaction_details == :signatures
+            if encoding
+              Kernel.raise ArgumentError, 'encoding is only valid with transaction_details: :full'
+            end
+            if max_supported_transaction_version
+              Kernel.raise ArgumentError, 'max_supported_transaction_version is only valid with transaction_details: :full'
+            end
+          end
+
+          config = { 'transactionDetails' => transaction_details.to_s }
+          config['encoding']                       = encoding if encoding
+          config['maxSupportedTransactionVersion'] = max_supported_transaction_version if max_supported_transaction_version
+          config['commitment']                     = commitment.to_s if commitment
+          config['limit']                          = limit if limit
+          config['minContextSlot']                 = min_context_slot if min_context_slot
+          config['paginationToken']                = pagination_token if pagination_token
+          config['sortOrder']                      = sort_order.to_s if sort_order
+          config['filters']                        = build_filters(filters) if filters && !filters.empty?
+
+          raw  = transport.request('getTransactionsForAddress', [address, config])
+          rows = raw['data'] || []
+
+          data = if transaction_details == :full
+                   # Returned verbatim so each element can be fed to
+                   # TransactionIntrospection.decode_transaction_from_rpc_response.
+                   rows
+                 else
+                   rows.map do |tx|
+                     TransactionsForAddressSignature.new(
+                       block_time:          tx['blockTime'],
+                       confirmation_status: tx['confirmationStatus']&.to_sym,
+                       err:                 tx['err'],
+                       memo:                tx['memo'],
+                       signature:           tx['signature'],
+                       slot:                Kernel.Integer(tx['slot']),
+                       transaction_index:   tx['transactionIndex'] && Kernel.Integer(tx['transactionIndex'])
+                     )
+                   end
+                 end
+
+          TransactionsForAddressPage.new(data: data, pagination_token: raw['paginationToken'])
+        end
+
+        # ── Private helpers ────────────────────────────────────────────────────
+
+        # Converts the snake_case +filters+ hash into its wire form. Symbol values
+        # (`status`, `token_accounts`) are lowerCamelCased so `:balance_changed`
+        # reaches the server as `"balanceChanged"`.
+        sig { params(filters: T::Hash[Symbol, T.untyped]).returns(T::Hash[String, T.untyped]) }
+        def build_filters(filters)
+          filters.each_with_object({}) do |(key, value), out|
+            wire_key = FILTER_KEYS[key]
+            Kernel.raise ArgumentError, "unknown filter #{key.inspect}" if wire_key.nil?
+
+            out[wire_key] = if value.is_a?(Hash)
+                              value.each_with_object({}) do |(op, operand), cmp|
+                                unless COMPARISON_KEYS.include?(op)
+                                  Kernel.raise ArgumentError, "unknown comparison #{op.inspect} in filter #{key.inspect}"
+                                end
+                                cmp[op.to_s] = operand
+                              end
+                            elsif value.is_a?(Symbol)
+                              camelize(value)
+                            else
+                              value
+                            end
+          end
+        end
+        private :build_filters
+
+        sig { params(value: Symbol).returns(String) }
+        def camelize(value)
+          head, *rest = value.to_s.split('_')
+          ([head] + rest.map(&:capitalize)).join
+        end
+        private :camelize
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc/api/get_vote_accounts.rb

@@ -12,6 +12,7 @@ module Solana::Ruby::Kit
           :activated_stake,
           :epoch_vote_account,
           :commission,
+          :inflation_rewards_commission_bps,
           :last_vote,
           :epoch_credits,
           :root_slot,
@@ -45,6 +46,7 @@ module Solana::Ruby::Kit
               activated_stake:    Kernel.Integer(v['activatedStake']),
               epoch_vote_account: v['epochVoteAccount'],
               commission:         Kernel.Integer(v['commission']),
+              inflation_rewards_commission_bps: v['inflationRewardsCommissionBps'] ? Kernel.Integer(v['inflationRewardsCommissionBps']) : nil,
               last_vote:          Kernel.Integer(v['lastVote']),
               epoch_credits:      v['epochCredits'],
               root_slot:          v['rootSlot'] ? Kernel.Integer(v['rootSlot']) : nil

data/lib/solana/ruby/kit/rpc/client.rb

@@ -24,6 +24,7 @@ require_relative 'api/get_block_time'
 require_relative 'api/get_epoch_schedule'
 require_relative 'api/get_inflation_reward'
 require_relative 'api/get_signatures_for_address'
+require_relative 'api/get_transactions_for_address'
 
 module Solana::Ruby::Kit
   module Rpc
@@ -64,6 +65,7 @@ module Solana::Ruby::Kit
       include Api::GetEpochSchedule
       include Api::GetInflationReward
       include Api::GetSignaturesForAddress
+      include Api::GetTransactionsForAddress
 
       sig { returns(Transport) }
       attr_reader :transport