solana-ruby-kit 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be22a1330f9190db447c2a209a2dc44991c75efc6758bbe9e94f6e56b579473
-  data.tar.gz: c33dc52550866af9c572ce7911fe0baa9d053dc0f4723e5b700f0473ee5ffee4
+  metadata.gz: 12771cac3706269f104b012ee691d4cd42856f61560d54b9e959308184c90be6
+  data.tar.gz: 52bc18d7dff9bce3c2f27115772275e8a2b0decd985faa4ef2f43723056030d9
 SHA512:
-  metadata.gz: ee653c6ea8f2b6b2dd5359e6d49281431d9127db48600d836d560ebd32dde7e75294fc6cc44f8b609de4fb0bc565bf3e810a30ca050ce78d7e8506177e7ba6cd
-  data.tar.gz: 5483176779980f87b8102e81dca85afc4f71a413281b5b296d50edee38ebae9b000c370d75362a442abd84589ec6014b661e075623aa5ba7cf5920df0b20bd4b
+  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

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

@@ -0,0 +1,117 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../transaction_messages/transaction_message'
+require_relative '../transactions/transaction'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # ── Result status types ───────────────────────────────────────────────────
+    #
+    # Each single transaction produces one of three statuses:
+    #   successful: { kind: :successful, transaction:, context: }
+    #   failed:     { kind: :failed,     error: }
+    #   canceled:   { kind: :canceled }
+    #
+    # Mirrors TypeScript's TransactionPlanResultStatus union.
+
+    class SuccessfulStatus < T::Struct
+      const :transaction, Transactions::Transaction
+      const :context,     T::Hash[T.untyped, T.untyped]
+      def kind = :successful
+    end
+
+    class FailedStatus < T::Struct
+      const :error, SolanaError
+      def kind = :failed
+    end
+
+    class CanceledStatus < T::Struct
+      def kind = :canceled
+    end
+
+    # ── Result plan types ──────────────────────────────────────────────────────
+
+    class SingleTransactionPlanResult < T::Struct
+      const :message, TransactionMessages::TransactionMessage
+      const :status,  T.untyped  # SuccessfulStatus | FailedStatus | CanceledStatus
+      def kind = :single
+    end
+
+    class SequentialTransactionPlanResult < T::Struct
+      const :plans,     T::Array[T.untyped]  # Array[TransactionPlanResult]
+      const :divisible, T::Boolean
+      def kind = :sequential
+    end
+
+    class ParallelTransactionPlanResult < T::Struct
+      const :plans, T::Array[T.untyped]  # Array[TransactionPlanResult]
+      def kind = :parallel
+    end
+
+    module_function
+
+    # ── Result factory helpers ────────────────────────────────────────────────
+
+    # Mirrors `sequentialTransactionPlanResult(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(SequentialTransactionPlanResult) }
+    def sequential_transaction_plan_result(plans)
+      SequentialTransactionPlanResult.new(plans: plans, divisible: true)
+    end
+
+    # Mirrors `nonDivisibleSequentialTransactionPlanResult(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(SequentialTransactionPlanResult) }
+    def non_divisible_sequential_transaction_plan_result(plans)
+      SequentialTransactionPlanResult.new(plans: plans, divisible: false)
+    end
+
+    # Mirrors `parallelTransactionPlanResult(plans)`.
+    sig { params(plans: T::Array[T.untyped]).returns(ParallelTransactionPlanResult) }
+    def parallel_transaction_plan_result(plans)
+      ParallelTransactionPlanResult.new(plans: plans)
+    end
+
+    # Mirrors `successfulSingleTransactionPlanResult(message, transaction, context)`.
+    sig do
+      params(
+        message:     TransactionMessages::TransactionMessage,
+        transaction: Transactions::Transaction,
+        context:     T::Hash[T.untyped, T.untyped]
+      ).returns(SingleTransactionPlanResult)
+    end
+    def successful_single_transaction_plan_result(message, transaction, context = {})
+      SingleTransactionPlanResult.new(
+        message: message,
+        status:  SuccessfulStatus.new(transaction: transaction, context: context)
+      )
+    end
+
+    # Mirrors `failedSingleTransactionPlanResult(message, error)`.
+    sig do
+      params(
+        message: TransactionMessages::TransactionMessage,
+        error:   SolanaError
+      ).returns(SingleTransactionPlanResult)
+    end
+    def failed_single_transaction_plan_result(message, error)
+      SingleTransactionPlanResult.new(
+        message: message,
+        status:  FailedStatus.new(error: error)
+      )
+    end
+
+    # Mirrors `canceledSingleTransactionPlanResult(message)`.
+    sig do
+      params(message: TransactionMessages::TransactionMessage).returns(SingleTransactionPlanResult)
+    end
+    def canceled_single_transaction_plan_result(message)
+      SingleTransactionPlanResult.new(
+        message: message,
+        status:  CanceledStatus.new
+      )
+    end
+  end
+end

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

