solana-ruby-kit 7.1.1.1 → 8.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa006377351feaf52ae4b75a9979f21065d0ac039f0c5dd4d18a6dc9a916921b
-  data.tar.gz: 4802bb1454ed72fdca55b226f9fef75f4e766b183be91d69480a5ceddc6d3d66
+  metadata.gz: ba7d2659d83b01af6565c7af483364d61e61fcc9761cbca9d63d8d41f6b4d73a
+  data.tar.gz: bd8402f845e9d8db5845be0e358676d00e308b2a0777afc1973e8814175e1c1c
 SHA512:
-  metadata.gz: 345cfd37b9188dde96eb86dced69885c8de18290e97126ff4e8d328842d44a044d19a5c5e9e9d63124ad792b85b81b892f106b31fccc091dade697f298c91b0e
-  data.tar.gz: 1b8591236759f984c22122b810ee92796ff9542e6d4c1cba30837a5696e057fb0c065486463223812c0f8c41331389b4604833ebbcef69b53a377229dd5ce153
+  metadata.gz: 589ade790ebb62b97f9905e8fe98113efc93deb5a6fad37239d377ab427915838eaa3d461644d213944ee8b80796134b28d5a6da43529a3920bb5037940a20a1
+  data.tar.gz: 3c03649c3b4314b93e7321f74b77150cd19bd775535b8431c14b678fdf35d3e7d4703fac43f341c3480ec5031b0c78bd0c0e3b7e385bb01f1822fc57fa5afaec

data/README.md

@@ -189,9 +189,17 @@ msg = TxMsg.append_instructions(msg, [instruction])
 msg = TxMsg.prepend_instructions(msg, [priority_fee_ix])
 
 # Compute unit limit (SetComputeUnitLimit instruction from the Compute Budget program)
+# The limit is validated: it must be an integer in [0, MAX_COMPUTE_UNIT_LIMIT] (1,400,000).
+# The runtime silently clamps a larger request rather than failing, so asking for more than
+# the maximum would run on a budget you did not ask for — this raises instead.
 msg = TxMsg.set_transaction_message_compute_unit_limit(200_000, msg)
 TxMsg.get_transaction_message_compute_unit_limit(msg)  # => 200_000
 
+# The check is also available on its own, alongside one for heap frame sizes — a whole
+# number of KiB in [MIN_HEAP_SIZE, MAX_HEAP_SIZE] (32 KiB to 256 KiB).
+TxMsg.assert_is_valid_compute_unit_limit(200_000)
+TxMsg.assert_is_valid_heap_size(64 * 1024)
+
 # Loaded accounts data size limit
 msg = TxMsg.set_transaction_message_loaded_accounts_data_size_limit(64_000, msg)
 TxMsg.get_transaction_message_loaded_accounts_data_size_limit(msg)  # => 64_000
@@ -274,6 +282,7 @@ rpc.get_block_time(slot)
 rpc.get_inflation_reward([address])
 rpc.get_signatures_for_address(address)
 rpc.get_vote_accounts
+rpc.get_ag_genesis_cert                      # Alpenglow genesis cert, or nil
 rpc.simulate_transaction(encoded_tx)
 rpc.send_transaction(encoded_tx)
 rpc.request_airdrop(address, lamports)        # devnet / testnet only
@@ -640,6 +649,21 @@ result = executor.call(transaction_plan)
 # A one-argument lambda returning { transaction:, context: } — the shape this method
 # required before v7.1.0 — is still accepted and adapted onto the flow above.
 
