solana-ruby-kit 0.1.0

data/lib/solana/ruby/kit/rpc_subscriptions/subscription.rb

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    # A live subscription to a Solana WebSocket notification channel.
+    # Wraps a DataPublisher channel and exposes an Enumerator interface.
+    #
+    # Typical usage:
+    #   sub = client.slot_subscribe
+    #   sub.take(10).each { |notification| puts notification }
+    #   sub.unsubscribe  # or break from the enumerator loop
+    class Subscription
+      extend T::Sig
+      extend T::Generic
+
+      Elem = type_member { { fixed: T.untyped } }
+
+      sig { returns(T::Enumerator[T.untyped]) }
+      attr_reader :enumerator
+
+      sig do
+        params(
+          enumerator:    T::Enumerator[T.untyped],
+          unsubscribe:   T.proc.void,
+          timeout:       T.nilable(Float)
+        ).void
+      end
+      def initialize(enumerator:, unsubscribe:, timeout: nil)
+        @enumerator  = enumerator
+        @unsubscribe = unsubscribe
+        @timeout     = timeout
+      end
+
+      # Stop the subscription and clean up.
+      sig { void }
+      def unsubscribe
+        @unsubscribe.call
+      end
+
+      # Delegate Enumerable methods to the enumerator for convenience.
+      sig { override.params(block: T.proc.params(item: T.untyped).void).void }
+      def each(&block)
+        @enumerator.each(&block)
+      ensure
+        unsubscribe
+      end
+
+      sig { params(n: Integer).returns(T::Array[T.untyped]) }
+      def take(n) = @enumerator.take(n)
+
+      sig { returns(T.untyped) }
+      def next = @enumerator.next
+
+      include Enumerable
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'websocket-client-simple'
+require 'json'
+require 'thread'
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    # WebSocket JSON-RPC transport for Solana subscription methods.
+    # Runs in a background thread; dispatches incoming messages to a
+    # DataPublisher keyed by subscription ID.
+    #
+    # Thread safety: all public methods are Mutex-protected.
+    class Transport
+      extend T::Sig
+
+      # Channel name used for raw incoming messages (before routing to sub-ID).
+      MESSAGE_CHANNEL = T.let(:__message__, Symbol)
+      ERROR_CHANNEL   = T.let(:error, Symbol)
+      CLOSE_CHANNEL   = T.let(:close, Symbol)
+
+      sig { returns(String) }
+      attr_reader :url
+
+      sig do
+        params(
+          url:                         String,
+          headers:                     T::Hash[String, String],
+          send_buffer_high_watermark:  Integer
+        ).void
+      end
+      def initialize(url:, headers: {}, send_buffer_high_watermark: 40)
+        @url        = url
+        @headers    = headers
+        @hwm        = send_buffer_high_watermark
+        @mutex      = T.let(Mutex.new, Mutex)
+        @id_seq     = T.let(0, Integer)
+        @pending     = T.let({}, T::Hash[Integer, Queue])   # request id → response Queue
+        @subscribers = T.let(
+          Hash.new { |h, k| h[k] = [] },
+          T::Hash[T.untyped, T::Array[T.proc.params(msg: T::Hash[String, T.untyped]).void]]
+        )
+        @send_buffer  = T.let([], T::Array[String])
+        @ws           = T.let(nil, T.nilable(WebSocket::Client::Simple::Client))
+        @connected    = T.let(false, T::Boolean)
+        @publisher    = T.let(Subscribable::DataPublisher.new, Subscribable::DataPublisher)
+
+        _connect
+      end
+
+      # Send a JSON-RPC request and return the result synchronously (blocks).
+      sig do
+        params(method: String, params: T::Array[T.untyped])
+          .returns(T.untyped)
+      end
+      def request(method, params = [])
+        id     = _next_id
+        q      = Queue.new
+        @mutex.synchronize { @pending[id] = q }
+
+        payload = JSON.generate({ 'jsonrpc' => '2.0', 'id' => id, 'method' => method, 'params' => params })
+        _send(payload)
+
+        response = q.pop
+        raise Rpc::RpcError.new(response['error']['message'], response['error']['code']) if response['error']
+
+        response['result']
+      end
+
+      # Subscribe to a channel (subscription ID from the server).
+      # Returns an unsubscribe lambda.
+      sig do
+        params(
+          sub_id: T.untyped,
+          block:  T.proc.params(msg: T::Hash[String, T.untyped]).void
+        ).returns(T.proc.void)
+      end
+      def subscribe(sub_id, &block)
+        @mutex.synchronize { T.must(@subscribers[sub_id]) << block }
+        lambda { @mutex.synchronize { T.must(@subscribers[sub_id]).delete(block) } }
+      end
+
+      # Access the underlying DataPublisher for AsyncIterable integration.
+      sig { returns(Subscribable::DataPublisher) }
+      attr_reader :publisher
+
+      sig { void }
+      def close
+        @ws&.close
+        @publisher.close
+      end
+
+      private
+
+      sig { returns(Integer) }
+      def _next_id
+        @mutex.synchronize { @id_seq += 1; @id_seq }
+      end
+
+      sig { params(payload: String).void }
+      def _send(payload)
+        if @connected
+          @ws&.send(payload)
+        else
+          @send_buffer << payload
+        end
+      end
+
+      sig { void }
+      def _connect # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        transport = self
+        @ws = WebSocket::Client::Simple.connect(@url, headers: @headers)
+
+        ws = @ws
+        ws.on(:open) do
+          transport.instance_variable_set(:@connected, true)
+          transport.instance_variable_get(:@send_buffer).each { |m| ws.send(m) }
+          transport.instance_variable_get(:@send_buffer).clear
+        end
+
+        ws.on(:message) do |msg|
+          next unless msg.type == :text
+
+          begin
+            data = JSON.parse(msg.data)
+          rescue JSON::ParserError
+            next
+          end
+
+          if data.key?('id')
+            # Response to a request
+            id = data['id']
+            q  = transport.instance_variable_get(:@mutex).synchronize do
+              transport.instance_variable_get(:@pending).delete(id)
+            end
+            q&.push(data)
+          elsif data.key?('method')
+            # Push notification (subscription event)
+            sub_id = data.dig('params', 'subscription')
+            subs   = transport.instance_variable_get(:@mutex).synchronize do
+              (transport.instance_variable_get(:@subscribers)[sub_id] || []).dup
+            end
+            subs.each { |blk| blk.call(data) }
+            transport.instance_variable_get(:@publisher).publish(sub_id, data)
+          end
+        end
+
+        ws.on(:error) do |e|
+          transport.instance_variable_get(:@publisher).publish(
+            Subscribable::DataPublisher::ERROR_CHANNEL,
+            e.is_a?(StandardError) ? e : RuntimeError.new(e.to_s)
+          )
+        end
+
+        ws.on(:close) do
+          transport.instance_variable_set(:@connected, false)
+          transport.instance_variable_get(:@publisher).close
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Mirrors @solana/rpc-subscriptions + @solana/rpc-subscriptions-api.
+# Provides a WebSocket-based subscription client for Solana push notifications.
+require_relative 'subscribable'
+require_relative 'rpc_subscriptions/client'
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+  end
+end

