@k256/sdk 0.2.0 → 0.3.0

package/src/leader-ws/client.ts

@@ -0,0 +1,377 @@
+/**
+ * Leader Schedule WebSocket Client
+ * 
+ * Connects to the K256 leader-schedule service via the Gateway.
+ * Binary mode by default (wincode protocol, matching K2 pattern).
+ * JSON mode opt-in via mode: 'json' (gateway decodes wincode to JSON).
+ * 
+ * @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, 'Leader:', msg.data.leader),
+ *   onRoutingHealth: (msg) => console.log('Coverage:', msg.data.coverage),
+ *   onGossipDiff: (msg) => console.log('Peers changed:', msg.data.added.length, 'added'),
+ * });
+ * 
+ * await client.connect();
+ * ```
+ */
+
+import { decodeLeaderMessage } from './decoder';
+import {
+  ALL_LEADER_CHANNELS,
+  type LeaderChannelValue,
+  type LeaderDecodedMessage,
+  type LeaderSubscribedMessage,
+  type LeaderScheduleMessage,
+  type GossipSnapshotMessage,
+  type GossipDiffMessage,
+  type SlotUpdateMessage,
+  type RoutingHealthMessage,
+  type SkipEventMessage,
+  type IpChangeMessage,
+  type LeaderHeartbeatMessage,
+  type LeaderErrorMessage,
+} from './types';
+
+/**
+ * Connection state
+ */
+export type ConnectionState = 
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'closed';
+
+/**
+ * Leader WebSocket client configuration
+ */
+export interface LeaderWebSocketClientConfig {
+  /** API key for authentication */
+  apiKey: string;
+  /** Gateway URL (default: wss://gateway.k256.xyz/v1/leader-ws) */
+  url?: string;
+  /** Message format: 'binary' (default, efficient) or 'json' (debugging via gateway) */
+  mode?: 'binary' | 'json';
+  /** Channels to subscribe to (default: all channels) */
+  channels?: LeaderChannelValue[];
+  
+  // Reconnection settings
+  /** Enable automatic reconnection (default: true) */
+  autoReconnect?: boolean;
+  /** Initial reconnect delay in ms (default: 1000) */
+  reconnectDelayMs?: number;
+  /** Max reconnect delay in ms (default: 30000) */
+  maxReconnectDelayMs?: number;
+  /** Max reconnect attempts (default: Infinity) */
+  maxReconnectAttempts?: number;
+  
+  // Event callbacks
+  /** Called when connection state changes */
+  onStateChange?: (state: ConnectionState, prevState: ConnectionState) => void;
+  /** Called on successful connection */
+  onConnect?: () => void;
+  /** Called on disconnection */
+  onDisconnect?: (code: number, reason: string, wasClean: boolean) => void;
+  /** Called on reconnection attempt */
+  onReconnecting?: (attempt: number, delayMs: number) => void;
+  /** Called on any error */
+  onError?: (error: LeaderWebSocketError) => void;
+  
+  // Message callbacks
+  /** Called on subscription confirmed (includes protocol schema) */
+  onSubscribed?: (msg: LeaderSubscribedMessage) => void;
+  /** Called on full leader schedule (snapshot — replaces previous) */
+  onLeaderSchedule?: (msg: LeaderScheduleMessage) => void;
+  /** Called on full gossip peer snapshot (snapshot — key: identity) */
+  onGossipSnapshot?: (msg: GossipSnapshotMessage) => void;
+  /** Called on gossip diff (diff — merge into snapshot using identity) */
+  onGossipDiff?: (msg: GossipDiffMessage) => void;
+  /** Called on slot update (snapshot — each replaces previous) */
+  onSlotUpdate?: (msg: SlotUpdateMessage) => void;
+  /** Called on routing health (snapshot — each replaces previous) */
+  onRoutingHealth?: (msg: RoutingHealthMessage) => void;
+  /** Called on skip event (event — block production stats) */
+  onSkipEvent?: (msg: SkipEventMessage) => void;
+  /** Called on IP change event */
+  onIpChange?: (msg: IpChangeMessage) => void;
+  /** Called on heartbeat (every 10s) */
+  onHeartbeat?: (msg: LeaderHeartbeatMessage) => void;
+  /** Called on any message (raw) */
+  onMessage?: (msg: LeaderDecodedMessage) => void;
+}
+
+/**
+ * Error codes for leader WebSocket
+ */
+export type LeaderErrorCode =
+  | 'CONNECTION_FAILED'
+  | 'CONNECTION_LOST'
+  | 'AUTH_FAILED'
+  | 'SERVER_ERROR'
+  | 'INVALID_MESSAGE'
+  | 'RECONNECT_FAILED';
+
+/**
+ * WebSocket error with context
+ */
+export class LeaderWebSocketError extends Error {
+  constructor(
+    public readonly code: LeaderErrorCode,
+    message: string,
+    public readonly closeCode?: number,
+    public readonly closeReason?: string,
+  ) {
+    super(message);
+    this.name = 'LeaderWebSocketError';
+  }
+
+  get isRecoverable(): boolean {
+    return this.code !== 'AUTH_FAILED';
+  }
+}
+
+/**
+ * Leader Schedule WebSocket Client
+ * 
+ * Connects to the leader-schedule service via the Gateway.
+ * Binary mode by default (wincode protocol). JSON mode opt-in via gateway.
+ * Automatically subscribes to configured channels on connect/reconnect.
+ */
+export class LeaderWebSocketClient {
+  private ws: WebSocket | null = null;
+  private readonly config: Required<Pick<LeaderWebSocketClientConfig,
+    'apiKey' | 'url' | 'mode' | 'channels' | 'autoReconnect' | 'reconnectDelayMs' | 'maxReconnectDelayMs' | 'maxReconnectAttempts'
+  >> & LeaderWebSocketClientConfig;
+  
+  private _state: ConnectionState = 'disconnected';
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private isIntentionallyClosed = false;
+
+  /** Current connection state */
+  get state(): ConnectionState { return this._state; }
+
+  /** Whether currently connected */
+  get isConnected(): boolean {
+    return this._state === 'connected' && this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  constructor(config: LeaderWebSocketClientConfig) {
+    this.config = {
+      url: 'wss://gateway.k256.xyz/v1/leader-ws',
+      mode: 'binary',
+      channels: ALL_LEADER_CHANNELS,
+      autoReconnect: true,
+      reconnectDelayMs: 1000,
+      maxReconnectDelayMs: 30000,
+      maxReconnectAttempts: Infinity,
+      ...config,
+    };
+  }
+
+  /**
+   * Connect to the leader-schedule WebSocket
+   */
+  async connect(): Promise<void> {
+    if (this._state === 'connected' || this._state === 'connecting') return;
+    
+    this.isIntentionallyClosed = false;
+    this.setState('connecting');
+
+    return new Promise((resolve, reject) => {
+      try {
+        const url = `${this.config.url}?apiKey=${encodeURIComponent(this.config.apiKey)}`;
+        this.ws = new WebSocket(url);
+        
+        // Binary mode needs arraybuffer
+        if (this.config.mode === 'binary') {
+          this.ws.binaryType = 'arraybuffer';
+        }
+
+        this.ws.onopen = () => {
+          this.setState('connected');
+          this.reconnectAttempts = 0;
+          
+          if (this.config.mode === 'binary') {
+            // Binary mode: send 0x01 tag + JSON payload
+            const payload = JSON.stringify({ channels: this.config.channels });
+            const bytes = new TextEncoder().encode(payload);
+            const msg = new Uint8Array(1 + bytes.length);
+            msg[0] = 0x01; // MSG_SUBSCRIBE
+            msg.set(bytes, 1);
+            this.ws!.send(msg.buffer);
+          } else {
+            // JSON mode: send text (gateway decodes wincode to JSON)
+            this.ws!.send(JSON.stringify({
+              type: 'subscribe',
+              channels: this.config.channels,
+              format: 'json',
+            }));
+          }
+          
+          this.config.onConnect?.();
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          if (this.config.mode === 'binary' && event.data instanceof ArrayBuffer) {
+            // Binary mode: decode wincode with SDK decoder
+            const decoded = decodeLeaderMessage(event.data);
+            if (decoded) {
+              this.dispatchMessage(decoded);
+            }
+          } else if (typeof event.data === 'string') {
+            // JSON mode: parse text frames from gateway
+            this.handleJsonMessage(event.data);
+          }
+        };
+
+        this.ws.onclose = (event) => {
+          const wasConnected = this._state === 'connected';
+          this.ws = null;
+          
+          if (this.isIntentionallyClosed) {
+            this.setState('closed');
+            this.config.onDisconnect?.(event.code, event.reason, event.wasClean);
+            return;
+          }
+          
+          this.config.onDisconnect?.(event.code, event.reason, event.wasClean);
+          
+          // Check for auth failure (don't reconnect)
+          if (event.code === 1008 || event.code === 4001 || event.code === 4003) {
+            this.setState('closed');
+            this.config.onError?.(new LeaderWebSocketError(
+              'AUTH_FAILED', `Authentication failed: ${event.reason}`, event.code, event.reason
+            ));
+            if (!wasConnected) reject(new LeaderWebSocketError('AUTH_FAILED', event.reason, event.code));
+            return;
+          }
+          
+          // Auto-reconnect
+          if (this.config.autoReconnect && this.reconnectAttempts < this.config.maxReconnectAttempts) {
+            this.scheduleReconnect();
+          } else {
+            this.setState('disconnected');
+          }
+          
+          if (!wasConnected) reject(new LeaderWebSocketError('CONNECTION_FAILED', 'WebSocket closed before connect'));
+        };
+
+        this.ws.onerror = () => {
+          this.config.onError?.(new LeaderWebSocketError('CONNECTION_FAILED', 'WebSocket connection error'));
+        };
+      } catch (err) {
+        this.setState('disconnected');
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Disconnect from the WebSocket
+   */
+  disconnect(): void {
+    this.isIntentionallyClosed = true;
+    this.clearTimers();
+    
+    if (this.ws) {
+      if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+        this.ws.close(1000, 'Client disconnect');
+      }
+      this.ws = null;
+    }
+    
+    this.setState('closed');
+  }
+
+  // ── Private ──
+
+  /** Handle JSON text frame (from gateway JSON mode) */
+  private handleJsonMessage(raw: string): void {
+    try {
+      const msg = JSON.parse(raw) as LeaderDecodedMessage;
+      this.dispatchMessage(msg);
+    } catch {
+      this.config.onError?.(new LeaderWebSocketError('INVALID_MESSAGE', 'Failed to parse message'));
+    }
+  }
+
+  /** Dispatch a decoded message to typed callbacks */
+  private dispatchMessage(msg: LeaderDecodedMessage): void {
+    switch (msg.type) {
+      case 'subscribed':
+        this.config.onSubscribed?.(msg as LeaderSubscribedMessage);
+        break;
+      case 'leader_schedule':
+        this.config.onLeaderSchedule?.(msg as LeaderScheduleMessage);
+        break;
+      case 'gossip_snapshot':
+        this.config.onGossipSnapshot?.(msg as GossipSnapshotMessage);
+        break;
+      case 'gossip_diff':
+        this.config.onGossipDiff?.(msg as GossipDiffMessage);
+        break;
+      case 'slot_update':
+        this.config.onSlotUpdate?.(msg as SlotUpdateMessage);
+        break;
+      case 'routing_health':
+        this.config.onRoutingHealth?.(msg as RoutingHealthMessage);
+        break;
+      case 'skip_event':
+        this.config.onSkipEvent?.(msg as SkipEventMessage);
+        break;
+      case 'ip_change':
+        this.config.onIpChange?.(msg as IpChangeMessage);
+        break;
+      case 'heartbeat':
+        this.config.onHeartbeat?.(msg as LeaderHeartbeatMessage);
+        break;
+      case 'error':
+        this.config.onError?.(new LeaderWebSocketError(
+          'SERVER_ERROR', (msg as LeaderErrorMessage).data.message
+        ));
+        break;
+    }
+    
+    // Generic handler
+    this.config.onMessage?.(msg);
+  }
+
+  private setState(state: ConnectionState): void {
+    const prev = this._state;
+    if (prev === state) return;
+    this._state = state;
+    this.config.onStateChange?.(state, prev);
+  }
+
+  private scheduleReconnect(): void {
+    this.setState('reconnecting');
+    this.reconnectAttempts++;
+    
+    const delay = Math.min(
+      this.config.reconnectDelayMs * Math.pow(2, this.reconnectAttempts - 1),
+      this.config.maxReconnectDelayMs
+    );
+    
+    this.config.onReconnecting?.(this.reconnectAttempts, delay);
+    
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch(() => {
+        // Error handled in onclose/onerror
+      });
+    }, delay);
+  }
+
+  private clearTimers(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}

package/src/leader-ws/decoder.ts

@@ -0,0 +1,314 @@
+/**
+ * Binary message decoder for Leader Schedule WebSocket protocol
+ * 
+ * Decodes wincode messages from the leader-schedule server into typed objects.
+ * Matches K2 decoder pattern: manual DataView offset walking, little-endian.
+ * 
+ * Wire format: [1 byte MessageType][N bytes wincode payload]
+ */
+
+import { base58Encode } from '../utils/base58';
+import type {
+  LeaderDecodedMessage,
+  GossipPeer,
+} from './types';
+
+/** Message type tag constants (must match leader-schedule server protocol.rs) */
+export const LeaderMessageTag = {
+  Subscribe: 0x01,
+  Subscribed: 0x02,
+  LeaderSchedule: 0x10,
+  GossipSnapshot: 0x11,
+  GossipDiff: 0x12,
+  SlotUpdate: 0x13,
+  RoutingHealth: 0x14,
+  SkipEvent: 0x15,
+  IpChange: 0x16,
+  Heartbeat: 0xFD,
+  Ping: 0xFE,
+  Error: 0xFF,
+} as const;
+
+/** Mutable offset tracker for sequential reading */
+type Offset = { v: number };
+
+/** Read a wincode u64 (little-endian) */
+function readU64(view: DataView, o: Offset): number {
+  const val = Number(view.getBigUint64(o.v, true));
+  o.v += 8;
+  return val;
+}
+
+/** Read a wincode u32 (little-endian) */
+function readU32(view: DataView, o: Offset): number {
+  const val = view.getUint32(o.v, true);
+  o.v += 4;
+  return val;
+}
+
+/** Read a wincode u16 (little-endian) */
+function readU16(view: DataView, o: Offset): number {
+  const val = view.getUint16(o.v, true);
+  o.v += 2;
+  return val;
+}
+
+/** Read a wincode u8 */
+function readU8(view: DataView, o: Offset): number {
+  const val = view.getUint8(o.v);
+  o.v += 1;
+  return val;
+}
+
+/** Read a wincode bool */
+function readBool(view: DataView, o: Offset): boolean {
+  return readU8(view, o) !== 0;
+}
+
+/** Read a [u8; 32] pubkey as base58 string */
+function readPubkey(data: ArrayBuffer, o: Offset): string {
+  const bytes = new Uint8Array(data, o.v, 32);
+  o.v += 32;
+  return base58Encode(bytes);
+}
+
+/** Read a wincode Vec<u8> as string */
+function readVecU8AsString(view: DataView, data: ArrayBuffer, o: Offset): string {
+  const len = readU64(view, o);
+  const bytes = new Uint8Array(data, o.v, len);
+  o.v += len;
+  return new TextDecoder().decode(bytes);
+}
+
+/** Read a wincode Option<SocketAddrWire>: tag + ip[16] + port:u16 + is_ipv4:bool */
+function readOptSocketAddr(view: DataView, o: Offset): string | null {
+  const tag = readU8(view, o);
+  if (tag === 0) return null;
+  const ipBytes = new Uint8Array(view.buffer, view.byteOffset + o.v, 16);
+  o.v += 16;
+  const port = readU16(view, o);
+  const isIpv4 = readBool(view, o);
+  if (isIpv4) {
+    return `${ipBytes[12]}.${ipBytes[13]}.${ipBytes[14]}.${ipBytes[15]}:${port}`;
+  }
+  return `[ipv6]:${port}`;
+}
+
+/** Read a wincode Vec<[u8;32]> as base58 string array */
+function readPubkeyVec(view: DataView, data: ArrayBuffer, o: Offset): string[] {
+  const count = readU64(view, o);
+  const keys: string[] = [];
+  for (let i = 0; i < count; i++) {
+    keys.push(readPubkey(data, o));
+  }
+  return keys;
+}
+
+/** Read a single GossipPeer from wincode */
+function readGossipPeer(view: DataView, data: ArrayBuffer, o: Offset): GossipPeer {
+  return {
+    identity: readPubkey(data, o),
+    tpuQuic: readOptSocketAddr(view, o),
+    tpuUdp: readOptSocketAddr(view, o),
+    tpuForwardsQuic: readOptSocketAddr(view, o),
+    tpuForwardsUdp: readOptSocketAddr(view, o),
+    tpuVote: readOptSocketAddr(view, o),
+    tpuVoteQuic: readOptSocketAddr(view, o),
+    gossipAddr: readOptSocketAddr(view, o),
+    shredVersion: readU16(view, o),
+    version: readVecU8AsString(view, data, o),
+    activatedStake: readU64(view, o),
+    commission: readU8(view, o),
+    isDelinquent: readBool(view, o),
+    votePubkey: readPubkey(data, o),
+    lastVote: readU64(view, o),
+    rootSlot: readU64(view, o),
+    wallclock: readU64(view, o),
+  };
+}
+
+/** Read a wincode Vec<GossipPeer> */
+function readGossipPeerVec(view: DataView, data: ArrayBuffer, o: Offset): GossipPeer[] {
+  const count = readU64(view, o);
+  const peers: GossipPeer[] = [];
+  for (let i = 0; i < count; i++) {
+    peers.push(readGossipPeer(view, data, o));
+  }
+  return peers;
+}
+
+/**
+ * Decode a binary WebSocket message from the leader-schedule server.
+ * 
+ * @param data - Raw binary data from WebSocket
+ * @returns Decoded message or null if unrecognized type
+ */
+export function decodeLeaderMessage(data: ArrayBuffer): LeaderDecodedMessage | null {
+  const view = new DataView(data);
+  if (data.byteLength < 1) return null;
+
+  const msgType = view.getUint8(0);
+  const payload = data.slice(1);
+  const pv = new DataView(payload);
+
+  switch (msgType) {
+    case LeaderMessageTag.Subscribed: {
+      const text = new TextDecoder().decode(payload);
+      try {
+        return { type: 'subscribed', data: JSON.parse(text) };
+      } catch {
+        return null;
+      }
+    }
+
+    case LeaderMessageTag.Error: {
+      return { type: 'error', data: { message: new TextDecoder().decode(payload) } };
+    }
+
+    case LeaderMessageTag.SlotUpdate: {
+      if (payload.byteLength < 48) return null;
+      const o: Offset = { v: 0 };
+      return {
+        type: 'slot_update',
+        kind: 'snapshot',
+        data: {
+          slot: readU64(pv, o),
+          leader: readPubkey(payload, o),
+          blockHeight: readU64(pv, o),
+        },
+      };
+    }
+
+    case LeaderMessageTag.Heartbeat: {
+      if (payload.byteLength < 24) return null;
+      const o: Offset = { v: 0 };
+      return {
+        type: 'heartbeat',
+        kind: 'snapshot',
+        data: {
+          timestampMs: readU64(pv, o),
+          currentSlot: readU64(pv, o),
+          connectedClients: readU32(pv, o),
+          gossipPeers: readU32(pv, o),
+        },
+      };
+    }
+
+    case LeaderMessageTag.SkipEvent: {
+      if (payload.byteLength < 48) return null;
+      const o: Offset = { v: 0 };
+      return {
+        type: 'skip_event',
+        kind: 'event',
+        key: 'leader',
+        data: {
+          slot: readU64(pv, o),
+          leader: readPubkey(payload, o),
+          assigned: readU32(pv, o),
+          produced: readU32(pv, o),
+        },
+      };
+    }
+
+    case LeaderMessageTag.RoutingHealth: {
+      if (payload.byteLength < 8) return null;
+      try {
+        const o: Offset = { v: 0 };
+        const leadersTotal = readU32(pv, o);
+        const leadersInGossip = readU32(pv, o);
+        const leadersMissingGossip = readPubkeyVec(pv, payload, o);
+        const leadersWithoutTpuQuic = readPubkeyVec(pv, payload, o);
+        const leadersDelinquent = readPubkeyVec(pv, payload, o);
+        return {
+          type: 'routing_health',
+          kind: 'snapshot',
+          data: {
+            leadersTotal,
+            leadersInGossip,
+            leadersMissingGossip,
+            leadersWithoutTpuQuic,
+            leadersDelinquent,
+            coverage: `${leadersTotal > 0 ? (leadersInGossip / leadersTotal * 100).toFixed(1) : 0}%`,
+          },
+        };
+      } catch { return null; }
+    }
+
+    case LeaderMessageTag.IpChange: {
+      if (payload.byteLength < 32) return null;
+      try {
+        const o: Offset = { v: 0 };
+        const identity = readPubkey(payload, o);
+        const oldIp = readVecU8AsString(pv, payload, o);
+        const newIp = readVecU8AsString(pv, payload, o);
+        const timestampMs = readU64(pv, o);
+        return {
+          type: 'ip_change',
+          kind: 'event',
+          key: 'identity',
+          data: { identity, oldIp, newIp, timestampMs },
+        };
+      } catch { return null; }
+    }
+
+    case LeaderMessageTag.GossipSnapshot: {
+      if (payload.byteLength < 8) return null;
+      try {
+        const o: Offset = { v: 0 };
+        const timestampMs = readU64(pv, o);
+        const peers = readGossipPeerVec(pv, payload, o);
+        return {
+          type: 'gossip_snapshot',
+          kind: 'snapshot',
+          key: 'identity',
+          data: { timestampMs, count: peers.length, peers },
+        };
+      } catch { return null; }
+    }
+
+    case LeaderMessageTag.GossipDiff: {
+      if (payload.byteLength < 8) return null;
+      try {
+        const o: Offset = { v: 0 };
+        const timestampMs = readU64(pv, o);
+        const added = readGossipPeerVec(pv, payload, o);
+        const removed = readPubkeyVec(pv, payload, o);
+        const updated = readGossipPeerVec(pv, payload, o);
+        return {
+          type: 'gossip_diff',
+          kind: 'diff',
+          key: 'identity',
+          data: { timestampMs, added, removed, updated },
+        };
+      } catch { return null; }
+    }
+
+    case LeaderMessageTag.LeaderSchedule: {
+      if (payload.byteLength < 16) return null;
+      try {
+        const o: Offset = { v: 0 };
+        const epoch = readU64(pv, o);
+        const slotsInEpoch = readU64(pv, o);
+        const validatorCount = readU64(pv, o);
+        const schedule: Array<{ identity: string; slots: number; slotIndices: number[] }> = [];
+        for (let i = 0; i < validatorCount; i++) {
+          const identity = readPubkey(payload, o);
+          const slotCount = readU64(pv, o);
+          const slotIndices: number[] = [];
+          for (let j = 0; j < slotCount; j++) {
+            slotIndices.push(readU32(pv, o));
+          }
+          schedule.push({ identity, slots: slotIndices.length, slotIndices });
+        }
+        return {
+          type: 'leader_schedule',
+          kind: 'snapshot',
+          data: { epoch, slotsInEpoch, validators: schedule.length, schedule },
+        };
+      } catch { return null; }
+    }
+
+    default:
+      return null;
+  }
+}