@@ -0,0 +1,264 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../transaction_messages/transaction_message'
+require_relative '../transactions/compiler'
+require_relative 'instruction_plan'
+require_relative 'transaction_plan'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # Creates a TransactionPlanner — a callable that converts an InstructionPlan
+    # into a TransactionPlan by packing instructions into transaction messages.
+    #
+    # Configuration:
+    #   create_transaction_message: -> { TransactionMessage }
+    #     Called whenever a new (empty) message is needed. Must return a message
+    #     with at least a fee payer and blockhash already set.
+    #
+    #   on_transaction_message_updated: ->(message) { TransactionMessage }  (optional)
+    #     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
+    #
+    # 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
+      ).returns(T.untyped)
+    end
+    def create_transaction_planner(
+      create_transaction_message:,
+      on_transaction_message_updated: ->(msg) { msg }
+    )
+      ctx = {
+        create_transaction_message:     create_transaction_message,
+        on_transaction_message_updated: on_transaction_message_updated
+      }
+
+      ->(instruction_plan) {
+        mutable = planner_traverse(instruction_plan, ctx.merge(parent: nil, parent_candidates: []))
+        Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN) unless mutable
+        planner_freeze(mutable)
+      }
+    end
+
+    module_function :create_transaction_planner
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    module_function
+
+    def planner_traverse(plan, ctx)
+      case plan.kind
+      when :sequential     then planner_traverse_sequential(plan, ctx)
+      when :parallel       then planner_traverse_parallel(plan, ctx)
+      when :single         then planner_traverse_single(plan, ctx)
+      when :message_packer then planner_traverse_message_packer(plan, ctx)
+      else
+        Kernel.raise SolanaError.new(
+          SolanaError::INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND,
+          { kind: plan.kind }
+        )
+      end
+    end
+
+    def planner_traverse_sequential(plan, ctx)
+      must_fit_in_parent = ctx[:parent] && (ctx[:parent].kind == :parallel || !plan.divisible)
+
+      if must_fit_in_parent
+        candidate = planner_select_and_mutate_candidate(ctx, ctx[:parent_candidates]) do |msg|
+          planner_fit_entire_plan(plan, msg, ctx)
+        end
+        return nil if candidate
+      end
+
+      candidate = (!must_fit_in_parent && !ctx[:parent_candidates].empty?) ? ctx[:parent_candidates][0] : nil
+      tx_plans  = []
+
+      plan.plans.each do |sub_plan|
+        sub_ctx = ctx.merge(parent: plan, parent_candidates: candidate ? [candidate] : [])
+        tx_plan = planner_traverse(sub_plan, sub_ctx)
+        next unless tx_plan
+
+        candidate = planner_get_sequential_candidate(tx_plan)
+        new_plans =
+          tx_plan[:kind] == :sequential && (tx_plan[:divisible] || !plan.divisible) \
+            ? tx_plan[:plans] \
+            : [tx_plan]
+        tx_plans.concat(new_plans)
+      end
+
+      return nil          if tx_plans.empty?
+      return tx_plans[0]  if tx_plans.length == 1
+      { kind: :sequential, divisible: plan.divisible, plans: tx_plans }
+    end
+
+    def planner_traverse_parallel(plan, ctx)
+      candidates = ctx[:parent_candidates].dup
+      tx_plans   = []
+
+      sorted = plan.plans.sort_by { |p| p.kind == :message_packer ? 1 : 0 }
+
+      sorted.each do |sub_plan|
+        sub_ctx = ctx.merge(parent: plan, parent_candidates: candidates)
+        tx_plan = planner_traverse(sub_plan, sub_ctx)
+        next unless tx_plan
+
+        candidates.concat(planner_get_parallel_candidates(tx_plan))
+        new_plans = tx_plan[:kind] == :parallel ? tx_plan[:plans] : [tx_plan]
+        tx_plans.concat(new_plans)
+      end
+
+      return nil          if tx_plans.empty?
+      return tx_plans[0]  if tx_plans.length == 1
+      { kind: :parallel, plans: tx_plans }
+    end
+
+    def planner_traverse_single(plan, ctx)
+      predicate = ->(msg) { TransactionMessages.append_instructions(msg, [plan.instruction]) }
+      candidate = planner_select_and_mutate_candidate(ctx, ctx[:parent_candidates], &predicate)
+      return nil if candidate
+
+      msg = planner_create_new_message(ctx, &predicate)
+      { kind: :single, message: msg }
+    end
+
+    def planner_traverse_message_packer(plan, ctx)
+      packer     = plan.get_message_packer.call
+      tx_plans   = []
+      candidates = ctx[:parent_candidates].dup
+
+      until packer.done?
+        predicate = ->(msg) { packer.pack_message_to_capacity(msg) }
+        candidate = planner_select_and_mutate_candidate(ctx, candidates, &predicate)
+        unless candidate
+          msg      = planner_create_new_message(ctx, &predicate)
+          new_plan = { kind: :single, message: msg }
+          tx_plans << new_plan
+          candidates << new_plan
+        end
+      end
+
+      return nil          if tx_plans.empty?
+      return tx_plans[0]  if tx_plans.length == 1
+
+      if ctx[:parent]&.kind == :parallel
+        { kind: :parallel, plans: tx_plans }
+      else
+        divisible = ctx[:parent]&.kind == :sequential ? ctx[:parent].divisible : true
+        { kind: :sequential, divisible: divisible, plans: tx_plans }
+      end
+    end
+
+    def planner_select_and_mutate_candidate(ctx, candidates, &predicate)
+      candidates.each do |candidate|
+        begin
+          updated = ctx[:on_transaction_message_updated].call(predicate.call(candidate[:message]))
+          if Transactions.get_transaction_message_size(updated) <= Transactions::TRANSACTION_SIZE_LIMIT
+            candidate[:message] = updated
+            return candidate
+          end
+        rescue SolanaError => e
+          next if e.code == SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN
+          Kernel.raise
+        end
+      end
+      nil
+    end
+
+    def planner_create_new_message(ctx, &predicate)
+      new_msg      = ctx[:create_transaction_message].call
+      updated_msg  = ctx[:on_transaction_message_updated].call(predicate.call(new_msg))
+      updated_size = Transactions.get_transaction_message_size(updated_msg)
+
+      if updated_size > Transactions::TRANSACTION_SIZE_LIMIT
+        new_size = Transactions.get_transaction_message_size(new_msg)
+        Kernel.raise SolanaError.new(
+          SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+          { num_bytes_required: updated_size - new_size,
+            num_free_bytes:     Transactions::TRANSACTION_SIZE_LIMIT - new_size }
+        )
+      end
+
+      updated_msg
+    end
+
+    def planner_fit_entire_plan(plan, message, ctx)
+      case plan.kind
+      when :sequential, :parallel
+        plan.plans.reduce(message) { |msg, sub| planner_fit_entire_plan(sub, msg, ctx) }
+      when :single
+        updated  = TransactionMessages.append_instructions(message, [plan.instruction])
+        new_size = Transactions.get_transaction_message_size(updated)
+        if new_size > Transactions::TRANSACTION_SIZE_LIMIT
+          base_size = Transactions.get_transaction_message_size(message)
+          Kernel.raise SolanaError.new(
+            SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+            { num_bytes_required: new_size - base_size,
+              num_free_bytes:     Transactions::TRANSACTION_SIZE_LIMIT - base_size }
+          )
+        end
+        updated
+      when :message_packer
+        packer = plan.get_message_packer.call
+        msg    = message
+        msg    = packer.pack_message_to_capacity(msg) until packer.done?
+        msg
+      else
+        Kernel.raise SolanaError.new(
+          SolanaError::INVARIANT_VIOLATION__INVALID_INSTRUCTION_PLAN_KIND,
+          { kind: plan.kind }
+        )
+      end
+    end
+
+    def planner_get_sequential_candidate(plan)
+      return plan if plan[:kind] == :single
+      return nil  unless plan[:kind] == :sequential && plan[:plans]&.any?
+      planner_get_sequential_candidate(plan[:plans].last)
+    end
+
+    def planner_get_parallel_candidates(plan)
+      return [plan] if plan[:kind] == :single
+      (plan[:plans] || []).flat_map { |p| planner_get_parallel_candidates(p) }
+    end
+
+    def planner_freeze(plan)
+      case plan[:kind]
+      when :single
+        single_transaction_plan(plan[:message])
+      when :sequential
+        frozen_plans = plan[:plans].map { |p| planner_freeze(p) }
+        plan[:divisible] \
+          ? sequential_transaction_plan(frozen_plans) \
+          : non_divisible_sequential_transaction_plan(frozen_plans)
+      when :parallel
+        parallel_transaction_plan(plan[:plans].map { |p| planner_freeze(p) })
+      else
+        Kernel.raise SolanaError.new(
+          SolanaError::INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND,
+          { kind: plan[:kind] }
+        )
+      end
+    end
+
+    private_class_method :planner_traverse
+    private_class_method :planner_traverse_sequential
+    private_class_method :planner_traverse_parallel
+    private_class_method :planner_traverse_single
+    private_class_method :planner_traverse_message_packer
+    private_class_method :planner_select_and_mutate_candidate
+    private_class_method :planner_create_new_message
+    private_class_method :planner_fit_entire_plan
+    private_class_method :planner_get_sequential_candidate
+    private_class_method :planner_get_parallel_candidates
+    private_class_method :planner_freeze
+  end
+end

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

