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

package/dist/esm/plugin/index.js

@@ -0,0 +1,927 @@
+/**
+ * @module plugin
+ * @description SynapsePlugin adapter for SAP v2.
+ *
+ * Exposes 52 tools across 8 on-chain protocol domains as a drop-in
+ * `SynapsePlugin` for `SynapseAgentKit`:
+ *
+ * ```ts
+ * import { SynapseAgentKit } from '@oobe-protocol-labs/synapse-client-sdk/ai/plugins';
+ * import { createSAPPlugin } from '@synapse-sap/sdk/plugin';
+ *
+ * const sapPlugin = createSAPPlugin({ provider });
+ * const kit = new SynapseAgentKit({ rpcUrl })
+ *   .use(sapPlugin);
+ *
+ * const tools = kit.getTools();   // → StructuredTool[] (LangChain)
+ * ```
+ *
+ * Architecture:
+ *   1. Schemas (Zod) → runtime validation + LLM-friendly descriptions
+ *   2. Protocols → 8 domain method registries (agent, feedback, …)
+ *   3. Executor → dispatches tool calls to SapClient module methods
+ *   4. Serialization → PublicKey↔string, BN↔string bridging
+ *
+ * @category Plugin
+ * @since v0.1.0
+ */
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { SapClient } from "../core/client";
+import { SAP_PROTOCOLS, } from "./protocols";
+import { deriveAgent, deriveVault, deriveSession, deriveLedger } from "../pda";
+import { hashToArray, sha256 } from "../utils";
+// ═══════════════════════════════════════════════════════════════════
+//  Version
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Current SAP plugin version string.
+ *
+ * @name SAP_PLUGIN_VERSION
+ * @description Semver version embedded in the plugin’s {@link PluginMeta}.
+ * @internal
+ * @since v0.1.0
+ */
+const SAP_PLUGIN_VERSION = "0.1.0";
+// ═══════════════════════════════════════════════════════════════════
+//  Serialization Helpers
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Convert a base58 string to PublicKey.
+ *
+ * @name toPubkey
+ * @description Returns `undefined` for nullish input, otherwise wraps
+ *   the base58 string in a Solana `PublicKey`.
+ * @param value - Base58-encoded public key or nullish
+ * @returns A `PublicKey` instance, or `undefined`
+ * @internal
+ * @since v0.1.0
+ */
+function toPubkey(value) {
+    return value ? new PublicKey(value) : undefined;
+}
+/**
+ * Convert a string amount to BN.
+ *
+ * @name toBN
+ * @description Returns `undefined` for nullish input, otherwise parses
+ *   the string as a `BN` (big number) instance.
+ * @param value - Numeric string or nullish
+ * @returns A `BN` instance, or `undefined`
+ * @internal
+ * @since v0.1.0
+ */
+function toBN(value) {
+    return value ? new BN(value) : undefined;
+}
+/**
+ * Convert a hex string to a Node.js Buffer.
+ *
+ * @name hexToBuffer
+ * @description Used for encrypted data payloads before sending to
+ *   on-chain instructions.
+ * @param hex - Hex-encoded string
+ * @returns Buffer of decoded bytes
+ * @internal
+ * @since v0.1.0
+ */
+function hexToBuffer(hex) {
+    return Buffer.from(hex, "hex");
+}
+/**
+ * Convert a hex string to Uint8Array for PDA seed derivation.
+ *
+ * @name hexToBytes
+ * @description Wraps `Buffer.from(hex, 'hex')` into a `Uint8Array`
+ *   suitable for Solana PDA seed arrays.
+ * @param hex - Hex-encoded string
+ * @returns Uint8Array of decoded bytes
+ * @internal
+ * @since v0.1.0
+ */
+function hexToBytes(hex) {
+    return new Uint8Array(Buffer.from(hex, "hex"));
+}
+/**
+ * Map token type strings to Anchor enum variant objects.
+ *
+ * @name toTokenType
+ * @description Converts `"sol"`, `"usdc"`, or `"spl"` to the
+ *   corresponding Anchor enum variant. Defaults to `{ sol: {} }`.
+ * @param s - Token type string
+ * @returns Anchor-compatible enum variant object
+ * @internal
+ * @since v0.1.0
+ */
+function toTokenType(s) {
+    const map = {
+        sol: { sol: {} },
+        usdc: { usdc: {} },
+        spl: { spl: {} },
+    };
+    return map[s] ?? { sol: {} };
+}
+/**
+ * Map settlement mode strings to Anchor enum variant objects.
+ *
+ * @name toSettlementMode
+ * @description Converts `"instant"`, `"escrow"`, `"batched"`, or `"x402"`
+ *   to the corresponding Anchor enum variant. Returns `null` for nullish input.
+ * @param s - Settlement mode string or nullish
+ * @returns Anchor-compatible enum variant object, or `null`
+ * @internal
+ * @since v0.1.0
+ */
+function toSettlementMode(s) {
+    if (!s)
+        return null;
+    const map = {
+        instant: { instant: {} },
+        escrow: { escrow: {} },
+        batched: { batched: {} },
+        x402: { x402: {} },
+    };
+    return map[s] ?? null;
+}
+/**
+ * Map HTTP method strings to numeric enum values.
+ *
+ * @name toHttpMethodNum
+ * @description Converts lowercase method names (`"get"`, `"post"`, etc.)
+ *   to their on-chain numeric representation. Defaults to `0` (GET).
+ * @param s - HTTP method string
+ * @returns Numeric enum value
+ * @internal
+ * @since v0.1.0
+ */
+function toHttpMethodNum(s) {
+    const map = {
+        get: 0,
+        post: 1,
+        put: 2,
+        delete: 3,
+        compound: 4,
+    };
+    return map[s] ?? 0;
+}
+/**
+ * Map category strings to numeric enum values.
+ *
+ * @name toCategoryNum
+ * @description Converts category names (`"swap"`, `"lend"`, etc.)
+ *   to their on-chain numeric representation. Defaults to `9` (custom).
+ * @param s - Category string
+ * @returns Numeric enum value
+ * @internal
+ * @since v0.1.0
+ */
+function toCategoryNum(s) {
+    const map = {
+        swap: 0,
+        lend: 1,
+        stake: 2,
+        nft: 3,
+        payment: 4,
+        data: 5,
+        governance: 6,
+        bridge: 7,
+        analytics: 8,
+        custom: 9,
+    };
+    return map[s] ?? 9;
+}
+/**
+ * Map schema type strings to numeric enum values.
+ *
+ * @name toSchemaTypeNum
+ * @description Converts `"input"`, `"output"`, or `"description"`
+ *   to their on-chain numeric representation. Defaults to `0` (input).
+ * @param s - Schema type string
+ * @returns Numeric enum value
+ * @internal
+ * @since v0.1.0
+ */
+function toSchemaTypeNum(s) {
+    const map = { input: 0, output: 1, description: 2 };
+    return map[s] ?? 0;
+}
+/**
+ * Map compression type strings to numeric enum values.
+ *
+ * @name toCompressionNum
+ * @description Converts `"none"`, `"deflate"`, `"gzip"`, or `"brotli"`
+ *   to their on-chain numeric representation. Defaults to `0` (none).
+ * @param s - Compression type string
+ * @returns Numeric enum value
+ * @internal
+ * @since v0.1.0
+ */
+function toCompressionNum(s) {
+    const map = {
+        none: 0,
+        deflate: 1,
+        gzip: 2,
+        brotli: 3,
+    };
+    return map[s] ?? 0;
+}
+/**
+ * Convert a JSON-serialized pricing tier from plugin input
+ * into the SDK’s PricingTier shape with BN/PublicKey/enum conversions.
+ *
+ * @name toPricingTier
+ * @description Transforms raw JSON input (string amounts, string enums)
+ *   into the native Anchor-compatible shape with `BN`, `PublicKey`,
+ *   and enum variant objects.
+ * @param raw - Raw pricing tier object from Zod-validated plugin input
+ * @returns Anchor-compatible PricingTier object
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function toPricingTier(raw) {
+    return {
+        tierId: raw.tierId,
+        pricePerCall: new BN(raw.pricePerCall),
+        minPricePerCall: toBN(raw.minPricePerCall) ?? null,
+        maxPricePerCall: toBN(raw.maxPricePerCall) ?? null,
+        rateLimit: raw.rateLimit,
+        maxCallsPerSession: raw.maxCallsPerSession,
+        burstLimit: raw.burstLimit ?? null,
+        tokenType: toTokenType(raw.tokenType),
+        tokenMint: toPubkey(raw.tokenMint) ?? null,
+        tokenDecimals: raw.tokenDecimals ?? null,
+        settlementMode: toSettlementMode(raw.settlementMode),
+        minEscrowDeposit: toBN(raw.minEscrowDeposit) ?? null,
+        batchIntervalSec: raw.batchIntervalSec ?? null,
+        volumeCurve: raw.volumeCurve
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ? raw.volumeCurve.map((v) => ({
+                afterCalls: v.afterCalls,
+                pricePerCall: new BN(v.pricePerCall),
+            }))
+            : null,
+    };
+}
+/**
+ * Serialize an on-chain account object to a JSON-safe shape.
+ *
+ * @name serializeAccount
+ * @description Recursively converts `PublicKey` → base58 string,
+ *   `BN` → decimal string, and nested objects/arrays. Used to
+ *   return tool output that is JSON-serializable for LLMs.
+ * @param obj - Raw account data record from Anchor deserialization
+ * @returns JSON-safe record with all Solana types converted to strings
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function serializeAccount(obj) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined) {
+            result[key] = null;
+        }
+        else if (value instanceof PublicKey) {
+            result[key] = value.toBase58();
+        }
+        else if (BN.isBN(value)) {
+            result[key] = value.toString();
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map((item) => {
+                if (item instanceof PublicKey)
+                    return item.toBase58();
+                if (BN.isBN(item))
+                    return item.toString();
+                if (typeof item === "object" && item !== null)
+                    return serializeAccount(item);
+                return item;
+            });
+        }
+        else if (typeof value === "object") {
+            result[key] = serializeAccount(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Executor Builder
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Build the executor function that dispatches incoming tool calls
+ * to the appropriate SapClient module method.
+ *
+ * @name buildExecutor
+ * @description Creates a closure over a `SapClient` instance that routes
+ *   each incoming `ProtocolMethod` to the correct per-protocol dispatcher
+ *   based on `method.protocol`.
+ * @param client - Initialized SapClient for the configured provider
+ * @returns Async executor function `(method, input) => Promise<unknown>`
+ * @internal
+ * @since v0.1.0
+ */
+function buildExecutor(client) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return async (method, raw) => {
+        switch (method.protocol) {
+            // ────────────────────── Agent ──────────────────────
+            case "sap-agent":
+                return executeAgent(client, method.name, raw);
+            // ────────────────────── Feedback ───────────────────
+            case "sap-feedback":
+                return executeFeedback(client, method.name, raw);
+            // ────────────────────── Attestation ────────────────
+            case "sap-attestation":
+                return executeAttestation(client, method.name, raw);
+            // ────────────────────── Escrow ─────────────────────
+            case "sap-escrow":
+                return executeEscrow(client, method.name, raw);
+            // ────────────────────── Tools ──────────────────────
+            case "sap-tools":
+                return executeTools(client, method.name, raw);
+            // ────────────────────── Vault ──────────────────────
+            case "sap-vault":
+                return executeVault(client, method.name, raw);
+            // ────────────────────── Indexing ───────────────────
+            case "sap-indexing":
+                return executeIndexing(client, method.name, raw);
+            // ────────────────────── Ledger ─────────────────────
+            case "sap-ledger":
+                return executeLedger(client, method.name, raw);
+            default:
+                throw new Error(`Unknown SAP protocol: ${method.protocol}`);
+        }
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Per-Protocol Dispatchers
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Dispatch tool calls for the **sap-agent** protocol.
+ *
+ * @name executeAgent
+ * @description Routes agent-domain method names to `client.agent.*` calls,
+ *   handling argument conversion and account serialization.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"registerAgent"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeAgent(client, name, input) {
+    switch (name) {
+        case "registerAgent": {
+            const args = {
+                name: input.name,
+                description: input.description,
+                capabilities: input.capabilities,
+                pricing: (input.pricing ?? []).map(toPricingTier),
+                protocols: input.protocols ?? [],
+                agentId: input.agentId ?? null,
+                agentUri: input.agentUri ?? null,
+                x402Endpoint: input.x402Endpoint ?? null,
+            };
+            const tx = await client.agent.register(args);
+            return { txSignature: tx };
+        }
+        case "updateAgent": {
+            const args = {
+                name: input.name ?? null,
+                description: input.description ?? null,
+                capabilities: input.capabilities ?? null,
+                pricing: input.pricing ? input.pricing.map(toPricingTier) : null,
+                protocols: input.protocols ?? null,
+                agentId: input.agentId ?? null,
+                agentUri: input.agentUri ?? null,
+                x402Endpoint: input.x402Endpoint ?? null,
+            };
+            const tx = await client.agent.update(args);
+            return { txSignature: tx };
+        }
+        case "deactivateAgent": {
+            const tx = await client.agent.deactivate();
+            return { txSignature: tx };
+        }
+        case "reactivateAgent": {
+            const tx = await client.agent.reactivate();
+            return { txSignature: tx };
+        }
+        case "reportCalls": {
+            const tx = await client.agent.reportCalls(input.callsServed);
+            return { txSignature: tx };
+        }
+        case "updateReputation": {
+            const tx = await client.agent.updateReputation(input.avgLatencyMs, input.uptimePercent);
+            return { txSignature: tx };
+        }
+        case "fetchAgent": {
+            const wallet = toPubkey(input.wallet);
+            const data = await client.agent.fetch(wallet);
+            return serializeAccount(data);
+        }
+        case "fetchGlobalRegistry": {
+            const data = await client.agent.fetchGlobalRegistry();
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-agent method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-feedback** protocol.
+ *
+ * @name executeFeedback
+ * @description Routes feedback-domain method names to `client.feedback.*` calls.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"giveFeedback"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeFeedback(client, name, input) {
+    switch (name) {
+        case "giveFeedback": {
+            const agentWallet = new PublicKey(input.agentWallet);
+            const args = {
+                score: input.score,
+                tag: input.tag,
+                commentHash: input.commentHash ?? null,
+            };
+            const tx = await client.feedback.give(agentWallet, args);
+            return { txSignature: tx };
+        }
+        case "updateFeedback": {
+            const agentWallet = new PublicKey(input.agentWallet);
+            const args = {
+                newScore: input.newScore,
+                newTag: input.newTag ?? null,
+                commentHash: input.commentHash ?? null,
+            };
+            const tx = await client.feedback.update(agentWallet, args);
+            return { txSignature: tx };
+        }
+        case "revokeFeedback": {
+            const tx = await client.feedback.revoke(new PublicKey(input.agentWallet));
+            return { txSignature: tx };
+        }
+        case "fetchFeedback": {
+            const [agentPda] = deriveAgent(new PublicKey(input.agentWallet));
+            const reviewer = toPubkey(input.reviewer);
+            const data = await client.feedback.fetch(agentPda, reviewer);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-feedback method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-attestation** protocol.
+ *
+ * @name executeAttestation
+ * @description Routes attestation-domain method names to `client.attestation.*` calls.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"createAttestation"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeAttestation(client, name, input) {
+    switch (name) {
+        case "createAttestation": {
+            const args = {
+                attestationType: input.attestationType,
+                metadataHash: input.metadataHash,
+                expiresAt: new BN(input.expiresAt),
+            };
+            const tx = await client.attestation.create(new PublicKey(input.agentWallet), args);
+            return { txSignature: tx };
+        }
+        case "revokeAttestation": {
+            const tx = await client.attestation.revoke(new PublicKey(input.agentWallet));
+            return { txSignature: tx };
+        }
+        case "fetchAttestation": {
+            const [agentPda] = deriveAgent(new PublicKey(input.agentWallet));
+            const attester = toPubkey(input.attester);
+            const data = await client.attestation.fetch(agentPda, attester);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-attestation method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-escrow** protocol.
+ *
+ * @name executeEscrow
+ * @description Routes escrow-domain method names to `client.escrow.*` calls,
+ *   including BN conversion for amounts and volume curves.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"createEscrow"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeEscrow(client, name, input) {
+    switch (name) {
+        case "createEscrow": {
+            const args = {
+                pricePerCall: new BN(input.pricePerCall),
+                maxCalls: new BN(input.maxCalls),
+                initialDeposit: new BN(input.initialDeposit),
+                expiresAt: new BN(input.expiresAt),
+                volumeCurve: (input.volumeCurve ?? []).map(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (v) => ({
+                    afterCalls: v.afterCalls,
+                    pricePerCall: new BN(v.pricePerCall),
+                })),
+                tokenMint: toPubkey(input.tokenMint) ?? null,
+                tokenDecimals: input.tokenDecimals ?? 9,
+            };
+            const tx = await client.escrow.create(new PublicKey(input.agentWallet), args);
+            return { txSignature: tx };
+        }
+        case "depositEscrow": {
+            const tx = await client.escrow.deposit(new PublicKey(input.agentWallet), new BN(input.amount));
+            return { txSignature: tx };
+        }
+        case "settleEscrow": {
+            const tx = await client.escrow.settle(new PublicKey(input.depositorWallet), new BN(input.callsToSettle), input.serviceHash);
+            return { txSignature: tx };
+        }
+        case "withdrawEscrow": {
+            const tx = await client.escrow.withdraw(new PublicKey(input.agentWallet), new BN(input.amount));
+            return { txSignature: tx };
+        }
+        case "batchSettle": {
+            const settlements = input.settlements.map(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (s) => ({
+                callsToSettle: new BN(s.callsToSettle),
+                serviceHash: s.serviceHash,
+            }));
+            const tx = await client.escrow.settleBatch(new PublicKey(input.depositorWallet), settlements);
+            return { txSignature: tx };
+        }
+        case "fetchEscrow": {
+            const [agentPda] = deriveAgent(new PublicKey(input.agentWallet));
+            const depositor = toPubkey(input.depositor);
+            const data = await client.escrow.fetch(agentPda, depositor);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-escrow method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-tools** protocol.
+ *
+ * @name executeTools
+ * @description Routes tools-domain method names to `client.tools.*` calls,
+ *   handling schema hashing and enum conversions.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"publishToolByName"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeTools(client, name, input) {
+    switch (name) {
+        case "publishToolByName": {
+            const tx = await client.tools.publishByName(input.toolName, input.protocolId, input.description, input.inputSchema, input.outputSchema, toHttpMethodNum(input.httpMethod), toCategoryNum(input.category), input.paramsCount, input.requiredParams, input.isCompound ?? false);
+            return { txSignature: tx };
+        }
+        case "inscribeToolSchema": {
+            const args = {
+                schemaType: toSchemaTypeNum(input.schemaType),
+                schemaData: Buffer.from(input.schemaData, "utf-8"),
+                schemaHash: hashToArray(sha256(input.schemaData)),
+                compression: toCompressionNum(input.compression ?? "none"),
+            };
+            const tx = await client.tools.inscribeSchema(input.toolName, args);
+            return { txSignature: tx };
+        }
+        case "updateTool": {
+            const args = {
+                descriptionHash: null,
+                inputSchemaHash: null,
+                outputSchemaHash: null,
+                httpMethod: input.httpMethod != null ? toHttpMethodNum(input.httpMethod) : null,
+                category: input.category != null ? toCategoryNum(input.category) : null,
+                paramsCount: input.paramsCount ?? null,
+                requiredParams: input.requiredParams ?? null,
+            };
+            const tx = await client.tools.update(input.toolName, args);
+            return { txSignature: tx };
+        }
+        case "deactivateTool": {
+            const tx = await client.tools.deactivate(input.toolName);
+            return { txSignature: tx };
+        }
+        case "reactivateTool": {
+            const tx = await client.tools.reactivate(input.toolName);
+            return { txSignature: tx };
+        }
+        case "reportInvocations": {
+            const tx = await client.tools.reportInvocations(input.toolName, input.invocations);
+            return { txSignature: tx };
+        }
+        case "fetchTool": {
+            const [agentPda] = deriveAgent(new PublicKey(input.agentWallet));
+            const data = await client.tools.fetch(agentPda, input.toolName);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-tools method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-vault** protocol.
+ *
+ * @name executeVault
+ * @description Routes vault-domain method names to `client.vault.*` calls,
+ *   handling hex-to-bytes conversion and PDA derivation for sessions.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"initVault"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeVault(client, name, input) {
+    switch (name) {
+        case "initVault": {
+            const tx = await client.vault.initVault(input.vaultNonce);
+            return { txSignature: tx };
+        }
+        case "openSession": {
+            const tx = await client.vault.openSession(input.sessionHash);
+            return { txSignature: tx };
+        }
+        case "inscribeMemory": {
+            const args = {
+                sequence: input.sequence,
+                encryptedData: hexToBuffer(input.encryptedData),
+                nonce: input.nonce,
+                contentHash: input.contentHash,
+                totalFragments: input.totalFragments ?? 1,
+                fragmentIndex: input.fragmentIndex ?? 0,
+                compression: input.compression ?? 0,
+                epochIndex: input.epochIndex ?? 0,
+            };
+            const tx = await client.vault.inscribe(args);
+            return { txSignature: tx };
+        }
+        case "closeSession": {
+            const [agentPda] = deriveAgent(client.walletPubkey);
+            const [vaultPda] = deriveVault(agentPda);
+            const sessionHashBytes = hexToBytes(input.sessionHash);
+            const [sessionPda] = deriveSession(vaultPda, sessionHashBytes);
+            const tx = await client.vault.closeSession(vaultPda, sessionPda);
+            return { txSignature: tx };
+        }
+        case "closeVault": {
+            const tx = await client.vault.closeVault();
+            return { txSignature: tx };
+        }
+        case "rotateNonce": {
+            const tx = await client.vault.rotateNonce(input.newNonce);
+            return { txSignature: tx };
+        }
+        case "addDelegate": {
+            const tx = await client.vault.addDelegate(new PublicKey(input.delegatePubkey), input.permissions, BigInt(input.expiresAt));
+            return { txSignature: tx };
+        }
+        case "revokeDelegate": {
+            const tx = await client.vault.revokeDelegate(new PublicKey(input.delegatePubkey));
+            return { txSignature: tx };
+        }
+        case "fetchVault": {
+            const wallet = toPubkey(input.agentWallet) ?? client.walletPubkey;
+            const [agentPda] = deriveAgent(wallet);
+            const data = await client.vault.fetchVault(agentPda);
+            return serializeAccount(data);
+        }
+        case "fetchSession": {
+            const wallet = new PublicKey(input.agentWallet);
+            const [agentPda] = deriveAgent(wallet);
+            const [vaultPda] = deriveVault(agentPda);
+            const sessionHashBytes = hexToBytes(input.sessionHash);
+            const data = await client.vault.fetchSession(vaultPda, sessionHashBytes);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-vault method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-indexing** protocol.
+ *
+ * @name executeIndexing
+ * @description Routes indexing-domain method names to `client.indexing.*` calls
+ *   for capability and protocol index management.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"initCapabilityIndex"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeIndexing(client, name, input) {
+    switch (name) {
+        case "initCapabilityIndex": {
+            const tx = await client.indexing.initCapabilityIndex(input.capabilityId);
+            return { txSignature: tx };
+        }
+        case "addToCapabilityIndex": {
+            const tx = await client.indexing.addToCapabilityIndex(input.capabilityId);
+            return { txSignature: tx };
+        }
+        case "removeFromCapabilityIndex": {
+            const tx = await client.indexing.removeFromCapabilityIndex(input.capabilityId);
+            return { txSignature: tx };
+        }
+        case "initProtocolIndex": {
+            const tx = await client.indexing.initProtocolIndex(input.protocolId);
+            return { txSignature: tx };
+        }
+        case "addToProtocolIndex": {
+            const tx = await client.indexing.addToProtocolIndex(input.protocolId);
+            return { txSignature: tx };
+        }
+        case "removeFromProtocolIndex": {
+            const tx = await client.indexing.removeFromProtocolIndex(input.protocolId);
+            return { txSignature: tx };
+        }
+        case "fetchCapabilityIndex": {
+            const data = await client.indexing.fetchCapabilityIndex(input.capabilityId);
+            return serializeAccount(data);
+        }
+        case "fetchProtocolIndex": {
+            const data = await client.indexing.fetchProtocolIndex(input.protocolId);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-indexing method: ${name}`);
+    }
+}
+/**
+ * Dispatch tool calls for the **sap-ledger** protocol.
+ *
+ * @name executeLedger
+ * @description Routes ledger-domain method names to `client.ledger.*` calls,
+ *   deriving session PDAs from hex-encoded session hashes.
+ * @param client - SapClient instance
+ * @param name - Method name (e.g. `"initLedger"`)
+ * @param input - Zod-validated input from the LLM tool call
+ * @returns Transaction signature or serialized account data
+ * @internal
+ * @since v0.1.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function executeLedger(client, name, input) {
+    const resolveSessionPda = (sessionHash, agentWallet) => {
+        const wallet = toPubkey(agentWallet) ?? client.walletPubkey;
+        const [agentPda] = deriveAgent(wallet);
+        const [vaultPda] = deriveVault(agentPda);
+        const sessionHashBytes = hexToBytes(sessionHash);
+        const [sessionPda] = deriveSession(vaultPda, sessionHashBytes);
+        return sessionPda;
+    };
+    switch (name) {
+        case "initLedger": {
+            const sessionPda = resolveSessionPda(input.sessionHash, input.agentWallet);
+            const tx = await client.ledger.init(sessionPda);
+            return { txSignature: tx };
+        }
+        case "writeLedger": {
+            const sessionPda = resolveSessionPda(input.sessionHash, input.agentWallet);
+            const data = hexToBuffer(input.data);
+            const tx = await client.ledger.write(sessionPda, data, input.contentHash);
+            return { txSignature: tx };
+        }
+        case "sealLedger": {
+            const sessionPda = resolveSessionPda(input.sessionHash, input.agentWallet);
+            const tx = await client.ledger.seal(sessionPda);
+            return { txSignature: tx };
+        }
+        case "closeLedger": {
+            const sessionPda = resolveSessionPda(input.sessionHash, input.agentWallet);
+            const tx = await client.ledger.close(sessionPda);
+            return { txSignature: tx };
+        }
+        case "fetchLedger": {
+            const sessionPda = resolveSessionPda(input.sessionHash, input.agentWallet);
+            const data = await client.ledger.fetchLedger(sessionPda);
+            return serializeAccount(data);
+        }
+        case "fetchLedgerPage": {
+            const sessionPda = resolveSessionPda(input.sessionHash, input.agentWallet);
+            const [ledgerPda] = deriveLedger(sessionPda);
+            const data = await client.ledger.fetchPage(ledgerPda, input.pageIndex);
+            return serializeAccount(data);
+        }
+        default:
+            throw new Error(`Unknown sap-ledger method: ${name}`);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Plugin Factory
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Create a SynapsePlugin for SAP v2.
+ *
+ * @name createSAPPlugin
+ * @description Factory function that returns a fully configured
+ *   {@link SynapsePlugin} exposing 52 tools across 8 on-chain
+ *   protocol domains. The plugin can be installed into a
+ *   `SynapseAgentKit` instance or used standalone.
+ * @param config - Plugin configuration with Anchor provider and optional program ID
+ * @returns A configured {@link SynapsePlugin} instance
+ * @category Plugin
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { createSAPPlugin } from '@synapse-sap/sdk/plugin';
+ *
+ * const sapPlugin = createSAPPlugin({ provider });
+ *
+ * // Use with SynapseAgentKit:
+ * kit.use(sapPlugin);
+ *
+ * // Or standalone:
+ * const executor = sapPlugin.install({ client, config: {} }).executor;
+ * await executor(someMethod, someInput);
+ * ```
+ */
+export function createSAPPlugin(config) {
+    return {
+        meta: {
+            id: "sap",
+            name: "SAP v2 — Solana Agent Protocol",
+            version: SAP_PLUGIN_VERSION,
+            description: "On-chain agent identity, reputation, tool registry, encrypted memory vault, x402 escrow, attestation, discovery indexes, and unified memory ledger on Solana",
+            tags: [
+                "solana",
+                "agent",
+                "identity",
+                "reputation",
+                "x402",
+                "escrow",
+                "vault",
+                "memory",
+                "tools",
+                "attestation",
+                "erc-8004",
+            ],
+        },
+        protocols: SAP_PROTOCOLS,
+        install(_context) {
+            const client = SapClient.from(config.provider, config.programId);
+            const executor = buildExecutor(client);
+            return { executor };
+        },
+    };
+}
+/**
+ * Pre-built plugin object for static use patterns.
+ *
+ * @name SAPPlugin
+ * @description Convenience namespace exposing a `configure` method
+ *   that delegates to {@link createSAPPlugin}. Useful for concise
+ *   one-liner instantiation.
+ * @category Plugin
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SAPPlugin } from '@synapse-sap/sdk/plugin';
+ *
+ * const plugin = SAPPlugin.configure({ provider });
+ * kit.use(plugin);
+ * ```
+ */
+export const SAPPlugin = {
+    /** Create a configured SynapsePlugin from an AnchorProvider. */
+    configure: createSAPPlugin,
+};
+//# sourceMappingURL=index.js.map