solana-ruby-kit 8.2.0 → 8.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba7d2659d83b01af6565c7af483364d61e61fcc9761cbca9d63d8d41f6b4d73a
-  data.tar.gz: bd8402f845e9d8db5845be0e358676d00e308b2a0777afc1973e8814175e1c1c
+  metadata.gz: c281fe52274deb9bbf493d3848b3bcb64ecc42b11e4acc6b727ef5e301dcb252
+  data.tar.gz: 6fefa37ee1da4bc377bc58f609adad46c2940b3377a9333168df0f6ff83cef6c
 SHA512:
-  metadata.gz: 589ade790ebb62b97f9905e8fe98113efc93deb5a6fad37239d377ab427915838eaa3d461644d213944ee8b80796134b28d5a6da43529a3920bb5037940a20a1
-  data.tar.gz: 3c03649c3b4314b93e7321f74b77150cd19bd775535b8431c14b678fdf35d3e7d4703fac43f341c3480ec5031b0c78bd0c0e3b7e385bb01f1822fc57fa5afaec
+  metadata.gz: ba02f18c40de9b8b9ab544551ac477e94b1f4dcd4b177e8d513680b3d406830991acb770f4f427b5e9d4ca4abaf0cdda28d5849d649e6e50037104fe653390a7
+  data.tar.gz: 5ccc70a501ac546deb6520394b9efedc8ddbd7b2278318ab0fdf3944352e9a66ac06d66bd8b8288b1bf4b10a9cb395266d23f3feec3d7708741421a83033af9d

data/README.md

@@ -360,20 +360,25 @@ Binary encoder/decoder framework for Solana on-chain data.
 ```ruby
 Codecs = Solana::Ruby::Kit::Codecs
 
-# Numbers
-u8  = Codecs.u8
-u16 = Codecs.u16_le   # little-endian (default for Solana)
-u32 = Codecs.u32_le
-u64 = Codecs.u64_le
-i8  = Codecs.i8
-f32 = Codecs.f32_le
-
-u16.encode(1000)       # => "\xe8\x03"
-u16.decode("\xe8\x03") # => 1000
+# Numbers. Every multi-byte codec takes `endian:`, defaulting to :little
+# (which is what Solana uses on-chain).
+u8   = Codecs.u8_codec
+u16  = Codecs.u16_codec
+u32  = Codecs.u32_codec
+u64  = Codecs.u64_codec
+u128 = Codecs.u128_codec
+u256 = Codecs.u256_codec              # 32 bytes
+i8   = Codecs.i8_codec
+i256 = Codecs.i256_codec              # 32 bytes, two's complement
+f32  = Codecs.f32_codec
+be   = Codecs.u16_codec(endian: :big)
+
+u16.encode(1000)         # => "\xe8\x03"
+u16.decode("\xe8\x03")   # => [1000, 2]   # [value, bytes consumed]
 
 # Strings
-utf8  = Codecs.utf8
-bytes = Codecs.bytes_codec
+utf8  = Codecs.utf8_codec
+bytes = Codecs.bytes_codec(32)
 
 # Data structures
 struct_codec = Codecs.struct_codec([
@@ -382,6 +387,71 @@ struct_codec = Codecs.struct_codec([
 ])
 ```
 
