@oobe-protocol-labs/synapse-sap-sdk 0.6.2 → 0.6.3

package/dist/types/postgres/sync.d.ts

@@ -33,6 +33,7 @@
  * ```
  */
 import type { SapClient } from "../core/client";
+import { type GeyserConfig } from "../events/geyser";
 import type { SapPostgres, SyncAllResult } from "./adapter";
 import type { SyncOptions } from "./types";
 /**
@@ -59,6 +60,7 @@ export declare class SapSyncEngine {
     private readonly debug;
     private intervalId;
     private logSubId;
+    private geyserStream;
     private running;
     constructor(pg: SapPostgres, client: SapClient, debug?: boolean);
     /**
@@ -111,10 +113,32 @@ export declare class SapSyncEngine {
     startEventStream(): Promise<void>;
     /**
      * @name stopEventStream
-     * @description Unsubscribe from the program log stream.
+     * @description Unsubscribe from the program log stream (WebSocket or Geyser).
      * @since v0.1.0
      */
     stopEventStream(): Promise<void>;
+    /**
+     * @name startGeyserStream
+     * @description Subscribe to SAP program transactions via Yellowstone gRPC
+     * and insert parsed events into the `sap_events` table in real-time.
+     *
+     * Drop-in replacement for {@link startEventStream} with lower latency,
+     * no missed events, and automatic reconnection.
+     *
+     * Requires `@triton-one/yellowstone-grpc` to be installed.
+     *
+     * @param geyserConfig - Yellowstone gRPC connection config.
+     * @since v0.6.3
+     *
+     * @example
+     * ```ts
+     * await sync.startGeyserStream({
+     *   endpoint: "https://grpc.triton.one",
+     *   token:    process.env.GEYSER_TOKEN!,
+     * });
+     * ```
+     */
+    startGeyserStream(geyserConfig: GeyserConfig): Promise<void>;
     /**
      * @name isRunning
      * @description Check whether the periodic sync is active.
@@ -123,7 +147,7 @@ export declare class SapSyncEngine {
     isRunning(): boolean;
     /**
      * @name isStreaming
-     * @description Check whether the event stream is active.
+     * @description Check whether the event stream is active (WebSocket or Geyser).
      * @since v0.1.0
      */
     isStreaming(): boolean;

package/dist/types/postgres/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/postgres/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAEhC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAS;gBAEZ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,UAAQ;IAU7D;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAWxD;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAcvD;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,OAAO,CAAC,YAAY;IAWpB;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAyCvC;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAatC;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAQtB,OAAO,CAAC,GAAG;CAKZ"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/postgres/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAEhC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,OAAO,CAAS;gBAEZ,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,UAAQ;IAU7D;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAWxD;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAcvD;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,OAAO,CAAC,YAAY;IAWpB;;;;;;;;;;;;;;;OAeG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAyCvC;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0DlE;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAQtB,OAAO,CAAC,GAAG;CAKZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana",
   "license": "MIT",
   "main": "dist/cjs/index.js",
@@ -166,6 +166,7 @@
   "peerDependencies": {
     "@coral-xyz/anchor": ">=0.30.0",
     "@solana/web3.js": ">=1.90.0",
+    "@triton-one/yellowstone-grpc": ">=1.0.0",
     "zod": ">=3.20.0",
     "pg": ">=8.0.0"
   },
@@ -175,6 +176,9 @@
     },
     "pg": {
       "optional": true
+    },
+    "@triton-one/yellowstone-grpc": {
+      "optional": true
     }
   },
   "engines": {

package/src/events/geyser.ts

@@ -0,0 +1,384 @@
+/**
+ * @module events/geyser
+ * @description Yellowstone gRPC (Geyser) event stream for SAP v2.
+ *
+ * Drop-in alternative to the WebSocket `connection.onLogs()` pipeline.
+ * Uses Triton / Helius / any Yellowstone-compatible gRPC endpoint to
+ * receive program transaction updates with sub-second latency and
+ * automatic reconnection.
+ *
+ * @category Events
+ * @since v0.6.3
+ *
+ * @example
+ * ```ts
+ * import { GeyserEventStream } from "@oobe-protocol-labs/synapse-sap-sdk";
+ * import { EventParser }       from "@oobe-protocol-labs/synapse-sap-sdk";
+ *
+ * const stream = new GeyserEventStream({
+ *   endpoint:  "https://grpc.triton.one",
+ *   token:     process.env.GEYSER_TOKEN!,
+ *   programId: "SAPpUhsWLJG1FfkGRcXagEDMrMsWGjbky7AyhGpFETZ",
+ * });
+ *
+ * const parser = new EventParser(program);
+ *
+ * stream.on("logs", (logs, signature, slot) => {
+ *   const events = parser.parseLogs(logs);
+ *   for (const event of events) {
+ *     console.log(event.name, event.data);
+ *   }
+ * });
+ *
+ * stream.on("error", (err) => console.error("gRPC error:", err));
+ *
+ * await stream.connect();
+ * // ... later
+ * await stream.disconnect();
+ * ```
+ */
+
+import { EventEmitter } from "events";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Types
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Configuration for the Yellowstone gRPC event stream.
+ *
+ * @interface GeyserConfig
+ * @since v0.6.3
+ */
+export interface GeyserConfig {
+  /** Yellowstone gRPC endpoint URL (e.g. "https://grpc.triton.one") */
+  endpoint: string;
+
+  /** Authentication token for the gRPC endpoint */
+  token: string;
+
+  /** SAP program ID to filter. Defaults to SAP v2 program. */
+  programId?: string;
+
+  /**
+   * Commitment level for the subscription.
+   * @default "confirmed"
+   */
+  commitment?: "processed" | "confirmed" | "finalized";
+
+  /**
+   * Automatically reconnect on disconnect.
+   * @default true
+   */
+  autoReconnect?: boolean;
+
+  /**
+   * Delay between reconnection attempts in ms.
+   * @default 3000
+   */
+  reconnectDelayMs?: number;
+
+  /**
+   * Maximum number of reconnection attempts. 0 = unlimited.
+   * @default 0
+   */
+  maxReconnectAttempts?: number;
+
+  /**
+   * Include failed transactions in the stream.
+   * @default false
+   */
+  includeFailedTxs?: boolean;
+}
+
+/**
+ * Events emitted by {@link GeyserEventStream}.
+ *
+ * @interface GeyserStreamEvents
+ * @since v0.6.3
+ */
+export interface GeyserStreamEvents {
+  /**
+   * Emitted for each transaction's log messages.
+   * Same shape as `connection.onLogs()` callback — plug into `EventParser.parseLogs()`.
+   */
+  logs: (logs: string[], signature: string, slot: number) => void;
+
+  /** Emitted when the gRPC stream connects or reconnects. */
+  connected: () => void;
+
+  /** Emitted when the stream disconnects. */
+  disconnected: (reason: string) => void;
+
+  /** Emitted on transport or parsing errors. */
+  error: (err: Error) => void;
+
+  /** Emitted on reconnection attempt. */
+  reconnecting: (attempt: number) => void;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Constants
+// ═══════════════════════════════════════════════════════════════════
+
+const SAP_PROGRAM_ID = "SAPpUhsWLJG1FfkGRcXagEDMrMsWGjbky7AyhGpFETZ";
+
+const COMMITMENT_MAP: Record<string, number> = {
+  processed: 0,
+  confirmed: 1,
+  finalized: 2,
+};
+
+// ═══════════════════════════════════════════════════════════════════
+//  GeyserEventStream
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Yellowstone gRPC event stream for SAP v2 programs.
+ *
+ * Wraps `@triton-one/yellowstone-grpc` and emits parsed log lines
+ * compatible with the existing {@link EventParser}.
+ *
+ * @name GeyserEventStream
+ * @category Events
+ * @since v0.6.3
+ *
+ * @example
+ * ```ts
+ * const stream = new GeyserEventStream({
+ *   endpoint: "https://grpc.triton.one",
+ *   token:    process.env.GEYSER_TOKEN!,
+ * });
+ *
+ * stream.on("logs", (logs, sig, slot) => {
+ *   const events = parser.parseLogs(logs);
+ *   events.forEach(e => db.insertEvent(e));
+ * });
+ *
+ * await stream.connect();
+ * ```
+ */
+export class GeyserEventStream extends EventEmitter {
+  private readonly config: Required<GeyserConfig>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private client: any = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private stream: any = null;
+  private reconnectAttempts = 0;
+  private _connected = false;
+  private _stopped = false;
+
+  constructor(config: GeyserConfig) {
+    super();
+    this.config = {
+      endpoint: config.endpoint,
+      token: config.token,
+      programId: config.programId ?? SAP_PROGRAM_ID,
+      commitment: config.commitment ?? "confirmed",
+      autoReconnect: config.autoReconnect ?? true,
+      reconnectDelayMs: config.reconnectDelayMs ?? 3_000,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? 0,
+      includeFailedTxs: config.includeFailedTxs ?? false,
+    };
+  }
+
+  /** Whether the gRPC stream is currently connected. */
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  /**
+   * Connect to the Yellowstone gRPC endpoint and start streaming.
+   *
+   * @throws If `@triton-one/yellowstone-grpc` is not installed.
+   */
+  async connect(): Promise<void> {
+    this._stopped = false;
+    this.reconnectAttempts = 0;
+
+    // Dynamic import — yellowstone is an optional peer dependency
+    let YellowstoneClient: new (...args: unknown[]) => unknown;
+    try {
+      const mod = await import("@triton-one/yellowstone-grpc");
+      YellowstoneClient = mod.default ?? mod.Client;
+    } catch {
+      throw new Error(
+        "Missing dependency: @triton-one/yellowstone-grpc\n" +
+          "Install it with: npm i @triton-one/yellowstone-grpc",
+      );
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.client = new (YellowstoneClient as any)(
+      this.config.endpoint,
+      this.config.token,
+      undefined, // TLS options — use defaults
+    );
+
+    await this.subscribe();
+  }
+
+  /**
+   * Disconnect from the gRPC stream and stop reconnection.
+   */
+  async disconnect(): Promise<void> {
+    this._stopped = true;
+    this._connected = false;
+
+    if (this.stream) {
+      try {
+        this.stream.cancel?.();
+        this.stream = null;
+      } catch {
+        // ignore cancel errors
+      }
+    }
+
+    this.emit("disconnected", "manual");
+  }
+
+  // ─── Internal ──────────────────────────────────────
+
+  private async subscribe(): Promise<void> {
+    if (!this.client || this._stopped) return;
+
+    try {
+      this.stream = await this.client.subscribe();
+    } catch (err) {
+      this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      await this.maybeReconnect();
+      return;
+    }
+
+    // Build the subscription request
+    const request = {
+      accounts: {},
+      slots: {},
+      transactions: {
+        sap: {
+          vote: false,
+          failed: this.config.includeFailedTxs,
+          signature: undefined,
+          accountInclude: [this.config.programId],
+          accountExclude: [],
+          accountRequired: [],
+        },
+      },
+      transactionsStatus: {},
+      blocks: {},
+      blocksMeta: {},
+      entry: {},
+      commitment: COMMITMENT_MAP[this.config.commitment] ?? 1,
+      accountsDataSlice: [],
+      ping: { id: 1 },
+    };
+
+    // Send subscription
+    try {
+      await new Promise<void>((resolve, reject) => {
+        this.stream.write(request, (err: Error | null) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    } catch (err) {
+      this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      await this.maybeReconnect();
+      return;
+    }
+
+    this._connected = true;
+    this.reconnectAttempts = 0;
+    this.emit("connected");
+
+    // Listen for data
+    this.stream.on("data", (data: GeyserUpdateMessage) => {
+      try {
+        this.handleMessage(data);
+      } catch (err) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+
+    this.stream.on("error", (err: Error) => {
+      this.emit("error", err);
+    });
+
+    this.stream.on("end", () => {
+      this._connected = false;
+      this.emit("disconnected", "stream-end");
+      this.maybeReconnect();
+    });
+
+    this.stream.on("close", () => {
+      this._connected = false;
+      this.emit("disconnected", "stream-close");
+      this.maybeReconnect();
+    });
+  }
+
+  private handleMessage(data: GeyserUpdateMessage): void {
+    // Respond to pings to keep the stream alive
+    if (data.ping) {
+      this.stream?.write({ ping: { id: data.ping.id } }, () => {});
+      return;
+    }
+
+    // Extract transaction data
+    const tx = data.transaction;
+    if (!tx?.transaction?.transaction) return;
+
+    const meta = tx.transaction.meta;
+    if (!meta) return;
+
+    // Extract log messages from the transaction meta
+    const logs: string[] = meta.logMessages ?? [];
+    if (logs.length === 0) return;
+
+    const signature = tx.transaction.signature
+      ? Buffer.from(tx.transaction.signature).toString("base64")
+      : "unknown";
+
+    const slot = Number(tx.slot ?? 0);
+
+    this.emit("logs", logs, signature, slot);
+  }
+
+  private async maybeReconnect(): Promise<void> {
+    if (this._stopped || !this.config.autoReconnect) return;
+
+    const max = this.config.maxReconnectAttempts;
+    if (max > 0 && this.reconnectAttempts >= max) {
+      this.emit(
+        "error",
+        new Error(`Max reconnect attempts (${max}) exceeded`),
+      );
+      return;
+    }
+
+    this.reconnectAttempts++;
+    this.emit("reconnecting", this.reconnectAttempts);
+
+    await new Promise((r) => setTimeout(r, this.config.reconnectDelayMs));
+
+    if (!this._stopped) {
+      await this.subscribe();
+    }
+  }
+}
+
+// ─── Internal Yellowstone message types ─────────────
+
+interface GeyserUpdateMessage {
+  ping?: { id: number };
+  transaction?: {
+    slot?: string | number;
+    transaction?: {
+      signature?: Uint8Array;
+      transaction?: unknown;
+      meta?: {
+        logMessages?: string[];
+      };
+    };
+  };
+}

package/src/events/yellowstone.d.ts

@@ -0,0 +1,7 @@
+// Optional peer dependency — only needed when using GeyserEventStream
+declare module "@triton-one/yellowstone-grpc" {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Client: any;
+  export default Client;
+  export { Client };
+}

package/src/index.ts

@@ -240,6 +240,10 @@ export type {
   LedgerEntryEventData,
 } from "./events";
 
+// ── Geyser (Yellowstone gRPC) ────────────────────────
+export { GeyserEventStream } from "./events/geyser";
+export type { GeyserConfig, GeyserStreamEvents } from "./events/geyser";
+
 // ── Modules (for advanced usage / tree-shaking) ──────
 export {
   AgentModule,

package/src/postgres/sync.ts

@@ -35,6 +35,7 @@
 
 import type { SapClient } from "../core/client";
 import { EventParser } from "../events";
+import { GeyserEventStream, type GeyserConfig } from "../events/geyser";
 import type { SapPostgres, SyncAllResult } from "./adapter";
 import type { SyncOptions } from "./types";
 
@@ -67,6 +68,7 @@ export class SapSyncEngine {
 
   private intervalId: ReturnType<typeof setInterval> | null = null;
   private logSubId: number | null = null;
+  private geyserStream: GeyserEventStream | null = null;
   private running = false;
 
   constructor(pg: SapPostgres, client: SapClient, debug = false) {
@@ -208,7 +210,7 @@ export class SapSyncEngine {
 
   /**
    * @name stopEventStream
-   * @description Unsubscribe from the program log stream.
+   * @description Unsubscribe from the program log stream (WebSocket or Geyser).
    * @since v0.1.0
    */
   async stopEventStream(): Promise<void> {
@@ -216,8 +218,92 @@ export class SapSyncEngine {
       const connection = this.client.program.provider.connection;
       await connection.removeOnLogsListener(this.logSubId);
       this.logSubId = null;
-      this.log("Event stream stopped");
+      this.log("WebSocket event stream stopped");
     }
+    if (this.geyserStream) {
+      await this.geyserStream.disconnect();
+      this.geyserStream = null;
+      this.log("Geyser event stream stopped");
+    }
+  }
+
+  // ═════════════════════════════════════════════
+  //  Geyser gRPC Event Stream
+  // ═════════════════════════════════════════════
+
+  /**
+   * @name startGeyserStream
+   * @description Subscribe to SAP program transactions via Yellowstone gRPC
+   * and insert parsed events into the `sap_events` table in real-time.
+   *
+   * Drop-in replacement for {@link startEventStream} with lower latency,
+   * no missed events, and automatic reconnection.
+   *
+   * Requires `@triton-one/yellowstone-grpc` to be installed.
+   *
+   * @param geyserConfig - Yellowstone gRPC connection config.
+   * @since v0.6.3
+   *
+   * @example
+   * ```ts
+   * await sync.startGeyserStream({
+   *   endpoint: "https://grpc.triton.one",
+   *   token:    process.env.GEYSER_TOKEN!,
+   * });
+   * ```
+   */
+  async startGeyserStream(geyserConfig: GeyserConfig): Promise<void> {
+    if (this.geyserStream) {
+      this.log("Geyser stream already running");
+      return;
+    }
+
+    const eventParser = new EventParser(this.client.program);
+    const stream = new GeyserEventStream(geyserConfig);
+
+    stream.on("logs", async (logs: string[], signature: string, slot: number) => {
+      try {
+        const events = eventParser.parseLogs(logs);
+        for (const event of events) {
+          const data = event.data as Record<string, unknown>;
+          const agentPda =
+            (data.agent as string) ?? (data.agentPda as string) ?? undefined;
+          const wallet =
+            (data.wallet as string) ?? (data.owner as string) ?? undefined;
+
+          await this.pg.syncEvent(
+            event.name,
+            signature,
+            slot,
+            data,
+            agentPda,
+            wallet,
+          );
+        }
+      } catch (err) {
+        this.log(`Geyser event parse error: ${err}`);
+      }
+    });
+
+    stream.on("connected", () => {
+      this.log("Geyser gRPC connected");
+    });
+
+    stream.on("disconnected", (reason: string) => {
+      this.log(`Geyser gRPC disconnected: ${reason}`);
+    });
+
+    stream.on("error", (err: Error) => {
+      this.log(`Geyser error: ${err.message}`);
+    });
+
+    stream.on("reconnecting", (attempt: number) => {
+      this.log(`Geyser reconnecting (attempt ${attempt})...`);
+    });
+
+    await stream.connect();
+    this.geyserStream = stream;
+    this.log("Geyser event stream started");
   }
 
   // ═════════════════════════════════════════════
@@ -235,11 +321,11 @@ export class SapSyncEngine {
 
   /**
    * @name isStreaming
-   * @description Check whether the event stream is active.
+   * @description Check whether the event stream is active (WebSocket or Geyser).
    * @since v0.1.0
    */
   isStreaming(): boolean {
-    return this.logSubId !== null;
+    return this.logSubId !== null || this.geyserStream?.connected === true;
   }
 
   // ═════════════════════════════════════════════