@caatinga/core 2.3.0 → 2.4.0

package/dist/index.cjs

@@ -37,17 +37,21 @@ __export(index_exports, {
   CaatingaConfigSchema: () => CaatingaConfigSchema,
   CaatingaError: () => CaatingaError,
   CaatingaErrorCode: () => CaatingaErrorCode,
+  READ_CALL_FAILURE_REGEX: () => READ_CALL_FAILURE_REGEX,
   STELLAR_CLI_LAST_TESTED_VERSION: () => STELLAR_CLI_LAST_TESTED_VERSION,
   STELLAR_CLI_MIN_VERSION: () => STELLAR_CLI_MIN_VERSION,
   TemplateManifestSchema: () => TemplateManifestSchema,
   WELL_KNOWN_NETWORKS: () => WELL_KNOWN_NETWORKS,
   buildContract: () => buildContract,
   buildDependencyGraph: () => buildDependencyGraph,
+  buildReadCallHint: () => buildReadCallHint,
   checkBinary: () => checkBinary,
   checkStellarCliVersion: () => checkStellarCliVersion,
   collectProjectStatus: () => collectProjectStatus,
   createInitialArtifacts: () => createInitialArtifacts,
+  createMinimalProject: () => createMinimalProject,
   createProjectFromTemplate: () => createProjectFromTemplate,
+  createZkProject: () => createZkProject,
   defineConfig: () => defineConfig,
   deployContract: () => deployContract,
   deployContractGraph: () => deployContractGraph,
@@ -58,6 +62,8 @@ __export(index_exports, {
   generateBindings: () => generateBindings,
   generateBindingsGraph: () => generateBindingsGraph,
   invokeContract: () => invokeContract,
+  isCargoBinMissingFromPath: () => isCargoBinMissingFromPath,
+  isReadCallFailure: () => isReadCallFailure,
   isTransientTestnetSmokeFailure: () => isTransientTestnetSmokeFailure,
   loadConfig: () => loadConfig,
   parseContractId: () => parseContractId,
@@ -65,11 +71,13 @@ __export(index_exports, {
   parseStellarCliVersion: () => parseStellarCliVersion,
   readArtifacts: () => readArtifacts,
   readBindingMarker: () => readBindingMarker,
+  readContract: () => readContract,
   resolveContract: () => resolveContract,
   resolveDefaultContractName: () => resolveDefaultContractName,
   resolveDeployArgs: () => resolveDeployArgs,
   resolveDeployOrder: () => resolveDeployOrder,
   resolveNetwork: () => resolveNetwork,
+  resolveSubprocessEnv: () => resolveSubprocessEnv,
   runCommand: () => runCommand,
   toCaatingaError: () => toCaatingaError,
   updateArtifact: () => updateArtifact,
@@ -82,6 +90,7 @@ module.exports = __toCommonJS(index_exports);
 // src/errors/CaatingaErrorCode.ts
 var CaatingaErrorCode = {
   CONFIG_NOT_FOUND: "CAATINGA_CONFIG_NOT_FOUND",
+  DEPENDENCIES_NOT_INSTALLED: "CAATINGA_DEPENDENCIES_NOT_INSTALLED",
   INVALID_CONFIG: "CAATINGA_INVALID_CONFIG",
   COMMAND_FAILED: "CAATINGA_COMMAND_FAILED",
   UNEXPECTED_ERROR: "CAATINGA_UNEXPECTED_ERROR",
@@ -186,7 +195,7 @@ function formatCause(cause) {
 }
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "2.3.0";
+var CAATINGA_CORE_VERSION = "2.4.0";
 
 // src/config/config.schema.ts
 var import_zod = require("zod");
@@ -224,7 +233,7 @@ var CaatingaConfigSchema = import_zod.z.object({
   frontend: import_zod.z.object({
     framework: import_zod.z.enum(["vite-react", "next", "astro"]).default("vite-react"),
     bindingsOutput: import_zod.z.string().min(1)
-  }),
+  }).optional(),
   zk: ZkConfigSchema
 });
 
@@ -238,6 +247,28 @@ var import_promises = require("fs/promises");
 var import_node_path = __toESM(require("path"), 1);
 var import_jiti = require("jiti");
 var import_zod2 = require("zod");
+
+// src/config/is-dependencies-not-installed-error.ts
+function isDependenciesNotInstalledError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const candidate = error;
+  const code = candidate.code;
+  const message = String(candidate.message ?? error);
+  if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+    return /@caatinga\/core/.test(message);
+  }
+  if (/Cannot find (module|package).+@caatinga\/core/i.test(message)) {
+    return true;
+  }
+  if (candidate.cause !== void 0) {
+    return isDependenciesNotInstalledError(candidate.cause);
+  }
+  return false;
+}
+
+// src/config/load-config.ts
 var import_meta = {};
 async function loadConfig(options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -263,6 +294,14 @@ async function loadConfig(options = {}) {
         error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
       );
     }
+    if (isDependenciesNotInstalledError(error)) {
+      throw new CaatingaError(
+        "Project dependencies are not installed.",
+        CaatingaErrorCode.DEPENDENCIES_NOT_INSTALLED,
+        "Run npm install (or pnpm install) in the project root, then retry.",
+        error
+      );
+    }
     throw error;
   }
 }
@@ -423,6 +462,15 @@ async function listGeneratedEntries(outputDir) {
 }
 async function evaluateBindingFreshness(options) {
   const cwd = options.cwd ?? process.cwd();
+  if (!options.config.frontend) {
+    return {
+      contractName: options.contractName,
+      status: "unknown",
+      outputDir: "",
+      marker: null,
+      reason: "frontend bindings are not configured"
+    };
+  }
   const outputDir = import_node_path5.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   const contractArtifact = options.artifacts.networks[options.networkName]?.contracts[options.contractName];
   if (!contractArtifact) {
@@ -660,6 +708,64 @@ function defaultEmitWarning(warning) {
 `);
 }
 
+// src/shell/resolve-subprocess-env.ts
+var import_node_fs = require("fs");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
+function uniquePaths(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const ordered = [];
+  for (const entry of entries) {
+    if (!entry || seen.has(entry)) {
+      continue;
+    }
+    seen.add(entry);
+    ordered.push(entry);
+  }
+  return ordered;
+}
+function hasExecutable(binDir, name) {
+  return (0, import_node_fs.existsSync)(import_node_path6.default.join(binDir, name));
+}
+function toolchainBinDirs(home, env) {
+  const candidates = [
+    import_node_path6.default.join(home, ".cargo", "bin"),
+    env.CARGO_HOME ? import_node_path6.default.join(env.CARGO_HOME, "bin") : void 0
+  ];
+  return candidates.filter((entry) => Boolean(entry && (0, import_node_fs.existsSync)(entry)));
+}
+function buildToolchainPrepend(existingPath, toolchainBins, executableExists = hasExecutable) {
+  const prepend = [];
+  for (const binDir of toolchainBins) {
+    const externalStellarDir = existingPath.find(
+      (entry) => entry !== binDir && executableExists(entry, "stellar")
+    );
+    if (externalStellarDir && executableExists(binDir, "stellar")) {
+      prepend.push(externalStellarDir);
+    }
+    prepend.push(binDir);
+  }
+  return prepend;
+}
+function resolveSubprocessEnv(overrides = {}) {
+  const env = { ...process.env, ...overrides };
+  const home = env.HOME ?? import_node_os.default.homedir();
+  const existingPath = (env.PATH ?? "").split(import_node_path6.default.delimiter).filter(Boolean);
+  const toolchainBins = toolchainBinDirs(home, env);
+  const prepend = buildToolchainPrepend(existingPath, toolchainBins);
+  env.PATH = uniquePaths([...prepend, ...existingPath]).join(import_node_path6.default.delimiter);
+  return env;
+}
+function isCargoBinMissingFromPath(baseEnv = process.env) {
+  const home = baseEnv.HOME ?? import_node_os.default.homedir();
+  const cargoBin = import_node_path6.default.join(home, ".cargo", "bin", "cargo");
+  if (!(0, import_node_fs.existsSync)(cargoBin)) {
+    return false;
+  }
+  const pathEntries = (baseEnv.PATH ?? "").split(import_node_path6.default.delimiter);
+  return !pathEntries.some((entry) => entry === import_node_path6.default.join(home, ".cargo", "bin"));
+}
+
 // src/shell/run-command.ts
 async function runCommand(command, args, options = {}) {
   try {
@@ -668,7 +774,7 @@ async function runCommand(command, args, options = {}) {
     }
     const result = await (0, import_execa.execa)(command, args, {
       cwd: options.cwd,
-      env: options.env,
+      env: resolveSubprocessEnv(options.env ?? {}),
       input: options.input,
       all: true,
       reject: true
@@ -866,7 +972,7 @@ function validateSourceShape(source) {
 }
 
 // src/contracts/resolve-contract.ts
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 function resolveContract(config, contractName, cwd = process.cwd()) {
   const contract = config.contracts[contractName];
   if (!contract) {
@@ -879,8 +985,8 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
   return {
     name: contractName,
     config: contract,
-    sourcePath: import_node_path6.default.resolve(cwd, contract.path),
-    wasmPath: import_node_path6.default.resolve(cwd, contract.wasm)
+    sourcePath: import_node_path7.default.resolve(cwd, contract.path),
+    wasmPath: import_node_path7.default.resolve(cwd, contract.wasm)
   };
 }
 
@@ -900,7 +1006,7 @@ function resolveDefaultContractName(config) {
 // src/contracts/wasm.ts
 var import_node_crypto = require("crypto");
 var import_promises6 = require("fs/promises");
-var import_node_path7 = __toESM(require("path"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
 var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
 function toCurrentWasmTargetPath(wasmPath) {
@@ -923,8 +1029,8 @@ function wasmNotFoundError(configuredWasmPath, options) {
   );
 }
 function toConfigRelativeWasmPath(absoluteWasmPath) {
-  const relative = import_node_path7.default.relative(process.cwd(), absoluteWasmPath);
-  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(import_node_path7.default.sep).join("/")}`;
+  const relative = import_node_path8.default.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(import_node_path8.default.sep).join("/")}`;
 }
 async function resolveWasmArtifactPath(configuredWasmPath) {
   try {
@@ -957,7 +1063,7 @@ async function getNewestMtimeInDirectory(directory) {
   async function walk(dir) {
     const entries = await (0, import_promises6.readdir)(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const entryPath = import_node_path7.default.join(dir, entry.name);
+      const entryPath = import_node_path8.default.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(entryPath);
         continue;
@@ -973,7 +1079,7 @@ async function getNewestMtimeInDirectory(directory) {
   return newest > 0 ? newest : void 0;
 }
 async function isWasmOlderThanSources(input) {
-  const srcDir = import_node_path7.default.join(input.contractPath, "src");
+  const srcDir = import_node_path8.default.join(input.contractPath, "src");
   const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
   if (newestSourceMtime === void 0) {
     return false;
@@ -1046,7 +1152,7 @@ async function buildContract(options) {
 }
 
 // src/contracts/deploy-contract.ts
-var import_node_path8 = __toESM(require("path"), 1);
+var import_node_path9 = __toESM(require("path"), 1);
 
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
@@ -1103,6 +1209,9 @@ function assertSafeSourceAccount(source) {
   }
   return source;
 }
+function resolveCliSource(explicit) {
+  return assertSafeSourceAccount(explicit ?? process.env.CAATINGA_SOURCE ?? "alice");
+}
 
 // src/contracts/deploy-contract.ts
 function toSnakeCaseFlag(key) {
@@ -1147,7 +1256,7 @@ async function deployContract(options) {
       contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: import_node_path8.default.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: import_node_path9.default.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
       skipped: true,
       staleWasmWarning
@@ -1424,13 +1533,13 @@ async function deployContractGraph(options) {
 
 // src/contracts/generate-bindings.ts
 var import_promises7 = require("fs/promises");
-var import_node_path9 = __toESM(require("path"), 1);
+var import_node_path10 = __toESM(require("path"), 1);
 function toBindingImportPath(bindingsOutput, contractName) {
-  const normalized = bindingsOutput.replace(/^\.\//, "").split(import_node_path9.default.sep).join("/");
-  return `./${import_node_path9.default.posix.join(normalized, contractName, "src", "index.js")}`;
+  const normalized = bindingsOutput.replace(/^\.\//, "").split(import_node_path10.default.sep).join("/");
+  return `./${import_node_path10.default.posix.join(normalized, contractName, "src", "index.js")}`;
 }
 async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
-  const legacyPath = import_node_path9.default.resolve(cwd, bindingsOutput, `${contractName}.ts`);
+  const legacyPath = import_node_path10.default.resolve(cwd, bindingsOutput, `${contractName}.ts`);
   try {
     await (0, import_promises7.access)(legacyPath);
     await (0, import_promises7.unlink)(legacyPath);
@@ -1441,6 +1550,13 @@ async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
 }
 async function generateBindings(options) {
   const cwd = options.cwd ?? process.cwd();
+  if (!options.config.frontend) {
+    throw new CaatingaError(
+      "Frontend bindings are not configured.",
+      CaatingaErrorCode.INVALID_CONFIG,
+      "Add a frontend.bindingsOutput entry to caatinga.config.ts before running caatinga generate."
+    );
+  }
   const network = resolveNetwork(options.config, options.networkName);
   const artifacts = await readArtifacts(cwd);
   const contractArtifact = artifacts.networks[network.name]?.contracts[options.contractName];
@@ -1452,7 +1568,7 @@ async function generateBindings(options) {
     );
   }
   await checkBinary("stellar", "Install Stellar CLI before running caatinga generate.");
-  const outputDir = import_node_path9.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const outputDir = import_node_path10.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   await (0, import_promises7.mkdir)(outputDir, { recursive: true });
   const result = await runCommand("stellar", [
     "contract",
@@ -1526,8 +1642,8 @@ async function generateBindingsGraph(options) {
   return { network, results };
 }
 
-// src/contracts/invoke-contract.ts
-var INVOKE_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
+// src/contracts/invoke-target.ts
+var READ_CALL_FAILURE_REGEX = /this is a read call|read-only/i;
 function parseInvokeTarget(target) {
   const [contractName, method, extra] = target.split(".");
   if (!contractName || !method || extra) {
@@ -1539,6 +1655,29 @@ function parseInvokeTarget(target) {
   }
   return { contractName, method };
 }
+function buildReadCallHint(target, networkName) {
+  return [
+    `"${target.contractName}.${target.method}" is a read-only contract method.`,
+    "Simulate without signing instead:",
+    `  npx caatinga read ${target.contractName}.${target.method} --network ${networkName}`,
+    "  (--source is optional; Caatinga resolves CAATINGA_SOURCE or defaults to alice)",
+    "In browser code, use:",
+    `  client.contract("${target.contractName}").read("${target.method}")`,
+    `  client.contract("${target.contractName}").simulate("${target.method}")`,
+    "Pass method args as the second argument to read() when the contract method takes parameters.",
+    "Only pass Stellar CLI --force when you intentionally need a signed read simulation."
+  ].join("\n");
+}
+function isReadCallFailure(error) {
+  if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.INVOKE_FAILED) {
+    return false;
+  }
+  return READ_CALL_FAILURE_REGEX.test(`${error.message}
+${error.hint ?? ""}`);
+}
+
+// src/contracts/invoke-contract.ts
+var INVOKE_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
 async function invokeContract(options) {
   const cwd = options.cwd ?? process.cwd();
   const network = resolveNetwork(options.config, options.networkName);
@@ -1572,6 +1711,14 @@ async function invokeContract(options) {
       failureCode: CaatingaErrorCode.INVOKE_FAILED
     });
   } catch (error) {
+    if (error instanceof CaatingaError && error.code === CaatingaErrorCode.INVOKE_FAILED && isReadCallFailure(error)) {
+      throw new CaatingaError(
+        error.message,
+        error.code,
+        buildReadCallHint(target, network.name),
+        error
+      );
+    }
     if (error instanceof CaatingaError && error.code === CaatingaErrorCode.INVOKE_FAILED && INVOKE_SIGNING_FAILURE_REGEX.test(`${error.message}
 ${error.hint ?? ""}`)) {
       throw new CaatingaError(
@@ -1597,9 +1744,48 @@ ${error.hint ?? ""}`)) {
   };
 }
 