data/lib/solana/ruby/kit/rpc_types/account_info.rb

@@ -0,0 +1,53 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../addresses/address'
+
+module Solana::Ruby::Kit
+  module RpcTypes
+    # Base fields present in every account-info response.
+    # Mirrors TypeScript's `AccountInfoBase`.
+    class AccountInfoBase < T::Struct
+      const :executable, T::Boolean
+      # Balance in lamports.
+      const :lamports,   Integer
+      # Address of the program that owns this account.
+      const :owner,      String        # base58 address string
+      # Allocated storage in bytes (excludes the 128-byte header).
+      # TypeScript uses bigint; Ruby uses Integer.
+      const :space,      Integer
+    end
+
+    # Account info with raw base64-encoded data (the most common encoding).
+    # Mirrors `AccountInfoWithBase64EncodedData`.
+    class AccountInfoWithBase64Data < T::Struct
+      const :executable,  T::Boolean
+      const :lamports,    Integer
+      const :owner,       String
+      const :space,       Integer
+      const :rent_epoch,  Integer, default: 0
+      # Tuple: [base64_string, "base64"]
+      const :data,        T::Array[String]
+    end
+
+    # Account info with JSON-parsed data (program-specific parsing on the RPC node).
+    # Mirrors `AccountInfoWithJsonData`.
+    class AccountInfoWithJsonData < T::Struct
+      const :executable,  T::Boolean
+      const :lamports,    Integer
+      const :owner,       String
+      const :space,       Integer
+      const :rent_epoch,  Integer, default: 0
+      # Either a hash (parsed JSON) or a base64 fallback tuple.
+      const :data,        T.untyped
+    end
+
+    # Slot + context wrapper returned by context-aware RPC methods.
+    # Mirrors TypeScript's `SolanaRpcResponse<T>`:
+    #   { context: { slot: bigint }, value: T }
+    class RpcContextualValue < T::Struct
+      const :slot,  Integer   # the slot at which the data was read
+      const :value, T.untyped # the actual result (typed by the caller)
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_types/cluster_url.rb

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcTypes
+    extend T::Sig
+    # Well-known cluster endpoint URLs.
+    MAINNET_URL = T.let('https://api.mainnet-beta.solana.com', String)
+    DEVNET_URL  = T.let('https://api.devnet.solana.com',       String)
+    TESTNET_URL = T.let('https://api.testnet.solana.com',      String)
+
+    # A cluster-tagged URL string.
+    # Mirrors TypeScript's branded string types:
+    #   MainnetUrl, DevnetUrl, TestnetUrl, ClusterUrl
+    #
+    # In Ruby we carry the cluster tag as a symbol on a wrapper struct,
+    # since Ruby cannot brand primitive String values.
+    class ClusterUrl < T::Struct
+      extend T::Sig
+      const :url,     String
+      const :cluster, T.nilable(Symbol)  # :mainnet | :devnet | :testnet | nil
+
+      sig { returns(String) }
+      def to_s = @url
+    end
+
+    module_function
+
+    # Wraps a URL string and tags it as mainnet.
+    # Mirrors `mainnet(url)`.
+    sig { params(url: String).returns(ClusterUrl) }
+    def mainnet(url = MAINNET_URL)
+      ClusterUrl.new(url: url, cluster: :mainnet)
+    end
+
+    # Wraps a URL string and tags it as devnet.
+    # Mirrors `devnet(url)`.
+    sig { params(url: String).returns(ClusterUrl) }
+    def devnet(url = DEVNET_URL)
+      ClusterUrl.new(url: url, cluster: :devnet)
+    end
+
+    # Wraps a URL string and tags it as testnet.
+    # Mirrors `testnet(url)`.
+    sig { params(url: String).returns(ClusterUrl) }
+    def testnet(url = TESTNET_URL)
+      ClusterUrl.new(url: url, cluster: :testnet)
+    end
+
+    # Wraps a custom URL with no cluster tag.
+    sig { params(url: String).returns(ClusterUrl) }
+    def cluster_url(url)
+      ClusterUrl.new(url: url, cluster: nil)
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_types/commitment.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcTypes
+    extend T::Sig
+    # Network confirmation level for an RPC request.
+    # Mirrors TypeScript's `Commitment = 'finalized' | 'confirmed' | 'processed'`.
+    #
+    # Each level is a measure of how many validators have confirmed a block:
+    #   - :finalized  — the block has been voted on by a supermajority and is permanent.
+    #   - :confirmed  — the block has been voted on by a supermajority (not yet rooted).
+    #   - :processed  — the node has seen the block but it may yet be rolled back.
+    Commitment = T.type_alias { Symbol }
+
+    FINALIZED = T.let(:finalized, Symbol)
+    CONFIRMED = T.let(:confirmed, Symbol)
+    PROCESSED = T.let(:processed, Symbol)
+
+    VALID_COMMITMENTS = T.let(
+      [FINALIZED, CONFIRMED, PROCESSED].freeze,
+      T::Array[Symbol]
+    )
+
+    module_function
+
+    # Returns a numeric score for a commitment level (higher = more confirmed).
+    # Mirrors `getCommitmentScore()`.
+    sig { params(commitment: Symbol).returns(Integer) }
+    def commitment_score(commitment)
+      case commitment
+      when FINALIZED then 2
+      when CONFIRMED then 1
+      when PROCESSED then 0
+      else Kernel.raise ArgumentError, "Unknown commitment: #{commitment.inspect}"
+      end
+    end
+
+    # Compares two commitment levels.  Returns -1, 0, or 1.
+    # Mirrors `commitmentComparator()`.
+    sig { params(a: Symbol, b: Symbol).returns(Integer) }
+    def commitment_comparator(a, b)
+      commitment_score(a) <=> commitment_score(b)
+    end
+
+    # Returns true if the symbol is a valid commitment level.
+    sig { params(value: T.untyped).returns(T::Boolean) }
+    def commitment?(value)
+      VALID_COMMITMENTS.include?(value)
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_types/lamports.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module RpcTypes
+    extend T::Sig
+    # The smallest denomination of SOL (1 SOL = 1_000_000_000 lamports).
+    # Mirrors TypeScript's `Lamports` branded bigint.
+    # In Ruby, arbitrary-precision Integer replaces JS bigint with no loss of range.
+    #
+    # Valid range: 0 .. 18_446_744_073_709_551_615  (u64)
+    Lamports = T.type_alias { Integer }
+
+    LAMPORTS_U64_MAX = T.let(T.unsafe(2**64 - 1), Integer)
+
+    module_function
+
+    # Returns true if the integer is a valid u64 lamport value.
+    # Mirrors `isLamports()`.
+    sig { params(value: T.untyped).returns(T::Boolean) }
+    def lamports?(value)
+      !!(value.is_a?(Integer) && value >= 0 && value <= LAMPORTS_U64_MAX)
+    end
+
+    # Raises SolanaError if the value is not a valid lamport amount.
+    # Mirrors `assertIsLamports()`.
+    sig { params(value: T.untyped).void }
+    def assert_lamports!(value)
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__LAMPORTS__AMOUNT_MUST_BE_POSITIVE) if value.is_a?(Integer) && value < 0
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__LAMPORTS__AMOUNT_OUT_OF_RANGE) unless lamports?(value)
+    end
+
+    # Validates and returns the lamport value.
+    # Mirrors `lamports()`.
+    sig { params(value: Integer).returns(Integer) }
+    def lamports(value)
+      assert_lamports!(value)
+      value
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Core RPC type definitions — mirrors @solana/rpc-types.
+require_relative 'rpc_types/commitment'
+require_relative 'rpc_types/lamports'
+require_relative 'rpc_types/cluster_url'
+require_relative 'rpc_types/account_info'

