solana-ruby-kit 0.1.9 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d26df33c1471059cde38ac46ec2604e0c26ffc8d64c580de4171396516530fd
-  data.tar.gz: dba1b05e818b10e8fa7692f6ae4af89c3946bcd19707be52cfdfd1c503e81b63
+  metadata.gz: 7b2766067cfcd434e5c657e1fde1dab4b44b23880e0f514f924d28a94ea0ca4a
+  data.tar.gz: 32814612b342df38df079aaba08b8ea17c9128ac9f54279ab3abad622ba02492
 SHA512:
-  metadata.gz: 56674f680f3059cd3247591fe2a14f303853b8806e251f4c147de90fb4ff7ebcea498394a2650aab40089d3cb5e52b10686cd3c5797e171c230a21ef05602eb3
-  data.tar.gz: b57dd91be86b034b1a207c809a04c38ca045700f608e4481ac125536d546f21f68e796f01930259a5054ea5ecf72f020f9260d4b63f6661dd177525c32ab924d
+  metadata.gz: 3bcfbd20e6f610a47053cb385511931004590646ff04e0edf4587e5699df3db8bb148af2b706cf025e8399f26e4736ae9db35ebfd04d68be287df8302bc9f4de
+  data.tar.gz: d40b332b7cc427730b17b01a091c53815c596c0ac114bca93f52bed4d35775cd2b57ca5146893e2c94d46cebcbe0f51ccf98d2c6e2cad308cd51c2ff7b022d62

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

@@ -56,6 +56,10 @@ module Solana::Ruby::Kit
     TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS
     TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING
     TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND = :SOLANA_ERROR__TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND
+    # context: { index: }
+    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
     TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE     = :SOLANA_ERROR__TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE
     TRANSACTIONS__BLOCKHASH_NOT_FOUND                    = :SOLANA_ERROR__TRANSACTIONS__BLOCKHASH_NOT_FOUND
     TRANSACTIONS__FAILED_TRANSACTION_PLAN                = :SOLANA_ERROR__TRANSACTIONS__FAILED_TRANSACTION_PLAN
@@ -118,6 +122,16 @@ module Solana::Ruby::Kit
     INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE      = :SOLANA_ERROR__INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE
     INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN               = :SOLANA_ERROR__INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN
     INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN   = :SOLANA_ERROR__INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN
+    # context: { max_instructions:, transaction_instruction_limit: }
+    INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION = :SOLANA_ERROR__INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION
+    # context: { max_instructions:, num_instructions: }
+    INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED = :SOLANA_ERROR__INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED
+
+    # ── Transaction introspection ────────────────────────────────────────────
+    TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION
+    TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE
+    # context: { needed_bytes: }
+    TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE = :SOLANA_ERROR__TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE
 
     # ── Wallet Standard ───────────────────────────────────────────────────────
     WALLET_STANDARD__INVALID_WIRE_FORMAT             = :SOLANA_ERROR__WALLET_STANDARD__INVALID_WIRE_FORMAT
@@ -184,7 +198,9 @@ module Solana::Ruby::Kit
         TRANSACTIONS__VERSION_NUMBER_OUT_OF_RANGE        => 'Transaction version %{version} is out of range',
         TRANSACTIONS__FAILED_TO_DECOMPILE_ADDRESS_LOOKUP_TABLE_CONTENTS => 'Failed to decompile address lookup table contents',
         TRANSACTIONS__FAILED_TO_DECOMPILE_FEE_PAYER_MISSING => 'Failed to decompile transaction: fee payer is missing',
-        TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND => 'Failed to decompile instruction: program address not found',
+        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',
         TRANSACTIONS__SEND_TRANSACTION_PREFLIGHT_FAILURE => 'Transaction simulation failed: %{message}',
         TRANSACTIONS__BLOCKHASH_NOT_FOUND                => 'Blockhash not found',
         TRANSACTIONS__FAILED_TRANSACTION_PLAN            => 'Failed to execute transaction plan',
@@ -245,6 +261,13 @@ module Solana::Ruby::Kit
         INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE    => 'Message packer is already complete; no more instructions to pack',
         INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN             => 'Instruction plan is empty and produced no transaction messages',
         INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN => 'Failed to execute transaction plan',
+        INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION => 'The configured maximum of %{max_instructions} instructions per transaction is invalid. It must be a positive integer no greater than the transaction format limit of %{transaction_instruction_limit} instructions per transaction.',
+        INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED => 'Planning this transaction message would require %{num_instructions} instructions, which exceeds the configured maximum of %{max_instructions} instructions per transaction.',
+
+        # Transaction introspection
+        TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION => "Cannot decode a 'jsonParsed'-encoded getTransaction response; its instructions are pre-parsed and lack raw bytes. Fetch with encoding: 'json' or 'base64' instead.",
+        TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE => 'Unrecognized getTransaction response shape; expected a base64, base58, or json-encoded transaction.',
+        TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE => 'Malformed compiled transaction message: expected at least %{needed_bytes} byte(s)',
 
         # Subscribable
         SUBSCRIBABLE__RETRY_NOT_SUPPORTED              => 'This reactive store does not support retry(); use create_reactive_store_from_data_publisher_factory for a retryable store',

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

@@ -5,6 +5,7 @@ require_relative '../errors'
 require_relative '../instructions/instruction'
 require_relative '../transaction_messages/transaction_message'
 require_relative '../transactions/compiler'
+require_relative 'max_instructions'
 
 module Solana::Ruby::Kit
   module InstructionPlans
@@ -68,9 +69,17 @@ module Solana::Ruby::Kit
       # Packs as many instructions as possible into +message+ and returns the
       # updated message. Raises SolanaError if the message is too small or the
       # packer is already done.
