solana-ruby-kit 0.1.0

data/lib/solana/ruby/kit/offchain_messages/message.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module OffchainMessages
+    # An off-chain message ready for signing.
+    # Mirrors the OffchainMessage type from @solana/signers.
+    class Message < T::Struct
+      # Header version: 0 = legacy ASCII, 1 = extended UTF-8.
+      const :version, Integer
+
+      # Application domain (up to 255 bytes).
+      const :domain, String
+
+      # UTF-8 message body.
+      const :message, String
+
+      # Optional application-specific domain (version ≥ 1 only).
+      const :application_domain, T.nilable(String), default: nil
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+
+# Mirrors @solana/signers off-chain message signing.
+require_relative 'offchain_messages/message'
+require_relative 'offchain_messages/codec'
+
+module Solana::Ruby::Kit
+  module OffchainMessages
+    # Re-export codec helpers at module level for convenience.
+    extend T::Sig
+    extend Codec
+  end
+end

data/lib/solana/ruby/kit/options/option.rb

@@ -0,0 +1,132 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Options
+    extend T::Sig
+    # Mirrors Rust's `Option<T>` pattern from @solana/options.
+    #
+    # TypeScript represents absence as `T | null`, but that collapses nested
+    # options: `Option<Option<T>>` becomes indistinguishable from `Option<T>`.
+    # This explicit discriminated union preserves that distinction.
+
+    # Represents the presence of a value — mirrors TypeScript's `Some<T>`.
+    class Some
+      extend T::Sig
+      extend T::Generic
+
+      Elem = type_member
+
+      sig { returns(Elem) }
+      attr_reader :value
+
+      sig { params(value: Elem).void }
+      def initialize(value)
+        @value = T.let(value, Elem)
+      end
+
+      sig { returns(String) }
+      def inspect = "Some(#{T.unsafe(@value).inspect})"
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        !!(other.is_a?(Some) && T.unsafe(value) == T.unsafe(other.value))
+      end
+    end
+
+    # Represents the absence of a value — mirrors TypeScript's `None`.
+    class None
+      extend T::Sig
+
+      INSTANCE = T.let(new, None)
+
+      sig { returns(String) }
+      def inspect = 'None'
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other) = other.is_a?(None)
+    end
+
+    # Sorbet type alias: Option<T> is either Some or None.
+    # Because Sorbet generics on non-class types are limited, we use T.untyped
+    # for the contained value at the type-alias level; callers rely on Some's
+    # generic parameter for per-use type safety.
+    Option = T.type_alias { T.any(Solana::Ruby::Kit::Options::Some[T.untyped], None) }
+
+    # OptionOrNullable mirrors TypeScript's `OptionOrNullable<T>`:
+    #   accepts Option<T>, T, or nil — useful for codec input.
+    OptionOrNullable = T.type_alias { T.untyped }
+
+    module_function
+
+    # Wraps a value in Some.  Mirrors `some<T>(value)`.
+    sig { params(value: T.untyped).returns(Solana::Ruby::Kit::Options::Some[T.untyped]) }
+    def some(value)
+      Some.new(value)
+    end
+
+    # Returns the singleton None instance.  Mirrors `none<T>()`.
+    sig { returns(None) }
+    def none
+      None::INSTANCE
+    end
+
+    # Returns true if the value is an Option (Some or None).
+    # Mirrors `isOption()`.
+    sig { params(input: T.untyped).returns(T::Boolean) }
+    def option?(input)
+      input.is_a?(Some) || input.is_a?(None)
+    end
+
+    # Returns true if the option contains a value.
+    # Mirrors `isSome()`.
+    sig { params(opt: T.untyped).returns(T::Boolean) }
+    def some?(opt)
+      opt.is_a?(Some)
+    end
+
+    # Returns true if the option is empty.
+    # Mirrors `isNone()`.
+    sig { params(opt: T.untyped).returns(T::Boolean) }
+    def none?(opt)
+      opt.is_a?(None)
+    end
+
+    # Extracts the contained value, or returns a fallback.
+    # Mirrors `unwrapOption(option, fallback?)`.
+    #
+    # @param opt      [Some, None]
+    # @param fallback [Proc, nil] called when opt is None; returns nil if omitted
+    sig { params(opt: T.untyped, fallback: T.nilable(T.proc.returns(T.untyped))).returns(T.untyped) }
+    def unwrap_option(opt, fallback = nil)
+      return opt.value if opt.is_a?(Some)
+
+      fallback ? fallback.call : nil
+    end
+
+    # Wraps a nullable (nil-able) value into an Option.
+    # Mirrors `wrapNullable()`.
+    sig { params(nullable: T.untyped).returns(T.any(Solana::Ruby::Kit::Options::Some[T.untyped], None)) }
+    def wrap_nullable(nullable)
+      nullable.nil? ? none : some(nullable)
+    end
+
+    # Recursively unwraps nested Options within objects, arrays, and hashes.
+    # Mirrors `unwrapOptionRecursively()`.
+    #
+    # Primitives (Integer, Float, String, Symbol, true, false) and
+    # binary/typed-array equivalents are returned as-is.
+    sig { params(input: T.untyped, fallback: T.nilable(T.proc.returns(T.untyped))).returns(T.untyped) }
+    def unwrap_option_recursively(input, fallback = nil)
+      nxt = ->(x) { unwrap_option_recursively(x, fallback) }
+
+      case input
+      when Some then nxt.call(input.value)
+      when None then fallback ? fallback.call : nil
+      when Array then input.map { |el| nxt.call(el) }
+      when Hash  then input.transform_values { |v| nxt.call(v) }
+      else input   # primitives and opaque objects pass through
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Option<T> type utilities — mirrors @solana/options.
+require_relative 'options/option'

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

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Mirrors @solana/rpc-types plugin-core pattern (createEmptyClient / use).
+#
+# A PluginClient starts empty and is extended incrementally via #use.
+# Each plugin is a callable that receives the current client and returns a
+# Hash of { method_name => callable } which is merged into the client.
+#
+#   client = Solana::Ruby::Kit::PluginCore.create_client
+#             .use(Solana::Ruby::Kit::Rpc::Api::ALL_METHODS)
+#
+module Solana::Ruby::Kit
+  class PluginClient
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @methods = T.let({}, T::Hash[Symbol, T.proc.params(args: T.untyped).returns(T.untyped)])
+    end
+
+    # Apply +plugin+ and return a new PluginClient with the additional methods.
+    # +plugin+ may be:
+    #   - a Hash of { symbol => callable }
+    #   - a callable that receives self and returns such a Hash
+    sig { params(plugin: T.untyped).returns(PluginClient) }
+    def use(plugin)
+      new_methods = plugin.respond_to?(:call) ? plugin.call(self) : plugin
+      extended    = PluginClient.new
+      extended.instance_variable_set(:@methods, @methods.merge(new_methods.transform_keys(&:to_sym)))
+      extended
+    end
+
+    sig { params(name: Symbol, args: T.untyped, block: T.untyped).returns(T.untyped) }
+    def method_missing(name, *args, &block)
+      m = @methods[name]
+      return super unless m
+
+      T.unsafe(m).call(*args, &block)
+    end
+
+    sig { params(name: Symbol, include_private: T::Boolean).returns(T::Boolean) }
+    def respond_to_missing?(name, include_private = false)
+      @methods.key?(name) || super
+    end
+  end
+
+  module PluginCore
+    extend T::Sig
+
+    module_function
+
+    sig { returns(PluginClient) }
+    def create_client
+      PluginClient.new
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Mirrors @solana/programs — helpers for inspecting custom program errors
+# returned in Solana transaction failures.
+#
+# A program error in a transaction result looks like:
+#   { "InstructionError" => [0, { "Custom" => 1234 }] }
+module Solana::Ruby::Kit
+  module Programs
+    extend T::Sig
+
+    module_function
+
+    # Returns true when +err+ is a custom program error, optionally matching
+    # a specific error code.
+    sig { params(err: T.untyped, expected_code: T.nilable(Integer)).returns(T::Boolean) }
+    def program_error?(err, expected_code: nil)
+      code = get_program_error_code(err)
+      return false if code.nil?
+
+      expected_code ? code == expected_code : true
+    end
+
+    # Extract the custom program error code from a transaction error hash.
+    # Returns nil when the error is not a custom program error.
+    sig { params(err: T.untyped).returns(T.nilable(Integer)) }
+    def get_program_error_code(err)
+      return nil unless err.is_a?(Hash)
+
+      instruction_error = err['InstructionError']
+      return nil unless instruction_error.is_a?(Array) && instruction_error.length == 2
+
+      inner = instruction_error[1]
+      return nil unless inner.is_a?(Hash) && inner.key?('Custom')
+
+      Kernel.Integer(inner['Custom'])
+    rescue TypeError, ArgumentError
+      nil
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'timeout'
+
+# Mirrors @solana/promises.
+# Provides thread-safe race and timeout helpers used by the RPC subscription
+# transport layer.  Ruby threads replace JavaScript Promises throughout.
+module Solana::Ruby::Kit
+  module Promises
+    extend T::Sig
+
+    module_function
+
+    # Run each callable in a dedicated thread and return the first result.
+    # All losing threads are killed to avoid memory leaks — analogous to the
+    # JS safeRace() that cancels losing promises via AbortSignal.
+    #
+    # @param callables [Array<#call>]  lambdas / procs to race
+    # @param timeout_secs [Float, nil] optional wall-clock limit
+    # @return the return value of whichever callable finishes first
+    # @raise [Timeout::Error] if timeout_secs is reached before any finishes
+    # @raise propagates any exception thrown by the winning callable
+    sig do
+      params(
+        callables:    T::Array[T.proc.returns(T.untyped)],
+        timeout_secs: T.nilable(Float)
+      ).returns(T.untyped)
+    end
+    def safe_race(callables, timeout_secs: nil)
+      result_q   = Queue.new
+      threads    = callables.map do |callable|
+        Thread.new do
+          value = callable.call
+          result_q.push([:ok, value])
+        rescue StandardError => e
+          result_q.push([:err, e])
+        end
+      end
+
+      begin
+        kind, payload = if timeout_secs
+                         Timeout.timeout(timeout_secs) { result_q.pop }
+                       else
+                         result_q.pop
+                       end
+      ensure
+        threads.each(&:kill)
+      end
+
+      Kernel.raise payload if kind == :err
+
+      payload
+    end
+
+    # Execute +block+ with an optional wall-clock deadline.
+    # When +secs+ is nil the block runs without any deadline.
+    #
+    # @param secs [Float, nil]
+    # @raise [Timeout::Error] on deadline exceeded
+    sig do
+      type_parameters(:R)
+        .params(secs: T.nilable(Float), block: T.proc.returns(T.type_parameter(:R)))
+        .returns(T.type_parameter(:R))
+    end
+    def with_timeout(secs, &block)
+      if secs
+        Timeout.timeout(secs) { block.call }
+      else
+        yield
+      end
+    end
+
+    # Returns a lambda that, when called, raises Timeout::Error.
+    # Useful for constructing an "abort signal" from a deadline.
+    sig { params(secs: Float).returns(T.proc.void) }
+    def make_abort_signal(secs)
+      start = T.let(Time.now, Time)
+      Kernel.lambda do
+        elapsed = Time.now - start
+        Kernel.raise Timeout::Error, "Aborted after #{elapsed.round(2)}s" if elapsed >= secs
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# typed: ignore
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  class Railtie < Rails::Railtie
+    config.solana_ruby_kit = ActiveSupport::OrderedOptions.new
+
+    initializer 'solana_ruby_kit.configure' do |app|
+      opts = app.config.solana_ruby_kit
+      Solana::Ruby::Kit.configure do |c|
+        c.rpc_url    = opts.rpc_url    if opts.rpc_url
+        c.ws_url     = opts.ws_url     if opts.ws_url
+        c.commitment = opts.commitment if opts.commitment
+        c.timeout    = opts.timeout    if opts.timeout
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require_relative '../../rpc_types/account_info'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Fetches all stored information for an account at the given address.
+      # Mirrors TypeScript's `GetAccountInfoApi.getAccountInfo(address, config?)`.
+      #
+      # Returns a `RpcContextualValue` with:
+      #   .slot  — context slot
+      #   .value — AccountInfoWithBase64Data | AccountInfoWithJsonData | nil
+      #            (nil when the account does not exist)
+      module GetAccountInfo
+        extend T::Sig
+
+        SUPPORTED_ENCODINGS = T.let(%w[base64 jsonParsed base64+zstd].freeze, T::Array[String])
+
+        sig do
+          params(
+            address:          String,
+            encoding:         String,
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer),
+            data_slice:       T.nilable(T::Hash[String, Integer])
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def get_account_info(
+          address,
+          encoding:         'base64',
+          commitment:       nil,
+          min_context_slot: nil,
+          data_slice:       nil
+        )
+          config = { 'encoding' => encoding }
+          config['commitment']      = commitment.to_s if commitment
+          config['minContextSlot']  = min_context_slot if min_context_slot
+          config['dataSlice']       = data_slice if data_slice
+
+          result = transport.request('getAccountInfo', [address, config])
+
+          slot = Kernel.Integer(result['context']['slot'])
+          raw  = result['value']
+
+          value =
+            if raw.nil?
+              nil
+            elsif encoding == 'jsonParsed'
+              RpcTypes::AccountInfoWithJsonData.new(
+                executable: raw['executable'],
+                lamports:   Kernel.Integer(raw['lamports']),
+                owner:      raw['owner'],
+                space:      Kernel.Integer(raw.fetch('space', 0)),
+                rent_epoch: Kernel.Integer(raw.fetch('rentEpoch', 0)),
+                data:       raw['data']
+              )
+            else
+              RpcTypes::AccountInfoWithBase64Data.new(
+                executable: raw['executable'],
+                lamports:   Kernel.Integer(raw['lamports']),
+                owner:      raw['owner'],
+                space:      Kernel.Integer(raw.fetch('space', 0)),
+                rent_epoch: Kernel.Integer(raw.fetch('rentEpoch', 0)),
+                data:       Kernel.Array(raw['data'])
+              )
+            end
+
+          RpcTypes::RpcContextualValue.new(slot: slot, value: value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../../rpc_types/account_info'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Returns the lamport balance of an account.
+      # Mirrors TypeScript's `GetBalanceApi.getBalance(address, config?)`.
+      #
+      # Returns a `RpcContextualValue` with:
+      #   .slot  — the slot at which the balance was read
+      #   .value — Integer (lamports)
+      module GetBalance
+        extend T::Sig
+
+        sig do
+          params(
+            address:          String,
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer)
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def get_balance(address, commitment: nil, min_context_slot: nil)
+          config = {}
+          config['commitment']      = commitment.to_s if commitment
+          config['minContextSlot']  = min_context_slot if min_context_slot
+
+          params = config.empty? ? [address] : [address, config]
+          result = transport.request('getBalance', params)
+
+          RpcTypes::RpcContextualValue.new(
+            slot:  Kernel.Integer(result['context']['slot']),
+            value: Kernel.Integer(result['value'])
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Returns the current block height of the node.
+      # Mirrors TypeScript's `GetBlockHeightApi.getBlockHeight(config?)`.
+      module GetBlockHeight
+        extend T::Sig
+
+        sig do
+          params(
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer)
+          ).returns(Integer)
+        end
+        def get_block_height(commitment: nil, min_context_slot: nil)
+          config = {}
+          config['commitment']      = commitment.to_s if commitment
+          config['minContextSlot']  = min_context_slot if min_context_slot
+
+          params = config.empty? ? [] : [config]
+          Kernel.Integer(transport.request('getBlockHeight', params))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Struct returned by get_epoch_info.
+      EpochInfo = T.let(
+        Struct.new(
+          :absolute_slot,       # Integer — current slot
+          :block_height,        # Integer
+          :epoch,               # Integer — current epoch
+          :slot_index,          # Integer — slot within current epoch
+          :slots_in_epoch,      # Integer — total slots in epoch
+          :transaction_count,   # Integer | nil
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # Fetch information about the current epoch.
+      # Mirrors TypeScript's GetEpochInfoApi.getEpochInfo.
+      module GetEpochInfo
+        extend T::Sig
+
+        sig do
+          params(commitment: T.nilable(Symbol)).returns(T.untyped)
+        end
+        def get_epoch_info(commitment: nil)
+          config = {}
+          config['commitment'] = commitment.to_s if commitment
+
+          raw = transport.request('getEpochInfo', config.empty? ? [] : [config])
+
+          EpochInfo.new(
+            absolute_slot:     Kernel.Integer(raw['absoluteSlot']),
+            block_height:      Kernel.Integer(raw['blockHeight']),
+            epoch:             Kernel.Integer(raw['epoch']),
+            slot_index:        Kernel.Integer(raw['slotIndex']),
+            slots_in_epoch:    Kernel.Integer(raw['slotsInEpoch']),
+            transaction_count: raw['transactionCount'] ? Kernel.Integer(raw['transactionCount']) : nil
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../../rpc_types/account_info'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # The payload returned by getLatestBlockhash.
+      # Mirrors TypeScript's `GetLatestBlockhashApiResponse`.
+      class LatestBlockhash < T::Struct
+        const :blockhash,               String   # base58-encoded 32 bytes
+        const :last_valid_block_height, Integer  # TypeScript bigint → Ruby Integer
+      end
+
+      # Returns the latest blockhash and its expiry block height.
+      # Mirrors TypeScript's `GetLatestBlockhashApi.getLatestBlockhash(config?)`.
+      #
+      # Returns a `RpcContextualValue` with:
+      #   .slot  — context slot
+      #   .value — LatestBlockhash
+      module GetLatestBlockhash
+        extend T::Sig
+
+        sig do
+          params(
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer)
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def get_latest_blockhash(commitment: nil, min_context_slot: nil)
+          config = {}
+          config['commitment']      = commitment.to_s if commitment
+          config['minContextSlot']  = min_context_slot if min_context_slot
+
+          params = config.empty? ? [] : [config]
+          result = transport.request('getLatestBlockhash', params)
+
+          value = LatestBlockhash.new(
+            blockhash:               result['value']['blockhash'],
+            last_valid_block_height: Kernel.Integer(result['value']['lastValidBlockHeight'])
+          )
+
+          RpcTypes::RpcContextualValue.new(
+            slot:  Kernel.Integer(result['context']['slot']),
+            value: value
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Returns the minimum balance required to keep an account rent-exempt
+      # given its data size in bytes.
+      # Mirrors `GetMinimumBalanceForRentExemptionApi.getMinimumBalanceForRentExemption()`.
+      module GetMinimumBalanceForRentExemption
+        extend T::Sig
+
+        sig do
+          params(
+            data_size:  Integer,
+            commitment: T.nilable(Symbol)
+          ).returns(Integer)
+        end
+        def get_minimum_balance_for_rent_exemption(data_size, commitment: nil)
+          config = {}
+          config['commitment'] = commitment.to_s if commitment
+
+          params = config.empty? ? [data_size] : [data_size, config]
+          Kernel.Integer(transport.request('getMinimumBalanceForRentExemption', params))
+        end
+      end
+    end
+  end
+end