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

package/src/modules/feedback.ts

@@ -0,0 +1,186 @@
+/**
+ * @module feedback
+ * @description Trustless reputation system — give, update, revoke, and close
+ *   on-chain feedback entries for agents.
+ *
+ * Feedback entries are PDA-based reviews tied to an agent and a reviewer wallet,
+ * enabling permissionless, verifiable reputation 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, deriveFeedback, deriveGlobalRegistry } from "../pda";
+import type { FeedbackAccountData, GiveFeedbackArgs, UpdateFeedbackArgs } from "../types";
+
+/**
+ * @name FeedbackModule
+ * @description Manages on-chain feedback entries for the Solana Agent Protocol.
+ *   Provides methods to give, update, revoke, close, and fetch feedback PDAs
+ *   that form the trustless reputation layer.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * const sig = await sap.feedback.give(agentWallet, {
+ *   score: 5,
+ *   tag: { quality: {} },
+ *   commentHash: null,
+ * });
+ * ```
+ */
+export class FeedbackModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  /**
+   * @name deriveFeedback
+   * @description Derive the `FeedbackAccount` PDA for a given agent and reviewer.
+   * @param agentPda - The agent account PDA to review.
+   * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+   * @returns A tuple of `[PublicKey, bump]` for the feedback PDA.
+   * @see {@link deriveFeedback} from `pda/` module for the underlying derivation.
+   * @since v0.1.0
+   */
+  deriveFeedback(
+    agentPda: PublicKey,
+    reviewer?: PublicKey,
+  ): readonly [PublicKey, number] {
+    return deriveFeedback(agentPda, reviewer ?? this.walletPubkey);
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  /**
+   * @name give
+   * @description Leave on-chain feedback for an agent. Creates a new
+   *   `FeedbackAccount` PDA owned by the reviewer.
+   * @param agentWallet - The wallet that owns the target agent.
+   * @param args - Feedback parameters (score, tag, optional comment hash).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async give(
+    agentWallet: PublicKey,
+    args: GiveFeedbackArgs,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [feedbackPda] = this.deriveFeedback(agentPda);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .giveFeedback(args.score, args.tag, args.commentHash ?? null)
+      .accounts({
+        reviewer: this.walletPubkey,
+        agent: agentPda,
+        feedback: feedbackPda,
+        globalRegistry: globalPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name update
+   * @description Update an existing feedback entry. Only the original reviewer
+   *   may update their feedback.
+   * @param agentWallet - The wallet that owns the target agent.
+   * @param args - Updated feedback parameters (new score, optional new tag, optional comment hash).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async update(
+    agentWallet: PublicKey,
+    args: UpdateFeedbackArgs,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [feedbackPda] = this.deriveFeedback(agentPda);
+
+    return this.methods
+      .updateFeedback(args.newScore, args.newTag ?? null, args.commentHash ?? null)
+      .accounts({
+        reviewer: this.walletPubkey,
+        agent: agentPda,
+        feedback: feedbackPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name revoke
+   * @description Revoke a feedback entry, marking it as revoked and excluding
+   *   it from reputation calculations.
+   * @param agentWallet - The wallet that owns the target agent.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async revoke(agentWallet: PublicKey): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [feedbackPda] = this.deriveFeedback(agentPda);
+
+    return this.methods
+      .revokeFeedback()
+      .accounts({
+        reviewer: this.walletPubkey,
+        agent: agentPda,
+        feedback: feedbackPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name close
+   * @description Close a revoked feedback PDA and reclaim rent to the reviewer.
+   * @param agentWallet - The wallet that owns the target agent.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async close(agentWallet: PublicKey): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(agentWallet);
+    const [feedbackPda] = this.deriveFeedback(agentPda);
+
+    return this.methods
+      .closeFeedback()
+      .accounts({
+        reviewer: this.walletPubkey,
+        feedback: feedbackPda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  /**
+   * @name fetch
+   * @description Fetch a deserialized `FeedbackAccount`.
+   * @param agentPda - The agent account PDA.
+   * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+   * @returns {Promise<FeedbackAccountData>} The feedback account data.
+   * @throws Will throw if the feedback account does not exist.
+   * @since v0.1.0
+   */
+  async fetch(agentPda: PublicKey, reviewer?: PublicKey): Promise<FeedbackAccountData> {
+    const [pda] = this.deriveFeedback(agentPda, reviewer);
+    return this.fetchAccount<FeedbackAccountData>("feedbackAccount", pda);
+  }
+
+  /**
+   * @name fetchNullable
+   * @description Fetch a deserialized `FeedbackAccount`, or `null` if it
+   *   does not exist on-chain.
+   * @param agentPda - The agent account PDA.
+   * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+   * @returns {Promise<FeedbackAccountData | null>} The feedback data or `null`.
+   * @since v0.1.0
+   */
+  async fetchNullable(agentPda: PublicKey, reviewer?: PublicKey): Promise<FeedbackAccountData | null> {
+    const [pda] = this.deriveFeedback(agentPda, reviewer);
+    return this.fetchAccountNullable<FeedbackAccountData>("feedbackAccount", pda);
+  }
+}

