solana-ruby-kit 0.1.8 → 7.0.0

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

@@ -117,10 +117,9 @@ module Solana::Ruby::Kit
         http.open_timeout = @open_timeout
 
         req = Net::HTTP::Post.new(T.cast(@uri, URI::HTTP).request_uri)
-        req['Content-Type']   = 'application/json; charset=utf-8'
-        req['Accept']         = 'application/json'
-        req['Content-Length'] = body.bytesize.to_s
-        req['solana-client']  = 'ruby-kit'
+        req['Content-Type']  = 'application/json; charset=utf-8'
+        req['Accept']        = 'application/json'
+        req['solana-client'] = 'ruby-kit'
         @headers.each { |k, v| req[k] = v }
         req.body = body
 

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