@k256/sdk 0.2.1 → 0.3.1

package/src/leader-ws/decoder.ts

@@ -0,0 +1,320 @@
+/**
+ * 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 (field names match REST /gossip/peer/:id) */
+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),
+    stake: readU64(view, o),
+    commission: readU8(view, o),
+    isDelinquent: readBool(view, o),
+    voteAccount: readPubkey(data, o),
+    lastVote: readU64(view, o),
+    rootSlot: readU64(view, o),
+    wallclock: readU64(view, o),
+    // Geo/ASN enrichment from IPinfo Lite MMDB (server-side)
+    countryCode: readVecU8AsString(view, data, o),
+    continentCode: readVecU8AsString(view, data, o),
+    asn: readVecU8AsString(view, data, o),
+    asName: readVecU8AsString(view, data, o),
+    asDomain: readVecU8AsString(view, data, 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;
+  }
+}

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,224 @@
+/**
+ * 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 (field names match REST /gossip/peer/:id for consistency) */
+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;
+  /** Activated stake in lamports (matches REST field name "stake") */
+  stake: number;
+  commission: number;
+  isDelinquent: boolean;
+  /** Vote account pubkey (matches REST field name "voteAccount") */
+  voteAccount: string;
+  lastVote: number;
+  rootSlot: number;
+  wallclock: number;
+  /** ISO 3166 country code (e.g. "US", "DE") — from IPinfo Lite MMDB on server */
+  countryCode: string;
+  /** Two-letter continent code (e.g. "NA", "EU") */
+  continentCode: string;
+  /** ASN string (e.g. "AS15169") */
+  asn: string;
+  /** AS organization name (e.g. "Google LLC") */
+  asName: string;
+  /** AS organization domain (e.g. "google.com") */
+  asDomain: string;
+}
+
+/** 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;