@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.14.0

package/src/events/geyser.ts

@@ -1,384 +0,0 @@
-/**
- * @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/index.ts

@@ -1,335 +0,0 @@
-/**
- * @module events
- * @description Decode SAP v2 events from transaction logs.
- *
- * Uses Anchor's event parser under the hood. Provides a
- * strongly-typed, filterable event stream.
- *
- * @category Events
- * @since v0.1.0
- *
- * @example
- * ```ts
- * import { EventParser } from "@synapse-sap/sdk/events";
- *
- * const events = client.events.parseLogs(txLogs);
- * for (const event of events) {
- *   if (event.name === "PaymentSettledEvent") {
- *     console.log(event.data);
- *   }
- * }
- * ```
- */
-
-import { type Program, BN, EventParser as AnchorEventParser } from "@coral-xyz/anchor";
-import type { PublicKey } from "@solana/web3.js";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Event Data Types
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Decoded payload for the `RegisteredEvent` emitted when a new agent is registered.
- *
- * @interface RegisteredEventData
- * @name RegisteredEventData
- * @description Contains the agent PDA, owner wallet, display name, capabilities list, and timestamp.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEvent}
- */
-export interface RegisteredEventData {
-  readonly name: "RegisteredEvent";
-  readonly data: {
-    agent: PublicKey;
-    wallet: PublicKey;
-    name: string;
-    capabilities: string[];
-    timestamp: BN;
-  };
-}
-
-/**
- * Decoded payload for the `UpdatedEvent` emitted when an agent’s profile is modified.
- *
- * @interface UpdatedEventData
- * @name UpdatedEventData
- * @description Contains the agent PDA, owner wallet, a list of changed field names, and timestamp.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEvent}
- */
-export interface UpdatedEventData {
-  readonly name: "UpdatedEvent";
-  readonly data: {
-    agent: PublicKey;
-    wallet: PublicKey;
-    updatedFields: string[];
-    timestamp: BN;
-  };
-}
-
-/**
- * Decoded payload for the `FeedbackEvent` emitted when a reviewer submits feedback.
- *
- * @interface FeedbackEventData
- * @name FeedbackEventData
- * @description Contains the agent PDA, reviewer wallet, numeric score, tag, and timestamp.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEvent}
- */
-export interface FeedbackEventData {
-  readonly name: "FeedbackEvent";
-  readonly data: {
-    agent: PublicKey;
-    reviewer: PublicKey;
-    score: number;
-    tag: string;
-    timestamp: BN;
-  };
-}
-
-/**
- * Decoded payload for the `MemoryInscribedEvent` emitted when data is written to a vault.
- *
- * @interface MemoryInscribedEventData
- * @name MemoryInscribedEventData
- * @description Contains vault/session PDAs, sequence info, encrypted data, nonce, content hash,
- *   fragment metadata, compression flag, and timestamp.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEvent}
- */
-export interface MemoryInscribedEventData {
-  readonly name: "MemoryInscribedEvent";
-  readonly data: {
-    vault: PublicKey;
-    session: PublicKey;
-    sequence: number;
-    epochIndex: number;
-    encryptedData: number[];
-    nonce: number[];
-    contentHash: number[];
-    totalFragments: number;
-    fragmentIndex: number;
-    compression: number;
-    dataLen: number;
-    nonceVersion: number;
-    timestamp: BN;
-  };
-}
-
-/**
- * Decoded payload for the `PaymentSettledEvent` emitted when an escrow settlement occurs.
- *
- * @interface PaymentSettledEventData
- * @name PaymentSettledEventData
- * @description Contains escrow/agent/depositor PDAs, settlement counts, amounts, service hash,
- *   and remaining balance.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEvent}
- */
-export interface PaymentSettledEventData {
-  readonly name: "PaymentSettledEvent";
-  readonly data: {
-    escrow: PublicKey;
-    agent: PublicKey;
-    depositor: PublicKey;
-    callsSettled: BN;
-    amount: BN;
-    serviceHash: number[];
-    totalCallsSettled: BN;
-    remainingBalance: BN;
-    timestamp: BN;
-  };
-}
-
-/**
- * Decoded payload for the `LedgerEntryEvent` emitted when data is appended to a ledger.
- *
- * @interface LedgerEntryEventData
- * @name LedgerEntryEventData
- * @description Contains session/ledger PDAs, entry index, raw data, content hash,
- *   Merkle root, and timestamp.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEvent}
- */
-export interface LedgerEntryEventData {
-  readonly name: "LedgerEntryEvent";
-  readonly data: {
-    session: PublicKey;
-    ledger: PublicKey;
-    entryIndex: number;
-    data: number[];
-    contentHash: number[];
-    dataLen: number;
-    merkleRoot: number[];
-    timestamp: BN;
-  };
-}
-
-/**
- * Discriminated union of all known SAP v2 event types.
- *
- * @name SapEvent
- * @description Use the `name` discriminant to narrow to a specific event payload.
- * @category Events
- * @since v0.1.0
- */
-export type SapEvent =
-  | RegisteredEventData
-  | UpdatedEventData
-  | FeedbackEventData
-  | MemoryInscribedEventData
-  | PaymentSettledEventData
-  | LedgerEntryEventData;
-
-// ═══════════════════════════════════════════════════════════════════
-//  Event Name Literals
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * Exhaustive list of all SAP v2 event name strings.
- *
- * @name SAP_EVENT_NAMES
- * @description Frozen array of every event discriminant emitted by the program.
- *   Useful for log filtering and exhaustive switch checks.
- * @category Events
- * @since v0.1.0
- * @see {@link SapEventName}
- */
-export const SAP_EVENT_NAMES = [
-  "RegisteredEvent",
-  "UpdatedEvent",
-  "DeactivatedEvent",
-  "ReactivatedEvent",
-  "ClosedEvent",
-  "FeedbackEvent",
-  "FeedbackUpdatedEvent",
-  "FeedbackRevokedEvent",
-  "ReputationUpdatedEvent",
-  "CallsReportedEvent",
-  "VaultInitializedEvent",
-  "SessionOpenedEvent",
-  "MemoryInscribedEvent",
-  "EpochOpenedEvent",
-  "SessionClosedEvent",
-  "VaultClosedEvent",
-  "SessionPdaClosedEvent",
-  "EpochPageClosedEvent",
-  "VaultNonceRotatedEvent",
-  "DelegateAddedEvent",
-  "DelegateRevokedEvent",
-  "ToolPublishedEvent",
-  "ToolSchemaInscribedEvent",
-  "ToolUpdatedEvent",
-  "ToolDeactivatedEvent",
-  "ToolReactivatedEvent",
-  "ToolClosedEvent",
-  "ToolInvocationReportedEvent",
-  "CheckpointCreatedEvent",
-  "EscrowCreatedEvent",
-  "EscrowDepositedEvent",
-  "PaymentSettledEvent",
-  "EscrowWithdrawnEvent",
-  "BatchSettledEvent",
-  "AttestationCreatedEvent",
-  "AttestationRevokedEvent",
-  "LedgerEntryEvent",
-  "LedgerSealedEvent",
-] as const;
-
-/**
- * String literal union of all SAP v2 event names.
- *
- * @name SapEventName
- * @description Derived from {@link SAP_EVENT_NAMES} for compile-time exhaustiveness.
- * @category Events
- * @since v0.1.0
- */
-export type SapEventName = (typeof SAP_EVENT_NAMES)[number];
-
-// ═══════════════════════════════════════════════════════════════════
-//  Event Parser
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * A single parsed event extracted from transaction logs.
- *
- * @interface ParsedEvent
- * @name ParsedEvent
- * @description Lightweight container with a `name` discriminant and untyped `data` record.
- *   Narrow via {@link SapEventName} for type-safe access.
- * @category Events
- * @since v0.1.0
- */
-export interface ParsedEvent {
-  readonly name: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly data: Record<string, any>;
-}
-
-/**
- * Typed wrapper around Anchor’s `EventParser` for SAP v2 programs.
- *
- * Extracts strongly-typed {@link ParsedEvent} objects from raw
- * transaction log lines.
- *
- * @name EventParser
- * @description Instantiate with an Anchor `Program` and call {@link EventParser.parseLogs}
- *   to decode events, or {@link EventParser.filterByName} to narrow results.
- * @category Events
- * @since v0.1.0
- *
- * @example
- * ```ts
- * const parser = new EventParser(program);
- * const events = parser.parseLogs(txLogs);
- * const settled = parser.filterByName(events, "PaymentSettledEvent");
- * ```
- */
-export class EventParser {
-  private readonly parser: AnchorEventParser;
-
-  /**
-   * Create a new `EventParser`.
-   *
-   * @param program - An Anchor `Program` instance whose IDL defines the events to decode.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  constructor(program: Program<any>) {
-    this.parser = new AnchorEventParser(program.programId, program.coder);
-  }
-
-  /**
-   * Parse raw transaction log lines into typed events.
-   *
-   * @param logs - Array of log strings from a confirmed transaction.
-   * @returns {ParsedEvent[]} Decoded events found in the logs.
-   */
-  parseLogs(logs: string[]): ParsedEvent[] {
-    const events: ParsedEvent[] = [];
-    const generator = this.parser.parseLogs(logs);
-    for (const event of generator) {
-      events.push(event as ParsedEvent);
-    }
-    return events;
-  }
-
-  /**
-   * Filter a list of parsed events by event name.
-   *
-   * @param events - The full array of {@link ParsedEvent} objects to filter.
-   * @param name   - The {@link SapEventName} to match against.
-   * @returns {ParsedEvent[]} Only events whose `name` matches.
-   */
-  filterByName<N extends SapEventName>(
-    events: ParsedEvent[],
-    name: N,
-  ): ParsedEvent[] {
-    return events.filter((e) => e.name === name);
-  }
-}