solana-ruby-kit 0.1.0

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

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Fetch multiple account infos in a single RPC call.
+      # Mirrors TypeScript's GetMultipleAccountsApi.getMultipleAccounts.
+      module GetMultipleAccounts
+        extend T::Sig
+
+        sig do
+          params(
+            addresses:        T::Array[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_multiple_accounts(
+          addresses,
+          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('getMultipleAccounts', [addresses, config])
+
+          slot   = Kernel.Integer(result['context']['slot'])
+          values = Kernel.Array(result['value']).map do |raw|
+            next nil if raw.nil?
+
+            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: values)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Fetch all accounts owned by a program.
+      # Mirrors TypeScript's GetProgramAccountsApi.getProgramAccounts.
+      #
+      # Returns an Array of { pubkey:, account: AccountInfoWithBase64Data }.
+      module GetProgramAccounts
+        extend T::Sig
+
+        sig do
+          params(
+            program_id:       String,
+            encoding:         String,
+            filters:          T::Array[T::Hash[String, T.untyped]],
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer),
+            with_context:     T::Boolean
+          ).returns(T.untyped)
+        end
+        def get_program_accounts(
+          program_id,
+          encoding:         'base64',
+          filters:          [],
+          commitment:       nil,
+          min_context_slot: nil,
+          with_context:     false
+        )
+          config = { 'encoding' => encoding, 'withContext' => with_context }
+          config['filters']        = filters        unless filters.empty?
+          config['commitment']     = commitment.to_s if commitment
+          config['minContextSlot'] = min_context_slot if min_context_slot
+
+          result = transport.request('getProgramAccounts', [program_id, config])
+
+          # withContext wraps result in {context:, value:}
+          accounts = with_context ? result['value'] : result
+
+          Kernel.Array(accounts).map do |item|
+            account_raw = item['account']
+            {
+              pubkey:  item['pubkey'],
+              account: RpcTypes::AccountInfoWithBase64Data.new(
+                executable: account_raw['executable'],
+                lamports:   Kernel.Integer(account_raw['lamports']),
+                owner:      account_raw['owner'],
+                space:      Kernel.Integer(account_raw.fetch('space', 0)),
+                rent_epoch: Kernel.Integer(account_raw.fetch('rentEpoch', 0)),
+                data:       Kernel.Array(account_raw['data'])
+              )
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../../rpc_types/account_info'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Status of a confirmed transaction signature.
+      # Mirrors TypeScript's signature-status response shape.
+      class SignatureStatus < T::Struct
+        const :slot,                 Integer
+        const :confirmations,        T.nilable(Integer)   # nil when finalized
+        const :err,                  T.untyped            # nil or error object
+        const :confirmation_status,  T.nilable(Symbol)    # :processed | :confirmed | :finalized
+      end
+
+      # Returns the confirmation status of one or more transaction signatures.
+      # Mirrors TypeScript's `GetSignatureStatusesApi.getSignatureStatuses(sigs, config?)`.
+      #
+      # Returns a `RpcContextualValue` with:
+      #   .slot  — context slot
+      #   .value — Array of SignatureStatus | nil (nil for unknown signatures)
+      module GetSignatureStatuses
+        extend T::Sig
+
+        sig do
+          params(
+            signatures:            T::Array[String],
+            search_transaction_history: T::Boolean
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def get_signature_statuses(signatures, search_transaction_history: false)
+          config = { 'searchTransactionHistory' => search_transaction_history }
+          result = transport.request('getSignatureStatuses', [signatures, config])
+
+          statuses = result['value'].map do |raw|
+            next nil if raw.nil?
+
+            SignatureStatus.new(
+              slot:                Kernel.Integer(raw['slot']),
+              confirmations:       raw['confirmations'] ? Kernel.Integer(raw['confirmations']) : nil,
+              err:                 raw['err'],
+              confirmation_status: raw['confirmationStatus']&.to_sym
+            )
+          end
+
+          RpcTypes::RpcContextualValue.new(
+            slot:  Kernel.Integer(result['context']['slot']),
+            value: statuses
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Returns the current slot number at the given commitment level.
+      # Mirrors TypeScript's `GetSlotApi.getSlot()`.
+      module GetSlot
+        extend T::Sig
+
+        sig do
+          params(
+            commitment:      T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer)
+          ).returns(Integer)
+        end
+        def get_slot(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('getSlot', params)
+          Kernel.Integer(result)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Fetch the token balance of an SPL Token account.
+      # Mirrors TypeScript's GetTokenAccountBalanceApi.getTokenAccountBalance.
+      module GetTokenAccountBalance
+        extend T::Sig
+
+        sig do
+          params(
+            token_account: String,
+            commitment:    T.nilable(Symbol)
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def get_token_account_balance(token_account, commitment: nil)
+          config = {}
+          config['commitment'] = commitment.to_s if commitment
+
+          result = transport.request('getTokenAccountBalance', [token_account, config].tap { |a| a.pop if a.last.empty? })
+          slot   = Kernel.Integer(result['context']['slot'])
+          raw    = result['value']
+
+          value = {
+            amount:           raw['amount'],
+            decimals:         Kernel.Integer(raw['decimals']),
+            ui_amount:        raw['uiAmount'],
+            ui_amount_string: raw['uiAmountString']
+          }
+
+          RpcTypes::RpcContextualValue.new(slot: slot, value: value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Fetch all SPL Token accounts by owner.
+      # +filter+ must be one of:
+      #   { 'mint' => mint_address }
+      #   { 'programId' => program_id }
+      module GetTokenAccountsByOwner
+        extend T::Sig
+
+        sig do
+          params(
+            owner:      String,
+            filter:     T::Hash[String, String],
+            encoding:   String,
+            commitment: T.nilable(Symbol)
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def get_token_accounts_by_owner(owner, filter, encoding: 'base64', commitment: nil)
+          config = { 'encoding' => encoding }
+          config['commitment'] = commitment.to_s if commitment
+
+          result = transport.request('getTokenAccountsByOwner', [owner, filter, config])
+          slot   = Kernel.Integer(result['context']['slot'])
+          value  = Kernel.Array(result['value']).map do |item|
+            raw = item['account']
+            {
+              pubkey:  item['pubkey'],
+              account: 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_transaction.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Fetch a confirmed transaction.
+      # Mirrors TypeScript's GetTransactionApi.getTransaction.
+      # Returns the raw JSON hash (nil if not found / not yet confirmed).
+      module GetTransaction
+        extend T::Sig
+
+        sig do
+          params(
+            signature:                          String,
+            encoding:                           String,
+            commitment:                         T.nilable(Symbol),
+            max_supported_transaction_version:  T.nilable(Integer)
+          ).returns(T.nilable(T::Hash[String, T.untyped]))
+        end
+        def get_transaction(
+          signature,
+          encoding:                          'json',
+          commitment:                        nil,
+          max_supported_transaction_version: nil
+        )
+          config = { 'encoding' => encoding }
+          config['commitment'] = commitment.to_s if commitment
+          config['maxSupportedTransactionVersion'] = max_supported_transaction_version if max_supported_transaction_version
+
+          transport.request('getTransaction', [signature, config])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Vote account info struct.
+      VoteAccountInfo = T.let(
+        Struct.new(
+          :vote_pubkey,
+          :node_pubkey,
+          :activated_stake,
+          :epoch_vote_account,
+          :commission,
+          :last_vote,
+          :epoch_credits,
+          :root_slot,
+          keyword_init: true
+        ),
+        T.untyped
+      )
+
+      # Fetch current and delinquent vote accounts.
+      # Returns { current: [], delinquent: [] }.
+      module GetVoteAccounts
+        extend T::Sig
+
+        sig do
+          params(
+            commitment:  T.nilable(Symbol),
+            vote_pubkey: T.nilable(String)
+          ).returns(T::Hash[Symbol, T::Array[T.untyped]])
+        end
+        def get_vote_accounts(commitment: nil, vote_pubkey: nil)
+          config = {}
+          config['commitment']  = commitment.to_s  if commitment
+          config['votePubkey']  = vote_pubkey       if vote_pubkey
+
+          raw = transport.request('getVoteAccounts', config.empty? ? [] : [config])
+
+          parse_vote = Kernel.lambda do |v|
+            VoteAccountInfo.new(
+              vote_pubkey:        v['votePubkey'],
+              node_pubkey:        v['nodePubkey'],
+              activated_stake:    Kernel.Integer(v['activatedStake']),
+              epoch_vote_account: v['epochVoteAccount'],
+              commission:         Kernel.Integer(v['commission']),
+              last_vote:          Kernel.Integer(v['lastVote']),
+              epoch_credits:      v['epochCredits'],
+              root_slot:          v['rootSlot'] ? Kernel.Integer(v['rootSlot']) : nil
+            )
+          end
+
+          {
+            current:    Kernel.Array(raw['current']).map(&parse_vote),
+            delinquent: Kernel.Array(raw['delinquent']).map(&parse_vote)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/solana/ruby/kit/rpc/api/is_blockhash_valid.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 whether a blockhash is still valid (not yet expired).
+      # Mirrors TypeScript's `IsBlockhashValidApi.isBlockhashValid(blockhash, config?)`.
+      #
+      # Returns a `RpcContextualValue` with:
+      #   .slot  — context slot
+      #   .value — Boolean
+      module IsBlockhashValid
+        extend T::Sig
+
+        sig do
+          params(
+            blockhash:        String,
+            commitment:       T.nilable(Symbol),
+            min_context_slot: T.nilable(Integer)
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def is_blockhash_valid(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? ? [blockhash] : [blockhash, config]
+          result = transport.request('isBlockhashValid', params)
+
+          RpcTypes::RpcContextualValue.new(
+            slot:  Kernel.Integer(result['context']['slot']),
+            value: result['value'] == true
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative '../../keys/signatures'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Requests an airdrop of lamports to the given address.
+      # Only available on devnet and testnet.
+      # Mirrors TypeScript's `RequestAirdropApi.requestAirdrop(address, lamports, config?)`.
+      #
+      # Returns the transaction `Signature` of the airdrop.
+      module RequestAirdrop
+        extend T::Sig
+
+        sig do
+          params(
+            address:    String,
+            lamports:   Integer,
+            commitment: T.nilable(Symbol)
+          ).returns(Keys::Signature)
+        end
+        def request_airdrop(address, lamports, commitment: nil)
+          config = {}
+          config['commitment'] = commitment.to_s if commitment
+
+          params = config.empty? ? [address, lamports] : [address, lamports, config]
+          sig_str = transport.request('requestAirdrop', params)
+          Keys::Signature.new(sig_str)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require_relative '../../keys/signatures'
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Submits a signed transaction to the cluster for processing.
+      # Mirrors TypeScript's `SendTransactionApi.sendTransaction(transaction, config?)`.
+      #
+      # Accepts the transaction in two forms:
+      #   - A `Solana::Ruby::Kit::Transactions::Transaction` struct (wire bytes are base64-encoded internally).
+      #   - A raw base64 String (the already-encoded wire transaction).
+      #
+      # Returns a `Solana::Ruby::Kit::Keys::Signature` (base58-encoded transaction signature).
+      #
+      # Note: This method returns as soon as the node receives the transaction; it does
+      # NOT wait for confirmation.  Use `get_signature_statuses` to poll for commitment.
+      module SendTransaction
+        extend T::Sig
+
+        sig do
+          params(
+            transaction:          T.untyped,  # Transactions::Transaction or String (base64)
+            skip_preflight:       T::Boolean,
+            preflight_commitment: T.nilable(Symbol),
+            max_retries:          T.nilable(Integer),
+            min_context_slot:     T.nilable(Integer)
+          ).returns(Keys::Signature)
+        end
+        def send_transaction(
+          transaction,
+          skip_preflight:       false,
+          preflight_commitment: nil,
+          max_retries:          nil,
+          min_context_slot:     nil
+        )
+          wire_base64 =
+            case transaction
+            when String
+              transaction
+            else
+              # Assume it responds to .message_bytes (Transactions::Transaction)
+              Base64.strict_encode64(transaction.message_bytes)
+            end
+
+          config = { 'encoding' => 'base64' }
+          config['skipPreflight']       = skip_preflight if skip_preflight
+          config['preflightCommitment'] = preflight_commitment.to_s if preflight_commitment
+          config['maxRetries']          = max_retries if max_retries
+          config['minContextSlot']      = min_context_slot if min_context_slot
+
+          sig_str = transport.request('sendTransaction', [wire_base64, config])
+          Keys::Signature.new(sig_str)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Solana::Ruby::Kit
+  module Rpc
+    module Api
+      # Simulate a transaction without broadcasting it.
+      # Mirrors TypeScript's SimulateTransactionApi.simulateTransaction.
+      # Returns an RpcContextualValue whose value is the simulation result hash.
+      module SimulateTransaction
+        extend T::Sig
+
+        sig do
+          params(
+            encoded_transaction: String,
+            encoding:            String,
+            commitment:          T.nilable(Symbol),
+            sig_verify:          T::Boolean,
+            replace_recent_blockhash: T::Boolean,
+            accounts:            T.nilable(T::Hash[String, T.untyped])
+          ).returns(RpcTypes::RpcContextualValue)
+        end
+        def simulate_transaction(
+          encoded_transaction,
+          encoding:                 'base64',
+          commitment:               nil,
+          sig_verify:               false,
+          replace_recent_blockhash: false,
+          accounts:                 nil
+        )
+          config = {
+            'encoding'              => encoding,
+            'sigVerify'             => sig_verify,
+            'replaceRecentBlockhash' => replace_recent_blockhash
+          }
+          config['commitment'] = commitment.to_s if commitment
+          config['accounts']   = accounts if accounts
+
+          result = transport.request('simulateTransaction', [encoded_transaction, config])
+          slot   = Kernel.Integer(result['context']['slot'])
+
+          RpcTypes::RpcContextualValue.new(slot: slot, value: result['value'])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'transport'
+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_block_height'
+require_relative 'api/get_signature_statuses'
+require_relative 'api/send_transaction'
+require_relative 'api/request_airdrop'
+require_relative 'api/is_blockhash_valid'
+require_relative 'api/get_minimum_balance_for_rent_exemption'
+require_relative 'api/get_multiple_accounts'
+require_relative 'api/get_program_accounts'
+require_relative 'api/get_transaction'
+require_relative 'api/get_token_account_balance'
+require_relative 'api/get_token_accounts_by_owner'
+require_relative 'api/get_epoch_info'
+require_relative 'api/get_vote_accounts'
+require_relative 'api/simulate_transaction'
+
+module Solana::Ruby::Kit
+  module Rpc
+    # Solana JSON-RPC client.
+    # Mirrors TypeScript's `Rpc` object created by `createSolanaRpc(url)`.
+    #
+    # Includes every API method as a mixin so the class surface exactly matches
+    # the TypeScript package's method set.  The `transport` accessor provides
+    # sub-modules with the HTTP connection.
+    #
+    # @example
+    #   rpc  = Solana::Ruby::Kit::Rpc::Client.new(Solana::Ruby::Kit::RpcTypes.devnet)
+    #   slot = rpc.get_slot
+    #   res  = rpc.get_balance(address)
+    #   puts "#{res.value} lamports at slot #{res.slot}"
+    class Client
+      extend T::Sig
+
+      include Api::GetSlot
+      include Api::GetBalance
+      include Api::GetLatestBlockhash
+      include Api::GetAccountInfo
+      include Api::GetBlockHeight
+      include Api::GetSignatureStatuses
+      include Api::SendTransaction
+      include Api::RequestAirdrop
+      include Api::IsBlockhashValid
+      include Api::GetMinimumBalanceForRentExemption
+      include Api::GetMultipleAccounts
+      include Api::GetProgramAccounts
+      include Api::GetTransaction
+      include Api::GetTokenAccountBalance
+      include Api::GetTokenAccountsByOwner
+      include Api::GetEpochInfo
+      include Api::GetVoteAccounts
+      include Api::SimulateTransaction
+
+      sig { returns(Transport) }
+      attr_reader :transport
+
+      # @param cluster_url [RpcTypes::ClusterUrl, String]  endpoint to connect to.
+      # @param headers     [Hash<String, String>]           additional HTTP headers.
+      # @param timeout     [Integer]                        read timeout in seconds.
+      sig do
+        params(
+          cluster_url:  T.untyped,    # RpcTypes::ClusterUrl or String
+          headers:      T::Hash[String, String],
+          timeout:      Integer,
+          open_timeout: Integer
+        ).void
+      end
+      def initialize(cluster_url, headers: {}, timeout: Transport::DEFAULT_TIMEOUT, open_timeout: Transport::DEFAULT_OPEN_TIMEOUT)
+        url = cluster_url.respond_to?(:url) ? cluster_url.url : cluster_url.to_s
+        @transport = T.let(
+          Transport.new(url: url, headers: headers, timeout: timeout, open_timeout: open_timeout),
+          Transport
+        )
+      end
+    end
+  end
+end