solana-ruby-kit 0.1.0

data/lib/solana/ruby/kit/subscribable/data_publisher.rb

@@ -0,0 +1,90 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Subscribable
+    # Thread-safe pub/sub hub — mirrors @solana/subscribable DataPublisher.
+    #
+    # Channels are arbitrary symbols/strings.  Subscribers are blocks called
+    # synchronously from #publish (in the calling thread).  An optional
+    # +signal+ lambda is checked before each dispatch; if it raises the
+    # subscriber is automatically removed.
+    #
+    # Returns an unsubscribe lambda from #on.
+    class DataPublisher
+      extend T::Sig
+
+      ERROR_CHANNEL = T.let(:error, Symbol)
+      CLOSE_CHANNEL = T.let(:close, Symbol)
+
+      sig { void }
+      def initialize
+        # channel_name → [[subscriber_proc, signal_lambda_or_nil], ...]
+        @subscribers = T.let(
+          Hash.new { |h, k| h[k] = [] },
+          T::Hash[T.untyped, T::Array[[T.proc.params(data: T.untyped).void, T.nilable(T.proc.void)]]]
+        )
+        @mutex  = T.let(Mutex.new, Mutex)
+        @closed = T.let(false, T::Boolean)
+      end
+
+      # Register +block+ as a subscriber on +channel_name+.
+      # +signal+ is an optional lambda that is called before each dispatch;
+      # if it raises (e.g. a Timeout::Error or custom AbortError) the
+      # subscription is removed automatically.
+      # Returns a lambda that removes the subscription when called.
+      sig do
+        params(
+          channel_name: T.untyped,
+          signal:       T.nilable(T.proc.void),
+          block:        T.proc.params(data: T.untyped).void
+        ).returns(T.proc.void)
+      end
+      def on(channel_name, signal: nil, &block)
+        entry = [block, signal]
+        @mutex.synchronize { T.must(@subscribers[channel_name]) << entry }
+
+        # Return unsubscribe lambda
+        lambda do
+          @mutex.synchronize { T.must(@subscribers[channel_name]).delete(entry) }
+        end
+      end
+
+      # Deliver +data+ to all subscribers on +channel_name+.
+      # Subscribers whose signal has fired are pruned automatically.
+      sig { params(channel_name: T.untyped, data: T.untyped).void }
+      def publish(channel_name, data)
+        entries = @mutex.synchronize { (@subscribers[channel_name] || []).dup }
+        entries.each do |subscriber, signal|
+          begin
+            signal&.call
+          rescue StandardError
+            # Signal fired — remove this subscriber and skip dispatch
+            @mutex.synchronize { T.must(@subscribers[channel_name]).delete([subscriber, signal]) }
+            next
+          end
+          begin
+            subscriber.call(data)
+          rescue StandardError => e
+            # Dispatch errors are re-published on the error channel (not raised)
+            publish(ERROR_CHANNEL, e) unless channel_name == ERROR_CHANNEL
+          end
+        end
+      end
+
+      # Close the publisher: emit a final event on the close channel and remove
+      # all subscribers.
+      sig { void }
+      def close
+        publish(CLOSE_CHANNEL, nil)
+        @mutex.synchronize do
+          @subscribers.clear
+          @closed = true
+        end
+      end
+
+      sig { returns(T::Boolean) }
+      def closed? = @closed
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'timeout'
+
+# Mirrors @solana/subscribable.
+require_relative 'subscribable/data_publisher'
+require_relative 'subscribable/async_iterable'
+
+module Solana::Ruby::Kit
+  module Subscribable
+  end
+end

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

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Sysvars
+    # Well-known on-chain addresses for all Solana sysvar accounts.
+    SYSVAR_CLOCK_ADDRESS                 = T.let('SysvarC1ock11111111111111111111111111111111', String)
+    SYSVAR_RENT_ADDRESS                  = T.let('SysvarRent111111111111111111111111111111111', String)
+    SYSVAR_EPOCH_SCHEDULE_ADDRESS        = T.let('SysvarEpochSchedu1e111111111111111111111111', String)
+    SYSVAR_FEES_ADDRESS                  = T.let('SysvarFees111111111111111111111111111111111', String)
+    SYSVAR_RECENT_BLOCKHASHES_ADDRESS    = T.let('SysvarRecentB1ockHashes11111111111111111111', String)
+    SYSVAR_SLOT_HASHES_ADDRESS           = T.let('SysvarS1otHashes111111111111111111111111111', String)
+    SYSVAR_SLOT_HISTORY_ADDRESS          = T.let('SysvarS1otHistory11111111111111111111111111', String)
+    SYSVAR_STAKE_HISTORY_ADDRESS         = T.let('SysvarStakeHistory1111111111111111111111111', String)
+    SYSVAR_INSTRUCTIONS_ADDRESS          = T.let('Sysvar1nstructions1111111111111111111111111', String)
+    SYSVAR_LAST_RESTART_SLOT_ADDRESS     = T.let('SysvarLastRestartS1ot1111111111111111111111', String)
+    SYSVAR_EPOCH_REWARDS_ADDRESS         = T.let('SysvarEpochRewards1111111111111111111111111', String)
+  end
+end