+#### UTF-8 options
+
+By default the UTF-8 codec substitutes `U+FFFD` for malformed input, strips a
+leading byte order mark, and strips null characters - the last of which is what
+makes fixed-size padded strings read back cleanly, at the cost of being lossy
+for strings that legitimately contain nulls.
+
+```ruby
+# Reject invalid UTF-8 instead of substituting the replacement character.
+strict = Codecs.utf8_codec(fatal: true)
+strict.encode("a\xC0\x80")   # raises SolanaError (invalid UTF-8 string)
+strict.decode("\xFF".b)      # raises SolanaError (invalid UTF-8 bytes)
+
+# Decode losslessly, keeping null characters and a leading byte order mark.
+lossless = Codecs.utf8_codec(ignore_bom: true, remove_null_characters: false)
+
+# The assertions are usable on their own.
+Codecs.find_malformed_utf8_sequence_offset("a\xC0\x80".b)  # => 1 (overlong)
+Codecs.assert_is_well_formed_utf8_bytes("\xE8\xAA\x9E".b)  # passes ("語")
+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.
+
+#### Requiring a size prefix
+
+A prefixed collection decodes an exhausted buffer to an empty collection rather
+than failing, so a program can append a collection to an existing account layout
+and still read accounts written before the change. Formats that cannot accept
+that leniency - borsh requires the prefix to be present - can opt into failing:
+
+```ruby
+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.
+
+#### Tap combinators
+
+Wrap a codec in one that observes a value - or the bytes - without changing it,
+for validation guards or logging. A tap that raises aborts the operation.
+
+```ruby
+guarded = Codecs.tap_encoder(u8.encoder) do |value|
+  raise ArgumentError, 'Value must not exceed 100' if value > 100
+end
+guarded.encode(42)   # => "\x2a"
+guarded.encode(200)  # raises ArgumentError
+
+# Both sides at once; decode_tap is optional.
+Codecs.tap_codec(u8, encode_tap: ->(v) { log(v) }, decode_tap: ->(v) { log(v) })
+
+# Observe the bytes instead of the value.
+Codecs.tap_decoder_bytes(u8.decoder) do |bytes, offset|
+  raise ArgumentError, 'Expected a 0 or a 1' if bytes.bytes[offset] > 1
+end
+```
+
+Upstream's byte taps take `(bytes, pre_offset, post_offset)` because encoders
+there write into a shared buffer. A Ruby `Encoder` returns a standalone byte
+String, so the encode-side taps receive exactly the bytes that were written.
+
 ### `Solana::Ruby::Kit::RpcSubscriptions` — `@solana/rpc-subscriptions`
 
 WebSocket-based subscription client.

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

@@ -28,7 +28,7 @@ module Solana::Ruby::Kit
       const :space,           T.nilable(Integer)
     end
 
-    module_function
+    extend self
 
     # Builds a MaybeAccount representing a found account.
     sig { params(account: Account).returns(MaybeAccount) }

data/lib/solana/ruby/kit/addresses/address.rb

@@ -61,7 +61,7 @@ module Solana::Ruby::Kit
     ADDRESS_MIN_STR_LEN = T.let(32, Integer)
     ADDRESS_MAX_STR_LEN = T.let(44, Integer)
 
-    module_function
+    extend self
 
     # Encodes raw bytes (binary String, length == 32) to a base58 address string.
     # Mirrors `getAddressEncoder()` in TypeScript.

data/lib/solana/ruby/kit/addresses/curve.rb

@@ -27,7 +27,7 @@ module Solana::Ruby::Kit
     # sqrt(−1) mod p  =  2^((p−1)/4) mod p
     CURVE_SQRT_M1 = T.let(2.pow((CURVE_P - 1) / 4, CURVE_P), Integer)
 
-    module_function
+    extend self
 
     # Returns true if the 32-byte binary string represents a point on the
     # Ed25519 twisted-Edwards curve.

data/lib/solana/ruby/kit/addresses/program_derived_address.rb

@@ -38,7 +38,7 @@ module Solana::Ruby::Kit
     # Marker bytes appended during hashing: UTF-8 "ProgramDerivedAddress".
     PDA_MARKER_BYTES = T.let('ProgramDerivedAddress'.b, String)
 
-    module_function
+    extend self
 
     # Returns true if the value is a well-formed ProgramDerivedAddress.
     # Mirrors `isProgramDerivedAddress()` in TypeScript.

data/lib/solana/ruby/kit/addresses/public_key.rb

@@ -8,7 +8,7 @@ require_relative '../errors'
 module Solana::Ruby::Kit
   module Addresses
     extend T::Sig
-    module_function
+    extend self
 
     # Given an RbNaCl::VerifyKey (Ed25519 public key), returns its Solana Address.
     #

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