+# ── 3b. Executing every leaf concurrently ────────────────────────────────────
+# For work that has no execution dependencies — signing or serializing, say —
+# create_transaction_plan_executor_with_concurrent_leaves takes the same callback
+# contract but starts every leaf immediately, each on its own thread. It preserves
+# the plan's nesting, order and divisibility in the result, supports non-divisible
+# sequential plans, and cancels nothing: a leaf that raises does not stop the others,
+# so every leaf runs to completion before the failure is reported. Because the leaves
+# run at the same time, the callback must be safe to call concurrently with itself.
+concurrent = Plans.create_transaction_plan_executor_with_concurrent_leaves(
+  execute_transaction_message: ->(_context, message) {
+    { transaction: Kit::Transactions.compile_transaction_message(message) }
+  }
+)
+result = concurrent.call(transaction_plan)
+
 # ── 4. Plan types ─────────────────────────────────────────────────────────────
 Plans.single_instruction_plan(ix)                      # wrap one instruction
 Plans.sequential_instruction_plan([ix1, ix2])          # ordered, divisible

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

@@ -60,6 +60,10 @@ module Solana::Ruby::Kit
     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
+    # context: { compute_unit_limit:, max_compute_unit_limit: }
+    TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE         = :SOLANA_ERROR__TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE
+    # context: { heap_size:, max_heap_size:, min_heap_size:, multiple_of: }
+    TRANSACTION__INVALID_HEAP_SIZE                       = :SOLANA_ERROR__TRANSACTION__INVALID_HEAP_SIZE
     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
@@ -147,6 +151,7 @@ module Solana::Ruby::Kit
 
     # ── Fixed-points ──────────────────────────────────────────────────────────
     FIXED_POINTS__STRICT_MODE_PRECISION_LOSS              = :SOLANA_ERROR__FIXED_POINTS__STRICT_MODE_PRECISION_LOSS
+    LAMPORTS_OUT_OF_RANGE                                 = :SOLANA_ERROR__LAMPORTS_OUT_OF_RANGE
 
     # ── Invariant violations (internal) ──────────────────────────────────────
     INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING = :SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING
@@ -206,6 +211,8 @@ module Solana::Ruby::Kit
         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',
+        TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE     => 'Transaction compute unit limit must be an integer in the range [0, %{max_compute_unit_limit}]. `%{compute_unit_limit}` given',
+        TRANSACTION__INVALID_HEAP_SIZE                   => 'Transaction heap size must be an integer multiple of %{multiple_of} bytes in the range [%{min_heap_size}, %{max_heap_size}]. `%{heap_size}` given',
         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',
@@ -286,6 +293,7 @@ module Solana::Ruby::Kit
 
         # Fixed-points
         FIXED_POINTS__STRICT_MODE_PRECISION_LOSS       => 'Value has more than 9 fractional digits and cannot be represented exactly as a Sol amount',
+        LAMPORTS_OUT_OF_RANGE                          => 'Lamports value out of range; must fit in an unsigned 64-bit integer',
 
         # Wallet Standard
         WALLET_STANDARD__INVALID_WIRE_FORMAT           => 'Invalid transaction wire format: %{reason}',

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

@@ -21,7 +21,7 @@ module Solana::Ruby::Kit
     #     ->(tx) { Solana::Ruby::Kit::TransactionMessages.set_fee_payer(fee_payer_address, tx) },
     #     ->(tx) { Solana::Ruby::Kit::TransactionMessages.set_blockhash_lifetime(blockhash, tx) },
     #   )
-    sig { params(value: T.untyped, fns: T::Array[T.proc.params(arg0: T.untyped).returns(T.untyped)]).returns(T.untyped) }
+    sig { params(value: T.untyped, fns: T.proc.params(arg0: T.untyped).returns(T.untyped)).returns(T.untyped) }
     def pipe(value, *fns)
       fns.reduce(value) { |acc, fn| T.unsafe(fn).call(acc) }
     end

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

@@ -23,7 +23,10 @@ module Solana::Ruby::Kit
 
     # A plan that wraps a single instruction.
     class SingleInstructionPlan < T::Struct
+      extend T::Sig
+
       const :instruction, Instructions::Instruction
+      sig { returns(Symbol) }
       def kind = :single
     end
 
@@ -31,21 +34,30 @@ module Solana::Ruby::Kit
     # +divisible: true+ allows the planner to split children across transactions.
     # +divisible: false+ means all children should be atomic (one tx or a bundle).
     class SequentialInstructionPlan < T::Struct
