solana-ruby-kit 8.4.0 → 8.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 874d4a76636d15a05ab0474d28d1ea069b1a8c1d50b18d9178a9f0639747fd92
-  data.tar.gz: 28cfc822396c2c7156daa6da853e25be997b4febbcbdec66e71aa687ad05c782
+  metadata.gz: 727cac096a118ea677195240a8ea3440f593b1f7930b0f0f603ae8156b66862a
+  data.tar.gz: e8a03418fa257b58b243933a9fe6c5918c7882f1bdfe47ad49f87bbd63a95a28
 SHA512:
-  metadata.gz: ca743643e0257eadc50274add4ce4f843dcb19f4c63ca9a4c1b4e9ebf3310e02945eee1d6b5cfe2d91fb153452e8d03ea6a44b6becad3a210c8f92f04350c2f5
-  data.tar.gz: 162cdeb79aee32775b4e35bc1fb80be095e11cb65f15217c3b93076de5172c76181ed94bb26b7d3b16a7b65394a28676b352cca03cee16ecb62ac96ab218b188
+  metadata.gz: 7fdcd2a35bde1be1eba49bf48f373d5bf701cd399c23f54f1bc53c4a7fdf8a21c4b3f478079be2a57095bd91aff7eb736a31fa047d357231bbcb3410bbaa6ad6
+  data.tar.gz: 890775283c250e98d91ab31263afd4b5c6f3fd093ae1c96422623d9c63716deb69a5376537b11811fd9deeb0961445d319f69086a985e41ee5d800d7f7bdb008

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
@@ -296,8 +299,54 @@ rescue Solana::Ruby::Kit::Rpc::RpcError => e
   puts e.message  # JSON-RPC error message
 rescue Solana::Ruby::Kit::Rpc::HttpTransportError => e
   puts e.status_code  # HTTP status code