@@ -64,7 +64,7 @@ module Solana::Ruby::Kit
 
     # ── Combinators ─────────────────────────────────────────────────────────────
 
-    module_function
+    extend self
 
     # Return a Codec whose output is always exactly +size+ bytes
     # (zero-padded on right, truncated if too large).
@@ -117,6 +117,100 @@ module Solana::Ruby::Kit
       Codec.new(enc, dec)
     end
 
+    # ── Tap combinators ─────────────────────────────────────────────────────────
+    #
+    # Each of these wraps a codec in one that observes a value (or the bytes)
+    # without changing it, for validation guards, logging or other read-only
+    # side effects. A tap that raises aborts the operation and the error
+    # propagates to the caller.
+    #
+    # Where upstream's byte taps take +(bytes, pre_offset, post_offset)+ over a
+    # shared output buffer, a Ruby Encoder returns a standalone byte String, so
+    # the encode-side taps below receive exactly the bytes that were written -
+    # the window upstream's tap has to slice out for itself. The decode-side
+    # taps keep +(bytes, offset)+, which Ruby Decoders already receive.
+
+    # Observe each value before it is encoded, leaving it unchanged.
+    sig do
+      params(encoder: Encoder, tap_fn: T.proc.params(value: T.untyped).void).returns(Encoder)
+    end
+    def tap_encoder(encoder, &tap_fn)
+      Encoder.new(fixed_size: encoder.fixed_size, max_size: encoder.max_size) do |value|
+        tap_fn.call(value)
+        encoder.encode(value)
+      end
+    end
+
+    # Observe each decoded value after it is decoded, leaving it unchanged.
+    sig do
+      params(decoder: Decoder, tap_fn: T.proc.params(value: T.untyped).void).returns(Decoder)
+    end
+    def tap_decoder(decoder, &tap_fn)
+      Decoder.new(fixed_size: decoder.fixed_size) do |bytes, offset|
+        value, consumed = decoder.decode(bytes, offset: offset)
+        tap_fn.call(value)
+        [value, consumed]
+      end
+    end
+
+    # Observe a codec's values on both sides. +decode_tap+ is optional.
+    sig do
+      params(
+        codec:      Codec,
+        encode_tap: T.proc.params(value: T.untyped).void,
+        decode_tap: T.nilable(T.proc.params(value: T.untyped).void)
+      ).returns(Codec)
+    end
+    def tap_codec(codec, encode_tap:, decode_tap: nil)
+      enc = tap_encoder(codec.encoder) { |value| encode_tap.call(value) }
+      dec = decode_tap ? tap_decoder(codec.decoder) { |value| decode_tap.call(value) } : codec.decoder
+      Codec.new(enc, dec)
+    end
+
+    # Observe the bytes an encoder produced, after they are written.
+    sig do
+      params(encoder: Encoder, tap_fn: T.proc.params(bytes: String).void).returns(Encoder)
+    end
+    def tap_encoder_bytes(encoder, &tap_fn)
+      Encoder.new(fixed_size: encoder.fixed_size, max_size: encoder.max_size) do |value|
+        bytes = encoder.encode(value)
+        tap_fn.call(bytes)
+        bytes
+      end
+    end
+
+    # Observe the raw bytes a decoder is about to read, before decoding.
+    sig do
+      params(
+        decoder: Decoder,
+        tap_fn:  T.proc.params(bytes: String, offset: Integer).void
+      ).returns(Decoder)
+    end
+    def tap_decoder_bytes(decoder, &tap_fn)
+      Decoder.new(fixed_size: decoder.fixed_size) do |bytes, offset|
+        tap_fn.call(bytes, offset)
+        decoder.decode(bytes, offset: offset)
+      end
+    end
+
+    # Observe a codec's raw bytes on both sides. +decode_tap+ is optional.
+    sig do
+      params(
+        codec:      Codec,
+        encode_tap: T.proc.params(bytes: String).void,
+        decode_tap: T.nilable(T.proc.params(bytes: String, offset: Integer).void)
+      ).returns(Codec)
+    end
+    def tap_codec_bytes(codec, encode_tap:, decode_tap: nil)
+      enc = tap_encoder_bytes(codec.encoder) { |bytes| encode_tap.call(bytes) }
+      dec = if decode_tap
+              tap_decoder_bytes(codec.decoder) { |bytes, offset| decode_tap.call(bytes, offset) }
+            else
+              codec.decoder
+            end
+      Codec.new(enc, dec)
+    end
+
     # Reverse the byte order of the encoded output (and input).
     sig { params(codec: Codec).returns(Codec) }
     def reverse_codec(codec)

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

