@svsprotocol/solana 0.1.0

package/dist/adapter-catalog.js

@@ -0,0 +1,146 @@
+export const SVS_ADAPTER_CATALOG_VERSION = "svs.agent-framework-adapter-catalog.v1";
+
+const FRAMEWORK_ADAPTERS = [
+  {
+    id: "custom-adapter-core",
+    runtime: "Custom agent runtime",
+    category: "adapter-core",
+    packageExport: "@svsprotocol/solana/adapter-core",
+    exportPath: "./adapter-core",
+    adapterVersion: "svs.adapter-core.v1",
+    readinessHelper: "requireSvsAdapterProductionReady",
+    submitHelper: "verifyAndSubmitSvsAdapterSolanaAction",
+    toolName: null,
+    pluginName: null,
+    actionName: null,
+    demoCommand: "npm run example:typescript:agent",
+    docsPath: "examples/host-apps/custom-adapter-core/README.md",
+    hostValidationTarget: "custom-adapter-core",
+    bestFit: "Any Solana agent framework that wants SVS without a first-party adapter.",
+    primary: false
+  },
+  {
+    id: "solana-agent-kit",
+    runtime: "Solana Agent Kit",
+    category: "framework-adapter",
+    packageExport: "@svsprotocol/solana/solana-agent-kit",
+    exportPath: "./solana-agent-kit",
+    adapterVersion: "svs.solana-agent-kit-adapter.v1",
+    readinessHelper: "requireSvsProductionReady",
+    submitHelper: "verifyAndSubmitSolanaAction",
+    toolName: "svs_verify_and_submit_solana_action",
+    pluginName: null,
+    actionName: null,
+    demoCommand: "npm run example:agent:solana-kit",
+    docsPath: "integrations/solana-agent-kit/README.md",
+    hostValidationTarget: "solana-agent-kit-minimal",
+    bestFit: "Solana-native agent kits that register executable tools.",
+    primary: true
+  },
+  {
+    id: "elizaos",
+    runtime: "ElizaOS",
+    category: "framework-adapter",
+    packageExport: "@svsprotocol/solana/elizaos",
+    exportPath: "./elizaos",
+    adapterVersion: "svs.elizaos-adapter.v1",
+    readinessHelper: "requireSvsElizaOsProductionReady",
+    submitHelper: "verifyAndSubmitElizaOsSolanaAction",
+    toolName: null,
+    pluginName: "svs-solana-verification",
+    actionName: "SVS_VERIFY_AND_SUBMIT_SOLANA_ACTION",
+    demoCommand: "npm run example:agent:elizaos",
+    docsPath: "integrations/elizaos/README.md",
+    hostValidationTarget: "elizaos-plugin-install",
+    bestFit: "ElizaOS plugins/actions with fail-closed handler results.",
+    primary: true
+  },
+  {
+    id: "goat",
+    runtime: "GOAT",
+    category: "framework-adapter",
+    packageExport: "@svsprotocol/solana/goat",
+    exportPath: "./goat",
+    adapterVersion: "svs.goat-adapter.v1",
+    readinessHelper: "requireSvsGoatProductionReady",
+    submitHelper: "verifyAndSubmitGoatSolanaAction",
+    toolName: "svs_verify_and_submit_solana_action",
+    pluginName: "svs-solana-verification",
+    actionName: null,
+    demoCommand: "npm run example:agent:goat",
+    docsPath: "integrations/goat/README.md",
+    hostValidationTarget: "goat-sdk-plugin-install",
+    bestFit: "GOAT finance agents and Solana transaction tools.",
+    primary: true
+  },
+  {
+    id: "vercel-ai-sdk",
+    runtime: "Vercel AI SDK",
+    category: "framework-adapter",
+    packageExport: "@svsprotocol/solana/vercel-ai",
+    exportPath: "./vercel-ai",
+    adapterVersion: "svs.vercel-ai-sdk-adapter.v1",
+    readinessHelper: "requireSvsVercelAiSdkProductionReady",
+    submitHelper: "verifyAndSubmitVercelAiSdkSolanaAction",
+    toolName: "svsVerifyAndSubmitSolanaAction",
+    pluginName: null,
+    actionName: null,
+    demoCommand: "npm run example:agent:vercel-ai",
+    docsPath: "integrations/vercel-ai/README.md",
+    hostValidationTarget: "vercel-ai-sdk-tool-install",
+    bestFit: "AI SDK generateText and streamText tool maps.",
+    primary: true
+  }
+];
+
+export const SVS_AGENT_FRAMEWORK_ADAPTERS = Object.freeze(
+  FRAMEWORK_ADAPTERS.map((adapter) => Object.freeze({ ...adapter }))
+);
+
+export function getSvsAgentFrameworkAdapters({
+  includeCustom = true,
+  primaryOnly = false
+} = {}) {
+  return SVS_AGENT_FRAMEWORK_ADAPTERS
+    .filter((adapter) => includeCustom || adapter.id !== "custom-adapter-core")
+    .filter((adapter) => !primaryOnly || adapter.primary === true)
+    .map((adapter) => ({ ...adapter }));
+}
+
+export function findSvsAgentFrameworkAdapter(identifier) {
+  if (!identifier) {
+    return null;
+  }
+
+  const raw = String(identifier);
+  const foundExact = SVS_AGENT_FRAMEWORK_ADAPTERS.find((adapter) => {
+    const values = getAdapterIdentifierValues(adapter);
+
+    return values.includes(raw);
+  });
+
+  if (foundExact) {
+    return { ...foundExact };
+  }
+
+  const normalized = raw.toLowerCase();
+  const foundNormalized = SVS_AGENT_FRAMEWORK_ADAPTERS.find((adapter) => {
+    const values = getAdapterIdentifierValues(adapter).map((value) => value.toLowerCase());
+
+    return values.includes(normalized);
+  });
+
+  return foundNormalized ? { ...foundNormalized } : null;
+}
+
+function getAdapterIdentifierValues(adapter) {
+  return [
+    adapter.id,
+    adapter.runtime,
+    adapter.packageExport,
+    adapter.exportPath,
+    adapter.toolName,
+    adapter.pluginName,
+    adapter.actionName
+  ].filter(Boolean).map((value) => String(value));
+}