+  puts e.retry_after  # raw Retry-After header, or nil
 ```
 
+#### Retries
+
+Transient failures are retried automatically, for every RPC method, with
+full-jitter exponential backoff. Defaults: `max_attempts: 5`, `base_delay: 0.25`,
+`max_delay: 8.0` (seconds). The wait before retry *n* is
+`rand * min(base_delay * 2**(n - 1), max_delay)`; a `Retry-After` header
+overrides it (still capped at `max_delay`).
+
+What gets retried depends on whether the request could have reached the node:
+
+| Failure | Retried for |
+|---|---|
+| Connect-phase: `Errno::ENETUNREACH`, `EHOSTUNREACH`, `ECONNREFUSED`, `Net::OpenTimeout`, `SocketError` | every method — the bytes never left the machine |
+| In-flight: `Errno::ECONNRESET`, `EPIPE`, `EOFError`, `Net::ReadTimeout`, `Net::WriteTimeout`, `OpenSSL::SSL::SSLError` | idempotent methods only |
+| HTTP 429 / 502 / 503 / 504 | idempotent methods only |
+| JSON-RPC error in a 200 response (`RpcError`) | never — the node answered |
+
+Every attempt resends the same bytes with the same JSON-RPC `id`; nothing is
+re-signed and no blockhash is refetched. Resending an identical signed
+`sendTransaction` is safe because the cluster dedupes by signature. When
+retries run out, the original error is re-raised.
+
+**`requestAirdrop` is not idempotent**: each accepted request is a new airdrop,
+so it is retried only on connect-phase errors. Add any of your own
+non-idempotent methods to `non_idempotent:`.
+
+```ruby
+# Customize, with logging
+policy = Solana::Ruby::Kit::Rpc::RetryPolicy.new(
+  max_attempts: 8,
+  max_delay:    15.0,
+  on_retry:     ->(method, attempt, error, wait) {
+    logger.warn("#{method} attempt #{attempt} failed (#{error.class}: #{error.message}); retrying in #{wait.round(2)}s")
+  }
+)
+rpc = Solana::Ruby::Kit::Rpc::Client.new(Solana::Ruby::Kit::RpcTypes.devnet, retry_policy: policy)
+
+# Disable
+rpc = Solana::Ruby::Kit::Rpc::Client.new(url, retry_policy: Solana::Ruby::Kit::Rpc::RetryPolicy.none)
+```
+
+`Rpc::Transport.new` takes the same `retry_policy:`, plus `sleeper:` (a
+callable receiving the wait in seconds, `Kernel.method(:sleep)` by default) so
+tests need not actually wait. The WebSocket subscriptions client is not covered.
+
 ### `Solana::Ruby::Kit::RpcTypes` — `@solana/rpc-types`
 
 Cluster URL helpers and typed wrappers.
@@ -477,6 +526,11 @@ 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
 
 Wrap a codec in one that observes a value - or the bytes - without changing it,

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

@@ -132,6 +132,7 @@ module Solana::Ruby::Kit
       end
       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)
@@ -244,6 +245,20 @@ module Solana::Ruby::Kit
       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)

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
@@ -104,6 +105,8 @@ module Solana::Ruby::Kit
     # 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
@@ -200,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',
@@ -260,6 +264,7 @@ module Solana::Ruby::Kit
         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}',

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/rpc/client.rb

@@ -80,18 +80,36 @@ module Solana::Ruby::Kit
       # @param cluster_url [RpcTypes::ClusterUrl, String]  endpoint to connect to.
       # @param headers     [Hash<String, String>]           additional HTTP headers.
       # @param timeout     [Integer]                        read timeout in seconds.
+      # @param retry_policy [RetryPolicy]                   transient-failure retries; `RetryPolicy.none` disables.
+      # @param sleeper     [#call]                          called with the wait in seconds between retries.
       sig do
         params(
           cluster_url:  T.untyped,    # RpcTypes::ClusterUrl or String
           headers:      T::Hash[String, String],
           timeout:      Integer,
-          open_timeout: Integer
+          open_timeout: Integer,
+          retry_policy: RetryPolicy,
+          sleeper:      T.any(Proc, Method)
         ).void
       end
-      def initialize(cluster_url, headers: {}, timeout: Transport::DEFAULT_TIMEOUT, open_timeout: Transport::DEFAULT_OPEN_TIMEOUT)
+      def initialize(
+        cluster_url,
+        headers:      {},
+        timeout:      Transport::DEFAULT_TIMEOUT,
+        open_timeout: Transport::DEFAULT_OPEN_TIMEOUT,
+        retry_policy: RetryPolicy.new,
+        sleeper:      Kernel.method(:sleep)
+      )
         url = cluster_url.respond_to?(:url) ? cluster_url.url : cluster_url.to_s
         @transport = T.let(
-          Transport.new(url: url, headers: headers, timeout: timeout, open_timeout: open_timeout),
+          Transport.new(
+            url:          url,
+            headers:      headers,
+            timeout:      timeout,
+            open_timeout: open_timeout,
+            retry_policy: retry_policy,
+            sleeper:      sleeper
+          ),
           Transport
         )
       end

data/lib/solana/ruby/kit/rpc/retry_policy.rb

@@ -0,0 +1,149 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'socket'
+require 'time'
+
+module Solana::Ruby::Kit
+  module Rpc
+    # Decides whether a failed JSON-RPC POST is retried, and how long to wait first.
+    # Ruby-only: upstream's `createHttpTransport` has no retry.
+    #
+    # Errors are classified by whether the request could have reached the node:
+    #
+    # - Connect-phase errors (`CONNECT_ERRORS`) are retried for every method — the
+    #   request bytes never left the machine, so nothing can have been executed twice.
+    # - In-flight errors (`IN_FLIGHT_ERRORS`) and HTTP 429/502/503/504 are retried
+    #   only for methods not listed in `non_idempotent`: the node may already have
+    #   acted on the request.
+    # - JSON-RPC error objects (`RpcError`) are never retried — the node answered.
+    #
+    # Backoff is full-jitter exponential: before retry n (1-based) the transport
+    # waits `rand * min(base_delay * 2**(n - 1), max_delay)`. A `Retry-After` header
+    # overrides it, capped at `max_delay`.
+    class RetryPolicy
+      extend T::Sig
+
+      CONNECT_ERRORS = T.let(
+        [Errno::ENETUNREACH, Errno::EHOSTUNREACH, Errno::ECONNREFUSED, Net::OpenTimeout, SocketError].freeze,
+        T::Array[T.class_of(Exception)]
+      )
+
+      IN_FLIGHT_ERRORS = T.let(
+        [Errno::ECONNRESET, Errno::EPIPE, EOFError, Net::ReadTimeout, Net::WriteTimeout, OpenSSL::SSL::SSLError].freeze,
+        T::Array[T.class_of(Exception)]
+      )
+
+      RETRYABLE_HTTP_STATUSES = T.let([429, 502, 503, 504].freeze, T::Array[Integer])
+
+      DEFAULT_NON_IDEMPOTENT = T.let(['requestAirdrop'].freeze, T::Array[String])
+
+      sig { returns(Integer) }
+      attr_reader :max_attempts
+
+      sig { returns(Float) }
+      attr_reader :base_delay
+
+      sig { returns(Float) }
+      attr_reader :max_delay
+
+      sig { returns(T::Array[String]) }
+      attr_reader :non_idempotent
+
+      # Called before each retry's sleep as `on_retry.call(method, attempt, error, wait)`,
+      # where `attempt` is the 1-based number of the attempt that just failed.
+      sig { returns(T.nilable(T.any(Proc, Method))) }
+      attr_reader :on_retry
+
+      # A policy that never retries.
+      sig { returns(RetryPolicy) }
+      def self.none
+        new(max_attempts: 1)
+      end
+
+      sig do
+        params(
+          max_attempts:   Integer,
+          base_delay:     Numeric,
+          max_delay:      Numeric,
+          non_idempotent: T::Array[String],
+          on_retry:       T.nilable(T.any(Proc, Method)),
+          random:         Random
+        ).void
+      end
+      def initialize(
+        max_attempts:   5,
+        base_delay:     0.25,
+        max_delay:      8.0,
+        non_idempotent: DEFAULT_NON_IDEMPOTENT,
+        on_retry:       nil,
+        random:         Random.new
+      )
+        raise ArgumentError, 'max_attempts must be at least 1' if max_attempts < 1
+
+        @max_attempts   = T.let(max_attempts, Integer)
+        @base_delay     = T.let(base_delay.to_f, Float)
+        @max_delay      = T.let(max_delay.to_f, Float)
+        @non_idempotent = T.let(non_idempotent.dup.freeze, T::Array[String])
+        @on_retry       = T.let(on_retry, T.nilable(T.any(Proc, Method)))
+        @random         = T.let(random, Random)
+      end
+
+      # Whether attempt number `attempt` (1-based) of `method`, having failed with
+      # `error`, should be followed by another.
+      sig { params(method: String, error: Exception, attempt: Integer).returns(T::Boolean) }
+      def retry?(method, error, attempt)
+        attempt < @max_attempts && retryable?(method, error)
+      end
+
+      # Whether `error` is retryable for `method` at all, ignoring the attempt budget.
+      sig { params(method: String, error: Exception).returns(T::Boolean) }
+      def retryable?(method, error)
+        return true if connect_error?(error)
+        return false unless idempotent?(method)
+
+        case error
+        when HttpTransportError then RETRYABLE_HTTP_STATUSES.include?(error.status_code)
+        else IN_FLIGHT_ERRORS.any? { |klass| error.is_a?(klass) }
+        end
+      end
+
+      sig { params(method: String).returns(T::Boolean) }
+      def idempotent?(method)
+        !@non_idempotent.include?(method)
+      end
+
+      # Seconds to wait after attempt number `attempt` (1-based) failed.
+      # `retry_after` is the raw `Retry-After` header value, if any: delta-seconds
+      # or an HTTP-date. An unparseable value falls back to the backoff.
+      sig { params(attempt: Integer, retry_after: T.nilable(String)).returns(Float) }
+      def delay(attempt, retry_after: nil)
+        server_wait = parse_retry_after(retry_after)
+        return [server_wait, @max_delay].min if server_wait
+
+        @random.rand(1.0) * [@base_delay * (2.0**(attempt - 1)), @max_delay].min
+      end
+
+      private
+
+      sig { params(error: Exception).returns(T::Boolean) }
+      def connect_error?(error)
+        CONNECT_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+
+      sig { params(value: T.nilable(String)).returns(T.nilable(Float)) }
+      def parse_retry_after(value)
+        return nil if value.nil?
+
+        stripped = value.strip
+        return [stripped.to_f, 0.0].max if stripped.match?(/\A\d+(\.\d+)?\z/)
+
+        [Time.httpdate(stripped) - Time.now, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc/transport.rb

@@ -5,6 +5,7 @@ require 'net/http'
 require 'json'
 require 'uri'
 require_relative '../errors'
+require_relative 'retry_policy'
 
 module Solana::Ruby::Kit
   module Rpc
@@ -33,9 +34,14 @@ module Solana::Ruby::Kit
       sig { returns(Integer) }
       attr_reader :status_code
 
-      sig { params(status_code: Integer, message: String).void }
-      def initialize(status_code, message)
+      # Raw `Retry-After` header value, when the response carried one.
+      sig { returns(T.nilable(String)) }
+      attr_reader :retry_after
+
+      sig { params(status_code: Integer, message: String, retry_after: T.nilable(String)).void }
+      def initialize(status_code, message, retry_after: nil)
         @status_code = T.let(status_code, Integer)
+        @retry_after = T.let(retry_after, T.nilable(String))
         super("HTTP #{status_code}: #{message}")
       end
     end
@@ -45,6 +51,14 @@ module Solana::Ruby::Kit
     #
     # Makes synchronous POST requests — TypeScript's async `fetch` maps to
     # Ruby's blocking `Net::HTTP`.  Use threads or Fibers for concurrency.
+    #
+    # Transient failures are retried according to `retry_policy` (see `RetryPolicy`;
+    # on by default, `RetryPolicy.none` disables it). The payload is built once, so
+    # every attempt sends the same bytes with the same JSON-RPC `id` — the transport
+    # never re-signs a transaction or refetches a blockhash.
+    #
+    # Each attempt opens its own connection (no keep-alive), so a Transport can be
+    # shared across threads and a retry never reuses a dead socket.
     class Transport
       extend T::Sig
 
@@ -61,7 +75,9 @@ module Solana::Ruby::Kit
           timeout:        Integer,
           open_timeout:   Integer,
           to_json:        T.nilable(T.proc.params(arg0: T.untyped).returns(String)),
-          from_json:      T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped))
+          from_json:      T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped)),
+          retry_policy:   RetryPolicy,
+          sleeper:        T.any(Proc, Method)
         ).void
       end
       def initialize(
@@ -70,7 +86,9 @@ module Solana::Ruby::Kit
         timeout:      DEFAULT_TIMEOUT,
         open_timeout: DEFAULT_OPEN_TIMEOUT,
         to_json:      nil,
-        from_json:    nil
+        from_json:    nil,
+        retry_policy: RetryPolicy.new,
+        sleeper:      Kernel.method(:sleep)
       )
         @url          = T.let(url, String)
         @headers      = T.let(headers, T::Hash[String, String])
@@ -80,8 +98,13 @@ module Solana::Ruby::Kit
         @from_json    = T.let(from_json, T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped)))
         @request_id   = T.let(0, Integer)
         @uri          = T.let(URI.parse(url), URI::Generic)
+        @retry_policy = T.let(retry_policy, RetryPolicy)
+        @sleeper      = T.let(sleeper, T.any(Proc, Method))
       end
 
+      sig { returns(RetryPolicy) }
+      attr_reader :retry_policy
+
       # Sends a single JSON-RPC request and returns the parsed `result`.
       # Raises `RpcError` on a JSON-RPC error, `HttpTransportError` on HTTP failure.
       sig { params(method: String, params: T::Array[T.untyped]).returns(T.untyped) }
@@ -89,7 +112,7 @@ module Solana::Ruby::Kit
         payload = build_payload(method, params)
         body    = @to_json ? @to_json.call(payload) : JSON.generate(payload)
 
-        response = post(body)
+        response = post_with_retry(method, body)
 
         parsed = @from_json ? @from_json.call(T.must(response.body), payload) : JSON.parse(T.must(response.body))
 
@@ -109,6 +132,32 @@ module Solana::Ruby::Kit
         { 'jsonrpc' => '2.0', 'id' => @request_id, 'method' => method, 'params' => params }
       end
 
+      # Posts `body` until it succeeds, the error is not retryable for `method`, or
+      # the policy's attempts run out — then re-raises the last error unchanged.
+      sig { params(method: String, body: String).returns(Net::HTTPResponse) }
+      def post_with_retry(method, body)
+        attempt = 0
+        begin
+          attempt += 1
+          post(body)
+        rescue StandardError => e
+          reset_connection unless e.is_a?(HttpTransportError)
+          raise unless @retry_policy.retry?(method, e, attempt)
+
+          retry_after = e.is_a?(HttpTransportError) ? e.retry_after : nil
+          wait = @retry_policy.delay(attempt, retry_after: retry_after)
+          @retry_policy.on_retry&.call(method, attempt, e, wait)
+          @sleeper.call(wait)
+          retry
+        end
+      end
+
+      # Called after every socket-level error, before any retry. Nothing to do
+      # while each attempt opens a fresh `Net::HTTP`; a keep-alive connection
+      # would be closed here so the retry could not reuse a dead socket.
+      sig { void }
+      def reset_connection; end
+
       sig { params(body: String).returns(Net::HTTPResponse) }
       def post(body)
         http = Net::HTTP.new(@uri.host, @uri.port)
@@ -126,7 +175,7 @@ module Solana::Ruby::Kit
         response = http.request(req)
 
         unless response.is_a?(Net::HTTPSuccess)
-          raise HttpTransportError.new(response.code.to_i, response.message)
+          raise HttpTransportError.new(response.code.to_i, response.message, retry_after: response['Retry-After'])
         end
 
         response

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

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '8.4.0'
+      VERSION = '8.5.1'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 8.4.0
+  version: 8.5.1
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
@@ -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
@@ -288,6 +289,7 @@ files:
 - lib/solana/ruby/kit/rpc/api/send_transaction.rb
 - lib/solana/ruby/kit/rpc/api/simulate_transaction.rb
 - lib/solana/ruby/kit/rpc/client.rb
+- lib/solana/ruby/kit/rpc/retry_policy.rb
 - lib/solana/ruby/kit/rpc/transport.rb
 - lib/solana/ruby/kit/rpc_parsed_types.rb
 - lib/solana/ruby/kit/rpc_parsed_types/address_lookup_table.rb