@@ -63,8 +63,23 @@ module Solana::Ruby::Kit
 
       # Encode/decode a variable-length array with a u32LE length prefix.
       # When +size+ is given the array has a fixed element count (no prefix).
-      sig { params(element_codec: Codec, size: T.nilable(Integer)).returns(Codec) }
-      def array_codec(element_codec, size: nil)
+      #
+      # 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
+      # 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.
+      sig do
+        params(
+          element_codec:       Codec,
+          size:                T.nilable(Integer),
+          require_size_prefix: T::Boolean
+        ).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|
@@ -90,6 +105,19 @@ module Solana::Ruby::Kit
             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
@@ -106,10 +134,18 @@ module Solana::Ruby::Kit
 
       # Encode/decode a Hash.
       # Encoded as: [length prefix] + [key, value, key, value, ...]
-      sig { params(key_codec: Codec, value_codec: Codec, size: T.nilable(Integer)).returns(Codec) }
-      def map_codec(key_codec, value_codec, size: nil)
+      # See +array_codec+ for what +require_size_prefix+ does.
+      sig do
+        params(
+          key_codec:           Codec,
+          value_codec:         Codec,
+          size:                T.nilable(Integer),
+          require_size_prefix: T::Boolean
+        ).returns(Codec)
+      end
+      def map_codec(key_codec, value_codec, size: nil, require_size_prefix: false)
         pair_codec = tuple_codec([key_codec, value_codec])
-        array_codec(pair_codec, size: size).transform_decoder do |pairs|
+        array_codec(pair_codec, size: size, require_size_prefix: require_size_prefix).transform_decoder do |pairs|
           pairs.each_with_object({}) { |(k, v), h| h[k] = v }
         end.transform_encoder do |hash|
           T.cast(hash, T::Hash[T.untyped, T.untyped]).map { |k, v| [k, v] }
@@ -117,9 +153,16 @@ module Solana::Ruby::Kit
       end
 
       # Encode/decode a Set (stored as an array of unique elements).
-      sig { params(element_codec: Codec, size: T.nilable(Integer)).returns(Codec) }
-      def set_codec(element_codec, size: nil)
-        array_codec(element_codec, size: size)
+      # See +array_codec+ for what +require_size_prefix+ does.
+      sig do
+        params(
+          element_codec:       Codec,
+          size:                T.nilable(Integer),
+          require_size_prefix: T::Boolean
+        ).returns(Codec)
+      end
+      def set_codec(element_codec, size: nil, require_size_prefix: false)
+        array_codec(element_codec, size: size, require_size_prefix: require_size_prefix)
           .transform_encoder { |s| T.cast(s, T::Set[T.untyped]).to_a }
           .transform_decoder { |arr| Set.new(arr) }
       end

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

@@ -19,6 +19,43 @@ module Solana::Ruby::Kit
       # defeated the "directly available as Codecs.x" intent in codecs.rb.
       extend self
 