package/dist/adapter-core.d.ts

@@ -0,0 +1,48 @@
+import type {
+  SvsAdapterActionInput,
+  SvsAdapterActionResult,
+  SvsAdapterOptions,
+  SvsAdapterReadinessResult,
+  SvsClientLike
+} from "./common.js";
+
+export class SvsAdapterCoreError extends Error {
+  details: unknown;
+  constructor(message: string, details?: unknown);
+}
+
+export interface SvsAdapterClientOptions {
+  client?: SvsAdapterOptions["client"];
+  baseUrl?: string;
+  apiKey?: string;
+  requestSigningSecret?: string;
+  expectedIntegrationContractHash?: string;
+}
+
+export type SvsAdapterProductionReadinessOptions = SvsAdapterOptions & {
+  runSelfTest?: boolean;
+  pendingProofMaxAgeMs?: number;
+  requireNoExpiredPreviousSigningSecrets?: boolean;
+  readinessVersion?: string;
+  readyMessage?: string;
+  adapterLabel?: string;
+  ErrorClass?: typeof SvsAdapterCoreError;
+};
+
+export type SvsAdapterSolanaActionSubmitOptions = SvsAdapterOptions & SvsAdapterActionInput & {
+  adapterVersion: string;
+  agentFramework: string;
+  resultVersion: string;
+  readinessVersion?: string;
+  readyMessage?: string;
+  adapterLabel?: string;
+  ErrorClass?: typeof SvsAdapterCoreError;
+};
+
+export function createSvsAdapterClient(options?: SvsAdapterClientOptions): SvsClientLike | unknown;
+
+export function requireSvsAdapterProductionReady(options?: SvsAdapterProductionReadinessOptions): Promise<SvsAdapterReadinessResult>;
+
+export function verifyAndSubmitSvsAdapterSolanaAction(options?: SvsAdapterSolanaActionSubmitOptions): Promise<SvsAdapterActionResult>;
+
+export function extractSubmittedRecordId(result: unknown): string | null;

