solana-ruby-kit 8.2.0 → 8.4.0

data/lib/solana/ruby/kit/codecs/strings.rb

@@ -15,14 +15,134 @@ module Solana::Ruby::Kit
       # defeated the "directly available as Codecs.x" intent in codecs.rb.
       extend self
 
+      # Byte order mark, U+FEFF, in its UTF-8 encoding.
+      BOM = T.let("\xEF\xBB\xBF".b.freeze, String)
+
+      # Remove every null character from a decoded string.
+      # Mirrors `removeNullCharacters`.
+      sig { params(value: String).returns(String) }
+      def remove_null_characters(value)
+        value.delete("\x00")
+      end
+
+      # Find the first malformed UTF-8 sequence in +bytes+, starting at +offset+.
+      # Returns the byte offset at which it starts, or -1 when the bytes are
+      # well-formed.
+      #
+      # This rejects everything the Unicode standard rejects: unexpected
+      # continuation bytes, overlong encodings, encoded surrogates, code points
+      # above U+10FFFF and truncated sequences. Ruby's own +valid_encoding?+
+      # answers the same question, but only yes or no - this reports *where*,
+      # which is what the error context needs.
+      # Mirrors `findMalformedUtf8SequenceOffset`.
+      sig { params(bytes: String, offset: Integer).returns(Integer) }
+      def find_malformed_utf8_sequence_offset(bytes, offset = 0)
+        arr    = T.cast(T.unsafe(bytes.b).unpack('C*'), T::Array[Integer])
+        length = arr.length
+        index  = offset
+        while index < length
+          lead = T.must(arr[index])
+          min  = 0x80
+          max  = 0xBF
+          if lead < 0x80
+            index += 1
+            next
+          elsif lead >= 0xC2 && lead <= 0xDF
+            count = 1
+          elsif lead >= 0xE0 && lead <= 0xEF
+            count = 2
+            min = 0xA0 if lead == 0xE0 # Overlong.
+            max = 0x9F if lead == 0xED # Encoded surrogate.
+          elsif lead >= 0xF0 && lead <= 0xF4
+            count = 3
+            min = 0x90 if lead == 0xF0 # Overlong.
+            max = 0x8F if lead == 0xF4 # Above U+10FFFF.
+          else
+            return index
+          end
+
+          start  = index
+          index += 1
+          count.times do |i|
+            return start if index >= length
+
+            byte     = T.must(arr[index])
+            in_range = i.zero? ? byte >= min && byte <= max : byte >= 0x80 && byte <= 0xBF
+            return start unless in_range
+
+            index += 1
+          end
+        end
+        -1
+      end
+
+      # Raise unless +bytes+, from +offset+, form well-formed UTF-8.
+      # Mirrors `assertIsWellFormedUtf8Bytes`.
+      sig { params(bytes: String, offset: Integer).void }
+      def assert_is_well_formed_utf8_bytes(bytes, offset = 0)
+        malformed = find_malformed_utf8_sequence_offset(bytes, offset)
+        return if malformed == -1
+
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__INVALID_UTF8_BYTES,
+          { bytes: bytes.b, offset: malformed }
+        )
+      end
+
+      # Raise unless +value+ can be encoded as UTF-8 without loss.
+      # Mirrors `assertIsWellFormedUtf8String`.
+      #
+      # Upstream guards against lone surrogates, which a JavaScript string can
+      # hold because it is a sequence of UTF-16 code units. A Ruby String is a
+      # byte sequence with an encoding tag, so the equivalent flaw is a String
+      # whose bytes are not valid UTF-8. Upstream's reported +index+ counts
+      # UTF-16 code units; the +index+ here is a byte offset.
+      sig { params(value: String).void }
+      def assert_is_well_formed_utf8_string(value)
+        index = find_malformed_utf8_sequence_offset(value.b)
+        return if index == -1
+
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__INVALID_UTF8_STRING,
+          { index: index, value: value }
+        )
+      end
+
       # UTF-8 string codec.
       # When +size+ is given the encoded bytes are fixed to that length
       # (zero-padded or truncated); otherwise the codec is variable-length
       # and must be used inside a size-prefixed container.
