@svsprotocol/solana 0.1.0

package/dist/vercel-ai.d.ts

@@ -0,0 +1,47 @@
+import type {
+  SvsAdapterActionInput,
+  SvsAdapterActionResult,
+  SvsAdapterOptions,
+  SvsAdapterReadinessResult,
+  JsonObject
+} from "./common.js";
+import { SvsAdapterCoreError } from "./adapter-core.js";
+
+export const VERCEL_AI_SDK_ADAPTER_VERSION: "svs.vercel-ai-sdk-adapter.v1";
+export const VERCEL_AI_SDK_TOOL_NAME: "svsVerifyAndSubmitSolanaAction";
+
+export class SvsVercelAiSdkAdapterError extends SvsAdapterCoreError {}
+
+export interface SvsVercelAiSdkTool {
+  version?: typeof VERCEL_AI_SDK_ADAPTER_VERSION;
+  name?: typeof VERCEL_AI_SDK_TOOL_NAME;
+  title: string;
+  description: string;
+  inputSchema: unknown;
+  inputExamples: unknown[];
+  needsApproval?: unknown;
+  execute(input: SvsAdapterActionInput): Promise<SvsAdapterActionResult>;
+  handler?: (input: SvsAdapterActionInput) => Promise<SvsAdapterActionResult>;
+}
+
+export interface SvsVercelAiSdkTools {
+  version: typeof VERCEL_AI_SDK_ADAPTER_VERSION;
+  name: "svs-vercel-ai-sdk-tools";
+  description: string;
+  botId: string;
+  policyId: string | null;
+  rpcUrl: string | null;
+  client: unknown;
+  tool: SvsVercelAiSdkTool | unknown;
+  tools: Record<typeof VERCEL_AI_SDK_TOOL_NAME, SvsVercelAiSdkTool | unknown>;
+  requireSvsProductionReady(options?: Partial<SvsAdapterOptions>): Promise<SvsAdapterReadinessResult>;
+  verifyAndSubmitSolanaAction(input: SvsAdapterActionInput, options?: Partial<SvsAdapterOptions>): Promise<SvsAdapterActionResult>;
+  getTools(): Record<typeof VERCEL_AI_SDK_TOOL_NAME, SvsVercelAiSdkTool | unknown>;
+}
+
+export function createSvsVercelAiSdkTools(options: SvsAdapterOptions & { tool?: Function | null; z?: unknown; needsApproval?: unknown }): SvsVercelAiSdkTools;
+export function createSvsVercelAiSdkTool(options?: { client?: unknown; defaults?: Partial<SvsAdapterOptions>; tool?: Function | null; z?: unknown; needsApproval?: unknown }): SvsVercelAiSdkTool | unknown;
+export function createVercelAiSdkToolMetadata(options?: { z?: unknown; needsApproval?: unknown }): JsonObject;
+export function createVercelAiSdkInputSchema(options?: { z?: unknown }): unknown;
+export function requireSvsVercelAiSdkProductionReady(options: SvsAdapterOptions): Promise<SvsAdapterReadinessResult>;
+export function verifyAndSubmitVercelAiSdkSolanaAction(options: SvsAdapterOptions & SvsAdapterActionInput): Promise<SvsAdapterActionResult>;

package/dist/vercel-ai.js

