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

package/src/modules/staking.ts

@@ -0,0 +1,122 @@
+/**
+ * @module staking
+ * @description Agent staking lifecycle — init, deposit, request unstake,
+ * complete unstake, and fetch stake 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, deriveStake } from "../pda";
+import type { AgentStakeData } from "../types";
+
+/**
+ * @name StakingModule
+ * @description Manages agent stake accounts — init, deposit, unstake, and fetch.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export class StakingModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  deriveStake(agentPda: PublicKey): readonly [PublicKey, number] {
+    return deriveStake(agentPda);
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  async initStake(
+    agentWallet: PublicKey,
+    initialDeposit: BN | number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [stakePda] = this.deriveStake(agentPda);
+
+    return this.methods
+      .initStake(this.bn(initialDeposit))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        stake: stakePda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  async deposit(
+    agentWallet: PublicKey,
+    amount: BN | number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [stakePda] = this.deriveStake(agentPda);
+
+    return this.methods
+      .depositStake(this.bn(amount))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        stake: stakePda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  async requestUnstake(
+    agentWallet: PublicKey,
+    amount: BN | number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [stakePda] = this.deriveStake(agentPda);
+
+    return this.methods
+      .requestUnstake(this.bn(amount))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        stake: stakePda,
+      })
+      .rpc();
+  }
+
+  async completeUnstake(
+    agentWallet: PublicKey,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [stakePda] = this.deriveStake(agentPda);
+
+    return this.methods
+      .completeUnstake()
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        stake: stakePda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  async fetch(agentPda: PublicKey): Promise<AgentStakeData> {
+    const [pda] = this.deriveStake(agentPda);
+    return this.fetchAccount<AgentStakeData>("agentStake", pda);
+  }
+
+  async fetchNullable(agentPda: PublicKey): Promise<AgentStakeData | null> {
+    const [pda] = this.deriveStake(agentPda);
+    return this.fetchAccountNullable<AgentStakeData>("agentStake", pda);
+  }
+
+  async fetchByPda(stakePda: PublicKey): Promise<AgentStakeData> {
+    return this.fetchAccount<AgentStakeData>("agentStake", stakePda);
+  }
+}

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,214 @@ 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,
+  );
+
+// ═════════════════════════════════════════════
+//  Receipt Batch (v0.7)
+// ═════════════════════════════════════════════
+
+/**
+ * Derive the **ReceiptBatch** PDA.
+ *
+ * Seeds: `["sap_receipt", escrow_v2_pda, batch_index_u32_le]`
+ *
+ * @name deriveReceiptBatch
+ * @description Computes the receipt batch PDA storing a merkle root of call receipts.
+ * @param escrowV2Pda - The parent V2 escrow PDA.
+ * @param batchIndex  - Zero-based batch index (u32).
+ * @param programId   - Override program ID.
+ * @returns {PdaResult} `[pda, bump]` tuple.
+ * @category PDA
+ * @since v0.7.0
+ */
+export const deriveReceiptBatch = (
+  escrowV2Pda: PublicKey,
+  batchIndex: number,
+  programId = SAP_PROGRAM_ID,
+): PdaResult =>
+  findPda(
+    [
+      toSeedBuf(SEEDS.RECEIPT),
+      escrowV2Pda.toBuffer(),
+      u32le(batchIndex),
+    ],
+    programId,
+  );