data/lib/solana/ruby/kit/signers/keypair_signer.rb

@@ -0,0 +1,126 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'rbnacl'
+require_relative '../errors'
+require_relative '../addresses/address'
+require_relative '../keys/key_pair'
+require_relative '../keys/signatures'
+require_relative '../transactions/transaction'
+
+module Solana::Ruby::Kit
+  module Signers
+    extend T::Sig
+    # A signer backed by an Ed25519 key pair, capable of signing both
+    # transaction messages and off-chain messages.
+    #
+    # Mirrors TypeScript's `KeyPairSigner<TAddress>`, which combines
+    # `MessagePartialSigner` and `TransactionPartialSigner` with a
+    # `CryptoKeyPair` reference.
+    #
+    # In Ruby we keep it simple: the signer holds an RbNaCl::SigningKey
+    # (which contains the private key seed and can derive the public key)
+    # and exposes the signer's address.
+    class KeyPairSigner
+      extend T::Sig
+
+      sig { returns(Addresses::Address) }
+      attr_reader :address
+
+      sig { returns(Keys::KeyPair) }
+      attr_reader :key_pair
+
+      sig { params(key_pair: Keys::KeyPair).void }
+      def initialize(key_pair)
+        @key_pair = T.let(key_pair, Keys::KeyPair)
+        @address  = T.let(
+          Addresses::Address.new(Addresses.encode_address(key_pair.verify_key.to_bytes)),
+          Addresses::Address
+        )
+      end
+
+      sig { returns(String) }
+      def to_s = @address.to_s
+
+      sig { returns(String) }
+      def inspect = "#<KeyPairSigner address=#{@address}>"
+
+      # Signs raw bytes with the private key, returning a SignatureBytes.
+      # Used internally by sign_transaction and sign_message.
+      sig { params(data: String).returns(Keys::SignatureBytes) }
+      def sign(data)
+        Keys.sign_bytes(@key_pair.signing_key, data)
+      end
+
+      # Verifies a signature against data using this signer's public key.
+      sig { params(sig_bytes: Keys::SignatureBytes, data: String).returns(T::Boolean) }
+      def verify(sig_bytes, data)
+        Keys.verify_signature(@key_pair.verify_key, sig_bytes, data)
+      end
+    end
+
+    module_function
+
+    # Creates a KeyPairSigner from an existing Keys::KeyPair.
+    # Mirrors `createSignerFromKeyPair(keyPair)`.
+    sig { params(key_pair: Keys::KeyPair).returns(KeyPairSigner) }
+    def create_signer_from_key_pair(key_pair)
+      KeyPairSigner.new(key_pair)
+    end
+
+    # Generates a fresh random key pair and wraps it in a KeyPairSigner.
+    # Mirrors `generateKeyPairSigner()`.
+    sig { returns(KeyPairSigner) }
+    def generate_key_pair_signer
+      KeyPairSigner.new(Keys.generate_key_pair)
+    end
+
+    # Creates a KeyPairSigner from 64 raw bytes (seed || public key).
+    # Mirrors `createKeyPairSignerFromBytes(bytes)`.
+    sig { params(bytes: String).returns(KeyPairSigner) }
+    def create_key_pair_signer_from_bytes(bytes)
+      KeyPairSigner.new(Keys.create_key_pair_from_bytes(bytes))
+    end
+
+    # Creates a KeyPairSigner from a 32-byte private key seed.
+    # Mirrors `createKeyPairSignerFromPrivateKeyBytes(bytes)`.
+    sig { params(bytes: String).returns(KeyPairSigner) }
+    def create_key_pair_signer_from_private_key_bytes(bytes)
+      KeyPairSigner.new(Keys.create_key_pair_from_private_key_bytes(bytes))
+    end
+
+    # Returns true if the value is a KeyPairSigner.
+    # Mirrors `isKeyPairSigner(value)`.
+    sig { params(value: T.untyped).returns(T::Boolean) }
+    def key_pair_signer?(value)
+      value.is_a?(KeyPairSigner)
+    end
+
+    # Raises SolanaError if the value is not a KeyPairSigner.
+    # Mirrors `assertIsKeyPairSigner(value)`.
+    sig { params(value: T.untyped).void }
+    def assert_key_pair_signer!(value)
+      Kernel.raise SolanaError.new(:SOLANA_ERROR__SIGNER__EXPECTED_KEY_PAIR_SIGNER) unless key_pair_signer?(value)
+    end
+
+    # Signs a transaction message's bytes using all provided signers.
+    # Returns a hash mapping each signer's address to its SignatureBytes.
+    #
+    # This is the Ruby analogue of the TypeScript signers' sign-transaction
+    # workflow: each signer produces its Ed25519 signature of the compiled
+    # message bytes, and the signatures are collected into a map.
+    #
+    # Mirrors the combined behaviour of `TransactionPartialSigner.signTransactions`.
+    sig do
+      params(
+        signers:       T::Array[KeyPairSigner],
+        message_bytes: String
+      ).returns(T::Hash[String, Keys::SignatureBytes])
+    end
+    def sign_message_bytes_with_signers(signers, message_bytes)
+      signers.each_with_object({}) do |signer, map|
+        map[signer.address.value] = signer.sign(message_bytes)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Signer abstractions — mirrors @solana/signers.
+require_relative 'signers/keypair_signer'