+      extend T::Sig
+
       const :plans,     T::Array[T.untyped]  # Array[InstructionPlan]
       const :divisible, T::Boolean
+      sig { returns(Symbol) }
       def kind = :sequential
     end
 
     # A plan whose children may execute concurrently or be packed in any order.
     class ParallelInstructionPlan < T::Struct
+      extend T::Sig
+
       const :plans, T::Array[T.untyped]  # Array[InstructionPlan]
+      sig { returns(Symbol) }
       def kind = :parallel
     end
 
     # Provides a MessagePacker that dynamically packs instructions into messages.
     # The +get_message_packer+ proc returns a fresh MessagePacker each call.
     class MessagePackerInstructionPlan < T::Struct
+      extend T::Sig
+
       const :get_message_packer, T.untyped  # Proc -> MessagePacker
+      sig { returns(Symbol) }
       def kind = :message_packer
     end
 
@@ -199,7 +211,7 @@ module Solana::Ruby::Kit
                   return packed
                 end
 
-                next_packed = TransactionMessages.append_instructions(packed, [instructions[i]])
+                next_packed = TransactionMessages.append_instructions(packed, [T.must(instructions[i])])
                 size        = Transactions.get_transaction_message_size(next_packed)
 
                 if size > Transactions::TRANSACTION_SIZE_LIMIT

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

@@ -17,18 +17,27 @@ module Solana::Ruby::Kit
     #                   | ParallelTransactionPlan
 
     class SingleTransactionPlan < T::Struct
+      extend T::Sig
+
       const :message, TransactionMessages::TransactionMessage
+      sig { returns(Symbol) }
       def kind = :single
     end
 
     class SequentialTransactionPlan < T::Struct
+      extend T::Sig
+
       const :plans,     T::Array[T.untyped]  # Array[TransactionPlan]
       const :divisible, T::Boolean
+      sig { returns(Symbol) }
       def kind = :sequential
     end
 
     class ParallelTransactionPlan < T::Struct
+      extend T::Sig
+
       const :plans, T::Array[T.untyped]  # Array[TransactionPlan]
+      sig { returns(Symbol) }
       def kind = :parallel
     end
 

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

@@ -9,6 +9,8 @@ module Solana::Ruby::Kit
   module InstructionPlans
     extend T::Sig
 
+    module_function
+
     # Creates a TransactionPlanExecutor — a callable that traverses a TransactionPlan,
     # executing each single transaction message and collecting results.
     #
@@ -48,7 +50,7 @@ module Solana::Ruby::Kit
           )
           # Store the full result tree as a non-enumerable attribute for recovery.
           err.instance_variable_set(:@transaction_plan_result, result)
-          err.define_singleton_method(:transaction_plan_result) { @transaction_plan_result }
+          err.define_singleton_method(:transaction_plan_result) { result }
           Kernel.raise err
         end
 
@@ -56,12 +58,63 @@ module Solana::Ruby::Kit
       }
     end
 
