solana-ruby-kit 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 328621bd69f0601b600df302ea5169001983cf56fa44cf23225e3f2515d5d34a
-  data.tar.gz: 5e2bc165e53ff6818b5650f5d8551e6ec3331f65df3e656d0bb7ecd588c16fb3
+  metadata.gz: 12771cac3706269f104b012ee691d4cd42856f61560d54b9e959308184c90be6
+  data.tar.gz: 52bc18d7dff9bce3c2f27115772275e8a2b0decd985faa4ef2f43723056030d9
 SHA512:
-  metadata.gz: 7664963dae246c46ef5d09c7f1d3d05b5c67cecc38dbd961955da8e86cce9a4d0aeff55fcc47425b35826dfe552bb032715f5f178dea8e8c716828013ebb151d
-  data.tar.gz: a5ee1ed23cca39029dc7a5e84f6319f06ef3319aaeb62488b12b702c6f7c391b8256ed7c706c140e4242285042a4d5b8c0ce7eb0fa484368a182556aa7ac0b84
+  metadata.gz: c1f7feeaf404a2911bf4498377e2e2426f10357cd415cb70e4a57d70b05a81a73b51b817983e33bd1a9aa169ee9dcd9d80018c050964b0a51ada8afebba772d2
+  data.tar.gz: 6f3f9b4d8de10136120b08d4be8927ba13546edc902f81a3f46b64e89e5947b9623ef3645857c721c44bd5bc7d16c4ba13eee74d65bca03d09bee78fd0b3a932

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

@@ -46,6 +46,7 @@ module Solana::Ruby::Kit
 
     # ── Transactions ──────────────────────────────────────────────────────────
     TRANSACTIONS__TRANSACTION_NOT_SIGNABLE               = :SOLANA_ERROR__TRANSACTIONS__TRANSACTION_NOT_SIGNABLE
+    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
@@ -87,6 +88,13 @@ 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_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
     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
@@ -101,9 +109,18 @@ module Solana::Ruby::Kit
     OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG                  = :SOLANA_ERROR__OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG
     OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN    = :SOLANA_ERROR__OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN
 
+    # ── Instruction plans ─────────────────────────────────────────────────────
+    # context: { num_bytes_required:, num_free_bytes: }
+    INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN      = :SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN
+    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
+
     # ── Invariant violations (internal) ──────────────────────────────────────
     INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING = :SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING
     INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE = :SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE
+    INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND      = :SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND
+    INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND      = :SOLANA_ERROR__INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND
 
     ERROR_MESSAGES = T.let(
       {
@@ -145,6 +162,7 @@ module Solana::Ruby::Kit
 
         # Transactions
         TRANSACTIONS__TRANSACTION_NOT_SIGNABLE           => 'Transaction is not signable (missing fee payer or lifetime constraint)',
+        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',
@@ -186,6 +204,9 @@ module Solana::Ruby::Kit
         RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER   => 'Integer overflow while serializing large integer %{value}',
         RPC__INTEGER_OVERFLOW_WHILE_DESERIALIZING_LARGE_INTEGER => 'Integer overflow while deserializing large integer %{value}',
         RPC__TRANSPORT_HTTP_ERROR                               => 'HTTP transport error: %{status} %{message}',
+        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',
         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',
@@ -200,9 +221,17 @@ module Solana::Ruby::Kit
         OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG              => 'Offchain message is too long (%{length} bytes, max %{max})',
         OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN => 'Offchain message signing domain must not start with a null byte',
 
+        # Instruction plans
+        INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN    => 'Transaction message cannot accommodate the plan: requires %{num_bytes_required} bytes but only %{num_free_bytes} are available',
+        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',
+
         # Invariant violations
         INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING => 'Subscription iterator state is missing (internal error)',
         INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE => 'Subscription iterator must not poll before resolving existing message (internal error)',
+        INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND    => 'Invalid instruction plan kind: %{kind} (internal error)',
+        INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND    => 'Invalid transaction plan kind: %{kind} (internal error)',
       }.freeze,
       T::Hash[Symbol, String]
     )

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

