solana-ruby-kit 7.1.1.2 → 8.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a30b73ebab9578e0345910ab3f7d019cb6cacc9840797abfb8a177a3de9b2bb
-  data.tar.gz: e540ed2b2b3cc1bb87a5f584b587d1ea4f86cad324c04385311289501ce48cf7
+  metadata.gz: ba7d2659d83b01af6565c7af483364d61e61fcc9761cbca9d63d8d41f6b4d73a
+  data.tar.gz: bd8402f845e9d8db5845be0e358676d00e308b2a0777afc1973e8814175e1c1c
 SHA512:
-  metadata.gz: 29728a4e25c5f9d7dabd89e75cb9fd2b583f03930b6640c48c68ff070e90e06345bbfa75d636383dda51c9dc8044f9942f4a299866f39f8b93189f832fbf03a6
-  data.tar.gz: 04c68d1f2e6f249c4be788e1c9e6919b056f9780eebd5a26bb6dc8aae6b15ceafe7838d39ed6af4ba24269ebdc5cbdd4cc028f8947db842631aace626750df45
+  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
@@ -207,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',

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

@@ -58,6 +58,57 @@ module Solana::Ruby::Kit
       }
     end
 
+    # 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
@@ -145,6 +196,58 @@ 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)
@@ -164,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/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/client.rb

@@ -7,6 +7,7 @@ require_relative 'api/get_slot'
 require_relative 'api/get_balance'
 require_relative 'api/get_latest_blockhash'
 require_relative 'api/get_account_info'
+require_relative 'api/get_ag_genesis_cert'
 require_relative 'api/get_block_height'
 require_relative 'api/get_signature_statuses'
 require_relative 'api/send_transaction'
@@ -51,6 +52,7 @@ module Solana::Ruby::Kit
       include Api::GetBalance
       include Api::GetLatestBlockhash
       include Api::GetAccountInfo
+      include Api::GetAgGenesisCert
       include Api::GetBlockHeight
       include Api::GetSignatureStatuses
       include Api::SendTransaction

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

@@ -4,6 +4,7 @@
 require_relative '../addresses/address'
 require_relative '../instructions/instruction'
 require_relative 'transaction_message'
+require_relative 'resource_limit_validation'
 
 module Solana::Ruby::Kit
   module TransactionMessages
@@ -63,6 +64,7 @@ module Solana::Ruby::Kit
     # SetComputeUnitLimit instruction. Mirrors `setTransactionMessageComputeUnitLimit`.
     sig { params(limit: Integer, message: TransactionMessage).returns(TransactionMessage) }
     def set_transaction_message_compute_unit_limit(limit, message)
+      assert_is_valid_compute_unit_limit(limit)
       existing_idx = message.instructions.index { |i| set_compute_unit_limit_instruction?(i) }
       new_ix = get_set_compute_unit_limit_instruction(limit)
 

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

