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

package/src/modules/subscription.ts

@@ -0,0 +1,147 @@
+/**
+ * @module subscription
+ * @description Agent subscription lifecycle — create, fund, cancel,
+ * close, and fetch subscription accounts.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+
+import {
+  SystemProgram,
+  type PublicKey,
+  type TransactionSignature,
+} from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveSubscription } from "../pda";
+import type { SubscriptionData, CreateSubscriptionArgs } from "../types";
+
+/**
+ * @name SubscriptionModule
+ * @description Manages recurring subscriptions between subscribers and agents.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export class SubscriptionModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  private toNum(v: BN | number | bigint): number {
+    return BN.isBN(v) ? v.toNumber() : Number(v);
+  }
+
+  deriveSubscription(
+    agentPda: PublicKey,
+    subscriber?: PublicKey,
+    subId: BN | number | bigint = 0,
+  ): readonly [PublicKey, number] {
+    return deriveSubscription(
+      agentPda,
+      subscriber ?? this.walletPubkey,
+      this.toNum(subId),
+    );
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  async create(
+    agentWallet: PublicKey,
+    args: CreateSubscriptionArgs,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [subPda] = this.deriveSubscription(agentPda, undefined, args.subId);
+
+    return this.methods
+      .createSubscription(
+        this.bn(args.subId),
+        this.bn(args.pricePerInterval),
+        args.billingInterval,
+        this.bn(args.initialFund),
+      )
+      .accounts({
+        subscriber: this.walletPubkey,
+        agent: agentPda,
+        subscription: subPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  async fund(
+    agentWallet: PublicKey,
+    subId: BN | number | bigint,
+    amount: BN | number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+
+    return this.methods
+      .fundSubscription(this.bn(amount))
+      .accounts({
+        subscriber: this.walletPubkey,
+        subscription: subPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  async cancel(
+    agentWallet: PublicKey,
+    subId: BN | number | bigint = 0,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+
+    return this.methods
+      .cancelSubscription()
+      .accounts({
+        subscriber: this.walletPubkey,
+        agentWallet,
+        subscription: subPda,
+      })
+      .rpc();
+  }
+
+  async close(
+    agentWallet: PublicKey,
+    subId: BN | number | bigint = 0,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [subPda] = this.deriveSubscription(agentPda, undefined, subId);
+
+    return this.methods
+      .closeSubscription()
+      .accounts({
+        subscriber: this.walletPubkey,
+        subscription: subPda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  async fetch(
+    agentPda: PublicKey,
+    subscriber?: PublicKey,
+    subId: BN | number | bigint = 0,
+  ): Promise<SubscriptionData> {
+    const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
+    return this.fetchAccount<SubscriptionData>("subscriptionAccount", pda);
+  }
+
+  async fetchNullable(
+    agentPda: PublicKey,
+    subscriber?: PublicKey,
+    subId: BN | number | bigint = 0,
+  ): Promise<SubscriptionData | null> {
+    const [pda] = this.deriveSubscription(agentPda, subscriber, subId);
+    return this.fetchAccountNullable<SubscriptionData>("subscriptionAccount", pda);
+  }
+
+  async fetchByPda(subPda: PublicKey): Promise<SubscriptionData> {
+    return this.fetchAccount<SubscriptionData>("subscriptionAccount", subPda);
+  }
+}

package/src/pda/index.ts

@@ -79,6 +79,22 @@ const u32le = (n: number): Buffer => {
   return buf;
 };
 
+/**
+ * Encode an unsigned 64-bit integer as a little-endian `Buffer`.
+ *
+ * @name u64le
+ * @description Produces an 8-byte LE buffer for u64 PDA seed segments (e.g., escrow nonce, sub_id).
+ * @param n - The number or bigint to encode.
+ * @returns {Buffer} 8-byte little-endian buffer.
+ * @category PDA
+ * @since v0.5.0
+ */
+const u64le = (n: number | bigint): Buffer => {
+  const buf = Buffer.alloc(8);
+  buf.writeBigUInt64LE(BigInt(n), 0);
+  return buf;
+};
+
 // ═════════════════════════════════════════════
 //  Core PDAs
 // ═════════════════════════════════════════════
