solana-ruby-kit 8.5.0 → 8.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3067fc0036448f0aef241f14f4e0b95f0faf6d6cedd4ed8aae5206d6e3169e28
-  data.tar.gz: a689c349c2e41d519b6e06814319d9760b2816bf59f48109d8d839790c4e6312
+  metadata.gz: c6c87d85cd6d590f5db4b09599ae8f0dc73be1c3f6ca5d387b184933bf9e5db3
+  data.tar.gz: 26b99981a5c5313a825f1bc6a0dc89c4f73e7dea53708a809af00c52e1b4047a
 SHA512:
-  metadata.gz: a02f7ce5743af32d1d6401f2023fc7293e33abfe1c0f495ec91f00a7ca4399e6fd654c7baa3f3c966ed34d6495514607432315323fb3425f294e8bf1713035ae
-  data.tar.gz: bfd06cf91f1fc1652cb5a578b822595c5f976537561fddbad22e04e6dc5567f1284b211b4e41be6472426005f3f4b0197c486fe5d87a046e2dac8989e30acb61
+  metadata.gz: 9a9a8a706b215942873c2e3208e34ed016e03355e11968b41f55fcf3b4191c4e5b4486c61e92dc223ea7f06c3b4217cb9f0b7bff733893ef7aab7344c44e5340
+  data.tar.gz: e9b515766f64ff010c570a8835a44c201863d45fc79947462bbef51adfe19192a5dfe5d8fa347a4e6d2be6f5ddf30e9ea052097233113001fb9f62495d6d2b09

data/README.md

@@ -213,6 +213,12 @@ nonce_constraint = TxMsg::DurableNonceLifetimeConstraint.new(
   nonce_account_address: nonce_addr
 )
 msg = TxMsg.set_durable_nonce_lifetime(nonce_constraint, msg)
+
+# Version 1 transaction config: compile to a mask + values, and back.
+config = TxMsg::V1TransactionConfig.new(compute_unit_limit: 300_000, priority_fee_lamports: 5_000)
+mask   = TxMsg.get_transaction_config_mask(config)    # => 0b111
+values = TxMsg.get_transaction_config_values(config)  # => [u64 5_000, u32 300_000]
+TxMsg.decompile_transaction_config(mask, values).compute_unit_limit  # => 300_000
 ```
 
 ### `Solana::Ruby::Kit::Transactions` — `@solana/transactions`
@@ -250,6 +256,9 @@ Txns.assert_fully_signed_transaction!(tx)
 Txns.within_size_limit?(tx)             # => true if wire size <= 1232 bytes
 Txns.assert_within_size_limit!(tx)
 
+Txns::LEGACY_TRANSACTION_SIZE_LIMIT     # => 1232 (legacy and v0)
+Txns::V1_TRANSACTION_SIZE_LIMIT         # => 4096
+
 # Sendable = fully signed AND within size limit
 Txns.sendable_transaction?(signed_tx)   # => true / false
 Txns.assert_sendable_transaction!(signed_tx)
@@ -287,6 +296,7 @@ rpc.get_signatures_for_address(address)
 rpc.get_vote_accounts
 rpc.get_ag_genesis_cert                      # Alpenglow genesis cert, or nil
 rpc.simulate_transaction(encoded_tx)
+rpc.simulate_transaction(encoded_tx, inner_instructions: true, inner_instructions_encoding: 'json')
 rpc.send_transaction(encoded_tx)
 rpc.request_airdrop(address, lamports)        # devnet / testnet only
 ```
@@ -299,8 +309,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.
@@ -906,7 +962,9 @@ end
 > fetch with `'json'` or `'base64'` instead. Wire-format (`'base64'`/`'base58'`)
 > decoding only handles legacy and v0 transactions — Ruby's transaction compiler
 > doesn't produce v1 transactions yet either, so there is nothing to decompile
-> for that version.
+> for that version. A `'json'` response is not wire-decoded, so it may be v1; its
+> `transactionConfig` lands in `compiled_message.config_mask` / `config_values`,
+> which `TransactionMessages.decompile_transaction_config` reads back.
 
 ## Error handling
 