+// src/contracts/read-contract.ts
+async function readContract(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const network = resolveNetwork(options.config, options.networkName);
+  const target = parseInvokeTarget(options.target);
+  const artifacts = await readArtifacts(cwd);
+  const contractArtifact = artifacts.networks[network.name]?.contracts[target.contractName];
+  if (!contractArtifact) {
+    throw new CaatingaError(
+      `No deployed artifact found for "${target.contractName}" on "${network.name}".`,
+      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+      "Run caatinga deploy for this contract and network before reading it."
+    );
+  }
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga read.");
+  const stellarArgs = [
+    "contract",
+    "invoke",
+    "--id",
+    contractArtifact.contractId,
+    "--source-account",
+    resolveCliSource(options.source),
+    "--send=no",
+    ...buildStellarNetworkArgs(network),
+    "--",
+    target.method,
+    ...options.args ?? []
+  ];
+  const result = await runCommand("stellar", stellarArgs, {
+    cwd,
+    failureCode: CaatingaErrorCode.INVOKE_FAILED
+  });
+  return {
+    target,
+    network,
+    result: result.stdout || result.all
+  };
+}
+
 // src/templates/create-project-from-template.ts
 var import_promises8 = require("fs/promises");
-var import_node_path10 = __toESM(require("path"), 1);
+var import_node_path11 = __toESM(require("path"), 1);
 var import_zod7 = require("zod");
 
 // src/templates/template-manifest.schema.ts