+      # ── Multi-byte integers ──────────────────────────────────────────────────
+
+      # Shared implementation behind u128 / i128 / u256 / i256.
+      #
+      # Upstream splits these values into 64-bit words because a JS `DataView`
+      # has no accessor wider than 64 bits. Ruby's Integer is arbitrary
+      # precision, so there is nothing to split: the value is shifted out one
+      # byte at a time and reassembled the same way, which keeps a single
+      # implementation correct for any +byte_count+.
+      #
+      # +signed+ selects two's-complement interpretation over +byte_count * 8+
+      # bits, so negative values round-trip.
+      sig { params(byte_count: Integer, signed: T::Boolean, endian: Symbol).returns(Codec) }
+      def big_int_codec(byte_count, signed:, endian: :little)
+        bits = byte_count * 8
+        enc = Encoder.new(fixed_size: byte_count) do |v|
+          n = Kernel.Integer(v)
+          n += (1 << bits) if signed && n.negative?
+          out = Array.new(byte_count) do
+            byte = n & 0xFF
+            n >>= 8
+            byte
+          end
+          # `out` is least-significant-byte first.
+          (endian == :little ? out : out.reverse).pack('C*')
+        end
+        dec = Decoder.new(fixed_size: byte_count) do |bytes, offset|
+          slice = bytes.b.byteslice(offset, byte_count) || ("\x00" * byte_count).b
+          arr   = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
+          arr   = arr.reverse if endian == :little
+          n     = arr.reduce(0) { |acc, byte| (acc << 8) | byte }
+          n -= (1 << bits) if signed && n >= (1 << (bits - 1))
+          [n, byte_count]
+        end
+        Codec.new(enc, dec)
+      end
+
       # ── Unsigned integers ────────────────────────────────────────────────────
 
       sig { returns(Codec) }
@@ -62,29 +99,12 @@ module Solana::Ruby::Kit
 
       sig { params(endian: Symbol).returns(Codec) }
       def u128_codec(endian: :little)
-        enc = Encoder.new(fixed_size: 16) do |v|
-          n = Kernel.Integer(v)
-          if endian == :little
-            bytes = []
-            16.times { bytes << (n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          else
-            bytes = []
-            16.times { bytes.unshift(n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          end
-        end
-        dec = Decoder.new(fixed_size: 16) do |bytes, offset|
-          slice = bytes.b.byteslice(offset, 16) || ("\x00" * 16).b
-          arr   = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
-          n = if endian == :little
-                arr.reverse.reduce(0) { |acc, b| (acc << 8) | b }
-              else
-                arr.reduce(0) { |acc, b| (acc << 8) | b }
-              end
-          [n, 16]
-        end
-        Codec.new(enc, dec)
+        big_int_codec(16, signed: false, endian: endian)
+      end
+
+      sig { params(endian: Symbol).returns(Codec) }
+      def u256_codec(endian: :little)
+        big_int_codec(32, signed: false, endian: endian)
       end
 
       # ── Signed integers ──────────────────────────────────────────────────────
@@ -130,33 +150,12 @@ module Solana::Ruby::Kit
 
       sig { params(endian: Symbol).returns(Codec) }
       def i128_codec(endian: :little)
-        enc = Encoder.new(fixed_size: 16) do |v|
-          n    = Kernel.Integer(v)
-          # Two's complement for negative numbers
-          n += (1 << 128) if n.negative?
-          if endian == :little
-            bytes = []
-            16.times { bytes << (n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          else
-            bytes = []
-            16.times { bytes.unshift(n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          end
-        end
-        dec = Decoder.new(fixed_size: 16) do |bytes, offset|
-          slice = bytes.b.byteslice(offset, 16) || ("\x00" * 16).b
-          arr   = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
-          n = if endian == :little
-                arr.reverse.reduce(0) { |acc, b| (acc << 8) | b }
-              else
-                arr.reduce(0) { |acc, b| (acc << 8) | b }
-              end
-          # Convert from unsigned to signed 128-bit
-          n -= (1 << 128) if n >= (1 << 127)
-          [n, 16]
-        end
-        Codec.new(enc, dec)
+        big_int_codec(16, signed: true, endian: endian)
+      end
+
+      sig { params(endian: Symbol).returns(Codec) }
+      def i256_codec(endian: :little)
+        big_int_codec(32, signed: true, endian: endian)
       end
 
       # ── Floating point ───────────────────────────────────────────────────────

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) }