@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/src/modules/attestation.ts

@@ -0,0 +1,168 @@
+/**
+ * @module attestation
+ * @description Web-of-trust attestations — create, revoke, and close
+ *   on-chain attestations that vouch for agent trustworthiness.
+ *
+ * Attestations are signed endorsements from one wallet to an agent,
+ * forming a composable trust graph on Solana.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+import { SystemProgram, type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveAttestation, deriveGlobalRegistry } from "../pda";
+import type { AgentAttestationData, CreateAttestationArgs } from "../types";
+
+/**
+ * @name AttestationModule
+ * @description Manages on-chain attestations for the Solana Agent Protocol.
+ *   Provides methods to create, revoke, close, and fetch attestation PDAs
+ *   that form the web-of-trust layer.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Create an attestation for an agent
+ * const sig = await sap.attestation.create(agentWallet, {
+ *   attestationType: { identity: {} },
+ *   metadataHash: [...],
+ *   expiresAt: null,
+ * });
+ * ```
+ */
+export class AttestationModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  /**
+   * @name deriveAttestation
+   * @description Derive the `AgentAttestation` PDA for a given agent and attester.
+   * @param agentPda - The agent account PDA to attest.
+   * @param attester - The attester wallet. Defaults to the connected wallet.
+   * @returns A tuple of `[PublicKey, bump]` for the attestation PDA.
+   * @see {@link deriveAttestation} from `pda/` module for the underlying derivation.
+   * @since v0.1.0
+   */
+  deriveAttestation(
+    agentPda: PublicKey,
+    attester?: PublicKey,
+  ): readonly [PublicKey, number] {
+    return deriveAttestation(agentPda, attester ?? this.walletPubkey);
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  /**
+   * @name create
+   * @description Create an on-chain attestation vouching for an agent.
+   *   The connected wallet becomes the attester.
+   * @param agentWallet - The wallet that owns the target agent.
+   * @param args - Attestation parameters (type, metadata hash, optional expiry).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async create(
+    agentWallet: PublicKey,
+    args: CreateAttestationArgs,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [attestPda] = this.deriveAttestation(agentPda);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .createAttestation(args.attestationType, args.metadataHash, args.expiresAt)
+      .accounts({
+        attester: this.walletPubkey,
+        agent: agentPda,
+        attestation: attestPda,
+        globalRegistry: globalPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name revoke
+   * @description Revoke a previously issued attestation. Only the original
+   *   attester may revoke.
+   * @param agentWallet - The wallet of the attested agent.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async revoke(agentWallet: PublicKey): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [attestPda] = this.deriveAttestation(agentPda);
+
+    return this.methods
+      .revokeAttestation()
+      .accounts({
+        attester: this.walletPubkey,
+        attestation: attestPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name close
+   * @description Close a revoked attestation PDA and reclaim rent to the attester.
+   * @param agentWallet - The wallet of the attested agent.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async close(agentWallet: PublicKey): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [attestPda] = this.deriveAttestation(agentPda);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .closeAttestation()
+      .accounts({
+        attester: this.walletPubkey,
+        attestation: attestPda,
+        globalRegistry: globalPda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  /**
+   * @name fetch
+   * @description Fetch a deserialized `AgentAttestation` account.
+   * @param agentPda - The agent account PDA.
+   * @param attester - The attester wallet. Defaults to the connected wallet.
+   * @returns {Promise<AgentAttestationData>} The attestation account data.
+   * @throws Will throw if the attestation account does not exist.
+   * @since v0.1.0
+   */
+  async fetch(
+    agentPda: PublicKey,
+    attester?: PublicKey,
+  ): Promise<AgentAttestationData> {
+    const [pda] = this.deriveAttestation(agentPda, attester);
+    return this.fetchAccount<AgentAttestationData>("agentAttestation", pda);
+  }
+
+  /**
+   * @name fetchNullable
+   * @description Fetch a deserialized `AgentAttestation` account, or `null`
+   *   if it does not exist on-chain.
+   * @param agentPda - The agent account PDA.
+   * @param attester - The attester wallet. Defaults to the connected wallet.
+   * @returns {Promise<AgentAttestationData | null>} The attestation data or `null`.
+   * @since v0.1.0
+   */
+  async fetchNullable(
+    agentPda: PublicKey,
+    attester?: PublicKey,
+  ): Promise<AgentAttestationData | null> {
+    const [pda] = this.deriveAttestation(agentPda, attester);
+    return this.fetchAccountNullable<AgentAttestationData>("agentAttestation", pda);
+  }
+}