data/lib/solana/ruby/kit/sysvars/clock.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+
+module Solana::Ruby::Kit
+  module Sysvars
+    # Clock sysvar — 40 bytes little-endian layout:
+    #   slot(u64) + epoch_start_timestamp(i64) + epoch(u64) + leader_schedule_epoch(u64) + unix_timestamp(i64)
+    class SysvarClock < T::Struct
+      const :slot,                   Integer
+      const :epoch_start_timestamp,  Integer   # Unix seconds (i64)
+      const :epoch,                  Integer
+      const :leader_schedule_epoch,  Integer
+      const :unix_timestamp,         Integer   # Unix seconds (i64)
+    end
+
+    CLOCK_SIZE = T.let(40, Integer)
+
+    module_function
+
+    sig { params(rpc: Rpc::Client).returns(SysvarClock) }
+    def fetch_sysvar_clock(rpc)
+      res  = rpc.get_account_info(SYSVAR_CLOCK_ADDRESS, encoding: 'base64')
+      data = _decode_account_data(res)
+
+      unpacked = T.cast(T.unsafe(data).unpack('Q<q<Q<Q<q<'), T::Array[Integer])
+      SysvarClock.new(
+        slot:                  T.must(unpacked[0]),
+        epoch_start_timestamp: T.must(unpacked[1]),
+        epoch:                 T.must(unpacked[2]),
+        leader_schedule_epoch: T.must(unpacked[3]),
+        unix_timestamp:        T.must(unpacked[4])
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/sysvars/epoch_schedule.rb

@@ -0,0 +1,34 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Sysvars
+    # EpochSchedule sysvar — 33 bytes:
+    #   slots_per_epoch(u64) + leader_schedule_slot_offset(u64)
+    #   + warmup(bool/u8) + first_normal_epoch(u64) + first_normal_slot(u64)
+    class SysvarEpochSchedule < T::Struct
+      const :slots_per_epoch,              Integer
+      const :leader_schedule_slot_offset,  Integer
+      const :warmup,                       T::Boolean
+      const :first_normal_epoch,           Integer
+      const :first_normal_slot,            Integer
+    end
+
+    module_function
+
+    sig { params(rpc: Rpc::Client).returns(SysvarEpochSchedule) }
+    def fetch_sysvar_epoch_schedule(rpc)
+      res  = rpc.get_account_info(SYSVAR_EPOCH_SCHEDULE_ADDRESS, encoding: 'base64')
+      data = _decode_account_data(res)
+
+      unpacked = T.unsafe(data).unpack('Q<Q<CQ<Q<')
+      SysvarEpochSchedule.new(
+        slots_per_epoch:             unpacked[0],
+        leader_schedule_slot_offset: unpacked[1],
+        warmup:                      unpacked[2] == 1,
+        first_normal_epoch:          unpacked[3],
+        first_normal_slot:           unpacked[4]
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/sysvars/last_restart_slot.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Sysvars
+    # LastRestartSlot sysvar — 8 bytes: last_restart_slot(u64 LE)
+    class SysvarLastRestartSlot < T::Struct
+      const :last_restart_slot, Integer
+    end
+
+    module_function
+
+    sig { params(rpc: Rpc::Client).returns(SysvarLastRestartSlot) }
+    def fetch_sysvar_last_restart_slot(rpc)
+      res  = rpc.get_account_info(SYSVAR_LAST_RESTART_SLOT_ADDRESS, encoding: 'base64')
+      data = _decode_account_data(res)
+
+      slot = data.unpack1('Q<')
+      SysvarLastRestartSlot.new(last_restart_slot: slot)
+    end
+  end
+end

data/lib/solana/ruby/kit/sysvars/rent.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Sysvars
+    # Rent sysvar — 17 bytes:
+    #   lamports_per_byte_year(u64) + exemption_threshold(f64) + burn_percent(u8)
+    class SysvarRent < T::Struct
+      const :lamports_per_byte_year, Integer
+      const :exemption_threshold,    Float
+      const :burn_percent,           Integer
+    end
+
+    module_function
+
+    sig { params(rpc: Rpc::Client).returns(SysvarRent) }
+    def fetch_sysvar_rent(rpc)
+      res  = rpc.get_account_info(SYSVAR_RENT_ADDRESS, encoding: 'base64')
+      data = _decode_account_data(res)
+
+      unpacked = T.unsafe(data).unpack('Q<EC')
+      SysvarRent.new(
+        lamports_per_byte_year: unpacked[0],
+        exemption_threshold:    unpacked[1],
+        burn_percent:           unpacked[2]
+      )
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+
+# Mirrors @solana/sysvars.
+# Provides addresses and fetch helpers for Solana sysvar accounts.
+
+# Set up the module (extend T::Sig) before requiring sub-files that use `sig`.
+module Solana::Ruby::Kit
+  module Sysvars
+    extend T::Sig
+
+    module_function
+
+    # Decode base64 account data from an RpcContextualValue returned by
+    # get_account_info(encoding: 'base64').
+    sig { params(res: RpcTypes::RpcContextualValue).returns(String) }
+    def _decode_account_data(res)
+      info = res.value
+      Kernel.raise ArgumentError, 'Account not found' if info.nil?
+
+      raw = T.cast(info, RpcTypes::AccountInfoWithBase64Data)
+      Base64.decode64(raw.data.first.to_s).b
+    end
+  end
+end
+
+require_relative 'sysvars/addresses'
+require_relative 'sysvars/clock'
+require_relative 'sysvars/rent'
+require_relative 'sysvars/epoch_schedule'
+require_relative 'sysvars/last_restart_slot'

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

@@ -0,0 +1,159 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'timeout'
+
+# Mirrors @solana/transaction-confirmation.
+# Provides synchronous polling strategies that wait for a transaction to reach
+# a desired commitment level.
+module Solana::Ruby::Kit
+  module TransactionConfirmation
+    extend T::Sig
+
+    module_function
+
+    # Poll getSignatureStatuses until +signature+ reaches +commitment+ or
+    # the blockheight/timeout deadline is exceeded.
+    #
+    # @param rpc          [Rpc::Client]
+    # @param signature    [Keys::Signature, String]
+    # @param commitment   [:processed, :confirmed, :finalized]
+    # @param timeout_secs [Integer]
+    # @param poll_interval [Float]
+    # @return [Rpc::Api::SignatureStatus]
+    # @raise [Timeout::Error] if the deadline is reached
+    # @raise [Solana::Ruby::Kit::SolanaError] if the transaction failed
+    sig do
+      params(
+        rpc:           Rpc::Client,
+        signature:     T.any(Keys::Signature, String),
+        commitment:    Symbol,
+        timeout_secs:  Integer,
+        poll_interval: Float
+      ).returns(T.untyped) # Rpc::Api::SignatureStatus
+    end
+    def wait_for_confirmation(
+      rpc,
+      signature,
+      commitment:    :confirmed,
+      timeout_secs:  30,
+      poll_interval: 0.5
+    )
+      sig_str    = signature.respond_to?(:value) ? T.cast(signature, Keys::Signature).value : signature.to_s
+      commitment_order = %i[processed confirmed finalized]
+      min_order  = commitment_order.index(commitment) || 1
+
+      Timeout.timeout(timeout_secs) do
+        Kernel.loop do
+          res    = rpc.get_signature_statuses([sig_str], search_transaction_history: false)
+          status = res.value.first
+          next Kernel.sleep(poll_interval) if status.nil?
+
+          err = status.respond_to?(:err) ? status.err : status[:err]
+          Kernel.raise SolanaError.new(SolanaError::TRANSACTIONS__FAILED_TRANSACTION_PLAN, err: err.inspect) if err
+
+          current_commitment = status.respond_to?(:confirmation_status) ? status.confirmation_status : status[:confirmation_status]
+          current_order      = commitment_order.index(current_commitment) || 0
+
+          return status if current_order >= min_order
+
+          Kernel.sleep(poll_interval)
+        end
+      end
+    end
+
+    # Wait until the transaction is confirmed or the blockhash lifetime expires
+    # (i.e. the current block height exceeds +last_valid_block_height+).
+    sig do
+      params(
+        rpc:                    Rpc::Client,
+        signature:              T.any(Keys::Signature, String),
+        last_valid_block_height: Integer,
+        commitment:             Symbol,
+        poll_interval:          Float
+      ).returns(T.untyped)
+    end
+    def wait_for_blockheight_lifetime(
+      rpc,
+      signature,
+      last_valid_block_height:,
+      commitment:    :confirmed,
+      poll_interval: 0.5
+    )
+      sig_str = signature.respond_to?(:value) ? T.cast(signature, Keys::Signature).value : signature.to_s
+      commitment_order = %i[processed confirmed finalized]
+      min_order        = commitment_order.index(commitment) || 1
+
+      Kernel.loop do
+        # Check if blockheight has been exceeded
+        current_height = rpc.get_block_height
+        Kernel.raise Timeout::Error, 'Transaction lifetime expired (blockheight)' if current_height > last_valid_block_height
+
+        res    = rpc.get_signature_statuses([sig_str], search_transaction_history: false)
+        status = res.value.first
+        next Kernel.sleep(poll_interval) if status.nil?
+
+        err = status.respond_to?(:err) ? status.err : status[:err]
+        Kernel.raise SolanaError.new(SolanaError::TRANSACTIONS__FAILED_TRANSACTION_PLAN, err: err.inspect) if err
+
+        current_commitment = status.respond_to?(:confirmation_status) ? status.confirmation_status : status[:confirmation_status]
+        current_order      = commitment_order.index(current_commitment) || 0
+
+        return status if current_order >= min_order
+
+        Kernel.sleep(poll_interval)
+      end
+    end
+
+    # Wait for confirmation using a durable nonce strategy.
+    # The transaction is considered expired once the nonce account's blockhash
+    # changes (indicating the nonce was advanced by someone else or the TX landed).
+    sig do
+      params(
+        rpc:           Rpc::Client,
+        signature:     T.any(Keys::Signature, String),
+        nonce_account: String,
+        nonce:         String,
+        commitment:    Symbol,
+        timeout_secs:  Integer,
+        poll_interval: Float
+      ).returns(T.untyped)
+    end
+    def wait_for_nonce_invalidation(
+      rpc,
+      signature,
+      nonce_account:,
+      nonce:,
+      commitment:    :confirmed,
+      timeout_secs:  120,
+      poll_interval: 1.0
+    )
+      sig_str          = signature.respond_to?(:value) ? T.cast(signature, Keys::Signature).value : signature.to_s
+      commitment_order = %i[processed confirmed finalized]
+      min_order        = commitment_order.index(commitment) || 1
+
+      Timeout.timeout(timeout_secs) do
+        Kernel.loop do
+          # First check if transaction already confirmed
+          res    = rpc.get_signature_statuses([sig_str], search_transaction_history: false)
+          status = res.value.first
+          unless status.nil?
+            err = status.respond_to?(:err) ? status.err : status[:err]
+            Kernel.raise SolanaError.new(SolanaError::TRANSACTIONS__FAILED_TRANSACTION_PLAN, err: err.inspect) if err
+
+            current_commitment = status.respond_to?(:confirmation_status) ? status.confirmation_status : status[:confirmation_status]
+            current_order      = commitment_order.index(current_commitment) || 0
+            return status if current_order >= min_order
+          end
+
+          # Check if nonce has advanced (transaction expired without confirming)
+          nonce_res = rpc.get_account_info(nonce_account, encoding: 'jsonParsed')
+          current_nonce_hash = nonce_res.value&.respond_to?(:data) ? nonce_res.value.data&.dig('parsed', 'info', 'blockhash') : nil
+          Kernel.raise Timeout::Error, 'Nonce advanced — transaction expired' if current_nonce_hash && current_nonce_hash != nonce
+
+          Kernel.sleep(poll_interval)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../errors'
+require_relative '../instructions/instruction'
+
+module Solana::Ruby::Kit
+  module TransactionMessages
+    extend T::Sig
+    # Supported transaction versions.
+    # Mirrors TypeScript's `TransactionVersion = 'legacy' | 0 | 1`.
+    # Version 1 is defined but not yet supported by most tooling.
+    TransactionVersion = T.type_alias { T.any(Symbol, Integer) }
+
+    LEGACY_VERSION = T.let(:legacy, Symbol)
+    V0_VERSION     = T.let(0, Integer)
+    V1_VERSION     = T.let(1, Integer)
+
+    MAX_SUPPORTED_TRANSACTION_VERSION = T.let(1, Integer)
+
+    # A blockhash-based lifetime constraint.
+    # Mirrors TypeScript's `BlockhashLifetimeConstraint`.
+    class BlockhashLifetimeConstraint < T::Struct
+      # A recent blockhash string (base58-encoded 32 bytes).
+      const :blockhash,              String
+      # Block height after which the blockhash is considered expired.
+      # TypeScript uses bigint; Ruby uses Integer.
+      const :last_valid_block_height, Integer
+    end
+
+    # A durable-nonce lifetime constraint.
+    # Mirrors TypeScript's `DurableNonceTransactionMessageLifetimeConstraint`.
+    class DurableNonceLifetimeConstraint < T::Struct
+      const :nonce,               String             # base58 nonce value
+      const :nonce_account_address, Addresses::Address
+    end
+
+    # Lifetime can be a blockhash constraint, a durable-nonce constraint, or nil.
+    Lifetime = T.type_alias { T.nilable(T.any(BlockhashLifetimeConstraint, DurableNonceLifetimeConstraint)) }
+
+    # The core transaction message structure.
+    # Mirrors TypeScript's `TransactionMessage` (legacy | V0).
+    #
+    # TypeScript uses compile-time type narrowing to differentiate versions;
+    # Ruby uses the `version` field at runtime.
+    class TransactionMessage < T::Struct
+      # :legacy or 0 (V1 reserved)
+      const :version,             T.untyped  # Symbol or Integer
+      # Ordered list of instructions.
+      const :instructions,        T::Array[Instructions::Instruction]
+      # The account that pays the transaction fee (nil on a freshly created message).
+      const :fee_payer,           T.nilable(Addresses::Address)
+      # Lifetime constraint (nil until explicitly set).
+      const :lifetime_constraint, Lifetime
+      # V0 only: lookup table addresses mapped to the accounts they hold.
+      const :address_table_lookups, T.nilable(T::Hash[String, T::Array[Integer]])
+    end
+
+    module_function
+
+    # Creates an empty transaction message at the given version.
+    # Mirrors `createTransactionMessage({ version })`.
+    sig { params(version: T.untyped).returns(TransactionMessage) }
+    def create_transaction_message(version:)
+      TransactionMessage.new(
+        version:               version,
+        instructions:          [],
+        fee_payer:             nil,
+        lifetime_constraint:   nil,
+        address_table_lookups: nil
+      )
+    end
+
+    # Sets the fee payer on a transaction message.
+    # Mirrors `setTransactionMessageFeePayer(feePayer, transactionMessage)`.
+    sig { params(fee_payer: Addresses::Address, message: TransactionMessage).returns(TransactionMessage) }
+    def set_fee_payer(fee_payer, message)
+      return message if message.fee_payer == fee_payer
+
+      TransactionMessage.new(
+        version:               message.version,
+        instructions:          message.instructions,
+        fee_payer:             fee_payer,
+        lifetime_constraint:   message.lifetime_constraint,
+        address_table_lookups: message.address_table_lookups
+      )
+    end
+
+    # Sets a blockhash-based lifetime constraint on a transaction message.
+    # Mirrors `setTransactionMessageLifetimeUsingBlockhash(constraint, message)`.
+    sig { params(constraint: BlockhashLifetimeConstraint, message: TransactionMessage).returns(TransactionMessage) }
+    def set_blockhash_lifetime(constraint, message)
+      existing = message.lifetime_constraint
+      if existing.is_a?(BlockhashLifetimeConstraint) &&
+         existing.blockhash == constraint.blockhash &&
+         existing.last_valid_block_height == constraint.last_valid_block_height
+        return message
+      end
+
+      TransactionMessage.new(
+        version:               message.version,
+        instructions:          message.instructions,
+        fee_payer:             message.fee_payer,
+        lifetime_constraint:   constraint,
+        address_table_lookups: message.address_table_lookups
+      )
+    end
+
+    # Sets a durable-nonce lifetime constraint on a transaction message.
+    # Mirrors `setTransactionMessageLifetimeUsingDurableNonce(constraint, message)`.
+    sig { params(constraint: DurableNonceLifetimeConstraint, message: TransactionMessage).returns(TransactionMessage) }
+    def set_durable_nonce_lifetime(constraint, message)
+      TransactionMessage.new(
+        version:               message.version,
+        instructions:          message.instructions,
+        fee_payer:             message.fee_payer,
+        lifetime_constraint:   constraint,
+        address_table_lookups: message.address_table_lookups
+      )
+    end
+
+    # Appends one or more instructions to a transaction message.
+    # Mirrors `appendTransactionMessageInstruction(instruction, message)` and
+    # `appendTransactionMessageInstructions(instructions, message)`.
+    sig { params(message: TransactionMessage, instructions: T::Array[Instructions::Instruction]).returns(TransactionMessage) }
+    def append_instructions(message, instructions)
+      TransactionMessage.new(
+        version:               message.version,
+        instructions:          message.instructions + instructions,
+        fee_payer:             message.fee_payer,
+        lifetime_constraint:   message.lifetime_constraint,
+        address_table_lookups: message.address_table_lookups
+      )
+    end
+
+    # Prepends one or more instructions to a transaction message.
+    # Mirrors `prependTransactionMessageInstruction(instruction, message)`.
+    sig { params(message: TransactionMessage, instructions: T::Array[Instructions::Instruction]).returns(TransactionMessage) }
+    def prepend_instructions(message, instructions)
+      TransactionMessage.new(
+        version:               message.version,
+        instructions:          instructions + message.instructions,
+        fee_payer:             message.fee_payer,
+        lifetime_constraint:   message.lifetime_constraint,
+        address_table_lookups: message.address_table_lookups
+      )
+    end
+
+    # Returns true if the message has a blockhash-based lifetime.
+    sig { params(message: TransactionMessage).returns(T::Boolean) }
+    def blockhash_lifetime?(message)
+      message.lifetime_constraint.is_a?(BlockhashLifetimeConstraint)
+    end
+
+    # Returns true if the message has a durable-nonce lifetime.
+    sig { params(message: TransactionMessage).returns(T::Boolean) }
+    def durable_nonce_lifetime?(message)
+      message.lifetime_constraint.is_a?(DurableNonceLifetimeConstraint)
+    end
+
+    # Raises SolanaError unless the message has a blockhash lifetime.
+    sig { params(message: TransactionMessage).void }
+    def assert_blockhash_lifetime!(message)
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__TRANSACTION__EXPECTED_BLOCKHASH_LIFETIME) unless blockhash_lifetime?(message)
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Transaction message construction utilities — mirrors @solana/transaction-messages.
+require_relative 'transaction_messages/transaction_message'