-      sig { params(size: T.nilable(Integer)).returns(Codec) }
-      def utf8_codec(size: nil)
+      #
+      # +fatal+ rejects invalid UTF-8 instead of passing it through: on encode a
+      # String whose bytes are not valid UTF-8, on decode a malformed byte
+      # sequence.
+      #
+      # +ignore_bom+ follows TextDecoder's confusing spelling: the default,
+      # +false+, *strips* a leading byte order mark; +true+ keeps it.
+      #
+      # +remove_null_characters+ strips every null character from the decoded
+      # string, which is what makes fixed-size padded strings read back cleanly.
+      # It is on by default, matching upstream, and makes the codec lossy for
+      # strings that legitimately contain nulls - pass +false+ for a lossless
+      # round trip.
+      sig do
+        params(
+          size:                   T.nilable(Integer),
+          fatal:                  T::Boolean,
+          ignore_bom:             T::Boolean,
+          remove_null_characters: T::Boolean
+        ).returns(Codec)
+      end
+      def utf8_codec(size: nil, fatal: false, ignore_bom: false, remove_null_characters: true)
+        strip_nulls = remove_null_characters
         enc = Encoder.new(fixed_size: size) do |v|
-          raw = v.to_s.encode('UTF-8').b
+          str = v.to_s
+          # Transcode anything that is not already UTF-8 (or raw bytes); a
+          # UTF-8 to UTF-8 `encode` is a no-op and would not validate, which is
+          # what `fatal` is for.
+          str = str.encode(::Encoding::UTF_8) unless [::Encoding::UTF_8, ::Encoding::BINARY].include?(str.encoding)
+          raw = str.b
+          assert_is_well_formed_utf8_string(raw) if fatal
           if size
             raw.bytesize <= size ? raw.ljust(size, "\x00") : raw.byteslice(0, size) || ''.b
           else
@@ -32,9 +152,15 @@ module Solana::Ruby::Kit
         dec = Decoder.new(fixed_size: size) do |bytes, offset|
           len   = size || (bytes.bytesize - offset)
           slice = bytes.b.byteslice(offset, len) || ''.b
-          # Strip null padding for fixed-size strings
-          str   = size ? slice.delete_suffix("\x00" * slice.bytesize.times.take_while { |i| slice.b[-1 - i] == "\x00" }.length) : slice
-          [str.force_encoding('UTF-8'), len]
+          assert_is_well_formed_utf8_bytes(slice) if fatal
+          slice = T.must(slice.byteslice(BOM.bytesize..)) if !ignore_bom && slice.start_with?(BOM)
+          str   = slice.force_encoding(::Encoding::UTF_8)
+          # Non-fatal decoding substitutes U+FFFD for malformed sequences, as
+          # TextDecoder does. `scrub` is Ruby's version of exactly that, and it
+          # also keeps the null-stripping below from raising on invalid bytes.
+          str   = str.scrub unless fatal
+          str   = remove_null_characters(str) if strip_nulls
+          [str, len]
         end
         Codec.new(enc, dec)
       end

data/lib/solana/ruby/kit/encoding/base58.rb

@@ -13,7 +13,7 @@ module Solana::Ruby::Kit
         String
       )
 
-      module_function
+      extend self
 
       # Encodes a binary String to a base58 string.
       sig { params(bytes: String).returns(String) }

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

@@ -95,6 +95,15 @@ module Solana::Ruby::Kit
     CODECS__INVALID_BYTE_LENGTH                          = :SOLANA_ERROR__CODECS__INVALID_BYTE_LENGTH
     CODECS__EXPECTED_ZERO_VALUE_TO_MATCH_ITEM_FIXED_DISCRIMINATOR = :SOLANA_ERROR__CODECS__EXPECTED_ZERO_VALUE_TO_MATCH_ITEM_FIXED_DISCRIMINATOR
     CODECS__FIXED_NULLABLE_CANNOT_WRAP_VARIABLE_SIZE_CODEC = :SOLANA_ERROR__CODECS__FIXED_NULLABLE_CANNOT_WRAP_VARIABLE_SIZE_CODEC