-      sig { params(message: TransactionMessages::TransactionMessage).returns(TransactionMessages::TransactionMessage) }
-      def pack_message_to_capacity(message)
-        @pack_proc.call(message)
+      #
+      # +max_instructions+ caps the number of top-level instructions allowed in the
+      # returned message (defaults to 16; must be a positive integer no greater than 64).
+      sig do
+        params(
+          message:          TransactionMessages::TransactionMessage,
+          max_instructions: T.nilable(Integer)
+        ).returns(TransactionMessages::TransactionMessage)
+      end
+      def pack_message_to_capacity(message, max_instructions: nil)
+        @pack_proc.call(message, max_instructions)
       end
     end
 
@@ -122,11 +131,15 @@ module Solana::Ruby::Kit
           offset = T.let(0, Integer)
           MessagePacker.new(
             done_proc: -> { offset >= total_length },
-            pack_proc:  ->(message) {
+            pack_proc:  ->(message, max_instructions) {
               if offset >= total_length
                 Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE)
               end
 
+              InstructionPlans.assert_valid_max_instructions_per_transaction(max_instructions)
+              resolved_max = InstructionPlans.resolve_max_instructions(max_instructions)
+              InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, resolved_max)
+
               base_ix    = get_instruction.call(offset, 0)
               with_base  = TransactionMessages.append_instructions(message, [base_ix])
               base_size  = Transactions.get_transaction_message_size(with_base)
@@ -164,18 +177,30 @@ module Solana::Ruby::Kit
           idx = T.let(0, Integer)
           MessagePacker.new(
             done_proc: -> { idx >= instructions.length },
-            pack_proc:  ->(message) {
+            pack_proc:  ->(message, max_instructions) {
               if idx >= instructions.length
                 Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__MESSAGE_PACKER_ALREADY_COMPLETE)
               end
 
+              InstructionPlans.assert_valid_max_instructions_per_transaction(max_instructions)
+              resolved_max = InstructionPlans.resolve_max_instructions(max_instructions)
+              InstructionPlans.assert_max_instructions_per_transaction(message.instructions.length + 1, resolved_max)
+
               original_size = Transactions.get_transaction_message_size(message)
               packed        = T.let(message, TransactionMessages::TransactionMessage)
               start_idx     = idx
 
               (idx...instructions.length).each do |i|
-                packed = TransactionMessages.append_instructions(packed, [instructions[i]])
-                size   = Transactions.get_transaction_message_size(packed)
+                # Stop once the message is full, before compiling a message that would exceed
+                # the instruction limit (which would raise). The assertion above guarantees at
+                # least the first instruction fits, so reaching the limit here is a graceful stop.
+                if packed.instructions.length >= resolved_max
+                  idx = i
+                  return packed
+                end
+
+                next_packed = TransactionMessages.append_instructions(packed, [instructions[i]])
+                size        = Transactions.get_transaction_message_size(next_packed)
 
                 if size > Transactions::TRANSACTION_SIZE_LIMIT
                   if i == start_idx
@@ -190,6 +215,8 @@ module Solana::Ruby::Kit
                   idx = i
                   return packed
                 end
+
+                packed = next_packed
               end
 
               idx = instructions.length

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

@@ -0,0 +1,59 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module InstructionPlans
+    extend T::Sig
+
+    # The default maximum number of top-level instructions per planned transaction message.
+    #
+    # Intentionally lower than the transaction format's instruction limit to leave headroom
+    # for inner instructions (CPIs), which are not visible at planning time.
+    DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION = T.let(16, Integer)
+
+    # The hard maximum number of top-level instructions the transaction format can encode.
+    TRANSACTION_INSTRUCTION_LIMIT = T.let(64, Integer)
+
+    module_function
+
+    # Resolves the effective maximum number of instructions allowed in a transaction message,
+    # falling back to the default when no value is provided.
+    # Mirrors `resolveMaxInstructions(maxInstructions)`.
+    sig { params(max_instructions: T.nilable(Integer)).returns(Integer) }
+    def resolve_max_instructions(max_instructions)
+      max_instructions || DEFAULT_MAX_INSTRUCTIONS_PER_TRANSACTION
+    end
+
+    # Asserts that a configured maximum number of instructions per transaction is valid.
+    # +nil+ is allowed and falls back to the default.
+    # Mirrors `assertValidMaxInstructionsPerTransaction(maxInstructions)`.
+    sig { params(max_instructions: T.nilable(Integer)).void }
+    def assert_valid_max_instructions_per_transaction(max_instructions)
+      return if max_instructions.nil?
+
+      if max_instructions <= 0 || max_instructions > TRANSACTION_INSTRUCTION_LIMIT
+        Kernel.raise SolanaError.new(
+          SolanaError::INSTRUCTION_PLANS__INVALID_MAX_INSTRUCTIONS_PER_TRANSACTION,
+          {
+            max_instructions:              max_instructions,
+            transaction_instruction_limit: TRANSACTION_INSTRUCTION_LIMIT
+          }
+        )
+      end
+    end
+
+    # Raises if +num_instructions+ exceeds +max_instructions+.
+    # Mirrors `assertMaxInstructionsPerTransaction(numInstructions, maxInstructions)`.
+    sig { params(num_instructions: Integer, max_instructions: Integer).void }
+    def assert_max_instructions_per_transaction(num_instructions, max_instructions)
+      return if num_instructions <= max_instructions
+
+      Kernel.raise SolanaError.new(
+        SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED,
+        { max_instructions: max_instructions, num_instructions: num_instructions }
+      )
+    end
+  end
+end

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

@@ -23,27 +23,45 @@ module Solana::Ruby::Kit
     #     Called after instructions are appended to a message. Must return the
     #     (possibly further updated) message. Defaults to identity.
     #
-    # The returned planner is a lambda: planner.call(instruction_plan) -> TransactionPlan
+    #   max_instructions_per_transaction: Integer  (optional)
+    #     Maximum number of top-level instructions allowed in each planned transaction.
+    #     Must be a positive integer no greater than 64. Defaults to 16. Can be overridden
+    #     per-call via the returned planner's `max_instructions_per_transaction:` kwarg.
+    #
+    # The returned planner is a lambda:
+    #   planner.call(instruction_plan, max_instructions_per_transaction: nil) -> TransactionPlan
     #
     # Mirrors `createTransactionPlanner(config)` from @solana/instruction-plans.
     # NOTE: Ruby translation is synchronous; abort-signal support is omitted.
     sig do
       params(
-        create_transaction_message:     T.untyped,
-        on_transaction_message_updated: T.untyped
+        create_transaction_message:        T.untyped,
+        on_transaction_message_updated:    T.untyped,
+        max_instructions_per_transaction:  T.nilable(Integer)
       ).returns(T.untyped)
     end
     def create_transaction_planner(
       create_transaction_message:,
-      on_transaction_message_updated: ->(msg) { msg }
+      on_transaction_message_updated: ->(msg) { msg },
+      max_instructions_per_transaction: nil
     )
       ctx = {
         create_transaction_message:     create_transaction_message,
         on_transaction_message_updated: on_transaction_message_updated
       }
+      config_max_instructions_per_transaction = max_instructions_per_transaction
+
+      ->(instruction_plan, max_instructions_per_transaction: nil) {
+        resolved_max = max_instructions_per_transaction || config_max_instructions_per_transaction
+
+        # Reject up front any configured maximum the transaction format could never satisfy,
+        # rather than discovering it mid-plan when a message fails to compile.
+        InstructionPlans.assert_valid_max_instructions_per_transaction(resolved_max)
 
-      ->(instruction_plan) {
-        mutable = planner_traverse(instruction_plan, ctx.merge(parent: nil, parent_candidates: []))
+        mutable = planner_traverse(
+          instruction_plan,
+          ctx.merge(parent: nil, parent_candidates: [], max_instructions_per_transaction: resolved_max)
+        )
         Kernel.raise SolanaError.new(SolanaError::INSTRUCTION_PLANS__EMPTY_INSTRUCTION_PLAN) unless mutable
         planner_freeze(mutable)
       }
@@ -136,7 +154,7 @@ module Solana::Ruby::Kit
       candidates = ctx[:parent_candidates].dup
 
       until packer.done?
-        predicate = ->(msg) { packer.pack_message_to_capacity(msg) }
+        predicate = ->(msg) { packer.pack_message_to_capacity(msg, max_instructions: ctx[:max_instructions_per_transaction]) }
         candidate = planner_select_and_mutate_candidate(ctx, candidates, &predicate)
         unless candidate
           msg      = planner_create_new_message(ctx, &predicate)
@@ -162,11 +180,18 @@ module Solana::Ruby::Kit
         begin
           updated = ctx[:on_transaction_message_updated].call(predicate.call(candidate[:message]))
           if Transactions.get_transaction_message_size(updated) <= Transactions::TRANSACTION_SIZE_LIMIT
+            InstructionPlans.assert_max_instructions_per_transaction(
+              updated.instructions.length,
+              InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+            )
             candidate[:message] = updated
             return candidate
           end
         rescue SolanaError => e
-          next if e.code == SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN
+          next if [
+            SolanaError::INSTRUCTION_PLANS__MESSAGE_CANNOT_ACCOMMODATE_PLAN,
+            SolanaError::INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED
+          ].include?(e.code)
           Kernel.raise
         end
       end
@@ -187,6 +212,11 @@ module Solana::Ruby::Kit
         )
       end
 
+      InstructionPlans.assert_max_instructions_per_transaction(
+        updated_msg.instructions.length,
+        InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+      )
+
       updated_msg
     end
 
@@ -205,11 +235,21 @@ module Solana::Ruby::Kit
               num_free_bytes:     Transactions::TRANSACTION_SIZE_LIMIT - base_size }
           )
         end
+        InstructionPlans.assert_max_instructions_per_transaction(
+          updated.instructions.length,
+          InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+        )
         updated
       when :message_packer
         packer = plan.get_message_packer.call
         msg    = message
-        msg    = packer.pack_message_to_capacity(msg) until packer.done?
+        until packer.done?
+          msg = packer.pack_message_to_capacity(msg, max_instructions: ctx[:max_instructions_per_transaction])
+          InstructionPlans.assert_max_instructions_per_transaction(
+            msg.instructions.length,
+            InstructionPlans.resolve_max_instructions(ctx[:max_instructions_per_transaction])
+          )
+        end
         msg
       else
         Kernel.raise SolanaError.new(

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

@@ -3,6 +3,7 @@
 
 # Mirrors @solana/instruction-plans.
 # An InstructionPlan describes operations that may span multiple transactions.
+require_relative 'instruction_plans/max_instructions'
 require_relative 'instruction_plans/instruction_plan'
 require_relative 'instruction_plans/transaction_plan'
 require_relative 'instruction_plans/transaction_plan_result'

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

@@ -12,6 +12,7 @@ module Solana::Ruby::Kit
           :activated_stake,
           :epoch_vote_account,
           :commission,
+          :inflation_rewards_commission_bps,
           :last_vote,
           :epoch_credits,
           :root_slot,
@@ -45,6 +46,7 @@ module Solana::Ruby::Kit
               activated_stake:    Kernel.Integer(v['activatedStake']),
               epoch_vote_account: v['epochVoteAccount'],
               commission:         Kernel.Integer(v['commission']),
+              inflation_rewards_commission_bps: v['inflationRewardsCommissionBps'] ? Kernel.Integer(v['inflationRewardsCommissionBps']) : nil,
               last_vote:          Kernel.Integer(v['lastVote']),
               epoch_credits:      v['epochCredits'],
               root_slot:          v['rootSlot'] ? Kernel.Integer(v['rootSlot']) : nil

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

@@ -0,0 +1,168 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    extend T::Sig
+
+    # The signer/readonly account counts from a compiled transaction message.
+    # Mirrors the `header` field of TypeScript's `CompiledTransactionMessage`.
+    class CompiledTransactionMessageHeader < T::Struct
+      const :num_signer_accounts,               Integer
+      const :num_readonly_signer_accounts,      Integer
+      const :num_readonly_non_signer_accounts,  Integer
+    end
+
+    # A single instruction inside a compiled transaction message, with account
+    # indices and data still unresolved (see GetInstructions for resolution).
+    class CompiledInstruction < T::Struct
+      const :program_address_index, Integer
+      const :account_indices,       T::Array[Integer]
+      const :data,                  String  # binary; may be empty
+    end
+
+    # A decoded transaction message: the account roles, static account list,
+    # instructions, and lifetime token (recent blockhash or durable nonce value).
+    #
+    # Mirrors TypeScript's `CompiledTransactionMessage & CompiledTransactionMessageWithLifetime`.
+    # Ruby normalizes legacy/v0/v1 instruction representations into a single
+    # `instructions` array (TypeScript keeps v1's headers/payloads split) since
+    # nothing downstream needs the raw per-version shape.
+    class CompiledTransactionMessage < T::Struct
+      const :version,         T.untyped  # :legacy or Integer (0 or 1)
+      const :header,          CompiledTransactionMessageHeader
+      const :static_accounts, T::Array[Addresses::Address]
+      const :instructions,    T::Array[CompiledInstruction]
+      const :lifetime_token,  String  # base58-encoded blockhash or nonce value
+    end
+
+    module_function
+
+    # Decodes legacy or v0 compiled transaction message bytes (the
+    # `message_bytes` of a `Transactions::Transaction`) into a
+    # CompiledTransactionMessage.
+    #
+    # v1 messages use a different (message-first) wire envelope and are not
+    # decoded here — Ruby's wire compiler (`Transactions.compile_transaction_message`)
+    # does not yet produce v1 transactions either, so there is nothing to
+    # round-trip. Raises SolanaError::TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED
+    # for any version this decoder cannot handle.
+    #
+    # Mirrors `getCompiledTransactionMessageDecoder()` from @solana/transaction-messages.
+    sig { params(message_bytes: String).returns(CompiledTransactionMessage) }
+    def decode_compiled_transaction_message(message_bytes)
+      bytes  = message_bytes.b
+      offset = 0
+
+      first_byte = bytes.getbyte(0).to_i
+      if (first_byte & 0x80) != 0
+        version = first_byte & 0x7f
+        unless version == 0
+          Kernel.raise SolanaError.new(
+            SolanaError::TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED,
+            { unsupported_version: version }
+          )
+        end
+        offset += 1
+      else
+        version = :legacy
+      end
+
+      num_signer_accounts, offset              = read_byte(bytes, offset)
+      num_readonly_signer_accounts, offset     = read_byte(bytes, offset)
+      num_readonly_non_signer_accounts, offset = read_byte(bytes, offset)
+
+      num_accounts, offset = decode_compact_u16(bytes, offset)
+      static_accounts = T.let([], T::Array[Addresses::Address])
+      num_accounts.times do
+        static_accounts << Addresses.address(Addresses.encode_address(read_bytes(bytes, offset, 32)))
+        offset += 32
+      end
+
+      lifetime_token = Addresses.encode_address(read_bytes(bytes, offset, 32))
+      offset += 32
+
+      num_instructions, offset = decode_compact_u16(bytes, offset)
+      instructions = T.let([], T::Array[CompiledInstruction])
+      num_instructions.times do
+        program_address_index, offset = read_byte(bytes, offset)
+
+        num_ix_accounts, offset = decode_compact_u16(bytes, offset)
+        account_indices = T.let([], T::Array[Integer])
+        num_ix_accounts.times do
+          index, offset = read_byte(bytes, offset)
+          account_indices << index
+        end
+
+        data_length, offset = decode_compact_u16(bytes, offset)
+        data = read_bytes(bytes, offset, data_length)
+        offset += data_length
+
+        instructions << CompiledInstruction.new(
+          program_address_index: program_address_index,
+          account_indices:       account_indices,
+          data:                  data
+        )
+      end
+
+      CompiledTransactionMessage.new(
+        version:         version,
+        header:          CompiledTransactionMessageHeader.new(
+          num_signer_accounts:              num_signer_accounts,
+          num_readonly_signer_accounts:     num_readonly_signer_accounts,
+          num_readonly_non_signer_accounts: num_readonly_non_signer_accounts
+        ),
+        static_accounts: static_accounts,
+        instructions:    instructions,
+        lifetime_token:  lifetime_token
+      )
+    end
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    sig { params(bytes: String, offset: Integer, length: Integer).returns(String) }
+    def read_bytes(bytes, offset, length)
+      slice = bytes[offset, length]
+      if slice.nil? || slice.bytesize != length
+        Kernel.raise SolanaError.new(
+          SolanaError::TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE,
+          { needed_bytes: offset + length }
+        )
+      end
+      slice.b
+    end
+    private_class_method :read_bytes
+
+    sig { params(bytes: String, offset: Integer).returns([Integer, Integer]) }
+    def read_byte(bytes, offset)
+      byte = bytes.getbyte(offset)
+      if byte.nil?
+        Kernel.raise SolanaError.new(
+          SolanaError::TRANSACTION_INTROSPECTION__MALFORMED_COMPILED_MESSAGE,
+          { needed_bytes: offset + 1 }
+        )
+      end
+      [byte, offset + 1]
+    end
+    private_class_method :read_byte
+
+    # Reads a Solana compact-u16 from +bytes+ starting at +offset+.
+    # Returns [decoded_integer, next_offset].
+    sig { params(bytes: String, offset: Integer).returns([Integer, Integer]) }
+    def decode_compact_u16(bytes, offset)
+      value = 0
+      shift = 0
+      Kernel.loop do
+        byte, offset = read_byte(bytes, offset)
+        value |= (byte & 0x7f) << shift
+        shift += 7
+        break unless (byte & 0x80) != 0
+      end
+      [value, offset]
+    end
+    private_class_method :decode_compact_u16
+  end
+end

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

@@ -0,0 +1,159 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require_relative '../addresses'
+require_relative '../encoding/base58'
+require_relative '../errors'
+require_relative '../transactions/transaction'
+require_relative '../wallet_standard'
+require_relative 'compiled_transaction_message'
+require_relative 'loaded_addresses'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    extend T::Sig
+
+    # The result of decoding a `getTransaction` response: the
+    # CompiledTransactionMessage, the loaded ALT addresses pulled from `meta`
+    # (if any), and — for `'base64'` and `'base58'` responses — the
+    # re-encodable wire-format Transactions::Transaction.
+    #
+    # `transaction` is nil for `encoding: 'json'` responses: the server has
+    # already decompiled the wire format, so there are no message bytes to
+    # round-trip. Fetch with `encoding: 'base64'` if you need a re-encodable
+    # Transaction.
+    #
+    # Mirrors `DecodedRpcTransaction` from @solana/transaction-introspection.
+    class DecodedRpcTransaction < T::Struct
+      const :compiled_message, CompiledTransactionMessage
+      const :loaded_addresses, LoadedAddresses
+      const :transaction,      T.nilable(Transactions::Transaction)
+    end
+
+    module_function
+
+    # Decodes a `getTransaction` response (any of `encoding: 'base64'`,
+    # `'base58'`, or `'json'`) into a CompiledTransactionMessage plus, for
+    # `'base64'` and `'base58'`, a re-encodable Transactions::Transaction.
+    # The JSON path does not produce a Transaction: the server has already
+    # decompiled the wire format, so there are no message bytes to carry.
+    #
+    # +rpc_tx+ is the raw (String-keyed) JSON hash returned by
+    # `Rpc::Api::GetTransaction#get_transaction`.
+    #
+    # `'jsonParsed'` is not supported — its instructions arrive pre-parsed by
+    # the server and lack raw bytes, so they cannot be round-tripped. Passing
+    # a `'jsonParsed'` response raises
+    # SolanaError::TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION;
+    # any other unrecognized input raises
+    # SolanaError::TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE.
+    #
+    # A transaction version this decoder cannot handle (anything but legacy
+    # or v0) raises SolanaError::TRANSACTION__VERSION_NUMBER_NOT_SUPPORTED —
+    # Ruby's wire compiler does not produce v1 transactions either, so there
+    # is nothing to decompile for that version yet.
+    #
+    # Mirrors `decodeTransactionFromRpcResponse()`.
+    sig { params(rpc_tx: T::Hash[String, T.untyped]).returns(DecodedRpcTransaction) }
+    def decode_transaction_from_rpc_response(rpc_tx)
+      tx_field = rpc_tx['transaction']
+
+      if tx_field.is_a?(Array)
+        encoding = tx_field[1]
+        return decode_from_base64(rpc_tx) if encoding == 'base64'
+        return decode_from_base58(rpc_tx) if encoding == 'base58'
+      elsif tx_field.is_a?(Hash) && tx_field['message'].is_a?(Hash)
+        # An `encoding: 'json'` message carries the compiled-message `header`
+        # (signer/readonly counts). A `jsonParsed` message has no `header` —
+        # the server has already resolved account roles onto `accountKeys` —
+        # so checking for it distinguishes the two encodings.
+        return decode_from_json(rpc_tx) if tx_field['message']['header'].is_a?(Hash)
+
+        Kernel.raise SolanaError.new(SolanaError::TRANSACTION_INTROSPECTION__CANNOT_DECODE_JSON_PARSED_TRANSACTION)
+      end
+
+      Kernel.raise SolanaError.new(SolanaError::TRANSACTION_INTROSPECTION__UNRECOGNIZED_GET_TRANSACTION_RESPONSE)
+    end
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    sig { params(meta: T.untyped).returns(LoadedAddresses) }
+    def get_loaded_addresses(meta)
+      loaded = meta.is_a?(Hash) ? meta['loadedAddresses'] : nil
+      return EMPTY_LOADED_ADDRESSES unless loaded.is_a?(Hash)
+
+      LoadedAddresses.new(
+        readonly: (loaded['readonly'] || []).map { |a| Addresses.address(a) },
+        writable: (loaded['writable'] || []).map { |a| Addresses.address(a) }
+      )
+    end
+    private_class_method :get_loaded_addresses
+
+    sig { params(rpc_tx: T::Hash[String, T.untyped]).returns(DecodedRpcTransaction) }
+    def decode_from_base64(rpc_tx)
+      b64         = rpc_tx['transaction'][0]
+      transaction = WalletStandard.decode_wire_transaction(b64)
+      DecodedRpcTransaction.new(
+        compiled_message: decode_compiled_transaction_message(transaction.message_bytes),
+        loaded_addresses: get_loaded_addresses(rpc_tx['meta']),
+        transaction:      transaction
+      )
+    end
+    private_class_method :decode_from_base64
+
+    sig { params(rpc_tx: T::Hash[String, T.untyped]).returns(DecodedRpcTransaction) }
+    def decode_from_base58(rpc_tx)
+      b58         = rpc_tx['transaction'][0]
+      transaction = WalletStandard.decode_wire_transaction(Encoding::Base58.decode(b58))
+      DecodedRpcTransaction.new(
+        compiled_message: decode_compiled_transaction_message(transaction.message_bytes),
+        loaded_addresses: get_loaded_addresses(rpc_tx['meta']),
+        transaction:      transaction
+      )
+    end
+    private_class_method :decode_from_base58
+
+    sig { params(rpc_tx: T::Hash[String, T.untyped]).returns(DecodedRpcTransaction) }
+    def decode_from_json(rpc_tx)
+      message = rpc_tx['transaction']['message']
+
+      header = CompiledTransactionMessageHeader.new(
+        num_signer_accounts:              message['header']['numRequiredSignatures'],
+        num_readonly_signer_accounts:      message['header']['numReadonlySignedAccounts'],
+        num_readonly_non_signer_accounts:  message['header']['numReadonlyUnsignedAccounts']
+      )
+
+      instructions = message['instructions'].map do |ix|
+        data_b58 = ix['data']
+        CompiledInstruction.new(
+          program_address_index: ix['programIdIndex'],
+          account_indices:       ix['accounts'] || [],
+          data:                  data_b58.nil? || data_b58.empty? ? ''.b : Encoding::Base58.decode(data_b58)
+        )
+      end
+
+      # The envelope only carries `version` when `maxSupportedTransactionVersion`
+      # was set on the request; otherwise the response is necessarily legacy.
+      version = rpc_tx.key?('version') ? rpc_tx['version'] : :legacy
+      version = :legacy if version == 'legacy'
+
+      compiled_message = CompiledTransactionMessage.new(
+        version:         version,
+        header:          header,
+        static_accounts: message['accountKeys'].map { |a| Addresses.address(a) },
+        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']
+      )
+
+      DecodedRpcTransaction.new(
+        compiled_message: compiled_message,
+        loaded_addresses: get_loaded_addresses(rpc_tx['meta']),
+        transaction:      nil
+      )
+    end
+    private_class_method :decode_from_json
+  end
+end

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

@@ -0,0 +1,86 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../encoding/base58'
+require_relative '../errors'
+require_relative '../instructions/instruction'
+require_relative 'types'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    extend T::Sig
+
+    module_function
+
+    # Returns the inner instructions in a `getTransaction` response as
+    # TracedInstructions.
+    #
+    # The RPC returns inner instructions in a different shape from the wire
+    # format: indices reference the same flat account list as the outer
+    # instructions, but `data` is a base58-encoded string. This decodes the
+    # data, resolves the indices against the supplied AccountMeta list, and
+    # tags each instruction with an `inner` trace.
+    #
+    # +meta+ is the raw (String-keyed) `meta` hash from a `getTransaction`
+    # response. Returns an empty array if it carries no `innerInstructions`.
+    #
+    # Raises if any `programIdIndex` or account index falls outside the
+    # supplied `account_metas` list.
+    #
+    # Mirrors `getInnerInstructionsFromMeta()`.
+    sig do
+      params(
+        meta:          T.nilable(T::Hash[String, T.untyped]),
+        account_metas: T::Array[Instructions::AccountMeta]
+      ).returns(T::Array[TracedInstruction])
+    end
+    def get_inner_instructions_from_meta(meta, account_metas)
+      groups = meta && meta['innerInstructions']
+      return [] unless groups
+
+      result = T.let([], T::Array[TracedInstruction])
+
+      groups.each do |group|
+        outer_index = group['index']
+
+        group['instructions'].each_with_index do |ix, inner_index|
+          program_meta = account_metas[ix['programIdIndex']]
+          if program_meta.nil?
+            Kernel.raise SolanaError.new(
+              SolanaError::TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND,
+              { index: ix['programIdIndex'] }
+            )
+          end
+
+          accounts = (ix['accounts'] || []).map do |i|
+            account_meta = account_metas[i]
+            if account_meta.nil?
+              Kernel.raise SolanaError.new(
+                SolanaError::TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE,
+                { index: i }
+              )
+            end
+            account_meta
+          end
+
+          data_b58 = ix['data']
+          data     = data_b58.nil? || data_b58.empty? ? nil : Encoding::Base58.decode(data_b58)
+
+          trace = { kind: :inner, outer_index: outer_index, inner_index: inner_index }
+          trace[:stack_height] = ix['stackHeight'] unless ix['stackHeight'].nil?
+
+          result << TracedInstruction.new(
+            instruction: Instructions::Instruction.new(
+              program_address: program_meta.address,
+              accounts:        accounts.empty? ? nil : accounts,
+              data:            data
+            ),
+            trace: trace
+          )
+        end
+      end
+
+      result
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../instructions/instruction'
+require_relative '../instructions/roles'
+require_relative 'compiled_transaction_message'
+require_relative 'loaded_addresses'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    extend T::Sig
+
+    module_function
+
+    # Builds the full ordered list of AccountMetas for a compiled transaction
+    # message.
+    #
+    # The order matches the runtime's resolution order:
+    #   1. Static accounts, with role bits derived from the message header
+    #      (writable signers, readonly signers, writable non-signers, readonly
+    #      non-signers).
+    #   2. ALT-loaded writable accounts (always non-signer, writable).
+    #   3. ALT-loaded readonly accounts (always non-signer, readonly).
+    #
+    # Inner-instruction account indices reference the same flat list, so this
+    # helper is also useful for resolving inner instructions.
+    #
+    # Mirrors `getAccountMetasFromCompiledTransactionMessage()`.
+    sig do
+      params(
+        compiled_message: CompiledTransactionMessage,
+        loaded_addresses: T.nilable(LoadedAddresses)
+      ).returns(T::Array[Instructions::AccountMeta])
+    end
+    def get_account_metas_from_compiled_transaction_message(compiled_message, loaded_addresses = nil)
+      header          = compiled_message.header
+      static_accounts = compiled_message.static_accounts
+
+      num_writable_signer_accounts =
+        header.num_signer_accounts - header.num_readonly_signer_accounts
+      num_writable_non_signer_accounts =
+        static_accounts.length - header.num_signer_accounts - header.num_readonly_non_signer_accounts
+
+      metas = T.let([], T::Array[Instructions::AccountMeta])
+      i = 0
+      num_writable_signer_accounts.times do
+        metas << Instructions::AccountMeta.new(address: T.must(static_accounts[i]), role: Instructions::AccountRole::WRITABLE_SIGNER)
+        i += 1
+      end
+      header.num_readonly_signer_accounts.times do
+        metas << Instructions::AccountMeta.new(address: T.must(static_accounts[i]), role: Instructions::AccountRole::READONLY_SIGNER)
+        i += 1
+      end
+      num_writable_non_signer_accounts.times do
+        metas << Instructions::AccountMeta.new(address: T.must(static_accounts[i]), role: Instructions::AccountRole::WRITABLE)
+        i += 1
+      end
+      header.num_readonly_non_signer_accounts.times do
+        metas << Instructions::AccountMeta.new(address: T.must(static_accounts[i]), role: Instructions::AccountRole::READONLY)
+        i += 1
+      end
+
+      if loaded_addresses
+        loaded_addresses.writable.each { |addr| metas << Instructions::AccountMeta.new(address: addr, role: Instructions::AccountRole::WRITABLE) }
+        loaded_addresses.readonly.each  { |addr| metas << Instructions::AccountMeta.new(address: addr, role: Instructions::AccountRole::READONLY) }
+      end
+
+      metas
+    end
+
+    # Returns the outer instructions of a compiled transaction message as
+    # Instructions::Instruction objects, with account indices resolved to
+    # AccountMetas and data exposed as a raw binary String. `accounts` and
+    # `data` are omitted (nil) when empty.
+    #
+    # Mirrors `getInstructionsFromCompiledTransactionMessage()`.
+    sig do
+      params(
+        compiled_message: CompiledTransactionMessage,
+        loaded_addresses: T.nilable(LoadedAddresses)
+      ).returns(T::Array[Instructions::Instruction])
+    end
+    def get_instructions_from_compiled_transaction_message(compiled_message, loaded_addresses = nil)
+      metas = get_account_metas_from_compiled_transaction_message(compiled_message, loaded_addresses)
+      get_instructions_from_compiled_transaction_message_with_metas(compiled_message, metas)
+    end
+
+    # Internal variant of get_instructions_from_compiled_transaction_message
+    # that takes pre-built AccountMetas. Used by WalkInstructions to avoid
+    # rebuilding the meta list when it is already needed for resolving inner
+    # instructions.
+    sig do
+      params(
+        compiled_message: CompiledTransactionMessage,
+        account_metas:    T::Array[Instructions::AccountMeta]
+      ).returns(T::Array[Instructions::Instruction])
+    end
+    def get_instructions_from_compiled_transaction_message_with_metas(compiled_message, account_metas)
+      compiled_message.instructions.map { |ix| resolve_instruction(ix, account_metas) }
+    end
+
+    # ── Private helpers ────────────────────────────────────────────────────────
+
+    sig { params(ix: CompiledInstruction, metas: T::Array[Instructions::AccountMeta]).returns(Instructions::Instruction) }
+    def resolve_instruction(ix, metas)
+      program_meta = metas[ix.program_address_index]
+      if program_meta.nil?
+        Kernel.raise SolanaError.new(
+          SolanaError::TRANSACTIONS__FAILED_TO_DECOMPILE_INSTRUCTION_PROGRAM_ADDRESS_NOT_FOUND,
+          { index: ix.program_address_index }
+        )
+      end
+
+      accounts = ix.account_indices.map do |i|
+        account_meta = metas[i]
+        if account_meta.nil?
+          Kernel.raise SolanaError.new(
+            SolanaError::TRANSACTION__FAILED_TO_DECOMPILE_INSTRUCTION_ACCOUNT_INDEX_OUT_OF_RANGE,
+            { index: i }
+          )
+        end
+        account_meta
+      end
+
+      Instructions::Instruction.new(
+        program_address: program_meta.address,
+        accounts:        accounts.empty? ? nil : accounts,
+        data:            ix.data.empty? ? nil : ix.data
+      )
+    end
+    private_class_method :resolve_instruction
+  end
+end

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

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    # Loaded ALT addresses as returned by `getTransaction`'s `meta.loadedAddresses`.
+    # The two arrays are kept in the same order the runtime uses to resolve
+    # instruction account indices.
+    # Mirrors `LoadedAddresses` from @solana/transaction-introspection.
+    class LoadedAddresses < T::Struct
+      const :readonly, T::Array[Addresses::Address]
+      const :writable, T::Array[Addresses::Address]
+    end
+
+    EMPTY_LOADED_ADDRESSES = T.let(LoadedAddresses.new(readonly: [], writable: []), LoadedAddresses)
+  end
+end

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

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../instructions/instruction'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    # A ResolvedInstruction carrying its location in the transaction as a
+    # `trace` Hash.
+    #
+    # TypeScript flattens `TracedInstruction` into the instruction itself
+    # (`ResolvedInstruction & { trace }`), so callers there access
+    # `ix.programAddress` directly. Ruby's `Instructions::Instruction` is a
+    # `T::Struct`, which is final and cannot be subclassed (see
+    # `Transactions::FullySignedTransaction` for the same constraint), so here
+    # the instruction and its trace are held as sibling fields instead:
+    # `traced.instruction.program_address`, `traced.trace`.
+    #
+    # `trace` is one of:
+    #   { kind: :outer, index: Integer }
+    #   { kind: :inner, outer_index: Integer, inner_index: Integer, stack_height: T.nilable(Integer) }
+    #
+    # Mirrors `TracedInstruction` / `InstructionTrace` from @solana/transaction-introspection.
+    class TracedInstruction < T::Struct
+      const :instruction, Instructions::Instruction
+      const :trace,       T::Hash[Symbol, T.untyped]
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'compiled_transaction_message'
+require_relative 'get_inner_instructions'
+require_relative 'get_instructions'
+require_relative 'loaded_addresses'
+require_relative 'types'
+
+module Solana::Ruby::Kit
+  module TransactionIntrospection
+    extend T::Sig
+
+    module_function
+
+    # Returns every instruction in a confirmed transaction as
+    # TracedInstructions, in the order an explorer displays them: each outer
+    # instruction followed immediately by the inner instructions its CPIs
+    # produced.
+    #
+    # If +meta+ is nil, only outer instructions are returned. If
+    # +loaded_addresses+ is nil, only static accounts are used to resolve
+    # indices — pass the `loadedAddresses` from a `getTransaction` response's
+    # `meta` for v0 transactions that load accounts from address lookup tables.
+    #
+    # Mirrors `walkInstructions({ compiledMessage, loadedAddresses, meta })`.
+    sig do
+      params(
+        compiled_message: CompiledTransactionMessage,
+        loaded_addresses: T.nilable(LoadedAddresses),
+        meta:             T.nilable(T::Hash[String, T.untyped])
+      ).returns(T::Array[TracedInstruction])
+    end
+    def walk_instructions(compiled_message:, loaded_addresses: nil, meta: nil)
+      account_metas      = get_account_metas_from_compiled_transaction_message(compiled_message, loaded_addresses)
+      outer_instructions = get_instructions_from_compiled_transaction_message_with_metas(compiled_message, account_metas)
+
+      inner_by_outer_index = T.let({}, T::Hash[Integer, T::Array[TracedInstruction]])
+      if meta
+        get_inner_instructions_from_meta(meta, account_metas).each do |inner|
+          outer_index = inner.trace.fetch(:outer_index)
+          (inner_by_outer_index[outer_index] ||= []) << inner
+        end
+      end
+
+      result = T.let([], T::Array[TracedInstruction])
+      outer_instructions.each_with_index do |instruction, index|
+        result << TracedInstruction.new(instruction: instruction, trace: { kind: :outer, index: index })
+        group = inner_by_outer_index.delete(index)
+        result.concat(group) if group
+      end
+      # Inner groups whose index matches no outer instruction can only come
+      # from malformed input (e.g. `meta` paired with the wrong message).
+      # Append them rather than dropping them so no instruction is ever lost.
+      inner_by_outer_index.each_value { |group| result.concat(group) }
+
+      result
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Helpers for inspecting confirmed Solana transactions and walking their
+# outer and inner instructions.
+# Mirrors @solana/transaction-introspection.
+require_relative 'transaction_introspection/loaded_addresses'
+require_relative 'transaction_introspection/compiled_transaction_message'
+require_relative 'transaction_introspection/types'
+require_relative 'transaction_introspection/get_instructions'
+require_relative 'transaction_introspection/get_inner_instructions'
+require_relative 'transaction_introspection/walk_instructions'
+require_relative 'transaction_introspection/decode_rpc_transaction'

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

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '0.1.9'
+      VERSION = '7.0.0'
     end
   end
 end

data/lib/solana/ruby/kit.rb

@@ -51,6 +51,7 @@ require_relative 'kit/sysvars'
 require_relative 'kit/transaction_confirmation'
 require_relative 'kit/instruction_plans'
 require_relative 'kit/resource_limit_estimation'
+require_relative 'kit/transaction_introspection'
 
 # Solana::Ruby::Kit is a Ruby translation of @anza-xyz/kit — the JavaScript SDK for
 # building Solana apps — into idiomatic Ruby with Sorbet static types.
@@ -80,6 +81,7 @@ require_relative 'kit/resource_limit_estimation'
 #   Solana::Ruby::Kit::TransactionConfirmation — confirmation polling   (@solana/transaction-confirmation)
 #   Solana::Ruby::Kit::InstructionPlans      — multi-tx planning        (@solana/instruction-plans)
 #   Solana::Ruby::Kit::WalletStandard        — server-side sig verify   (@solana/wallet-standard)
+#   Solana::Ruby::Kit::TransactionIntrospection — decode/walk instructions (@solana/transaction-introspection)
 
 module Solana::Ruby::Kit
   extend T::Sig

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 7.0.0
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
@@ -209,6 +209,7 @@ files:
 - lib/solana/ruby/kit/functional.rb
 - lib/solana/ruby/kit/instruction_plans.rb
 - lib/solana/ruby/kit/instruction_plans/instruction_plan.rb
+- lib/solana/ruby/kit/instruction_plans/max_instructions.rb
 - lib/solana/ruby/kit/instruction_plans/plans.rb
 - lib/solana/ruby/kit/instruction_plans/transaction_plan.rb
 - lib/solana/ruby/kit/instruction_plans/transaction_plan_executor.rb
@@ -298,6 +299,14 @@ files:
 - lib/solana/ruby/kit/sysvars/last_restart_slot.rb
 - lib/solana/ruby/kit/sysvars/rent.rb
 - lib/solana/ruby/kit/transaction_confirmation.rb
+- lib/solana/ruby/kit/transaction_introspection.rb
+- lib/solana/ruby/kit/transaction_introspection/compiled_transaction_message.rb
+- lib/solana/ruby/kit/transaction_introspection/decode_rpc_transaction.rb
+- lib/solana/ruby/kit/transaction_introspection/get_inner_instructions.rb
+- lib/solana/ruby/kit/transaction_introspection/get_instructions.rb
+- lib/solana/ruby/kit/transaction_introspection/loaded_addresses.rb
+- lib/solana/ruby/kit/transaction_introspection/types.rb
+- lib/solana/ruby/kit/transaction_introspection/walk_instructions.rb
 - lib/solana/ruby/kit/transaction_messages.rb
 - lib/solana/ruby/kit/transaction_messages/compute_budget.rb
 - lib/solana/ruby/kit/transaction_messages/transaction_message.rb