solana-ruby-kit 8.2.0 → 8.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba7d2659d83b01af6565c7af483364d61e61fcc9761cbca9d63d8d41f6b4d73a
-  data.tar.gz: bd8402f845e9d8db5845be0e358676d00e308b2a0777afc1973e8814175e1c1c
+  metadata.gz: 874d4a76636d15a05ab0474d28d1ea069b1a8c1d50b18d9178a9f0639747fd92
+  data.tar.gz: 28cfc822396c2c7156daa6da853e25be997b4febbcbdec66e71aa687ad05c782
 SHA512:
-  metadata.gz: 589ade790ebb62b97f9905e8fe98113efc93deb5a6fad37239d377ab427915838eaa3d461644d213944ee8b80796134b28d5a6da43529a3920bb5037940a20a1
-  data.tar.gz: 3c03649c3b4314b93e7321f74b77150cd19bd775535b8431c14b678fdf35d3e7d4703fac43f341c3480ec5031b0c78bd0c0e3b7e385bb01f1822fc57fa5afaec
+  metadata.gz: ca743643e0257eadc50274add4ce4f843dcb19f4c63ca9a4c1b4e9ebf3310e02945eee1d6b5cfe2d91fb153452e8d03ea6a44b6becad3a210c8f92f04350c2f5
+  data.tar.gz: 162cdeb79aee32775b4e35bc1fb80be095e11cb65f15217c3b93076de5172c76181ed94bb26b7d3b16a7b65394a28676b352cca03cee16ecb62ac96ab218b188

data/README.md

@@ -360,28 +360,148 @@ 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)
+# 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
+
+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.
+
+#### 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
+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, 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.
+
+#### 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.
@@ -675,6 +795,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/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).
@@ -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
@@ -117,6 +133,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)