-    module_function :create_transaction_plan_executor
+    # Creates a TransactionPlanExecutor that processes every leaf concurrently.
+    #
+    # It takes the same configuration as +create_transaction_plan_executor+ and its
+    # +execute_transaction_message+ callback follows the same contract: it receives a fresh
+    # mutable +context+ Hash for every leaf and returns the Hash a successful result should
+    # carry. On success the two are merged with the returned value winning; when the callback
+    # raises, the context accumulated so far is preserved on the failed result. The legacy
+    # one-argument callable shape is accepted here too.
+    #
+    # The difference is the traversal. This executor preserves the input plan's nesting, order
+    # and divisibility in the returned result, but it does not enforce the execution
+    # dependencies expressed by sequential plans: every leaf is started immediately, each on
+    # its own thread, with no concurrency limit. That makes it suitable for work that can be
+    # performed independently, such as signing or serializing transactions. For the same
+    # reason a callback that raises does not cancel the other leaves — each one runs to
+    # completion — and non-divisible sequential plans are supported rather than rejected.
+    #
+    # Once every leaf has settled, a result tree containing any failure raises
+    # INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN carrying the complete tree on its
+    # +transaction_plan_result+ reader.
+    #
+    # Because each leaf runs on its own thread, the callback must be safe to run concurrently
+    # with itself. Each leaf gets its own context Hash, so the contexts do not need guarding,
+    # but anything the callback shares between invocations does.
+    #
+    # Mirrors `createTransactionPlanExecutorWithConcurrentLeaves(config)` from
+    # @solana/instruction-plans.
+    # NOTE: Ruby translation has no abort signal; leaves are never canceled, only failed.
+    sig { params(execute_transaction_message: T.untyped).returns(T.untyped) }
+    def create_transaction_plan_executor_with_concurrent_leaves(execute_transaction_message:)
+      ->(transaction_plan) {
+        # Traversal spawns every leaf's thread on the way down and returns a tree of thunks;
+        # resolving them afterwards is what joins the threads, so all leaves are already in
+        # flight before the first one is waited on.
+        result = concurrent_executor_traverse(transaction_plan, execute_transaction_message).call
+
+        cause = executor_find_error(result)
+        if cause
+          err = SolanaError.new(
+            SolanaError::INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN,
+            { cause: cause }
+          )
+          err.instance_variable_set(:@transaction_plan_result, result)
+          err.define_singleton_method(:transaction_plan_result) { result }
+          Kernel.raise err
+        end
+
+        result
+      }
+    end
 
     # ── Private helpers ────────────────────────────────────────────────────────
 
     module_function
 
+    sig { params(plan: T.untyped, execute_fn: T.untyped, state: T.untyped).returns(T.untyped) }
+
     def executor_traverse(plan, execute_fn, state)
       case plan.kind
       when :sequential then executor_traverse_sequential(plan, execute_fn, state)
@@ -75,6 +128,8 @@ module Solana::Ruby::Kit
       end
     end
 
+    sig { params(plan: T.untyped, execute_fn: T.untyped, state: T.untyped).returns(T.untyped) }
+
     def executor_traverse_sequential(plan, execute_fn, state)
       results = plan.plans.map { |sub| executor_traverse(sub, execute_fn, state) }
       plan.divisible \
@@ -82,11 +137,15 @@ module Solana::Ruby::Kit
         : non_divisible_sequential_transaction_plan_result(results)
     end
 
+    sig { params(plan: T.untyped, execute_fn: T.untyped, state: T.untyped).returns(T.untyped) }
+
     def executor_traverse_parallel(plan, execute_fn, state)
       results = plan.plans.map { |sub| executor_traverse(sub, execute_fn, state) }
       parallel_transaction_plan_result(results)
     end
 
+    sig { params(plan: T.untyped, execute_fn: T.untyped, state: T.untyped).returns(T.untyped) }
+
     def executor_traverse_single(plan, execute_fn, state)
       # A fresh context per single transaction plan. Nothing is populated yet — filling
       # it in is the callback's job, which is what lets a partial context survive an error.
@@ -137,6 +196,60 @@ module Solana::Ruby::Kit
       returned
     end
 
