solana-ruby-kit 0.1.8 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f96f7c22b28fbf9bec4186e3bf92ec52483d532b7e398da89bf143473b267878
-  data.tar.gz: 4a2e915aba2620726be4b5c89880c49fd7d54acf950618d4002ce19b54ac7884
+  metadata.gz: 7b2766067cfcd434e5c657e1fde1dab4b44b23880e0f514f924d28a94ea0ca4a
+  data.tar.gz: 32814612b342df38df079aaba08b8ea17c9128ac9f54279ab3abad622ba02492
 SHA512:
-  metadata.gz: 8a7fef4cd3632770e3e7d67f5b4722585f66f2ad45c601687d6664fc38433a85d39de7f4d582062e6396be7df29ea3cf089ca77184a7d8c28c3cf2b3d37015ae
-  data.tar.gz: '0967fe5ea552384a656b22f5f03d08674e4066c373e0ee83cc31bd45598573aacade37f4295a0c24341eb0e31b7d543720be99cf347aba0ab626429f5c629085'
+  metadata.gz: 3bcfbd20e6f610a47053cb385511931004590646ff04e0edf4587e5699df3db8bb148af2b706cf025e8399f26e4736ae9db35ebfd04d68be287df8302bc9f4de
+  data.tar.gz: d40b332b7cc427730b17b01a091c53815c596c0ac114bca93f52bed4d35775cd2b57ca5146893e2c94d46cebcbe0f51ccf98d2c6e2cad308cd51c2ff7b022d62

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

@@ -46,12 +46,20 @@ module Solana::Ruby::Kit
 
     # ── Transactions ──────────────────────────────────────────────────────────
     TRANSACTIONS__TRANSACTION_NOT_SIGNABLE               = :SOLANA_ERROR__TRANSACTIONS__TRANSACTION_NOT_SIGNABLE
+    TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT        = :SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT
+    TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT = :SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT
+    TRANSACTION__FAILED_TO_ESTIMATE_LOADED_ACCOUNTS_DATA_SIZE_LIMIT = :SOLANA_ERROR__TRANSACTION__FAILED_TO_ESTIMATE_LOADED_ACCOUNTS_DATA_SIZE_LIMIT
+    TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS = :SOLANA_ERROR__TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS
     TRANSACTIONS__EXCEEDS_SIZE_LIMIT                     = :SOLANA_ERROR__TRANSACTION__EXCEEDS_SIZE_LIMIT
     TRANSACTIONS__MISSING_SIGNER                         = :SOLANA_ERROR__TRANSACTIONS__MISSING_SIGNER
     TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE            = :SOLANA_ERROR__TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE
     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
@@ -88,13 +96,12 @@ module Solana::Ruby::Kit
     RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER = :SOLANA_ERROR__RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER
     RPC__INTEGER_OVERFLOW_WHILE_DESERIALIZING_LARGE_INTEGER = :SOLANA_ERROR__RPC__INTEGER_OVERFLOW_WHILE_DESERIALIZING_LARGE_INTEGER
     RPC__TRANSPORT_HTTP_ERROR                             = :SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR
-    # JSON-RPC server errors (-32017..-32019); context keys mirror TypeScript SolanaErrorContext:
-    #   EPOCH_REWARDS_PERIOD_ACTIVE: { slot:, current_block_height:, rewards_complete_block_height: }
-    #   SLOT_NOT_EPOCH_BOUNDARY:     { slot: }
-    #   LONG_TERM_STORAGE_UNREACHABLE: (no context)
+    # JSON-RPC server errors (see https://github.com/anza-xyz/kit/blob/main/packages/errors/src/codes.ts)
     JSON_RPC__SERVER_ERROR_EPOCH_REWARDS_PERIOD_ACTIVE    = :SOLANA_ERROR__JSON_RPC__SERVER_ERROR_EPOCH_REWARDS_PERIOD_ACTIVE
     JSON_RPC__SERVER_ERROR_SLOT_NOT_EPOCH_BOUNDARY        = :SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SLOT_NOT_EPOCH_BOUNDARY
     JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_UNREACHABLE  = :SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_UNREACHABLE