+    # context: { bytes:, offset: }
+    CODECS__INVALID_UTF8_BYTES                           = :SOLANA_ERROR__CODECS__INVALID_UTF8_BYTES
+    # context: { index:, value: }
+    CODECS__INVALID_UTF8_STRING                          = :SOLANA_ERROR__CODECS__INVALID_UTF8_STRING
+    # context: { codec_description:, min:, max:, value: }
+    CODECS__NUMBER_OUT_OF_RANGE                          = :SOLANA_ERROR__CODECS__NUMBER_OUT_OF_RANGE
+    # context: { codec_description:, hex_sentinel:, sentinel: }
+    CODECS__SENTINEL_MISSING_AT_END_OF_BYTES             = :SOLANA_ERROR__CODECS__SENTINEL_MISSING_AT_END_OF_BYTES
+    CODECS__SENTINEL_MUST_NOT_BE_EMPTY                   = :SOLANA_ERROR__CODECS__SENTINEL_MUST_NOT_BE_EMPTY
 
     # ── RPC / JSON-RPC ────────────────────────────────────────────────────────
     RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER = :SOLANA_ERROR__RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER
@@ -134,6 +143,8 @@ module Solana::Ruby::Kit
     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
+    # context: { reason: }
+    INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER            = :SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER
 
     # ── Transaction introspection ────────────────────────────────────────────
     TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION
@@ -233,7 +244,7 @@ module Solana::Ruby::Kit
         CODECS__EXPECTED_POSITIVE_BYTE_LENGTH            => 'Expected a positive byte length, got %{byte_length}',
         CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH      => 'Encoder fixed size (%{encoder_size}) does not match decoder fixed size (%{decoder_size})',
         CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH        => 'Encoder max size (%{encoder_max}) does not match decoder max size (%{decoder_max})',
-        CODECS__INVALID_NUMBER_OF_ITEMS                  => 'Expected %{expected} items but got %{actual}',
+        CODECS__INVALID_NUMBER_OF_ITEMS                  => 'Expected [%{codec_description}] to have %{expected} items, got %{actual}.',
         CODECS__ENUM_DISCRIMINATOR_OUT_OF_RANGE          => 'Enum discriminator %{discriminator} is out of range [0, %{max}]',
         CODECS__UNION_VARIANT_OUT_OF_RANGE               => 'Union variant index %{index} is out of range',
         CODECS__OFFSET_OUT_OF_RANGE                      => 'Codec offset %{offset} is out of range for byte array of length %{byte_length}',
@@ -244,6 +255,11 @@ module Solana::Ruby::Kit
         CODECS__INVALID_BYTE_LENGTH                      => 'Expected %{expected} bytes but got %{actual}',
         CODECS__EXPECTED_ZERO_VALUE_TO_MATCH_ITEM_FIXED_DISCRIMINATOR => 'Expected zero value to match fixed discriminator',
         CODECS__FIXED_NULLABLE_CANNOT_WRAP_VARIABLE_SIZE_CODEC => 'A fixed-size nullable codec cannot wrap a variable-size codec',
+        CODECS__INVALID_UTF8_BYTES                       => 'Invalid UTF-8 byte sequence at offset %{offset}',
+        CODECS__INVALID_UTF8_STRING                      => 'Invalid UTF-8 string at index %{index}',
+        CODECS__NUMBER_OUT_OF_RANGE                      => 'Codec [%{codec_description}] expected number to be in the range [%{min}, %{max}], got %{value}.',
+        CODECS__SENTINEL_MISSING_AT_END_OF_BYTES         => 'Codec [%{codec_description}] expected sentinel [%{hex_sentinel}] to terminate the collection, but reached the end of the byte array without it.',
+        CODECS__SENTINEL_MUST_NOT_BE_EMPTY               => 'The sentinel must not be empty.',
 
         # RPC
         RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER   => 'Integer overflow while serializing large integer %{value}',
@@ -281,6 +297,7 @@ module Solana::Ruby::Kit
         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.',
+        INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER         => 'The message packer rejected the provided transaction message: %{reason}.',
 
         # 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.",

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

@@ -8,7 +8,7 @@ module Solana::Ruby::Kit
   module FastStableStringify
     extend T::Sig
 
-    module_function
+    extend self
 
     # Serialize +value+ to a deterministic JSON string.
     # Hash keys are sorted lexicographically at every level.

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

@@ -6,7 +6,7 @@ module Solana::Ruby::Kit
   # Mirrors the TypeScript package @solana/functional.
   module Functional
     extend T::Sig
-    module_function
+    extend self
 
     # Passes an initial value through a series of single-argument callables,
     # returning the final result.

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

