@k256/sdk 0.1.6 → 0.2.0

package/src/ws/decoder.ts

@@ -8,7 +8,8 @@
  */
 
 import { base58Encode } from '../utils/base58';
-import { MessageType, type DecodedMessage, type PoolUpdateMessage } from './types';
+import type { BlockMiniStats, TrendDirection } from '../types';
+import { MessageType, type DecodedMessage, type PoolUpdateMessage, type FeeMarketMessage } from './types';
 
 /**
  * Decode a binary WebSocket message from K2
@@ -69,84 +70,78 @@ 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));
+      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;
       }
 
-      // 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));
+      // Decode recent_blocks (Vec<BlockMiniStats>) — v3
+      const recentBlocksCount = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const recentBlocks: BlockMiniStats[] = [];
+      for (let i = 0; i < recentBlocksCount; i++) {
+        const rbSlot = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+        const rbCuConsumed = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+        const rbTxCount = payloadView.getUint32(offset, true); offset += 4;
+        const rbUtilizationPct = payloadView.getFloat32(offset, true); offset += 4;
+        const rbAvgCuPrice = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+        recentBlocks.push({ slot: rbSlot, cuConsumed: rbCuConsumed, txCount: rbTxCount, utilizationPct: rbUtilizationPct, avgCuPrice: rbAvgCuPrice });
       }
 
+      // Decode trend (u8) — v3
+      const trendByte = payloadView.getUint8(offset); offset += 1;
+      const trend: TrendDirection = trendByte === 0 ? 'rising' : trendByte === 1 ? 'falling' : 'stable';
+
       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,
+          recentBlocks, trend,
         },
-      };
+      } as FeeMarketMessage;
     }
 
     case MessageType.Blockhash: {
@@ -204,6 +199,35 @@ export function decodeMessage(data: ArrayBuffer): DecodedMessage | null {
       };
     }
 
+    case MessageType.BlockStats: {
+      // BlockStats (0x0F) — v3
+      // Layout: slot(u64) + cu_consumed(u64) + execution_cu(u64) + cu_limit(u64) + cu_remaining(u64)
+      //       + utilization_pct(f32) + tx_count(u32) + avg_cu_per_tx(u32) + avg_cu_price(u64)
+      //       + min_cu_price(u64) + max_cu_price(u64) + timestamp_ms(u64)
+      let offset = 0; // payload already has type byte stripped
+      const slot = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const cuConsumed = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const executionCu = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const cuLimit = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const cuRemaining = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const utilizationPct = payloadView.getFloat32(offset, true); offset += 4;
+      const txCount = payloadView.getUint32(offset, true); offset += 4;
+      const avgCuPerTx = payloadView.getUint32(offset, true); offset += 4;
+      const avgCuPrice = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const minCuPrice = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const maxCuPrice = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+      const timestampMs = Number(payloadView.getBigUint64(offset, true)); offset += 8;
+
+      return {
+        type: 'block_stats',
+        data: {
+          slot, cuConsumed, executionCu, cuLimit, cuRemaining, utilizationPct,
+          txCount, avgCuPerTx, avgCuPrice, minCuPrice, maxCuPrice, timestampMs,
+        },
+        receivedAt: Date.now(),
+      };
+    }
+
     default:
       return null;
   }
@@ -341,19 +365,7 @@ function decodePoolUpdate(payload: ArrayBuffer, payloadView: DataView): PoolUpda
       },
     };
   } catch {
-    return {
-      type: 'pool_update',
-      data: {
-        sequence: 0,
-        slot: 0,
-        writeVersion: 0,
-        protocol: 'unknown',
-        poolAddress: '',
-        tokenMints: [],
-        tokenBalances: [],
-        tokenDecimals: [],
-      },
-    };
+    return null;
   }
 }
 
@@ -461,24 +473,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,8 @@ export type {
   MessageTypeValue,
   DecodedMessage,
   PoolUpdateMessage,
-  PriorityFeesMessage,
+  FeeMarketMessage,
+  BlockStatsMessage,
   BlockhashMessage,
   QuoteMessage,
   HeartbeatMessage,

package/src/ws/types.ts

@@ -5,6 +5,8 @@
  * See: https://github.com/k256-xyz for protocol documentation
  */
 
+import type { BlockMiniStats, TrendDirection, BlockStats } from '../types';
+
 /**
  * WebSocket message type constants
  * 
@@ -40,6 +42,8 @@ export const MessageType = {
   Heartbeat: 0x0d,
   /** Batched pool updates for high throughput */
   PoolUpdateBatch: 0x0e,
+  /** Block-level statistics (v3) */
+  BlockStats: 0x0f,
   /** Error message (UTF-8 string) */
   Error: 0xff,
 } as const;
@@ -66,42 +70,61 @@ export interface PoolUpdateMessage {
 }
 
 /**
- * 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;
+    }[];
+    /** Recent block mini-stats (v3) */
+    recentBlocks: BlockMiniStats[];
+    /** Fee trend direction (v3) */
+    trend: TrendDirection;
   };
 }
 
+/**
+ * Decoded block stats from binary message (v3)
+ */
+export interface BlockStatsMessage {
+  type: 'block_stats';
+  data: BlockStats;
+  receivedAt: number;
+}
+
 /**
  * Decoded blockhash from binary message
  */
@@ -216,7 +239,8 @@ export interface PongMessage {
  */
 export type DecodedMessage =
   | PoolUpdateMessage
-  | PriorityFeesMessage
+  | FeeMarketMessage
+  | BlockStatsMessage
   | BlockhashMessage
   | QuoteMessage
   | HeartbeatMessage