@k256/sdk 0.1.4 → 0.1.7

package/src/types/index.ts

@@ -1,8 +1,8 @@
 /**
  * Shared type definitions for K256 SDK
- * 
+ *
  * These types are used across WebSocket and REST API modules.
- * 
+ *
  * @module @k256/sdk/types
  */
 
@@ -20,8 +20,6 @@ export interface Pool {
   tokenBalances: string[];
   /** Token decimals */
   tokenDecimals: number[];
-  /** Whether pool is valid for trading */
-  isValid: boolean;
 }
 
 /**
@@ -109,24 +107,59 @@ export interface RoutePlanStep {
 }
 
 /**
- * Priority fee estimates
+ * Per-writable-account fee data
+ *
+ * Solana's scheduler limits each writable account to 12M CU per block.
+ * Fee pricing is per-account: the fee you pay should be
+ * max(p75(account) for account in your writable accounts).
  */
-export interface PriorityFees {
+export interface AccountFee {
+  /** Account public key (Base58) */
+  pubkey: string;
+  /** Total transactions touching this account in the window */
+  totalTxs: number;
+  /** Number of slots where this account was active */
+  activeSlots: number;
+  /** Total CU consumed by transactions touching this account */
+  cuConsumed: number;
+  /** Account utilization percentage (0-100) of 12M CU limit */
+  utilizationPct: number;
+  /** 25th percentile fee in microlamports/CU */
+  p25: number;
+  /** 50th percentile fee in microlamports/CU */
+  p50: number;
+  /** 75th percentile fee in microlamports/CU */
+  p75: number;
+  /** 90th percentile fee in microlamports/CU */
+  p90: number;
+  /** Minimum non-zero fee observed */
+  minNonzeroPrice: number;
+}
+
+/**
+ * Fee market update (per-writable-account model)
+ *
+ * Replaces the old flat PriorityFees struct. Now provides per-account
+ * fee data so clients can price transactions based on the specific
+ * writable accounts they touch.
+ */
+export interface FeeMarket {
   /** Current slot */
   slot: number;
   /** Timestamp in milliseconds */
   timestampMs: number;
-  /** Recommended fee in microlamports */
+  /** Recommended fee in microlamports/CU (max p75 across hottest accounts) */
   recommended: number;
-  /** Network state (0=low, 1=normal, 2=high, 3=congested) */
+  /** Network state (0=low, 1=normal, 2=high, 3=extreme) */
   state: NetworkState;
   /** Whether data is stale */
   isStale: boolean;
-  /** Swap fee percentiles */
-  swapP50: number;
-  swapP75: number;
-  swapP90: number;
-  swapP99: number;
+  /** Block utilization percentage (0-100) */
+  blockUtilizationPct: number;
+  /** Number of blocks in the observation window */
+  blocksInWindow: number;
+  /** Per-account fee data */
+  accounts: AccountFee[];
 }
 
 /**

package/src/utils/base58.ts

@@ -58,9 +58,19 @@ export function base58Encode(bytes: Uint8Array): string {
  * ```
  */
 export function base58Decode(str: string): Uint8Array {
+  if (str.length === 0) {
+    return new Uint8Array(0);
+  }
+
+  // Count leading '1's (they represent leading zero bytes)
+  let leadingZeros = 0;
+  for (let i = 0; i < str.length && str[i] === '1'; i++) {
+    leadingZeros++;
+  }
+
+  // Process remaining characters through base conversion
   const bytes = [0];
-  
-  for (let i = 0; i < str.length; i++) {
+  for (let i = leadingZeros; i < str.length; i++) {
     const char = str[i];
     const value = BASE58_ALPHABET.indexOf(char);
     
@@ -80,12 +90,30 @@ export function base58Decode(str: string): Uint8Array {
     }
   }
 
-  // Leading '1's are leading zeros
-  for (let i = 0; i < str.length && str[i] === '1'; i++) {
-    bytes.push(0);
+  // Build result: leading zeros + converted bytes (reversed)
+  bytes.reverse();
+  
+  // Handle case where input was all '1's (all leading zeros, no data to convert)
+  // In this case, bytes is just [0] from initialization, which we should ignore
+  if (leadingZeros > 0 && bytes.length === 1 && bytes[0] === 0) {
+    // Input was all '1's, return that many zero bytes
+    return new Uint8Array(leadingZeros);
   }
-
-  return new Uint8Array(bytes.reverse());
+  
+  // Remove leading zero from conversion if present (artifact of starting with [0])
+  const startIdx = bytes.length > 1 && bytes[0] === 0 ? 1 : 0;
+  
+  const result = new Uint8Array(leadingZeros + bytes.length - startIdx);
+  // Fill leading zeros
+  for (let i = 0; i < leadingZeros; i++) {
+    result[i] = 0;
+  }
+  // Copy converted bytes
+  for (let i = startIdx; i < bytes.length; i++) {
+    result[leadingZeros + i - startIdx] = bytes[i];
+  }
+  
+  return result;
 }
 
 /**

package/src/ws/client.ts

@@ -83,7 +83,7 @@ export interface SubscribeOptions {
   channels: string[];
   /** Pool address filters (optional) */
   pools?: string[];
-  /** Protocol filters (optional): 'Raydium AMM', 'Orca Whirlpool', etc. */
+  /** Protocol filters (optional): 'RaydiumAmm', 'Whirlpool', 'MeteoraDlmm', etc. */
   protocols?: string[];
   /** Token pair filters (optional): [['mint1', 'mint2'], ...] */
   tokenPairs?: string[][];
@@ -153,8 +153,8 @@ export interface K256WebSocketClientConfig {
   onPoolUpdate?: (update: PoolUpdateMessage) => void;
   /** Called on batched pool updates (for efficiency) */
   onPoolUpdateBatch?: (updates: PoolUpdateMessage[]) => void;
-  /** Called on priority fees update */
-  onPriorityFees?: (data: DecodedMessage & { type: 'priority_fees' }) => void;
+  /** Called on fee market update (per-writable-account fees) */
+  onFeeMarket?: (data: DecodedMessage & { type: 'fee_market' }) => void;
   /** Called on blockhash update */
   onBlockhash?: (data: DecodedMessage & { type: 'blockhash' }) => void;
   /** Called on quote update */
@@ -225,7 +225,7 @@ export class K256WebSocketClient {
   private ws: WebSocket | null = null;
   private config: Required<Omit<K256WebSocketClientConfig, 
     'onStateChange' | 'onConnect' | 'onDisconnect' | 'onReconnecting' | 'onError' |
-    'onSubscribed' | 'onPoolUpdate' | 'onPoolUpdateBatch' | 'onPriorityFees' | 
+    'onSubscribed' | 'onPoolUpdate' | 'onPoolUpdateBatch' | 'onFeeMarket' |
     'onBlockhash' | 'onQuote' | 'onQuoteSubscribed' | 'onHeartbeat' | 'onPong' | 
     'onMessage' | 'onRawMessage'
   >> & K256WebSocketClientConfig;
@@ -536,8 +536,8 @@ export class K256WebSocketClient {
         case 'pool_update':
           this.config.onPoolUpdate?.(decoded as PoolUpdateMessage);
           break;
-        case 'priority_fees':
-          this.config.onPriorityFees?.(decoded as DecodedMessage & { type: 'priority_fees' });
+        case 'fee_market':
+          this.config.onFeeMarket?.(decoded as DecodedMessage & { type: 'fee_market' });
           break;
         case 'blockhash':
           this.config.onBlockhash?.(decoded as DecodedMessage & { type: 'blockhash' });

package/src/ws/decoder.ts

@@ -8,7 +8,7 @@
  */
 
 import { base58Encode } from '../utils/base58';
-import { MessageType, type DecodedMessage, type PoolUpdateMessage } from './types';
+import { MessageType, type DecodedMessage, type PoolUpdateMessage, type FeeMarketMessage } from './types';
 
 /**
  * Decode a binary WebSocket message from K2
@@ -69,84 +69,60 @@ export function decodeMessage(data: ArrayBuffer): DecodedMessage | null {
     }
 
     case MessageType.PriorityFees: {
-      // PriorityFeesWire bincode layout:
-      // Offset 0:  slot: u64
-      // Offset 8:  timestamp_ms: u64
-      // Offset 16: recommended: u64
-      // Offset 24: state: u8 (0=low, 1=normal, 2=high, 3=extreme)
-      // Offset 25: is_stale: bool
-      // Offset 26: swap_p50: u64
-      // Offset 34: swap_p75: u64
-      // Offset 42: swap_p90: u64
-      // Offset 50: swap_p99: u64
-      // Offset 58: swap_samples: u32
-      // Offset 62: landing_p50_fee: u64
-      // Offset 70: landing_p75_fee: u64
-      // Offset 78: landing_p90_fee: u64
-      // Offset 86: landing_p99_fee: u64
-      // Offset 94: top_10_fee: u64
-      // Offset 102: top_25_fee: u64
-      // Offset 110: spike_detected: bool
-      // Offset 111: spike_fee: u64
-      // Total: 119 bytes
-      if (payload.byteLength < 24) return null;
+      // FeeMarketWire bincode layout (per-writable-account model):
+      // Header (42 bytes):
+      //   Offset 0:  slot: u64 (8 bytes)
+      //   Offset 8:  timestamp_ms: u64 (8 bytes)
+      //   Offset 16: recommended: u64 (8 bytes)
+      //   Offset 24: state: u8 (1 byte)
+      //   Offset 25: is_stale: bool (1 byte)
+      //   Offset 26: block_utilization_pct: f32 (4 bytes)
+      //   Offset 30: blocks_in_window: u32 (4 bytes)
+      //   Offset 34: account_count: u64 (8 bytes) [bincode Vec length]
+      // Per account (92 bytes each):
+      //   pubkey: [u8; 32], total_txs: u32, active_slots: u32,
+      //   cu_consumed: u64, utilization_pct: f32,
+      //   p25: u64, p50: u64, p75: u64, p90: u64, min_nonzero_price: u64
+      if (payload.byteLength < 42) return null;
 
       const slot = Number(payloadView.getBigUint64(0, true));
       const timestampMs = Number(payloadView.getBigUint64(8, true));
       const recommended = Number(payloadView.getBigUint64(16, true));
-      const state = payload.byteLength > 24 ? payloadView.getUint8(24) : 1;
-      const isStale = payload.byteLength > 25 ? payloadView.getUint8(25) !== 0 : false;
-
-      // Swap percentiles (offset 26-57)
-      let swapP50 = 0, swapP75 = 0, swapP90 = 0, swapP99 = 0;
-      if (payload.byteLength >= 58) {
-        swapP50 = Number(payloadView.getBigUint64(26, true));
-        swapP75 = Number(payloadView.getBigUint64(34, true));
-        swapP90 = Number(payloadView.getBigUint64(42, true));
-        swapP99 = Number(payloadView.getBigUint64(50, true));
-      }
-
-      // Extended fields (offset 58+)
-      let swapSamples = 0;
-      let landingP50Fee = 0, landingP75Fee = 0, landingP90Fee = 0, landingP99Fee = 0;
-      let top10Fee = 0, top25Fee = 0;
-      let spikeDetected = false, spikeFee = 0;
-
-      if (payload.byteLength >= 119) {
-        swapSamples = payloadView.getUint32(58, true);
-        landingP50Fee = Number(payloadView.getBigUint64(62, true));
-        landingP75Fee = Number(payloadView.getBigUint64(70, true));
-        landingP90Fee = Number(payloadView.getBigUint64(78, true));
-        landingP99Fee = Number(payloadView.getBigUint64(86, true));
-        top10Fee = Number(payloadView.getBigUint64(94, true));
-        top25Fee = Number(payloadView.getBigUint64(102, true));
-        spikeDetected = payloadView.getUint8(110) !== 0;
-        spikeFee = Number(payloadView.getBigUint64(111, true));
+      const state = payloadView.getUint8(24);
+      const isStale = payloadView.getUint8(25) !== 0;
+      const blockUtilizationPct = payloadView.getFloat32(26, true);
+      const blocksInWindow = payloadView.getUint32(30, true);
+      const accountCount = Number(payloadView.getBigUint64(34, true));
+
+      const accounts: FeeMarketMessage['data']['accounts'] = [];
+      let offset = 42;
+      for (let i = 0; i < accountCount && offset + 92 <= payload.byteLength; i++) {
+        const pubkeyBytes = new Uint8Array(payload, offset, 32);
+        const pubkey = base58Encode(pubkeyBytes);
+        const totalTxs = payloadView.getUint32(offset + 32, true);
+        const activeSlots = payloadView.getUint32(offset + 36, true);
+        const cuConsumed = Number(payloadView.getBigUint64(offset + 40, true));
+        const utilizationPct = payloadView.getFloat32(offset + 48, true);
+        const p25 = Number(payloadView.getBigUint64(offset + 52, true));
+        const p50 = Number(payloadView.getBigUint64(offset + 60, true));
+        const p75 = Number(payloadView.getBigUint64(offset + 68, true));
+        const p90 = Number(payloadView.getBigUint64(offset + 76, true));
+        const minNonzeroPrice = Number(payloadView.getBigUint64(offset + 84, true));
+
+        accounts.push({
+          pubkey, totalTxs, activeSlots, cuConsumed, utilizationPct,
+          p25, p50, p75, p90, minNonzeroPrice,
+        });
+        offset += 92;
       }
 
       return {
-        type: 'priority_fees',
+        type: 'fee_market',
         data: {
-          slot,
-          timestampMs,
-          recommended,
-          state,
-          isStale,
-          swapP50,
-          swapP75,
-          swapP90,
-          swapP99,
-          swapSamples,
-          landingP50Fee,
-          landingP75Fee,
-          landingP90Fee,
-          landingP99Fee,
-          top10Fee,
-          top25Fee,
-          spikeDetected,
-          spikeFee,
+          slot, timestampMs, recommended, state, isStale,
+          blockUtilizationPct, blocksInWindow, accounts,
         },
-      };
+      } as FeeMarketMessage;
     }
 
     case MessageType.Blockhash: {
@@ -324,10 +300,6 @@ function decodePoolUpdate(payload: ArrayBuffer, payloadView: DataView): PoolUpda
       offset += 4;
     }
 
-    // is_valid (bool)
-    const isValid = offset < payload.byteLength ? payloadView.getUint8(offset) !== 0 : true;
-    offset += 1;
-
     // best_bid and best_ask (Option<OrderLevel>) - skip for now
     // They use bincode Option encoding: 0 = None, 1 + data = Some
 
@@ -342,24 +314,10 @@ function decodePoolUpdate(payload: ArrayBuffer, payloadView: DataView): PoolUpda
         tokenMints,
         tokenBalances,
         tokenDecimals,
-        isValid,
       },
     };
   } catch {
-    return {
-      type: 'pool_update',
-      data: {
-        sequence: 0,
-        slot: 0,
-        writeVersion: 0,
-        protocol: 'unknown',
-        poolAddress: '',
-        tokenMints: [],
-        tokenBalances: [],
-        tokenDecimals: [],
-        isValid: false,
-      },
-    };
+    return null;
   }
 }
 
@@ -467,24 +425,6 @@ function decodeQuote(payload: ArrayBuffer, payloadView: DataView): DecodedMessag
       },
     };
   } catch {
-    return {
-      type: 'quote',
-      data: {
-        topicId: '',
-        timestampMs: 0,
-        sequence: 0,
-        inputMint: '',
-        outputMint: '',
-        inAmount: '0',
-        outAmount: '0',
-        priceImpactBps: 0,
-        contextSlot: 0,
-        algorithm: '',
-        isImprovement: false,
-        isCached: false,
-        isStale: false,
-        routePlan: null,
-      },
-    };
+    return null;
   }
 }

package/src/ws/index.ts

@@ -44,7 +44,7 @@ export type {
   MessageTypeValue,
   DecodedMessage,
   PoolUpdateMessage,
-  PriorityFeesMessage,
+  FeeMarketMessage,
   BlockhashMessage,
   QuoteMessage,
   HeartbeatMessage,

package/src/ws/types.ts

@@ -60,46 +60,51 @@ export interface PoolUpdateMessage {
     tokenMints: string[];
     tokenBalances: string[];
     tokenDecimals: number[];
-    isValid: boolean;
     bestBid?: { price: string; size: string };
     bestAsk?: { price: string; size: string };
   };
 }
 
 /**
- * Decoded priority fees from binary message
- * 
- * All fields from K2 PriorityFeesWire
+ * Decoded fee market from binary message (per-writable-account model)
+ *
+ * All fields from K2 FeeMarketWire
  */
-export interface PriorityFeesMessage {
-  type: 'priority_fees';
+export interface FeeMarketMessage {
+  type: 'fee_market';
   data: {
     slot: number;
     timestampMs: number;
-    /** Recommended priority fee in micro-lamports */
+    /** Recommended priority fee in microlamports/CU (max p75 across hottest accounts) */
     recommended: number;
     /** Fee state: 0=low, 1=normal, 2=high, 3=extreme */
     state: number;
     /** True if data is stale (no recent samples) */
     isStale: boolean;
-    // Swap fee percentiles (for ≥50K CU transactions)
-    swapP50: number;
-    swapP75: number;
-    swapP90: number;
-    swapP99: number;
-    /** Number of samples used for swap percentiles */
-    swapSamples: number;
-    // Landing probability fees (fee to land with X% probability)
-    landingP50Fee: number;
-    landingP75Fee: number;
-    landingP90Fee: number;
-    landingP99Fee: number;
-    // Top fee tiers
-    top10Fee: number;
-    top25Fee: number;
-    // Spike detection
-    spikeDetected: boolean;
-    spikeFee: number;
+    /** Block utilization percentage (0-100) */
+    blockUtilizationPct: number;
+    /** Number of blocks in the observation window */
+    blocksInWindow: number;
+    /** Per-writable-account fee data */
+    accounts: {
+      /** Account public key (Base58) */
+      pubkey: string;
+      /** Total transactions touching this account */
+      totalTxs: number;
+      /** Active slots for this account */
+      activeSlots: number;
+      /** Total CU consumed */
+      cuConsumed: number;
+      /** Utilization percentage (0-100) of 12M CU limit */
+      utilizationPct: number;
+      /** Fee percentiles in microlamports/CU */
+      p25: number;
+      p50: number;
+      p75: number;
+      p90: number;
+      /** Minimum non-zero fee observed */
+      minNonzeroPrice: number;
+    }[];
   };
 }
 
@@ -217,7 +222,7 @@ export interface PongMessage {
  */
 export type DecodedMessage =
   | PoolUpdateMessage
-  | PriorityFeesMessage
+  | FeeMarketMessage
   | BlockhashMessage
   | QuoteMessage
   | HeartbeatMessage