+    # Returns a thunk that resolves to this plan's result. Leaf threads are started as the
+    # tree is walked, so the whole plan is in flight by the time the outermost thunk is called.
+    sig { params(plan: T.untyped, execute_fn: T.untyped).returns(T.untyped) }
+
+    def concurrent_executor_traverse(plan, execute_fn)
+      case plan.kind
+      when :single
+        thread = Thread.new { concurrent_executor_execute_single(plan, execute_fn) }
+        -> { thread.value }
+      when :sequential, :parallel
+        thunks = plan.plans.map { |sub| concurrent_executor_traverse(sub, execute_fn) }
+        Kernel.lambda do
+          results = thunks.map(&:call)
+          if plan.kind == :parallel
+            parallel_transaction_plan_result(results)
+          elsif plan.divisible
+            sequential_transaction_plan_result(results)
+          else
+            # Unlike the sequential executor, non-divisible plans are supported: nothing
+            # about running every leaf independently depends on the plan being divisible.
+            non_divisible_sequential_transaction_plan_result(results)
+          end
+        end
+      else
+        Kernel.raise SolanaError.new(
+          SolanaError::INVARIANT_VIOLATION__INVALID_TRANSACTION_PLAN_KIND,
+          { kind: plan.kind }
+        )
+      end
+    end
+
+    # Runs one leaf. Identical to +executor_traverse_single+ except that a failure is recorded
+    # and nothing else — there is no shared cancellation state for it to trip.
+    sig { params(plan: T.untyped, execute_fn: T.untyped).returns(T.untyped) }
+
+    def concurrent_executor_execute_single(plan, execute_fn)
+      context = {}
+
+      begin
+        returned = executor_invoke(execute_fn, context, plan.message)
+        successful_single_transaction_plan_result(plan.message, nil, context.merge(returned))
+      rescue SolanaError => e
+        failed_single_transaction_plan_result(plan.message, e, context)
+      rescue => e
+        wrapped = SolanaError.new(
+          SolanaError::INSTRUCTION_PLANS__FAILED_TO_EXECUTE_TRANSACTION_PLAN,
+          { cause: e }
+        )
+        failed_single_transaction_plan_result(plan.message, wrapped, context)
+      end
+    end
+
+    sig { params(result: T.untyped).returns(T.untyped) }
+
     def executor_find_error(result)
       return result.status.error if result.kind == :single && result.status.kind == :failed
       return nil                 if result.kind == :single
@@ -154,5 +267,7 @@ module Solana::Ruby::Kit
     private_class_method :executor_traverse_single
     private_class_method :executor_invoke
     private_class_method :executor_find_error
+    private_class_method :concurrent_executor_traverse
+    private_class_method :concurrent_executor_execute_single
   end
 end

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

@@ -21,38 +21,56 @@ module Solana::Ruby::Kit
     # the result. Mirrors TypeScript's TransactionPlanResultStatus union.
 
     class SuccessfulStatus < T::Struct
+      extend T::Sig
+
       const :transaction, T.nilable(Transactions::Transaction)
       const :context,     T::Hash[T.untyped, T.untyped]
+      sig { returns(Symbol) }
       def kind = :successful
     end
 
     class FailedStatus < T::Struct
+      extend T::Sig
+
       const :error,   SolanaError
       const :context, T::Hash[T.untyped, T.untyped], default: {}.freeze
+      sig { returns(Symbol) }
       def kind = :failed
     end
 
     class CanceledStatus < T::Struct
+      extend T::Sig
+
       const :context, T::Hash[T.untyped, T.untyped], default: {}.freeze
+      sig { returns(Symbol) }
       def kind = :canceled
     end
 
     # ── Result plan types ──────────────────────────────────────────────────────
 
     class SingleTransactionPlanResult < T::Struct
+      extend T::Sig
+
       const :message, TransactionMessages::TransactionMessage
       const :status,  T.untyped  # SuccessfulStatus | FailedStatus | CanceledStatus
+      sig { returns(Symbol) }
       def kind = :single
     end
 
     class SequentialTransactionPlanResult < T::Struct
+      extend T::Sig
+
       const :plans,     T::Array[T.untyped]  # Array[TransactionPlanResult]
       const :divisible, T::Boolean
+      sig { returns(Symbol) }
       def kind = :sequential
     end
 
     class ParallelTransactionPlanResult < T::Struct
+      extend T::Sig
+
       const :plans, T::Array[T.untyped]  # Array[TransactionPlanResult]
+      sig { returns(Symbol) }
       def kind = :parallel
     end
 

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

@@ -11,6 +11,8 @@ module Solana::Ruby::Kit
   module InstructionPlans
     extend T::Sig
 
+    module_function
+
     # Creates a TransactionPlanner — a callable that converts an InstructionPlan
     # into a TransactionPlan by packing instructions into transaction messages.
     #
