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

package/dist/types/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,eAAe,EACf,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGnE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,eAAe,EACf,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,GACnC,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,iBAAiB,EACjB,aAAa,GACd,MAAM,gBAAgB,CAAC"}

package/dist/types/utils/priority-fee.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @module utils/priority-fee
+ * @description Compute budget and priority fee utilities for SAP transactions.
+ *
+ * Solana transactions that include a priority fee (via the Compute Budget program)
+ * land faster because validators prefer higher-fee transactions. This module
+ * provides a clean, composable API for building priority-fee instructions
+ * that can be prepended to any Anchor method builder via `.preInstructions()`.
+ *
+ * Typical use: x402 settlement transactions where the receiving agent's RPC
+ * has a short confirmation window (e.g., 30 seconds).
+ *
+ * @category Utils
+ * @since v0.6.2
+ *
+ * @example
+ * ```ts
+ * import { buildPriorityFeeIxs, DEFAULT_SETTLE_PRIORITY } from "@synapse-sap/sdk";
+ *
+ * // Append to any Anchor method builder:
+ * await program.methods
+ *   .settleCalls(calls, hash)
+ *   .accounts({ ... })
+ *   .preInstructions(buildPriorityFeeIxs({ priorityFeeMicroLamports: 5000 }))
+ *   .rpc({ skipPreflight: true });
+ * ```
+ */
+import { type TransactionInstruction } from "@solana/web3.js";
+/**
+ * Default priority fee for settlement transactions (in microlamports).
+ * 5000 µL ≈ 0.0005 SOL per 200k CU — fast enough for most agent RPCs.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_SETTLE_PRIORITY_FEE = 5000;
+/**
+ * Default compute unit limit for settlement transactions.
+ * `settle_calls` uses ~60k CU; 100k provides a safe margin.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_SETTLE_COMPUTE_UNITS = 100000;
+/**
+ * Default compute unit limit for batch settlement transactions.
+ * `settle_batch` with 10 entries uses ~200k CU; 300k provides margin.
+ *
+ * @since v0.6.2
+ */
+export declare const DEFAULT_BATCH_SETTLE_COMPUTE_UNITS = 300000;
+/**
+ * @interface PriorityFeeConfig
+ * @description Configuration for building compute budget instructions.
+ * @category Utils
+ * @since v0.6.2
+ */
+export interface PriorityFeeConfig {
+    /**
+     * Priority fee in microlamports per compute unit.
+     * Higher values = faster confirmation.
+     *
+     * Common values:
+     * - `1000` — low priority (~0.0001 SOL)
+     * - `5000` — medium priority (~0.0005 SOL) ← recommended for settle
+     * - `50000` — high priority (~0.005 SOL)
+     * - `0` — no priority fee (default Solana behavior)
+     *
+     * @default 0
+     */
+    readonly priorityFeeMicroLamports?: number;
+    /**
+     * Maximum compute units the transaction may consume.
+     * Setting an explicit limit avoids overpaying for unused CU.
+     *
+     * @default 200_000 (Solana default)
+     */
+    readonly computeUnits?: number;
+}
+/**
+ * @interface SettleOptions
+ * @description Options for x402 settlement transactions.
+ * Controls priority fees, compute budget, and RPC behavior
+ * to optimize confirmation speed for time-sensitive settlements.
+ *
+ * @category Registries
+ * @since v0.6.2
+ *
+ * @example
+ * ```ts
+ * // Fast settlement with priority fee
+ * const receipt = await x402.settle(depositor, 1, "data", {
+ *   priorityFeeMicroLamports: 5000,
+ *   computeUnits: 100_000,
+ *   skipPreflight: true,
+ * });
+ *
+ * // Use the convenience preset
+ * import { FAST_SETTLE_OPTIONS } from "@synapse-sap/sdk";
+ * const receipt = await x402.settle(depositor, 1, "data", FAST_SETTLE_OPTIONS);
+ * ```
+ */
+export interface SettleOptions extends PriorityFeeConfig {
+    /**
+     * Skip Solana simulation before submitting.
+     * Saves ~400ms but loses pre-flight error detection.
+     *
+     * Recommended for settlements where the escrow state
+     * has already been pre-fetched and validated.
+     *
+     * @default false
+     */
+    readonly skipPreflight?: boolean;
+    /**
+     * Transaction commitment level override.
+     * Uses the provider's default when omitted.
+     *
+     * - `"processed"` — fastest, least reliable
+     * - `"confirmed"` — balanced (recommended)
+     * - `"finalized"` — slowest, most reliable
+     */
+    readonly commitment?: "processed" | "confirmed" | "finalized";
+    /**
+     * Maximum number of RPC retry attempts.
+     * @default provider default (usually 3)
+     */
+    readonly maxRetries?: number;
+}
+/**
+ * Recommended preset for fast x402 settlements.
+ * Priority fee 5000 µL, 100k CU, skip preflight, confirmed commitment.
+ *
+ * @since v0.6.2
+ */
+export declare const FAST_SETTLE_OPTIONS: Readonly<SettleOptions>;
+/**
+ * Recommended preset for fast batch settlements.
+ * Priority fee 5000 µL, 300k CU, skip preflight, confirmed commitment.
+ *
+ * @since v0.6.2
+ */
+export declare const FAST_BATCH_SETTLE_OPTIONS: Readonly<SettleOptions>;
+/**
+ * @name buildPriorityFeeIxs
+ * @description Build compute budget instructions for priority fee transactions.
+ *
+ * Returns an array of 0–2 `TransactionInstruction`s:
+ * - `SetComputeUnitPrice` (if `priorityFeeMicroLamports > 0`)
+ * - `SetComputeUnitLimit` (if `computeUnits` provided)
+ *
+ * The returned array is designed to be passed directly to
+ * Anchor's `.preInstructions()` builder method.
+ *
+ * @param config - Priority fee configuration.
+ * @returns Array of compute budget instructions (may be empty).
+ *
+ * @category Utils
+ * @since v0.6.2
+ *
+ * @example
+ * ```ts
+ * const ixs = buildPriorityFeeIxs({
+ *   priorityFeeMicroLamports: 5000,
+ *   computeUnits: 100_000,
+ * });
+ *
+ * await program.methods
+ *   .settleCalls(calls, hash)
+ *   .accounts({ ... })
+ *   .preInstructions(ixs)
+ *   .rpc({ skipPreflight: true });
+ * ```
+ */
+export declare function buildPriorityFeeIxs(config?: PriorityFeeConfig): TransactionInstruction[];
+/**
+ * @name buildRpcOptions
+ * @description Build Anchor `.rpc()` options from {@link SettleOptions}.
+ *
+ * @param opts - Settle options.
+ * @returns Options object suitable for Anchor `.rpc(opts)`.
+ *
+ * @category Utils
+ * @since v0.6.2
+ * @internal
+ */
+export declare function buildRpcOptions(opts?: SettleOptions): Record<string, unknown> | undefined;
+//# sourceMappingURL=priority-fee.d.ts.map