package/src/modules/base.ts

@@ -0,0 +1,158 @@
+/**
+ * @module base
+ * @description Abstract base class for all SDK modules.
+ *
+ * Provides shared access to the Anchor program, provider,
+ * and typed `fetch` / `fetchNullable` helpers.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+import { type AnchorProvider, type Program, BN } from "@coral-xyz/anchor";
+import type { PublicKey, TransactionSignature } from "@solana/web3.js";
+
+/**
+ * Anchor `Program` instance typed for the Synapse Agent SAP IDL.
+ *
+ * @name SapProgram
+ * @description Alias for `Program<any>` — the Anchor program reference
+ *   used as the backbone of every module in the SDK.
+ * @category Modules
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type SapProgram = Program<any>;
+
+/**
+ * @name SapTransactionResult
+ * @description Instruction builder return type — a ready-to-send transaction.
+ * Contains the finalized transaction signature after RPC submission.
+ * @category Modules
+ * @since v0.1.0
+ */
+export interface SapTransactionResult {
+  /** The base-58 encoded transaction signature returned by the RPC node. */
+  readonly signature: TransactionSignature;
+}
+
+/**
+ * @name BaseModule
+ * @description Abstract base module inherited by every domain module in the SDK.
+ * Encapsulates the Anchor program reference, provider access, and common
+ * helpers for account fetching and BN construction.
+ *
+ * @abstract
+ * @category Modules
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * class MyModule extends BaseModule {
+ *   async doSomething() {
+ *     const data = await this.fetchAccount<MyData>("myAccount", pda);
+ *   }
+ * }
+ * ```
+ */
+export abstract class BaseModule {
+  /**
+   * Create a new module instance.
+   *
+   * @param program - The Anchor `Program` instance for the SAP IDL.
+   * @protected
+   */
+  constructor(protected readonly program: SapProgram) {}
+
+  /**
+   * @name methods
+   * @description Instruction method namespace — bypasses `noUncheckedIndexedAccess`
+   *   on `Program<any>` where every property is `T | undefined`.
+   *   Used internally by subclasses to build and send instructions.
+   * @returns The Anchor program `methods` object for chaining instruction builders.
+   * @protected
+   * @since v0.1.0
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  protected get methods(): any {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return this.program.methods;
+  }
+
+  /**
+   * @name provider
+   * @description The AnchorProvider from the program, giving access to
+   *   the connection and wallet for signing transactions.
+   * @returns {AnchorProvider} The Anchor provider instance.
+   * @protected
+   * @since v0.1.0
+   */
+  protected get provider(): AnchorProvider {
+    return this.program.provider as AnchorProvider;
+  }
+
+  /**
+   * @name walletPubkey
+   * @description Convenience accessor for the signer wallet's public key.
+   * @returns {PublicKey} The public key of the connected wallet.
+   * @protected
+   * @since v0.1.0
+   */
+  protected get walletPubkey(): PublicKey {
+    return this.provider.wallet.publicKey;
+  }
+
+  /**
+   * @name fetchAccount
+   * @description Generic account fetch — deserializes the on-chain account
+   *   data into the given type `T`, or throws if the account does not exist.
+   * @typeParam T - The expected deserialized account data type.
+   * @param accountName - The Anchor account discriminator name (e.g. `"agentAccount"`).
+   * @param address - The public key of the account to fetch.
+   * @returns {Promise<T>} The deserialized account data.
+   * @throws Will throw if the account does not exist on-chain.
+   * @protected
+   * @since v0.1.0
+   */
+  protected async fetchAccount<T>(
+    accountName: string,
+    address: PublicKey,
+  ): Promise<T> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    return (this.program.account as any)[accountName].fetch(address) as Promise<T>;
+  }
+
+  /**
+   * @name fetchAccountNullable
+   * @description Generic nullable account fetch — deserializes the on-chain
+   *   account data into type `T`, or returns `null` if the account does not exist.
+   * @typeParam T - The expected deserialized account data type.
+   * @param accountName - The Anchor account discriminator name (e.g. `"agentAccount"`).
+   * @param address - The public key of the account to fetch.
+   * @returns {Promise<T | null>} The deserialized account data, or `null`.
+   * @protected
+   * @since v0.1.0
+   */
+  protected async fetchAccountNullable<T>(
+    accountName: string,
+    address: PublicKey,
+  ): Promise<T | null> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    return (this.program.account as any)[accountName].fetchNullable(address) as Promise<T | null>;
+  }
+
+  /**
+   * @name bn
+   * @description Create an Anchor `BN` from a number, bigint, or existing BN.
+   *   Passes through values that are already `BN` instances.
+   * @param value - The numeric value to convert.
+   * @returns {BN} An Anchor-compatible big number.
+   * @protected
+   * @since v0.1.0
+   */
+  protected bn(value: number | bigint | BN): BN {
+    if (BN.isBN(value)) return value;
+    return new BN(value.toString());
+  }
+}

