@trucore/openclaw-atf 0.1.0 → 0.2.0

package/src/config.mjs

@@ -0,0 +1,317 @@
+/**
+ * config.mjs — Config validation + sanity checking for ATF OpenClaw plugin
+ *
+ * Validates user-supplied config against the canonical schema, reports
+ * unsupported keys, detects common misconfigurations, and provides
+ * operator-language remediation.
+ *
+ * Exports:
+ *   - validateConfig(userConfig)      → ConfigValidationResult
+ *   - SUPPORTED_KEYS                  → canonical top-level keys
+ *   - SUPPORTED_SAFETY_KEYS           → canonical safety sub-keys
+ *   - CANONICAL_PLUGIN_ID             → "trucore-atf"
+ *   - MINIMAL_ENABLE_CONFIG           → smallest working config object
+ *
+ * Uses ONLY built-in Node modules. No external deps.
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Canonical plugin ID — single source of truth for config validation. */
+export const CANONICAL_PLUGIN_ID = "trucore-atf";
+
+/** Supported top-level config keys (matches openclaw.plugin.json configSchema). */
+export const SUPPORTED_KEYS = Object.freeze([
+  "atfCli",
+  "atfBaseUrl",
+  "prefer",
+  "receiptsDir",
+  "safety",
+]);
+
+/** Supported safety sub-keys. */
+export const SUPPORTED_SAFETY_KEYS = Object.freeze([
+  "allowExecuteSafe",
+  "allowNetwork",
+]);
+
+/** Valid values for the `prefer` key. */
+const VALID_PREFER_VALUES = Object.freeze(["cli", "api"]);
+
+/**
+ * Smallest config that enables the plugin with all defaults.
+ * Zero required keys — the plugin works with an empty object.
+ */
+export const MINIMAL_ENABLE_CONFIG = Object.freeze({});
+
+/**
+ * Config for CLI-preferred mode (explicit, copy-paste-safe).
+ */
+export const CLI_PREFER_CONFIG = Object.freeze({
+  prefer: "cli",
+});
+
+/**
+ * Config for API-preferred mode (requires atfBaseUrl).
+ */
+export const API_PREFER_CONFIG = Object.freeze({
+  prefer: "api",
+  atfBaseUrl: "https://api.trucore.xyz",
+});
+
+// ---------------------------------------------------------------------------
+// Validation result
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} ConfigValidationResult
+ * @property {boolean} valid          True if no errors found.
+ * @property {string[]} errors        Hard errors (config will not work).
+ * @property {string[]} warnings      Soft warnings (config works but suboptimal).
+ * @property {string[]} remediation   Operator-facing fix instructions.
+ * @property {string[]} unsupported_keys  Keys present but not in schema.
+ */
+
+// ---------------------------------------------------------------------------
+// Validation logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a user-supplied plugin config object.
+ *
+ * Does NOT throw. Returns a structured result with errors, warnings,
+ * and remediation steps in operator language.
+ *
+ * @param {unknown} userConfig  The config object from OpenClaw.
+ * @returns {ConfigValidationResult}
+ */
+export function validateConfig(userConfig) {
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {string[]} */
+  const remediation = [];
+  /** @type {string[]} */
+  const unsupportedKeys = [];
+
+  // ---- Null / non-object config ----
+  if (userConfig === null || userConfig === undefined) {
+    // Perfectly fine — zero-config enable
+    return {
+      valid: true,
+      errors: [],
+      warnings: [],
+      remediation: [],
+      unsupported_keys: [],
+    };
+  }
+
+  if (typeof userConfig !== "object" || Array.isArray(userConfig)) {
+    return {
+      valid: false,
+      errors: ["Plugin config must be an object (or omitted for defaults)."],
+      warnings: [],
+      remediation: [
+        'Use: { "plugins": { "trucore-atf": {} } } for zero-config enable.',
+      ],
+      unsupported_keys: [],
+    };
+  }
+
+  const cfg = /** @type {Record<string, unknown>} */ (userConfig);
+
+  // ---- Detect unsupported top-level keys ----
+  const supportedSet = new Set(SUPPORTED_KEYS);
+  for (const key of Object.keys(cfg)) {
+    if (!supportedSet.has(key)) {
+      unsupportedKeys.push(key);
+    }
+  }
+  if (unsupportedKeys.length > 0) {
+    errors.push(
+      `Unsupported config keys: ${unsupportedKeys.join(", ")}. ` +
+      `Supported keys: ${SUPPORTED_KEYS.join(", ")}.`,
+    );
+    remediation.push(
+      `Remove unsupported keys from your plugin config: ${unsupportedKeys.join(", ")}.`,
+    );
+  }
+
+  // ---- Validate `prefer` value ----
+  if ("prefer" in cfg) {
+    if (!VALID_PREFER_VALUES.includes(/** @type {string} */ (cfg.prefer))) {
+      errors.push(
+        `Invalid prefer value: "${cfg.prefer}". Must be "cli" or "api".`,
+      );
+      remediation.push('Set prefer to "cli" or "api".');
+    }
+  }
+
+  // ---- Validate prefer=api requires atfBaseUrl ----
+  if (cfg.prefer === "api" && !cfg.atfBaseUrl) {
+    errors.push(
+      'prefer="api" requires atfBaseUrl to be set.',
+    );
+    remediation.push(
+      "Set atfBaseUrl in plugin config " +
+      '(e.g. "https://api.trucore.xyz").',
+    );
+  }
+
+  // ---- Validate atfBaseUrl format ----
+  if (cfg.atfBaseUrl !== undefined && cfg.atfBaseUrl !== null) {
+    if (typeof cfg.atfBaseUrl !== "string" || cfg.atfBaseUrl.length === 0) {
+      errors.push("atfBaseUrl must be a non-empty string URL.");
+      remediation.push(
+        'Set atfBaseUrl to a valid URL (e.g. "https://api.trucore.xyz").',
+      );
+    } else if (
+      !cfg.atfBaseUrl.startsWith("http://") &&
+      !cfg.atfBaseUrl.startsWith("https://")
+    ) {
+      warnings.push(
+        `atfBaseUrl "${cfg.atfBaseUrl}" does not start with http:// or https://.`,
+      );
+    }
+  }
+
+  // ---- Validate atfCli type ----
+  if (cfg.atfCli !== undefined && cfg.atfCli !== null) {
+    if (typeof cfg.atfCli !== "string" || cfg.atfCli.length === 0) {
+      errors.push("atfCli must be a non-empty string.");
+      remediation.push('Set atfCli to a CLI command name (e.g. "atf").');
+    }
+  }
+
+  // ---- Validate receiptsDir type ----
+  if (cfg.receiptsDir !== undefined && cfg.receiptsDir !== null) {
+    if (typeof cfg.receiptsDir !== "string") {
+      errors.push("receiptsDir must be a string path.");
+    }
+  }
+
+  // ---- Validate safety sub-object ----
+  if ("safety" in cfg) {
+    if (
+      cfg.safety === null ||
+      typeof cfg.safety !== "object" ||
+      Array.isArray(cfg.safety)
+    ) {
+      errors.push("safety must be an object.");
+      remediation.push(
+        'Use: "safety": { "allowExecuteSafe": true, "allowNetwork": false }',
+      );
+    } else {
+      const safetyObj = /** @type {Record<string, unknown>} */ (cfg.safety);
+      const safetySupportedSet = new Set(SUPPORTED_SAFETY_KEYS);
+      for (const key of Object.keys(safetyObj)) {
+        if (!safetySupportedSet.has(key)) {
+          unsupportedKeys.push(`safety.${key}`);
+        }
+      }
+      if (
+        "allowExecuteSafe" in safetyObj &&
+        typeof safetyObj.allowExecuteSafe !== "boolean"
+      ) {
+        errors.push("safety.allowExecuteSafe must be a boolean.");
+      }
+      if (
+        "allowNetwork" in safetyObj &&
+        typeof safetyObj.allowNetwork !== "boolean"
+      ) {
+        errors.push("safety.allowNetwork must be a boolean.");
+      }
+    }
+  }
+
+  // ---- Warn about atfBaseUrl without prefer=api ----
+  if (
+    cfg.atfBaseUrl &&
+    typeof cfg.atfBaseUrl === "string" &&
+    cfg.prefer !== "api"
+  ) {
+    warnings.push(
+      "atfBaseUrl is set but prefer is not 'api'. " +
+      "The URL will only be used as a fallback. " +
+      "Set prefer='api' to use the API as the primary backend.",
+    );
+  }
+
+  const valid = errors.length === 0;
+  return {
+    valid,
+    errors,
+    warnings,
+    remediation,
+    unsupported_keys: unsupportedKeys,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Activation-time warning formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a ConfigValidationResult into concise, deterministic log lines
+ * suitable for activation-time console output.
+ *
+ * Returns an empty array when config is fully valid with no warnings.
+ * Never throws.
+ *
+ * @param {ConfigValidationResult} result  Output from validateConfig().
+ * @returns {string[]}  Log lines (each prefixed with [trucore-atf]).
+ */
+export function formatActivationWarnings(result) {
+  if (!result || typeof result !== "object") {
+    return [];
+  }
+
+  const hasErrors = result.errors && result.errors.length > 0;
+  const hasWarnings = result.warnings && result.warnings.length > 0;
+  const hasUnsupported =
+    result.unsupported_keys && result.unsupported_keys.length > 0;
+
+  if (!hasErrors && !hasWarnings && !hasUnsupported) {
+    return [];
+  }
+
+  /** @type {string[]} */
+  const lines = [];
+
+  lines.push(
+    `[trucore-atf] Plugin activated with config issues (plugin still operational):`,
+  );
+
+  if (hasErrors) {
+    for (const err of result.errors) {
+      lines.push(`[trucore-atf]   ERROR: ${err}`);
+    }
+  }
+
+  if (hasWarnings) {
+    for (const w of result.warnings) {
+      lines.push(`[trucore-atf]   WARNING: ${w}`);
+    }
+  }
+
+  if (hasUnsupported) {
+    lines.push(
+      `[trucore-atf]   Unsupported keys: ${result.unsupported_keys.join(", ")}`,
+    );
+  }
+
+  if (result.remediation && result.remediation.length > 0) {
+    lines.push(
+      `[trucore-atf]   Run atf_integration_doctor for full details and remediation.`,
+    );
+  } else {
+    lines.push(
+      `[trucore-atf]   Run atf_integration_doctor for full details.`,
+    );
+  }
+
+  return lines;
+}

package/src/contracts/deny_codes.mjs

@@ -0,0 +1,217 @@
+/**
+ * deny_codes.mjs — Universal ATF deny / reason / error code vocabularies
+ *
+ * Platform-agnostic code catalogs used across all ATF surfaces.
+ * These are the CANONICAL source of truth for deny and reason codes.
+ *
+ * Exports:
+ *   - REASON_CODE_CATALOG    — deny reason code explanations (swap/perps/lending/general)
+ *   - CLAIM_DENY_CODES       — billing claim deny/error codes
+ *   - REASON_CATEGORIES      — canonical categories for reason codes
+ *
+ * No dependencies. No side effects. Pure constants.
+ */
+
+// ---------------------------------------------------------------------------
+// Reason categories
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical categories for ATF reason codes.
+ */
+export const REASON_CATEGORIES = Object.freeze({
+  SWAP: "swap",
+  PERPS: "perps",
+  LENDING: "lending",
+  GENERAL: "general",
+  UNKNOWN: "unknown",
+});
+
+// ---------------------------------------------------------------------------
+// Reason code catalog — maps deny codes to human explanations
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical reason code catalog: maps ATF deny reason codes to structured
+ * explanations. Used by tx_explain and any future surface that needs to
+ * explain a deny decision.
+ *
+ * Each entry has:
+ *   - category: one of REASON_CATEGORIES values
+ *   - explanation: human-readable description
+ *   - remediation: actionable fix instruction
+ *
+ * @type {Readonly<Record<string, {category: string, explanation: string, remediation: string}>>}
+ */
+export const REASON_CODE_CATALOG = Object.freeze({
+  // --- DEX / Swap ---
+  DEX_VENUE_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.SWAP,
+    explanation:
+      "The swap venue (DEX) is not in the policy's allowed_venues list.",
+    remediation:
+      "Add the venue to swap_policy.allowed_venues in your policy YAML.",
+  },
+  DEX_SLIPPAGE_TOO_HIGH: {
+    category: REASON_CATEGORIES.SWAP,
+    explanation:
+      "The requested slippage exceeds the policy's max_slippage_bps limit.",
+    remediation:
+      "Lower slippage_bps in your intent or raise max_slippage_bps in policy.",
+  },
+  SWAP_VENUE_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.SWAP,
+    explanation:
+      "The swap venue is not in the policy's allowed_venues list.",
+    remediation:
+      "Add the venue to swap_policy.allowed_venues in your policy YAML.",
+  },
+  SWAP_SLIPPAGE_TOO_HIGH: {
+    category: REASON_CATEGORIES.SWAP,
+    explanation:
+      "The slippage exceeds the policy's maximum allowed slippage.",
+    remediation:
+      "Lower slippage_bps or raise max_slippage_bps in policy.",
+  },
+  // --- Perps ---
+  PERPS_MARKET_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.PERPS,
+    explanation:
+      "The perpetuals market is not in the policy's allowed_markets list.",
+    remediation:
+      "Add the market to perps_policy.allowed_markets in your policy YAML.",
+  },
+  PERPS_ORDER_TYPE_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.PERPS,
+    explanation:
+      "The order type is not in the policy's allowed_order_types list.",
+    remediation:
+      "Add the order type to perps_policy.allowed_order_types.",
+  },
+  PERPS_LEVERAGE_TOO_HIGH: {
+    category: REASON_CATEGORIES.PERPS,
+    explanation:
+      "The leverage exceeds the policy's max_leverage limit.",
+    remediation:
+      "Lower leverage or raise max_leverage_x10 in perps_policy.",
+  },
+  PERPS_VENUE_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.PERPS,
+    explanation:
+      "The perps venue is not in the policy's allowed_venues list.",
+    remediation:
+      "Add the venue to perps_policy.allowed_venues.",
+  },
+  PERPS_POSITION_SIZE_TOO_LARGE: {
+    category: REASON_CATEGORIES.PERPS,
+    explanation:
+      "The position size exceeds the policy's maximum.",
+    remediation:
+      "Lower position size or raise the limit in perps_policy.",
+  },
+  // --- Lending ---
+  LEND_VENUE_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.LENDING,
+    explanation:
+      "The lending venue is not in the policy's allowed_venues list.",
+    remediation:
+      "Add the venue to lending_policy.allowed_venues.",
+  },
+  LEND_MARKET_NOT_ALLOWED: {
+    category: REASON_CATEGORIES.LENDING,
+    explanation:
+      "The lending market is not in the policy's allowed_markets list.",
+    remediation:
+      "Add the market to lending_policy.allowed_markets.",
+  },
+  LEND_AMOUNT_TOO_LARGE: {
+    category: REASON_CATEGORIES.LENDING,
+    explanation:
+      "The deposit/withdrawal amount exceeds the policy's maximum.",
+    remediation:
+      "Lower the amount or raise the limit in lending_policy.",
+  },
+  // --- General ---
+  CHAIN_NOT_SUPPORTED: {
+    category: REASON_CATEGORIES.GENERAL,
+    explanation:
+      "The chain_id is not supported or recognized by ATF.",
+    remediation:
+      "Verify chain_id is correct (e.g. 'solana').",
+  },
+  INTENT_TYPE_UNKNOWN: {
+    category: REASON_CATEGORIES.GENERAL,
+    explanation:
+      "The intent_type is not recognized by ATF.",
+    remediation:
+      "Use a supported intent_type: swap, lend_deposit, lend_withdraw, " +
+      "perps_open, perps_close.",
+  },
+  POLICY_NOT_CONFIGURED: {
+    category: REASON_CATEGORIES.GENERAL,
+    explanation:
+      "No policy is configured for this intent type.",
+    remediation:
+      "Create and load a policy YAML with the relevant section " +
+      "(swap_policy, perps_policy, lending_policy).",
+  },
+  FEATURE_GATE_DISABLED: {
+    category: REASON_CATEGORIES.GENERAL,
+    explanation:
+      "A required feature gate is not enabled.",
+    remediation:
+      "Set the relevant ATF_ENABLE_* environment variable to 1.",
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Claim deny codes — billing claim verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured deny/error codes for billing claim verification results.
+ */
+export const CLAIM_DENY_CODES = Object.freeze({
+  /** Transaction signature is malformed or empty. */
+  INVALID_SIGNATURE: "INVALID_SIGNATURE",
+  /** Transaction not found on-chain. */
+  TX_NOT_FOUND: "TX_NOT_FOUND",
+  /** Transaction exists but is not finalized/confirmed. */
+  TX_NOT_FINALIZED: "TX_NOT_FINALIZED",
+  /** Transaction exists but execution failed. */
+  TX_FAILED: "TX_FAILED",
+  /** Payment recipient does not match ATF treasury. */
+  WRONG_RECIPIENT: "WRONG_RECIPIENT",
+  /** Token mint does not match accepted payment rails. */
+  WRONG_MINT: "WRONG_MINT",
+  /** Asset type is not supported for payment. */
+  UNSUPPORTED_ASSET: "UNSUPPORTED_ASSET",
+  /** Payment amount is below minimum threshold. */
+  INSUFFICIENT_AMOUNT: "INSUFFICIENT_AMOUNT",
+  /** Package ID is not recognized. */
+  UNKNOWN_PACKAGE: "UNKNOWN_PACKAGE",
+  /** Transaction signature has already been claimed. */
+  DUPLICATE_CLAIM: "DUPLICATE_CLAIM",
+  /** Required claim parameters are missing. */
+  MISSING_PARAMS: "MISSING_PARAMS",
+  /** RPC infrastructure error during verification. */
+  RPC_ERROR: "RPC_ERROR",
+});
+
+// ---------------------------------------------------------------------------
+// Convenience: all deny code keys as a frozen array
+// ---------------------------------------------------------------------------
+
+/**
+ * All reason code keys from the catalog, as a frozen array.
+ */
+export const REASON_CODE_KEYS = Object.freeze(
+  Object.keys(REASON_CODE_CATALOG),
+);
+
+/**
+ * All claim deny code keys, as a frozen array.
+ */
+export const CLAIM_DENY_CODE_KEYS = Object.freeze(
+  Object.keys(CLAIM_DENY_CODES),
+);

package/src/contracts/index.mjs

@@ -0,0 +1,52 @@
+/**
+ * contracts/index.mjs — Universal ATF contract layer barrel export
+ *
+ * Re-exports all universal contract primitives from a single entry point.
+ *
+ * Usage:
+ *   import { RESPONSE_STATUS, REASON_CODE_CATALOG, buildResult } from "./contracts/index.mjs";
+ *
+ * This module is the canonical import point for any code that needs
+ * ATF's platform-agnostic contract definitions.
+ *
+ * Adapter-specific code (OpenClaw, CLI, API) should import from here
+ * rather than duplicating constants.
+ */
+
+// Status code vocabularies
+export {
+  RESPONSE_STATUS,
+  DOCTOR_STATUS,
+  CLAIM_STATUS,
+  BACKEND_STATUS,
+  PREFLIGHT_STATUS,
+  ADOPTION_TIER,
+  SEVERITY,
+  SEVERITY_RANK,
+} from "./status_codes.mjs";
+
+// Deny / reason code vocabularies
+export {
+  REASON_CODE_CATALOG,
+  CLAIM_DENY_CODES,
+  REASON_CATEGORIES,
+  REASON_CODE_KEYS,
+  CLAIM_DENY_CODE_KEYS,
+} from "./deny_codes.mjs";
+
+// Contract family schemas
+export {
+  CONTRACT_FAMILIES,
+  UNIVERSAL_RESULT_FIELDS,
+  ADAPTER_ENVELOPE_FIELDS,
+  TOOL_FAMILY_MAP,
+  CANONICAL_TOOLS,
+  CANONICAL_TOOL_COUNT,
+} from "./schemas.mjs";
+
+// Universal result builder
+export {
+  buildResult,
+  buildErrorResult,
+  buildMeta,
+} from "./result_builder.mjs";