@@ -5,7 +5,7 @@ require_relative '../errors'
 require_relative '../instructions/instruction'
 require_relative '../transaction_messages/transaction_message'
 require_relative '../transactions/compiler'
-require_relative 'max_instructions'
+require_relative 'message_packer_errors'
 
 module Solana::Ruby::Kit
   module InstructionPlans
@@ -84,6 +84,14 @@ module Solana::Ruby::Kit
       #
       # +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).
+      #
+      # A custom packer can enforce those limits with
+      # InstructionPlans.resolve_max_instructions_per_transaction,
+      # .assert_max_instructions_per_transaction and .assert_message_can_accommodate_size,
+      # and may raise INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER (with a +reason:+) to
+      # refuse a message for any other reason - e.g. a constraint specific to the
+      # instructions being packed. The planner then tries another message; see
+      # InstructionPlans.message_packer_error_that_requires_new_candidate?.
       sig do
         params(
           message:          TransactionMessages::TransactionMessage,
@@ -97,7 +105,7 @@ module Solana::Ruby::Kit
 
     # ── Factory helpers ────────────────────────────────────────────────────────
 
-    module_function
+    extend self
 
     # Wraps a single instruction in a plan.
     # Mirrors `singleInstructionPlan(instruction)`.
@@ -148,8 +156,7 @@ module Solana::Ruby::Kit
                 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)
+              resolved_max = InstructionPlans.resolve_max_instructions_per_transaction(max_instructions)
               InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, resolved_max)
 
               base_ix    = get_instruction.call(offset, 0)
@@ -194,8 +201,7 @@ module Solana::Ruby::Kit
                 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)
+              resolved_max = InstructionPlans.resolve_max_instructions_per_transaction(max_instructions)
               InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, resolved_max)
 
               original_size = Transactions.get_transaction_message_size(message)
@@ -212,18 +218,16 @@ module Solana::Ruby::Kit
                 end
 
                 next_packed = TransactionMessages.append_instructions(packed, [T.must(instructions[i])])
-                size        = Transactions.get_transaction_message_size(next_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
+                next_size   = Transactions.get_transaction_message_size(next_packed)
+                size_limit  = Transactions::TRANSACTION_SIZE_LIMIT
+
+                if i == start_idx
+                  # The count was already asserted above, so the first instruction can
+                  # only fail to fit because of the transaction size limit.
+                  InstructionPlans.assert_message_can_accommodate_size(
+                    current_size: original_size, next_size: next_size, size_limit: size_limit
+                  )
+                elsif next_size > size_limit
                   idx = i
                   return packed
                 end
@@ -240,7 +244,9 @@ module Solana::Ruby::Kit
     end
 
     # Creates a MessagePackerInstructionPlan that splits +total_size+ bytes into
-    # chunks of REALLOC_LIMIT (10,240) bytes, calling +get_instruction.(size)+.
+    # chunks of at most REALLOC_LIMIT (10,240) bytes and creates one instruction
+    # per chunk, calling +get_instruction.(size)+. A +total_size+ that is an exact
+    # multiple of the limit yields only full-sized chunks, and zero yields none.
     # Mirrors `getReallocMessagePackerInstructionPlan({ getInstruction, totalSize })`.
     sig do
       params(
@@ -249,13 +255,12 @@ module Solana::Ruby::Kit
       ).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)
+      realloc_limit = 10_240
+      instructions  = []
+      remaining     = total_size
+      while remaining.positive?
+        instructions << get_instruction.call([realloc_limit, remaining].min)
+        remaining -= realloc_limit
       end
 
       get_message_packer_instruction_plan_from_instructions(instructions)

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