package/dist/adapter-core.js

@@ -0,0 +1,249 @@
+import {
+  SolanaVerificationClient,
+  productionCertificationIsReady
+} from "./index.js";
+
+export class SvsAdapterCoreError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "SvsAdapterCoreError";
+    this.details = details;
+  }
+}
+
+export function createSvsAdapterClient({
+  client = null,
+  baseUrl,
+  apiKey,
+  requestSigningSecret,
+  expectedIntegrationContractHash
+} = {}) {
+  return client ?? new SolanaVerificationClient({
+    baseUrl,
+    apiKey,
+    requestSigningSecret,
+    expectedIntegrationContractHash
+  });
+}
+
+export async function requireSvsAdapterProductionReady({
+  client = null,
+  baseUrl,
+  apiKey,
+  requestSigningSecret,
+  expectedIntegrationContractHash,
+  botId,
+  certificationStaleAfterMs = undefined,
+  requireCurrentIntegrationContract = true,
+  runSelfTest = true,
+  pendingProofMaxAgeMs = undefined,
+  requireNoExpiredPreviousSigningSecrets = true,
+  readinessVersion = "svs.adapter-readiness.v1",
+  readyMessage = "SVS adapter readiness and production certification passed.",
+  adapterLabel = "SVS adapter",
+  ErrorClass = SvsAdapterCoreError
+} = {}) {
+  if (!botId) {
+    throw new Error("botId is required.");
+  }
+
+  const svs = createSvsAdapterClient({
+    client,
+    baseUrl,
+    apiKey,
+    requestSigningSecret,
+    expectedIntegrationContractHash
+  });
+  const readiness = await svs.checkBotReadiness({
+    botId,
+    runSelfTest,
+    pendingProofMaxAgeMs,
+    requireNoExpiredPreviousSigningSecrets
+  });
+
+  if (readiness.ok !== true) {
+    throw new ErrorClass(
+      `SVS bot readiness failed for ${botId}: ${readiness.nextAction?.message ?? readiness.status ?? "not ready"}`,
+      { readiness }
+    );
+  }
+
+  const certification = await svs.requireProductionCertification({
+    botId,
+    staleAfterMs: certificationStaleAfterMs,
+    requireCurrentIntegrationContract
+  });
+
+  if (!productionCertificationIsReady(certification)) {
+    throw new ErrorClass(
+      `SVS production certification failed for ${botId}: ${certification.nextAction?.message ?? certification.status ?? "not certified"}`,
+      {
+        readiness,
+        certification
+      }
+    );
+  }
+
+  return {
+    version: readinessVersion,
+    ok: true,
+    status: "ready",
+    botId: certification.botId ?? readiness.botId ?? botId,
+    readiness,
+    certification,
+    nextAction: {
+      code: "none",
+      message: readyMessage || `${adapterLabel} readiness and production certification passed.`
+    }
+  };
+}
+
+export async function verifyAndSubmitSvsAdapterSolanaAction({
+  client = null,
+  baseUrl,
+  apiKey,
+  requestSigningSecret,
+  expectedIntegrationContractHash,
+  botId,
+  requestId = null,
+  idempotencyKey = requestId,
+  intent,
+  transaction = null,
+  serializedTransaction = transaction?.serializedTransaction ?? transaction,
+  policyId,
+  rpcUrl,
+  simulation = null,
+  metadata = null,
+  source = {},
+  certificationStaleAfterMs = undefined,
+  requireCurrentIntegrationContract = true,
+  waitForProof = false,
+  waitAttempts = 12,
+  waitIntervalMs = 5000,
+  fetchProof = true,
+  checkReceiptRegistryChain = true,
+  requireReadinessOnSubmit = true,
+  adapterVersion,
+  agentFramework,
+  resultVersion,
+  readinessVersion = "svs.adapter-readiness.v1",
+  readyMessage,
+  adapterLabel,
+  ErrorClass = SvsAdapterCoreError
+} = {}) {
+  if (!botId) {
+    throw new Error("botId is required.");
+  }
+
+  if (!intent || typeof intent !== "object") {
+    throw new Error("intent is required.");
+  }
+
+  if (!policyId) {
+    throw new Error("policyId is required.");
+  }
+
+  if (!serializedTransaction) {
+    throw new Error("serializedTransaction is required.");
+  }
+
+  if (!adapterVersion) {
+    throw new Error("adapterVersion is required.");
+  }
+
+  if (!agentFramework) {
+    throw new Error("agentFramework is required.");
+  }
+
+  if (!resultVersion) {
+    throw new Error("resultVersion is required.");
+  }
+
+  const svs = createSvsAdapterClient({
+    client,
+    baseUrl,
+    apiKey,
+    requestSigningSecret,
+    expectedIntegrationContractHash
+  });
+  let readiness = null;
+
+  if (requireReadinessOnSubmit !== false) {
+    readiness = await requireSvsAdapterProductionReady({
+      client: svs,
+      botId,
+      certificationStaleAfterMs,
+      requireCurrentIntegrationContract,
+      readinessVersion,
+      readyMessage,
+      adapterLabel,
+      ErrorClass
+    });
+  }
+
+  const actionPayload = {
+    requestId,
+    idempotencyKey,
+    intent,
+    policyId,
+    simulation,
+    serializedTransaction,
+    rpcUrl,
+    metadata,
+    source: {
+      ...source,
+      submittedBy: source.submittedBy ?? botId,
+      adapter: adapterVersion,
+      agentFramework: source.agentFramework ?? agentFramework
+    }
+  };
+  const result = waitForProof
+    ? await svs.submitCertifiedActionAndWaitForProof(actionPayload, {
+        idempotencyKey,
+        botId,
+        certificationStaleAfterMs,
+        requireCurrentIntegrationContract,
+        waitAttempts,
+        waitIntervalMs,
+        fetchProof,
+        checkReceiptRegistryChain
+      })
+    : await svs.submitCertifiedAction(actionPayload, {
+        idempotencyKey,
+        botId,
+        certificationStaleAfterMs,
+        requireCurrentIntegrationContract
+      });
+
+  return {
+    version: resultVersion,
+    ok: result.ok !== false,
+    status: waitForProof ? result.status : "submitted",
+    botId: result.botId ?? botId,
+    requestId,
+    idempotencyKey,
+    policyId,
+    adapter: adapterVersion,
+    readiness,
+    result,
+    recordId: waitForProof
+      ? result.recordId ?? null
+      : extractSubmittedRecordId(result),
+    productionProofReady: waitForProof
+      ? result.ok === true && result.status === "production_proof_ready"
+      : false,
+    nextAction: result.nextAction ?? {
+      code: "wait_for_human_approval",
+      message: "Wait for human approval, broadcast, registry write, and production proof verification."
+    }
+  };
+}
+
+export function extractSubmittedRecordId(result) {
+  return result?.submitted?.record?.id ??
+    result?.submitted?.queue?.record?.id ??
+    result?.submitted?.recordId ??
+    result?.submitted?.id ??
+    result?.submitted?.action?.id ??
+    null;
+}