@@ -3,45 +3,8 @@
 
 # Mirrors @solana/instruction-plans.
 # An InstructionPlan describes operations that may span multiple transactions.
-require_relative 'instruction_plans/plans'
-
-module Solana::Ruby::Kit
-  module InstructionPlans
-    extend T::Sig
-
-    module_function
-
-    # Build a plan that wraps a single instruction.
-    sig { params(instruction: Instructions::Instruction).returns(SingleInstructionPlan) }
-    def single_instruction_plan(instruction)
-      SingleInstructionPlan.new(instruction: instruction)
-    end
-
-    # Build a sequential plan from an array of sub-plans.
-    sig { params(steps: T::Array[T.untyped], divisible: T::Boolean).returns(SequentialInstructionPlan) }
-    def sequential_instruction_plan(steps, divisible: false)
-      SequentialInstructionPlan.new(steps: steps, divisible: divisible)
-    end
-
-    # Build a parallel plan from an array of sub-plans.
-    sig { params(plans: T::Array[T.untyped]).returns(ParallelInstructionPlan) }
-    def parallel_instruction_plan(plans)
-      ParallelInstructionPlan.new(plans: plans)
-    end
-
-    # Flatten a plan tree into a single ordered Array of Instructions.
-    sig { params(plan: T.untyped).returns(T::Array[Instructions::Instruction]) }
-    def flatten_instruction_plan(plan)
-      case plan
-      when SingleInstructionPlan
-        [plan.instruction]
-      when SequentialInstructionPlan
-        plan.steps.flat_map { |s| flatten_instruction_plan(s) }
-      when ParallelInstructionPlan
-        plan.plans.flat_map { |p| flatten_instruction_plan(p) }
-      else
-        Kernel.raise ArgumentError, "Unknown InstructionPlan type: #{plan.class}"
-      end
-    end
-  end
-end
+require_relative 'instruction_plans/instruction_plan'
+require_relative 'instruction_plans/transaction_plan'
+require_relative 'instruction_plans/transaction_plan_result'
+require_relative 'instruction_plans/transaction_planner'
+require_relative 'instruction_plans/transaction_plan_executor'