package/src/modules/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @module modules
+ * @description Barrel export for all domain modules of the `@synapse-sap/sdk`.
+ *
+ * Re-exports every module class so consumers can import from a single entry point:
+ * ```ts
+ * import { AgentModule, VaultModule } from "@synapse-sap/sdk/modules";
+ * ```
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+export { AgentModule } from "./agent";
+export { FeedbackModule } from "./feedback";
+export { IndexingModule } from "./indexing";
+export { ToolsModule } from "./tools";
+export { VaultModule } from "./vault";
+export { EscrowModule } from "./escrow";
+export { AttestationModule } from "./attestation";
+export { LedgerModule } from "./ledger";
+export { BaseModule } from "./base";
+export type { SapProgram, SapTransactionResult } from "./base";

package/src/modules/indexing.ts

@@ -0,0 +1,444 @@
+/**
+ * @module indexing
+ * @description Scalable discovery layer — capability indexes, protocol indexes,
+ * and tool category indexes for the Solana Agent Protocol.
+ *
+ * Indexes are shared PDA-based registries that map agents and tools to
+ * discovery dimensions, enabling efficient on-chain lookups.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+import { SystemProgram, type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import {
+  deriveAgent,
+  deriveCapabilityIndex,
+  deriveProtocolIndex,
+  deriveToolCategoryIndex,
+  deriveGlobalRegistry,
+} from "../pda";
+import type {
+  CapabilityIndexData,
+  ProtocolIndexData,
+  ToolCategoryIndexData,
+} from "../types";
+import { sha256, hashToArray } from "../utils";
+
+/**
+ * @name IndexingModule
+ * @description Manages on-chain discovery indexes for the Solana Agent Protocol.
+ *   Provides methods to create, populate, prune, close, and fetch capability
+ *   indexes, protocol indexes, and tool category indexes.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Create a capability index and add your agent
+ * await sap.indexing.initCapabilityIndex("text-generation");
+ * // Query agents by capability
+ * const idx = await sap.indexing.fetchCapabilityIndex("text-generation");
+ * ```
+ */
+export class IndexingModule extends BaseModule {
+  // ── Helpers ──────────────────────────────────────────
+
+  /**
+   * @name hash
+   * @description Hash a capability or protocol ID string for use as a PDA seed.
+   *   Uses SHA-256 internally.
+   * @param id - The capability or protocol identifier string.
+   * @returns {Uint8Array} The 32-byte SHA-256 hash.
+   * @since v0.1.0
+   */
+  hash(id: string): Uint8Array {
+    return sha256(id);
+  }
+
+  // ── Capability Index ─────────────────────────────────
+
+  /**
+   * @name initCapabilityIndex
+   * @description Create a new capability index and register the caller’s agent.
+   *   The capability ID is hashed to derive the PDA.
+   * @param capabilityId - Human-readable capability identifier (e.g. `"text-generation"`).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async initCapabilityIndex(
+    capabilityId: string,
+  ): Promise<TransactionSignature> {
+    const capHash = this.hash(capabilityId);
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [capIdxPda] = deriveCapabilityIndex(capHash);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .initCapabilityIndex(capabilityId, hashToArray(capHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        capabilityIndex: capIdxPda,
+        globalRegistry: globalPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name addToCapabilityIndex
+   * @description Add the caller’s agent to an existing capability index.
+   * @param capabilityId - The capability identifier string.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async addToCapabilityIndex(
+    capabilityId: string,
+  ): Promise<TransactionSignature> {
+    const capHash = this.hash(capabilityId);
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [capIdxPda] = deriveCapabilityIndex(capHash);
+
+    return this.methods
+      .addToCapabilityIndex(hashToArray(capHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        capabilityIndex: capIdxPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name removeFromCapabilityIndex
+   * @description Remove the caller’s agent from a capability index.
+   * @param capabilityId - The capability identifier string.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async removeFromCapabilityIndex(
+    capabilityId: string,
+  ): Promise<TransactionSignature> {
+    const capHash = this.hash(capabilityId);
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [capIdxPda] = deriveCapabilityIndex(capHash);
+
+    return this.methods
+      .removeFromCapabilityIndex(hashToArray(capHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        capabilityIndex: capIdxPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name closeCapabilityIndex
+   * @description Close an empty capability index PDA and reclaim rent.
+   * @param capabilityId - The capability identifier string.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async closeCapabilityIndex(
+    capabilityId: string,
+  ): Promise<TransactionSignature> {
+    const capHash = this.hash(capabilityId);
+    const [capIdxPda] = deriveCapabilityIndex(capHash);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .closeCapabilityIndex(hashToArray(capHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        capabilityIndex: capIdxPda,
+        globalRegistry: globalPda,
+      })
+      .rpc();
+  }
+
+  // ── Protocol Index ───────────────────────────────────
+
+  /**
+   * @name initProtocolIndex
+   * @description Create a new protocol index and register the caller’s agent.
+   *   The protocol ID is hashed to derive the PDA.
+   * @param protocolId - Human-readable protocol identifier (e.g. `"mcp-v1"`).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async initProtocolIndex(
+    protocolId: string,
+  ): Promise<TransactionSignature> {
+    const protoHash = this.hash(protocolId);
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [protoIdxPda] = deriveProtocolIndex(protoHash);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .initProtocolIndex(protocolId, hashToArray(protoHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        protocolIndex: protoIdxPda,
+        globalRegistry: globalPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name addToProtocolIndex
+   * @description Add the caller’s agent to an existing protocol index.
+   * @param protocolId - The protocol identifier string.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async addToProtocolIndex(
+    protocolId: string,
+  ): Promise<TransactionSignature> {
+    const protoHash = this.hash(protocolId);
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [protoIdxPda] = deriveProtocolIndex(protoHash);
+
+    return this.methods
+      .addToProtocolIndex(hashToArray(protoHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        protocolIndex: protoIdxPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name removeFromProtocolIndex
+   * @description Remove the caller’s agent from a protocol index.
+   * @param protocolId - The protocol identifier string.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async removeFromProtocolIndex(
+    protocolId: string,
+  ): Promise<TransactionSignature> {
+    const protoHash = this.hash(protocolId);
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [protoIdxPda] = deriveProtocolIndex(protoHash);
+
+    return this.methods
+      .removeFromProtocolIndex(hashToArray(protoHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        protocolIndex: protoIdxPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name closeProtocolIndex
+   * @description Close an empty protocol index PDA and reclaim rent.
+   * @param protocolId - The protocol identifier string.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async closeProtocolIndex(
+    protocolId: string,
+  ): Promise<TransactionSignature> {
+    const protoHash = this.hash(protocolId);
+    const [protoIdxPda] = deriveProtocolIndex(protoHash);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .closeProtocolIndex(hashToArray(protoHash))
+      .accounts({
+        wallet: this.walletPubkey,
+        protocolIndex: protoIdxPda,
+        globalRegistry: globalPda,
+      })
+      .rpc();
+  }
+
+  // ── Tool Category Index ──────────────────────────────
+
+  /**
+   * @name initToolCategoryIndex
+   * @description Create a new tool category index PDA.
+   * @param category - Numeric tool category enum value.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async initToolCategoryIndex(
+    category: number,
+  ): Promise<TransactionSignature> {
+    const [catIdxPda] = deriveToolCategoryIndex(category);
+
+    return this.methods
+      .initToolCategoryIndex(category)
+      .accounts({
+        wallet: this.walletPubkey,
+        toolCategoryIndex: catIdxPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name addToToolCategory
+   * @description Add a tool to its matching category index.
+   * @param category - Numeric tool category enum value.
+   * @param toolPda - The tool descriptor PDA to add.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async addToToolCategory(
+    category: number,
+    toolPda: PublicKey,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [catIdxPda] = deriveToolCategoryIndex(category);
+
+    return this.methods
+      .addToToolCategory(category)
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+        toolCategoryIndex: catIdxPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name removeFromToolCategory
+   * @description Remove a tool from a category index.
+   * @param category - Numeric tool category enum value.
+   * @param toolPda - The tool descriptor PDA to remove.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async removeFromToolCategory(
+    category: number,
+    toolPda: PublicKey,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [catIdxPda] = deriveToolCategoryIndex(category);
+
+    return this.methods
+      .removeFromToolCategory(category)
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+        toolCategoryIndex: catIdxPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name closeToolCategoryIndex
+   * @description Close an empty tool category index PDA and reclaim rent.
+   * @param category - Numeric tool category enum value.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async closeToolCategoryIndex(
+    category: number,
+  ): Promise<TransactionSignature> {
+    const [catIdxPda] = deriveToolCategoryIndex(category);
+
+    return this.methods
+      .closeToolCategoryIndex(category)
+      .accounts({
+        wallet: this.walletPubkey,
+        toolCategoryIndex: catIdxPda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  /**
+   * @name fetchCapabilityIndex
+   * @description Fetch a deserialized `CapabilityIndex` account by capability ID.
+   * @param capabilityId - The capability identifier string.
+   * @returns {Promise<CapabilityIndexData>} The capability index data.
+   * @throws Will throw if the capability index does not exist.
+   * @since v0.1.0
+   */
+  async fetchCapabilityIndex(capabilityId: string): Promise<CapabilityIndexData> {
+    const [pda] = deriveCapabilityIndex(this.hash(capabilityId));
+    return this.fetchAccount<CapabilityIndexData>("capabilityIndex", pda);
+  }
+
+  /**
+   * @name fetchCapabilityIndexNullable
+   * @description Fetch a deserialized `CapabilityIndex` account, or `null`
+   *   if it does not exist on-chain.
+   * @param capabilityId - The capability identifier string.
+   * @returns {Promise<CapabilityIndexData | null>} The capability index data or `null`.
+   * @since v0.1.0
+   */
+  async fetchCapabilityIndexNullable(capabilityId: string): Promise<CapabilityIndexData | null> {
+    const [pda] = deriveCapabilityIndex(this.hash(capabilityId));
+    return this.fetchAccountNullable<CapabilityIndexData>("capabilityIndex", pda);
+  }
+
+  /**
+   * @name fetchProtocolIndex
+   * @description Fetch a deserialized `ProtocolIndex` account by protocol ID.
+   * @param protocolId - The protocol identifier string.
+   * @returns {Promise<ProtocolIndexData>} The protocol index data.
+   * @throws Will throw if the protocol index does not exist.
+   * @since v0.1.0
+   */
+  async fetchProtocolIndex(protocolId: string): Promise<ProtocolIndexData> {
+    const [pda] = deriveProtocolIndex(this.hash(protocolId));
+    return this.fetchAccount<ProtocolIndexData>("protocolIndex", pda);
+  }
+
+  /**
+   * @name fetchProtocolIndexNullable
+   * @description Fetch a deserialized `ProtocolIndex` account, or `null`
+   *   if it does not exist on-chain.
+   * @param protocolId - The protocol identifier string.
+   * @returns {Promise<ProtocolIndexData | null>} The protocol index data or `null`.
+   * @since v0.1.0
+   */
+  async fetchProtocolIndexNullable(protocolId: string): Promise<ProtocolIndexData | null> {
+    const [pda] = deriveProtocolIndex(this.hash(protocolId));
+    return this.fetchAccountNullable<ProtocolIndexData>("protocolIndex", pda);
+  }
+
+  /**
+   * @name fetchToolCategoryIndex
+   * @description Fetch a deserialized `ToolCategoryIndex` account by category number.
+   * @param category - Numeric tool category enum value.
+   * @returns {Promise<ToolCategoryIndexData>} The tool category index data.
+   * @throws Will throw if the tool category index does not exist.
+   * @since v0.1.0
+   */
+  async fetchToolCategoryIndex(category: number): Promise<ToolCategoryIndexData> {
+    const [pda] = deriveToolCategoryIndex(category);
+    return this.fetchAccount<ToolCategoryIndexData>("toolCategoryIndex", pda);
+  }
+
+  /**
+   * @name fetchToolCategoryIndexNullable
+   * @description Fetch a deserialized `ToolCategoryIndex` account, or `null`
+   *   if it does not exist on-chain.
+   * @param category - Numeric tool category enum value.
+   * @returns {Promise<ToolCategoryIndexData | null>} The tool category index data or `null`.
+   * @since v0.1.0
+   */
+  async fetchToolCategoryIndexNullable(category: number): Promise<ToolCategoryIndexData | null> {
+    const [pda] = deriveToolCategoryIndex(category);
+    return this.fetchAccountNullable<ToolCategoryIndexData>("toolCategoryIndex", pda);
+  }
+}