@@ -0,0 +1,131 @@
+# 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)
+
+    # The error codes the transaction planner treats as "try another message": the message
+    # holds too many instructions, would be too large, or a message packer refused it for a
+    # custom reason. Upstream's list also has four `TRANSACTION__TOO_MANY_*` compile errors;
+    # Ruby's compiler raises none of them, so they are not listed.
+    MESSAGE_PACKER_ERRORS_THAT_REQUIRE_NEW_CANDIDATE = T.let(
+      [
+        SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED,
+        SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+        SolanaError::INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER
+      ].freeze,
+      T::Array[Symbol]
+    )
+
+    extend self
+
+    # Resolves the maximum number of instructions a message packer may put in a transaction
+    # message: the default of 16 when +max_instructions+ is nil, otherwise the given value,
+    # which must be a positive integer no greater than TRANSACTION_INSTRUCTION_LIMIT.
+    #
+    # This is typically the first thing a custom MessagePacker does with the
+    # +max_instructions+ it receives in +pack_message_to_capacity+:
+    #
+    #   pack_proc: ->(message, max_instructions) {
+    #     max = InstructionPlans.resolve_max_instructions_per_transaction(max_instructions)
+    #     InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, max)
+    #     # ...
+    #   }
+    #
+    # Raises INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION for an out-of-range value.
+    # Mirrors `resolveMaxInstructionsPerTransaction(maxInstructions)`.
+    sig { params(max_instructions: T.nilable(Integer)).returns(Integer) }
+    def resolve_max_instructions_per_transaction(max_instructions = nil)
+      return DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION 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
+
+      max_instructions
+    end
+
+    # Raises if a message holding +num_instructions+ instructions would exceed
+    # +max_instructions+. Use it in a custom MessagePacker before appending an instruction -
+    # passing the count the message would have after the append - so the planner knows to
+    # pack that instruction into another message.
+    #
+    # Raises INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED.
+    # 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
+
+    # Raises if a message cannot grow from +current_size+ to +next_size+ bytes without
+    # exceeding +size_limit+. Use it in a custom MessagePacker after appending the next
+    # instruction(s), so the planner knows to pack them into another message. It takes sizes
+    # rather than messages so callers who already computed them do not pay for it twice:
+    #
+    #   next_message = TransactionMessages.append_instructions(message, [ix])
+    #   InstructionPlans.assert_message_can_accommodate_size(
+    #     current_size: Transactions.get_transaction_message_size(message),
+    #     next_size:    Transactions.get_transaction_message_size(next_message),
+    #     size_limit:   Transactions::TRANSACTION_SIZE_LIMIT
+    #   )
+    #
+    # Raises INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN, reporting how many bytes
+    # were required and how many were free.
+    # Mirrors `assertMessageCanAccommodateSize({ currentSize, nextSize, sizeLimit })`.
+    sig { params(current_size: Integer, next_size: Integer, size_limit: Integer).void }
+    def assert_message_can_accommodate_size(current_size:, next_size:, size_limit:)
+      return if next_size <= size_limit
+
+      Kernel.raise SolanaError.new(
+        SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+        { num_bytes_required: next_size - current_size, num_free_bytes: size_limit - current_size }
+      )
+    end
+
+    # Whether +error+, raised while packing instructions into a message, means the message
+    # cannot take them and a new candidate message is required (see
+    # MESSAGE_PACKER_ERRORS_THAT_REQUIRE_NEW_CANDIDATE). Any other error is unexpected and
+    # should propagate:
+    #
+    #   begin
+    #     message = packer.pack_message_to_capacity(message)
+    #   rescue => e
+    #     raise unless InstructionPlans.message_packer_error_that_requires_new_candidate?(e)
+    #     message = packer.pack_message_to_capacity(create_new_message)
+    #   end
+    #
+    # A custom packer refuses a message for any other reason by raising
+    # INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER with a +reason:+.
+    # Mirrors `isMessagePackerErrorThatRequiresNewCandidate(error)`.
+    sig { params(error: T.anything).returns(T::Boolean) }
+    def message_packer_error_that_requires_new_candidate?(error)
+      case error
+      when SolanaError then MESSAGE_PACKER_ERRORS_THAT_REQUIRE_NEW_CANDIDATE.include?(error.code)
+      else false
+      end
+    end
+  end
+end

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

@@ -41,7 +41,7 @@ module Solana::Ruby::Kit
       def kind = :parallel
     end
 
-    module_function
+    extend self
 
     # Creates a single-message plan.
     # Mirrors `singleTransactionPlan(transactionMessage)`.

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

@@ -9,7 +9,7 @@ module Solana::Ruby::Kit
   module InstructionPlans
     extend T::Sig
 
-    module_function
+    extend self
 
     # Creates a TransactionPlanExecutor — a callable that traverses a TransactionPlan,
     # executing each single transaction message and collecting results.
@@ -111,7 +111,7 @@ module Solana::Ruby::Kit
 
     # ── Private helpers ────────────────────────────────────────────────────────
 
