solana-ruby-kit 8.3.0 → 8.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c281fe52274deb9bbf493d3848b3bcb64ecc42b11e4acc6b727ef5e301dcb252
-  data.tar.gz: 6fefa37ee1da4bc377bc58f609adad46c2940b3377a9333168df0f6ff83cef6c
+  metadata.gz: 3067fc0036448f0aef241f14f4e0b95f0faf6d6cedd4ed8aae5206d6e3169e28
+  data.tar.gz: a689c349c2e41d519b6e06814319d9760b2816bf59f48109d8d839790c4e6312
 SHA512:
-  metadata.gz: ba02f18c40de9b8b9ab544551ac477e94b1f4dcd4b177e8d513680b3d406830991acb770f4f427b5e9d4ca4abaf0cdda28d5849d649e6e50037104fe653390a7
-  data.tar.gz: 5ccc70a501ac546deb6520394b9efedc8ddbd7b2278318ab0fdf3944352e9a66ac06d66bd8b8288b1bf4b10a9cb395266d23f3feec3d7708741421a83033af9d
+  metadata.gz: a02f7ce5743af32d1d6401f2023fc7293e33abfe1c0f495ec91f00a7ca4399e6fd654c7baa3f3c966ed34d6495514607432315323fb3425f294e8bf1713035ae
+  data.tar.gz: bfd06cf91f1fc1652cb5a578b822595c5f976537561fddbad22e04e6dc5567f1284b211b4e41be6472426005f3f4b0197c486fe5d87a046e2dac8989e30acb61

data/README.md

@@ -133,6 +133,9 @@ kp = Keys.create_key_pair_from_private_key_bytes(seed_bytes)
 # Sign / verify
 sig = Keys.sign_bytes(kp.signing_key, data)
 ok  = Keys.verify_signature(kp.verify_key, sig, data)
+# verify_signature is strict: a small-order public key or signature R
+# component returns false (as the Solana runtime does), and passing anything
+# other than an RbNaCl::VerifyKey raises KEYS__VERIFICATION_REQUIRES_EXTRACTABLE_PUBLIC_KEY.
 
 # Base58-encode a signature
 Keys.encode_signature(sig)   # => Signature string
@@ -379,12 +382,17 @@ u16.decode("\xe8\x03")   # => [1000, 2]   # [value, bytes consumed]
 # Strings
 utf8  = Codecs.utf8_codec
 bytes = Codecs.bytes_codec(32)
+# A borsh-style string: a u32 byte length, then that many UTF-8 bytes.
+name  = Codecs.add_codec_size_prefix(utf8, u32)
 
 # Data structures
 struct_codec = Codecs.struct_codec([
   ['amount', u64],
+  ['name',   name],
   ['mint',   bytes]
 ])
+struct_codec.decode(struct_codec.encode({ amount: 5, name: 'gold', mint: "\x01".b * 32 }))
+# => [{ amount: 5, name: "gold", mint: "\x01\x01..." }, 48]
 ```
 
 #### UTF-8 options
@@ -412,6 +420,25 @@ Codecs.remove_null_characters("a\x00b")                        # => "ab"
 Note that `ignore_bom` follows `TextDecoder`'s confusing spelling: the default,
 `false`, *strips* the mark; `true` keeps it.
 
+#### Collection sizes
+
+`array_codec`, `map_codec` and `set_codec` take a `size:` that sets how the item
+count is stored:
+
+```ruby
+Codecs.array_codec(u8).encode([1, 2, 3])                          # => "\x03\x00\x00\x00\x01\x02\x03" (u32 count)
+Codecs.array_codec(u8, size: u8).encode([1, 2, 3])                # => "\x03\x01\x02\x03" (any number codec as the count)
+Codecs.array_codec(u8, size: Codecs.compact_u16_codec).encode([1]) # => "\x01\x01" (Solana's shortU16)
+Codecs.array_codec(u8, size: 3).encode([1, 2, 3])                 # => "\x01\x02\x03" (fixed count, no prefix)
+Codecs.array_codec(u8, size: 3).encode([1, 2])                    # raises SolanaError (wrong number of items)
+Codecs.array_codec(u8, size: :remainder).encode([1, 2, 3])        # => "\x01\x02\x03" (no prefix...)
+Codecs.array_codec(u8, size: :remainder).decode("\x01\x02\x03".b)  # => [[1, 2, 3], 3] (...reads to the end)
+```
+
+A `:remainder` array must be the last thing in the buffer. Upstream spells it
+`'remainder'`; Ruby uses the Symbol. The fifth option, a `Codecs::SentinelSize`,
+is described below.
+
 #### Requiring a size prefix
 
 A prefixed collection decodes an exhausted buffer to an empty collection rather
@@ -424,8 +451,39 @@ Codecs.array_codec(u8).decode(''.b)                              # => [[], 0]
 Codecs.array_codec(u8, require_size_prefix: true).decode(''.b)   # raises SolanaError
 ```
 
