solana-ruby-kit 7.0.0 → 7.1.1

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

@@ -115,6 +115,10 @@ module Solana::Ruby::Kit
     OFFCHAIN_MESSAGES__NON_PRINTABLE_ASCII_CHARACTER     = :SOLANA_ERROR__OFFCHAIN_MESSAGES__NON_PRINTABLE_ASCII_CHARACTER
     OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG                  = :SOLANA_ERROR__OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG
     OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN    = :SOLANA_ERROR__OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN
+    # context: { actual_bytes:, expected_bytes: }
+    OFFCHAIN_MESSAGES__CONTENT_DOES_NOT_MATCH_EXPECTED   = :SOLANA_ERROR__OFFCHAIN_MESSAGE__CONTENT_DOES_NOT_MATCH_EXPECTED
+    # context: { actual_addresses:, expected_addresses: }
+    OFFCHAIN_MESSAGES__REQUIRED_SIGNATORIES_DO_NOT_MATCH_EXPECTED = :SOLANA_ERROR__OFFCHAIN_MESSAGE__REQUIRED_SIGNATORIES_DO_NOT_MATCH_EXPECTED
 
     # ── Instruction plans ─────────────────────────────────────────────────────
     # context: { num_bytes_required:, num_free_bytes: }
@@ -139,6 +143,7 @@ module Solana::Ruby::Kit
 
     # ── Subscribable ──────────────────────────────────────────────────────────
     SUBSCRIBABLE__RETRY_NOT_SUPPORTED                     = :SOLANA_ERROR__SUBSCRIBABLE__RETRY_NOT_SUPPORTED
+    SUBSCRIBABLE__STREAM_CLOSED_WITHOUT_ERROR             = :SOLANA_ERROR__SUBSCRIBABLE__STREAM_CLOSED_WITHOUT_ERROR
 
     # ── Fixed-points ──────────────────────────────────────────────────────────
     FIXED_POINTS__STRICT_MODE_PRECISION_LOSS              = :SOLANA_ERROR__FIXED_POINTS__STRICT_MODE_PRECISION_LOSS
@@ -255,6 +260,12 @@ module Solana::Ruby::Kit
         OFFCHAIN_MESSAGES__NON_PRINTABLE_ASCII_CHARACTER => 'Offchain message v0 contains non-printable ASCII character at index %{index}',
         OFFCHAIN_MESSAGES__MESSAGE_TOO_LONG              => 'Offchain message is too long (%{length} bytes, max %{max})',
         OFFCHAIN_MESSAGES__LEADING_ZERO_IN_SIGNING_DOMAIN => 'Offchain message signing domain must not start with a null byte',
+        OFFCHAIN_MESSAGES__CONTENT_DOES_NOT_MATCH_EXPECTED => 'The content of the offchain message does not match the content that was expected. ' \
+          'Expected content with a byte-length of %{expected_bytes}; got content with a byte-length of %{actual_bytes}. ' \
+          'The signer may have signed different data than was requested; do not trust its signature.',
+        OFFCHAIN_MESSAGES__REQUIRED_SIGNATORIES_DO_NOT_MATCH_EXPECTED => 'The offchain message lists different required signatories than was expected. ' \
+          'Expected [%{expected_addresses}]. Got [%{actual_addresses}]. ' \
+          'The signer may have signed different data than was requested; do not trust its signature.',
 
         # Instruction plans
         INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN    => 'Transaction message cannot accommodate the plan: requires %{num_bytes_required} bytes but only %{num_free_bytes} are available',
@@ -271,6 +282,7 @@ module Solana::Ruby::Kit
 
         # Subscribable
         SUBSCRIBABLE__RETRY_NOT_SUPPORTED              => 'This reactive store does not support retry(); use create_reactive_store_from_data_publisher_factory for a retryable store',
