solana-ruby-kit 0.1.0

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

@@ -0,0 +1,137 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require_relative '../errors'
+
+module Solana::Ruby::Kit
+  module Rpc
+    # JSON-RPC error returned by the Solana node.
+    class RpcError < StandardError
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :code
+
+      sig { returns(T.untyped) }
+      attr_reader :data
+
+      sig { params(code: Integer, message: String, data: T.untyped).void }
+      def initialize(code, message, data = nil)
+        @code = T.let(code, Integer)
+        @data = T.let(data, T.untyped)
+        super("JSON-RPC error #{code}: #{message}")
+      end
+    end
+
+    # HTTP error from the transport layer (non-2xx response).
+    class HttpTransportError < StandardError
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :status_code
+
+      sig { params(status_code: Integer, message: String).void }
+      def initialize(status_code, message)
+        @status_code = T.let(status_code, Integer)
+        super("HTTP #{status_code}: #{message}")
+      end
+    end
+
+    # HTTP transport for Solana's JSON-RPC API.
+    # Mirrors TypeScript's `createHttpTransport(config)` from @solana/rpc-transport-http.
+    #
+    # Makes synchronous POST requests — TypeScript's async `fetch` maps to
+    # Ruby's blocking `Net::HTTP`.  Use threads or Fibers for concurrency.
+    class Transport
+      extend T::Sig
+
+      DEFAULT_TIMEOUT   = T.let(30, Integer)   # seconds
+      DEFAULT_OPEN_TIMEOUT = T.let(10, Integer) # seconds
+
+      sig { returns(String) }
+      attr_reader :url
+
+      sig do
+        params(
+          url:            String,
+          headers:        T::Hash[String, String],
+          timeout:        Integer,
+          open_timeout:   Integer,
+          to_json:        T.nilable(T.proc.params(arg0: T.untyped).returns(String)),
+          from_json:      T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped))
+        ).void
+      end
+      def initialize(
+        url:,
+        headers:      {},
+        timeout:      DEFAULT_TIMEOUT,
+        open_timeout: DEFAULT_OPEN_TIMEOUT,
+        to_json:      nil,
+        from_json:    nil
+      )
+        @url          = T.let(url, String)
+        @headers      = T.let(headers, T::Hash[String, String])
+        @timeout      = T.let(timeout, Integer)
+        @open_timeout = T.let(open_timeout, Integer)
+        @to_json      = T.let(to_json, T.nilable(T.proc.params(arg0: T.untyped).returns(String)))
+        @from_json    = T.let(from_json, T.nilable(T.proc.params(arg0: String, arg1: T.untyped).returns(T.untyped)))
+        @request_id   = T.let(0, Integer)
+        @uri          = T.let(URI.parse(url), URI::Generic)
+      end
+
+      # Sends a single JSON-RPC request and returns the parsed `result`.
+      # Raises `RpcError` on a JSON-RPC error, `HttpTransportError` on HTTP failure.
+      sig { params(method: String, params: T::Array[T.untyped]).returns(T.untyped) }
+      def request(method, params = [])
+        payload = build_payload(method, params)
+        body    = @to_json ? @to_json.call(payload) : JSON.generate(payload)
+
+        response = post(body)
+
+        parsed = @from_json ? @from_json.call(T.must(response.body), payload) : JSON.parse(T.must(response.body))
+
+        if parsed.key?('error')
+          err = parsed['error']
+          raise RpcError.new(err['code'].to_i, err['message'].to_s, err['data'])
+        end
+
+        parsed['result']
+      end
+
+      private
+
+      sig { params(method: String, params: T::Array[T.untyped]).returns(T::Hash[String, T.untyped]) }
+      def build_payload(method, params)
+        @request_id += 1
+        { 'jsonrpc' => '2.0', 'id' => @request_id, 'method' => method, 'params' => params }
+      end
+
+      sig { params(body: String).returns(Net::HTTPResponse) }
+      def post(body)
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl      = (@uri.scheme == 'https')
+        http.read_timeout = @timeout
+        http.open_timeout = @open_timeout
+
+        req = Net::HTTP::Post.new(T.cast(@uri, URI::HTTP).request_uri)
+        req['Content-Type']   = 'application/json; charset=utf-8'
+        req['Accept']         = 'application/json'
+        req['Content-Length'] = body.bytesize.to_s
+        req['solana-client']  = 'ruby-kit'
+        @headers.each { |k, v| req[k] = v }
+        req.body = body
+
+        response = http.request(req)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise HttpTransportError.new(response.code.to_i, response.message)
+        end
+
+        response
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# typed: strict
+# frozen_string_literal: true
+
+# RPC package — mirrors @solana/rpc + @solana/rpc-transport-http.
+# Provides a synchronous JSON-RPC client for the Solana network.
+require_relative 'rpc_types'
+require_relative 'rpc/transport'
+require_relative 'rpc/client'
+
+module Solana::Ruby::Kit
+  module Rpc
+  end
+end