@@ -922,6 +980,19 @@ end
 
 Error codes match the TypeScript `@solana/errors` package constants.
 
+`SolanaError.simulation_error?` identifies a failed transaction simulation, including
+the `Rpc::RpcError` that `send_transaction` raises when preflight fails:
+
+```ruby
+begin
+  rpc.send_transaction(signed_tx)
+rescue StandardError => e
+  raise unless Solana::Ruby::Kit::SolanaError.simulation_error?(e)
+
+  puts e.is_a?(Solana::Ruby::Kit::Rpc::RpcError) ? e.data['logs'] : e.context[:logs]
+end
+```
+
 ## Type checking with Sorbet
 
 Every public method has a `sig` block. To enable static type checking in your project:

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

@@ -61,6 +61,10 @@ module Solana::Ruby::Kit
     TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE = :SOLANA_ERROR__TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE
     # context: { unsupported_version: }
     TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED            = :SOLANA_ERROR__TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED
+    # context: { mask: }
+    TRANSACTION__INVALID_CONFIG_MASK_PRIORITY_FEE_BITS   = :SOLANA_ERROR__TRANSACTION__INVALID_CONFIG_MASK_PRIORITY_FEE_BITS
+    # context: { actual_kind:, config_name:, expected_kind: }
+    TRANSACTION__INVALID_CONFIG_VALUE_KIND               = :SOLANA_ERROR__TRANSACTION__INVALID_CONFIG_VALUE_KIND
     # context: { compute_unit_limit:, max_compute_unit_limit: }
     TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE         = :SOLANA_ERROR__TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE
     # context: { heap_size:, max_heap_size:, min_heap_size:, multiple_of: }
@@ -226,6 +230,8 @@ module Solana::Ruby::Kit
         TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND => 'Failed to decompile instruction: program address not found at index %{index}',
         TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE => 'Failed to decompile instruction: account index %{index} is out of range',
         TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED        => 'Transaction version %{unsupported_version} is not supported',
+        TRANSACTION__INVALID_CONFIG_MASK_PRIORITY_FEE_BITS => 'Invalid transaction config mask: %{mask}. Bits 0 and 1 must match (both set or both unset)',
+        TRANSACTION__INVALID_CONFIG_VALUE_KIND           => 'The transaction config value for %{config_name} has the incorrect kind. Expected %{expected_kind}, got %{actual_kind}.',
         TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE     => 'Transaction compute unit limit must be an integer in the range [0, %{max_compute_unit_limit}]. `%{compute_unit_limit}` given',
         TRANSACTION__INVALID_HEAP_SIZE                   => 'Transaction heap size must be an integer multiple of %{multiple_of} bytes in the range [%{min_heap_size}, %{max_heap_size}]. `%{heap_size}` given',
         TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE => 'Transaction simulation failed: %{message}',
@@ -330,6 +336,33 @@ module Solana::Ruby::Kit
       T::Hash[Symbol, String]
     )
 
+    SIMULATION_ERROR_CODES = T.let(
+      [
+        TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE,
+        TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_COMPUTE_LIMIT,
+        TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS
+      ].freeze,
+      T::Array[Symbol]
+    )
+
+    # The JSON-RPC error code of a `sendTransaction` whose preflight simulation failed.
+    JSON_RPC_SEND_TRANSACTION_PREFLIGHT_FAILURE = T.let(-32_002, Integer)
+
+    # Returns true if +error+ was raised because a transaction simulation failed.
+    #
+    # `Rpc::Client#send_transaction` reports a preflight failure as an `Rpc::RpcError`
+    # rather than a SolanaError, so that counts too; its `data` holds the simulation
+    # result (`data['logs']`). A SolanaError holds it in `context` (`context[:logs]`).
+    #
+    # Mirrors `isSimulationError()` from @solana/errors.
+    sig { params(error: T.untyped).returns(T::Boolean) }
+    def self.simulation_error?(error)
+      return SIMULATION_ERROR_CODES.include?(error.code) if error.is_a?(SolanaError)
+      return false unless defined?(Rpc::RpcError) && error.is_a?(Rpc::RpcError)
+
+      error.code == JSON_RPC_SEND_TRANSACTION_PREFLIGHT_FAILURE
+    end
+
     sig { returns(Symbol) }
     attr_reader :code
 

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

