@oobe-protocol-labs/synapse-sap-sdk 0.12.9 → 0.14.0

package/dist/esm/modules/indexing.js

@@ -1,371 +0,0 @@
-/**
- * @module indexing
- * @description Scalable discovery layer — capability indexes, protocol indexes,
- * and tool category indexes for the Synapse 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 } from "@solana/web3.js";
-import { BaseModule } from "./base";
-import { deriveAgent, deriveCapabilityIndex, deriveProtocolIndex, deriveToolCategoryIndex, deriveGlobalRegistry, } from "../pda";
-import { sha256, hashToArray } from "../utils";
-/**
- * @name IndexingModule
- * @description Manages on-chain discovery indexes for the Synapse 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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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) {
-        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, toolPda) {
-        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, toolPda) {
-        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) {
-        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) {
-        const [pda] = deriveCapabilityIndex(this.hash(capabilityId));
-        return this.fetchAccount("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) {
-        const [pda] = deriveCapabilityIndex(this.hash(capabilityId));
-        return this.fetchAccountNullable("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) {
-        const [pda] = deriveProtocolIndex(this.hash(protocolId));
-        return this.fetchAccount("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) {
-        const [pda] = deriveProtocolIndex(this.hash(protocolId));
-        return this.fetchAccountNullable("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) {
-        const [pda] = deriveToolCategoryIndex(category);
-        return this.fetchAccount("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) {
-        const [pda] = deriveToolCategoryIndex(category);
-        return this.fetchAccountNullable("toolCategoryIndex", pda);
-    }
-}
-//# sourceMappingURL=indexing.js.map

package/dist/esm/modules/indexing.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"indexing.js","sourceRoot":"","sources":["../../../src/modules/indexing.ts"],"names":[],"mappings":"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"}

package/dist/esm/modules/ledger.js

@@ -1,230 +0,0 @@
-/**
- * @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 } from "@solana/web3.js";
-import { BaseModule } from "./base";
-import { deriveLedger, deriveLedgerPage } from "../pda";
-/**
- * @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) {
-        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, pageIndex) {
-        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) {
-        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, data, contentHash) {
-        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) {
-        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) {
-        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) {
-        const [pda] = deriveLedger(sessionPda);
-        return this.fetchAccount("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) {
-        const [pda] = deriveLedger(sessionPda);
-        return this.fetchAccountNullable("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, pageIndex) {
-        const [pda] = deriveLedgerPage(ledgerPda, pageIndex);
-        return this.fetchAccount("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, pageIndex) {
-        const [pda] = deriveLedgerPage(ledgerPda, pageIndex);
-        return this.fetchAccountNullable("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) {
-        const buf = Buffer.from(ring);
-        const entries = [];
-        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;
-    }
-}
-//# sourceMappingURL=ledger.js.map

package/dist/esm/modules/ledger.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../src/modules/ledger.ts"],"names":[],"mappings":"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"}