@svsprotocol/solana 0.1.0

package/dist/svs-client.js

@@ -0,0 +1,1232 @@
+import { randomUUID } from "node:crypto";
+import http from "node:http";
+import https from "node:https";
+import { createBotRequestSignature } from "./bot-auth.js";
+import {
+  BOT_INTEGRATION_CONTRACT_VERSION,
+  BOT_INTEGRATION_QUICKSTART_VERSION,
+  hashBotIntegrationContract
+} from "./bot-integration-contract.js";
+
+export const BOT_CLIENT_COMPATIBILITY_VERSION = "svs.bot-client-compatibility.v1";
+export const BOT_CLIENT_RETRY_SAFETY_VERSION = "svs.bot-client-retry-safety.v1";
+export const SOLANA_VERIFICATION_CLIENT_NAME = "SolanaVerificationClient";
+export const SOLANA_VERIFICATION_CLIENT_VERSION = "svs-js-client.v1";
+export const SOLANA_VERIFICATION_CLIENT_CAPABILITIES = Object.freeze([
+  "fetchIntegrationContract",
+  "createSignedBotRequest",
+  "submitSignedAction",
+  "autoNonceForSignedAction",
+  "retrySafeIdempotentSubmit",
+  "signedSelfTest",
+  "credentialReadiness",
+  "credentialRotationReceipt",
+  "credentialRotationReadinessCheck",
+  "combinedReadinessCheck",
+  "certificationStatus",
+  "certificationQualityTarget",
+  "productionCertificationGuard",
+  "certifiedSubmitStatus",
+  "certifiedActionSubmit",
+  "certifiedActionSubmitAndWaitForProof",
+  "actionProductionProofStatus",
+  "actionProductionProofFetch"
+]);
+
+const DEFAULT_RETRYABLE_STATUSES = Object.freeze([408, 429, 500, 502, 503, 504]);
+const DEFAULT_RETRY_OPTIONS = Object.freeze({
+  maxRetries: 2,
+  baseDelayMs: 100,
+  maxDelayMs: 1000,
+  retryableStatuses: DEFAULT_RETRYABLE_STATUSES
+});
+
+export function createSignedBotRequest({
+  body,
+  requestSigningSecret,
+  timestamp = new Date().toISOString(),
+  headers = {}
+} = {}) {
+  if (!requestSigningSecret) {
+    throw new Error("requestSigningSecret is required.");
+  }
+
+  const rawBody = body === undefined || body === null
+    ? ""
+    : typeof body === "string"
+      ? body
+      : JSON.stringify(body);
+
+  return {
+    body: rawBody,
+    headers: {
+      ...headers,
+      "svs-request-timestamp": timestamp,
+      "svs-request-signature": createBotRequestSignature({
+        body: rawBody,
+        timestamp,
+        secret: requestSigningSecret
+      })
+    }
+  };
+}
+
+export class SolanaVerificationClient {
+  constructor({
+    baseUrl = "http://127.0.0.1:4173",
+    apiKey = null,
+    requestSigningSecret = null,
+    expectedIntegrationContractHash = null,
+    timestampProvider = () => new Date().toISOString(),
+    fetchImpl = globalThis.fetch,
+    retry = {},
+    sleep = defaultSleep
+  } = {}) {
+    if (!fetchImpl) {
+      throw new Error("fetch is required.");
+    }
+
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+    this.requestSigningSecret = requestSigningSecret;
+    this.expectedIntegrationContractHash = expectedIntegrationContractHash;
+    this.timestampProvider = timestampProvider;
+    this.fetchImpl = fetchImpl;
+    this.usesDefaultFetch = fetchImpl === globalThis.fetch;
+    this.retry = normalizeRetryOptions(retry);
+    this.sleep = sleep;
+  }
+
+  submitAction(payload, {
+    idempotencyKey = payload?.idempotencyKey ?? payload?.requestId,
+    requestSigningSecret = this.requestSigningSecret,
+    requestTimestamp = null,
+    requestNonce = null,
+    retry = undefined
+  } = {}) {
+    const shouldSign = Boolean(requestSigningSecret);
+    const body = shouldSign && payload && typeof payload === "object" && !payload.requestNonce
+      ? { ...payload, requestNonce: requestNonce ?? randomUUID() }
+      : payload;
+
+    return this.request("/api/actions", {
+      method: "POST",
+      body,
+      headers: idempotencyKey
+        ? { "idempotency-key": idempotencyKey }
+        : undefined,
+      requestSigningSecret,
+      requestTimestamp,
+      signRequest: shouldSign,
+      retry,
+      retrySafe: Boolean(idempotencyKey)
+    });
+  }
+
+  getRetrySafetyProof() {
+    return createSolanaVerificationClientRetrySafetyProof({
+      retry: this.retry
+    });
+  }
+
+  getIntegrationContract() {
+    return this.request("/api/bots/integration-contract");
+  }
+
+  async checkClientCompatibility({ contract = null } = {}) {
+    const liveContract = contract ?? await this.getIntegrationContract();
+
+    return createSolanaVerificationClientCompatibilityReport({ contract: liveContract });
+  }
+
+  getCredentialReadiness(options = {}) {
+    const params = new URLSearchParams();
+
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        params.set(key, String(value));
+      }
+    }
+
+    const query = params.toString();
+
+    return this.request(`/api/bots/credential-readiness${query ? `?${query}` : ""}`);
+  }
+
+  getCredentialRotationReceipt({
+    botId,
+    pendingProofMaxAgeMs = undefined
+  } = {}) {
+    if (!botId) {
+      throw new Error("botId is required.");
+    }
+
+    const params = new URLSearchParams();
+
+    if (pendingProofMaxAgeMs !== undefined && pendingProofMaxAgeMs !== null) {
+      params.set("pendingProofMaxAgeMs", String(pendingProofMaxAgeMs));
+    }
+
+    const query = params.toString();
+
+    return this.request(`/api/bots/${encodeURIComponent(botId)}/request-signing-rotation-receipt${query ? `?${query}` : ""}`);
+  }
+
+  async checkCredentialRotationReadiness({
+    botId,
+    pendingProofMaxAgeMs = undefined
+  } = {}) {
+    const checkedAt = this.timestampProvider();
+    const receipt = await this.getCredentialRotationReceipt({
+      botId,
+      pendingProofMaxAgeMs
+    });
+    const missingProof = Array.isArray(receipt.missingProof) ? receipt.missingProof : [];
+    const firstMissing = missingProof[0] ?? null;
+    const readyToPromote = receipt.readyToPromote === true;
+    const nextAction = receipt.nextAction ?? firstMissing?.nextAction ?? {
+      code: readyToPromote ? "operator_promote_pending_secret" : "rotation_not_ready",
+      message: readyToPromote
+        ? "Send this non-secret rotation receipt to the operator so they can promote the pending signing secret."
+        : "Complete the missing credential-rotation proof before promotion."
+    };
+    const operatorSteps = firstMissing && Array.isArray(firstMissing.operatorSteps)
+      ? firstMissing.operatorSteps
+      : readyToPromote
+        ? [
+            "Send this receipt to the operator.",
+            "Ask the operator to import the receipt in the dashboard.",
+            "Wait for the operator to promote the pending signing secret."
+          ]
+        : [];
+
+    return {
+      version: "svs.bot-credential-rotation-readiness-check.v1",
+      checkedAt,
+      ok: readyToPromote,
+      status: readyToPromote ? "ready_to_promote" : receipt.status ?? "not_ready",
+      botId: receipt.botId ?? botId ?? null,
+      readyToPromote,
+      receiptHash: receipt.receiptHash ?? null,
+      receipt,
+      missingProof,
+      nextAction,
+      operatorSteps
+    };
+  }
+
+  getIntegrationCertificationStatus({
+    botId,
+    staleAfterMs = undefined
+  } = {}) {
+    if (!botId) {
+      throw new Error("botId is required.");
+    }
+
+    const params = new URLSearchParams();
+
+    if (staleAfterMs !== undefined && staleAfterMs !== null) {
+      params.set("staleAfterMs", String(staleAfterMs));
+    }
+
+    const query = params.toString();
+
+    return this.request(`/api/bots/${encodeURIComponent(botId)}/integration-certification/status${query ? `?${query}` : ""}`);
+  }
+
+  selfTest({
+    botId = null,
+    requestNonce = null,
+    requestSigningSecret = this.requestSigningSecret,
+    requestTimestamp = null
+  } = {}) {
+    return this.request("/api/bots/self-test", {
+      method: "POST",
+      body: {
+        kind: "svs.bot-self-test-request.v1",
+        botId,
+        requestNonce: requestNonce ?? randomUUID()
+      },
+      requestSigningSecret,
+      requestTimestamp,
+      signRequest: Boolean(requestSigningSecret)
+    });
+  }
+
+  async checkBotReadiness({
+    botId = null,
+    runSelfTest = true,
+    pendingProofMaxAgeMs = undefined,
+    requireNoExpiredPreviousSigningSecrets = true,
+    requestSigningSecret = this.requestSigningSecret,
+    requestTimestamp = null,
+    requestNonce = null
+  } = {}) {
+    const checkedAt = this.timestampProvider();
+    let selfTest = null;
+
+    if (runSelfTest) {
+      try {
+        selfTest = await this.selfTest({
+          botId,
+          requestNonce,
+          requestSigningSecret,
+          requestTimestamp
+        });
+      } catch (error) {
+        selfTest = {
+          ok: false,
+          status: "failed",
+          error: error.message
+        };
+      }
+    }
+
+    const readiness = await this.getCredentialReadiness({
+      pendingProofMaxAgeMs,
+      requireNoExpiredPreviousSigningSecrets
+    });
+    const bot = selectReadinessBot(readiness, botId);
+    const selfTestOk = runSelfTest ? selfTest?.ok === true : true;
+    const readinessOk = bot ? bot.productionReady === true : readiness.productionReady === true;
+    const ok = selfTestOk && readinessOk;
+
+    return {
+      version: "svs.bot-readiness-check.v1",
+      checkedAt,
+      ok,
+      status: ok ? "ready" : "not_ready",
+      botId: bot?.botId ?? botId ?? null,
+      selfTest: runSelfTest ? selfTest : null,
+      readiness: {
+        version: readiness.version ?? null,
+        productionReady: readiness.productionReady === true,
+        activeBotCount: readiness.summary?.activeBotCount ?? null,
+        adoptionAverageScore: readiness.summary?.adoptionAverageScore ?? null,
+        adoptionNeedsActionCount: readiness.summary?.adoptionNeedsActionCount ?? null
+      },
+      bot: bot ? summarizeReadinessBot(bot) : null,
+      adoption: bot?.adoption ?? null,
+      nextAction: createReadinessNextAction({ bot, readiness, selfTest, runSelfTest })
+    };
+  }
+
+  async checkProductionCertification({
+    botId,
+    staleAfterMs = undefined,
+    requireCurrentIntegrationContract = true,
+    expectedIntegrationContractHash = this.expectedIntegrationContractHash
+  } = {}) {
+    const checkedAt = this.timestampProvider();
+    const certification = await this.getIntegrationCertificationStatus({
+      botId,
+      staleAfterMs
+    });
+    const integrationContract = await this.checkProductionCertificationContractBinding({
+      certification,
+      required: requireCurrentIntegrationContract,
+      expectedIntegrationContractHash
+    });
+    const ok = certification.ok === true && integrationContract.ok === true;
+    const nextAction = certification.nextAction ?? {
+      code: certification.ok === true ? "none" : "certification_not_ready",
+      message: certification.ok === true
+        ? "Bot certification is current."
+        : "Ask the operator to persist fresh bot integration certification evidence."
+    };
+
+    return {
+      version: "svs.bot-production-certification-check.v1",
+      checkedAt,
+      ok,
+      status: ok ? "ready" : "not_ready",
+      botId: certification.botId ?? botId ?? null,
+      certification,
+      integrationContract,
+      quality: certification.quality ?? certification.certification?.quality ?? null,
+      qualityTarget: certification.qualityTarget ?? null,
+      nextAction: integrationContract.ok === false
+        ? {
+            code: "integration_contract_mismatch",
+            message: integrationContract.nextActionMessage
+          }
+        : nextAction
+    };
+  }
+
+  async checkProductionCertificationContractBinding({
+    certification,
+    required = true,
+    expectedIntegrationContractHash = this.expectedIntegrationContractHash
+  } = {}) {
+    if (!required) {
+      return {
+        version: "svs.production-certification-contract-binding.v1",
+        required: false,
+        ok: true,
+        status: "not_required",
+        localContractHash: null,
+        certifiedContractHash: certification?.proofs?.integrationContractHash ??
+          certification?.contract?.certifiedHash ??
+          certification?.certification?.evidence?.integrationContractHash ??
+          null,
+        currentContractHash: certification?.proofs?.currentIntegrationContractHash ??
+          certification?.contract?.currentHash ??
+          null,
+        drifted: certification?.contract?.drifted === true,
+        nextActionMessage: "Integration contract binding check was not required."
+      };
+    }
+
+    try {
+      const contract = await this.getIntegrationContract();
+      const dashboardContractHash = hashBotIntegrationContract(contract);
+      const localContractHash = expectedIntegrationContractHash ?? dashboardContractHash;
+      const certifiedContractHash = certification?.proofs?.integrationContractHash ??
+        certification?.contract?.certifiedHash ??
+        certification?.certification?.evidence?.integrationContractHash ??
+        null;
+      const currentContractHash = certification?.proofs?.currentIntegrationContractHash ??
+        certification?.contract?.currentHash ??
+        null;
+      const drifted = certification?.contract?.drifted === true ||
+        certification?.proofs?.integrationContractCurrent === false;
+      const ok = Boolean(localContractHash) &&
+        dashboardContractHash === localContractHash &&
+        certifiedContractHash === localContractHash &&
+        (!currentContractHash || currentContractHash === localContractHash) &&
+        !drifted;
+      const status = ok
+        ? "current"
+        : dashboardContractHash !== localContractHash
+          ? "client_contract_mismatch"
+          : drifted
+            ? "drifted"
+            : "mismatch";
+
+      return {
+        version: "svs.production-certification-contract-binding.v1",
+        required: true,
+        ok,
+        status,
+        localContractHash,
+        dashboardContractHash,
+        certifiedContractHash,
+        currentContractHash,
+        drifted,
+        contractVersion: contract?.version ?? null,
+        nextActionMessage: ok
+          ? "Bot integration certification matches the current integration contract."
+          : status === "client_contract_mismatch"
+            ? `Update the bot client integration contract before production submit. local=${shortHash(localContractHash)} dashboard=${shortHash(dashboardContractHash)} certified=${shortHash(certifiedContractHash)}.`
+            : `Refresh bot integration certification before production submit. local=${shortHash(localContractHash)} certified=${shortHash(certifiedContractHash)} current=${shortHash(currentContractHash)}.`
+      };
+    } catch (error) {
+      return {
+        version: "svs.production-certification-contract-binding.v1",
+        required: true,
+        ok: false,
+        status: "unavailable",
+        localContractHash: null,
+        certifiedContractHash: certification?.proofs?.integrationContractHash ??
+          certification?.contract?.certifiedHash ??
+          certification?.certification?.evidence?.integrationContractHash ??
+          null,
+        currentContractHash: certification?.proofs?.currentIntegrationContractHash ??
+          certification?.contract?.currentHash ??
+          null,
+        drifted: certification?.contract?.drifted === true,
+        error: error.message,
+        nextActionMessage: `Fetch the live bot integration contract before production submit: ${error.message}`
+      };
+    }
+  }
+
+  async requireProductionCertification({
+    botId,
+    staleAfterMs = undefined,
+    requireCurrentIntegrationContract = true
+  } = {}) {
+    const result = await this.checkProductionCertification({
+      botId,
+      staleAfterMs,
+      requireCurrentIntegrationContract
+    });
+
+    if (!productionCertificationIsReady(result)) {
+      throw new SolanaVerificationProductionCertificationError(
+        createProductionCertificationFailureMessage(result),
+        { certificationCheck: result }
+      );
+    }
+
+    return result;
+  }
+
+  async submitCertifiedAction(payload, {
+    botId = payload?.source?.submittedBy ?? payload?.intent?.botId ?? null,
+    certificationStaleAfterMs = undefined,
+    requireCurrentIntegrationContract = true,
+    ...submitOptions
+  } = {}) {
+    const certification = await this.requireProductionCertification({
+      botId,
+      staleAfterMs: certificationStaleAfterMs,
+      requireCurrentIntegrationContract
+    });
+    const submitted = await this.submitAction({
+      ...payload,
+      source: {
+        ...(payload?.source ?? {}),
+        submittedBy: payload?.source?.submittedBy ?? botId ?? payload?.intent?.botId ?? null,
+        productionCertification: createProductionCertificationSourceProof({
+          certification,
+          staleAfterMs: certificationStaleAfterMs,
+          integrationContract: certification.integrationContract
+        })
+      }
+    }, submitOptions);
+
+    return {
+      version: "svs.certified-action-submission.v1",
+      ok: true,
+      status: "submitted",
+      botId: certification.botId ?? botId ?? null,
+      certification,
+      submitted
+    };
+  }
+
+  getCertifiedSubmitStatus({
+    staleAfterMs = undefined
+  } = {}) {
+    const params = new URLSearchParams();
+
+    if (staleAfterMs !== undefined && staleAfterMs !== null) {
+      params.set("staleAfterMs", String(staleAfterMs));
+    }
+
+    const query = params.toString();
+
+    return this.request(`/api/bots/certified-submit-status${query ? `?${query}` : ""}`);
+  }
+
+  async submitCertifiedActionAndWaitForProof(payload, {
+    botId = payload?.source?.submittedBy ?? payload?.intent?.botId ?? null,
+    certificationStaleAfterMs = undefined,
+    requireCurrentIntegrationContract = true,
+    waitAttempts = 12,
+    waitIntervalMs = 5000,
+    fetchProof = true,
+    checkReceiptRegistryChain = false,
+    ...submitOptions
+  } = {}) {
+    const submission = await this.submitCertifiedAction(payload, {
+      botId,
+      certificationStaleAfterMs,
+      requireCurrentIntegrationContract,
+      ...submitOptions
+    });
+    const recordId = getCertifiedSubmissionRecordId(submission);
+
+    if (!recordId) {
+      return {
+        version: "svs.certified-action-production-proof-wait.v1",
+        ok: false,
+        status: "submitted_record_missing",
+        botId: submission.botId ?? botId ?? null,
+        recordId: null,
+        submission,
+        productionProof: null,
+        nextAction: {
+          code: "record_id_missing",
+          message: "SVS accepted the certified action, but the response did not include a queued record id to poll."
+        }
+      };
+    }
+
+    const productionProof = await this.waitForActionProductionProof(recordId, {
+      attempts: waitAttempts,
+      intervalMs: waitIntervalMs,
+      fetchProof,
+      checkReceiptRegistryChain
+    });
+    const proofStatus = fetchProof ? productionProof?.status : productionProof;
+    const ready = proofStatus?.ready === true;
+    const proofFetched = !fetchProof || Boolean(productionProof?.proof);
+
+    return {
+      version: "svs.certified-action-production-proof-wait.v1",
+      ok: ready && proofFetched,
+      status: ready && proofFetched ? "production_proof_ready" : "production_proof_not_ready",
+      botId: submission.botId ?? botId ?? null,
+      recordId,
+      submission,
+      productionProof,
+      nextAction: ready && proofFetched
+        ? {
+            code: "none",
+            message: "Production proof is ready."
+          }
+        : proofStatus?.nextAction ?? {
+            code: "wait_for_human_approval",
+            message: "Wait for human approval, broadcast, custom registry registration, and production proof readiness."
+          }
+    };
+  }
+
+  getAction(id) {
+    return this.request(`/api/actions/${encodeURIComponent(id)}`);
+  }
+
+  getActionProductionProofStatus(id, {
+    signRequest = Boolean(this.requestSigningSecret),
+    requestSigningSecret = this.requestSigningSecret,
+    requestTimestamp = null
+  } = {}) {
+    if (!id) {
+      throw new Error("id is required.");
+    }
+
+    return this.request(`/api/actions/${encodeURIComponent(id)}/production-proof-status`, {
+      signRequest,
+      requestSigningSecret,
+      requestTimestamp
+    });
+  }
+
+  getActionProductionProof(id, {
+    checkReceiptRegistryChain = false,
+    signRequest = Boolean(this.requestSigningSecret),
+    requestSigningSecret = this.requestSigningSecret,
+    requestTimestamp = null
+  } = {}) {
+    if (!id) {
+      throw new Error("id is required.");
+    }
+
+    const params = new URLSearchParams();
+    params.set("checkReceiptRegistryChain", checkReceiptRegistryChain ? "true" : "false");
+
+    return this.request(`/api/actions/${encodeURIComponent(id)}/production-proof?${params.toString()}`, {
+      signRequest,
+      requestSigningSecret,
+      requestTimestamp
+    });
+  }
+
+  async waitForActionProductionProof(id, {
+    attempts = 12,
+    intervalMs = 5000,
+    fetchProof = false,
+    checkReceiptRegistryChain = false
+  } = {}) {
+    if (!id) {
+      throw new Error("id is required.");
+    }
+
+    let lastStatus = null;
+
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      lastStatus = await this.getActionProductionProofStatus(id);
+
+      if (lastStatus.ready === true) {
+        return fetchProof
+          ? {
+              status: lastStatus,
+              proof: await this.getActionProductionProof(id, { checkReceiptRegistryChain })
+            }
+          : lastStatus;
+      }
+
+      if (attempt < attempts) {
+        await this.sleep(intervalMs);
+      }
+    }
+
+    return fetchProof
+      ? {
+          status: lastStatus,
+          proof: null
+        }
+      : lastStatus;
+  }
+
+  getReceipt(id) {
+    return this.request(`/api/actions/${encodeURIComponent(id)}/receipt`);
+  }
+
+  verifyReceipt(receipt, options = {}) {
+    return this.request("/api/verify-receipt", {
+      method: "POST",
+      body: {
+        receipt,
+        ...options
+      }
+    });
+  }
+
+  verifyActionReceipt(id, options = {}) {
+    return this.request(`/api/actions/${encodeURIComponent(id)}/verify-receipt`, {
+      method: "POST",
+      body: options
+    });
+  }
+
+  async request(path, {
+    method = "GET",
+    body = null,
+    headers: extraHeaders = {},
+    requestSigningSecret = this.requestSigningSecret,
+    requestTimestamp = null,
+    signRequest = false,
+    retry = undefined,
+    retrySafe = false
+  } = {}) {
+    const headers = { ...extraHeaders };
+    const hasBody = body !== null && body !== undefined;
+    let rawBody = hasBody ? JSON.stringify(body) : undefined;
+
+    if (hasBody) {
+      headers["content-type"] = "application/json";
+    }
+
+    if (this.apiKey) {
+      headers.authorization = `Bearer ${this.apiKey}`;
+    }
+
+    if (signRequest) {
+      const signed = createSignedBotRequest({
+        body: rawBody ?? "",
+        requestSigningSecret,
+        timestamp: requestTimestamp ?? this.timestampProvider(),
+        headers
+      });
+
+      if (hasBody) {
+        rawBody = signed.body;
+      }
+      Object.assign(headers, signed.headers);
+    }
+
+    const requestOptions = {
+      method,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+      body: rawBody
+    };
+    const retryOptions = normalizeRetryOptions(retry, this.retry);
+    const maxAttempts = Math.max(1, retryOptions.maxRetries + 1);
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      try {
+        const requestUrl = `${this.baseUrl}${path}`;
+        const response = await this.fetchWithLocalFallback(requestUrl, requestOptions);
+        const text = await response.text();
+        const data = text ? JSON.parse(text) : null;
+
+        if (response.ok) {
+          return data;
+        }
+
+        const error = new SolanaVerificationRequestError(data?.error ?? `SVS request failed with HTTP ${response.status}`, {
+          status: response.status,
+          data,
+          attempt,
+          retryable: retryOptions.retryableStatuses.includes(response.status)
+        });
+
+        if (!shouldRetryRequest({
+          error,
+          attempt,
+          maxAttempts,
+          retrySafe
+        })) {
+          throw decorateUnsafeRetryError(error, { retrySafe });
+        }
+
+        lastError = error;
+      } catch (error) {
+        const requestError = error instanceof SolanaVerificationRequestError
+          ? error
+          : new SolanaVerificationRequestError(error.message ?? "SVS request failed.", {
+              cause: error,
+              attempt,
+              retryable: true
+            });
+
+        if (!shouldRetryRequest({
+          error: requestError,
+          attempt,
+          maxAttempts,
+          retrySafe
+        })) {
+          throw decorateUnsafeRetryError(requestError, { retrySafe });
+        }
+
+        lastError = requestError;
+      }
+
+      await this.sleep(calculateRetryDelayMs({
+        attempt,
+        baseDelayMs: retryOptions.baseDelayMs,
+        maxDelayMs: retryOptions.maxDelayMs
+      }));
+    }
+
+    throw lastError;
+  }
+
+  async fetchWithLocalFallback(url, requestOptions) {
+    try {
+      return await this.fetchImpl(url, requestOptions);
+    } catch (error) {
+      if (!this.usesDefaultFetch || !shouldUseNodeHttpFallback(url)) {
+        throw error;
+      }
+
+      return nodeHttpFetch(url, requestOptions);
+    }
+  }
+}
+
+export class SolanaVerificationRequestError extends Error {
+  constructor(message, {
+    status = null,
+    data = null,
+    attempt = null,
+    attempts = null,
+    retryable = false,
+    retrySkippedReason = null,
+    cause = null
+  } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "SolanaVerificationRequestError";
+    this.status = status;
+    this.data = data;
+    this.attempt = attempt;
+    this.attempts = attempts ?? attempt;
+    this.retryable = retryable;
+    this.retrySkippedReason = retrySkippedReason;
+  }
+}
+
+export class SolanaVerificationProductionCertificationError extends Error {
+  constructor(message, { certificationCheck = null } = {}) {
+    super(message);
+    this.name = "SolanaVerificationProductionCertificationError";
+    this.certificationCheck = certificationCheck;
+    this.qualityTarget = certificationCheck?.qualityTarget ?? null;
+    this.nextAction = certificationCheck?.nextAction ?? null;
+  }
+}
+
+export function productionCertificationIsReady(result) {
+  const target = result?.qualityTarget;
+  const integrationContractOk = result?.integrationContract
+    ? result.integrationContract.ok === true
+    : true;
+
+  return result?.ok === true &&
+    integrationContractOk &&
+    target?.ready === true &&
+    Number.isInteger(target.score) &&
+    Number.isInteger(target.targetScore) &&
+    target.score === target.targetScore &&
+    target.status === "excellent";
+}
+
+export function createSolanaVerificationClientRetrySafetyProof({
+  retry = DEFAULT_RETRY_OPTIONS
+} = {}) {
+  const retryOptions = normalizeRetryOptions(retry);
+  const preservedAcrossRetries = [
+    "rawJsonBody",
+    "requestTimestamp",
+    "requestNonce",
+    "hmacSignature",
+    "idempotencyKey"
+  ];
+  const supported = SOLANA_VERIFICATION_CLIENT_CAPABILITIES.includes("retrySafeIdempotentSubmit") &&
+    retryOptions.maxRetries > 0 &&
+    retryOptions.retryableStatuses.length > 0;
+
+  return {
+    version: BOT_CLIENT_RETRY_SAFETY_VERSION,
+    supported,
+    status: supported ? "ready" : "disabled",
+    clientName: SOLANA_VERIFICATION_CLIENT_NAME,
+    clientVersion: SOLANA_VERIFICATION_CLIENT_VERSION,
+    capability: "retrySafeIdempotentSubmit",
+    maxRetries: retryOptions.maxRetries,
+    retryableStatuses: retryOptions.retryableStatuses,
+    mutationPolicy: {
+      requiresIdempotencyKey: true,
+      idempotencySources: [
+        "Idempotency-Key header",
+        "idempotencyKey body field",
+        "requestId body field"
+      ],
+      unsafeRetrySkippedReason: "idempotency_key_required",
+      preservedAcrossRetries
+    },
+    nextAction: supported
+      ? {
+          code: "none",
+          message: "Client retries transient submit failures only when a stable idempotency key is present."
+        }
+      : {
+          code: "retry_safety_disabled",
+          message: "Enable client retry options and use stable requestId or idempotencyKey values before production bot submissions."
+        }
+  };
+}
+
+function createProductionCertificationFailureMessage(result) {
+  const target = result?.qualityTarget;
+  const score = Number.isInteger(target?.score) ? target.score : "missing";
+  const targetScore = Number.isInteger(target?.targetScore)
+    ? target.targetScore
+    : Number.isInteger(target?.maxScore)
+      ? target.maxScore
+      : "missing";
+  const status = target?.status ?? result?.status ?? "missing";
+  const ready = target?.ready === true ? "ready" : "not ready";
+  const nextAction = result?.nextAction?.message ?? "Ask the operator to certify the bot integration path.";
+  const contract = result?.integrationContract?.required
+    ? ` contract=${result.integrationContract.status ?? "unknown"} local=${shortHash(result.integrationContract.localContractHash)} dashboard=${shortHash(result.integrationContract.dashboardContractHash)} certified=${shortHash(result.integrationContract.certifiedContractHash)}`
+    : "";
+
+  return `SVS production certification is required before submitting bot actions: quality=${score}/${targetScore} ${status} (${ready})${contract}. Next action: ${nextAction}`;
+}
+
+function createProductionCertificationSourceProof({
+  certification,
+  integrationContract = null,
+  staleAfterMs = undefined
+} = {}) {
+  const target = certification?.qualityTarget ?? null;
+  const certificationArtifact = certification?.certification?.certification ?? certification?.certification ?? certification;
+
+  return {
+    version: "svs.production-certification-source-proof.v1",
+    clientGuard: "SolanaVerificationClient.submitCertifiedAction",
+    verified: true,
+    checkedAt: certification?.checkedAt ?? null,
+    botId: certification?.botId ?? null,
+    status: certification?.status ?? null,
+    certificationHash: certificationArtifact?.certificationHash ?? null,
+    recordId: certificationArtifact?.recordId ?? null,
+    staleAfterMs: staleAfterMs ?? null,
+    integrationContract: integrationContract
+      ? {
+          required: integrationContract.required === true,
+          ok: integrationContract.ok === true,
+          status: integrationContract.status ?? null,
+          localContractHash: integrationContract.localContractHash ?? null,
+          dashboardContractHash: integrationContract.dashboardContractHash ?? null,
+          certifiedContractHash: integrationContract.certifiedContractHash ?? null,
+          currentContractHash: integrationContract.currentContractHash ?? null,
+          drifted: integrationContract.drifted === true
+        }
+      : null,
+    qualityTarget: target
+      ? {
+          ready: target.ready === true,
+          score: Number.isInteger(target.score) ? target.score : null,
+          targetScore: Number.isInteger(target.targetScore) ? target.targetScore : null,
+          status: target.status ?? null
+        }
+      : null
+  };
+}
+
+function shortHash(value) {
+  return value ? `${String(value).slice(0, 12)}...` : "missing";
+}
+
+function normalizeRetryOptions(options = {}, fallback = DEFAULT_RETRY_OPTIONS) {
+  if (options === false) {
+    return {
+      ...fallback,
+      retryableStatuses: [...fallback.retryableStatuses],
+      maxRetries: 0
+    };
+  }
+
+  const source = options === true || options === undefined || options === null
+    ? {}
+    : options;
+  const fallbackStatuses = Array.isArray(fallback.retryableStatuses)
+    ? fallback.retryableStatuses
+    : DEFAULT_RETRYABLE_STATUSES;
+  const retryableStatuses = Array.isArray(source.retryableStatuses)
+    ? source.retryableStatuses
+    : fallbackStatuses;
+  const maxRetries = normalizeNonNegativeInteger(source.maxRetries, fallback.maxRetries ?? DEFAULT_RETRY_OPTIONS.maxRetries);
+  const baseDelayMs = normalizeNonNegativeInteger(source.baseDelayMs, fallback.baseDelayMs ?? DEFAULT_RETRY_OPTIONS.baseDelayMs);
+  const maxDelayMs = normalizeNonNegativeInteger(source.maxDelayMs, fallback.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs);
+
+  return {
+    maxRetries,
+    baseDelayMs,
+    maxDelayMs,
+    retryableStatuses: [...new Set(retryableStatuses.map((status) => Number(status)).filter(Number.isInteger))]
+  };
+}
+
+function normalizeNonNegativeInteger(value, fallback) {
+  const parsed = Number(value);
+
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+
+  return Math.floor(parsed);
+}
+
+function shouldRetryRequest({
+  error,
+  attempt,
+  maxAttempts,
+  retrySafe
+} = {}) {
+  return retrySafe === true &&
+    error?.retryable === true &&
+    attempt < maxAttempts;
+}
+
+function decorateUnsafeRetryError(error, { retrySafe } = {}) {
+  if (error?.retryable === true && retrySafe !== true && !error.retrySkippedReason) {
+    error.retrySkippedReason = "idempotency_key_required";
+    error.message = `${error.message} Retry skipped because this mutation is not retry-safe without an idempotency key.`;
+  }
+
+  return error;
+}
+
+function calculateRetryDelayMs({
+  attempt,
+  baseDelayMs,
+  maxDelayMs
+} = {}) {
+  const exponent = Math.max(0, Number(attempt ?? 1) - 1);
+  const delay = Number(baseDelayMs ?? 0) * (2 ** exponent);
+  const capped = Math.min(Number(maxDelayMs ?? delay), delay);
+
+  return Number.isFinite(capped) && capped > 0 ? capped : 0;
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function shouldUseNodeHttpFallback(url) {
+  try {
+    const parsed = new URL(url);
+
+    return ["127.0.0.1", "localhost", "::1"].includes(parsed.hostname) &&
+      ["http:", "https:"].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+
+function nodeHttpFetch(url, {
+  method = "GET",
+  headers = undefined,
+  body = undefined
+} = {}) {
+  const parsed = new URL(url);
+  const transport = parsed.protocol === "https:" ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const request = transport.request(parsed, {
+      method,
+      headers
+    }, (response) => {
+      const chunks = [];
+
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => {
+        const status = response.statusCode ?? 0;
+        const text = Buffer.concat(chunks).toString("utf8");
+
+        resolve({
+          ok: status >= 200 && status < 300,
+          status,
+          headers: response.headers,
+          text: async () => text,
+          json: async () => JSON.parse(text)
+        });
+      });
+    });
+
+    request.on("error", reject);
+
+    if (body !== undefined && body !== null) {
+      request.write(body);
+    }
+
+    request.end();
+  });
+}
+
+function getCertifiedSubmissionRecordId(submission) {
+  return submission?.submitted?.queue?.record?.id
+    ?? submission?.submitted?.record?.id
+    ?? submission?.submitted?.recordId
+    ?? submission?.submitted?.id
+    ?? submission?.submitted?.action?.id
+    ?? null;
+}
+
+export function createSolanaVerificationClientCompatibilityReport({ contract } = {}) {
+  const quickstart = contract?.quickstart;
+  const contractClient = quickstart?.client ?? contract?.client ?? {};
+  const requiredCapabilities = Array.isArray(contractClient.requiredCapabilities)
+    ? contractClient.requiredCapabilities
+    : SOLANA_VERIFICATION_CLIENT_CAPABILITIES;
+  const localCapabilities = [...SOLANA_VERIFICATION_CLIENT_CAPABILITIES];
+  const missingLocalCapabilities = requiredCapabilities.filter((capability) => !localCapabilities.includes(capability));
+  const checks = [
+    {
+      name: "contract_version_supported",
+      ok: contract?.version === BOT_INTEGRATION_CONTRACT_VERSION,
+      detail: `version=${contract?.version ?? "missing"}`
+    },
+    {
+      name: "quickstart_version_supported",
+      ok: quickstart?.version === BOT_INTEGRATION_QUICKSTART_VERSION,
+      detail: `version=${quickstart?.version ?? "missing"}`
+    },
+    {
+      name: "client_class_matches",
+      ok: !contractClient.className || contractClient.className === SOLANA_VERIFICATION_CLIENT_NAME,
+      detail: `expected=${contractClient.className ?? SOLANA_VERIFICATION_CLIENT_NAME} local=${SOLANA_VERIFICATION_CLIENT_NAME}`
+    },
+    {
+      name: "request_signing_helper_available",
+      ok: !contractClient.requestSigningHelper || contractClient.requestSigningHelper === "createSignedBotRequest",
+      detail: `expected=${contractClient.requestSigningHelper ?? "createSignedBotRequest"}`
+    },
+    {
+      name: "readiness_helper_available",
+      ok: !contractClient.readinessHelper || /checkBotReadiness/.test(String(contractClient.readinessHelper)),
+      detail: `expected=${contractClient.readinessHelper ?? "checkBotReadiness"}`
+    },
+    {
+      name: "minimum_startup_check_available",
+      ok: !contractClient.minimumStartupCheck || /checkBotReadiness/.test(String(contractClient.minimumStartupCheck)),
+      detail: `expected=${contractClient.minimumStartupCheck ?? "checkBotReadiness"}`
+    },
+    {
+      name: "required_capabilities_available",
+      ok: missingLocalCapabilities.length === 0,
+      detail: missingLocalCapabilities.length === 0
+        ? `capabilities=${requiredCapabilities.join(", ")}`
+        : `missing=${missingLocalCapabilities.join(", ")}`
+    }
+  ];
+  const failed = checks.find((check) => !check.ok);
+  const ok = !failed;
+
+  return {
+    version: BOT_CLIENT_COMPATIBILITY_VERSION,
+    ok,
+    status: ok ? "compatible" : "incompatible",
+    client: {
+      name: SOLANA_VERIFICATION_CLIENT_NAME,
+      version: SOLANA_VERIFICATION_CLIENT_VERSION,
+      capabilities: localCapabilities
+    },
+    contract: {
+      version: contract?.version ?? null,
+      quickstartVersion: quickstart?.version ?? null,
+      className: contractClient.className ?? null,
+      requestSigningHelper: contractClient.requestSigningHelper ?? null,
+      readinessHelper: contractClient.readinessHelper ?? null,
+      minimumStartupCheck: contractClient.minimumStartupCheck ?? null,
+      requiredCapabilities
+    },
+    missingLocalCapabilities,
+    checks,
+    nextAction: ok
+      ? {
+          code: "none",
+          message: "Local bot client is compatible with the live integration contract."
+        }
+      : {
+          code: "client_contract_incompatible",
+          message: `Update the bot client or dashboard contract before live submissions. First failing check: ${failed.name}.`
+        }
+  };
+}
+
+function selectReadinessBot(readiness, botId) {
+  const bots = Array.isArray(readiness?.bots) ? readiness.bots : [];
+
+  if (botId) {
+    return bots.find((bot) => bot.botId === botId) ?? null;
+  }
+
+  return bots.length === 1 ? bots[0] : null;
+}
+
+function summarizeReadinessBot(bot) {
+  return {
+    botId: bot.botId,
+    name: bot.name ?? bot.botId,
+    status: bot.status ?? null,
+    productionReady: bot.productionReady === true,
+    readinessStatus: bot.readinessStatus ?? null,
+    credentialRotationStatus: bot.credentialRotationStatus ?? null,
+    requestSigningSecretSlots: Array.isArray(bot.requestSigningSecretSlots)
+      ? bot.requestSigningSecretSlots
+      : [],
+    lastSuccessfulSignedRequest: bot.lastSuccessfulSignedRequest ?? null,
+    selfTest: bot.selfTest ?? null,
+    blockingReasons: Array.isArray(bot.blockingReasons) ? bot.blockingReasons : []
+  };
+}
+
+function createReadinessNextAction({ bot, readiness, selfTest, runSelfTest }) {
+  if (runSelfTest && selfTest?.ok !== true) {
+    return {
+      code: "self_test_failed",
+      message: selfTest?.error ?? "Run the signed bot self-test successfully before live traffic."
+    };
+  }
+
+  if (!bot) {
+    const botCount = Array.isArray(readiness?.bots) ? readiness.bots.length : 0;
+
+    return {
+      code: botCount === 0 ? "no_bot_found" : "select_bot_id",
+      message: botCount === 0
+        ? "No bot credential readiness entry was returned."
+        : "Pass botId so the client can report the exact bot readiness entry."
+    };
+  }
+
+  const blockingReason = Array.isArray(bot.blockingReasons) ? bot.blockingReasons[0] : null;
+
+  if (blockingReason) {
+    return {
+      code: blockingReason.code ?? "credential_readiness_blocked",
+      message: blockingReason.message ?? "Resolve the first credential readiness blocker."
+    };
+  }
+
+  if (bot.adoption?.nextAction && bot.adoption.nextAction.code !== "none") {
+    return {
+      code: bot.adoption.nextAction.code,
+      message: bot.adoption.nextAction.message
+    };
+  }
+
+  return {
+    code: "none",
+    message: "Bot readiness path is complete."
+  };
+}