package/dist/approval-signature.js

@@ -0,0 +1,197 @@
+import { createHash, createPublicKey, sign, verify } from "node:crypto";
+import { decodeBase58, encodeBase58 } from "./base58.js";
+
+export const APPROVAL_MESSAGE_VERSION = "svs.approval.v1";
+export const APPROVAL_MESSAGE_DOMAIN = "svs-solana-verification-system";
+export const LEGACY_APPROVAL_MESSAGE_DOMAIN = "solana-human-verification-system";
+
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+const VALID_OUTCOMES = new Set(["approved", "rejected", "acknowledged"]);
+const VALID_DOMAINS = new Set([APPROVAL_MESSAGE_DOMAIN, LEGACY_APPROVAL_MESSAGE_DOMAIN]);
+
+export function createApprovalPayload(record, {
+  outcome,
+  reviewedAt,
+  domain = APPROVAL_MESSAGE_DOMAIN
+}) {
+  assertValidOutcome(outcome);
+  assertValidDomain(domain);
+
+  if (!reviewedAt) {
+    throw new Error("reviewedAt is required to create an approval payload.");
+  }
+
+  return {
+    domain,
+    version: APPROVAL_MESSAGE_VERSION,
+    chain: "solana-devnet",
+    recordId: record.id,
+    outcome,
+    controllerWallet: record.intent.controllerWallet,
+    botId: record.intent.botId,
+    txType: record.intent.txType,
+    amountSol: record.intent.amountSol,
+    destinationWallet: record.intent.destinationWallet ?? null,
+    serviceFee: record.serviceFee ?? null,
+    receiptHash: record.receipt.receiptHash,
+    policyHash: record.receipt.policyHash,
+    intentHash: record.receipt.intentHash,
+    simulationHash: record.receipt.simulationHash,
+    reviewedAt
+  };
+}
+
+export function createApprovalMessage(record, { outcome, reviewedAt, domain }) {
+  return JSON.stringify(createApprovalPayload(record, { outcome, reviewedAt, domain }), null, 2);
+}
+
+export function signApproval({
+  record,
+  outcome,
+  reviewedAt = new Date().toISOString(),
+  wallet,
+  domain = APPROVAL_MESSAGE_DOMAIN
+}) {
+  const message = createApprovalMessage(record, { outcome, reviewedAt, domain });
+  const signature = sign(null, Buffer.from(message, "utf8"), wallet.privateKey);
+
+  return {
+    version: APPROVAL_MESSAGE_VERSION,
+    scheme: "ed25519",
+    signer: wallet.publicKey,
+    message,
+    messageHash: hashMessage(message),
+    signature: encodeBase58(signature)
+  };
+}
+
+export function verifyApprovalSignature(record, signedApproval) {
+  if (!signedApproval || typeof signedApproval !== "object") {
+    throw new Error("A signed approval is required.");
+  }
+
+  const payload = parseApprovalMessage(signedApproval.message);
+  const expectedMessage = createApprovalMessage(record, {
+    outcome: payload.outcome,
+    reviewedAt: payload.reviewedAt,
+    domain: payload.domain
+  });
+  const signer = signedApproval.signer ?? payload.controllerWallet;
+
+  if (signedApproval.version && signedApproval.version !== APPROVAL_MESSAGE_VERSION) {
+    throw new Error(`Unsupported approval version: ${signedApproval.version}`);
+  }
+
+  if (signedApproval.scheme && signedApproval.scheme !== "ed25519") {
+    throw new Error(`Unsupported approval signature scheme: ${signedApproval.scheme}`);
+  }
+
+  if (signedApproval.message !== expectedMessage) {
+    throw new Error("Signed approval message does not match this approval record.");
+  }
+
+  if (signedApproval.messageHash && signedApproval.messageHash !== hashMessage(signedApproval.message)) {
+    throw new Error("Signed approval message hash does not match the approval message.");
+  }
+
+  if (signer !== record.intent.controllerWallet) {
+    throw new Error("Signed approval must come from the controller wallet.");
+  }
+
+  const publicKey = createSolanaPublicKey(signer);
+  const signature = decodeBase58(signedApproval.signature);
+  const verified = verify(null, Buffer.from(signedApproval.message, "utf8"), publicKey, signature);
+
+  if (!verified) {
+    throw new Error("Approval signature verification failed.");
+  }
+
+  return {
+    version: APPROVAL_MESSAGE_VERSION,
+    scheme: "ed25519",
+    signer,
+    message: signedApproval.message,
+    messageHash: hashMessage(signedApproval.message),
+    signature: signedApproval.signature,
+    verified: true,
+    payload
+  };
+}
+
+export function summarizeApprovalDomain(signatureOrPayload) {
+  const domain = extractApprovalDomain(signatureOrPayload);
+  const status = domain === APPROVAL_MESSAGE_DOMAIN
+    ? "current"
+    : domain === LEGACY_APPROVAL_MESSAGE_DOMAIN
+      ? "legacy_compatible"
+      : domain
+        ? "unsupported"
+        : "missing";
+
+  return {
+    domain,
+    status,
+    current: status === "current",
+    legacyCompatible: status === "legacy_compatible",
+    supported: status === "current" || status === "legacy_compatible"
+  };
+}
+
+function parseApprovalMessage(message) {
+  if (typeof message !== "string" || message.length === 0) {
+    throw new Error("Signed approval message is required.");
+  }
+
+  const payload = JSON.parse(message);
+
+  if (payload.version !== APPROVAL_MESSAGE_VERSION) {
+    throw new Error(`Unsupported approval message version: ${payload.version}`);
+  }
+
+  assertValidOutcome(payload.outcome);
+  assertValidDomain(payload.domain);
+
+  return payload;
+}
+
+function extractApprovalDomain(signatureOrPayload) {
+  if (!signatureOrPayload || typeof signatureOrPayload !== "object") return null;
+  if (signatureOrPayload.domain) return signatureOrPayload.domain;
+  if (!signatureOrPayload.message) return null;
+
+  try {
+    return JSON.parse(signatureOrPayload.message)?.domain ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function createSolanaPublicKey(publicKey) {
+  const publicKeyBytes = decodeBase58(publicKey);
+
+  if (publicKeyBytes.length !== 32) {
+    throw new Error("Controller wallet public key must decode to 32 bytes.");
+  }
+
+  return createPublicKey({
+    key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(publicKeyBytes)]),
+    format: "der",
+    type: "spki"
+  });
+}
+
+function hashMessage(message) {
+  return createHash("sha256").update(message).digest("hex");
+}
+
+function assertValidOutcome(outcome) {
+  if (!VALID_OUTCOMES.has(outcome)) {
+    throw new Error("Review outcome must be approved, rejected, or acknowledged.");
+  }
+}
+
+function assertValidDomain(domain) {
+  if (!VALID_DOMAINS.has(domain)) {
+    throw new Error(`Unsupported approval message domain: ${domain ?? "missing"}.`);
+  }
+}

