solana-ruby-kit 0.1.9 → 7.0.0.1

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.1'
     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.1
 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
@@ -254,6 +255,7 @@ files:
 - lib/solana/ruby/kit/rpc/api/get_token_account_balance.rb
 - lib/solana/ruby/kit/rpc/api/get_token_accounts_by_owner.rb
 - lib/solana/ruby/kit/rpc/api/get_transaction.rb
+- lib/solana/ruby/kit/rpc/api/get_transactions_for_address.rb
 - lib/solana/ruby/kit/rpc/api/get_vote_accounts.rb
 - lib/solana/ruby/kit/rpc/api/is_blockhash_valid.rb
 - lib/solana/ruby/kit/rpc/api/request_airdrop.rb
@@ -288,6 +290,7 @@ files:
 - lib/solana/ruby/kit/signers/keypair_signer.rb
 - lib/solana/ruby/kit/subscribable.rb
 - lib/solana/ruby/kit/subscribable/async_iterable.rb
+- lib/solana/ruby/kit/subscribable/bridge_store_to_async_iterable.rb
 - lib/solana/ruby/kit/subscribable/data_publisher.rb
 - lib/solana/ruby/kit/subscribable/reactive_action_store.rb
 - lib/solana/ruby/kit/subscribable/reactive_stream_store.rb
@@ -298,6 +301,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