@@ -72,7 +72,8 @@ module Solana::Ruby::Kit
 
           if transaction_error
             Kernel.raise SolanaError.new(
-              SolanaError::TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS
+              SolanaError::TRANSACTION__FAILED_WHEN_SIMULATING_TO_ESTIMATE_RESOURCE_LIMITS,
+              simulation_result_context(sim_value)
             )
           end
 
@@ -152,5 +153,14 @@ module Solana::Ruby::Kit
       end
       result
     end
+
+    # The simulation result as a SolanaError context: `unitsConsumed` becomes
+    # `:units_consumed`, and so on. Upstream moves `err` onto the error's `cause` via a
+    # transaction error translator Ruby does not have, so here it stays in the context.
+    sig { params(sim_value: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def simulation_result_context(sim_value)
+      sim_value.to_h { |key, value| [key.gsub(/[A-Z]/) { |c| "_#{c.downcase}" }.to_sym, value] }
+    end
+    private_class_method :simulation_result_context
   end
 end

data/lib/solana/ruby/kit/rpc/api/simulate_transaction.rb

@@ -9,6 +9,10 @@ module Solana::Ruby::Kit
       # Simulate a transaction without broadcasting it.
       # Mirrors TypeScript's SimulateTransactionApi.simulateTransaction.
       # Returns an RpcContextualValue whose value is the simulation result hash.
+      #
+      # +inner_instructions_encoding+ is `'json'` (compiled form) or `'jsonParsed'`, and has
+      # no effect unless +inner_instructions+ is true. Servers older than Agave 4.5 ignore
+      # it and always return `'jsonParsed'`, so callers must handle either shape.
       module SimulateTransaction
         extend T::Sig
         extend T::Helpers
@@ -22,7 +26,10 @@ module Solana::Ruby::Kit
             commitment:          T.nilable(Symbol),
             sig_verify:          T::Boolean,
             replace_recent_blockhash: T::Boolean,
-            accounts:            T.nilable(T::Hash[String, T.untyped])
+            accounts:            T.nilable(T::Hash[String, T.untyped]),
+            min_context_slot:    T.nilable(Integer),
+            inner_instructions:  T::Boolean,
+            inner_instructions_encoding: T.nilable(String)
           ).returns(RpcTypes::RpcContextualValue)
         end
         def simulate_transaction(
@@ -31,7 +38,10 @@ module Solana::Ruby::Kit
           commitment:               nil,
           sig_verify:               false,
           replace_recent_blockhash: false,
-          accounts:                 nil
+          accounts:                 nil,
+          min_context_slot:         nil,
+          inner_instructions:       false,
+          inner_instructions_encoding: nil
         )
           config = {
             'encoding'              => encoding,
@@ -40,6 +50,9 @@ module Solana::Ruby::Kit
           }
           config['commitment'] = commitment.to_s if commitment
           config['accounts']   = accounts if accounts
+          config['minContextSlot']            = min_context_slot if min_context_slot
+          config['innerInstructions']         = true if inner_instructions
+          config['innerInstructionsEncoding'] = inner_instructions_encoding if inner_instructions_encoding
 
           result = transport.request('simulateTransaction', [encoded_transaction, config])
           slot   = Kernel.Integer(result['context']['slot'])

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/rpc_subscriptions/transport.rb

@@ -63,7 +63,9 @@ module Solana::Ruby::Kit
         _send(payload)
 
         response = q.pop
-        raise Rpc::RpcError.new(response['error']['message'], response['error']['code']) if response['error']
+        if (err = response['error'])
+          raise Rpc::RpcError.new(err['code'].to_i, err['message'].to_s, err['data'])
+        end
 
         response['result']
       end

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

@@ -3,6 +3,7 @@
 
 require_relative '../addresses/address'
 require_relative '../errors'
+require_relative '../transaction_messages/v1_transaction_config'
 
 module Solana::Ruby::Kit
   module TransactionIntrospection
@@ -37,6 +38,9 @@ module Solana::Ruby::Kit
       const :static_accounts, T::Array[Addresses::Address]
       const :instructions,    T::Array[CompiledInstruction]
       const :lifetime_token,  String  # base58-encoded blockhash or nonce value
+      # Version 1 only; see TransactionMessages.decompile_transaction_config.
+      const :config_mask,     Integer, default: 0
+      const :config_values,   T::Array[TransactionMessages::CompiledTransactionConfigValue], default: []
     end
 
     extend self

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

@@ -155,6 +155,9 @@ module Solana::Ruby::Kit
       version = rpc_tx['version'] || :legacy
       version = :legacy if version == 'legacy'
 
+      # Only a v1 message has a config; `transactionConfig` is absent otherwise.
+      config = get_v1_transaction_config(version == 1 ? message['transactionConfig'] : nil)
+
       compiled_message = CompiledTransactionMessage.new(
         version:         version,
         header:          header,
@@ -162,7 +165,9 @@ module Solana::Ruby::Kit
         instructions:    instructions,
         # For durable-nonce transactions, `recentBlockhash` is the nonce value, not a
         # blockhash — either way it is the message's lifetime token.
-        lifetime_token:  message['recentBlockhash']
+        lifetime_token:  message['recentBlockhash'],
+        config_mask:     TransactionMessages.get_transaction_config_mask(config),
+        config_values:   TransactionMessages.get_transaction_config_values(config)
       )
 
       DecodedRpcTransaction.new(
@@ -172,5 +177,18 @@ module Solana::Ruby::Kit
       )
     end
     private_class_method :decode_from_json
+
+    # The RPC names the priority fee `priorityFee`, and reports an unset field as null.
+    sig { params(transaction_config: T.nilable(T::Hash[String, T.untyped])).returns(TransactionMessages::V1TransactionConfig) }
+    def get_v1_transaction_config(transaction_config)
+      config = transaction_config || {}
+      TransactionMessages::V1TransactionConfig.new(
+        compute_unit_limit:              config['computeUnitLimit'],
+        heap_size:                       config['heapSize'],
+        loaded_accounts_data_size_limit: config['loadedAccountsDataSizeLimit'],
+        priority_fee_lamports:           config['priorityFee']
+      )
+    end
+    private_class_method :get_v1_transaction_config
   end
 end

data/lib/solana/ruby/kit/transaction_messages/v1_transaction_config.rb

@@ -0,0 +1,132 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module TransactionMessages
+    # Set in a config mask when a priority fee is present. Both bits must match:
+    # a mask with only one of them set is invalid.
+    TRANSACTION_CONFIG_PRIORITY_FEE_LAMPORTS_BIT_MASK = T.let(0b11, Integer)
+    TRANSACTION_CONFIG_COMPUTE_UNIT_LIMIT_BIT_MASK = T.let(0b100, Integer)
+    TRANSACTION_CONFIG_LOADED_ACCOUNTS_DATA_SIZE_LIMIT_BIT_MASK = T.let(0b1000, Integer)
+    TRANSACTION_CONFIG_HEAP_SIZE_BIT_MASK = T.let(0b10000, Integer)
+
+    # The resource limits and priority fee of a version 1 transaction message.
+    # A nil field is absent from the config; 0 is a set value.
+    #
+    # Mirrors `V1TransactionConfig` from @solana/transaction-messages.
+    class V1TransactionConfig < T::Struct
+      const :compute_unit_limit,              T.nilable(Integer)
+      const :heap_size,                       T.nilable(Integer)
+      const :loaded_accounts_data_size_limit, T.nilable(Integer)
+      const :priority_fee_lamports,           T.nilable(Integer)
+    end
+
+    # A single entry of a compiled message's `config_values`, tagged with the
+    # width it is encoded with: `:u64` for the priority fee, `:u32` otherwise.
+    #
+    # Mirrors `CompiledTransactionConfigValue` (`kind` is a Symbol here, where
+    # upstream uses the strings `'u32'` / `'u64'`).
+    class CompiledTransactionConfigValue < T::Struct
+      const :kind,  Symbol
+      const :value, Integer
+    end
+
+    extend self
+
+    # Returns true if the mask flags a priority fee. Raises
+    # TRANSACTION__INVALID_CONFIG_MASK_PRIORITY_FEE_BITS if only one of its two bits is set.
+    # Mirrors `transactionConfigMaskHasPriorityFee()`.
+    sig { params(mask: Integer).returns(T::Boolean) }
+    def transaction_config_mask_has_priority_fee?(mask)
+      bits = mask & TRANSACTION_CONFIG_PRIORITY_FEE_LAMPORTS_BIT_MASK
+      if [0b01, 0b10].include?(bits)
+        Kernel.raise SolanaError.new(SolanaError::TRANSACTION__INVALID_CONFIG_MASK_PRIORITY_FEE_BITS, { mask: mask })
+      end
+
+      bits == TRANSACTION_CONFIG_PRIORITY_FEE_LAMPORTS_BIT_MASK
+    end
+
+    # Mirrors `transactionConfigMaskHasComputeUnitLimit()`.
+    sig { params(mask: Integer).returns(T::Boolean) }
+    def transaction_config_mask_has_compute_unit_limit?(mask)
+      (mask & TRANSACTION_CONFIG_COMPUTE_UNIT_LIMIT_BIT_MASK) != 0
+    end
+
+    # Mirrors `transactionConfigMaskHasLoadedAccountsDataSizeLimit()`.
+    sig { params(mask: Integer).returns(T::Boolean) }
+    def transaction_config_mask_has_loaded_accounts_data_size_limit?(mask)
+      (mask & TRANSACTION_CONFIG_LOADED_ACCOUNTS_DATA_SIZE_LIMIT_BIT_MASK) != 0
+    end
+
+    # Mirrors `transactionConfigMaskHasHeapSize()`.
+    sig { params(mask: Integer).returns(T::Boolean) }
+    def transaction_config_mask_has_heap_size?(mask)
+      (mask & TRANSACTION_CONFIG_HEAP_SIZE_BIT_MASK) != 0
+    end
+
+    # Computes the `config_mask` of a compiled version 1 message.
+    # Mirrors `getTransactionConfigMask()`.
+    sig { params(config: V1TransactionConfig).returns(Integer) }
+    def get_transaction_config_mask(config)
+      mask = 0
+      mask |= TRANSACTION_CONFIG_PRIORITY_FEE_LAMPORTS_BIT_MASK unless config.priority_fee_lamports.nil?
+      mask |= TRANSACTION_CONFIG_COMPUTE_UNIT_LIMIT_BIT_MASK unless config.compute_unit_limit.nil?
+      mask |= TRANSACTION_CONFIG_LOADED_ACCOUNTS_DATA_SIZE_LIMIT_BIT_MASK unless config.loaded_accounts_data_size_limit.nil?
+      mask |= TRANSACTION_CONFIG_HEAP_SIZE_BIT_MASK unless config.heap_size.nil?
+      mask
+    end
+
+    # Computes the `config_values` of a compiled version 1 message: the set
+    # fields, in the order their bits appear in the mask.
+    # Mirrors `getTransactionConfigValues()`.
+    sig { params(config: V1TransactionConfig).returns(T::Array[CompiledTransactionConfigValue]) }
+    def get_transaction_config_values(config)
+      [
+        [:u64, config.priority_fee_lamports],
+        [:u32, config.compute_unit_limit],
+        [:u32, config.loaded_accounts_data_size_limit],
+        [:u32, config.heap_size]
+      ].filter_map do |kind, value|
+        value.nil? ? nil : CompiledTransactionConfigValue.new(kind: kind, value: value)
+      end
+    end
+
+    # Decodes a compiled message's `config_mask` and `config_values` back into a
+    # V1TransactionConfig holding only the fields present in the mask.
+    #
+    # Raises TRANSACTION__INVALID_CONFIG_MASK_PRIORITY_FEE_BITS if only one of the
+    # priority fee bits is set, and TRANSACTION__INVALID_CONFIG_VALUE_KIND if a
+    # value's kind does not match its field.
+    #
+    # Mirrors `decompileTransactionConfig()`.
+    sig do
+      params(config_mask: Integer, config_values: T::Array[CompiledTransactionConfigValue])
+        .returns(V1TransactionConfig)
+    end
+    def decompile_transaction_config(config_mask, config_values)
+      fields = [
+        [:priority_fee_lamports, :u64, transaction_config_mask_has_priority_fee?(config_mask)],
+        [:compute_unit_limit, :u32, transaction_config_mask_has_compute_unit_limit?(config_mask)],
+        [:loaded_accounts_data_size_limit, :u32, transaction_config_mask_has_loaded_accounts_data_size_limit?(config_mask)],
+        [:heap_size, :u32, transaction_config_mask_has_heap_size?(config_mask)]
+      ]
+
+      present = fields.select { |_name, _kind, set| set }
+      config = present.each_with_index.to_h do |(name, kind, _set), index|
+        value = T.must(config_values[index])
+        unless value.kind == kind
+          Kernel.raise SolanaError.new(
+            SolanaError::TRANSACTION__INVALID_CONFIG_VALUE_KIND,
+            { actual_kind: value.kind, config_name: name, expected_kind: kind }
+          )
+        end
+
+        [name, value.value]
+      end
+
+      V1TransactionConfig.new(**T.unsafe(config))
+    end
+  end
+end

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

@@ -5,3 +5,4 @@
 require_relative 'transaction_messages/transaction_message'
 require_relative 'transaction_messages/resource_limit_validation'
 require_relative 'transaction_messages/compute_budget'
+require_relative 'transaction_messages/v1_transaction_config'

data/lib/solana/ruby/kit/transactions/compiler.rb

@@ -9,8 +9,17 @@ require_relative '../errors'
 
 module Solana::Ruby::Kit
   module Transactions
-    # Maximum wire-encoded transaction size in bytes (Solana protocol limit).
-    TRANSACTION_SIZE_LIMIT = T.let(1232, Integer)
+    # The maximum size of a legacy (and v0) transaction in bytes.
+    # Mirrors `LEGACY_TRANSACTION_SIZE_LIMIT` from @solana/transactions.
+    LEGACY_TRANSACTION_SIZE_LIMIT = T.let(1232, Integer)
+
+    # The maximum size of a version 1 transaction in bytes. Nothing in Ruby compiles
+    # v1 transactions yet, so no size check here applies it.
+    # Mirrors `V1_TRANSACTION_SIZE_LIMIT` from @solana/transactions.
+    V1_TRANSACTION_SIZE_LIMIT = T.let(4096, Integer)
+
+    # The limit Ruby enforces: every transaction it can compile is legacy-sized.
+    TRANSACTION_SIZE_LIMIT = T.let(LEGACY_TRANSACTION_SIZE_LIMIT, Integer)
 
     extend self
 

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 8.5.0
+  version: 8.6.0
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
@@ -289,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
@@ -341,6 +342,7 @@ files:
 - lib/solana/ruby/kit/transaction_messages/compute_budget.rb
 - lib/solana/ruby/kit/transaction_messages/resource_limit_validation.rb
 - lib/solana/ruby/kit/transaction_messages/transaction_message.rb
+- lib/solana/ruby/kit/transaction_messages/v1_transaction_config.rb
 - lib/solana/ruby/kit/transactions.rb
 - lib/solana/ruby/kit/transactions/compiler.rb
 - lib/solana/ruby/kit/transactions/transaction.rb