data/lib/solana/ruby/kit/subscribable/async_iterable.rb

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Subscribable
+    # Creates an Enumerator backed by a thread-safe Queue.
+    #
+    # Mirrors createAsyncIterableFromDataPublisher from @solana/subscribable.
+    #
+    # Usage:
+    #   enum = AsyncIterable.from_publisher(publisher, data_channel: :accountNotification)
+    #   enum.each { |notification| process(notification) }
+    #
+    # The enumerator blocks on Queue#pop until the publisher closes or the
+    # optional +timeout+ expires.  When the publisher emits on the error
+    # channel the exception is re-raised inside the enumerator.
+    module AsyncIterable
+      extend T::Sig
+
+      # Sentinel value pushed into the queue when the stream is done.
+      DONE = T.let(Object.new.freeze, Object)
+
+      module_function
+
+      # @param publisher [DataPublisher]
+      # @param data_channel channel name for data messages
+      # @param error_channel channel name for errors (default: :error)
+      # @param timeout [Float, nil] per-item pop timeout in seconds
+      # @return [Enumerator]
+      sig do
+        params(
+          publisher:     DataPublisher,
+          data_channel:  T.untyped,
+          error_channel: T.untyped,
+          timeout:       T.nilable(Float)
+        ).returns(T::Enumerator[T.untyped])
+      end
+      def from_publisher(publisher, data_channel:, error_channel: :error, timeout: nil)
+        queue = T.let(Queue.new, Queue)
+
+        # Subscribe to data
+        unsub_data = publisher.on(data_channel) { |data| queue.push([:data, data]) }
+
+        # Subscribe to errors — re-raise inside the enumerator
+        unsub_error = publisher.on(error_channel) { |err| queue.push([:error, err]) }
+
+        # Subscribe to close
+        unsub_close = publisher.on(DataPublisher::CLOSE_CHANNEL) { queue.push([:done, nil]) }
+
+        cleanup = Kernel.lambda do
+          unsub_data.call
+          unsub_error.call
+          unsub_close.call
+        end
+
+        Enumerator.new do |yielder|
+          Kernel.loop do
+            kind, payload = if timeout
+                              begin
+                                Timeout.timeout(timeout) { queue.pop }
+                              rescue Timeout::Error
+                                [:done, nil]
+                              end
+                            else
+                              queue.pop
+                            end
+
+            case kind
+            when :data  then yielder.yield(payload)
+            when :error then Kernel.raise T.cast(payload, StandardError)
+            else             break
+            end
+          end
+        ensure
+          cleanup.call
+        end
+      end
+    end
+  end
+end