package/dist/types/utils/priority-fee.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-fee.d.ts","sourceRoot":"","sources":["../../../src/utils/priority-fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,SAAU,CAAC;AAM1D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAE9D;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,aAAa,CAKtD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,aAAa,CAK5D,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,iBAAiB,GACzB,sBAAsB,EAAE,CAwB1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,CAAC,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgBrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.6.0",
+  "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

@@ -202,6 +202,20 @@ export {
   validateOrThrow,
 } from "./utils";
 
+// v0.6.2 — Priority fee & settle options
+export {
+  buildPriorityFeeIxs,
+  buildRpcOptions,
+  FAST_SETTLE_OPTIONS,
+  FAST_BATCH_SETTLE_OPTIONS,
+  DEFAULT_SETTLE_PRIORITY_FEE,
+  DEFAULT_SETTLE_COMPUTE_UNITS,
+  DEFAULT_BATCH_SETTLE_COMPUTE_UNITS,
+} from "./utils";
+export type {
+  PriorityFeeConfig,
+} from "./utils";
+
 // ── Errors ───────────────────────────────────────────
 export {
   SapError,
@@ -226,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,
@@ -315,6 +333,7 @@ export type {
   EscrowBalance,
   SettlementResult,
   BatchSettlementResult,
+  SettleOptions,
   SessionContext,
   WriteResult,
   SealResult,