data/lib/solana/ruby/kit/transactions/compiler.rb

@@ -9,8 +9,19 @@ require_relative '../errors'
 
 module Solana::Ruby::Kit
   module Transactions
+    # Maximum wire-encoded transaction size in bytes (Solana protocol limit).
+    TRANSACTION_SIZE_LIMIT = T.let(1232, Integer)
+
     module_function
 
+    # Returns the compiled byte-size of a transaction message.
+    # Mirrors `getTransactionMessageSize()` from @solana/transactions.
+    # The message must have a fee payer and a blockhash lifetime set.
+    sig { params(message: TransactionMessages::TransactionMessage).returns(Integer) }
+    def get_transaction_message_size(message)
+      compile_transaction_message(message).message_bytes.bytesize
+    end
+
     # ---------------------------------------------------------------------------
     # compile_transaction_message
     # ---------------------------------------------------------------------------
@@ -40,10 +51,6 @@ module Solana::Ruby::Kit
       Kernel.raise SolanaError.new(:SOLANA_ERROR__TRANSACTION__FEE_PAYER_MISSING) if message.fee_payer.nil?
       fee_payer = T.must(message.fee_payer)
 
-      constraint = message.lifetime_constraint
-      Kernel.raise SolanaError.new(:SOLANA_ERROR__TRANSACTION__EXPECTED_BLOCKHASH_LIFETIME) unless constraint.is_a?(TransactionMessages::BlockhashLifetimeConstraint)
-      blockhash_str = constraint.blockhash
-
       # ── 1. Collect accounts and merge roles ────────────────────────────────
       # Insertion-ordered hash: address_str → merged AccountRole integer.
       account_roles = T.let({}, T::Hash[String, Integer])