@@ -67,12 +69,12 @@ module Solana::Ruby::Kit
       }
     end
 
-    module_function :create_transaction_planner
-
     # ── Private helpers ────────────────────────────────────────────────────────
 
     module_function
 
+    sig { params(plan: T.untyped, ctx: T.untyped).returns(T.untyped) }
+
     def planner_traverse(plan, ctx)
       case plan.kind
       when :sequential     then planner_traverse_sequential(plan, ctx)
@@ -87,6 +89,8 @@ module Solana::Ruby::Kit
       end
     end
 
+    sig { params(plan: T.untyped, ctx: T.untyped).returns(T.untyped) }
+
     def planner_traverse_sequential(plan, ctx)
       must_fit_in_parent = ctx[:parent] && (ctx[:parent].kind == :parallel || !plan.divisible)
 
@@ -118,6 +122,8 @@ module Solana::Ruby::Kit
       { kind: :sequential, divisible: plan.divisible, plans: tx_plans }
     end
 
+    sig { params(plan: T.untyped, ctx: T.untyped).returns(T.untyped) }
+
     def planner_traverse_parallel(plan, ctx)
       candidates = ctx[:parent_candidates].dup
       tx_plans   = []
@@ -139,6 +145,8 @@ module Solana::Ruby::Kit
       { kind: :parallel, plans: tx_plans }
     end
 
+    sig { params(plan: T.untyped, ctx: T.untyped).returns(T.untyped) }
+
     def planner_traverse_single(plan, ctx)
       predicate = ->(msg) { TransactionMessages.append_instructions(msg, [plan.instruction]) }
       candidate = planner_select_and_mutate_candidate(ctx, ctx[:parent_candidates], &predicate)
@@ -148,6 +156,8 @@ module Solana::Ruby::Kit
       { kind: :single, message: msg }
     end
 
+    sig { params(plan: T.untyped, ctx: T.untyped).returns(T.untyped) }
+
     def planner_traverse_message_packer(plan, ctx)
       packer     = plan.get_message_packer.call
       tx_plans   = []
@@ -175,6 +185,8 @@ module Solana::Ruby::Kit
       end
     end
 
+    sig { params(ctx: T.untyped, candidates: T.untyped, predicate: T.proc.params(arg0: T.untyped).returns(T.untyped)).returns(T.untyped) }
+
     def planner_select_and_mutate_candidate(ctx, candidates, &predicate)
       candidates.each do |candidate|
         begin
@@ -198,6 +210,8 @@ module Solana::Ruby::Kit
       nil
     end
 
+    sig { params(ctx: T.untyped, predicate: T.proc.params(arg0: T.untyped).returns(T.untyped)).returns(T.untyped) }
+
     def planner_create_new_message(ctx, &predicate)
       new_msg      = ctx[:create_transaction_message].call
       updated_msg  = ctx[:on_transaction_message_updated].call(predicate.call(new_msg))
@@ -220,6 +234,8 @@ module Solana::Ruby::Kit
       updated_msg
     end
 
+    sig { params(plan: T.untyped, message: T.untyped, ctx: T.untyped).returns(T.untyped) }
+
     def planner_fit_entire_plan(plan, message, ctx)
       case plan.kind
       when :sequential, :parallel
@@ -259,17 +275,23 @@ module Solana::Ruby::Kit
       end
     end
 
+    sig { params(plan: T.untyped).returns(T.untyped) }
+
     def planner_get_sequential_candidate(plan)
       return plan if plan[:kind] == :single
       return nil  unless plan[:kind] == :sequential && plan[:plans]&.any?
       planner_get_sequential_candidate(plan[:plans].last)
     end
 
+    sig { params(plan: T.untyped).returns(T.untyped) }
+
     def planner_get_parallel_candidates(plan)
       return [plan] if plan[:kind] == :single
       (plan[:plans] || []).flat_map { |p| planner_get_parallel_candidates(p) }
     end
 