package/dist/base58.js

@@ -0,0 +1,69 @@
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const BASE = BigInt(ALPHABET.length);
+const LOOKUP = new Map([...ALPHABET].map((char, index) => [char, BigInt(index)]));
+
+export function encodeBase58(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError("encodeBase58 expects a Uint8Array.");
+  }
+
+  let value = 0n;
+
+  for (const byte of bytes) {
+    value = value * 256n + BigInt(byte);
+  }
+
+  let encoded = "";
+
+  while (value > 0n) {
+    const remainder = value % BASE;
+    value /= BASE;
+    encoded = ALPHABET[Number(remainder)] + encoded;
+  }
+
+  for (const byte of bytes) {
+    if (byte !== 0) {
+      break;
+    }
+
+    encoded = "1" + encoded;
+  }
+
+  return encoded || "1";
+}
+
+export function decodeBase58(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("decodeBase58 expects a non-empty string.");
+  }
+
+  let decoded = 0n;
+
+  for (const char of value) {
+    const index = LOOKUP.get(char);
+
+    if (index === undefined) {
+      throw new Error(`Invalid base58 character: ${char}`);
+    }
+
+    decoded = decoded * BASE + index;
+  }
+
+  const bytes = [];
+
+  while (decoded > 0n) {
+    bytes.unshift(Number(decoded % 256n));
+    decoded /= 256n;
+  }
+
+  for (const char of value) {
+    if (char !== "1") {
+      break;
+    }
+
+    bytes.unshift(0);
+  }
+
+  return Uint8Array.from(bytes);
+}
+