-    module_function
+    extend self
 
     sig { params(plan: T.untyped, execute_fn: T.untyped, state: T.untyped).returns(T.untyped) }
 

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

@@ -74,7 +74,7 @@ module Solana::Ruby::Kit
       def kind = :parallel
     end
 
-    module_function
+    extend self
 
     # ── Result factory helpers ────────────────────────────────────────────────
 

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

@@ -11,7 +11,7 @@ module Solana::Ruby::Kit
   module InstructionPlans
     extend T::Sig
 
-    module_function
+    extend self
 
     # Creates a TransactionPlanner — a callable that converts an InstructionPlan
     # into a TransactionPlan by packing instructions into transaction messages.
@@ -54,11 +54,11 @@ module Solana::Ruby::Kit
       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)
+        resolved_max = InstructionPlans.resolve_max_instructions_per_transaction(
+          max_instructions_per_transaction || config_max_instructions_per_transaction
+        )
 
         mutable = planner_traverse(
           instruction_plan,
@@ -71,7 +71,7 @@ module Solana::Ruby::Kit
 
     # ── Private helpers ────────────────────────────────────────────────────────
 
-    module_function
+    extend self
 
     sig { params(plan: T.untyped, ctx: T.untyped).returns(T.untyped) }
 
@@ -194,17 +194,14 @@ module Solana::Ruby::Kit
           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])
+              ctx[:max_instructions_per_transaction]
             )
             candidate[:message] = updated
             return candidate
           end
         rescue SolanaError => e
-          next if [
-            SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
-            SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED
-          ].include?(e.code)
-          Kernel.raise
+          Kernel.raise unless InstructionPlans.message_packer_error_that_requires_new_candidate?(e)
+          # Try the next candidate.
         end
       end
       nil
@@ -228,7 +225,7 @@ module Solana::Ruby::Kit
 
       InstructionPlans.assert_max_instructions_per_transaction(
         updated_msg.instructions.length,
-        InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+        ctx[:max_instructions_per_transaction]
       )
 
       updated_msg
@@ -253,7 +250,7 @@ module Solana::Ruby::Kit
         end
         InstructionPlans.assert_max_instructions_per_transaction(
           updated.instructions.length,
-          InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+          ctx[:max_instructions_per_transaction]
         )
         updated
       when :message_packer
@@ -263,7 +260,7 @@ module Solana::Ruby::Kit
           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])
+            ctx[:max_instructions_per_transaction]
           )
         end
         msg

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

@@ -3,7 +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/message_packer_errors'
 require_relative 'instruction_plans/instruction_plan'
 require_relative 'instruction_plans/transaction_plan'
 require_relative 'instruction_plans/transaction_plan_result'

data/lib/solana/ruby/kit/instructions/accounts.rb

@@ -19,7 +19,7 @@ module Solana::Ruby::Kit
 
     # AccountMeta subtypes — mirrors the four TypeScript convenience types.
 
-    module_function
+    extend self
 
     # Creates a read-only account reference.
     sig { params(address: Addresses::Address).returns(AccountMeta) }

data/lib/solana/ruby/kit/instructions/instruction.rb

@@ -18,7 +18,7 @@ module Solana::Ruby::Kit
       const :data,            T.nilable(String)  # binary String (Uint8Array equivalent)
     end
 
-    module_function
+    extend self
 
     # Returns true if the instruction targets the given program address.
     # Mirrors `isInstructionForProgram()`.

data/lib/solana/ruby/kit/instructions/roles.rb

@@ -19,7 +19,7 @@ module Solana::Ruby::Kit
 
       ALL = T.let([READONLY, WRITABLE, READONLY_SIGNER, WRITABLE_SIGNER].freeze, T::Array[Integer])
 
-      module_function
+      extend self
 
       # Returns true if the role requires the account to sign the transaction.
       sig { params(role: Integer).returns(T::Boolean) }

data/lib/solana/ruby/kit/keys/key_pair.rb

@@ -24,7 +24,7 @@ module Solana::Ruby::Kit
       const :verify_key,  T.untyped  # RbNaCl::VerifyKey
     end
 
-    module_function
+    extend self
 
     # Generates a fresh Ed25519 key pair using a cryptographically secure RNG.
     # Mirrors `generateKeyPair()` in TypeScript.