data/lib/solana/ruby/kit/rpc_parsed_types/address_lookup_table.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcParsedTypes
+    extend T::Sig
+    AddressLookupTableData = T.let(
+      Struct.new(:deactivation_slot, :last_extended_slot, :addresses, keyword_init: true),
+      T.untyped
+    )
+
+    ParsedAddressLookupTable = T.let(
+      Struct.new(:program, :parsed, :space, keyword_init: true),
+      T.untyped
+    )
+
+    module_function
+
+    sig { params(raw: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def parse_address_lookup_table(raw)
+      info = raw.dig('parsed', 'info') || {}
+      ParsedAddressLookupTable.new(
+        program: raw['program'],
+        space:   raw['space'],
+        parsed:  AddressLookupTableData.new(
+          deactivation_slot:  info['deactivationSlot'] ? Kernel.Integer(info['deactivationSlot']) : nil,
+          last_extended_slot: info['lastExtendedSlot']  ? Kernel.Integer(info['lastExtendedSlot']) : nil,
+          addresses:          Kernel.Array(info['addresses'])
+        )
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_parsed_types/nonce_account.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcParsedTypes
+    extend T::Sig
+    NonceAccountData = T.let(
+      Struct.new(:authority, :blockhash, :fee_calculator, keyword_init: true),
+      T.untyped
+    )
+
+    ParsedNonceAccount = T.let(
+      Struct.new(:program, :parsed, :space, keyword_init: true),
+      T.untyped
+    )
+
+    module_function
+
+    sig { params(raw: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def parse_nonce_account(raw)
+      info = raw.dig('parsed', 'info') || {}
+      ParsedNonceAccount.new(
+        program: raw['program'],
+        space:   raw['space'],
+        parsed:  NonceAccountData.new(
+          authority:      info['authority'],
+          blockhash:      info['blockhash'],
+          fee_calculator: info['feeCalculator']
+        )
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_parsed_types/stake_account.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcParsedTypes
+    extend T::Sig
+    StakeDelegation = T.let(
+      Struct.new(:stake, :voter, :activation_epoch, :deactivation_epoch,
+                 :warmup_cooldown_rate, keyword_init: true),
+      T.untyped
+    )
+
+    StakeAccountData = T.let(
+      Struct.new(:type, :stake, :meta, keyword_init: true),
+      T.untyped
+    )
+
+    ParsedStakeAccount = T.let(
+      Struct.new(:program, :parsed, :space, keyword_init: true),
+      T.untyped
+    )
+
+    module_function
+
+    sig { params(raw: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def parse_stake_account(raw)
+      parsed = raw['parsed'] || {}
+      info   = parsed['info'] || {}
+      stake  = info['stake'] || {}
+      deleg  = stake.dig('delegation') || {}
+
+      delegation = StakeDelegation.new(
+        stake:               deleg['stake'] ? Kernel.Integer(deleg['stake']) : nil,
+        voter:               deleg['voter'],
+        activation_epoch:    deleg['activationEpoch'] ? Kernel.Integer(deleg['activationEpoch']) : nil,
+        deactivation_epoch:  deleg['deactivationEpoch'] ? Kernel.Integer(deleg['deactivationEpoch']) : nil,
+        warmup_cooldown_rate: deleg['warmupCooldownRate']&.to_f
+      )
+
+      ParsedStakeAccount.new(
+        program: raw['program'],
+        space:   raw['space'],
+        parsed:  StakeAccountData.new(
+          type:  parsed['type'],
+          stake: delegation,
+          meta:  info['meta']
+        )
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_parsed_types/token_account.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcParsedTypes
+    extend T::Sig
+    # Parsed SPL Token amount.
+    TokenAmount = T.let(
+      Struct.new(:amount, :decimals, :ui_amount, :ui_amount_string, keyword_init: true),
+      T.untyped
+    )
+
+    # Parsed SPL Token account data (inside jsonParsed account info).
+    TokenAccountInfo = T.let(
+      Struct.new(:is_native, :mint, :owner, :state, :token_amount, keyword_init: true),
+      T.untyped
+    )
+
+    # Full parsed token account wrapper.
+    ParsedTokenAccount = T.let(
+      Struct.new(:program, :parsed, :space, keyword_init: true),
+      T.untyped
+    )
+
+    module_function
+
+    sig { params(raw: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def parse_token_account(raw)
+      info_raw = raw.dig('parsed', 'info') || {}
+      ta_raw   = info_raw['tokenAmount'] || {}
+
+      info = TokenAccountInfo.new(
+        is_native:    info_raw['isNative'],
+        mint:         info_raw['mint'],
+        owner:        info_raw['owner'],
+        state:        info_raw['state'],
+        token_amount: TokenAmount.new(
+          amount:           ta_raw['amount'],
+          decimals:         Kernel.Integer(ta_raw.fetch('decimals', 0)),
+          ui_amount:        ta_raw['uiAmount'],
+          ui_amount_string: ta_raw['uiAmountString']
+        )
+      )
+
+      ParsedTokenAccount.new(
+        program: raw['program'],
+        parsed:  info,
+        space:   raw['space']
+      )
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc_parsed_types/vote_account.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcParsedTypes
+    extend T::Sig
+    VoteState = T.let(
+      Struct.new(:node, :authorized_voter, :authorized_withdrawer, :commission,
+                 :votes, :root_slot, :epoch_credits, keyword_init: true),
+      T.untyped
+    )
+
+    ParsedVoteAccount = T.let(
+      Struct.new(:program, :parsed, :space, keyword_init: true),
+      T.untyped
+    )
+
+    module_function
+
+    sig { params(raw: T::Hash[String, T.untyped]).returns(T.untyped) }
+    def parse_vote_account(raw)
+      info = raw.dig('parsed', 'info') || {}
+      ParsedVoteAccount.new(
+        program: raw['program'],
+        space:   raw['space'],
+        parsed:  VoteState.new(
+          node:                  info['nodePubkey'],
+          authorized_voter:      info['authorizedVoters'],
+          authorized_withdrawer: info['authorizedWithdrawer'],
+          commission:            info['commission'] ? Kernel.Integer(info['commission']) : nil,
+          votes:                 info['votes'],
+          root_slot:             info['rootSlot'] ? Kernel.Integer(info['rootSlot']) : nil,
+          epoch_credits:         info['epochCredits']
+        )
+      )
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Parsed RPC response types — mirrors @solana/rpc-parsed-types.
+# These structs are populated when using encoding: 'jsonParsed' with
+# RPC methods like getAccountInfo / getMultipleAccounts.
+require_relative 'rpc_parsed_types/token_account'
+require_relative 'rpc_parsed_types/nonce_account'
+require_relative 'rpc_parsed_types/stake_account'
+require_relative 'rpc_parsed_types/vote_account'
+require_relative 'rpc_parsed_types/address_lookup_table'
+
+module Solana::Ruby::Kit
+  module RpcParsedTypes
+  end
+end

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

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    module Api
+      # Subscribe to account change notifications.
+      # Mirrors TypeScript's AccountNotificationsApi.accountSubscribe.
+      module AccountNotifications
+        extend T::Sig
+
+        sig do
+          params(
+            pubkey:     String,
+            commitment: T.nilable(Symbol),
+            encoding:   String
+          ).returns(Subscription)
+        end
+        def account_subscribe(pubkey, commitment: nil, encoding: 'base64')
+          config = { 'encoding' => encoding }
+          config['commitment'] = commitment.to_s if commitment
+
+          sub_id = transport.request('accountSubscribe', [pubkey, config])
+          _build_subscription(sub_id, 'accountUnsubscribe')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    module Api
+      # Subscribe to transaction log notifications.
+      # +filter+ may be 'all', 'allWithVotes', or { 'mentions' => [pubkey] }.
+      module LogsNotifications
+        extend T::Sig
+
+        sig do
+          params(
+            filter:     T.untyped,
+            commitment: T.nilable(Symbol)
+          ).returns(Subscription)
+        end
+        def logs_subscribe(filter = 'all', commitment: nil)
+          config = {}
+          config['commitment'] = commitment.to_s if commitment
+
+          sub_id = transport.request('logsSubscribe', config.empty? ? [filter] : [filter, config])
+          _build_subscription(sub_id, 'logsUnsubscribe')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    module Api
+      # Subscribe to program account change notifications.
+      module ProgramNotifications
+        extend T::Sig
+
+        sig do
+          params(
+            program_id:  String,
+            commitment:  T.nilable(Symbol),
+            encoding:    String,
+            filters:     T::Array[T::Hash[String, T.untyped]]
+          ).returns(Subscription)
+        end
+        def program_subscribe(program_id, commitment: nil, encoding: 'base64', filters: [])
+          config = { 'encoding' => encoding }
+          config['commitment'] = commitment.to_s if commitment
+          config['filters']    = filters unless filters.empty?
+
+          sub_id = transport.request('programSubscribe', [program_id, config])
+          _build_subscription(sub_id, 'programUnsubscribe')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    module Api
+      # Subscribe to root change notifications.
+      module RootNotifications
+        extend T::Sig
+
+        sig { returns(Subscription) }
+        def root_subscribe
+          sub_id = transport.request('rootSubscribe', [])
+          _build_subscription(sub_id, 'rootUnsubscribe')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    module Api
+      # Subscribe to signature status notifications.
+      # The subscription auto-unsubscribes once the signature is confirmed.
+      module SignatureNotifications
+        extend T::Sig
+
+        sig do
+          params(
+            signature:  String,
+            commitment: T.nilable(Symbol)
+          ).returns(Subscription)
+        end
+        def signature_subscribe(signature, commitment: nil)
+          config = {}
+          config['commitment'] = commitment.to_s if commitment
+
+          sub_id = transport.request('signatureSubscribe', config.empty? ? [signature] : [signature, config])
+          _build_subscription(sub_id, 'signatureUnsubscribe')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    module Api
+      # Subscribe to slot change notifications.
+      module SlotNotifications
+        extend T::Sig
+
+        sig { returns(Subscription) }
+        def slot_subscribe
+          sub_id = transport.request('slotSubscribe', [])
+          _build_subscription(sub_id, 'slotUnsubscribe')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    # Sends a WebSocket ping on a fixed interval to keep the connection alive.
+    # Mirrors @solana/rpc-subscriptions autopinger.
+    class Autopinger
+      extend T::Sig
+
+      sig { params(transport: Transport, interval: Float).void }
+      def initialize(transport, interval: 5.0)
+        @transport = transport
+        @interval  = interval
+        @thread    = T.let(nil, T.nilable(Thread))
+      end
+
+      sig { void }
+      def start
+        @thread = Thread.new do
+          loop do
+            sleep(@interval)
+            break if @transport.publisher.closed?
+
+            begin
+              @transport.instance_variable_get(:@ws)&.send(nil, type: :ping)
+            rescue StandardError
+              break
+            end
+          end
+        end
+        @thread.abort_on_exception = false
+      end
+
+      sig { void }
+      def stop
+        @thread&.kill
+        @thread = nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'transport'
+require_relative 'subscription'
+require_relative 'autopinger'
+require_relative 'api/account_notifications'
+require_relative 'api/logs_notifications'
+require_relative 'api/program_notifications'
+require_relative 'api/root_notifications'
+require_relative 'api/signature_notifications'
+require_relative 'api/slot_notifications'
+
+module Solana::Ruby::Kit
+  module RpcSubscriptions
+    # WebSocket subscription client for Solana.
+    # Mirrors TypeScript's createSolanaRpcSubscriptions(url) factory.
+    #
+    # @example
+    #   subs = Solana::Ruby::Kit::RpcSubscriptions::Client.new('wss://api.devnet.solana.com')
+    #   sub  = subs.slot_subscribe
+    #   sub.take(3).each { |n| puts n.inspect }
+    class Client
+      extend T::Sig
+
+      include Api::AccountNotifications
+      include Api::LogsNotifications
+      include Api::ProgramNotifications
+      include Api::RootNotifications
+      include Api::SignatureNotifications
+      include Api::SlotNotifications
+
+      sig { returns(Transport) }
+      attr_reader :transport
+
+      sig do
+        params(
+          url:           String,
+          headers:       T::Hash[String, String],
+          ping_interval: Float
+        ).void
+      end
+      def initialize(url, headers: {}, ping_interval: 5.0)
+        @transport  = T.let(Transport.new(url: url, headers: headers), Transport)
+        @pinger     = T.let(Autopinger.new(@transport, interval: ping_interval), Autopinger)
+        @pinger.start
+      end
+
+      sig { void }
+      def close
+        @pinger.stop
+        @transport.close
+      end
+
+      private
+
+      # Build a Subscription wrapping an AsyncIterable enumerator and
+      # an auto-unsubscribe on close.
+      sig { params(sub_id: T.untyped, unsub_method: String).returns(Subscription) }
+      def _build_subscription(sub_id, unsub_method)
+        publisher  = @transport.publisher
+        enumerator = Subscribable::AsyncIterable.from_publisher(
+          publisher,
+          data_channel:  sub_id,
+          error_channel: Subscribable::DataPublisher::ERROR_CHANNEL
+        )
+
+        unsubscribe = lambda do
+          begin
+            @transport.request(unsub_method, [sub_id])
+          rescue StandardError
+            nil # Best-effort: transport may already be closed
+          end
+        end
+
+        Subscription.new(enumerator: enumerator, unsubscribe: unsubscribe)
+      end
+    end
+  end
+end