@@ -115,7 +122,19 @@ module Solana::Ruby::Kit
       end
 
       # ── 6. Recent blockhash (32 bytes) ─────────────────────────────────────
-      blockhash_bytes = Addresses.decode_address(Addresses::Address.new(blockhash_str))
+      # Mirrors upstream compile-transaction.ts #581:
+      #   - BlockhashLifetime → use the blockhash bytes
+      #   - DurableNonceLifetime → use the nonce value bytes (stored in the same field)
+      #   - No lifetime → 32 zero bytes (placeholder; must be replaced before signing)
+      constraint = message.lifetime_constraint
+      blockhash_bytes =
+        if constraint.is_a?(TransactionMessages::BlockhashLifetimeConstraint)
+          Addresses.decode_address(Addresses::Address.new(constraint.blockhash))
+        elsif constraint.is_a?(TransactionMessages::DurableNonceLifetimeConstraint)
+          Addresses.decode_address(Addresses::Address.new(constraint.nonce))
+        else
+          ("\x00" * 32).b
+        end
 
       # ── 7. Instructions section ────────────────────────────────────────────
       ixs_section = encode_compact_u16(message.instructions.size)

data/lib/solana/ruby/kit/transactions/transaction.rb

@@ -67,6 +67,42 @@ module Solana::Ruby::Kit
       )
     end
 
+    # Returns true if the wire-encoded transaction fits within TRANSACTION_SIZE_LIMIT.
+    # Mirrors `isTransactionWithinSizeLimit(transaction)`.
+    sig { params(transaction: Transaction).returns(T::Boolean) }
+    def within_size_limit?(transaction)
+      wire_encode_transaction(transaction).bytesize <= TRANSACTION_SIZE_LIMIT
+    end
+
+    # Raises SolanaError if the wire-encoded transaction exceeds TRANSACTION_SIZE_LIMIT.
+    # Mirrors `assertIsTransactionWithinSizeLimit(transaction)`.
+    sig { params(transaction: Transaction).void }
+    def assert_within_size_limit!(transaction)
+      actual = wire_encode_transaction(transaction).bytesize
+      return if actual <= TRANSACTION_SIZE_LIMIT
+
+      Kernel.raise SolanaError.new(
+        SolanaError::TRANSACTIONS__EXCEEDS_SIZE_LIMIT,
+        { actual_size: actual, limit: TRANSACTION_SIZE_LIMIT }
+      )
+    end
+
+    # Returns true if the transaction is both fully signed and within the size limit.
+    # Mirrors `isSendableTransaction(transaction)`.
+    # sendableTransaction = FullySignedTransaction & TransactionWithinSizeLimit
+    sig { params(transaction: Transaction).returns(T::Boolean) }
+    def sendable_transaction?(transaction)
+      fully_signed_transaction?(transaction) && within_size_limit?(transaction)
+    end
+
+    # Raises SolanaError unless the transaction is fully signed and within size limit.
+    # Mirrors `assertIsSendableTransaction(transaction)`.
+    sig { params(transaction: Transaction).void }
+    def assert_sendable_transaction!(transaction)
+      assert_fully_signed_transaction!(transaction)
+      assert_within_size_limit!(transaction)
+    end
+
     # Signs a transaction with one or more RbNaCl::SigningKey objects.
     # Only keys whose address appears in `transaction.signatures` are applied.
     # Raises SolanaError if a key is not expected to sign this transaction.

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

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '0.1.4'
+      VERSION = '0.1.5'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -208,7 +208,12 @@ files:
 - lib/solana/ruby/kit/fast_stable_stringify.rb
 - lib/solana/ruby/kit/functional.rb
 - lib/solana/ruby/kit/instruction_plans.rb
+- lib/solana/ruby/kit/instruction_plans/instruction_plan.rb
 - lib/solana/ruby/kit/instruction_plans/plans.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_plan.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_plan_executor.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_plan_result.rb
+- lib/solana/ruby/kit/instruction_plans/transaction_planner.rb
 - lib/solana/ruby/kit/instructions.rb
 - lib/solana/ruby/kit/instructions/accounts.rb
 - lib/solana/ruby/kit/instructions/instruction.rb