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

package/dist/types/utils/x402-direct.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module utils/x402-direct
+ * @description Recognize x402 direct SPL token payments on an agent's ATA
+ * by scanning transaction history and filtering for x402 patterns.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { type Connection, PublicKey } from "@solana/web3.js";
+/**
+ * @interface SettlementPayload
+ * @description Settlement metadata from the merchant's PAYMENT-RESPONSE.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface SettlementPayload {
+    /** SHA-256 service hash. */
+    readonly serviceHash: string;
+    /** Resource identifier. */
+    readonly resource: string;
+    /** Agent wallet (base58). */
+    readonly agentWallet: string;
+    /** Depositor wallet (base58). */
+    readonly depositorWallet: string;
+    /** Amount in smallest unit. */
+    readonly amount: string;
+    /** Service timestamp. */
+    readonly timestamp: number;
+}
+/**
+ * @interface X402DirectPayment
+ * @description A recognized x402 direct SPL transfer on an agent's ATA.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface X402DirectPayment {
+    /** Transaction signature. */
+    readonly signature: string;
+    /** Transfer amount (in smallest token unit). */
+    readonly amount: bigint;
+    /** Source ATA (payer). */
+    readonly payerAta: PublicKey;
+    /** Destination ATA (payTo / agent). */
+    readonly payeeAta: PublicKey;
+    /** Token mint used for transfer. */
+    readonly mint: PublicKey;
+    /** Memo data (if a Memo instruction was included). */
+    readonly memo: string | null;
+    /** Matched settlement payload (if server-side verification is available). */
+    readonly settlement: SettlementPayload | null;
+    /** Block time (unix seconds). */
+    readonly blockTime: number | null;
+    /** Slot number. */
+    readonly slot: number;
+}
+/**
+ * @interface GetX402DirectOptions
+ * @description Options for {@link getX402DirectPayments}.
+ * @category Utils
+ * @since v0.6.4
+ */
+export interface GetX402DirectOptions {
+    /** Max signatures to scan (default: 100). */
+    readonly limit?: number;
+    /** Only return transfers from this specific payer. */
+    readonly filterPayer?: PublicKey;
+    /** Known settlements from server-side PAYMENT-RESPONSE logs.
+     *  Used for deterministic hash matching. */
+    readonly knownSettlements?: SettlementPayload[];
+    /** Only include payments that match x402 memo prefix. Default: false. */
+    readonly requireMemo?: boolean;
+    /** Scan before this TX signature (pagination). */
+    readonly before?: string;
+    /** Scan after this TX signature (pagination). */
+    readonly until?: string;
+}
+/**
+ * @name getX402DirectPayments
+ * @description Scan an agent's ATA for x402 direct payments.
+ *
+ * Fetches recent transaction signatures for the given `payTo` ATA,
+ * inspects each transaction for SPL token transfers, and filters
+ * for x402 payment patterns (memo prefix, settlement hash match, etc.).
+ *
+ * @param connection - Solana RPC connection.
+ * @param payToAta   - The agent's receiving ATA (e.g. USDC ATA of Syra).
+ * @param opts       - Filter and pagination options.
+ * @returns Array of recognized x402 direct payments, newest first.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * import { getX402DirectPayments, findATA } from "@oobe-protocol-labs/synapse-sap-sdk";
+ *
+ * const USDC_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+ * const payToAta = findATA(agentWallet, USDC_MINT);
+ *
+ * const payments = await getX402DirectPayments(connection, payToAta, {
+ *   limit: 50,
+ *   knownSettlements: savedSettlements, // from your API PAYMENT-RESPONSE logs
+ * });
+ *
+ * for (const p of payments) {
+ *   console.log(`${p.signature}: ${p.amount} from ${p.payerAta.toBase58()}`);
+ *   if (p.settlement) {
+ *     console.log(`  Matched settlement: ${p.settlement.serviceHash}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function getX402DirectPayments(connection: Connection, payToAta: PublicKey, opts?: GetX402DirectOptions): Promise<X402DirectPayment[]>;
+//# sourceMappingURL=x402-direct.d.ts.map

package/dist/types/utils/x402-direct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-direct.d.ts","sourceRoot":"","sources":["../../../src/utils/x402-direct.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,SAAS,EAGV,MAAM,iBAAiB,CAAC;AAOzB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC9C,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC;gDAC4C;IAC5C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChD,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA6KD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,EACnB,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAmE9B"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.6.3",
-  "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana",
+  "version": "0.8.0",
+  "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana Mainnet/Devnet",
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/constants/seeds.ts

@@ -47,6 +47,7 @@ export const SEEDS = {
   TOOL: "sap_tool",
   CHECKPOINT: "sap_checkpoint",
   ESCROW: "sap_escrow",
+  ESCROW_V2: "sap_escrow_v2",
   STATS: "sap_stats",
   TOOL_CATEGORY: "sap_tool_cat",
   ATTESTATION: "sap_attest",
@@ -54,6 +55,14 @@ export const SEEDS = {
   LEDGER_PAGE: "sap_page",
   BUFFER: "sap_buffer",
   DIGEST: "sap_digest",
+  PENDING: "sap_pending",
+  DISPUTE: "sap_dispute",
+  STAKE: "sap_stake",
+  SUBSCRIPTION: "sap_sub",
+  SHARD: "sap_shard",
+  INDEX_PAGE: "sap_idx_page",
+  /** @since v0.7.0 — Receipt batch merkle root PDA */
+  RECEIPT: "sap_receipt",
 } as const;
 
 /**

package/src/core/client.ts

@@ -33,6 +33,10 @@ import { IndexingModule } from "../modules/indexing";
 import { ToolsModule } from "../modules/tools";
 import { VaultModule } from "../modules/vault";
 import { EscrowModule } from "../modules/escrow";
+import { EscrowV2Module } from "../modules/escrow-v2";
+import { ReceiptModule } from "../modules/receipt";
+import { StakingModule } from "../modules/staking";
+import { SubscriptionModule } from "../modules/subscription";
 import { AttestationModule } from "../modules/attestation";
 import { LedgerModule } from "../modules/ledger";
 import { EventParser } from "../events";
@@ -113,6 +117,10 @@ export class SapClient {
   #tools?: ToolsModule;
   #vault?: VaultModule;
   #escrow?: EscrowModule;
+  #escrowV2?: EscrowV2Module;
+  #receipt?: ReceiptModule;
+  #staking?: StakingModule;
+  #subscription?: SubscriptionModule;
   #attestation?: AttestationModule;
   #ledger?: LedgerModule;
   #events?: EventParser;
@@ -284,6 +292,57 @@ export class SapClient {
     return (this.#escrow ??= new EscrowModule(this.program));
   }
 
+  /**
+   * @name escrowV2
+   * @description V2 escrow settlement with dispute windows, co-signing,
+   * pending settlements, and migration from V1.
+   * @returns {EscrowV2Module} The lazily-instantiated `EscrowV2Module` singleton.
+   * @category Modules
+   * @since v0.7.0
+   * @see {@link EscrowV2Module}
+   */
+  get escrowV2(): EscrowV2Module {
+    return (this.#escrowV2 ??= new EscrowV2Module(this.program));
+  }
+
+  /**
+   * @name receipt
+   * @description Receipt batch inscriptions and automatic dispute resolution (v0.7).
+   * @returns {ReceiptModule} The lazily-instantiated `ReceiptModule` singleton.
+   * @category Modules
+   * @since v0.7.0
+   * @see {@link ReceiptModule}
+   */
+  get receipt(): ReceiptModule {
+    return (this.#receipt ??= new ReceiptModule(this.program));
+  }
+
+  /**
+   * @name staking
+   * @description Agent staking: init stake, deposit, request unstake,
+   * and complete unstake.
+   * @returns {StakingModule} The lazily-instantiated `StakingModule` singleton.
+   * @category Modules
+   * @since v0.7.0
+   * @see {@link StakingModule}
+   */
+  get staking(): StakingModule {
+    return (this.#staking ??= new StakingModule(this.program));
+  }
+
+  /**
+   * @name subscription
+   * @description Recurring subscriptions: create, fund, cancel, and close
+   * subscriber-agent subscription accounts.
+   * @returns {SubscriptionModule} The lazily-instantiated `SubscriptionModule` singleton.
+   * @category Modules
+   * @since v0.7.0
+   * @see {@link SubscriptionModule}
+   */
+  get subscription(): SubscriptionModule {
+    return (this.#subscription ??= new SubscriptionModule(this.program));
+  }
+
   /**
    * @name attestation
    * @description Web of trust: create, revoke, and close on-chain