@@ -0,0 +1,251 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../instructions/instruction'
+require_relative '../transaction_messages/transaction_message'
+require_relative '../transactions/compiler'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # ── Plan types ─────────────────────────────────────────────────────────────
+    #
+    # InstructionPlan is a recursive tree that describes operations which may
+    # span multiple transactions. Mirrors @solana/instruction-plans.
+    #
+    #   InstructionPlan = SingleInstructionPlan
+    #                   | SequentialInstructionPlan
+    #                   | ParallelInstructionPlan
+    #                   | MessagePackerInstructionPlan
+
+    # A plan that wraps a single instruction.
+    class SingleInstructionPlan < T::Struct
+      const :instruction, Instructions::Instruction
+      def kind = :single
+    end
+
+    # A plan whose children must execute in order.
+    # +divisible: true+ allows the planner to split children across transactions.
+    # +divisible: false+ means all children should be atomic (one tx or a bundle).
+    class SequentialInstructionPlan < T::Struct
+      const :plans,     T::Array[T.untyped]  # Array[InstructionPlan]
+      const :divisible, T::Boolean
+      def kind = :sequential
+    end
+
+    # A plan whose children may execute concurrently or be packed in any order.
+    class ParallelInstructionPlan < T::Struct
+      const :plans, T::Array[T.untyped]  # Array[InstructionPlan]
+      def kind = :parallel
+    end
+
+    # Provides a MessagePacker that dynamically packs instructions into messages.
+    # The +get_message_packer+ proc returns a fresh MessagePacker each call.
+    class MessagePackerInstructionPlan < T::Struct
+      const :get_message_packer, T.untyped  # Proc -> MessagePacker
+      def kind = :message_packer
+    end
+
+    # Returned by MessagePackerInstructionPlan#get_message_packer.
+    # Mirrors the TypeScript MessagePacker interface.
+    class MessagePacker
+      extend T::Sig
+
+      sig { params(done_proc: T.untyped, pack_proc: T.untyped).void }
+      def initialize(done_proc:, pack_proc:)
+        @done_proc = T.let(done_proc, T.untyped)
+        @pack_proc = T.let(pack_proc, T.untyped)
+      end
+
+      # Returns true when all instructions have been packed.
+      sig { returns(T::Boolean) }
+      def done?
+        @done_proc.call
+      end
+
+      # 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)
+      end
+    end
+
+    # ── Factory helpers ────────────────────────────────────────────────────────
+
+    module_function
+
+    # Wraps a single instruction in a plan.
+    # Mirrors `singleInstructionPlan(instruction)`.
+    sig { params(instruction: Instructions::Instruction).returns(SingleInstructionPlan) }
+    def single_instruction_plan(instruction)
+      SingleInstructionPlan.new(instruction: instruction)
+    end
+
+    # Creates a divisible sequential plan (children may be split across txs).
+    # Mirrors `sequentialInstructionPlan(plans)`.
+    # Accepts raw Instruction objects; wraps them in SingleInstructionPlan automatically.
+    sig { params(plans: T::Array[T.untyped]).returns(SequentialInstructionPlan) }
+    def sequential_instruction_plan(plans)
+      SequentialInstructionPlan.new(plans: parse_single_instruction_plans(plans), divisible: true)
+    end
+
+    # Creates a non-divisible sequential plan (children must be atomic).
+    # Mirrors `nonDivisibleSequentialInstructionPlan(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(SequentialInstructionPlan) }
+    def non_divisible_sequential_instruction_plan(plans)
+      SequentialInstructionPlan.new(plans: parse_single_instruction_plans(plans), divisible: false)
+    end
+
+    # Creates a parallel plan (children may execute concurrently).
+    # Mirrors `parallelInstructionPlan(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(ParallelInstructionPlan) }
+    def parallel_instruction_plan(plans)
+      ParallelInstructionPlan.new(plans: parse_single_instruction_plans(plans))
+    end
+
+    # Creates a MessagePackerInstructionPlan that packs a fixed byte stream into
+    # instructions of maximum size, calling +get_instruction.(offset, length)+.
+    # Mirrors `getLinearMessagePackerInstructionPlan({ getInstruction, totalLength })`.
+    sig do
+      params(
+        total_length:    Integer,
+        get_instruction: T.untyped  # Proc(offset, length) -> Instruction
+      ).returns(MessagePackerInstructionPlan)
+    end
+    def get_linear_message_packer_instruction_plan(total_length:, get_instruction:)
+      MessagePackerInstructionPlan.new(
+        get_message_packer: -> {
+          offset = T.let(0, Integer)
+          MessagePacker.new(
+            done_proc: -> { offset >= total_length },
+            pack_proc:  ->(message) {
+              if offset >= total_length
+                Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE)
+              end
+
+              base_ix    = get_instruction.call(offset, 0)
+              with_base  = TransactionMessages.append_instructions(message, [base_ix])
+              base_size  = Transactions.get_transaction_message_size(with_base)
+              # -1 leeway for compact-u16 headers
+              free_space = Transactions::TRANSACTION_SIZE_LIMIT - base_size - 1
+
+              if free_space <= 0
+                msg_size = Transactions.get_transaction_message_size(message)
+                Kernel.raise SolanaError.new(
+                  SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+                  {
+                    num_bytes_required: base_size - msg_size + 1,
+                    num_free_bytes:     Transactions::TRANSACTION_SIZE_LIMIT - msg_size - 1
+                  }
+                )
+              end
+
+              length = [total_length - offset, free_space].min
+              ix     = get_instruction.call(offset, length)
+              offset += length
+              TransactionMessages.append_instructions(message, [ix])
+            }
+          )
+        }
+      )
+    end
+
+    # Creates a MessagePackerInstructionPlan that iterates over a fixed list of
+    # instructions, packing as many as fit into each message.
+    # Mirrors `getMessagePackerInstructionPlanFromInstructions(instructions)`.
+    sig { params(instructions: T::Array[Instructions::Instruction]).returns(MessagePackerInstructionPlan) }
+    def get_message_packer_instruction_plan_from_instructions(instructions)
+      MessagePackerInstructionPlan.new(
+        get_message_packer: -> {
+          idx = T.let(0, Integer)
+          MessagePacker.new(
+            done_proc: -> { idx >= instructions.length },
+            pack_proc:  ->(message) {
+              if idx >= instructions.length
+                Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE)
+              end
+
+              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)
+
+                if size > Transactions::TRANSACTION_SIZE_LIMIT
+                  if i == start_idx
+                    Kernel.raise SolanaError.new(
+                      SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+                      {
+                        num_bytes_required: size - original_size,
+                        num_free_bytes:     Transactions::TRANSACTION_SIZE_LIMIT - original_size
+                      }
+                    )
+                  end
+                  idx = i
+                  return packed
+                end
+              end
+
+              idx = instructions.length
+              packed
+            }
+          )
+        }
+      )
+    end
+
+    # Creates a MessagePackerInstructionPlan that splits +total_size+ bytes into
+    # chunks of REALLOC_LIMIT (10,240) bytes, calling +get_instruction.(size)+.
+    # Mirrors `getReallocMessagePackerInstructionPlan({ getInstruction, totalSize })`.
+    sig do
+      params(
+        total_size:      Integer,
+        get_instruction: T.untyped  # Proc(size) -> Instruction
+      ).returns(MessagePackerInstructionPlan)
+    end
+    def get_realloc_message_packer_instruction_plan(total_size:, get_instruction:)
+      realloc_limit      = 10_240
+      num_instructions   = (total_size.to_f / realloc_limit).ceil
+      last_size          = total_size % realloc_limit
+
+      instructions = num_instructions.times.map do |i|
+        chunk = (i == num_instructions - 1) ? last_size : realloc_limit
+        get_instruction.call(chunk)
+      end
+
+      get_message_packer_instruction_plan_from_instructions(instructions)
+    end
+
+    # Recursively extracts all instructions from a plan tree (depth-first).
+    sig { params(plan: T.untyped).returns(T::Array[Instructions::Instruction]) }
+    def flatten_instruction_plan(plan)
+      case plan
+      when SingleInstructionPlan
+        [plan.instruction]
+      when SequentialInstructionPlan, ParallelInstructionPlan
+        plan.plans.flat_map { |p| flatten_instruction_plan(p) }
+      when MessagePackerInstructionPlan
+        Kernel.raise ArgumentError, 'Cannot flatten a MessagePackerInstructionPlan (instructions are dynamically generated)'
+      else
+        Kernel.raise ArgumentError, "Unknown InstructionPlan type: #{plan.class}"
+      end
+    end
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    # Wraps bare Instruction objects in SingleInstructionPlan; passes plans through.
+    sig { params(items: T::Array[T.untyped]).returns(T::Array[T.untyped]) }
+    def parse_single_instruction_plans(items)
+      items.map do |item|
+        item.is_a?(Instructions::Instruction) ? single_instruction_plan(item) : item
+      end
+    end
+    private_class_method :parse_single_instruction_plans
+  end
+end

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