@@ -0,0 +1,70 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  # NOTE: `MAX_COMPUTE_UNIT_LIMIT` lives in `compute_budget.rb`, which requires this file, so it
+  # is referenced from a method body rather than at load time to keep the two files acyclic.
+  module TransactionMessages
+    # The smallest heap frame size that a transaction may request (32 KiB).
+    MIN_HEAP_SIZE = T.let(32 * 1024, Integer)
+
+    # The largest heap frame size that a transaction may request (256 KiB).
+    MAX_HEAP_SIZE = T.let(256 * 1024, Integer)
+
+    # A requested heap frame size must be a whole number of KiB.
+    HEAP_SIZE_MULTIPLE_OF = T.let(1024, Integer)
+
+    module_function
+
+    # Raises if the given compute unit limit is one the runtime will not honor as written.
+    #
+    # A transaction may request at most MAX_COMPUTE_UNIT_LIMIT compute units. Requesting more
+    # does not fail the transaction; the runtime clamps the request down to that maximum, so
+    # the budget the transaction runs with is silently not the one that was asked for. Values
+    # that are not integers are a separate hazard, since they cannot be encoded as a `u32` and
+    # are not clamped. Failing here surfaces both at the point the value is set.
+    #
+    # Mirrors `assertIsValidComputeUnitLimit` from @solana/transaction-messages.
+    sig { params(compute_unit_limit: T.untyped).void }
+    def assert_is_valid_compute_unit_limit(compute_unit_limit)
+      return if compute_unit_limit.is_a?(Integer) &&
+                compute_unit_limit >= 0 &&
+                compute_unit_limit <= MAX_COMPUTE_UNIT_LIMIT
+
+      Kernel.raise SolanaError.new(
+        SolanaError::TRANSACTION__COMPUTE_UNIT_LIMIT_OUT_OF_RANGE,
+        { compute_unit_limit: compute_unit_limit, max_compute_unit_limit: MAX_COMPUTE_UNIT_LIMIT }
+      )
+    end
+
+    # Raises if the given heap frame size is one the runtime will not accept.
+    #
+    # The requested heap size must be a multiple of HEAP_SIZE_MULTIPLE_OF bytes and lie between
+    # MIN_HEAP_SIZE and MAX_HEAP_SIZE inclusive. This mirrors the transaction sanitization check
+    # performed by the runtime.
+    #
+    # Mirrors `assertIsValidHeapSize` from @solana/transaction-messages. Ruby has no heap-size
+    # setter of its own — the `RequestHeapFrame` instruction and the version 1 transaction config
+    # are both untranslated — so this is offered as a standalone check for callers building that
+    # instruction themselves.
+    sig { params(heap_size: T.untyped).void }
+    def assert_is_valid_heap_size(heap_size)
+      return if heap_size.is_a?(Integer) &&
+                heap_size >= MIN_HEAP_SIZE &&
+                heap_size <= MAX_HEAP_SIZE &&
+                (heap_size % HEAP_SIZE_MULTIPLE_OF).zero?
+
+      Kernel.raise SolanaError.new(
+        SolanaError::TRANSACTION__INVALID_HEAP_SIZE,
+        {
+          heap_size:     heap_size,
+          max_heap_size: MAX_HEAP_SIZE,
+          min_heap_size: MIN_HEAP_SIZE,
+          multiple_of:   HEAP_SIZE_MULTIPLE_OF
+        }
+      )
+    end
+  end
+end

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

@@ -3,4 +3,5 @@
 
 # Transaction message construction utilities — mirrors @solana/transaction-messages.
 require_relative 'transaction_messages/transaction_message'
+require_relative 'transaction_messages/resource_limit_validation'
 require_relative 'transaction_messages/compute_budget'

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

@@ -4,7 +4,7 @@
 module Solana
   module Ruby
     module Kit
-      VERSION = '7.1.1.2'
+      VERSION = '8.2.0'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-ruby-kit
 version: !ruby/object:Gem::Version
-  version: 7.1.1.2
+  version: 8.2.0
 platform: ruby
 authors:
 - Paul Zupan, Idhra Inc.
@@ -262,6 +262,7 @@ files:
 - lib/solana/ruby/kit/resource_limit_estimation.rb
 - lib/solana/ruby/kit/rpc.rb
 - lib/solana/ruby/kit/rpc/api/get_account_info.rb
+- lib/solana/ruby/kit/rpc/api/get_ag_genesis_cert.rb
 - lib/solana/ruby/kit/rpc/api/get_balance.rb
 - lib/solana/ruby/kit/rpc/api/get_block_height.rb
 - lib/solana/ruby/kit/rpc/api/get_block_time.rb
@@ -337,6 +338,7 @@ files:
 - 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/resource_limit_validation.rb
 - lib/solana/ruby/kit/transaction_messages/transaction_message.rb
 - lib/solana/ruby/kit/transactions.rb
 - lib/solana/ruby/kit/transactions/compiler.rb