@@ -421,6 +437,7 @@ export const deriveTool = (
  * @returns {PdaResult} `[pda, bump]` tuple.
  * @category PDA
  * @since v0.1.0
+ * @deprecated Since v0.7.0 — Use {@link deriveEscrowV2} for V2 escrows with nonce support.
  * @see EscrowAccount
  */
 export const deriveEscrow = (
@@ -650,3 +667,182 @@ export const deriveMemoryChunk = (
     ],
     programId,
   );
+
+// ═════════════════════════════════════════════
+//  Escrow V2
+// ═════════════════════════════════════════════
+
+/**
+ * Derive the **EscrowAccountV2** PDA.
+ *
+ * Seeds: `["sap_escrow_v2", agent_pda, depositor_wallet, nonce_u64_le]`
+ *
+ * @name deriveEscrowV2
+ * @description Computes the V2 escrow PDA supporting nonce-based multi-escrow.
+ * @param agentPda  - The agent's PDA.
+ * @param depositor - The depositor's wallet.
+ * @param nonce     - Escrow nonce (u64) allowing multiple escrows per pair.
+ * @param programId - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const deriveEscrowV2 = (
+  agentPda: PublicKey,
+  depositor: PublicKey,
+  nonce: number | bigint = 0,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [
+      toSeedBuf(SEEDS.ESCROW_V2),
+      agentPda.toBuffer(),
+      depositor.toBuffer(),
+      u64le(nonce),
+    ],
+    programId,
+  );
+
+/**
+ * Derive the **PendingSettlement** PDA.
+ *
+ * Seeds: `["sap_pending", escrow_v2_pda, settlement_index_u64_le]`
+ *
+ * @name derivePendingSettlement
+ * @param escrowV2Pda     - The parent V2 escrow PDA.
+ * @param settlementIndex - The monotonic settlement index (u64).
+ * @param programId       - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const derivePendingSettlement = (
+  escrowV2Pda: PublicKey,
+  settlementIndex: number | bigint,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [
+      toSeedBuf(SEEDS.PENDING),
+      escrowV2Pda.toBuffer(),
+      u64le(settlementIndex),
+    ],
+    programId,
+  );
+
+/**
+ * Derive the **DisputeRecord** PDA.
+ *
+ * Seeds: `["sap_dispute", pending_settlement_pda]`
+ *
+ * @name deriveDispute
+ * @param pendingSettlementPda - The parent pending settlement PDA.
+ * @param programId            - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const deriveDispute = (
+  pendingSettlementPda: PublicKey,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [toSeedBuf(SEEDS.DISPUTE), pendingSettlementPda.toBuffer()],
+    programId,
+  );
+
+/**
+ * Derive the **AgentStake** PDA.
+ *
+ * Seeds: `["sap_stake", agent_pda]`
+ *
+ * @name deriveStake
+ * @param agentPda  - The agent's PDA.
+ * @param programId - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const deriveStake = (
+  agentPda: PublicKey,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda([toSeedBuf(SEEDS.STAKE), agentPda.toBuffer()], programId);
+
+/**
+ * Derive the **Subscription** PDA.
+ *
+ * Seeds: `["sap_sub", agent_pda, subscriber_wallet, sub_id_u64_le]`
+ *
+ * @name deriveSubscription
+ * @param agentPda   - The agent's PDA.
+ * @param subscriber - The subscriber's wallet.
+ * @param subId      - Subscription ID (u64).
+ * @param programId  - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const deriveSubscription = (
+  agentPda: PublicKey,
+  subscriber: PublicKey,
+  subId: number | bigint = 0,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [
+      toSeedBuf(SEEDS.SUBSCRIPTION),
+      agentPda.toBuffer(),
+      subscriber.toBuffer(),
+      u64le(subId),
+    ],
+    programId,
+  );
+
+/**
+ * Derive the **CounterShard** PDA.
+ *
+ * Seeds: `["sap_shard", shard_index_u8]`
+ *
+ * @name deriveShard
+ * @param shardIndex - The shard index (0–7).
+ * @param programId  - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const deriveShard = (
+  shardIndex: number,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [toSeedBuf(SEEDS.SHARD), Buffer.from([shardIndex])],
+    programId,
+  );
+
+/**
+ * Derive the **IndexPage** PDA.
+ *
+ * Seeds: `["sap_idx_page", parent_index_pda, page_index_u8]`
+ *
+ * @name deriveIndexPage
+ * @param parentIndexPda - The parent index PDA (CapabilityIndex, ProtocolIndex, etc.).
+ * @param pageIndex      - The page index (0–255).
+ * @param programId      - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.5.0
+ */
+export const deriveIndexPage = (
+  parentIndexPda: PublicKey,
+  pageIndex: number,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [
+      toSeedBuf(SEEDS.INDEX_PAGE),
+      parentIndexPda.toBuffer(),
+      Buffer.from([pageIndex]),
+    ],
+    programId,
+  );

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;
   }
 
   // ═════════════════════════════════════════════