package/src/modules/escrow.ts

@@ -0,0 +1,308 @@
+/**
+ * @module escrow
+ * @description x402 escrow settlement layer — create, deposit,
+ * settle, withdraw, batch settle, and close escrow accounts.
+ *
+ * Supports both SOL and SPL token escrows. SPL operations require
+ * passing additional `AccountMeta[]` via the `splAccounts` parameter.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+import {
+  SystemProgram,
+  type PublicKey,
+  type TransactionSignature,
+  type AccountMeta,
+} from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import {
+  deriveAgent,
+  deriveAgentStats,
+  deriveEscrow,
+} from "../pda";
+import type {
+  EscrowAccountData,
+  CreateEscrowArgs,
+  Settlement,
+} from "../types";
+
+/**
+ * @name EscrowModule
+ * @description Manages x402-compatible escrow accounts for agent micropayments.
+ *   Provides methods to create, fund, settle, withdraw, batch-settle, close,
+ *   and fetch escrow PDAs on the Solana Agent Protocol.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Create a SOL escrow for an agent
+ * const sig = await sap.escrow.create(agentWallet, {
+ *   pricePerCall: new BN(1_000_000),
+ *   maxCalls: new BN(100),
+ *   initialDeposit: new BN(100_000_000),
+ *   expiresAt: null,
+ *   volumeCurve: null,
+ *   tokenMint: null,
+ *   tokenDecimals: null,
+ * });
+ * ```
+ */
+export class EscrowModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  /**
+   * @name deriveEscrow
+   * @description Derive the `EscrowAccount` PDA for a given agent and depositor.
+   * @param agentPda - The agent account PDA.
+   * @param depositor - The depositor wallet. Defaults to the connected wallet.
+   * @returns A tuple of `[PublicKey, bump]` for the escrow PDA.
+   * @see {@link deriveEscrow} from `pda/` module for the underlying derivation.
+   * @since v0.1.0
+   */
+  deriveEscrow(
+    agentPda: PublicKey,
+    depositor?: PublicKey,
+  ): readonly [PublicKey, number] {
+    return deriveEscrow(agentPda, depositor ?? this.walletPubkey);
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  /**
+   * @name create
+   * @description Create a new escrow for agent micropayments.
+   *
+   *   For **SOL escrow**: pass `tokenMint: null` and leave `splAccounts` empty.
+   *   For **SPL escrow**: pass `tokenMint`, `tokenDecimals`, and provide
+   *   `splAccounts` with `[depositorAta, escrowAta, tokenMint, tokenProgram]`.
+   *
+   * @param agentWallet - The wallet of the agent to pay.
+   * @param args - Escrow creation parameters (price, max calls, deposit, expiry, volume curve, token info).
+   * @param splAccounts - Remaining accounts for SPL token transfers:
+   *   `[depositorAta, escrowAta, tokenMint, tokenProgram]`. Defaults to `[]`.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async create(
+    agentWallet: PublicKey,
+    args: CreateEscrowArgs,
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda);
+    const [statsPda] = deriveAgentStats(agentPda);
+
+    return this.methods
+      .createEscrow(
+        args.pricePerCall,
+        args.maxCalls,
+        args.initialDeposit,
+        args.expiresAt,
+        args.volumeCurve,
+        args.tokenMint,
+        args.tokenDecimals,
+      )
+      .accounts({
+        depositor: this.walletPubkey,
+        agent: agentPda,
+        agentStats: statsPda,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  /**
+   * @name deposit
+   * @description Deposit additional funds into an existing escrow.
+   * @param agentWallet - The wallet of the agent associated with the escrow.
+   * @param amount - The amount to deposit (lamports for SOL, smallest unit for SPL).
+   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async deposit(
+    agentWallet: PublicKey,
+    amount: BN | number | bigint,
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda);
+
+    return this.methods
+      .depositEscrow(this.bn(amount))
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  /**
+   * @name settle
+   * @description Agent settles calls — claims earned funds from the escrow.
+   *   Must be called by the agent owner wallet.
+   * @param depositorWallet - The wallet of the client who funded the escrow.
+   * @param callsToSettle - Number of calls to settle payment for.
+   * @param serviceHash - A 32-byte SHA-256 hash identifying the service rendered.
+   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async settle(
+    depositorWallet: PublicKey,
+    callsToSettle: BN | number | bigint,
+    serviceHash: number[],
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
+    const [statsPda] = deriveAgentStats(agentPda);
+
+    return this.methods
+      .settleCalls(this.bn(callsToSettle), serviceHash)
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        agentStats: statsPda,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  /**
+   * @name withdraw
+   * @description Client withdraws un-settled funds from their escrow.
+   * @param agentWallet - The wallet of the agent associated with the escrow.
+   * @param amount - The amount to withdraw (lamports for SOL, smallest unit for SPL).
+   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async withdraw(
+    agentWallet: PublicKey,
+    amount: BN | number | bigint,
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda);
+
+    return this.methods
+      .withdrawEscrow(this.bn(amount))
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  /**
+   * @name close
+   * @description Close an empty escrow PDA (balance must be 0) and reclaim rent.
+   * @param agentWallet - The wallet of the agent associated with the escrow.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async close(agentWallet: PublicKey): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [escrowPda] = this.deriveEscrow(agentPda);
+
+    return this.methods
+      .closeEscrow()
+      .accounts({
+        depositor: this.walletPubkey,
+        escrow: escrowPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name settleBatch
+   * @description Batch settlement — process up to 10 settlements in a single
+   *   transaction. Must be called by the agent owner wallet.
+   * @param depositorWallet - The wallet of the client who funded the escrow.
+   * @param settlements - Array of settlement entries (up to 10).
+   * @param splAccounts - Remaining accounts for SPL token transfers. Defaults to `[]`.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async settleBatch(
+    depositorWallet: PublicKey,
+    settlements: Settlement[],
+    splAccounts: AccountMeta[] = [],
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
+    const [statsPda] = deriveAgentStats(agentPda);
+
+    return this.methods
+      .settleBatch(settlements)
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        agentStats: statsPda,
+        escrow: escrowPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .remainingAccounts(splAccounts)
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  /**
+   * @name fetch
+   * @description Fetch a deserialized `EscrowAccount`.
+   * @param agentPda - The agent account PDA.
+   * @param depositor - The depositor wallet. Defaults to the connected wallet.
+   * @returns {Promise<EscrowAccountData>} The escrow account data.
+   * @throws Will throw if the escrow account does not exist.
+   * @since v0.1.0
+   */
+  async fetch(agentPda: PublicKey, depositor?: PublicKey): Promise<EscrowAccountData> {
+    const [pda] = this.deriveEscrow(agentPda, depositor);
+    return this.fetchAccount<EscrowAccountData>("escrowAccount", pda);
+  }
+
+  /**
+   * @name fetchNullable
+   * @description Fetch a deserialized `EscrowAccount`, or `null` if it
+   *   does not exist on-chain.
+   * @param agentPda - The agent account PDA.
+   * @param depositor - The depositor wallet. Defaults to the connected wallet.
+   * @returns {Promise<EscrowAccountData | null>} The escrow data or `null`.
+   * @since v0.1.0
+   */
+  async fetchNullable(agentPda: PublicKey, depositor?: PublicKey): Promise<EscrowAccountData | null> {
+    const [pda] = this.deriveEscrow(agentPda, depositor);
+    return this.fetchAccountNullable<EscrowAccountData>("escrowAccount", pda);
+  }
+
+  /**
+   * @name fetchByPda
+   * @description Fetch an escrow account by its PDA address directly,
+   *   bypassing PDA derivation.
+   * @param escrowPda - The escrow PDA public key.
+   * @returns {Promise<EscrowAccountData>} The escrow account data.
+   * @throws Will throw if the escrow account does not exist.
+   * @since v0.1.0
+   */
+  async fetchByPda(escrowPda: PublicKey): Promise<EscrowAccountData> {
+    return this.fetchAccount<EscrowAccountData>("escrowAccount", escrowPda);
+  }
+}