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

package/src/modules/ledger.ts

@@ -0,0 +1,262 @@
+/**
+ * @module ledger
+ * @description Unified on-chain memory — init, write, seal, and close ledger.
+ *
+ * The recommended memory system: fixed-cost PDA with 4 KB ring buffer,
+ * automatic TX log persistence, and rolling merkle proof.
+ * Write cost is TX fee only (~0.000005 SOL). ZERO additional rent.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+import { SystemProgram, type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveLedger, deriveLedgerPage } from "../pda";
+import type { MemoryLedgerData, LedgerPageData } from "../types";
+
+/**
+ * @name LedgerModule
+ * @description Manage on-chain memory ledgers for sessions.
+ * Each session can have one MemoryLedger PDA with a 4KB ring buffer for recent entries.
+ * When the ring buffer fills, it can be sealed into a permanent LedgerPage.
+ * Ledgers are designed for high-frequency writes with minimal cost (~0.000005 SOL per write).
+ * Sealed pages are immutable and stored on-chain (~0.031 SOL per page).
+ */
+/**
+ * @name LedgerModule
+ * @description Manages the unified on-chain memory ledger for the Solana Agent
+ *   Protocol. Provides methods to initialise a ledger with a 4 KB ring buffer,
+ *   write data (TX fee only), seal pages permanently, close ledgers, and
+ *   decode ring buffer contents.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Init ledger, write data, seal
+ * await sap.ledger.init(sessionPda);
+ * await sap.ledger.write(sessionPda, data, contentHash);
+ * await sap.ledger.seal(sessionPda);
+ * ```
+ */
+export class LedgerModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  /**
+   * @name deriveLedger
+   * @description Derive the `MemoryLedger` PDA for a given session.
+   * @param sessionPda - The session ledger PDA.
+   * @returns A tuple of `[PublicKey, bump]` for the ledger PDA.
+   * @see {@link deriveLedger} from `pda/` module for the underlying derivation.
+   * @since v0.1.0
+   */
+  deriveLedger(sessionPda: PublicKey): readonly [PublicKey, number] {
+    return deriveLedger(sessionPda);
+  }
+
+  /**
+   * @name deriveLedgerPage
+   * @description Derive a `LedgerPage` PDA for a given ledger and page index.
+   * @param ledgerPda - The memory ledger PDA.
+   * @param pageIndex - The zero-based page index.
+   * @returns A tuple of `[PublicKey, bump]` for the page PDA.
+   * @see {@link deriveLedgerPage} from `pda/` module for the underlying derivation.
+   * @since v0.1.0
+   */
+  deriveLedgerPage(
+    ledgerPda: PublicKey,
+    pageIndex: number,
+  ): readonly [PublicKey, number] {
+    return deriveLedgerPage(ledgerPda, pageIndex);
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  /**
+   * @name init
+   * @description Create a `MemoryLedger` with a 4 KB ring buffer (~0.032 SOL rent).
+   * @param sessionPda - The session ledger PDA to attach the ledger to.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async init(sessionPda: PublicKey): Promise<TransactionSignature> {
+    const [ledgerPda] = deriveLedger(sessionPda);
+
+    return this.methods
+      .initLedger()
+      .accounts({
+        wallet: this.walletPubkey,
+        session: sessionPda,
+        ledger: ledgerPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name write
+   * @description Write data to the ledger (ring buffer + TX log simultaneously).
+   *   Cost: TX fee only (~0.000005 SOL). ZERO additional rent.
+   * @param sessionPda - The session ledger PDA.
+   * @param data - The data payload to write (Buffer or Uint8Array).
+   * @param contentHash - A 32-byte SHA-256 content hash for verification.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async write(
+    sessionPda: PublicKey,
+    data: Buffer | Uint8Array,
+    contentHash: number[],
+  ): Promise<TransactionSignature> {
+    const [ledgerPda] = deriveLedger(sessionPda);
+
+    return this.methods
+      .writeLedger(Buffer.from(data), contentHash)
+      .accounts({
+        wallet: this.walletPubkey,
+        session: sessionPda,
+        ledger: ledgerPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name seal
+   * @description Seal the ring buffer into a permanent `LedgerPage`.
+   *   Pages are WRITE-ONCE, NEVER-DELETE: ~0.031 SOL per page.
+   *   Automatically fetches the current page index from the ledger.
+   * @param sessionPda - The session ledger PDA.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async seal(sessionPda: PublicKey): Promise<TransactionSignature> {
+    const [ledgerPda] = deriveLedger(sessionPda);
+    // Fetch ledger to get current page index
+    const ledger = await this.fetchLedger(sessionPda);
+    const [pagePda] = deriveLedgerPage(ledgerPda, ledger.numPages);
+
+    return this.methods
+      .sealLedger()
+      .accounts({
+        wallet: this.walletPubkey,
+        session: sessionPda,
+        ledger: ledgerPda,
+        page: pagePda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name close
+   * @description Close a ledger PDA and reclaim ~0.032 SOL rent.
+   * @param sessionPda - The session ledger PDA.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async close(sessionPda: PublicKey): Promise<TransactionSignature> {
+    const [ledgerPda] = deriveLedger(sessionPda);
+
+    return this.methods
+      .closeLedger()
+      .accounts({
+        wallet: this.walletPubkey,
+        session: sessionPda,
+        ledger: ledgerPda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  /**
+   * @name fetchLedger
+   * @description Fetch a deserialized `MemoryLedger` account.
+   * @param sessionPda - The session ledger PDA.
+   * @returns {Promise<MemoryLedgerData>} The memory ledger data.
+   * @throws Will throw if the ledger does not exist.
+   * @since v0.1.0
+   */
+  async fetchLedger(sessionPda: PublicKey): Promise<MemoryLedgerData> {
+    const [pda] = deriveLedger(sessionPda);
+    return this.fetchAccount<MemoryLedgerData>("memoryLedger", pda);
+  }
+
+  /**
+   * @name fetchLedgerNullable
+   * @description Fetch a deserialized `MemoryLedger` account, or `null`
+   *   if it does not exist on-chain.
+   * @param sessionPda - The session ledger PDA.
+   * @returns {Promise<MemoryLedgerData | null>} The ledger data or `null`.
+   * @since v0.1.0
+   */
+  async fetchLedgerNullable(sessionPda: PublicKey): Promise<MemoryLedgerData | null> {
+    const [pda] = deriveLedger(sessionPda);
+    return this.fetchAccountNullable<MemoryLedgerData>("memoryLedger", pda);
+  }
+
+  /**
+   * @name fetchPage
+   * @description Fetch a deserialized sealed `LedgerPage` account.
+   * @param ledgerPda - The memory ledger PDA.
+   * @param pageIndex - The zero-based page index.
+   * @returns {Promise<LedgerPageData>} The ledger page data.
+   * @throws Will throw if the page does not exist.
+   * @since v0.1.0
+   */
+  async fetchPage(
+    ledgerPda: PublicKey,
+    pageIndex: number,
+  ): Promise<LedgerPageData> {
+    const [pda] = deriveLedgerPage(ledgerPda, pageIndex);
+    return this.fetchAccount<LedgerPageData>("ledgerPage", pda);
+  }
+
+  /**
+   * @name fetchPageNullable
+   * @description Fetch a deserialized sealed `LedgerPage` account, or `null`
+   *   if it does not exist on-chain.
+   * @param ledgerPda - The memory ledger PDA.
+   * @param pageIndex - The zero-based page index.
+   * @returns {Promise<LedgerPageData | null>} The page data or `null`.
+   * @since v0.1.0
+   */
+  async fetchPageNullable(
+    ledgerPda: PublicKey,
+    pageIndex: number,
+  ): Promise<LedgerPageData | null> {
+    const [pda] = deriveLedgerPage(ledgerPda, pageIndex);
+    return this.fetchAccountNullable<LedgerPageData>("ledgerPage", pda);
+  }
+
+  /**
+   * @name decodeRingBuffer
+   * @description Decode the ring buffer into individual entries.
+   *   Each entry is stored as `[u16 LE data_len][data bytes]`.
+   *   An entry with `data_len === 0` acts as the empty sentinel.
+   * @param ring - Raw ring buffer data (byte array or Uint8Array).
+   * @returns {Uint8Array[]} Array of decoded data entries.
+   * @since v0.1.0
+   */
+  decodeRingBuffer(ring: number[] | Uint8Array): Uint8Array[] {
+    const buf = Buffer.from(ring);
+    const entries: Uint8Array[] = [];
+    let offset = 0;
+
+    while (offset + 2 <= buf.length) {
+      const len = buf.readUInt16LE(offset);
+      if (len === 0) break; // empty sentinel
+      offset += 2;
+      if (offset + len > buf.length) break;
+      entries.push(new Uint8Array(buf.subarray(offset, offset + len)));
+      offset += len;
+    }
+
+    return entries;
+  }
+}

