@k256/sdk 0.2.0 → 0.3.0

package/src/leader-ws/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Leader Schedule WebSocket module for K256 SDK
+ * 
+ * Real-time Solana leader schedule, gossip network, and routing data.
+ * Binary mode by default (wincode protocol). JSON mode opt-in via gateway.
+ * 
+ * @module @k256/sdk/leader-ws
+ * 
+ * @example
+ * ```typescript
+ * import { LeaderWebSocketClient } from '@k256/sdk/leader-ws';
+ * 
+ * const client = new LeaderWebSocketClient({
+ *   apiKey: 'your-api-key',
+ *   onSlotUpdate: (msg) => console.log('Slot:', msg.data.slot),
+ *   onRoutingHealth: (msg) => console.log('Coverage:', msg.data.coverage),
+ *   onGossipDiff: (msg) => {
+ *     // Merge into your local peer map using identity as key
+ *     for (const peer of msg.data.added) peerMap.set(peer.identity, peer);
+ *     for (const peer of msg.data.updated) peerMap.set(peer.identity, peer);
+ *     for (const id of msg.data.removed) peerMap.delete(id);
+ *   },
+ * });
+ * 
+ * await client.connect();
+ * ```
+ */
+
+// Client
+export { LeaderWebSocketClient, LeaderWebSocketError } from './client';
+export type {
+  LeaderWebSocketClientConfig,
+  LeaderErrorCode,
+  ConnectionState,
+} from './client';
+
+// Decoder (for advanced usage)
+export { decodeLeaderMessage, LeaderMessageTag } from './decoder';
+
+// Types
+export { LeaderChannel, ALL_LEADER_CHANNELS } from './types';
+export type {
+  LeaderChannelValue,
+  MessageKind,
+  MessageSchemaEntry,
+  LeaderDecodedMessage,
+  LeaderSubscribedMessage,
+  LeaderScheduleMessage,
+  GossipSnapshotMessage,
+  GossipDiffMessage,
+  GossipPeer,
+  SlotUpdateMessage,
+  RoutingHealthMessage,
+  SkipEventMessage,
+  IpChangeMessage,
+  LeaderHeartbeatMessage,
+  LeaderErrorMessage,
+} from './types';

package/src/leader-ws/types.ts