@@ -1,27 +1,5 @@
 # typed: strict
 # frozen_string_literal: true
 
-module Solana::Ruby::Kit
-  module InstructionPlans
-    # A plan that wraps a single instruction.
-    class SingleInstructionPlan < T::Struct
-      const :instruction, Instructions::Instruction
-    end
-
-    # A plan that executes a sequence of sub-plans in order.
-    # When +divisible+ is true the planner may split steps across transactions.
-    class SequentialInstructionPlan < T::Struct
-      const :steps,     T::Array[T.untyped]  # Array[InstructionPlan]
-      const :divisible, T::Boolean, default: false
-    end
-
-    # A plan whose sub-plans may execute concurrently or be packed into the
-    # same transaction in any order.
-    class ParallelInstructionPlan < T::Struct
-      const :plans, T::Array[T.untyped]  # Array[InstructionPlan]
-    end
-
-    # Union type alias (used only in doc strings; Ruby is duck-typed).
-    # InstructionPlan = SingleInstructionPlan | SequentialInstructionPlan | ParallelInstructionPlan
-  end
-end
+# Kept for backwards compatibility — content moved to instruction_plan.rb.
+require_relative 'instruction_plan'

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

@@ -0,0 +1,91 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../transaction_messages/transaction_message'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # ── Transaction plan types ────────────────────────────────────────────────
+    #
+    # A TransactionPlan is a recursive tree of compiled transaction messages that
+    # mirrors the structure of an InstructionPlan after the planner has resolved it.
+    #
+    #   TransactionPlan = SingleTransactionPlan
+    #                   | SequentialTransactionPlan
+    #                   | ParallelTransactionPlan
+
+    class SingleTransactionPlan < T::Struct
+      const :message, TransactionMessages::TransactionMessage
+      def kind = :single
+    end
+
+    class SequentialTransactionPlan < T::Struct
+      const :plans,     T::Array[T.untyped]  # Array[TransactionPlan]
+      const :divisible, T::Boolean
+      def kind = :sequential
+    end
+
+    class ParallelTransactionPlan < T::Struct
+      const :plans, T::Array[T.untyped]  # Array[TransactionPlan]
+      def kind = :parallel
+    end
+
+    module_function
+
+    # Creates a single-message plan.
+    # Mirrors `singleTransactionPlan(transactionMessage)`.
+    sig { params(message: TransactionMessages::TransactionMessage).returns(SingleTransactionPlan) }
+    def single_transaction_plan(message)
+      SingleTransactionPlan.new(message: message)
+    end
+
+    # Creates a divisible sequential plan.
+    # Accepts TransactionMessage objects directly (wraps them automatically).
+    # Mirrors `sequentialTransactionPlan(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(SequentialTransactionPlan) }
+    def sequential_transaction_plan(plans)
+      SequentialTransactionPlan.new(plans: parse_single_transaction_plans(plans), divisible: true)
+    end
+
+    # Creates a non-divisible sequential plan.
+    # Mirrors `nonDivisibleSequentialTransactionPlan(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(SequentialTransactionPlan) }
+    def non_divisible_sequential_transaction_plan(plans)
+      SequentialTransactionPlan.new(plans: parse_single_transaction_plans(plans), divisible: false)
+    end
+
+    # Creates a parallel plan.
+    # Accepts TransactionMessage objects directly (wraps them automatically).
+    # Mirrors `parallelTransactionPlan(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(ParallelTransactionPlan) }
+    def parallel_transaction_plan(plans)
+      ParallelTransactionPlan.new(plans: parse_single_transaction_plans(plans))
+    end
+
+    # Recursively collects all SingleTransactionPlan leaves from a plan tree.
+    # Mirrors `getAllSingleTransactionPlans(transactionPlan)`.
+    sig { params(plan: T.untyped).returns(T::Array[SingleTransactionPlan]) }
+    def get_all_single_transaction_plans(plan)
+      case plan
+      when SingleTransactionPlan
+        [plan]
+      when SequentialTransactionPlan, ParallelTransactionPlan
+        plan.plans.flat_map { |p| get_all_single_transaction_plans(p) }
+      else
+        Kernel.raise ArgumentError, "Unknown TransactionPlan type: #{plan.class}"
+      end
+    end
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    sig { params(items: T::Array[T.untyped]).returns(T::Array[T.untyped]) }
+    def parse_single_transaction_plans(items)
+      items.map do |item|
+        item.is_a?(TransactionMessages::TransactionMessage) ? single_transaction_plan(item) : item
+      end
+    end
+    private_class_method :parse_single_transaction_plans
+  end
+end

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