@@ -0,0 +1,266 @@
+import {
+  SvsAdapterCoreError,
+  createSvsAdapterClient,
+  requireSvsAdapterProductionReady,
+  verifyAndSubmitSvsAdapterSolanaAction
+} from "./adapter-core.js";
+
+export const VERCEL_AI_SDK_ADAPTER_VERSION = "svs.vercel-ai-sdk-adapter.v1";
+export const VERCEL_AI_SDK_TOOL_NAME = "svsVerifyAndSubmitSolanaAction";
+
+export class SvsVercelAiSdkAdapterError extends SvsAdapterCoreError {
+  constructor(message, details = {}) {
+    super(message, details);
+    this.name = "SvsVercelAiSdkAdapterError";
+  }
+}
+
+export function createSvsVercelAiSdkTools({
+  client = null,
+  baseUrl,
+  apiKey,
+  requestSigningSecret,
+  expectedIntegrationContractHash,
+  botId,
+  policyId = null,
+  rpcUrl = null,
+  certificationStaleAfterMs = undefined,
+  requireCurrentIntegrationContract = true,
+  waitForProof = false,
+  waitAttempts = 12,
+  waitIntervalMs = 5000,
+  fetchProof = true,
+  checkReceiptRegistryChain = true,
+  requireReadinessOnSubmit = true,
+  tool = null,
+  z = null,
+  needsApproval = undefined
+} = {}) {
+  if (!botId) {
+    throw new Error("botId is required.");
+  }
+
+  const svs = createSvsAdapterClient({
+    client,
+    baseUrl,
+    apiKey,
+    requestSigningSecret,
+    expectedIntegrationContractHash
+  });
+  const defaults = {
+    botId,
+    policyId,
+    rpcUrl,
+    certificationStaleAfterMs,
+    requireCurrentIntegrationContract,
+    waitForProof,
+    waitAttempts,
+    waitIntervalMs,
+    fetchProof,
+    checkReceiptRegistryChain,
+    requireReadinessOnSubmit
+  };
+  const svsTool = createSvsVercelAiSdkTool({
+    client: svs,
+    defaults,
+    tool,
+    z,
+    needsApproval
+  });
+  const tools = {
+    [VERCEL_AI_SDK_TOOL_NAME]: svsTool
+  };
+
+  return {
+    version: VERCEL_AI_SDK_ADAPTER_VERSION,
+    name: "svs-vercel-ai-sdk-tools",
+    description: "SVS Agent Verification tools for Vercel AI SDK Solana agents.",
+    botId,
+    policyId,
+    rpcUrl,
+    client: svs,
+    tool: svsTool,
+    tools,
+    async requireSvsProductionReady(options = {}) {
+      return requireSvsVercelAiSdkProductionReady({
+        client: svs,
+        ...defaults,
+        ...options
+      });
+    },
+    async verifyAndSubmitSolanaAction(input = {}, options = {}) {
+      return verifyAndSubmitVercelAiSdkSolanaAction({
+        client: svs,
+        ...defaults,
+        ...input,
+        ...options
+      });
+    },
+    getTools() {
+      return tools;
+    }
+  };
+}
+
+export function createSvsVercelAiSdkTool({
+  client,
+  defaults = {},
+  tool = null,
+  z = null,
+  needsApproval = undefined
+} = {}) {
+  const metadata = createVercelAiSdkToolMetadata({ z, needsApproval });
+  const execute = async (input = {}) => verifyAndSubmitVercelAiSdkSolanaAction({
+    client,
+    ...defaults,
+    ...input
+  });
+  const definition = {
+    ...metadata,
+    execute
+  };
+
+  if (typeof tool === "function") {
+    return tool(definition);
+  }
+
+  return {
+    version: VERCEL_AI_SDK_ADAPTER_VERSION,
+    name: VERCEL_AI_SDK_TOOL_NAME,
+    ...definition,
+    handler: execute
+  };
+}
+
+export function createVercelAiSdkToolMetadata({
+  z = null,
+  needsApproval = undefined
+} = {}) {
+  const metadata = {
+    title: "SVS verified Solana action",
+    description: "Submit a Solana action through SVS so signed bot identity, production certification, human wallet approval, policy enforcement, and portable production proof are required before the action is trusted.",
+    inputSchema: createVercelAiSdkInputSchema({ z }),
+    inputExamples: [{
+      input: {
+        requestId: "agent-action-001",
+        intent: {
+          type: "memo",
+          summary: "Write a devnet memo after human approval"
+        },
+        serializedTransaction: "<base64-solana-transaction>"
+      }
+    }]
+  };
+
+  if (needsApproval !== undefined) {
+    metadata.needsApproval = needsApproval;
+  }
+
+  return metadata;
+}
+
+export function createVercelAiSdkInputSchema({ z = null } = {}) {
+  if (z?.object && z?.string && z?.boolean && z?.number && z?.unknown) {
+    return z.object({
+      requestId: z.string().optional(),
+      idempotencyKey: z.string().optional(),
+      intent: z.unknown(),
+      policyId: z.string().optional(),
+      serializedTransaction: z.string(),
+      rpcUrl: z.string().optional(),
+      simulation: z.unknown().optional(),
+      metadata: z.unknown().optional(),
+      waitForProof: z.boolean().optional(),
+      waitAttempts: z.number().optional(),
+      waitIntervalMs: z.number().optional(),
+      fetchProof: z.boolean().optional(),
+      checkReceiptRegistryChain: z.boolean().optional()
+    });
+  }
+
+  return {
+    type: "object",
+    required: ["intent", "serializedTransaction"],
+    properties: {
+      requestId: {
+        type: "string",
+        description: "Stable idempotency key for this AI SDK tool call."
+      },
+      idempotencyKey: {
+        type: "string",
+        description: "Optional idempotency override. Defaults to requestId."
+      },
+      intent: {
+        type: "object",
+        description: "Human-readable Solana action intent shown to the SVS operator."
+      },
+      policyId: {
+        type: "string",
+        description: "SVS policy id to enforce for this action."
+      },
+      serializedTransaction: {
+        type: "string",
+        description: "Serialized Solana transaction prepared by the agent."
+      },
+      rpcUrl: {
+        type: "string",
+        description: "Solana RPC URL used to simulate or verify the action."
+      },
+      simulation: {
+        type: "object",
+        description: "Optional Solana simulation result produced before submitting."
+      },
+      metadata: {
+        type: "object",
+        description: "Optional non-secret metadata to include in the approval record."
+      },
+      waitForProof: {
+        type: "boolean",
+        description: "Wait for the human/operator path to produce a production proof."
+      },
+      waitAttempts: {
+        type: "number",
+        description: "Maximum proof polling attempts."
+      },
+      waitIntervalMs: {
+        type: "number",
+        description: "Delay between proof polling attempts."
+      },
+      fetchProof: {
+        type: "boolean",
+        description: "Fetch the proof package after proof status becomes ready."
+      },
+      checkReceiptRegistryChain: {
+        type: "boolean",
+        description: "Ask SVS to independently check the custom registry proof on-chain."
+      }
+    }
+  };
+}
+
+export async function requireSvsVercelAiSdkProductionReady({
+  ...options
+} = {}) {
+  return requireSvsAdapterProductionReady({
+    ...options,
+    readinessVersion: "svs.vercel-ai-sdk-readiness.v1",
+    readyMessage: "SVS Vercel AI SDK tool readiness and production certification passed.",
+    adapterLabel: "Vercel AI SDK adapter",
+    ErrorClass: SvsVercelAiSdkAdapterError
+  });
+}
+
+export async function verifyAndSubmitVercelAiSdkSolanaAction({
+  ...options
+} = {}) {
+  return verifyAndSubmitSvsAdapterSolanaAction({
+    ...options,
+    adapterVersion: VERCEL_AI_SDK_ADAPTER_VERSION,
+    agentFramework: "vercel-ai-sdk",
+    resultVersion: "svs.vercel-ai-sdk-action-result.v1",
+    readinessVersion: "svs.vercel-ai-sdk-readiness.v1",
+    readyMessage: "SVS Vercel AI SDK tool readiness and production certification passed.",
+    adapterLabel: "Vercel AI SDK adapter",
+    ErrorClass: SvsVercelAiSdkAdapterError
+  });
+}