+    JSON_RPC__SERVER_ERROR_NO_SLOT_HISTORY                = :SOLANA_ERROR__JSON_RPC__SERVER_ERROR_NO_SLOT_HISTORY
+    JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND   = :SOLANA_ERROR__JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND
     RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_REQUEST = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_REQUEST
     RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID   = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID
     RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED = :SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED
@@ -115,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
@@ -172,12 +189,18 @@ module Solana::Ruby::Kit
 
         # Transactions
         TRANSACTIONS__TRANSACTION_NOT_SIGNABLE           => 'Transaction is not signable (missing fee payer or lifetime constraint)',
+        TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT    => 'Failed to estimate the compute unit consumption for this transaction message. This is likely because simulating the transaction failed.',
+        TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT => 'Transaction failed when it was simulated in order to estimate the compute unit consumption.',
+        TRANSACTION__FAILED_TO_ESTIMATE_LOADED_ACCOUNTS_DATA_SIZE_LIMIT => 'Failed to estimate the loaded accounts data size for this transaction message. The RPC did not return a loadedAccountsDataSize value from simulation. This value is required for version 1 transactions.',
+        TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS => 'Transaction failed when it was simulated in order to estimate its resource limits.',
         TRANSACTIONS__EXCEEDS_SIZE_LIMIT                 => 'Transaction wire size (%{actual_size} bytes) exceeds the limit of %{limit} bytes',
         TRANSACTIONS__MISSING_SIGNER                     => 'Transaction is missing a required signer: %{address}',
         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',
@@ -217,6 +240,8 @@ module Solana::Ruby::Kit
         JSON_RPC__SERVER_ERROR_EPOCH_REWARDS_PERIOD_ACTIVE      => 'Epoch rewards period still active at slot %{slot}',
         JSON_RPC__SERVER_ERROR_SLOT_NOT_EPOCH_BOUNDARY          => "Rewards cannot be found because slot %{slot} is not the epoch boundary. This may be due to gap in the queried node's local ledger or long-term storage",
         JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_UNREACHABLE    => 'Failed to query long-term storage; please try again',
+        JSON_RPC__SERVER_ERROR_NO_SLOT_HISTORY                  => 'No slot history',
+        JSON_RPC__SERVER_ERROR_FILTER_TRANSACTION_NOT_FOUND     => 'Filter transaction not found',
         RPC_SUBSCRIPTIONS__CANNOT_CREATE_SUBSCRIPTION_REQUEST  => 'Cannot create subscription request',
         RPC_SUBSCRIPTIONS__EXPECTED_SERVER_SUBSCRIPTION_ID     => 'Expected server to return a subscription ID',
         RPC_SUBSCRIPTIONS__CHANNEL_CLOSED_BEFORE_MESSAGE_BUFFERED => 'WebSocket channel closed before message could be buffered',
@@ -236,6 +261,13 @@ 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',

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/resource_limit_estimation.rb