+        SUBSCRIBABLE__STREAM_CLOSED_WITHOUT_ERROR      => 'The stream store closed in an error state but did not report an error.',
 
         # Fixed-points
         FIXED_POINTS__STRICT_MODE_PRECISION_LOSS       => 'Value has more than 9 fractional digits and cannot be represented exactly as a Sol amount',
@@ -300,8 +312,19 @@ module Solana::Ruby::Kit
       @context = T.let(context, T::Hash[Symbol, T.untyped])
 
       template = ERROR_MESSAGES[code] || code.to_s
-      message  = context.empty? ? template : (template % context rescue "#{template} #{context}")
+      message  = context.empty? ? template : (template % display_context(context) rescue "#{template} #{context}")
       super(message)
     end
+
+    private
+
+    # Values used to fill a message template. Array values — lists of addresses, say —
+    # interpolate as a comma-separated list rather than as Ruby's `inspect` output, so
+    # that `[%{expected_addresses}]` reads like the TypeScript original. `#context` is
+    # untouched and still hands back the array itself.
+    sig { params(context: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def display_context(context)
+      context.transform_values { |value| value.is_a?(Array) ? value.join(', ') : value }
+    end
   end
 end

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

@@ -13,11 +13,22 @@ module Solana::Ruby::Kit
     # executing each single transaction message and collecting results.
     #
     # Configuration:
-    #   execute_transaction_message: ->(message) { { transaction:, context: } }
-    #     Called for each SingleTransactionPlan. Must return a hash with:
-    #       :transaction — the signed Transaction
-    #       :context     — optional Hash of extra data (defaults to {})
-    #     Raise a SolanaError to signal failure; remaining plans will be canceled.
+    #   execute_transaction_message: ->(context, message) { context_to_report }
+    #     Called once per SingleTransactionPlan with a fresh, mutable +context+ Hash and
+    #     the transaction message to execute. Store data on +context+ as execution
+    #     progresses, and return the context a successful result should carry. The two
+    #     serve different outcomes: what you *store* reaches a failed or canceled result,
+    #     what you *return* reaches a successful one. On success the returned Hash is
+    #     merged over the stored one, the returned value winning, so anything recorded
+    #     but left out of the return value is still reported.
+    #
+    #     Raise a SolanaError to signal failure; remaining plans will be canceled. The
+    #     context accumulated up to the point of failure is preserved on the resulting
+    #     failed result, which is useful for debugging or building recovery plans.
+    #
+    #     A one-argument callable is still accepted for backwards compatibility with the
+    #     shape this method used to require — `->(message) { { transaction:, context: } }`
+    #     — and is adapted onto the context flow above.
     #
     # The returned executor is a lambda: executor.call(transaction_plan) -> TransactionPlanResult
     #
@@ -77,26 +88,55 @@ module Solana::Ruby::Kit
     end
 
     def executor_traverse_single(plan, execute_fn, state)
-      return canceled_single_transaction_plan_result(plan.message) if state[:canceled]
+      # A fresh context per single transaction plan. Nothing is populated yet — filling
+      # it in is the callback's job, which is what lets a partial context survive an error.
+      context = {}
+      return canceled_single_transaction_plan_result(plan.message, context) if state[:canceled]
 
       begin
-        result      = execute_fn.call(plan.message)
-        transaction = result.fetch(:transaction)
-        context     = result.fetch(:context, {})
-        successful_single_transaction_plan_result(plan.message, transaction, context)
+        returned = executor_invoke(execute_fn, context, plan.message)
+        # The callback told us what the successful result should carry, so take it as-is
+        # and derive nothing from it. Anything it stored but left out of the return value
+        # is kept, since dropping it would lose data it deliberately recorded.
+        successful_single_transaction_plan_result(plan.message, nil, context.merge(returned))
       rescue SolanaError => e
         state[:canceled] = true
-        failed_single_transaction_plan_result(plan.message, e)
+        failed_single_transaction_plan_result(plan.message, e, context)
       rescue => e
         state[:canceled] = true
         wrapped = SolanaError.new(
           SolanaError::INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN,
           { cause: e }
         )
-        failed_single_transaction_plan_result(plan.message, wrapped)
+        failed_single_transaction_plan_result(plan.message, wrapped, context)
       end
     end
 
+    # Calls the configured callback, adapting the legacy one-argument shape onto the
+    # context flow. Returns the Hash the successful result should carry.
+    sig do
+      params(
+        execute_fn: T.untyped,
+        context:    T::Hash[T.untyped, T.untyped],
+        message:    TransactionMessages::TransactionMessage
+      ).returns(T::Hash[T.untyped, T.untyped])
+    end
+    def executor_invoke(execute_fn, context, message)
+      unless execute_fn.arity == 1
+        returned = execute_fn.call(context, message)
+        return returned.is_a?(Hash) ? returned : {}
+      end
+
+      # Legacy shape: `->(message) { { transaction:, context: } }`. There is no mutable
+      # context to record into, so everything it reports arrives at once on the way out.
+      legacy      = execute_fn.call(message)
+      legacy      = {} unless legacy.is_a?(Hash)
+      returned    = legacy.fetch(:context, {}).dup
+      transaction = legacy[:transaction]
+      returned[:transaction] = transaction if transaction
+      returned
+    end
+
     def executor_find_error(result)
       return result.status.error if result.kind == :single && result.status.kind == :failed
       return nil                 if result.kind == :single
@@ -112,6 +152,7 @@ module Solana::Ruby::Kit
     private_class_method :executor_traverse_sequential
     private_class_method :executor_traverse_parallel
     private_class_method :executor_traverse_single
+    private_class_method :executor_invoke
     private_class_method :executor_find_error
   end
 end

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

@@ -13,23 +13,27 @@ module Solana::Ruby::Kit
     #
     # Each single transaction produces one of three statuses:
     #   successful: { kind: :successful, transaction:, context: }
-    #   failed:     { kind: :failed,     error: }
-    #   canceled:   { kind: :canceled }
+    #   failed:     { kind: :failed,     error:, context: }
+    #   canceled:   { kind: :canceled,   context: }
     #
-    # Mirrors TypeScript's TransactionPlanResultStatus union.
+    # Every status carries a context, so whatever the executor callback recorded
+    # before it failed — or before an earlier failure canceled it — survives into
+    # the result. Mirrors TypeScript's TransactionPlanResultStatus union.
 
     class SuccessfulStatus < T::Struct
-      const :transaction, Transactions::Transaction
+      const :transaction, T.nilable(Transactions::Transaction)
       const :context,     T::Hash[T.untyped, T.untyped]
       def kind = :successful
     end
 
     class FailedStatus < T::Struct
-      const :error, SolanaError
+      const :error,   SolanaError
+      const :context, T::Hash[T.untyped, T.untyped], default: {}.freeze
       def kind = :failed
     end
 
     class CanceledStatus < T::Struct
+      const :context, T::Hash[T.untyped, T.untyped], default: {}.freeze
       def kind = :canceled
     end
 
@@ -74,43 +78,55 @@ module Solana::Ruby::Kit
       ParallelTransactionPlanResult.new(plans: plans)
     end
 
-    # Mirrors `successfulSingleTransactionPlanResult(message, transaction, context)`.
+    # Mirrors `successfulSingleTransactionPlanResult(message, context)`.
+    #
+    # Upstream carries the transaction inside the context; Ruby keeps the separate
+    # +transaction+ reader it has always exposed. Pass it either way — as the positional
+    # argument, or under +:transaction+ in the context, where the reader picks it up.
+    # Nothing is written back into the context, which stays exactly what was passed.
     sig do
       params(
         message:     TransactionMessages::TransactionMessage,
-        transaction: Transactions::Transaction,
+        transaction: T.nilable(Transactions::Transaction),
         context:     T::Hash[T.untyped, T.untyped]
       ).returns(SingleTransactionPlanResult)
     end
-    def successful_single_transaction_plan_result(message, transaction, context = {})
+    def successful_single_transaction_plan_result(message, transaction = nil, context = {})
+      from_context = context[:transaction]
+      transaction ||= from_context if from_context.is_a?(Transactions::Transaction)
+
       SingleTransactionPlanResult.new(
         message: message,
-        status:  SuccessfulStatus.new(transaction: transaction, context: context)
+        status:  SuccessfulStatus.new(transaction: transaction, context: context.dup.freeze)
       )
     end
 
-    # Mirrors `failedSingleTransactionPlanResult(message, error)`.
+    # Mirrors `failedSingleTransactionPlanResult(message, error, context)`.
     sig do
       params(
         message: TransactionMessages::TransactionMessage,
-        error:   SolanaError
+        error:   SolanaError,
+        context: T::Hash[T.untyped, T.untyped]
       ).returns(SingleTransactionPlanResult)
     end
-    def failed_single_transaction_plan_result(message, error)
+    def failed_single_transaction_plan_result(message, error, context = {})
       SingleTransactionPlanResult.new(
         message: message,
-        status:  FailedStatus.new(error: error)
+        status:  FailedStatus.new(error: error, context: context.dup.freeze)
       )
     end
 
-    # Mirrors `canceledSingleTransactionPlanResult(message)`.
+    # Mirrors `canceledSingleTransactionPlanResult(message, context)`.
     sig do
-      params(message: TransactionMessages::TransactionMessage).returns(SingleTransactionPlanResult)
+      params(
+        message: TransactionMessages::TransactionMessage,
+        context: T::Hash[T.untyped, T.untyped]
+      ).returns(SingleTransactionPlanResult)
     end
-    def canceled_single_transaction_plan_result(message)
+    def canceled_single_transaction_plan_result(message, context = {})
       SingleTransactionPlanResult.new(
         message: message,
-        status:  CanceledStatus.new
+        status:  CanceledStatus.new(context: context.dup.freeze)
       )
     end
   end

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

@@ -31,8 +31,12 @@ module Solana::Ruby::Kit
         buf << domain_b
         buf << [msg.version].pack('C')
 
-        if msg.version >= 1 && msg.application_domain
-          app_b = T.must(msg.application_domain).encode('ASCII').b
+        # The v1 application-domain block is always emitted, using a zero length when
+        # there is no application domain. The decoder reads this length unconditionally
+        # for v1, so omitting the block would desynchronise it and make it read the
+        # message length as an application-domain length.
+        if msg.version >= 1
+          app_b = msg.application_domain ? T.must(msg.application_domain).encode('ASCII').b : ''.b
           Kernel.raise ArgumentError, 'Application domain exceeds 65535 bytes' if app_b.bytesize > 0xFFFF
 
           buf << [app_b.bytesize].pack('v')
@@ -62,7 +66,9 @@ module Solana::Ruby::Kit
         if version >= 1
           app_len = b.byteslice(offset, 2)&.unpack1('v') || 0
           offset += 2
-          application_domain = b.byteslice(offset, app_len)&.force_encoding('ASCII')
+          # A zero length means there was no application domain, not an empty one, so
+          # that encode/decode round-trips a message that never had one.
+          application_domain = app_len.positive? ? b.byteslice(offset, app_len)&.force_encoding('ASCII') : nil
           offset += app_len
         end
 
@@ -94,12 +100,14 @@ module Solana::Ruby::Kit
         ).returns(T::Boolean)
       end
       def verify_offchain_message_signature(verify_key, signature, msg)
-        payload  = encode_offchain_message(msg)
-        vk       = RbNaCl::VerifyKey.new(verify_key)
-        sig_bytes = signature.respond_to?(:to_bytes) ? signature.to_s : [signature.value].pack('H*')
+        payload = encode_offchain_message(msg)
+        vk      = RbNaCl::VerifyKey.new(verify_key)
+        # `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
+      rescue RbNaCl::BadSignatureError, RbNaCl::LengthError
         false
       end
     end

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

@@ -0,0 +1,115 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../addresses/address'
+
+module Solana::Ruby::Kit
+  module OffchainMessages
+    extend T::Sig
+
+    # An address that is required to sign an offchain message for it to be valid.
+    # Mirrors TypeScript's `OffchainMessageSignatory`.
+    class Signatory < T::Struct
+      const :address, Addresses::Address
+    end
+
+    # A version 1 offchain message.
+    #
+    # Mirrors TypeScript's `OffchainMessageV1` — the shape from the newer
+    # `@solana/offchain-messages` package, whose content is UTF-8 and whose preamble
+    # lists the addresses required to sign it. This is a different type from the
+    # legacy Message in message.rb, which models the older `@solana/signers`
+    # domain/application-domain form; the two are not interchangeable.
+    class MessageV1 < T::Struct
+      # UTF-8 message content.
+      const :content, String
+
+      # Addresses required to sign this message. The offchain message specification
+      # mandates that these be serialized in lexicographic order, so a decoded message
+      # always lists them that way; one you build yourself may list them in any order.
+      const :required_signatories, T::Array[Signatory], default: [].freeze
+
+      extend T::Sig
+
+      sig { returns(Integer) }
+      def version = 1
+    end
+
+    module_function
+
+    # Asserts that a version 1 offchain message received from an untrusted source is the
+    # message it was expected to be.
+    #
+    # A signer (a wallet, say) returns the message bytes it signed alongside its signature.
+    # Verifying that signature proves only that the signer produced it over *those* bytes;
+    # it says nothing about whether those bytes represent the message that was asked for.
+    # Use this to establish that they do, then verify the signature separately.
+    #
+    # Perform this assertion *before* verifying signatures. A signer that signed the wrong
+    # message would otherwise surface as a signature verification failure, misattributing
+    # the problem to the cryptography rather than to the content.
+    #
+    # Required signatories are compared without regard to order — both lists are sorted
+    # first, and reported sorted so they can be compared by eye. Order is the only thing
+    # ignored: the lists are otherwise compared element by element, so listing an address
+    # twice on one side and once on the other is a mismatch rather than a no-op.
+    #
+    # Message content is never placed in the error context, since it can carry data better
+    # kept out of logs and error reporting. Its length in UTF-8 bytes — the encoding in
+    # which version 1 content is serialized — is reported instead.
+    #
+    # Raises SolanaError OFFCHAIN_MESSAGES__CONTENT_DOES_NOT_MATCH_EXPECTED if the two
+    # messages' contents differ, or
+    # OFFCHAIN_MESSAGES__REQUIRED_SIGNATORIES_DO_NOT_MATCH_EXPECTED if they require
+    # signatures from different addresses. Content is checked first, so a message that
+    # differs in both reports the content mismatch.
+    #
+    # Mirrors `assertOffchainMessageV1Equal(receivedMessage, expectedMessage)`.
+    sig { params(received_message: MessageV1, expected_message: MessageV1).void }
+    def assert_offchain_message_v1_equal(received_message, expected_message)
+      if received_message.content != expected_message.content
+        Kernel.raise SolanaError.new(
+          SolanaError::OFFCHAIN_MESSAGES__CONTENT_DOES_NOT_MATCH_EXPECTED,
+          {
+            actual_bytes:   utf8_byte_length(received_message.content),
+            expected_bytes: utf8_byte_length(expected_message.content)
+          }
+        )
+      end
+
+      actual_addresses   = sorted_signatory_addresses(received_message)
+      expected_addresses = sorted_signatory_addresses(expected_message)
+      return if actual_addresses == expected_addresses
+
+      Kernel.raise SolanaError.new(
+        SolanaError::OFFCHAIN_MESSAGES__REQUIRED_SIGNATORIES_DO_NOT_MATCH_EXPECTED,
+        {
+          actual_addresses:   actual_addresses.map(&:to_s),
+          expected_addresses: expected_addresses.map(&:to_s)
+        }
+      )
+    end
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    sig { params(message: MessageV1).returns(T::Array[Addresses::Address]) }
+    def sorted_signatory_addresses(message)
+      message.required_signatories.map(&:address).sort
+    end
+
+    # Length of a string in UTF-8 bytes, which is how version 1 content is serialized.
+    # Ruby strings carry their own encoding, so one that arrived as anything else is
+    # converted first rather than having its raw bytes counted.
+    #
+    # NOTE: `::Encoding` must be spelled with the leading `::`. Bare `Encoding` resolves
+    # to Solana::Ruby::Kit::Encoding — this gem's own base58 namespace — not Ruby's.
+    sig { params(content: String).returns(Integer) }
+    def utf8_byte_length(content)
+      content.encoding == ::Encoding::UTF_8 ? content.bytesize : content.encode(::Encoding::UTF_8).bytesize
+    end
+
+    private_class_method :sorted_signatory_addresses
+    private_class_method :utf8_byte_length
+  end
+end

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

@@ -3,14 +3,41 @@
 
 require 'rbnacl'
 
-# Mirrors @solana/signers off-chain message signing.
+# Mirrors @solana/signers off-chain message signing, plus the version 1 message
+# comparison helper from @solana/offchain-messages.
 require_relative 'offchain_messages/message'
+require_relative 'offchain_messages/message_v1'
 require_relative 'offchain_messages/codec'
 
 module Solana::Ruby::Kit
   module OffchainMessages
-    # Re-export codec helpers at module level for convenience.
     extend T::Sig
-    extend Codec
+
+    # Re-export codec helpers at module level for convenience.
+    #
+    # NOTE: `extend Codec` does not work here. Codec declares its helpers with
+    # `module_function`, which makes the instance-method copies private, and `extend`
+    # only imports public instance methods — so it would silently import nothing.
+    # Delegate to Codec's module methods explicitly instead.
+
+    sig { params(msg: Message).returns(String) }
+    def self.encode_offchain_message(msg) = Codec.encode_offchain_message(msg)
+
+    sig { params(bytes: String).returns(Message) }
+    def self.decode_offchain_message(bytes) = Codec.decode_offchain_message(bytes)
+
+    sig { params(signer: Signers::KeyPairSigner, msg: Message).returns(Keys::Signature) }
+    def self.sign_offchain_message(signer, msg) = Codec.sign_offchain_message(signer, msg)
+
+    sig do
+      params(
+        verify_key: String,
+        signature:  Keys::Signature,
+        msg:        Message
+      ).returns(T::Boolean)
+    end
+    def self.verify_offchain_message_signature(verify_key, signature, msg)
+      Codec.verify_offchain_message_signature(verify_key, signature, msg)
+    end
   end
 end

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

@@ -9,7 +9,9 @@ module Solana::Ruby::Kit
       InflationReward = T.let(
         Struct.new(
           :amount,         # Integer (Lamports) — reward credited
-          :commission,     # Integer — vote account commission at reward time
+          :commission,     # Integer, nilable — vote account commission at reward time;
+                           #   null once the vote account reports commission through
+                           #   getVoteAccounts' inflationRewardsCommissionBps instead
           :effective_slot, # Integer — slot in which rewards were delivered
           :epoch,          # Integer — epoch for which reward occurred
           :post_balance,   # Integer (Lamports) — post-reward account balance
@@ -46,7 +48,7 @@ module Solana::Ruby::Kit
 
             InflationReward.new(
               amount:         Kernel.Integer(entry['amount']),
-              commission:     Kernel.Integer(entry['commission']),
+              commission:     entry['commission'] ? Kernel.Integer(entry['commission']) : nil,
               effective_slot: Kernel.Integer(entry['effectiveSlot']),
               epoch:          Kernel.Integer(entry['epoch']),
               post_balance:   Kernel.Integer(entry['postBalance'])