-`map_codec` and `set_codec` take the same option. It has no effect on
-fixed-count collections, which carry no prefix.
+`map_codec` and `set_codec` take the same option, and it applies to a custom
+count codec too. It has no effect on fixed-count, `:remainder` or
+sentinel-terminated collections, none of which carries a prefix.
+
+#### Sentinel-terminated collections
+
+Instead of a length prefix, `size:` can be a `Codecs::SentinelSize`: the
+collection ends where the bytes at the next item position match the sentinel.
+It is compared at item boundaries only, so its bytes may appear *inside* an item.
+
+```ruby
+zero = Codecs::SentinelSize.new(sentinel: "\x00".b)
+list = Codecs.array_codec(u8, size: zero)
+list.encode([1, 2, 3])            # => "\x01\x02\x03\x00"
+list.decode("\x01\x02\x03\x00".b)  # => [[1, 2, 3], 4]
+list.decode("\x01\x02".b)          # raises SolanaError (sentinel missing)
+
+# :optional still writes the sentinel but tolerates its absence on decode;
+# :omitted never writes it. Both stop at the end of the bytes.
+lenient = Codecs.array_codec(u8, size: Codecs::SentinelSize.new(sentinel: "\x00".b, strategy: :optional))
+lenient.decode("\x01\x02".b)       # => [[1, 2], 2]
+```
+
+`map_codec` and `set_codec` accept the same `size:`. The codec does **not**
+check two invariants, so it is up to you to make sure they hold. First, no item
+may *begin* with the sentinel's bytes, or decoding stops early at that item.
+Second, under `:optional` / `:omitted` the sentinel must be no wider than the
+smallest item, or a short trailing item is silently dropped.
+
+An item codec with a fixed size of zero (e.g. `struct_codec([])`) can never
+reach a sentinel or the end of the bytes, so pairing one with a `SentinelSize`
+or `:remainder` raises `CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY`
+when the codec is built. Explicit counts and prefixes still allow it.
 
 #### Tap combinators
 
@@ -745,6 +803,38 @@ Plans.get_linear_message_packer_instruction_plan(
   total_length:    data.bytesize,
   get_instruction: ->(offset, length) { build_write_ix(offset, data[offset, length]) }
 )