@@ -0,0 +1,117 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative 'transaction_plan'
+require_relative 'transaction_plan_result'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # Creates a TransactionPlanExecutor — a callable that traverses a TransactionPlan,
+    # executing each single transaction message and collecting results.
+    #
+    # Configuration:
+    #   execute_transaction_message: ->(message) { { transaction:, context: } }
+    #     Called for each SingleTransactionPlan. Must return a hash with:
+    #       :transaction — the signed Transaction
+    #       :context     — optional Hash of extra data (defaults to {})
+    #     Raise a SolanaError to signal failure; remaining plans will be canceled.
+    #
+    # The returned executor is a lambda: executor.call(transaction_plan) -> TransactionPlanResult
+    #
+    # Mirrors `createTransactionPlanExecutor(config)` from @solana/instruction-plans.
+    # NOTE: Ruby translation is synchronous; abort-signal support is omitted.
+    sig { params(execute_transaction_message: T.untyped).returns(T.untyped) }
+    def create_transaction_plan_executor(execute_transaction_message:)
+      ->(transaction_plan) {
+        state  = { canceled: false }
+        result = executor_traverse(transaction_plan, execute_transaction_message, state)
+
+        if state[:canceled]
+          cause = executor_find_error(result)
+          err   = SolanaError.new(
+            SolanaError::INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN,
+            { cause: cause }
+          )
+          # Store the full result tree as a non-enumerable attribute for recovery.
+          err.instance_variable_set(:@transaction_plan_result, result)
+          err.define_singleton_method(:transaction_plan_result) { @transaction_plan_result }
+          Kernel.raise err
+        end
+
+        result
+      }
+    end
+
+    module_function :create_transaction_plan_executor
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    module_function
+
+    def executor_traverse(plan, execute_fn, state)
+      case plan.kind
+      when :sequential then executor_traverse_sequential(plan, execute_fn, state)
+      when :parallel   then executor_traverse_parallel(plan, execute_fn, state)
+      when :single     then executor_traverse_single(plan, execute_fn, state)
+      else
+        Kernel.raise SolanaError.new(
+          SolanaError::INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND,
+          { kind: plan.kind }
+        )
+      end
+    end
+
+    def executor_traverse_sequential(plan, execute_fn, state)
+      results = plan.plans.map { |sub| executor_traverse(sub, execute_fn, state) }
+      plan.divisible \
+        ? sequential_transaction_plan_result(results) \
+        : non_divisible_sequential_transaction_plan_result(results)
+    end
+
+    def executor_traverse_parallel(plan, execute_fn, state)
+      results = plan.plans.map { |sub| executor_traverse(sub, execute_fn, state) }
+      parallel_transaction_plan_result(results)
+    end
+
+    def executor_traverse_single(plan, execute_fn, state)
+      return canceled_single_transaction_plan_result(plan.message) if state[:canceled]
+
+      begin
+        result      = execute_fn.call(plan.message)
+        transaction = result.fetch(:transaction)
+        context     = result.fetch(:context, {})
+        successful_single_transaction_plan_result(plan.message, transaction, context)
+      rescue SolanaError => e
+        state[:canceled] = true
+        failed_single_transaction_plan_result(plan.message, e)
+      rescue => e
+        state[:canceled] = true
+        wrapped = SolanaError.new(
+          SolanaError::INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN,
+          { cause: e }
+        )
+        failed_single_transaction_plan_result(plan.message, wrapped)
+      end
+    end
+
+    def executor_find_error(result)
+      return result.status.error if result.kind == :single && result.status.kind == :failed
+      return nil                 if result.kind == :single
+
+      result.plans.each do |sub|
+        err = executor_find_error(sub)
+        return err if err
+      end
+      nil
+    end
+
+    private_class_method :executor_traverse
+    private_class_method :executor_traverse_sequential
+    private_class_method :executor_traverse_parallel
+    private_class_method :executor_traverse_single
+    private_class_method :executor_find_error
+  end
+end