k256-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 441531a7c9cb1a3c7e357c47f270cf941b935b9cad3fbb7708a301a2c2886810
+  data.tar.gz: '09304c0416afc3b6a68602fa072bd6bf101bd8acda4c6ffacf51725c86ee7825'
+SHA512:
+  metadata.gz: 7869faf88938bb6d508b27889460aa98b72f830bc63673aac9c7f8e9d635357573687cbd4dd8e46748e0a9e64e47b9ae1baca97c2c1e0cbf1e91e62c7bab176f
+  data.tar.gz: 001dc522decff3492664f432e1daa617fe56131ab899cbbd5f34d96a206e4dd567b67cffa81e832f6286bd68ded99ad22fe1bf789c0d789927b0c639a845c699

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 K256
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# K256 Ruby SDK
+
+Official Ruby SDK for [K256](https://k256.xyz) - the gateway to decentralized finance.
+
+Connect any application to Solana's liquidity ecosystem. One API. All venues. Full observability.
+
+[![Gem Version](https://badge.fury.io/rb/k256-sdk.svg)](https://badge.fury.io/rb/k256-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'k256-sdk'
+```
+
+Or install directly:
+
+```bash
+gem install k256-sdk
+```
+
+## Quick Start
+
+```ruby
+require 'k256'
+
+client = K256::Client.new(api_key: ENV['K256_API_KEY'])
+
+client.on_pool_update do |update|
+  puts "Pool #{update.pool_address}: slot=#{update.slot}"
+end
+
+client.on_priority_fees do |fees|
+  puts "Recommended fee: #{fees.recommended} microlamports"
+end
+
+client.on_blockhash do |bh|
+  puts "Blockhash: #{bh.blockhash} (slot #{bh.slot})"
+end
+
+client.on_error do |err|
+  puts "Error: #{err}"
+end
+
+client.connect
+client.subscribe(channels: ['pools', 'priority_fees', 'blockhash'])
+
+# Keep running
+sleep
+```
+
+## Module Structure
+
+```
+K256
+├── Client          # WebSocket client
+├── Decoder         # Binary message decoder
+├── Base58          # Base58 encoding utilities
+├── MessageType     # Message type constants
+├── PoolUpdate      # Pool state update struct
+├── PriorityFees    # Priority fees struct
+├── Blockhash       # Blockhash struct
+└── Quote           # Quote struct
+```
+
+## Architecture
+
+This SDK follows the cross-language conventions defined in [ARCHITECTURE.md](../ARCHITECTURE.md).
+
+## License
+
+MIT

data/lib/k256/base58.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module K256
+  # Base58 encoding/decoding utilities for Solana addresses.
+  module Base58
+    ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    BASE = ALPHABET.length
+    INDEXES = ALPHABET.each_char.with_index.to_h.freeze
+
+    class << self
+      # Encode bytes to base58 string.
+      #
+      # @param data [String, Array<Integer>] Bytes to encode
+      # @return [String] Base58-encoded string
+      def encode(data)
+        data = data.bytes if data.is_a?(String)
+        return "" if data.empty?
+
+        # Count leading zeros
+        leading_zeros = data.take_while(&:zero?).length
+
+        # Convert to big integer
+        num = data.reduce(0) { |acc, byte| (acc << 8) + byte }
+
+        # Convert to base58
+        result = []
+        while num.positive?
+          num, remainder = num.divmod(BASE)
+          result.unshift(ALPHABET[remainder])
+        end
+
+        # Add leading '1's for leading zeros
+        ("1" * leading_zeros) + result.join
+      end
+
+      # Decode base58 string to bytes.
+      #
+      # @param str [String] Base58-encoded string
+      # @return [Array<Integer>] Decoded bytes
+      # @raise [ArgumentError] if string contains invalid characters
+      def decode(str)
+        return [] if str.empty?
+
+        # Count leading '1's
+        leading_ones = str.chars.take_while { |c| c == "1" }.length
+
+        # Convert from base58 to integer
+        num = 0
+        str.each_char do |c|
+          index = INDEXES[c]
+          raise ArgumentError, "Invalid Base58 character: #{c}" if index.nil?
+
+          num = num * BASE + index
+        end
+
+        # Convert to bytes
+        result = []
+        while num.positive?
+          result.unshift(num & 0xFF)
+          num >>= 8
+        end
+
+        # Add leading zero bytes
+        ([0] * leading_ones) + result
+      end
+
+      # Check if a string is a valid Solana public key.
+      #
+      # @param address [String] Base58-encoded address
+      # @return [Boolean] True if valid
+      def valid_pubkey?(address)
+        return false if address.nil? || address.length < 32 || address.length > 44
+
+        begin
+          decoded = decode(address)
+          decoded.length == 32
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/k256/client.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "websocket-client-simple"
+require "json"
+
+module K256
+  # K256 WebSocket client for real-time Solana liquidity data.
+  #
+  # @example
+  #   client = K256::Client.new(api_key: ENV['K256_API_KEY'])
+  #
+  #   client.on_pool_update { |update| puts update.pool_address }
+  #   client.on_priority_fees { |fees| puts fees.recommended }
+  #
+  #   client.connect
+  #   client.subscribe(channels: ['pools', 'priority_fees', 'blockhash'])
+  class Client
+    DEFAULT_ENDPOINT = "wss://gateway.k256.xyz/v1/ws"
+
+    attr_reader :api_key, :endpoint, :reconnect, :connected
+
+    # Create a new K256 WebSocket client.
+    #
+    # @param api_key [String] K256 API key
+    # @param endpoint [String] WebSocket endpoint URL
+    # @param reconnect [Boolean] Whether to automatically reconnect
+    # @param reconnect_delay_initial [Float] Initial reconnect delay in seconds
+    # @param reconnect_delay_max [Float] Maximum reconnect delay in seconds
+    def initialize(
+      api_key:,
+      endpoint: DEFAULT_ENDPOINT,
+      reconnect: true,
+      reconnect_delay_initial: 1.0,
+      reconnect_delay_max: 60.0
+    )
+      @api_key = api_key
+      @endpoint = endpoint
+      @reconnect = reconnect
+      @reconnect_delay_initial = reconnect_delay_initial
+      @reconnect_delay_max = reconnect_delay_max
+      @reconnect_delay = reconnect_delay_initial
+
+      @callbacks = {}
+      @ws = nil
+      @connected = false
+      @running = false
+      @last_subscription = nil
+    end
+
+    # Register a callback for pool updates.
+    #
+    # @yield [PoolUpdate] Pool update
+    def on_pool_update(&block)
+      @callbacks[:pool_update] = block
+    end
+
+    # Register a callback for priority fee updates.
+    #
+    # @yield [PriorityFees] Priority fees
+    def on_priority_fees(&block)
+      @callbacks[:priority_fees] = block
+    end
+
+    # Register a callback for blockhash updates.
+    #
+    # @yield [Blockhash] Blockhash
+    def on_blockhash(&block)
+      @callbacks[:blockhash] = block
+    end
+
+    # Register a callback for quote updates.
+    #
+    # @yield [Quote] Quote
+    def on_quote(&block)
+      @callbacks[:quote] = block
+    end
+
+    # Register a callback for heartbeat messages.
+    #
+    # @yield [Heartbeat] Heartbeat
+    def on_heartbeat(&block)
+      @callbacks[:heartbeat] = block
+    end
+
+    # Register a callback for errors.
+    #
+    # @yield [String] Error message
+    def on_error(&block)
+      @callbacks[:error] = block
+    end
+
+    # Register a callback for connection established.
+    #
+    # @yield Called when connected
+    def on_connected(&block)
+      @callbacks[:connected] = block
+    end
+
+    # Register a callback for disconnection.
+    #
+    # @yield Called when disconnected
+    def on_disconnected(&block)
+      @callbacks[:disconnected] = block
+    end
+
+    # Connect to the K256 WebSocket.
+    def connect
+      @running = true
+      do_connect
+    end
+
+    # Disconnect from the WebSocket.
+    def disconnect
+      @running = false
+      @ws&.close
+      @ws = nil
+      @connected = false
+    end
+
+    # Subscribe to channels.
+    #
+    # @param channels [Array<String>] List of channels
+    # @param protocols [Array<String>, nil] Optional DEX protocols to filter
+    # @param pools [Array<String>, nil] Optional pool addresses to filter
+    # @param token_pairs [Array<Array<String>>, nil] Optional token pairs to filter
+    def subscribe(channels:, protocols: nil, pools: nil, token_pairs: nil)
+      @last_subscription = {
+        channels: channels,
+        protocols: protocols,
+        pools: pools,
+        token_pairs: token_pairs
+      }
+
+      send_subscribe if @connected
+    end
+
+    # Unsubscribe from all channels.
+    def unsubscribe
+      @last_subscription = nil
+      send_json(type: "unsubscribe") if @connected
+    end
+
+    private
+
+    def do_connect
+      url = "#{@endpoint}?apiKey=#{@api_key}"
+
+      @ws = WebSocket::Client::Simple.connect(url)
+      client = self
+
+      @ws.on :open do
+        client.send(:handle_open)
+      end
+
+      @ws.on :message do |msg|
+        client.send(:handle_message, msg)
+      end
+
+      @ws.on :close do |e|
+        client.send(:handle_close, e)
+      end
+
+      @ws.on :error do |e|
+        client.send(:handle_error, e)
+      end
+    end
+
+    def handle_open
+      @connected = true
+      @reconnect_delay = @reconnect_delay_initial
+      @callbacks[:connected]&.call
+      send_subscribe if @last_subscription
+    end
+
+    def handle_message(msg)
+      if msg.type == :binary
+        handle_binary_message(msg.data)
+      else
+        handle_text_message(msg.data)
+      end
+    end
+
+    def handle_binary_message(data)
+      return if data.bytesize < 1
+
+      msg_type = data.getbyte(0)
+      payload = data[1..]
+
+      case msg_type
+      when MessageType::POOL_UPDATE
+        if @callbacks[:pool_update]
+          update = Decoder.decode_pool_update(payload)
+          @callbacks[:pool_update].call(update) if update
+        end
+      when MessageType::POOL_UPDATE_BATCH
+        if @callbacks[:pool_update]
+          updates = Decoder.decode_pool_update_batch(payload)
+          updates.each { |u| @callbacks[:pool_update].call(u) }
+        end
+      when MessageType::PRIORITY_FEES
+        if @callbacks[:priority_fees]
+          fees = Decoder.decode_priority_fees(payload)
+          @callbacks[:priority_fees].call(fees) if fees
+        end
+      when MessageType::BLOCKHASH
+        if @callbacks[:blockhash]
+          bh = Decoder.decode_blockhash(payload)
+          @callbacks[:blockhash].call(bh) if bh
+        end
+      when MessageType::QUOTE
+        if @callbacks[:quote]
+          quote = Decoder.decode_quote(payload)
+          @callbacks[:quote].call(quote) if quote
+        end
+      when MessageType::ERROR
+        @callbacks[:error]&.call(payload.force_encoding("UTF-8"))
+      end
+    end
+
+    def handle_text_message(data)
+      json = JSON.parse(data)
+      type = json["type"]
+
+      case type
+      when "heartbeat"
+        if @callbacks[:heartbeat]
+          hb = Heartbeat.new(
+            timestamp_ms: json["timestamp_ms"],
+            uptime_seconds: json["uptime_seconds"],
+            messages_received: json["messages_received"],
+            messages_sent: json["messages_sent"],
+            subscriptions: json["subscriptions"]
+          )
+          @callbacks[:heartbeat].call(hb)
+        end
+      when "subscribed"
+        # Subscription confirmed
+      when "error"
+        @callbacks[:error]&.call(json["message"])
+      end
+    rescue JSON::ParserError
+      # Ignore invalid JSON
+    end
+
+    def handle_close(_event)
+      @connected = false
+      @callbacks[:disconnected]&.call
+
+      schedule_reconnect if @running && @reconnect
+    end
+
+    def handle_error(error)
+      @callbacks[:error]&.call(error.message)
+    end
+
+    def schedule_reconnect
+      jitter = rand * 0.5
+      delay = [@reconnect_delay + jitter, @reconnect_delay_max].min
+
+      Thread.new do
+        sleep(delay)
+        do_connect if @running
+      end
+
+      @reconnect_delay = [@reconnect_delay * 2, @reconnect_delay_max].min
+    end
+
+    def send_subscribe
+      return unless @last_subscription
+
+      msg = { type: "subscribe", channels: @last_subscription[:channels] }
+      msg[:protocols] = @last_subscription[:protocols] if @last_subscription[:protocols]
+      msg[:pools] = @last_subscription[:pools] if @last_subscription[:pools]
+      msg[:token_pairs] = @last_subscription[:token_pairs] if @last_subscription[:token_pairs]
+
+      send_json(msg)
+    end
+
+    def send_json(data)
+      @ws&.send(data.to_json)
+    end
+  end
+end

data/lib/k256/decoder.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module K256
+  # Binary message decoder for K256 WebSocket protocol.
+  module Decoder
+    class << self
+      # Decode priority fees from binary payload.
+      # Wire format: 119 bytes, little-endian.
+      #
+      # @param data [String] Binary payload (without message type byte)
+      # @return [PriorityFees, nil] Decoded fees or nil if too short
+      def decode_priority_fees(data)
+        return nil if data.bytesize < 119
+
+        bytes = data.bytes
+
+        PriorityFees.new(
+          slot: read_u64_le(bytes, 0),
+          timestamp_ms: read_u64_le(bytes, 8),
+          recommended: read_u64_le(bytes, 16),
+          state: bytes[24],
+          is_stale: bytes[25] != 0,
+          swap_p50: read_u64_le(bytes, 26),
+          swap_p75: read_u64_le(bytes, 34),
+          swap_p90: read_u64_le(bytes, 42),
+          swap_p99: read_u64_le(bytes, 50),
+          swap_samples: read_u32_le(bytes, 58),
+          landing_p50_fee: read_u64_le(bytes, 62),
+          landing_p75_fee: read_u64_le(bytes, 70),
+          landing_p90_fee: read_u64_le(bytes, 78),
+          landing_p99_fee: read_u64_le(bytes, 86),
+          top_10_fee: read_u64_le(bytes, 94),
+          top_25_fee: read_u64_le(bytes, 102),
+          spike_detected: bytes[110] != 0,
+          spike_fee: read_u64_le(bytes, 111)
+        )
+      end
+
+      # Decode blockhash from binary payload.
+      # Wire format: 65 bytes, little-endian.
+      #
+      # @param data [String] Binary payload (without message type byte)
+      # @return [Blockhash, nil] Decoded blockhash or nil if too short
+      def decode_blockhash(data)
+        return nil if data.bytesize < 65
+
+        bytes = data.bytes
+
+        Blockhash.new(
+          slot: read_u64_le(bytes, 0),
+          timestamp_ms: read_u64_le(bytes, 8),
+          blockhash: Base58.encode(bytes[16, 32]),
+          block_height: read_u64_le(bytes, 48),
+          last_valid_block_height: read_u64_le(bytes, 56),
+          is_stale: bytes[64] != 0
+        )
+      end
+
+      # Decode a single pool update from binary payload.
+      #
+      # @param data [String] Binary payload (without message type byte)
+      # @return [PoolUpdate, nil] Decoded update or nil if decoding fails
+      def decode_pool_update(data)
+        return nil if data.bytesize < 8
+
+        bytes = data.bytes
+        offset = 0
+
+        # serialized_state: Bytes (u64 len + bytes)
+        state_len = read_u64_le(bytes, offset)
+        offset += 8
+        return nil if offset + state_len > bytes.length
+        serialized_state = bytes[offset, state_len].pack("C*")
+        offset += state_len
+
+        # sequence (u64)
+        return nil if offset + 8 > bytes.length
+        sequence = read_u64_le(bytes, offset)
+        offset += 8
+
+        # slot (u64)
+        return nil if offset + 8 > bytes.length
+        slot = read_u64_le(bytes, offset)
+        offset += 8
+
+        # write_version (u64)
+        return nil if offset + 8 > bytes.length
+        write_version = read_u64_le(bytes, offset)
+        offset += 8
+
+        # protocol_name: String (u64 len + UTF-8 bytes)
+        return nil if offset + 8 > bytes.length
+        protocol_len = read_u64_le(bytes, offset)
+        offset += 8
+        return nil if offset + protocol_len > bytes.length
+        protocol_name = bytes[offset, protocol_len].pack("C*").force_encoding("UTF-8")
+        offset += protocol_len
+
+        # pool_address: [u8; 32]
+        return nil if offset + 32 > bytes.length
+        pool_address = Base58.encode(bytes[offset, 32])
+        offset += 32
+
+        # all_token_mints: Vec<[u8; 32]>
+        return nil if offset + 8 > bytes.length
+        mint_count = read_u64_le(bytes, offset)
+        offset += 8
+        return nil if offset + mint_count * 32 > bytes.length
+        token_mints = mint_count.times.map do
+          mint = Base58.encode(bytes[offset, 32])
+          offset += 32
+          mint
+        end
+
+        # all_token_balances: Vec<u64>
+        return nil if offset + 8 > bytes.length
+        balance_count = read_u64_le(bytes, offset)
+        offset += 8
+        return nil if offset + balance_count * 8 > bytes.length
+        token_balances = balance_count.times.map do
+          balance = read_u64_le(bytes, offset)
+          offset += 8
+          balance
+        end
+
+        # all_token_decimals: Vec<i32>
+        return nil if offset + 8 > bytes.length
+        decimals_count = read_u64_le(bytes, offset)
+        offset += 8
+        return nil if offset + decimals_count * 4 > bytes.length
+        token_decimals = decimals_count.times.map do
+          dec = read_i32_le(bytes, offset)
+          offset += 4
+          dec
+        end
+
+        # best_bid: Option<OrderLevel>
+        best_bid = nil
+        if offset < bytes.length && bytes[offset] == 1
+          offset += 1
+          return nil if offset + 16 > bytes.length
+          best_bid = OrderLevel.new(
+            price: read_u64_le(bytes, offset),
+            size: read_u64_le(bytes, offset + 8)
+          )
+          offset += 16
+        elsif offset < bytes.length
+          offset += 1
+        end
+
+        # best_ask: Option<OrderLevel>
+        best_ask = nil
+        if offset < bytes.length && bytes[offset] == 1
+          offset += 1
+          return nil if offset + 16 > bytes.length
+          best_ask = OrderLevel.new(
+            price: read_u64_le(bytes, offset),
+            size: read_u64_le(bytes, offset + 8)
+          )
+        end
+
+        PoolUpdate.new(
+          sequence: sequence,
+          slot: slot,
+          write_version: write_version,
+          protocol_name: protocol_name,
+          pool_address: pool_address,
+          token_mints: token_mints,
+          token_balances: token_balances,
+          token_decimals: token_decimals,
+          best_bid: best_bid,
+          best_ask: best_ask,
+          serialized_state: serialized_state
+        )
+      rescue StandardError
+        nil
+      end
+
+      # Decode a batch of pool updates.
+      # Wire format: [u16 count][u32 len1][payload1]...
+      #
+      # @param data [String] Binary payload (without message type byte)
+      # @return [Array<PoolUpdate>] Decoded updates
+      def decode_pool_update_batch(data)
+        return [] if data.bytesize < 2
+
+        bytes = data.bytes
+        count = read_u16_le(bytes, 0)
+        offset = 2
+
+        updates = []
+        count.times do
+          break if offset + 4 > bytes.length
+
+          payload_len = read_u32_le(bytes, offset)
+          offset += 4
+
+          break if offset + payload_len > bytes.length
+
+          update_data = bytes[offset, payload_len].pack("C*")
+          update = decode_pool_update(update_data)
+          updates << update if update
+
+          offset += payload_len
+        end
+
+        updates
+      end
+
+      # Decode a quote from binary payload.
+      #
+      # @param data [String] Binary payload (without message type byte)
+      # @return [Quote, nil] Decoded quote or nil if decoding fails
+      def decode_quote(data)
+        return nil if data.bytesize < 8
+
+        bytes = data.bytes
+        offset = 0
+
+        # topic_id: String (u64 len + UTF-8 bytes)
+        topic_len = read_u64_le(bytes, offset)
+        offset += 8
+        topic_id = bytes[offset, topic_len].pack("C*").force_encoding("UTF-8")
+        offset += topic_len
+
+        # timestamp_ms (u64)
+        timestamp_ms = read_u64_le(bytes, offset)
+        offset += 8
+
+        # sequence (u64)
+        sequence = read_u64_le(bytes, offset)
+        offset += 8
+
+        # input_mint ([u8; 32])
+        input_mint = Base58.encode(bytes[offset, 32])
+        offset += 32
+
+        # output_mint ([u8; 32])
+        output_mint = Base58.encode(bytes[offset, 32])
+        offset += 32
+
+        # in_amount (u64)
+        in_amount = read_u64_le(bytes, offset)
+        offset += 8
+
+        # out_amount (u64)
+        out_amount = read_u64_le(bytes, offset)
+        offset += 8
+
+        # price_impact_bps (i32)
+        price_impact_bps = read_i32_le(bytes, offset)
+        offset += 4
+
+        # context_slot (u64)
+        context_slot = read_u64_le(bytes, offset)
+        offset += 8
+
+        # algorithm: String (u64 len + UTF-8 bytes)
+        algo_len = read_u64_le(bytes, offset)
+        offset += 8
+        algorithm = bytes[offset, algo_len].pack("C*").force_encoding("UTF-8")
+        offset += algo_len
+
+        # is_improvement (bool)
+        is_improvement = bytes[offset] != 0
+        offset += 1
+
+        # is_cached (bool)
+        is_cached = bytes[offset] != 0
+        offset += 1
+
+        # is_stale (bool)
+        is_stale = bytes[offset] != 0
+        offset += 1
+
+        # route_plan_json: Vec<u8> (u64 len + bytes)
+        route_plan_json = nil
+        if offset + 8 <= bytes.length
+          route_len = read_u64_le(bytes, offset)
+          offset += 8
+          if route_len.positive? && offset + route_len <= bytes.length
+            route_plan_json = bytes[offset, route_len].pack("C*").force_encoding("UTF-8")
+          end
+        end
+
+        Quote.new(
+          topic_id: topic_id,
+          timestamp_ms: timestamp_ms,
+          sequence: sequence,
+          input_mint: input_mint,
+          output_mint: output_mint,
+          in_amount: in_amount,
+          out_amount: out_amount,
+          price_impact_bps: price_impact_bps,
+          context_slot: context_slot,
+          algorithm: algorithm,
+          is_improvement: is_improvement,
+          is_cached: is_cached,
+          is_stale: is_stale,
+          route_plan_json: route_plan_json
+        )
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def read_u64_le(bytes, offset)
+        bytes[offset, 8].each_with_index.reduce(0) do |acc, (byte, i)|
+          acc | (byte << (i * 8))
+        end
+      end
+
+      def read_u32_le(bytes, offset)
+        bytes[offset, 4].each_with_index.reduce(0) do |acc, (byte, i)|
+          acc | (byte << (i * 8))
+        end
+      end
+
+      def read_u16_le(bytes, offset)
+        bytes[offset] | (bytes[offset + 1] << 8)
+      end
+
+      def read_i32_le(bytes, offset)
+        val = read_u32_le(bytes, offset)
+        val >= 0x80000000 ? val - 0x100000000 : val
+      end
+    end
+  end
+end

data/lib/k256/types.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module K256
+  # WebSocket binary message type identifiers.
+  # These correspond to the first byte of each binary message.
+  module MessageType
+    POOL_UPDATE       = 0x01 # Server → Client: Single pool update
+    SUBSCRIBE         = 0x02 # Client → Server: Subscribe request (JSON)
+    SUBSCRIBED        = 0x03 # Server → Client: Subscription confirmed (JSON)
+    UNSUBSCRIBE       = 0x04 # Client → Server: Unsubscribe all
+    PRIORITY_FEES     = 0x05 # Server → Client: Priority fee update
+    BLOCKHASH         = 0x06 # Server → Client: Recent blockhash
+    QUOTE             = 0x07 # Server → Client: Streaming quote update
+    QUOTE_SUBSCRIBED  = 0x08 # Server → Client: Quote subscription confirmed
+    SUBSCRIBE_QUOTE   = 0x09 # Client → Server: Subscribe to quote stream
+    UNSUBSCRIBE_QUOTE = 0x0A # Client → Server: Unsubscribe from quote
+    PING              = 0x0B # Client → Server: Ping keepalive
+    PONG              = 0x0C # Server → Client: Pong response
+    HEARTBEAT         = 0x0D # Server → Client: Connection stats (JSON)
+    POOL_UPDATE_BATCH = 0x0E # Server → Client: Batched pool updates
+    ERROR             = 0xFF # Server → Client: Error message (UTF-8)
+  end
+
+  # Network congestion state.
+  module NetworkState
+    LOW     = 0 # Low congestion - minimal fees needed
+    NORMAL  = 1 # Normal congestion
+    HIGH    = 2 # High congestion - higher fees recommended
+    EXTREME = 3 # Extreme congestion - maximum fees recommended
+  end
+
+  # Order book level with price and size.
+  OrderLevel = Struct.new(:price, :size, keyword_init: true)
+
+  # Real-time pool state update from K256 WebSocket.
+  PoolUpdate = Struct.new(
+    :sequence,
+    :slot,
+    :write_version,
+    :protocol_name,
+    :pool_address,
+    :token_mints,
+    :token_balances,
+    :token_decimals,
+    :best_bid,
+    :best_ask,
+    :serialized_state,
+    keyword_init: true
+  )
+
+  # Priority fee recommendations from K256.
+  # Wire format: 119 bytes, little-endian.
+  PriorityFees = Struct.new(
+    :slot,             # offset 0
+    :timestamp_ms,     # offset 8
+    :recommended,      # offset 16
+    :state,            # offset 24
+    :is_stale,         # offset 25
+    :swap_p50,         # offset 26
+    :swap_p75,         # offset 34
+    :swap_p90,         # offset 42
+    :swap_p99,         # offset 50
+    :swap_samples,     # offset 58
+    :landing_p50_fee,  # offset 62
+    :landing_p75_fee,  # offset 70
+    :landing_p90_fee,  # offset 78
+    :landing_p99_fee,  # offset 86
+    :top_10_fee,       # offset 94
+    :top_25_fee,       # offset 102
+    :spike_detected,   # offset 110
+    :spike_fee,        # offset 111
+    keyword_init: true
+  )
+
+  # Recent blockhash from K256.
+  # Wire format: 65 bytes, little-endian.
+  Blockhash = Struct.new(
+    :slot,                    # offset 0
+    :timestamp_ms,            # offset 8
+    :blockhash,               # offset 16 (32 bytes)
+    :block_height,            # offset 48
+    :last_valid_block_height, # offset 56
+    :is_stale,                # offset 64
+    keyword_init: true
+  )
+
+  # Swap quote from K256.
+  Quote = Struct.new(
+    :topic_id,
+    :timestamp_ms,
+    :sequence,
+    :input_mint,
+    :output_mint,
+    :in_amount,
+    :out_amount,
+    :price_impact_bps,
+    :context_slot,
+    :algorithm,
+    :is_improvement,
+    :is_cached,
+    :is_stale,
+    :route_plan_json,
+    keyword_init: true
+  )
+
+  # Connection heartbeat with stats.
+  Heartbeat = Struct.new(
+    :timestamp_ms,
+    :uptime_seconds,
+    :messages_received,
+    :messages_sent,
+    :subscriptions,
+    keyword_init: true
+  )
+
+  # Token metadata.
+  Token = Struct.new(
+    :address,
+    :symbol,
+    :name,
+    :decimals,
+    :logo_uri,
+    :tags,
+    :extensions,
+    keyword_init: true
+  )
+end

data/lib/k256/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module K256
+  VERSION = "0.1.0"
+end

data/lib/k256.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "k256/version"
+require_relative "k256/types"
+require_relative "k256/base58"
+require_relative "k256/decoder"
+require_relative "k256/client"
+
+# K256 SDK - The gateway to Solana's liquidity ecosystem
+#
+# @example
+#   require 'k256'
+#
+#   client = K256::Client.new(api_key: ENV['K256_API_KEY'])
+#
+#   client.on_pool_update do |update|
+#     puts "Pool #{update.pool_address}: slot=#{update.slot}"
+#   end
+#
+#   client.connect
+#   client.subscribe(channels: ['pools', 'priority_fees', 'blockhash'])
+module K256
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class DecodeError < Error; end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: k256-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- K256
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-01-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: Connect any application to Solana's liquidity ecosystem. One API. All
+  venues. Full observability.
+email:
+- support@k256.xyz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/k256.rb
+- lib/k256/base58.rb
+- lib/k256/client.rb
+- lib/k256/decoder.rb
+- lib/k256/types.rb
+- lib/k256/version.rb
+homepage: https://k256.xyz
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://k256.xyz
+  source_code_uri: https://github.com/k256-xyz/k256-sdks
+  changelog_uri: https://github.com/k256-xyz/k256-sdks/releases
+  documentation_uri: https://docs.k256.xyz
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for K256 - the gateway to Solana's liquidity ecosystem
+test_files: []