package/src/modules/tools.ts

@@ -0,0 +1,411 @@
+/**
+ * @module tools
+ * @description Tool schema registry and session checkpoints for the
+ * Solana Agent Protocol.
+ *
+ * Covers: publish, inscribe schema, update, deactivate/reactivate,
+ * close, report invocations, and session checkpoint management.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+
+import { SystemProgram, type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import {
+  deriveAgent,
+  deriveTool,
+  deriveCheckpoint,
+  deriveGlobalRegistry,
+} from "../pda";
+import type {
+  ToolDescriptorData,
+  SessionCheckpointData,
+  PublishToolArgs,
+  UpdateToolArgs,
+  InscribeToolSchemaArgs,
+} from "../types";
+import { sha256, hashToArray } from "../utils";
+
+/**
+ * @name ToolsModule
+ * @description Manages tool descriptors and session checkpoints for the
+ *   Solana Agent Protocol. Provides methods to publish, update, deactivate,
+ *   reactivate, close, and fetch tool descriptors, as well as inscribe
+ *   JSON schemas into TX logs and manage session checkpoints.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Publish a tool by name (auto-hashes)
+ * const sig = await sap.tools.publishByName(
+ *   "getWeather", "mcp-v1", "Fetch weather",
+ *   '{"type":"object"}', '{"type":"object"}',
+ *   0, 1, 2, 1, false,
+ * );
+ * ```
+ */
+export class ToolsModule extends BaseModule {
+  // ── PDA helpers ──────────────────────────────────────
+
+  /**
+   * @name deriveTool
+   * @description Derive the `ToolDescriptor` PDA for a given agent and tool name.
+   *   The tool name is SHA-256 hashed internally.
+   * @param agentPda - The agent account PDA.
+   * @param toolName - The human-readable tool name.
+   * @returns A tuple of `[PublicKey, bump]` for the tool PDA.
+   * @see {@link deriveTool} from `pda/` module for the underlying derivation.
+   * @since v0.1.0
+   */
+  deriveTool(
+    agentPda: PublicKey,
+    toolName: string,
+  ): readonly [PublicKey, number] {
+    return deriveTool(agentPda, sha256(toolName));
+  }
+
+  // ── Instructions ─────────────────────────────────────
+
+  /**
+   * @name publish
+   * @description Publish a new tool descriptor for an agent using pre-computed
+   *   hashes. For auto-hashing, prefer {@link publishByName}.
+   * @param args - Tool publication parameters (name, hashes, HTTP method, category, params, etc.).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async publish(args: PublishToolArgs): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = deriveTool(agentPda, new Uint8Array(args.toolNameHash));
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .publishTool(
+        args.toolName,
+        args.toolNameHash,
+        args.protocolHash,
+        args.descriptionHash,
+        args.inputSchemaHash,
+        args.outputSchemaHash,
+        args.httpMethod,
+        args.category,
+        args.paramsCount,
+        args.requiredParams,
+        args.isCompound,
+      )
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+        globalRegistry: globalPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name publishByName
+   * @description Convenience method to publish a tool using string names.
+   *   All string arguments are automatically SHA-256 hashed.
+   * @param toolName - Human-readable tool name.
+   * @param protocolId - Protocol identifier (e.g. `"mcp-v1"`).
+   * @param description - Tool description text.
+   * @param inputSchema - JSON schema string for input validation.
+   * @param outputSchema - JSON schema string for output validation.
+   * @param httpMethod - Numeric HTTP method enum value.
+   * @param category - Numeric tool category enum value.
+   * @param paramsCount - Total number of parameters.
+   * @param requiredParams - Number of required parameters.
+   * @param isCompound - Whether the tool is a compound (multi-step) tool.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async publishByName(
+    toolName: string,
+    protocolId: string,
+    description: string,
+    inputSchema: string,
+    outputSchema: string,
+    httpMethod: number,
+    category: number,
+    paramsCount: number,
+    requiredParams: number,
+    isCompound: boolean,
+  ): Promise<TransactionSignature> {
+    return this.publish({
+      toolName,
+      toolNameHash: hashToArray(sha256(toolName)),
+      protocolHash: hashToArray(sha256(protocolId)),
+      descriptionHash: hashToArray(sha256(description)),
+      inputSchemaHash: hashToArray(sha256(inputSchema)),
+      outputSchemaHash: hashToArray(sha256(outputSchema)),
+      httpMethod,
+      category,
+      paramsCount,
+      requiredParams,
+      isCompound,
+    });
+  }
+
+  /**
+   * @name inscribeSchema
+   * @description Inscribe a full JSON schema into the transaction log (zero rent).
+   *   The schema is stored as TX log data, not as PDA account data.
+   * @param toolName - The human-readable tool name.
+   * @param args - Schema inscription parameters (type, data, hash, compression).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async inscribeSchema(
+    toolName: string,
+    args: InscribeToolSchemaArgs,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = this.deriveTool(agentPda, toolName);
+
+    return this.methods
+      .inscribeToolSchema(
+        args.schemaType,
+        args.schemaData,
+        args.schemaHash,
+        args.compression,
+      )
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name update
+   * @description Update a tool’s schema hashes and bump its version.
+   *   All fields are optional — only non-null values are written.
+   * @param toolName - The human-readable tool name.
+   * @param args - Partial update parameters (hashes, method, category, params).
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async update(
+    toolName: string,
+    args: UpdateToolArgs,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = this.deriveTool(agentPda, toolName);
+
+    return this.methods
+      .updateTool(
+        args.descriptionHash ?? null,
+        args.inputSchemaHash ?? null,
+        args.outputSchemaHash ?? null,
+        args.httpMethod ?? null,
+        args.category ?? null,
+        args.paramsCount ?? null,
+        args.requiredParams ?? null,
+      )
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name deactivate
+   * @description Deactivate a tool. The tool remains discoverable but is
+   *   marked as unavailable.
+   * @param toolName - The human-readable tool name.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async deactivate(toolName: string): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = this.deriveTool(agentPda, toolName);
+
+    return this.methods
+      .deactivateTool()
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name reactivate
+   * @description Reactivate a previously deactivated tool.
+   * @param toolName - The human-readable tool name.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async reactivate(toolName: string): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = this.deriveTool(agentPda, toolName);
+
+    return this.methods
+      .reactivateTool()
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name close
+   * @description Close a tool PDA and reclaim rent to the owner wallet.
+   * @param toolName - The human-readable tool name.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async close(toolName: string): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = this.deriveTool(agentPda, toolName);
+    const [globalPda] = deriveGlobalRegistry();
+
+    return this.methods
+      .closeTool()
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+        globalRegistry: globalPda,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name reportInvocations
+   * @description Report tool invocation count. Updates the on-chain counter
+   *   for analytics and discovery ranking.
+   * @param toolName - The human-readable tool name.
+   * @param invocations - The number of invocations to report.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async reportInvocations(
+    toolName: string,
+    invocations: number | bigint,
+  ): Promise<TransactionSignature> {
+    const [agentPda] = deriveAgent(this.walletPubkey);
+    const [toolPda] = this.deriveTool(agentPda, toolName);
+
+    return this.methods
+      .reportToolInvocations(this.bn(invocations))
+      .accounts({
+        wallet: this.walletPubkey,
+        agent: agentPda,
+        tool: toolPda,
+      })
+      .rpc();
+  }
+
+  // ── Checkpoints ──────────────────────────────────────
+
+  /**
+   * @name createCheckpoint
+   * @description Create a checkpoint snapshot of the current session state.
+   *   Checkpoints are indexed by session PDA and checkpoint index.
+   * @param sessionPda - The session ledger PDA.
+   * @param checkpointIndex - The zero-based checkpoint index.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async createCheckpoint(
+    sessionPda: PublicKey,
+    checkpointIndex: number,
+  ): Promise<TransactionSignature> {
+    const [checkpointPda] = deriveCheckpoint(sessionPda, checkpointIndex);
+
+    return this.methods
+      .createSessionCheckpoint(checkpointIndex)
+      .accounts({
+        wallet: this.walletPubkey,
+        session: sessionPda,
+        checkpoint: checkpointPda,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+  }
+
+  /**
+   * @name closeCheckpoint
+   * @description Close a checkpoint PDA and reclaim rent.
+   * @param sessionPda - The session ledger PDA.
+   * @param checkpointIndex - The zero-based checkpoint index.
+   * @returns {Promise<TransactionSignature>} The transaction signature.
+   * @since v0.1.0
+   */
+  async closeCheckpoint(
+    sessionPda: PublicKey,
+    checkpointIndex: number,
+  ): Promise<TransactionSignature> {
+    const [checkpointPda] = deriveCheckpoint(sessionPda, checkpointIndex);
+
+    return this.methods
+      .closeCheckpoint(checkpointIndex)
+      .accounts({
+        wallet: this.walletPubkey,
+        session: sessionPda,
+        checkpoint: checkpointPda,
+      })
+      .rpc();
+  }
+
+  // ── Fetchers ─────────────────────────────────────────
+
+  /**
+   * @name fetch
+   * @description Fetch a deserialized `ToolDescriptor` account.
+   * @param agentPda - The agent account PDA.
+   * @param toolName - The human-readable tool name.
+   * @returns {Promise<ToolDescriptorData>} The tool descriptor data.
+   * @throws Will throw if the tool descriptor does not exist.
+   * @since v0.1.0
+   */
+  async fetch(agentPda: PublicKey, toolName: string): Promise<ToolDescriptorData> {
+    const [pda] = this.deriveTool(agentPda, toolName);
+    return this.fetchAccount<ToolDescriptorData>("toolDescriptor", pda);
+  }
+
+  /**
+   * @name fetchNullable
+   * @description Fetch a deserialized `ToolDescriptor` account, or `null`
+   *   if it does not exist on-chain.
+   * @param agentPda - The agent account PDA.
+   * @param toolName - The human-readable tool name.
+   * @returns {Promise<ToolDescriptorData | null>} The tool data or `null`.
+   * @since v0.1.0
+   */
+  async fetchNullable(agentPda: PublicKey, toolName: string): Promise<ToolDescriptorData | null> {
+    const [pda] = this.deriveTool(agentPda, toolName);
+    return this.fetchAccountNullable<ToolDescriptorData>("toolDescriptor", pda);
+  }
+
+  /**
+   * @name fetchCheckpoint
+   * @description Fetch a deserialized `SessionCheckpoint` account by session PDA and index.
+   * @param sessionPda - The session ledger PDA.
+   * @param checkpointIndex - The zero-based checkpoint index.
+   * @returns {Promise<SessionCheckpointData>} The checkpoint data.
+   * @throws Will throw if the checkpoint does not exist.
+   * @since v0.1.0
+   */
+  async fetchCheckpoint(
+    sessionPda: PublicKey,
+    checkpointIndex: number,
+  ): Promise<SessionCheckpointData> {
+    const [pda] = deriveCheckpoint(sessionPda, checkpointIndex);
+    return this.fetchAccount<SessionCheckpointData>("sessionCheckpoint", pda);
+  }
+}