@@ -0,0 +1,212 @@
+/**
+ * Leader Schedule WebSocket message types and interfaces
+ * 
+ * The leader-schedule WS uses wincode binary protocol (matching K2 pattern).
+ * Wire format: [1-byte tag][wincode payload]
+ * Every decoded message has:
+ * - type: message type name
+ * - kind: "snapshot" (full state) | "diff" (merge into snapshot) | "event" (append-only)
+ * - key: primary key field for merging (on diff/event types)
+ * - data: typed payload
+ * 
+ * @see https://k256.xyz/docs/leader-schedule
+ */
+
+/**
+ * Leader Schedule WebSocket channels
+ */
+export const LeaderChannel = {
+  /** Full epoch leader schedule (on connect + epoch change) */
+  LeaderSchedule: 'leader_schedule',
+  /** Gossip peers (snapshot on connect, then diffs) */
+  Gossip: 'gossip',
+  /** Real-time slot updates with current leader */
+  Slots: 'slots',
+  /** Skip events, IP changes, routing health */
+  Alerts: 'alerts',
+} as const;
+
+export type LeaderChannelValue = typeof LeaderChannel[keyof typeof LeaderChannel];
+
+/** All available channels */
+export const ALL_LEADER_CHANNELS: LeaderChannelValue[] = [
+  LeaderChannel.LeaderSchedule,
+  LeaderChannel.Gossip,
+  LeaderChannel.Slots,
+  LeaderChannel.Alerts,
+];
+
+/**
+ * Message kind — tells you how to consume the message
+ */
+export type MessageKind = 'snapshot' | 'diff' | 'event';
+
+// ═══════════════════════════════════════════════════════════════════════
+// Message Interfaces
+// ═══════════════════════════════════════════════════════════════════════
+
+/** Protocol schema entry (included in subscribed handshake) */
+export interface MessageSchemaEntry {
+  type: string;
+  tag: string;
+  kind: MessageKind;
+  key?: string;
+  description: string;
+}
+
+/** Subscribed response — connection handshake */
+export interface LeaderSubscribedMessage {
+  type: 'subscribed';
+  data: {
+    channels: string[];
+    currentSlot: number;
+    epoch: number;
+    schema: MessageSchemaEntry[];
+  };
+}
+
+/** Full epoch leader schedule (snapshot — replaces previous) */
+export interface LeaderScheduleMessage {
+  type: 'leader_schedule';
+  kind: 'snapshot';
+  data: {
+    epoch: number;
+    slotsInEpoch: number;
+    validators: number;
+    schedule: Array<{
+      identity: string;
+      slots: number;
+      slotIndices: number[];
+    }>;
+  };
+}
+
+/** Gossip peer data */
+export interface GossipPeer {
+  identity: string;
+  tpuQuic: string | null;
+  tpuUdp: string | null;
+  tpuForwardsQuic: string | null;
+  tpuForwardsUdp: string | null;
+  tpuVote: string | null;
+  tpuVoteQuic: string | null;
+  gossipAddr: string | null;
+  shredVersion: number;
+  version: string;
+  activatedStake: number;
+  commission: number;
+  isDelinquent: boolean;
+  votePubkey: string;
+  lastVote: number;
+  rootSlot: number;
+  wallclock: number;
+}
+
+/** Full gossip peer list (snapshot — apply gossip_diff to keep current) */
+export interface GossipSnapshotMessage {
+  type: 'gossip_snapshot';
+  kind: 'snapshot';
+  key: 'identity';
+  data: {
+    timestampMs: number;
+    count: number;
+    peers: GossipPeer[];
+  };
+}
+
+/** Incremental gossip changes (diff — merge into snapshot using identity) */
+export interface GossipDiffMessage {
+  type: 'gossip_diff';
+  kind: 'diff';
+  key: 'identity';
+  data: {
+    timestampMs: number;
+    added: GossipPeer[];
+    removed: string[];
+    updated: GossipPeer[];
+  };
+}
+
+/** Current slot with leader identity (snapshot — each replaces previous) */
+export interface SlotUpdateMessage {
+  type: 'slot_update';
+  kind: 'snapshot';
+  data: {
+    slot: number;
+    leader: string;
+    blockHeight: number;
+  };
+}
+
+/** Routing health summary (snapshot — each replaces previous) */
+export interface RoutingHealthMessage {
+  type: 'routing_health';
+  kind: 'snapshot';
+  data: {
+    leadersTotal: number;
+    leadersInGossip: number;
+    leadersMissingGossip: string[];
+    leadersWithoutTpuQuic: string[];
+    leadersDelinquent: string[];
+    coverage: string;
+  };
+}
+
+/** Block production stats per validator (event — cumulative) */
+export interface SkipEventMessage {
+  type: 'skip_event';
+  kind: 'event';
+  key: 'leader';
+  data: {
+    slot: number;
+    leader: string;
+    assigned: number;
+    produced: number;
+  };
+}
+
+/** Validator IP address change (event) */
+export interface IpChangeMessage {
+  type: 'ip_change';
+  kind: 'event';
+  key: 'identity';
+  data: {
+    identity: string;
+    oldIp: string;
+    newIp: string;
+    timestampMs: number;
+  };
+}
+
+/** Server heartbeat (snapshot — each replaces previous) */
+export interface LeaderHeartbeatMessage {
+  type: 'heartbeat';
+  kind: 'snapshot';
+  data: {
+    timestampMs: number;
+    currentSlot: number;
+    connectedClients: number;
+    gossipPeers: number;
+  };
+}
+
+/** Error from server */
+export interface LeaderErrorMessage {
+  type: 'error';
+  data: {
+    message: string;
+  };
+}
+
+/** Union of all leader-schedule message types */
+export type LeaderDecodedMessage =
+  | LeaderSubscribedMessage
+  | LeaderScheduleMessage
+  | GossipSnapshotMessage
+  | GossipDiffMessage
+  | SlotUpdateMessage
+  | RoutingHealthMessage
+  | SkipEventMessage
+  | IpChangeMessage
+  | LeaderHeartbeatMessage
+  | LeaderErrorMessage;

package/src/ws/client.ts

@@ -131,7 +131,7 @@ export interface K256WebSocketClientConfig {
   pingIntervalMs?: number;
   /** Pong timeout in ms - disconnect if no pong (default: 10000) */
   pongTimeoutMs?: number;
-  /** Heartbeat timeout in ms - warn if no heartbeat (default: 15000) */
+  /** Heartbeat timeout in ms - warn if no heartbeat (default: 45000, K2 sends every 30s) */
   heartbeatTimeoutMs?: number;
   
   // Event callbacks
@@ -274,7 +274,7 @@ export class K256WebSocketClient {
       maxReconnectAttempts: Infinity,
       pingIntervalMs: 30000,
       pongTimeoutMs: 10000,
-      heartbeatTimeoutMs: 15000,
+      heartbeatTimeoutMs: 45000, // K2 sends heartbeats every 30s; allow 45s before warning
       ...config,
     };
   }

package/src/ws/decoder.ts

@@ -118,10 +118,13 @@ export function decodeMessage(data: ArrayBuffer): DecodedMessage | null {
       }
 
       // Decode recent_blocks (Vec<BlockMiniStats>) — v3
-      const recentBlocksCount = Number(payloadView.getBigUint64(offset, true));
+      // Guard: need at least 8 bytes for count + 1 byte for trend after
+      const recentBlocksCount = offset + 8 <= payload.byteLength
+        ? Number(payloadView.getBigUint64(offset, true))
+        : 0;
       offset += 8;
       const recentBlocks: BlockMiniStats[] = [];
-      for (let i = 0; i < recentBlocksCount; i++) {
+      for (let i = 0; i < recentBlocksCount && offset + 32 <= payload.byteLength; 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;
@@ -131,7 +134,8 @@ export function decodeMessage(data: ArrayBuffer): DecodedMessage | null {
       }
 
       // Decode trend (u8) — v3
-      const trendByte = payloadView.getUint8(offset); offset += 1;
+      const trendByte = offset < payload.byteLength ? payloadView.getUint8(offset) : 2;
+      offset += 1;
       const trend: TrendDirection = trendByte === 0 ? 'rising' : trendByte === 1 ? 'falling' : 'stable';
 
       return {