+    sig { params(plan: T.untyped).returns(T.untyped) }
+
     def planner_freeze(plan)
       case plan[:kind]
       when :single

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

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative 'has_transport'
+
 require 'base64'
 require_relative '../../rpc_types/account_info'
 
@@ -16,6 +18,9 @@ module Solana::Ruby::Kit
       #            (nil when the account does not exist)
       module GetAccountInfo
         extend T::Sig
+        extend T::Helpers
+
+        requires_ancestor { HasTransport }
 
         SUPPORTED_ENCODINGS = T.let(%w[base64 jsonParsed base64+zstd].freeze, T::Array[String])
 

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

@@ -0,0 +1,72 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'has_transport'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # The block an Alpenglow genesis certificate certifies.
+      AgGenesisCertBlock = T.let(
+        Struct.new(
+          :block_id, # Array<Integer> — block id of the certified block, as a 32-byte array
+          :slot,     # Integer — slot of the certified block
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # The aggregate signature over an Alpenglow genesis certificate.
+      AgGenesisCertSignature = T.let(
+        Struct.new(
+          :bitmap,    # Array<Integer> — ranks of the validators in the aggregate signature
+          :signature, # Array<Integer> — the 192-byte aggregate BLS signature
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # The Alpenglow genesis certificate, as gossiped between validators.
+      # Mirrors the `WireBlockCertMessage` type in the Agave validator.
+      AgGenesisCert = T.let(
+        Struct.new(
+          :block,     # AgGenesisCertBlock
+          :signature, # AgGenesisCertSignature
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # Returns the Alpenglow genesis certificate — the certificate over the block at which the
+      # Alpenglow consensus protocol was activated — or nil if the node does not have one.
+      # Mirrors TypeScript's GetAgGenesisCertApi.getAgGenesisCert.
+      # @see https://solana.com/docs/rpc/http/getaggenesiscert
+      module GetAgGenesisCert
+        extend T::Sig
+        extend T::Helpers
+
+        requires_ancestor { HasTransport }
+
+        sig { returns(T.untyped) }
+        def get_ag_genesis_cert
+          raw = transport.request('getAgGenesisCert', [])
+          return nil if raw.nil?
+
+          block     = raw['block'] || {}
+          signature = raw['signature'] || {}
+
+          AgGenesisCert.new(
+            block:     AgGenesisCertBlock.new(
+              block_id: Kernel.Array(block['blockId']).map { |b| Kernel.Integer(b) },
+              slot:     Kernel.Integer(block['slot'])
+            ),
+            signature: AgGenesisCertSignature.new(
+              bitmap:    Kernel.Array(signature['bitmap']).map { |b| Kernel.Integer(b) },
+              signature: Kernel.Array(signature['signature']).map { |b| Kernel.Integer(b) }
+            )
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative 'has_transport'
 require_relative '../../rpc_types/account_info'
 
 module Solana::Ruby::Kit
@@ -14,6 +15,9 @@ module Solana::Ruby::Kit
       #   .value — Integer (lamports)
       module GetBalance
         extend T::Sig
+        extend T::Helpers
+
+        requires_ancestor { HasTransport }
 
         sig do
           params(

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

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative 'has_transport'
+
 module Solana::Ruby::Kit
   module Rpc
     module Api
@@ -8,6 +10,9 @@ module Solana::Ruby::Kit
       # Mirrors TypeScript's `GetBlockHeightApi.getBlockHeight(config?)`.
       module GetBlockHeight
         extend T::Sig
+        extend T::Helpers
+
+        requires_ancestor { HasTransport }
 
         sig do
           params(

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

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require_relative 'has_transport'
+
 module Solana::Ruby::Kit
   module Rpc
     module Api
@@ -8,6 +10,9 @@ module Solana::Ruby::Kit
       # Mirrors TypeScript's GetBlockTimeApi.getBlockTime.
       module GetBlockTime
         extend T::Sig
+        extend T::Helpers
+
+        requires_ancestor { HasTransport }
 
         sig { params(slot: Integer).returns(T.nilable(Integer)) }
         def get_block_time(slot)