+
+# ── 5. Custom message packers ────────────────────────────────────────────────
+# A custom packer enforces the same limits the built-in ones do, and can refuse a
+# message for a reason of its own with MESSAGE_REJECTED_BY_PACKER. The planner
+# treats all three errors as "try another message"
+# (Plans.message_packer_error_that_requires_new_candidate?).
+one_per_message = Plans::MessagePackerInstructionPlan.new(
+  get_message_packer: -> {
+    remaining = [ix1, ix2]
+    Plans::MessagePacker.new(
+      done_proc: -> { remaining.empty? },
+      pack_proc: ->(message, max_instructions) {
+        max = Plans.resolve_max_instructions_per_transaction(max_instructions)
+        Plans.assert_max_instructions_per_transaction(message.instructions.length + 1, max)
+        unless message.instructions.empty?
+          raise Kit::SolanaError.new(
+            Kit::SolanaError::INSTRUCTION_PLANS__MESSAGE_REJECTED_BY_PACKER,
+            { reason: 'these instructions must each have a transaction to themselves' }
+          )
+        end
+        next_message = Kit::TransactionMessages.append_instructions(message, [remaining.first])
+        Plans.assert_message_can_accommodate_size(
+          current_size: Kit::Transactions.get_transaction_message_size(message),
+          next_size:    Kit::Transactions.get_transaction_message_size(next_message),
+          size_limit:   Kit::Transactions::TRANSACTION_SIZE_LIMIT
+        )
+        remaining.shift
+        next_message
+      }
+    )
+  }
+)
 ```
 
 ### `Solana::Ruby::Kit::WalletStandard` — `@solana/wallet-standard`

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

@@ -88,17 +88,33 @@ module Solana::Ruby::Kit
 
     # Prefix encoded data with its byte length using +prefix_codec+
     # (typically a u32 little-endian codec).
+    #
+    # On decode the inner codec sees exactly the prefixed number of bytes, as
+    # upstream's `addDecoderSizePrefix` does - so a variable-size inner codec
+    # such as +utf8_codec+ stops at its own end instead of reading the rest of
+    # the buffer. Fewer bytes than the prefix promises raise
+    # +CODECS__INVALID_BYTE_LENGTH+.
     sig { params(codec: Codec, prefix_codec: Codec).returns(Codec) }
     def add_codec_size_prefix(codec, prefix_codec)
-      enc = Encoder.new do |value|
+      inner_size = codec.fixed_size
+      fixed      = inner_size && prefix_codec.fixed_size && (inner_size + T.must(prefix_codec.fixed_size))
+      enc = Encoder.new(fixed_size: fixed) do |value|
         data   = codec.encode(value)
         prefix = prefix_codec.encode(data.bytesize)
         prefix + data
       end
-      dec = Decoder.new do |bytes, offset|
+      dec = Decoder.new(fixed_size: fixed) do |bytes, offset|
         len, prefix_size = prefix_codec.decode(bytes, offset: offset)
-        value, data_size = codec.decode(bytes, offset: offset + prefix_size)
-        [value, prefix_size + data_size]
+        len  = Kernel.Integer(len)
+        data = bytes.byteslice(offset + prefix_size, len) || ''.b
+        if data.bytesize < len
+          Kernel.raise SolanaError.new(
+            SolanaError::CODECS__INVALID_BYTE_LENGTH,
+            { codec_description: 'addDecoderSizePrefix', expected: len, actual: data.bytesize }
+          )
+        end
+        value, = codec.decode(data)
+        [value, prefix_size + len]
       end
       Codec.new(enc, dec)
     end

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

@@ -3,6 +3,38 @@
 
 module Solana::Ruby::Kit
   module Codecs
+    # A size strategy for +array_codec+ / +map_codec+ / +set_codec+ where the
+    # collection ends when the bytes at the next item position match a constant
+    # +sentinel+. Mirrors upstream's `ArrayLikeCodecSentinelSize`
+    # (`{ __kind: 'sentinel', sentinel, strategy? }`), itself a mirror of
+    # Codama's `sentinelCountNode`.
+    #
+    # Unlike a sentinel searched for in the byte stream, this one is compared at
+    # item boundaries only, so its bytes may occur *inside* an item without
+    # terminating the collection.
+    #
+    # +strategy+ controls whether the sentinel is written and required:
+    # - +:required+ (default) - written after the last item; decoding raises
+    #   +CODECS__SENTINEL_MISSING_AT_END_OF_BYTES+ if the bytes run out first.
+    # - +:optional+ - written, but decoding also stops at the end of the bytes,
+    #   to tolerate tightly sized or legacy data that lacks it.
+    # - +:omitted+ - never written; decoding stops at the end of the bytes, and
+    #   consumes the sentinel if one happens to be there.
+    #
+    # Two invariants must hold for a round trip, and - as upstream - the codec
+    # does NOT enforce them:
+    # 1. No item may *begin* with the sentinel's bytes; decoding cannot tell
+    #    such an item from the terminator and stops early.
+    # 2. Under +:optional+ / +:omitted+ the sentinel must be no wider than the
+    #    smallest possible item, or a short trailing item is silently dropped:
+    #    decoding stops once fewer bytes than the sentinel remain.
+    class SentinelSize < T::Struct
+      STRATEGIES = T.let(%i[required optional omitted].freeze, T::Array[Symbol])
+
+      const :sentinel, String
+      const :strategy, Symbol, default: :required
+    end
+
     # Data-structure codecs — mirrors @solana/codecs-data-structures.
     module DataStructures
       extend T::Sig
@@ -15,7 +47,8 @@ module Solana::Ruby::Kit
 
       # Encode/decode a fixed ordered list of named fields.
       # +fields+ is an Array of [name, codec] pairs (name can be String or Symbol).
-      # Encodes to a Hash on decode; expects a Hash for encode.
+      # Decodes to a Hash with Symbol keys. Encode takes a Hash keyed by either
+      # form, whichever way the field was named, so a decoded value re-encodes.
       sig { params(fields: T::Array[[T.any(String, Symbol), Codec]]).returns(Codec) }
       def struct_codec(fields)
         fixed = fields.all? { |_, c| c.fixed_size }
@@ -23,7 +56,11 @@ module Solana::Ruby::Kit
 
         enc = Encoder.new(fixed_size: total) do |value|
           h = T.cast(value, T::Hash[T.untyped, T.untyped])
-          fields.map { |name, codec| codec.encode(h[name] || h[name.to_s]) }.join.b
+          fields.map do |name, codec|
+            # key? rather than `h[name] || ...`, which would skip a false value.
+            key = [name, name.to_sym, name.to_s].find { |k| h.key?(k) }
+            codec.encode(key.nil? ? nil : h[key])
+          end.join.b
         end
         dec = Decoder.new(fixed_size: total) do |bytes, offset|
           result   = {}
@@ -61,85 +98,64 @@ module Solana::Ruby::Kit
         Codec.new(enc, dec)
       end
 
-      # Encode/decode a variable-length array with a u32LE length prefix.
-      # When +size+ is given the array has a fixed element count (no prefix).
+      # Encode/decode an array, one +element_codec+ value per item. +size+
+      # picks how the item count is stored - mirrors upstream's
+      # `ArrayLikeCodecSize`:
       #
-      # When the size is stored as a prefix and there are not enough bytes left
-      # to read it, the decoder yields an empty array rather than failing. That
-      # is deliberate: it lets a program append a collection to an existing
+      # - +nil+ (default): a u32 little-endian count prefix.
+      # - a Codec, e.g. +u16_codec+ or +compact_u16_codec+: the count prefix is
+      #   written and read with that codec instead.
+      # - an Integer: a fixed item count with no prefix. Encoding an array of
+      #   any other length raises +CODECS__INVALID_NUMBER_OF_ITEMS+.
+      # - +:remainder+: no prefix; decoding reads items until the bytes run out,
+      #   so the array must be the last thing in the buffer.
+      # - a SentinelSize: no prefix; the array ends at a sentinel. See
+      #   SentinelSize for the strategies and the invariants you must uphold.
+      #
+      # When the count is a prefix and there are not enough bytes left to read
+      # it, the decoder yields an empty array rather than failing. That is
+      # deliberate: it lets a program append a collection to an existing
       # account layout and still decode accounts written before the change.
       # Formats that cannot accept that leniency - borsh, for one, requires the
       # prefix to be present - can pass +require_size_prefix: true+ to make a
-      # truncated buffer raise instead. The option has no effect when +size+ is
-      # given, since a fixed-count array carries no prefix.
+      # truncated buffer raise instead. The option has no effect on the other
+      # strategies, none of which carries a prefix.
+      #
+      # +description+ names the codec in errors; it defaults to +'array'+.
       sig do
         params(
           element_codec:       Codec,
-          size:                T.nilable(Integer),
-          require_size_prefix: T::Boolean
+          size:                T.nilable(T.any(Integer, Symbol, Codec, SentinelSize)),
+          require_size_prefix: T::Boolean,
+          description:         T.nilable(String)
         ).returns(Codec)
       end
-      def array_codec(element_codec, size: nil, require_size_prefix: false)
-        if size
-          fixed = element_codec.fixed_size ? size * T.must(element_codec.fixed_size) : nil
-          enc = Encoder.new(fixed_size: fixed) do |values|
-            T.cast(values, T::Array[T.untyped]).map { |v| element_codec.encode(v) }.join.b
-          end
-          dec = Decoder.new(fixed_size: fixed) do |bytes, offset|
-            result   = []
-            consumed = 0
-            size.times do
-              val, n = element_codec.decode(bytes, offset: offset + consumed)
-              result << val
-              consumed += n
-            end
-            [result, consumed]
-          end
-          Codec.new(enc, dec)
+      def array_codec(element_codec, size: nil, require_size_prefix: false, description: nil)
+        description ||= 'array'
+        ArrayLikeSize.assert_item_codec_supports_size_strategy(description, size, element_codec.fixed_size)
+        case size
+        when nil          then ArrayLikeSize.prefixed(element_codec, Numbers.u32_codec, require_size_prefix)
+        when Codec        then ArrayLikeSize.prefixed(element_codec, size, require_size_prefix)
+        when Integer      then ArrayLikeSize.fixed_count(element_codec, size, description)
+        when SentinelSize then ArrayLikeSize.sentinel(element_codec, size, description)
+        when :remainder   then ArrayLikeSize.remainder(element_codec)
         else
-          prefix = Numbers.u32_codec
-          enc = Encoder.new do |values|
-            arr    = T.cast(values, T::Array[T.untyped])
-            header = prefix.encode(arr.length)
-            body   = arr.map { |v| element_codec.encode(v) }.join.b
-            header + body
-          end
-          dec = Decoder.new do |bytes, offset|
-            prefix_size = T.must(prefix.fixed_size)
-            remaining   = [bytes.b.bytesize - offset, 0].max
-            if remaining < prefix_size
-              # The prefix is missing or truncated. By default that decodes to
-              # an empty collection having consumed nothing; under
-              # +require_size_prefix+ it is an error.
-              Kernel.raise SolanaError.new(
-                SolanaError::CODECS__INVALID_BYTE_LENGTH,
-                { expected: prefix_size, actual: remaining }
-              ) if require_size_prefix
-
-              next [[], 0]
-            end
-            len, prefix_bytes = prefix.decode(bytes, offset: offset)
-            result   = []
-            consumed = prefix_bytes
-            len.times do
-              val, n = element_codec.decode(bytes, offset: offset + consumed)
-              result << val
-              consumed += n
-            end
-            [result, consumed]
-          end
-          Codec.new(enc, dec)
+          Kernel.raise ArgumentError,
+                       "Unknown array size #{size.inspect}; expected nil, a number Codec, an Integer, " \
+                       ':remainder or a SentinelSize'
         end
       end
 
       # Encode/decode a Hash.
       # Encoded as: [length prefix] + [key, value, key, value, ...]
-      # See +array_codec+ for what +require_size_prefix+ does.
+      # See +array_codec+ for what +size+ and +require_size_prefix+ do; +size+
+      # counts entries, and a SentinelSize is compared at entry (key)
+      # boundaries.
       sig do
         params(
           key_codec:           Codec,
           value_codec:         Codec,
-          size:                T.nilable(Integer),
+          size:                T.nilable(T.any(Integer, Symbol, Codec, SentinelSize)),
           require_size_prefix: T::Boolean
         ).returns(Codec)
       end
@@ -153,11 +169,11 @@ module Solana::Ruby::Kit
       end
 
       # Encode/decode a Set (stored as an array of unique elements).
-      # See +array_codec+ for what +require_size_prefix+ does.
+      # See +array_codec+ for what +size+ and +require_size_prefix+ do.
       sig do
         params(
           element_codec:       Codec,
-          size:                T.nilable(Integer),
+          size:                T.nilable(T.any(Integer, Symbol, Codec, SentinelSize)),
           require_size_prefix: T::Boolean
         ).returns(Codec)
       end
@@ -220,5 +236,160 @@ module Solana::Ruby::Kit
         Codec.new(enc, dec)
       end
     end
+
+    # The per-strategy builders behind +array_codec+ (and so +map_codec+ and
+    # +set_codec+). Call those instead. Kept out of DataStructures on purpose:
+    # everything there is re-exported as a public +Codecs.*+ helper, and these
+    # are an implementation detail.
+    module ArrayLikeSize
+      extend T::Sig
+      extend self
+
+      # Raises when a zero-byte item codec is paired with a strategy that relies
+      # on items consuming bytes to make progress: a sentinel could never be
+      # reached, nor could the end of the bytes under +:remainder+.
+      sig { params(description: String, size: T.untyped, item_fixed_size: T.nilable(Integer)).void }
+      def assert_item_codec_supports_size_strategy(description, size, item_fixed_size)
+        return unless item_fixed_size&.zero?
+        return unless size == :remainder || size.is_a?(SentinelSize)
+
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY,
+          { codec_description: description, size_strategy: size == :remainder ? 'remainder' : 'sentinel' }
+        )
+      end
+
+      # A count prefix written and read with +prefix+.
+      sig { params(element_codec: Codec, prefix: Codec, require_size_prefix: T::Boolean).returns(Codec) }
+      def prefixed(element_codec, prefix, require_size_prefix)
+        enc = Encoder.new do |values|
+          arr = T.cast(values, T::Array[T.untyped])
+          prefix.encode(arr.length) + arr.map { |v| element_codec.encode(v) }.join.b
+        end
+        dec = Decoder.new do |bytes, offset|
+          # A fixed-size prefix needs all its bytes; a variable-size one (e.g.
+          # compact_u16) needs at least one, and raises for itself if the rest
+          # are missing.
+          prefix_size = prefix.fixed_size || 1
+          remaining   = [bytes.bytesize - offset, 0].max
+          if remaining < prefix_size
+            # The prefix is missing or truncated. By default that decodes to an
+            # empty collection having consumed nothing; under
+            # +require_size_prefix+ it is an error.
+            Kernel.raise SolanaError.new(
+              SolanaError::CODECS__INVALID_BYTE_LENGTH,
+              { expected: prefix_size, actual: remaining }
+            ) if require_size_prefix
+
+            next [[], 0]
+          end
+          count, consumed = prefix.decode(bytes, offset: offset)
+          result = Array.new(Kernel.Integer(count)) do
+            val, n = element_codec.decode(bytes, offset: offset + consumed)
+            consumed += n
+            val
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Exactly +count+ items and no prefix. Fixed-size when the items are - and
+      # always for a count of zero, whatever the item.
+      sig { params(element_codec: Codec, count: Integer, description: String).returns(Codec) }
+      def fixed_count(element_codec, count, description)
+        item_size = element_codec.fixed_size
+        fixed     = count.zero? ? 0 : (item_size && count * item_size)
+        enc = Encoder.new(fixed_size: fixed) do |values|
+          arr = T.cast(values, T::Array[T.untyped])
+          unless arr.length == count
+            Kernel.raise SolanaError.new(
+              SolanaError::CODECS__INVALID_NUMBER_OF_ITEMS,
+              { codec_description: description, expected: count, actual: arr.length }
+            )
+          end
+          arr.map { |v| element_codec.encode(v) }.join.b
+        end
+        dec = Decoder.new(fixed_size: fixed) do |bytes, offset|
+          consumed = 0
+          result = Array.new(count) do
+            val, n = element_codec.decode(bytes, offset: offset + consumed)
+            consumed += n
+            val
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # No prefix; decoding reads items until the bytes run out.
+      sig { params(element_codec: Codec).returns(Codec) }
+      def remainder(element_codec)
+        enc = Encoder.new do |values|
+          T.cast(values, T::Array[T.untyped]).map { |v| element_codec.encode(v) }.join.b
+        end
+        dec = Decoder.new do |bytes, offset|
+          result   = []
+          consumed = 0
+          while offset + consumed < bytes.bytesize
+            val, n = element_codec.decode(bytes, offset: offset + consumed)
+            # An item that consumes nothing would never reach the end.
+            Kernel.raise ArgumentError, 'a :remainder array item decoded zero bytes' if n.zero?
+
+            result << val
+            consumed += n
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Ends at a sentinel instead of carrying a count. Always variable-size:
+      # the item count is only known by reading up to the sentinel.
+      sig { params(element_codec: Codec, size: SentinelSize, description: String).returns(Codec) }
+      def sentinel(element_codec, size, description)
+        sentinel = size.sentinel.b
+        strategy = size.strategy
+        # Raised at construction, as upstream does for both the encoder and the
+        # decoder: an empty sentinel matches everywhere and delimits nothing.
+        Kernel.raise SolanaError.new(SolanaError::CODECS__SENTINEL_MUST_NOT_BE_EMPTY) if sentinel.empty?
+        unless SentinelSize::STRATEGIES.include?(strategy)
+          Kernel.raise ArgumentError,
+                       "Unknown sentinel strategy #{strategy.inspect}; expected one of #{SentinelSize::STRATEGIES.inspect}"
+        end
+
+        enc = Encoder.new do |values|
+          body = T.cast(values, T::Array[T.untyped]).map { |v| element_codec.encode(v) }.join.b
+          strategy == :omitted ? body : body + sentinel
+        end
+        dec = Decoder.new do |bytes, offset|
+          result   = []
+          consumed = 0
+          Kernel.loop do
+            position = offset + consumed
+            if position + sentinel.bytesize > bytes.bytesize
+              # Not enough bytes remain to hold the sentinel.
+              if strategy == :required
+                Kernel.raise SolanaError.new(
+                  SolanaError::CODECS__SENTINEL_MISSING_AT_END_OF_BYTES,
+                  { codec_description: description, hex_sentinel: sentinel.unpack1('H*'), sentinel: sentinel }
+                )
+              end
+              break
+            end
+            if Bytes.contains_bytes?(bytes, sentinel, offset: position)
+              # The sentinel is present; consume it and stop.
+              consumed += sentinel.bytesize
+              break
+            end
+            val, n = element_codec.decode(bytes, offset: position)
+            result << val
+            consumed += n
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+    end
   end
 end

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

@@ -200,21 +200,57 @@ module Solana::Ruby::Kit
           bytes.pack('C*')
         end
         dec = Decoder.new do |bytes, offset|
-          b  = bytes.b
-          n  = 0
-          shift = 0
-          consumed = 0
-          Kernel.loop do
-            byte = b.byteslice(offset + consumed, 1)&.unpack1('C') || 0
-            consumed += 1
-            n |= (byte & 0x7F) << shift
-            shift += 7
-            break if (byte & 0x80).zero?
+          b = bytes.b
+          n = 0
+          decoded = (1..3).each do |byte_count|
+            # The chain must terminate within the bytes that remain; a buffer
+            # that ends mid-chain is truncated, not an implicit zero byte.
+            remaining = b.bytesize - offset
+            if remaining < byte_count
+              Kernel.raise SolanaError.new(
+                SolanaError::CODECS__INVALID_BYTE_LENGTH,
+                { codec_description: 'shortU16', expected: byte_count, actual: [remaining, 0].max }
+              )
+            end
+
+            byte = T.must(b.getbyte(offset + byte_count - 1))
+            n |= (byte & 0x7F) << ((byte_count - 1) * 7)
+            next unless (byte & 0x80).zero?
+
+            Numbers.assert_short_u16_in_range(n)
+            break [n, byte_count]
           end
-          [n, consumed]
+          # `each` only returns its range when no byte terminated the chain.
+          next decoded if decoded.is_a?(Array)
+
+          Numbers.raise_short_u16_too_long
         end
         Codec.new(enc, dec)
       end
+
+      # Three terminated shortU16 bytes can hold up to 2^21 - 1, but only the
+      # u16 domain is valid. Shared with the wire-format readers in
+      # WalletStandard and TransactionIntrospection, which decode shortU16
+      # inline so they can raise their own truncation errors.
+      sig { params(value: Integer).void }
+      def assert_short_u16_in_range(value)
+        return if value <= 0xFFFF
+
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__NUMBER_OUT_OF_RANGE,
+          { codec_description: 'shortU16', min: 0, max: 0xFFFF, value: value }
+        )
+      end
+
+      # Raised when all three shortU16 bytes carry a continuation bit: the
+      # encoding would need a fourth byte, which the format does not allow.
+      sig { returns(T.noreturn) }
+      def raise_short_u16_too_long
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__INVALID_BYTE_LENGTH,
+          { codec_description: 'shortU16', expected: 3, actual: 4 }
+        )
+      end
     end
   end
 end

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

@@ -191,11 +191,20 @@ module Solana::Ruby::Kit
         Codec.new(enc, dec)
       end
 
-      # Hex codec — lower-case hex string ↔ binary bytes.
+      # Hex codec — lower-case hex string ↔ binary bytes. Spaces are ignored on
+      # encode; any other non-hex character raises. An odd-length string keeps
+      # its last digit as a final low-nibble byte (+'abc'+ → +0xab 0x0c+), as
+      # upstream's base16 encoder does — +pack('H*')+ alone would pad it into
+      # the high nibble (+0xc0+).
       sig { returns(Codec) }
       def hex_codec
         enc = Encoder.new do |v|
-          [v.to_s.tr(' ', '')].pack('H*')
+          value = v.to_s.tr(' ', '')
+          unless value.match?(/\A\h*\z/)
+            Kernel.raise SolanaError.new(SolanaError::CODECS__INVALID_STRING_FOR_HEX_CODEC, { value: v.to_s })
+          end
+          value = "#{value[0...-1]}0#{value[-1]}" if value.length.odd?
+          [value].pack('H*')
         end
         dec = Decoder.new do |bytes, offset|
           remaining = bytes.b.byteslice(offset..) || ''.b

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

@@ -36,6 +36,7 @@ module Solana::Ruby::Kit
     KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY              = :SOLANA_ERROR__KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY
     KEYS__INVALID_SIGNATURE_BYTE_LENGTH                  = :SOLANA_ERROR__KEYS__INVALID_SIGNATURE_BYTE_LENGTH
     KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE           = :SOLANA_ERROR__KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE
+    KEYS__VERIFICATION_REQUIRES_EXTRACTABLE_PUBLIC_KEY   = :SOLANA_ERROR__KEYS__VERIFICATION_REQUIRES_EXTRACTABLE_PUBLIC_KEY
 
     # ── Instructions ──────────────────────────────────────────────────────────
     INSTRUCTIONS__EXPECTED_TO_HAVE_ACCOUNTS              = :SOLANA_ERROR__INSTRUCTIONS__EXPECTED_TO_HAVE_ACCOUNTS
@@ -99,6 +100,13 @@ module Solana::Ruby::Kit
     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
+    # context: { codec_description:, size_strategy: }
+    CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY = :SOLANA_ERROR__CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY
 
     # ── RPC / JSON-RPC ────────────────────────────────────────────────────────
     RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER = :SOLANA_ERROR__RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER
@@ -138,6 +146,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
@@ -193,6 +203,7 @@ module Solana::Ruby::Kit
         KEYS__PUBLIC_KEY_MUST_MATCH_PRIVATE_KEY          => 'The public key does not match the private key',
         KEYS__INVALID_SIGNATURE_BYTE_LENGTH              => 'Signature must be 64 bytes, got %{actual_length}',
         KEYS__SIGNATURE_STRING_LENGTH_OUT_OF_RANGE       => 'Signature string length out of range (64–88 chars), got %{actual_length}',
+        KEYS__VERIFICATION_REQUIRES_EXTRACTABLE_PUBLIC_KEY => 'Signatures can only be verified using a public key (an RbNaCl::VerifyKey).',
 
         # Instructions
         INSTRUCTIONS__EXPECTED_TO_HAVE_ACCOUNTS          => 'Expected instruction to have accounts',
@@ -237,7 +248,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}',
@@ -250,6 +261,10 @@ module Solana::Ruby::Kit
         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.',
+        CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY => 'Codec [%{codec_description}] cannot use the [%{size_strategy}] size strategy: the item codec has a fixed size of zero and consumes no bytes.',
 
         # RPC
         RPC__INTEGER_OVERFLOW_WHILE_SERIALIZING_LARGE_INTEGER   => 'Integer overflow while serializing large integer %{value}',
@@ -287,6 +302,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/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,
@@ -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_planner.rb

@@ -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,
@@ -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/keys/signatures.rb

@@ -4,6 +4,7 @@
 require 'rbnacl'
 require_relative '../errors'
 require_relative '../encoding/base58'
+require_relative 'small_order'
 
 module Solana::Ruby::Kit
   module Keys
@@ -144,11 +145,23 @@ module Solana::Ruby::Kit
     # Mirrors `verifySignature(key, signature, data)` in TypeScript.
     # Returns false rather than raising on mismatch, matching the TS return type.
     #
+    # Verification is strict: a public key or a signature `R` component that is
+    # a point of small order is rejected without consulting RbNaCl, matching the
+    # Solana runtime whatever the linked libsodium does itself. Upstream raises
+    # for a non-extractable or non-public CryptoKey; an RbNaCl::VerifyKey always
+    # exposes its bytes, so here only a non-VerifyKey (e.g. a SigningKey) raises.
+    #
     # @param verify_key  [RbNaCl::VerifyKey]
     # @param sig_bytes   [SignatureBytes]
     # @param data        [String] binary string that was signed
     sig { params(verify_key: T.untyped, sig_bytes: SignatureBytes, data: String).returns(T::Boolean) }
     def verify_signature(verify_key, sig_bytes, data)
+      unless verify_key.is_a?(RbNaCl::VerifyKey)
+        Kernel.raise SolanaError.new(SolanaError::KEYS__VERIFICATION_REQUIRES_EXTRACTABLE_PUBLIC_KEY)
+      end
+      return false if SmallOrder.small_order_point_encoding?(verify_key.to_bytes)
+      return false if SmallOrder.small_order_point_encoding?(sig_bytes.value.byteslice(0, 32).to_s)
+
       verify_key.verify(sig_bytes.value, data.b)
       true
     rescue RbNaCl::BadSignatureError

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

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Keys
+    extend T::Sig
+
+    # Mirrors the private `isSmallOrderPointEncoding` in @solana/keys
+    # (`small-order.ts`). An Ed25519 public key or signature `R` that is a point
+    # of small order lets trivially forged signatures verify against any data;
+    # the Solana runtime rejects them, so `verify_signature` does too.
+    module SmallOrder
+      extend T::Sig
+      extend self
+
+      P = T.let((1 << 255) - 19, Integer)
+
+      # The y-coordinates of the eight small-order points (the x sign bit picks
+      # between each pair, so it is masked off before the lookup). The two large
+      # ones are parsed from Strings because Sorbet rejects bignum literals.
+      SMALL_ORDER_Y_COORDINATES = T.let(
+        [
+          0,
+          1,
+          P - 1,
+          Integer('2707385501144840649318225287225658788936804267575313519463743609750303402022'),
+          Integer('55188659117513257062467267217118295137698188065244968500265048394206261417927')
+        ].freeze,
+        T::Array[Integer]
+      )
+
+      # True when +bytes+ (a 32-byte binary String) encodes a point of small
+      # order, canonically or not (a y-coordinate >= p is reduced mod p first).
+      # Any other length returns false.
+      sig { params(bytes: String).returns(T::Boolean) }
+      def small_order_point_encoding?(bytes)
+        bytes = bytes.b
+        return false unless bytes.bytesize == 32
+
+        last = bytes.getbyte(31).to_i & 0x7f
+        y    = (bytes.byteslice(0, 31).to_s + last.chr).reverse.unpack1('H*').to_i(16)
+        SMALL_ORDER_Y_COORDINATES.include?(y % P)
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/offchain_messages/codec.rb

@@ -105,9 +105,9 @@ module Solana::Ruby::Kit
         # `Signature` holds a base58 string (that is what `sign_offchain_message` returns),
         # so it has to be decoded back to the 64 raw bytes RbNaCl expects.
         sig_bytes = Solana::Ruby::Kit::Encoding::Base58.decode(signature.to_s)
-        vk.verify(sig_bytes, payload)
-        true
-      rescue RbNaCl::BadSignatureError, RbNaCl::LengthError
+        # Through Keys.verify_signature for its small-order key/`R` rejection.
+        Keys.verify_signature(vk, Keys.signature_bytes(sig_bytes), payload)
+      rescue RbNaCl::LengthError, SolanaError
         false
       end
     end

data/lib/solana/ruby/kit/transaction_introspection/compiled_transaction_message.rb

@@ -154,14 +154,15 @@ module Solana::Ruby::Kit
     sig { params(bytes: String, offset: Integer).returns([Integer, Integer]) }
     def decode_compact_u16(bytes, offset)
       value = 0
-      shift = 0
-      Kernel.loop do
+      (0...3).each do |i|
         byte, offset = read_byte(bytes, offset)
-        value |= (byte & 0x7f) << shift
-        shift += 7
-        break unless (byte & 0x80) != 0
+        value |= (byte & 0x7f) << (i * 7)
+        next unless (byte & 0x80).zero?
+
+        Codecs::Numbers.assert_short_u16_in_range(value)
+        return [value, offset]
       end
-      [value, offset]
+      Codecs::Numbers.raise_short_u16_too_long
     end
     private_class_method :decode_compact_u16
   end

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

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '8.3.0'
+      VERSION = '8.5.0'
     end
   end
 end

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

@@ -233,8 +233,7 @@ module Solana::Ruby::Kit
     sig { params(bytes: String, offset: Integer).returns([Integer, Integer]) }
     def decode_compact_u16(bytes, offset)
       value = 0
-      shift = 0
-      Kernel.loop do
+      (0...3).each do |i|
         byte = bytes.getbyte(offset)
         if byte.nil?
           Kernel.raise SolanaError.new(
@@ -243,11 +242,13 @@ module Solana::Ruby::Kit
           )
         end
         offset += 1
-        value  |= (byte & 0x7f) << shift
-        shift  += 7
-        break unless (byte & 0x80) != 0
+        value  |= (byte & 0x7f) << (i * 7)
+        next unless (byte & 0x80).zero?
+
+        Codecs::Numbers.assert_short_u16_in_range(value)
+        return [value, offset]
       end
-      [value, offset]
+      Codecs::Numbers.raise_short_u16_too_long
     end
     private_class_method :decode_compact_u16
   end

data/solana-ruby-kit.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.version               = Solana::Ruby::Kit::VERSION
   spec.authors               = ['Paul Zupan, Idhra Inc.']
   spec.summary               = 'Ruby port of the Anza TypeScript SDK (@anza-xyz/kit)'
-  spec.homepage              = 'https://github.com/pzupan/solana-ruby-kit'
+  spec.homepage              = 'https://github.com/idhra/solana-ruby-kit'
   spec.license               = 'MIT'
   spec.required_ruby_version = '>= 3.2.0'
   spec.require_paths         = ['lib']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 8.3.0
+  version: 8.5.0
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
@@ -231,7 +231,7 @@ files:
 - 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/max_instructions.rb
+- lib/solana/ruby/kit/instruction_plans/message_packer_errors.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
@@ -246,6 +246,7 @@ files:
 - lib/solana/ruby/kit/keys/private_key.rb
 - lib/solana/ruby/kit/keys/public_key.rb
 - lib/solana/ruby/kit/keys/signatures.rb
+- lib/solana/ruby/kit/keys/small_order.rb
 - lib/solana/ruby/kit/offchain_messages.rb
 - lib/solana/ruby/kit/offchain_messages/codec.rb
 - lib/solana/ruby/kit/offchain_messages/message.rb
@@ -346,13 +347,13 @@ files:
 - lib/solana/ruby/kit/version.rb
 - lib/solana/ruby/kit/wallet_standard.rb
 - solana-ruby-kit.gemspec
-homepage: https://github.com/pzupan/solana-ruby-kit
+homepage: https://github.com/idhra/solana-ruby-kit
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/pzupan/solana-ruby-kit/tree/main
-  documentation_uri: https://github.com/pzupan/solana-ruby-kit/wiki
-  bug_tracker_uri: https://github.com/pzupan/solana-ruby-kit/issues
+  source_code_uri: https://github.com/idhra/solana-ruby-kit/tree/main
+  documentation_uri: https://github.com/idhra/solana-ruby-kit/wiki
+  bug_tracker_uri: https://github.com/idhra/solana-ruby-kit/issues
 rdoc_options: []
 require_paths:
 - lib

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

@@ -1,59 +0,0 @@
-# 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)
-
-    extend self
-
-    # Resolves the effective maximum number of instructions allowed in a transaction message,
-    # falling back to the default when no value is provided.
-    # Mirrors `resolveMaxInstructions(maxInstructions)`.
-    sig { params(max_instructions: T.nilable(Integer)).returns(Integer) }
-    def resolve_max_instructions(max_instructions)
-      max_instructions || DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION
-    end
-
-    # Asserts that a configured maximum number of instructions per transaction is valid.
-    # +nil+ is allowed and falls back to the default.
-    # Mirrors `assertValidMaxInstructionsPerTransaction(maxInstructions)`.
-    sig { params(max_instructions: T.nilable(Integer)).void }
-    def assert_valid_max_instructions_per_transaction(max_instructions)
-      return if max_instructions.nil?
-
-      if max_instructions <= 0 || max_instructions > TRANSACTION_INSTRUCTION_LIMIT
-        Kernel.raise SolanaError.new(
-          SolanaError::INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION,
-          {
-            max_instructions:              max_instructions,
-            transaction_instruction_limit: TRANSACTION_INSTRUCTION_LIMIT
-          }
-        )
-      end
-    end
-
-    # Raises if +num_instructions+ exceeds +max_instructions+.
-    # Mirrors `assertMaxInstructionsPerTransaction(numInstructions, maxInstructions)`.
-    sig { params(num_instructions: Integer, max_instructions: Integer).void }
-    def assert_max_instructions_per_transaction(num_instructions, max_instructions)
-      return if num_instructions <= max_instructions
-
-      Kernel.raise SolanaError.new(
-        SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED,
-        { max_instructions: max_instructions, num_instructions: num_instructions }
-      )
-    end
-  end
-end