@k256/sdk 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -979,6 +979,500 @@ var K256WebSocketClient = class {
   }
 };
 
+// src/leader-ws/decoder.ts
+var LeaderMessageTag = {
+  Subscribe: 1,
+  Subscribed: 2,
+  LeaderSchedule: 16,
+  GossipSnapshot: 17,
+  GossipDiff: 18,
+  SlotUpdate: 19,
+  RoutingHealth: 20,
+  SkipEvent: 21,
+  IpChange: 22,
+  Heartbeat: 253,
+  Ping: 254,
+  Error: 255
+};
+function readU64(view, o) {
+  const val = Number(view.getBigUint64(o.v, true));
+  o.v += 8;
+  return val;
+}
+function readU32(view, o) {
+  const val = view.getUint32(o.v, true);
+  o.v += 4;
+  return val;
+}
+function readU16(view, o) {
+  const val = view.getUint16(o.v, true);
+  o.v += 2;
+  return val;
+}
+function readU8(view, o) {
+  const val = view.getUint8(o.v);
+  o.v += 1;
+  return val;
+}
+function readBool(view, o) {
+  return readU8(view, o) !== 0;
+}
+function readPubkey(data, o) {
+  const bytes = new Uint8Array(data, o.v, 32);
+  o.v += 32;
+  return base58Encode(bytes);
+}
+function readVecU8AsString(view, data, o) {
+  const len = readU64(view, o);
+  const bytes = new Uint8Array(data, o.v, len);
+  o.v += len;
+  return new TextDecoder().decode(bytes);
+}
+function readOptSocketAddr(view, o) {
+  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}`;
+}
+function readPubkeyVec(view, data, o) {
+  const count = readU64(view, o);
+  const keys = [];
+  for (let i = 0; i < count; i++) {
+    keys.push(readPubkey(data, o));
+  }
+  return keys;
+}
+function readGossipPeer(view, data, o) {
+  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)
+  };
+}
+function readGossipPeerVec(view, data, o) {
+  const count = readU64(view, o);
+  const peers = [];
+  for (let i = 0; i < count; i++) {
+    peers.push(readGossipPeer(view, data, o));
+  }
+  return peers;
+}
+function decodeLeaderMessage(data) {
+  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 = { 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 = { 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 = { 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 = { 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 = { 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 = { 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 = { 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 = { v: 0 };
+        const epoch = readU64(pv, o);
+        const slotsInEpoch = readU64(pv, o);
+        const validatorCount = readU64(pv, o);
+        const schedule = [];
+        for (let i = 0; i < validatorCount; i++) {
+          const identity = readPubkey(payload, o);
+          const slotCount = readU64(pv, o);
+          const slotIndices = [];
+          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;
+  }
+}
+
+// src/leader-ws/types.ts
+var 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"
+};
+var ALL_LEADER_CHANNELS = [
+  LeaderChannel.LeaderSchedule,
+  LeaderChannel.Gossip,
+  LeaderChannel.Slots,
+  LeaderChannel.Alerts
+];
+
+// src/leader-ws/client.ts
+var LeaderWebSocketError = class extends Error {
+  constructor(code, message, closeCode, closeReason) {
+    super(message);
+    this.code = code;
+    this.closeCode = closeCode;
+    this.closeReason = closeReason;
+    this.name = "LeaderWebSocketError";
+  }
+  get isRecoverable() {
+    return this.code !== "AUTH_FAILED";
+  }
+};
+var LeaderWebSocketClient = class {
+  ws = null;
+  config;
+  _state = "disconnected";
+  reconnectAttempts = 0;
+  reconnectTimer = null;
+  isIntentionallyClosed = false;
+  /** Current connection state */
+  get state() {
+    return this._state;
+  }
+  /** Whether currently connected */
+  get isConnected() {
+    return this._state === "connected" && this.ws?.readyState === WebSocket.OPEN;
+  }
+  constructor(config) {
+    this.config = {
+      url: "wss://gateway.k256.xyz/v1/leader-ws",
+      mode: "binary",
+      channels: ALL_LEADER_CHANNELS,
+      autoReconnect: true,
+      reconnectDelayMs: 1e3,
+      maxReconnectDelayMs: 3e4,
+      maxReconnectAttempts: Infinity,
+      ...config
+    };
+  }
+  /**
+   * Connect to the leader-schedule WebSocket
+   */
+  async connect() {
+    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);
+        if (this.config.mode === "binary") {
+          this.ws.binaryType = "arraybuffer";
+        }
+        this.ws.onopen = () => {
+          this.setState("connected");
+          this.reconnectAttempts = 0;
+          if (this.config.mode === "binary") {
+            const payload = JSON.stringify({ channels: this.config.channels });
+            const bytes = new TextEncoder().encode(payload);
+            const msg = new Uint8Array(1 + bytes.length);
+            msg[0] = 1;
+            msg.set(bytes, 1);
+            this.ws.send(msg.buffer);
+          } else {
+            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) {
+            const decoded = decodeLeaderMessage(event.data);
+            if (decoded) {
+              this.dispatchMessage(decoded);
+            }
+          } else if (typeof event.data === "string") {
+            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);
+          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;
+          }
+          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() {
+    this.isIntentionallyClosed = true;
+    this.clearTimers();
+    if (this.ws) {
+      if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+        this.ws.close(1e3, "Client disconnect");
+      }
+      this.ws = null;
+    }
+    this.setState("closed");
+  }
+  // ── Private ──
+  /** Handle JSON text frame (from gateway JSON mode) */
+  handleJsonMessage(raw) {
+    try {
+      const msg = JSON.parse(raw);
+      this.dispatchMessage(msg);
+    } catch {
+      this.config.onError?.(new LeaderWebSocketError("INVALID_MESSAGE", "Failed to parse message"));
+    }
+  }
+  /** Dispatch a decoded message to typed callbacks */
+  dispatchMessage(msg) {
+    switch (msg.type) {
+      case "subscribed":
+        this.config.onSubscribed?.(msg);
+        break;
+      case "leader_schedule":
+        this.config.onLeaderSchedule?.(msg);
+        break;
+      case "gossip_snapshot":
+        this.config.onGossipSnapshot?.(msg);
+        break;
+      case "gossip_diff":
+        this.config.onGossipDiff?.(msg);
+        break;
+      case "slot_update":
+        this.config.onSlotUpdate?.(msg);
+        break;
+      case "routing_health":
+        this.config.onRoutingHealth?.(msg);
+        break;
+      case "skip_event":
+        this.config.onSkipEvent?.(msg);
+        break;
+      case "ip_change":
+        this.config.onIpChange?.(msg);
+        break;
+      case "heartbeat":
+        this.config.onHeartbeat?.(msg);
+        break;
+      case "error":
+        this.config.onError?.(new LeaderWebSocketError(
+          "SERVER_ERROR",
+          msg.data.message
+        ));
+        break;
+    }
+    this.config.onMessage?.(msg);
+  }
+  setState(state) {
+    const prev = this._state;
+    if (prev === state) return;
+    this._state = state;
+    this.config.onStateChange?.(state, prev);
+  }
+  scheduleReconnect() {
+    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(() => {
+      });
+    }, delay);
+  }
+  clearTimers() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+
 // src/types/index.ts
 var NetworkState = /* @__PURE__ */ ((NetworkState2) => {
   NetworkState2[NetworkState2["Low"] = 0] = "Low";
@@ -988,13 +1482,19 @@ var NetworkState = /* @__PURE__ */ ((NetworkState2) => {
   return NetworkState2;
 })(NetworkState || {});
 
+exports.ALL_LEADER_CHANNELS = ALL_LEADER_CHANNELS;
 exports.CloseCode = CloseCode;
 exports.K256WebSocketClient = K256WebSocketClient;
 exports.K256WebSocketError = K256WebSocketError;
+exports.LeaderChannel = LeaderChannel;
+exports.LeaderMessageTag = LeaderMessageTag;
+exports.LeaderWebSocketClient = LeaderWebSocketClient;
+exports.LeaderWebSocketError = LeaderWebSocketError;
 exports.MessageType = MessageType;
 exports.NetworkState = NetworkState;
 exports.base58Decode = base58Decode;
 exports.base58Encode = base58Encode;
+exports.decodeLeaderMessage = decodeLeaderMessage;
 exports.decodeMessage = decodeMessage;
 exports.decodePoolUpdateBatch = decodePoolUpdateBatch;
 exports.isValidPubkey = isValidPubkey;