@@ -1675,8 +1861,8 @@ var TEMPLATE_COPY_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git"
 ]);
 async function createProjectFromTemplate(options) {
-  const targetDir = import_node_path10.default.resolve(options.targetDir);
-  const templateDir = import_node_path10.default.resolve(options.templateDir);
+  const targetDir = import_node_path11.default.resolve(options.targetDir);
+  const templateDir = import_node_path11.default.resolve(options.templateDir);
   try {
     await (0, import_promises8.stat)(templateDir);
   } catch {
@@ -1714,7 +1900,7 @@ async function ensureArtifacts(targetDir, projectName) {
   }
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = import_node_path10.default.join(templateDir, "caatinga.template.json");
+  const manifestPath = import_node_path11.default.join(templateDir, "caatinga.template.json");
   try {
     const rawManifest = await (0, import_promises8.readFile)(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
@@ -1751,7 +1937,7 @@ async function readTemplateManifest(templateDir) {
 async function replaceTemplateVariables(dir, projectName) {
   const entries = await (0, import_promises8.readdir)(dir);
   await Promise.all(entries.map(async (entry) => {
-    const entryPath = import_node_path10.default.join(dir, entry);
+    const entryPath = import_node_path11.default.join(dir, entry);
     const entryStat = await (0, import_promises8.stat)(entryPath);
     if (entryStat.isDirectory()) {
       await replaceTemplateVariables(entryPath, projectName);
@@ -1765,15 +1951,15 @@ async function replaceTemplateVariables(dir, projectName) {
   }));
 }
 function shouldCopyTemplateEntry(templateDir, source, userFilter) {
-  const relativePath = import_node_path10.default.relative(templateDir, source);
+  const relativePath = import_node_path11.default.relative(templateDir, source);
   if (!relativePath || relativePath === ".") {
     return true;
   }
-  const normalizedPath = relativePath.split(import_node_path10.default.sep).join("/");
+  const normalizedPath = relativePath.split(import_node_path11.default.sep).join("/");
   if (userFilter && !userFilter(normalizedPath)) {
     return false;
   }
-  return !relativePath.split(import_node_path10.default.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
+  return !relativePath.split(import_node_path11.default.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
 }
 function isTextTemplateFile(filePath) {
   return [
@@ -1785,7 +1971,224 @@ function isTextTemplateFile(filePath) {
     ".tsx",
     ".css",
     ".html"
-  ].includes(import_node_path10.default.extname(filePath));
+  ].includes(import_node_path11.default.extname(filePath));
+}
+
+// src/scaffold/create-zk-project.ts
+var import_promises9 = require("fs/promises");
+var import_node_fs2 = require("fs");
+var import_node_path12 = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_meta2 = {};
+var moduleDir = typeof __dirname === "string" ? __dirname : import_node_path12.default.dirname((0, import_node_url.fileURLToPath)(import_meta2.url));
+function scaffoldRoot() {
+  const candidates = [
+    import_node_path12.default.resolve(moduleDir, "../../scaffolds"),
+    import_node_path12.default.resolve(moduleDir, "../scaffolds")
+  ];
+  const found = candidates.find((candidate) => (0, import_node_fs2.existsSync)(candidate));
+  return found ?? candidates[0];
+}
+function configSource(projectName) {
+  return `import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "${projectName}",
+  defaultNetwork: "testnet",
+  contracts: {
+    verifier: {
+      path: "./contracts/verifier",
+      wasm: "./contracts/verifier/target/wasm32v1-none/release/verifier.wasm"
+    }
+  },
+  networks: {
+    testnet: {
+      rpcUrl: "https://soroban-testnet.stellar.org",
+      networkPassphrase: "Test SDF Network ; September 2015"
+    }
+  },
+  zk: {
+    circuits: {
+      main: {
+        path: "./circuits",
+        protocol: "groth16",
+        curve: "bls12381",
+        verifierContract: "verifier"
+      }
+    }
+  }
+});
+`;
+}
+function packageJsonSource(projectName) {
+  return `${JSON.stringify({
+    name: projectName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+      "zk:build": "caatinga zk build main",
+      "zk:prove": "caatinga zk prove main",
+      build: "caatinga build verifier",
+      deploy: "caatinga deploy verifier"
+    },
+    devDependencies: {
+      "@caatinga/cli": `^${CAATINGA_CORE_VERSION}`,
+      "@caatinga/core": `^${CAATINGA_CORE_VERSION}`
+    }
+  }, null, 2)}
+`;
+}
+function readmeSource(projectName) {
+  return `# ${projectName}
+
+Minimal Caatinga ZK project.
+
+## Workflow
+
+\`\`\`bash
+npm install
+npx caatinga zk build main
+npx caatinga build verifier
+npx caatinga deploy verifier --network testnet
+npx caatinga zk prove main
+\`\`\`
+
+Replace \`circuits/main.circom\` with your circuit. Keep the entry point named \`main\`.
+`;
+}
+async function createZkProject(options) {
+  const targetDir = import_node_path12.default.resolve(options.targetDir);
+  const force = options.force ?? false;
+  const projectFiles = options.projectFiles ?? true;
+  await (0, import_promises9.mkdir)(targetDir, { recursive: true });
+  if (projectFiles) {
+    await Promise.all([
+      (0, import_promises9.writeFile)(import_node_path12.default.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+      (0, import_promises9.writeFile)(import_node_path12.default.join(targetDir, "package.json"), packageJsonSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+      (0, import_promises9.writeFile)(import_node_path12.default.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", { encoding: "utf8", flag: force ? "w" : "wx" }),
+      (0, import_promises9.writeFile)(import_node_path12.default.join(targetDir, "README.md"), readmeSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" })
+    ]);
+  }
+  await (0, import_promises9.mkdir)(import_node_path12.default.join(targetDir, "contracts"), { recursive: true });
+  await (0, import_promises9.cp)(import_node_path12.default.join(scaffoldRoot(), "zk-circuit-stub"), import_node_path12.default.join(targetDir, "circuits"), {
+    recursive: true,
+    force,
+    errorOnExist: !force
+  });
+  await (0, import_promises9.cp)(import_node_path12.default.join(scaffoldRoot(), "zk-verifier"), import_node_path12.default.join(targetDir, "contracts", "verifier"), {
+    recursive: true,
+    force,
+    errorOnExist: !force
+  });
+  if (projectFiles) {
+    await writeArtifacts(createInitialArtifacts(options.projectName, { networks: ["testnet"] }), targetDir);
+  }
+  return { targetDir };
+}
+
+// src/scaffold/create-minimal-project.ts
+var import_promises10 = require("fs/promises");
+var import_node_fs3 = require("fs");
+var import_node_path13 = __toESM(require("path"), 1);
+var import_node_url2 = require("url");
+var import_meta3 = {};
+var moduleDir2 = typeof __dirname === "string" ? __dirname : import_node_path13.default.dirname((0, import_node_url2.fileURLToPath)(import_meta3.url));
+function scaffoldRoot2() {
+  const candidates = [
+    import_node_path13.default.resolve(moduleDir2, "../../scaffolds"),
+    import_node_path13.default.resolve(moduleDir2, "../scaffolds")
+  ];
+  const found = candidates.find((candidate) => (0, import_node_fs3.existsSync)(candidate));
+  return found ?? candidates[0];
+}
+function configSource2(projectName) {
+  return `import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "${projectName}",
+  defaultNetwork: "testnet",
+  contracts: {
+    app: {
+      path: "./contracts/app",
+      wasm: "./contracts/app/target/wasm32v1-none/release/app.wasm"
+    }
+  },
+  networks: {
+    testnet: {
+      rpcUrl: "https://soroban-testnet.stellar.org",
+      networkPassphrase: "Test SDF Network ; September 2015"
+    }
+  }
+});
+`;
+}
+function packageJsonSource2(projectName) {
+  return `${JSON.stringify({
+    name: projectName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+      build: "caatinga build app",
+      deploy: "caatinga deploy app --network testnet --source ${CAATINGA_SOURCE:-alice}",
+      doctor: "caatinga doctor",
+      "read:hello": "caatinga read app.hello --network testnet --source ${CAATINGA_SOURCE:-alice}",
+      "read:version": "caatinga read app.version --network testnet --source ${CAATINGA_SOURCE:-alice}"
+    },
+    devDependencies: {
+      "@caatinga/cli": `^${CAATINGA_CORE_VERSION}`,
+      "@caatinga/core": `^${CAATINGA_CORE_VERSION}`
+    }
+  }, null, 2)}
+`;
+}
+function readmeSource2(projectName) {
+  return `# ${projectName}
+
+Minimal Caatinga project with a Soroban contract stub (no frontend template).
+
+## Workflow
+
+\`\`\`bash
+npm install
+npx caatinga doctor
+npx caatinga build app
+npx caatinga deploy app --network testnet --source <identity>
+npx caatinga read app.version --network testnet
+npx caatinga read app.hello --network testnet
+\`\`\`
+
+## Contract
+
+- \`hello()\` \u2014 read-only; returns Soroban Symbol \`hello\`
+- \`version()\` \u2014 read-only; returns \`1\`
+
+Use \`caatinga read\` for read-only methods. Use \`caatinga invoke\` only after you add state-changing methods to the contract.
+
+Soroban \`Symbol\` parameters are generated as TypeScript \`string\` values with host-specific restrictions \u2014 see the Caatinga docs on [Soroban types](https://github.com/caatinga/caatinga/blob/main/docs/soroban-types.md).
+
+Edit \`contracts/app/src/lib.rs\` to customize the contract. Add a frontend later with \`@caatinga/client\` and your chosen UI stack.
+`;
+}
+async function createMinimalProject(options) {
+  const targetDir = import_node_path13.default.resolve(options.targetDir);
+  const force = options.force ?? false;
+  await (0, import_promises10.mkdir)(targetDir, { recursive: true });
+  await Promise.all([
+    (0, import_promises10.writeFile)(import_node_path13.default.join(targetDir, "caatinga.config.ts"), configSource2(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+    (0, import_promises10.writeFile)(import_node_path13.default.join(targetDir, "package.json"), packageJsonSource2(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+    (0, import_promises10.writeFile)(import_node_path13.default.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", { encoding: "utf8", flag: force ? "w" : "wx" }),
+    (0, import_promises10.writeFile)(import_node_path13.default.join(targetDir, "README.md"), readmeSource2(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" })
+  ]);
+  await (0, import_promises10.mkdir)(import_node_path13.default.join(targetDir, "contracts"), { recursive: true });
+  await (0, import_promises10.cp)(import_node_path13.default.join(scaffoldRoot2(), "soroban-contract-stub"), import_node_path13.default.join(targetDir, "contracts", "app"), {
+    recursive: true,
+    force,
+    errorOnExist: !force
+  });
+  await writeArtifacts(createInitialArtifacts(options.projectName, { networks: ["testnet"] }), targetDir);
+  return { targetDir };
 }
 
 // src/ci/is-transient-testnet-smoke-failure.ts
@@ -1817,17 +2220,21 @@ function isTransientTestnetSmokeFailure(logText) {
   CaatingaConfigSchema,
   CaatingaError,
   CaatingaErrorCode,
+  READ_CALL_FAILURE_REGEX,
   STELLAR_CLI_LAST_TESTED_VERSION,
   STELLAR_CLI_MIN_VERSION,
   TemplateManifestSchema,
   WELL_KNOWN_NETWORKS,
   buildContract,
   buildDependencyGraph,
+  buildReadCallHint,
   checkBinary,
   checkStellarCliVersion,
   collectProjectStatus,
   createInitialArtifacts,
+  createMinimalProject,
   createProjectFromTemplate,
+  createZkProject,
   defineConfig,
   deployContract,
   deployContractGraph,
@@ -1838,6 +2245,8 @@ function isTransientTestnetSmokeFailure(logText) {
   generateBindings,
   generateBindingsGraph,
   invokeContract,
+  isCargoBinMissingFromPath,
+  isReadCallFailure,
   isTransientTestnetSmokeFailure,
   loadConfig,
   parseContractId,
@@ -1845,11 +2254,13 @@ function isTransientTestnetSmokeFailure(logText) {
   parseStellarCliVersion,
   readArtifacts,
   readBindingMarker,
+  readContract,
   resolveContract,
   resolveDefaultContractName,
   resolveDeployArgs,
   resolveDeployOrder,
   resolveNetwork,
+  resolveSubprocessEnv,
   runCommand,
   toCaatingaError,
   updateArtifact,