@@ -0,0 +1,156 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require_relative 'errors'
+require_relative 'functional'
+require_relative 'transaction_messages'
+require_relative 'transaction_messages/compute_budget'
+require_relative 'transactions'
+
+module Solana::Ruby::Kit
+  # Utilities for estimating and setting transaction resource limits (compute units and
+  # loaded accounts data size) via simulation.
+  #
+  # Mirrors `estimateResourceLimitsFactory`, `estimateAndSetResourceLimitsFactory`,
+  # and `fillTransactionMessageProvisoryResourceLimits` from @solana/kit.
+  module ResourceLimitEstimation
+    extend T::Sig
+
+    PROVISORY_LIMIT = T.let(0, Integer)
+
+    module_function
+
+    # Returns a callable that estimates the resource limits required by a transaction message
+    # by simulating it with maximum limits set, then reading back the actual consumption.
+    #
+    # The returned callable accepts a TransactionMessage and optional keyword args:
+    #   commitment:        Symbol (nil uses RPC default)
+    #   min_context_slot:  Integer
+    #
+    # Returns a Hash with:
+    #   :compute_unit_limit              Integer (always present)
+    #   :loaded_accounts_data_size_limit Integer (present when the RPC returns it)
+    #
+    # Raises SolanaError with TRANSACTION__FAILED_TO_ESTIMATE_LOADED_ACCOUNTS_DATA_SIZE_LIMIT
+    # if the message is version 1 but the RPC does not return loadedAccountsDataSize.
+    # Raises SolanaError with TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS
+    # if the simulated transaction itself fails.
+    # Raises SolanaError with TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT for any other error.
+    #
+    # Mirrors `estimateResourceLimitsFactory({ rpc })` from @solana/kit.
+    sig { params(rpc: T.untyped).returns(T.untyped) }
+    def estimate_resource_limits_factory(rpc:)
+      ->(transaction_message, commitment: nil, min_context_slot: nil) do
+        replace_recent_blockhash = !TransactionMessages.durable_nonce_lifetime?(transaction_message)
+        is_v1 = transaction_message.version == 1
+
+        tx_for_sim = Functional.pipe(
+          transaction_message,
+          ->(m) { TransactionMessages.set_transaction_message_compute_unit_limit(TransactionMessages::MAX_COMPUTE_UNIT_LIMIT, m) },
+          ->(m) { is_v1 ? TransactionMessages.set_transaction_message_loaded_accounts_data_size_limit(TransactionMessages::MAX_LOADED_ACCOUNTS_DATA_SIZE_LIMIT, m) : m }
+        )
+
+        transaction = Transactions.compile_transaction_message(tx_for_sim)
+        wire_bytes  = Transactions.wire_encode_transaction(transaction)
+        encoded     = Base64.strict_encode64(wire_bytes)
+
+        sim_opts = { replace_recent_blockhash: replace_recent_blockhash }
+        sim_opts[:commitment]       = commitment       if commitment
+        sim_opts[:min_context_slot] = min_context_slot if min_context_slot
+
+        begin
+          sim_value = rpc.simulate_transaction(encoded, **sim_opts).value
+
+          transaction_error         = sim_value['err']
+          units_consumed            = sim_value['unitsConsumed']
+          loaded_accounts_data_size = sim_value['loadedAccountsDataSize']
+
+          if is_v1 && loaded_accounts_data_size.nil?
+            Kernel.raise SolanaError.new(SolanaError::TRANSACTION__FAILED_TO_ESTIMATE_LOADED_ACCOUNTS_DATA_SIZE_LIMIT)
+          end
+
+          if transaction_error
+            Kernel.raise SolanaError.new(
+              SolanaError::TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS
+            )
+          end
+
+          compute_unit_limit = [units_consumed.to_i, 4_294_967_295].min
+
+          estimate = { compute_unit_limit: compute_unit_limit }
+          estimate[:loaded_accounts_data_size_limit] = loaded_accounts_data_size.to_i unless loaded_accounts_data_size.nil?
+          estimate
+        rescue SolanaError => e
+          known = [
+            SolanaError::TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS,
+            SolanaError::TRANSACTION__FAILED_TO_ESTIMATE_LOADED_ACCOUNTS_DATA_SIZE_LIMIT
+          ]
+          Kernel.raise if known.include?(e.code)
+          Kernel.raise SolanaError.new(SolanaError::TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT)
+        rescue StandardError
+          Kernel.raise SolanaError.new(SolanaError::TRANSACTION__FAILED_TO_ESTIMATE_COMPUTE_LIMIT)
+        end
+      end
+    end
+
+    # Returns a callable that estimates resource limits for a transaction message and
+    # sets them on the message, unless they are already explicitly configured.
+    #
+    # A limit of 0 (the provisory value) or the maximum (1,400,000 for CU) is treated
+    # as non-explicit and will be replaced with the estimate.
+    #
+    # Mirrors `estimateAndSetResourceLimitsFactory(estimator)` from @solana/kit.
+    sig { params(estimate_resource_limits: T.untyped).returns(T.untyped) }
+    def estimate_and_set_resource_limits_factory(estimate_resource_limits)
+      ->(transaction_message, **opts) do
+        existing_cu = TransactionMessages.get_transaction_message_compute_unit_limit(transaction_message)
+        cu_explicit = !existing_cu.nil? &&
+                      existing_cu != PROVISORY_LIMIT &&
+                      existing_cu != TransactionMessages::MAX_COMPUTE_UNIT_LIMIT
+
+        is_v1 = transaction_message.version == 1
+        loaded_explicit = true
+        if is_v1
+          existing_loaded = TransactionMessages.get_transaction_message_loaded_accounts_data_size_limit(transaction_message)
+          loaded_explicit = !existing_loaded.nil? && existing_loaded != PROVISORY_LIMIT
+        end
+
+        return transaction_message if cu_explicit && loaded_explicit
+
+        estimate = estimate_resource_limits.call(transaction_message, **opts)
+
+        result = transaction_message
+        unless cu_explicit
+          result = TransactionMessages.set_transaction_message_compute_unit_limit(estimate[:compute_unit_limit], result)
+        end
+        if is_v1 && !loaded_explicit && estimate.key?(:loaded_accounts_data_size_limit)
+          result = TransactionMessages.set_transaction_message_loaded_accounts_data_size_limit(estimate[:loaded_accounts_data_size_limit], result)
+        end
+        result
+      end
+    end
+
+    # Sets compute unit limit (and, for V1, loaded accounts data size limit) to the
+    # provisory value of 0 on the message, unless a limit is already present.
+    #
+    # Use this during message construction to reserve space for limits that will later
+    # be replaced with actual estimates via `estimate_and_set_resource_limits_factory`.
+    #
+    # Mirrors `fillTransactionMessageProvisoryResourceLimits` from @solana/kit.
+    sig do
+      params(message: TransactionMessages::TransactionMessage)
+        .returns(TransactionMessages::TransactionMessage)
+    end
+    def fill_transaction_message_provisory_resource_limits(message)
+      result = message
+      if TransactionMessages.get_transaction_message_compute_unit_limit(result).nil?
+        result = TransactionMessages.set_transaction_message_compute_unit_limit(PROVISORY_LIMIT, result)
+      end
+      if result.version == 1 && TransactionMessages.get_transaction_message_loaded_accounts_data_size_limit(result).nil?
+        result = TransactionMessages.set_transaction_message_loaded_accounts_data_size_limit(PROVISORY_LIMIT, result)
+      end
+      result
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Struct representing one transaction signature entry returned by getSignaturesForAddress.
+      # Mirrors TypeScript's GetSignaturesForAddressTransaction.
+      SignatureInfo = 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 | nil — 0-based index within block (Agave 4.0+)
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # Returns confirmed transaction signatures that reference the given address.
+      # Mirrors TypeScript's GetSignaturesForAddressApi.getSignaturesForAddress.
+      # See https://solana.com/docs/rpc/http/getsignaturesforaddress
+      module GetSignaturesForAddress
+        extend T::Sig
+
+        sig do
+          params(
+            address:          String,
+            before:           T.nilable(String),
+            until_sig:        T.nilable(String),
+            limit:            T.nilable(Integer),
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer)
+          ).returns(T::Array[T.untyped])
+        end
+        def get_signatures_for_address(
+          address,
+          before:           nil,
+          until_sig:        nil,
+          limit:            nil,
+          commitment:       nil,
+          min_context_slot: nil
+        )
+          config = {}
+          config['before']           = before if before
+          config['until']            = until_sig if until_sig
+          config['limit']            = limit if limit
+          config['commitment']       = commitment.to_s if commitment
+          config['minContextSlot']   = min_context_slot if min_context_slot
+
+          params = config.empty? ? [address] : [address, config]
+          result = transport.request('getSignaturesForAddress', params)
+
+          result.map do |tx|
+            SignatureInfo.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']
+            )
+          end
+        end
+      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

@@ -23,6 +23,7 @@ require_relative 'api/simulate_transaction'
 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'
 
 module Solana::Ruby::Kit
   module Rpc
@@ -62,6 +63,7 @@ module Solana::Ruby::Kit
       include Api::GetBlockTime
       include Api::GetEpochSchedule
       include Api::GetInflationReward
+      include Api::GetSignaturesForAddress
 
       sig { returns(Transport) }
       attr_reader :transport