@caatinga/core 3.2.0 → 3.3.1

package/dist/index.js

@@ -8,6 +8,8 @@ var CaatingaErrorCode = {
   STELLAR_CLI_NOT_FOUND: "CAATINGA_STELLAR_CLI_NOT_FOUND",
   STELLAR_CLI_VERSION_PARSE_FAILED: "CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED",
   UNSUPPORTED_CLI_VERSION: "CAATINGA_UNSUPPORTED_CLI_VERSION",
+  STELLAR_SDK_VERSION_PARSE_FAILED: "CAATINGA_STELLAR_SDK_VERSION_PARSE_FAILED",
+  UNSUPPORTED_SDK_VERSION: "CAATINGA_UNSUPPORTED_SDK_VERSION",
   RUST_NOT_FOUND: "CAATINGA_RUST_NOT_FOUND",
   RUST_TARGET_NOT_FOUND: "CAATINGA_RUST_TARGET_NOT_FOUND",
   DEPLOY_FAILED: "CAATINGA_DEPLOY_FAILED",
@@ -50,6 +52,8 @@ var CaatingaErrorCode = {
   ZK_VERIFICATION_FAILED: "CAATINGA_ZK_VERIFICATION_FAILED",
   ZK_DEV_CEREMONY_BLOCKED: "CAATINGA_ZK_DEV_CEREMONY_BLOCKED",
   DOCTOR_PARTIAL_DEPLOY: "CAATINGA_DOCTOR_PARTIAL_DEPLOY",
+  ROLLBACK_TARGET_NOT_FOUND: "CAATINGA_ROLLBACK_TARGET_NOT_FOUND",
+  ESTIMATE_FAILED: "CAATINGA_ESTIMATE_FAILED",
   MULTI_AUTH_REQUIRED: "CAATINGA_MULTI_AUTH_REQUIRED"
 };
 
@@ -236,6 +240,14 @@ async function loadConfig(options = {}) {
 
 // src/artifacts/artifact.schema.ts
 import { z as z3 } from "zod";
+var ArtifactSupersedeReasonSchema = z3.enum(["upgrade", "rollback", "force-redeploy"]);
+var ContractArtifactHistoryEntrySchema = z3.object({
+  contractId: z3.string().min(1),
+  wasmHash: z3.string().min(1),
+  deployedAt: z3.string().datetime(),
+  supersededAt: z3.string().datetime(),
+  reason: ArtifactSupersedeReasonSchema.optional()
+});
 var ContractArtifactSchema = z3.object({
   contractId: z3.string().min(1),
   wasmHash: z3.string().min(1),
@@ -243,17 +255,28 @@ var ContractArtifactSchema = z3.object({
   sourcePath: z3.string().min(1),
   wasmPath: z3.string().min(1),
   dependencies: z3.array(z3.string().min(1)).default([]),
-  resolvedDeployArgs: z3.record(z3.string().min(1), z3.union([z3.string(), z3.number(), z3.boolean()])).default({})
+  resolvedDeployArgs: z3.record(z3.string().min(1), z3.union([z3.string(), z3.number(), z3.boolean()])).default({}),
+  history: z3.array(ContractArtifactHistoryEntrySchema).optional()
 });
 var NetworkArtifactsSchema = z3.object({
   contracts: z3.record(z3.string().min(1), ContractArtifactSchema).default({}),
   dependencyGraph: z3.record(z3.string().min(1), z3.array(z3.string().min(1))).default({})
 });
-var CaatingaArtifactsSchema = z3.object({
+var CaatingaArtifactsBaseSchema = z3.object({
   project: z3.string().min(1),
-  version: z3.literal(1),
   networks: z3.record(z3.string().min(1), NetworkArtifactsSchema).default({})
 });
+var CaatingaArtifactsV1Schema = CaatingaArtifactsBaseSchema.extend({
+  version: z3.literal(1)
+});
+var CaatingaArtifactsV2Schema = CaatingaArtifactsBaseSchema.extend({
+  version: z3.literal(2)
+});
+var CaatingaArtifactsSchema = z3.union([
+  CaatingaArtifactsV1Schema,
+  CaatingaArtifactsV2Schema
+]);
+var CURRENT_ARTIFACTS_SCHEMA_VERSION = 2;
 
 // src/artifacts/read-artifacts.ts
 import { readFile } from "fs/promises";
@@ -305,29 +328,139 @@ function createInitialArtifacts(project, options = {}) {
   );
   return {
     project,
-    version: 1,
+    version: 2,
     networks
   };
 }
 
 // src/artifacts/update-artifact.ts
-function updateArtifact(artifacts, networkName, contractName, contractArtifact, networkExtras) {
+function appendHistory(existing, reason) {
+  if (!existing || !reason) {
+    return existing?.history;
+  }
+  const supersededAt = (/* @__PURE__ */ new Date()).toISOString();
+  const entry = {
+    contractId: existing.contractId,
+    wasmHash: existing.wasmHash,
+    deployedAt: existing.deployedAt,
+    supersededAt,
+    reason
+  };
+  return [...existing.history ?? [], entry];
+}
+function updateArtifact(artifacts, networkName, contractName, contractArtifact, options = {}) {
   const existingNetwork = artifacts.networks[networkName] ?? { contracts: {}, dependencyGraph: {} };
+  const existingContract = existingNetwork.contracts[contractName];
+  const history = appendHistory(existingContract, options.supersedeReason);
+  const nextVersion = artifacts.version === 1 && options.supersedeReason ? 2 : artifacts.version;
   return {
     ...artifacts,
+    version: nextVersion,
     networks: {
       ...artifacts.networks,
       [networkName]: {
         ...existingNetwork,
-        dependencyGraph: networkExtras?.dependencyGraph ?? existingNetwork.dependencyGraph ?? {},
+        dependencyGraph: options.dependencyGraph ?? existingNetwork.dependencyGraph ?? {},
         contracts: {
           ...existingNetwork.contracts,
-          [contractName]: contractArtifact
+          [contractName]: {
+            ...contractArtifact,
+            history: history ?? contractArtifact.history
+          }
         }
       }
     }
   };
 }
+function restoreArtifactFromHistory(input) {
+  const network = input.artifacts.networks[input.networkName];
+  const current = network?.contracts[input.contractName];
+  if (!current) {
+    throw new CaatingaError(
+      `No artifact for "${input.contractName}" on "${input.networkName}".`,
+      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+      "Deploy the contract before attempting rollback."
+    );
+  }
+  if (current.contractId === input.contractId) {
+    return input.artifacts;
+  }
+  const fromHistory = (current.history ?? []).find(
+    (entry) => entry.contractId === input.contractId
+  );
+  if (!fromHistory) {
+    throw new CaatingaError(
+      `Rollback target "${input.contractId}" was not found in artifact history for "${input.contractName}".`,
+      CaatingaErrorCode.ROLLBACK_TARGET_NOT_FOUND,
+      "Use caatinga inspect to list prior contract IDs, or redeploy manually."
+    );
+  }
+  const supersededAt = (/* @__PURE__ */ new Date()).toISOString();
+  const restoredArtifact = {
+    contractId: fromHistory.contractId,
+    wasmHash: fromHistory.wasmHash,
+    deployedAt: fromHistory.deployedAt,
+    sourcePath: current.sourcePath,
+    wasmPath: current.wasmPath,
+    dependencies: current.dependencies,
+    resolvedDeployArgs: current.resolvedDeployArgs,
+    history: [
+      ...current.history ?? [],
+      {
+        contractId: current.contractId,
+        wasmHash: current.wasmHash,
+        deployedAt: current.deployedAt,
+        supersededAt,
+        reason: "rollback"
+      }
+    ]
+  };
+  return {
+    ...updateArtifact(input.artifacts, input.networkName, input.contractName, restoredArtifact),
+    version: 2
+  };
+}
+
+// src/artifacts/migrate-artifacts.ts
+function migrateArtifactsToV2(artifacts) {
+  if (artifacts.version === CURRENT_ARTIFACTS_SCHEMA_VERSION) {
+    return {
+      artifacts,
+      migrated: false
+    };
+  }
+  const v1 = artifacts;
+  return {
+    artifacts: {
+      project: v1.project,
+      version: CURRENT_ARTIFACTS_SCHEMA_VERSION,
+      networks: v1.networks
+    },
+    migrated: true
+  };
+}
+
+// src/artifacts/migrate-artifacts-file.ts
+async function migrateArtifactsFile(cwd = process.cwd()) {
+  const artifacts = await readArtifacts(cwd);
+  const { artifacts: migrated, migrated: changed } = migrateArtifactsToV2(artifacts);
+  const path17 = await writeArtifacts(migrated, cwd);
+  return { path: path17, migrated: changed, artifacts: migrated };
+}
+
+// src/artifacts/rollback-artifact.ts
+async function rollbackContractArtifact(input) {
+  const cwd = input.cwd ?? process.cwd();
+  const artifacts = await readArtifacts(cwd);
+  const next = restoreArtifactFromHistory({
+    artifacts,
+    networkName: input.networkName,
+    contractName: input.contractName,
+    contractId: input.contractId
+  });
+  const path17 = await writeArtifacts(next, cwd);
+  return { path: path17, artifacts: next };
+}
 
 // src/networks/resolve-network.ts
 function resolveNetwork(config, networkName) {
@@ -594,6 +727,35 @@ function evaluateStellarCliCompatibility(input) {
   };
 }
 
+// src/stellar-cli/probe-stellar-cli-features.ts
+import semver3 from "semver";
+var STELLAR_CLI_REQUIRED_FEATURES = [
+  "contract-build",
+  "contract-deploy",
+  "contract-invoke-sign"
+];
+var FEATURE_COMMANDS = {
+  "contract-build": ["contract", "build", "--help"],
+  "contract-deploy": ["contract", "deploy", "--help"],
+  "contract-invoke-sign": ["contract", "invoke", "--help"]
+};
+async function probeMissingStellarCliFeatures(version) {
+  const missing = [];
+  if (semver3.valid(version) && semver3.lt(version, STELLAR_CLI_MIN_VERSION)) {
+    return ["contract-invoke-sign"];
+  }
+  for (const feature of STELLAR_CLI_REQUIRED_FEATURES) {
+    try {
+      await runCommand("stellar", FEATURE_COMMANDS[feature], {
+        skipStellarVersionCheck: true
+      });
+    } catch {
+      missing.push(feature);
+    }
+  }
+  return missing;
+}
+
 // src/stellar-cli/check-stellar-cli-version.ts
 async function checkStellarCliVersion(input = {}) {
   let rawOutput;
@@ -613,9 +775,12 @@ async function checkStellarCliVersion(input = {}) {
     }
     throw error;
   }
+  const version = parseStellarCliVersion(rawOutput);
+  const probedMissing = input.probeFeatures === false ? [] : await probeMissingStellarCliFeatures(version);
+  const missingFeatures = [...input.features ?? [], ...probedMissing];
   const report = evaluateStellarCliCompatibility({
-    version: parseStellarCliVersion(rawOutput),
-    features: input.features,
+    version,
+    features: missingFeatures.length > 0 ? missingFeatures : void 0,
     lastTestedVersion: input.lastTestedVersion
   });
   for (const warning of report.warnings) {
@@ -761,6 +926,122 @@ function parseContractId(output) {
   return match[0];
 }
 
+// src/stellar-sdk/check-stellar-sdk-version.ts
+import { readFile as readFile3 } from "fs/promises";
+import path7 from "path";
+
+// src/stellar-sdk/compat.ts
+import semver4 from "semver";
+
+// src/stellar-sdk/version.ts
+var STELLAR_SDK_MIN_VERSION = "16.0.1";
+var STELLAR_SDK_LAST_TESTED_VERSION = "16.0.1";
+
+// src/stellar-sdk/compat.ts
+function evaluateStellarSdkCompatibility(input) {
+  const parsed = semver4.parse(input.version);
+  if (!parsed || !semver4.valid(input.version)) {
+    throw new CaatingaError(
+      "Could not parse @stellar/stellar-sdk version.",
+      CaatingaErrorCode.STELLAR_SDK_VERSION_PARSE_FAILED,
+      "Use a semantic version such as 16.0.1."
+    );
+  }
+  const lastTestedVersion = semver4.valid(input.lastTestedVersion ?? STELLAR_SDK_LAST_TESTED_VERSION) ?? STELLAR_SDK_LAST_TESTED_VERSION;
+  const warnings = [];
+  let status = "supported";
+  if (semver4.lt(parsed, STELLAR_SDK_MIN_VERSION)) {
+    throw new CaatingaError(
+      `@stellar/stellar-sdk ${input.version} is below the supported minimum ${STELLAR_SDK_MIN_VERSION}.`,
+      CaatingaErrorCode.UNSUPPORTED_SDK_VERSION,
+      `Install @stellar/stellar-sdk ${STELLAR_SDK_MIN_VERSION} or newer.`
+    );
+  }
+  if (semver4.gt(parsed, lastTestedVersion)) {
+    status = "untested";
+    warnings.push({
+      code: "STELLAR_SDK_UNTESTED_VERSION",
+      message: `@stellar/stellar-sdk ${input.version} is newer than the last-tested ${lastTestedVersion}; binding output may differ.`,
+      remediation: "Pin @stellar/stellar-sdk to the last-tested version in package.json, or update Caatinga fixtures after validating generate output."
+    });
+  }
+  return {
+    version: input.version,
+    status,
+    minVersion: STELLAR_SDK_MIN_VERSION,
+    lastTestedVersion,
+    warnings
+  };
+}
+function parseStellarSdkVersion(raw) {
+  const trimmed = raw.trim();
+  const match = trimmed.match(/(\d+\.\d+\.\d+(?:[-+][\w.-]+)?)/);
+  if (!match) {
+    throw new CaatingaError(
+      "Could not parse @stellar/stellar-sdk version.",
+      CaatingaErrorCode.STELLAR_SDK_VERSION_PARSE_FAILED,
+      "Expected output like 16.0.1."
+    );
+  }
+  return match[1];
+}
+
+// src/stellar-sdk/check-stellar-sdk-version.ts
+async function readInstalledSdkVersion(cwd) {
+  try {
+    const pkgPath = path7.join(cwd, "node_modules", "@stellar", "stellar-sdk", "package.json");
+    const raw = await readFile3(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function resolveRegistrySdkVersion() {
+  const result = await runCommand("npm", ["view", "@stellar/stellar-sdk", "version"], {
+    skipStellarVersionCheck: true
+  });
+  return parseStellarSdkVersion(result.stdout || result.all);
+}
+async function checkStellarSdkVersion(input = {}) {
+  const cwd = input.cwd ?? process.cwd();
+  let version;
+  try {
+    const installed = await readInstalledSdkVersion(cwd);
+    version = installed ?? await resolveRegistrySdkVersion();
+  } catch (error) {
+    if (error instanceof CaatingaError) {
+      throw error;
+    }
+    throw new CaatingaError(
+      "Could not resolve @stellar/stellar-sdk version.",
+      CaatingaErrorCode.STELLAR_SDK_VERSION_PARSE_FAILED,
+      "Install @stellar/stellar-sdk in your project or ensure npm registry access.",
+      error
+    );
+  }
+  const report = evaluateStellarSdkCompatibility({
+    version,
+    lastTestedVersion: input.lastTestedVersion
+  });
+  for (const warning of report.warnings) {
+    if (input.onWarning) {
+      input.onWarning(warning);
+    } else {
+      defaultEmitWarning2(warning);
+    }
+  }
+  return report;
+}
+function defaultEmitWarning2(warning) {
+  const lines = [
+    `Warning: ${warning.message}`,
+    warning.remediation ? `  ${warning.remediation}` : void 0
+  ].filter((line) => Boolean(line));
+  process.stderr.write(`${lines.join("\n")}
+`);
+}
+
 // src/stellar-cli/build-stellar-network-args.ts
 function matchesWellKnownNetwork(name, config) {
   const known = WELL_KNOWN_NETWORKS[name];
@@ -898,8 +1179,38 @@ function validateSourceShape(source) {
   return void 0;
 }
 
+// src/contracts/source-account.ts
+function assertSafeSourceAccount(source) {
+  if (!source) {
+    throw new CaatingaError(
+      "A source account or Stellar CLI identity is required.",
+      CaatingaErrorCode.SOURCE_ACCOUNT_REQUIRED,
+      "Pass a Stellar CLI identity alias, for example: --source alice"
+    );
+  }
+  const unsafeSource = validateSourceShape(source);
+  if (unsafeSource) {
+    throw unsafeSource;
+  }
+  return source;
+}
+var DEFAULT_CLI_SOURCE = "alice";
+function describeCliSource(explicit) {
+  if (explicit) {
+    return { source: assertSafeSourceAccount(explicit), origin: "explicit" };
+  }
+  const fromEnv = process.env.CAATINGA_SOURCE;
+  if (fromEnv) {
+    return { source: assertSafeSourceAccount(fromEnv), origin: "env" };
+  }
+  return { source: assertSafeSourceAccount(DEFAULT_CLI_SOURCE), origin: "default" };
+}
+function resolveCliSource(explicit) {
+  return describeCliSource(explicit).source;
+}
+
 // src/contracts/resolve-contract.ts
-import path7 from "path";
+import path8 from "path";
 function resolveContract(config, contractName, cwd = process.cwd()) {
   const contract = config.contracts[contractName];
   if (!contract) {
@@ -912,8 +1223,8 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
   return {
     name: contractName,
     config: contract,
-    sourcePath: path7.resolve(cwd, contract.path),
-    wasmPath: path7.resolve(cwd, contract.wasm)
+    sourcePath: path8.resolve(cwd, contract.path),
+    wasmPath: path8.resolve(cwd, contract.wasm)
   };
 }
 
@@ -932,8 +1243,8 @@ function resolveDefaultContractName(config) {
 
 // src/contracts/wasm.ts
 import { createHash } from "crypto";
-import { access as access2, readdir as readdir2, readFile as readFile3, stat } from "fs/promises";
-import path8 from "path";
+import { access as access2, readdir as readdir2, readFile as readFile4, stat } from "fs/promises";
+import path9 from "path";
 var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
 var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
 function toCurrentWasmTargetPath(wasmPath) {
@@ -964,18 +1275,18 @@ function wasmNotFoundError(configuredWasmPath, options) {
   );
 }
 function toConfigRelativeWasmPath(absoluteWasmPath) {
-  const relative = path8.relative(process.cwd(), absoluteWasmPath);
-  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path8.sep).join("/")}`;
+  const relative = path9.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path9.sep).join("/")}`;
 }
 function wasmFileName(configuredWasmPath) {
-  return path8.basename(configuredWasmPath);
+  return path9.basename(configuredWasmPath);
 }
 function buildAlternateWasmCandidates(configuredWasmPath, options) {
   const fileName = wasmFileName(configuredWasmPath);
   const candidates = [];
   const seen = /* @__PURE__ */ new Set();
   function addCandidate(candidate) {
-    const resolved = path8.resolve(candidate);
+    const resolved = path9.resolve(candidate);
     if (seen.has(resolved)) {
       return;
     }
@@ -984,15 +1295,15 @@ function buildAlternateWasmCandidates(configuredWasmPath, options) {
   }
   const cargoTargetDir = process.env.CARGO_TARGET_DIR;
   if (cargoTargetDir) {
-    addCandidate(path8.join(cargoTargetDir, CURRENT_RUST_WASM_TARGET, "release", fileName));
-    addCandidate(path8.join(cargoTargetDir, LEGACY_RUST_WASM_TARGET, "release", fileName));
+    addCandidate(path9.join(cargoTargetDir, CURRENT_RUST_WASM_TARGET, "release", fileName));
+    addCandidate(path9.join(cargoTargetDir, LEGACY_RUST_WASM_TARGET, "release", fileName));
   }
   if (options?.sourcePath) {
     addCandidate(
-      path8.join(options.sourcePath, "target", CURRENT_RUST_WASM_TARGET, "release", fileName)
+      path9.join(options.sourcePath, "target", CURRENT_RUST_WASM_TARGET, "release", fileName)
     );
     addCandidate(
-      path8.join(options.sourcePath, "target", LEGACY_RUST_WASM_TARGET, "release", fileName)
+      path9.join(options.sourcePath, "target", LEGACY_RUST_WASM_TARGET, "release", fileName)
     );
   }
   return candidates;
@@ -1009,7 +1320,7 @@ async function firstExistingPath(paths) {
   return void 0;
 }
 async function resolveWasmArtifactPath(configuredWasmPath, options) {
-  const resolvedConfiguredPath = path8.resolve(configuredWasmPath);
+  const resolvedConfiguredPath = path9.resolve(configuredWasmPath);
   try {
     await access2(resolvedConfiguredPath);
     return resolvedConfiguredPath;
@@ -1033,7 +1344,7 @@ async function resolveWasmArtifactPath(configuredWasmPath, options) {
   }
 }
 async function hashWasm(wasmPath) {
-  const bytes = await readFile3(wasmPath);
+  const bytes = await readFile4(wasmPath);
   return createHash("sha256").update(bytes).digest("hex");
 }
 async function getNewestMtimeInDirectory(directory) {
@@ -1046,7 +1357,7 @@ async function getNewestMtimeInDirectory(directory) {
   async function walk(dir) {
     const entries = await readdir2(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const entryPath = path8.join(dir, entry.name);
+      const entryPath = path9.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(entryPath);
         continue;
@@ -1062,7 +1373,7 @@ async function getNewestMtimeInDirectory(directory) {
   return newest > 0 ? newest : void 0;
 }
 async function isWasmOlderThanSources(input) {
-  const srcDir = path8.join(input.contractPath, "src");
+  const srcDir = path9.join(input.contractPath, "src");
   const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
   if (newestSourceMtime === void 0) {
     return false;
@@ -1137,7 +1448,38 @@ async function buildContract(options) {
 }
 
 // src/contracts/deploy-contract.ts
-import path9 from "path";
+import path10 from "path";
+
+// src/shell/is-transient-command-failure.ts
+var NO_RETRY_CAATINGA_SUBSTRINGS = [
+  "CAATINGA_UNSUPPORTED_CLI_VERSION",
+  "CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED",
+  "CAATINGA_STELLAR_CLI_NOT_FOUND",
+  "CAATINGA_INVALID_CONFIG",
+  "CAATINGA_CONFIG_NOT_FOUND"
+];
+var TRANSIENT_COMMAND_FAILURE_PATTERN = /timeout|i\/o timeout|econnreset|connection reset|503|502|429|rate limit|temporar|bad gateway|fetch failed|network error|unavailable/i;
+function isTransientCommandFailure(logText) {
+  if (!logText.trim()) {
+    return false;
+  }
+  for (const marker of NO_RETRY_CAATINGA_SUBSTRINGS) {
+    if (logText.includes(marker)) {
+      return false;
+    }
+  }
+  return TRANSIENT_COMMAND_FAILURE_PATTERN.test(logText);
+}
+
+// src/contracts/is-transient-deploy-failure.ts
+function isTransientDeployFailure(error) {
+  if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.DEPLOY_FAILED) {
+    return false;
+  }
+  const logText = `${error.message}
+${error.hint ?? ""}`;
+  return isTransientCommandFailure(logText);
+}
 
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
@@ -1179,26 +1521,13 @@ function resolveDeployArgs(input) {
   return resolved;
 }
 
-// src/contracts/source-account.ts
-function assertSafeSourceAccount(source) {
-  if (!source) {
-    throw new CaatingaError(
-      "A source account or Stellar CLI identity is required.",
-      CaatingaErrorCode.SOURCE_ACCOUNT_REQUIRED,
-      "Pass a Stellar CLI identity alias, for example: --source alice"
-    );
-  }
-  const unsafeSource = validateSourceShape(source);
-  if (unsafeSource) {
-    throw unsafeSource;
-  }
-  return source;
-}
-function resolveCliSource(explicit) {
-  return assertSafeSourceAccount(explicit ?? process.env.CAATINGA_SOURCE ?? "alice");
-}
-
 // src/contracts/deploy-contract.ts
+var DEFAULT_DEPLOY_RETRY_DELAYS_MS = [2e3, 5e3];
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
 function toSnakeCaseFlag(key) {
   return key.replace(/([A-Z])/g, "_$1").replace(/^_/, "").toLowerCase();
 }
@@ -1243,7 +1572,7 @@ async function deployContract(options) {
       contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: path9.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: path10.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
       skipped: true,
       staleWasmWarning
@@ -1283,40 +1612,69 @@ async function deployContract(options) {
     ...buildStellarNetworkArgs(network),
     ...constructorArgs
   ];
-  let output = "";
-  let contractId;
-  try {
-    const result = await runCommand("stellar", stellarArgs, {
-      cwd,
-      failureCode: CaatingaErrorCode.DEPLOY_FAILED
-    });
-    output = result.all || `${result.stdout}
+  let deployOutcome;
+  const retryDelaysMs = options.deployRetryDelaysMs ?? DEFAULT_DEPLOY_RETRY_DELAYS_MS;
+  const maxDeployAttempts = retryDelaysMs.length + 1;
+  for (let attempt = 0; attempt < maxDeployAttempts; attempt++) {
+    try {
+      const result = await runCommand("stellar", stellarArgs, {
+        cwd,
+        failureCode: CaatingaErrorCode.DEPLOY_FAILED
+      });
+      const output2 = result.all || `${result.stdout}
 ${result.stderr}`;
-    contractId = parseContractId(output);
-  } catch (error) {
-    if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.DEPLOY_FAILED) {
-      throw error;
-    }
-    const recoveredContractId = await tryRecoverContractIdFromDeployFailure({
-      output: `${error.message}
+      deployOutcome = {
+        output: output2,
+        contractId: parseContractId(output2)
+      };
+      break;
+    } catch (error) {
+      if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.DEPLOY_FAILED) {
+        throw error;
+      }
+      const recoveredContractId = await tryRecoverContractIdFromDeployFailure({
+        output: `${error.message}
 ${error.hint ?? ""}`,
-      source,
-      network: network.config,
-      cwd
-    });
-    if (!recoveredContractId) {
-      throw error;
+        source,
+        network: network.config,
+        cwd
+      });
+      if (recoveredContractId) {
+        deployOutcome = {
+          output: [
+            error.hint ?? "",
+            "Caatinga recovered the contract ID from the on-chain deploy transaction.",
+            `Contract ID: ${recoveredContractId}`
+          ].filter(Boolean).join("\n"),
+          contractId: recoveredContractId
+        };
+        break;
+      }
+      const isLastAttempt = attempt === maxDeployAttempts - 1;
+      if (!isTransientDeployFailure(error) || isLastAttempt) {
+        throw error;
+      }
+      const delayMs = retryDelaysMs[attempt] ?? retryDelaysMs[retryDelaysMs.length - 1] ?? 0;
+      options.onTransientDeployRetry?.({
+        attempt: attempt + 1,
+        maxAttempts: maxDeployAttempts,
+        delayMs
+      });
+      await sleep(delayMs);
     }
-    contractId = recoveredContractId;
-    output = [
-      error.hint ?? "",
-      "Caatinga recovered the contract ID from the on-chain deploy transaction.",
-      `Contract ID: ${contractId}`
-    ].filter(Boolean).join("\n");
   }
+  if (!deployOutcome) {
+    throw new CaatingaError(
+      "Deploy failed without a contract ID.",
+      CaatingaErrorCode.DEPLOY_FAILED,
+      "Re-run the deploy command with the underlying Stellar CLI for full diagnostics."
+    );
+  }
+  const { output, contractId } = deployOutcome;
   const wasmHash = await hashWasm(wasmPath);
   const dependencyGraph = buildDependencyGraph(options.config.contracts);
   const dependencies = options.dependencies ?? contract.config.dependsOn;
+  const supersedeReason = existing?.contractId && options.force ? options.upgrade ? "upgrade" : "force-redeploy" : void 0;
   const nextArtifacts = updateArtifact(
     artifactsBefore,
     network.name,
@@ -1330,7 +1688,7 @@ ${error.hint ?? ""}`,
       dependencies,
       resolvedDeployArgs
     },
-    { dependencyGraph }
+    { dependencyGraph, supersedeReason }
   );
   const artifactsPath = await writeArtifacts(nextArtifacts, cwd);
   return {
@@ -1494,9 +1852,11 @@ async function deployContractGraph(options) {
       source: options.source,
       cwd,
       force: options.force,
+      upgrade: options.upgrade,
       checkStaleWasm: options.checkStaleWasm,
       resolvedDeployArgs,
-      dependencies: contractConfig.dependsOn
+      dependencies: contractConfig.dependsOn,
+      onTransientDeployRetry: options.onTransientDeployRetry
     });
     if (result.staleWasmWarning) {
       staleWasmWarnings.push({
@@ -1520,11 +1880,11 @@ async function deployContractGraph(options) {
 
 // src/contracts/generate-bindings.ts
 import { access as access4, mkdir as mkdir2, unlink } from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 
 // src/bindings/patch-generated-binding-package.ts
-import { access as access3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
-import path10 from "path";
+import { access as access3, readFile as readFile5, writeFile as writeFile3 } from "fs/promises";
+import path11 from "path";
 var BUNDLER_ENTRY = "./src/index.ts";
 var ROOT_BINDING_INDEX_CONTENT = 'export * from "./src/index.js";\n';
 function resolveExportEntry(exportsField) {
@@ -1559,9 +1919,9 @@ function shouldPatchPackageJson(packageJson) {
   return pointsToDist(packageJson.main) || pointsToDist(packageJson.types) || !pointsToBundlerSource(exportEntry);
 }
 async function ensureRootBindingIndex(outputDir) {
-  const rootIndexPath = path10.join(outputDir, "index.ts");
+  const rootIndexPath = path11.join(outputDir, "index.ts");
   try {
-    const existing = await readFile4(rootIndexPath, "utf8");
+    const existing = await readFile5(rootIndexPath, "utf8");
     if (existing === ROOT_BINDING_INDEX_CONTENT) {
       return;
     }
@@ -1571,8 +1931,8 @@ async function ensureRootBindingIndex(outputDir) {
   }
 }
 async function patchGeneratedBindingPackage(outputDir) {
-  const packageJsonPath = path10.join(outputDir, "package.json");
-  const entryPath = path10.join(outputDir, "src", "index.ts");
+  const packageJsonPath = path11.join(outputDir, "package.json");
+  const entryPath = path11.join(outputDir, "src", "index.ts");
   try {
     await access3(entryPath);
   } catch {
@@ -1584,7 +1944,7 @@ async function patchGeneratedBindingPackage(outputDir) {
   }
   let raw;
   try {
-    raw = await readFile4(packageJsonPath, "utf8");
+    raw = await readFile5(packageJsonPath, "utf8");
   } catch {
     throw new CaatingaError(
       "Generated binding package is missing package.json.",
@@ -1625,11 +1985,11 @@ function buildGenerateNetworkArgs(network) {
 
 // src/contracts/generate-bindings.ts
 function toBindingImportPath(bindingsOutput, contractName) {
-  const normalized = bindingsOutput.replace(/^\.\//, "").split(path11.sep).join("/");
-  return `./${path11.posix.join(normalized, contractName)}`;
+  const normalized = bindingsOutput.replace(/^\.\//, "").split(path12.sep).join("/");
+  return `./${path12.posix.join(normalized, contractName)}`;
 }
 async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
-  const legacyPath = path11.resolve(cwd, bindingsOutput, `${contractName}.ts`);
+  const legacyPath = path12.resolve(cwd, bindingsOutput, `${contractName}.ts`);
   try {
     await access4(legacyPath);
     await unlink(legacyPath);
@@ -1657,8 +2017,9 @@ async function generateBindings(options) {
       "Run caatinga deploy for this contract and network before generating bindings."
     );
   }
-  const outputDir = path11.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const outputDir = path12.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   await mkdir2(outputDir, { recursive: true });
+  await checkStellarSdkVersion({ cwd });
   const result = await runCommand(
     "npx",
     [
@@ -1883,14 +2244,172 @@ async function readContract(options) {
   };
 }
 
+// src/contracts/estimate-deploy-cost.ts
+import path13 from "path";
+function toSnakeCaseFlag2(key) {
+  return key.replace(/([A-Z])/g, "_$1").replace(/^_/, "").toLowerCase();
+}
+function formatConstructorCliArgs2(resolved) {
+  const entries = Object.entries(resolved);
+  if (entries.length === 0) {
+    return [];
+  }
+  const tail = ["--"];
+  for (const [key, value] of entries) {
+    tail.push(`--${toSnakeCaseFlag2(key)}`, String(value));
+  }
+  return tail;
+}
+function parseFeeStroops(output) {
+  const inclusionMatch = output.match(/inclusion[_\s-]*fee[:\s]+(\d+)/i);
+  const resourceMatch = output.match(/resource[_\s-]*fee[:\s]+(\d+)/i);
+  const totalMatch = output.match(/total[_\s-]*fee[:\s]+(\d+)/i);
+  return {
+    inclusion: inclusionMatch ? Number(inclusionMatch[1]) : void 0,
+    resource: resourceMatch ? Number(resourceMatch[1]) : void 0,
+    ...totalMatch && !resourceMatch ? { resource: Number(totalMatch[1]) } : {}
+  };
+}
+async function estimateDeployCost(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const contract = resolveContract(options.config, options.contractName, cwd);
+  const network = resolveNetwork(options.config, options.networkName);
+  const source = assertSafeSourceAccount(options.source);
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga estimate.");
+  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath, {
+    sourcePath: contract.sourcePath
+  });
+  const artifacts = await readArtifacts(cwd);
+  const rawDeployArgs = contract.config.deployArgs;
+  const resolvedDeployArgs = Object.keys(rawDeployArgs).length > 0 ? resolveDeployArgs({
+    deployArgs: rawDeployArgs,
+    artifacts,
+    network: network.name
+  }) : {};
+  const constructorArgs = formatConstructorCliArgs2(resolvedDeployArgs);
+  const deployArgs = [
+    "contract",
+    "deploy",
+    "--wasm",
+    wasmPath,
+    "--source-account",
+    source,
+    "--build-only",
+    ...buildStellarNetworkArgs(network),
+    ...constructorArgs
+  ];
+  let buildOutput;
+  try {
+    const buildResult = await runCommand("stellar", deployArgs, {
+      cwd,
+      failureCode: CaatingaErrorCode.ESTIMATE_FAILED
+    });
+    buildOutput = (buildResult.stdout || buildResult.all).trim();
+  } catch (error) {
+    if (error instanceof CaatingaError) {
+      throw new CaatingaError(
+        `Deploy cost estimate failed for "${contract.name}".`,
+        CaatingaErrorCode.ESTIMATE_FAILED,
+        error.hint ?? "Ensure WASM is built and deploy args resolve correctly.",
+        error.cause
+      );
+    }
+    throw error;
+  }
+  const simulateArgs = ["tx", "simulate", "--source-account", source, buildOutput];
+  let simulateOutput = "";
+  try {
+    const simulateResult = await runCommand("stellar", simulateArgs, {
+      cwd,
+      failureCode: CaatingaErrorCode.ESTIMATE_FAILED
+    });
+    simulateOutput = simulateResult.all || `${simulateResult.stdout}
+${simulateResult.stderr}`;
+  } catch {
+    simulateOutput = "";
+  }
+  const parsed = parseFeeStroops(simulateOutput);
+  const inclusionFeeStroops = parsed.inclusion ?? 100;
+  const resourceFeeStroops = parsed.resource;
+  const totalFeeStroops = inclusionFeeStroops + (resourceFeeStroops ?? 0);
+  return {
+    contractName: contract.name,
+    network: network.name,
+    wasmPath: path13.relative(cwd, wasmPath) || wasmPath,
+    inclusionFeeStroops,
+    resourceFeeStroops,
+    totalFeeStroops,
+    advisory: "Advisory estimate only \u2014 actual fees may differ under network congestion or contract complexity.",
+    rawOutput: simulateOutput || buildOutput
+  };
+}
+
+// src/contracts/inspect-contract.ts
+async function inspectContract(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const contract = resolveContract(options.config, options.contractName, cwd);
+  const network = resolveNetwork(options.config, options.networkName);
+  const artifacts = await readArtifacts(cwd);
+  const artifact = artifacts.networks[network.name]?.contracts[contract.name];
+  if (!artifact) {
+    throw new CaatingaError(
+      `No deployed artifact found for "${contract.name}" on "${network.name}".`,
+      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+      "Run caatinga deploy before inspect."
+    );
+  }
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga inspect.");
+  let reachable = false;
+  let detail;
+  try {
+    await verifyDependencyContract({
+      dependencyName: contract.name,
+      contractId: artifact.contractId,
+      network,
+      cwd
+    });
+    reachable = true;
+    detail = "Contract interface reachable on network.";
+  } catch (error) {
+    reachable = false;
+    detail = error instanceof CaatingaError ? error.message : "Contract not reachable on network.";
+  }
+  let localHash;
+  try {
+    const wasmPath = await resolveWasmArtifactPath(contract.wasmPath, {
+      sourcePath: contract.sourcePath
+    });
+    localHash = await hashWasm(wasmPath);
+  } catch {
+    localHash = void 0;
+  }
+  return {
+    contractName: contract.name,
+    network: network.name,
+    artifact: {
+      contractId: artifact.contractId,
+      wasmHash: artifact.wasmHash,
+      deployedAt: artifact.deployedAt,
+      historyCount: artifact.history?.length ?? 0
+    },
+    onChain: { reachable, detail },
+    localWasm: {
+      path: contract.config.wasm,
+      hash: localHash,
+      matchesArtifact: Boolean(localHash && localHash === artifact.wasmHash)
+    },
+    dependencies: artifact.dependencies ?? contract.config.dependsOn ?? []
+  };
+}
+
 // src/templates/create-project-from-template.ts
-import { cp, mkdir as mkdir3, readFile as readFile5, readdir as readdir3, stat as stat2, writeFile as writeFile4 } from "fs/promises";
-import path12 from "path";
+import { cp, lstat, mkdir as mkdir3, readFile as readFile6, readdir as readdir3, stat as stat2, writeFile as writeFile4 } from "fs/promises";
+import path14 from "path";
 import { z as z7 } from "zod";
 
 // src/templates/template-manifest.schema.ts
 import { z as z6 } from "zod";
-import semver3 from "semver";
+import semver5 from "semver";
 var CURRENT_TEMPLATE_VERSION = 1;
 var TemplateManifestSchema = z6.object({
   name: z6.string().min(1),
@@ -1914,14 +2433,14 @@ var TemplateManifestSchema = z6.object({
   })
 });
 function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
-  const version = semver3.valid(semver3.coerce(coreVersion));
+  const version = semver5.valid(semver5.coerce(coreVersion));
   if (!version) {
     throw new Error(`Invalid core version: ${coreVersion}`);
   }
   return `^${version}`;
 }
 function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
-  return semver3.satisfies(coreVersion, range);
+  return semver5.satisfies(coreVersion, range);
 }
 function getTemplateCompatibilityIssue(manifest, coreVersion = CAATINGA_CORE_VERSION) {
   if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
@@ -1956,8 +2475,8 @@ function formatTemplateCompatibilityHint(issue) {
 // src/templates/create-project-from-template.ts
 var TEMPLATE_COPY_EXCLUDED_DIRS = /* @__PURE__ */ new Set(["target", "test_snapshots", "node_modules", ".git"]);
 async function createProjectFromTemplate(options) {
-  const targetDir = path12.resolve(options.targetDir);
-  const templateDir = path12.resolve(options.templateDir);
+  const targetDir = path14.resolve(options.targetDir);
+  const templateDir = path14.resolve(options.templateDir);
   try {
     await stat2(templateDir);
   } catch {
@@ -1998,9 +2517,9 @@ async function ensureArtifacts(targetDir, projectName) {
   }
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = path12.join(templateDir, "caatinga.template.json");
+  const manifestPath = path14.join(templateDir, "caatinga.template.json");
   try {
-    const rawManifest = await readFile5(manifestPath, "utf8");
+    const rawManifest = await readFile6(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
     const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
     if (compatibilityIssue) {
@@ -2036,47 +2555,53 @@ async function replaceTemplateVariables(dir, projectName) {
   const entries = await readdir3(dir);
   await Promise.all(
     entries.map(async (entry) => {
-      const entryPath = path12.join(dir, entry);
-      const entryStat = await stat2(entryPath);
+      if (TEMPLATE_COPY_EXCLUDED_DIRS.has(entry)) {
+        return;
+      }
+      const entryPath = path14.join(dir, entry);
+      const entryStat = await lstat(entryPath);
+      if (entryStat.isSymbolicLink()) {
+        return;
+      }
       if (entryStat.isDirectory()) {
         await replaceTemplateVariables(entryPath, projectName);
         return;
       }
-      if (!isTextTemplateFile(entryPath)) {
+      if (!entryStat.isFile() || !isTextTemplateFile(entryPath)) {
         return;
       }
-      const content = await readFile5(entryPath, "utf8");
+      const content = await readFile6(entryPath, "utf8");
       await writeFile4(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
     })
   );
 }
 function shouldCopyTemplateEntry(templateDir, source, userFilter) {
-  const relativePath = path12.relative(templateDir, source);
+  const relativePath = path14.relative(templateDir, source);
   if (!relativePath || relativePath === ".") {
     return true;
   }
-  const normalizedPath = relativePath.split(path12.sep).join("/");
+  const normalizedPath = relativePath.split(path14.sep).join("/");
   if (userFilter && !userFilter(normalizedPath)) {
     return false;
   }
-  return !relativePath.split(path12.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
+  return !relativePath.split(path14.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
 }
 function isTextTemplateFile(filePath) {
   return [".json", ".md", ".rs", ".toml", ".ts", ".tsx", ".css", ".html"].includes(
-    path12.extname(filePath)
+    path14.extname(filePath)
   );
 }
 
 // src/scaffold/create-zk-project.ts
 import { cp as cp2, mkdir as mkdir4, writeFile as writeFile5 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
-import path13 from "path";
+import path15 from "path";
 import { fileURLToPath } from "url";
-var moduleDir = typeof __dirname === "string" ? __dirname : path13.dirname(fileURLToPath(import.meta.url));
+var moduleDir = typeof __dirname === "string" ? __dirname : path15.dirname(fileURLToPath(import.meta.url));
 function scaffoldRoot() {
   const candidates = [
-    path13.resolve(moduleDir, "../../scaffolds"),
-    path13.resolve(moduleDir, "../scaffolds")
+    path15.resolve(moduleDir, "../../scaffolds"),
+    path15.resolve(moduleDir, "../scaffolds")
   ];
   const found = candidates.find((candidate) => existsSync2(candidate));
   return found ?? candidates[0];
@@ -2167,39 +2692,39 @@ Replace \`circuits/main.circom\` with your circuit. Keep the entry point named \
 `;
 }
 async function createZkProject(options) {
-  const targetDir = path13.resolve(options.targetDir);
+  const targetDir = path15.resolve(options.targetDir);
   const force = options.force ?? false;
   const projectFiles = options.projectFiles ?? true;
   await mkdir4(targetDir, { recursive: true });
   if (projectFiles) {
     await Promise.all([
-      writeFile5(path13.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), {
+      writeFile5(path15.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), {
         encoding: "utf8",
         flag: force ? "w" : "wx"
       }),
-      writeFile5(path13.join(targetDir, "package.json"), packageJsonSource(options.projectName), {
+      writeFile5(path15.join(targetDir, "package.json"), packageJsonSource(options.projectName), {
         encoding: "utf8",
         flag: force ? "w" : "wx"
       }),
-      writeFile5(path13.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", {
+      writeFile5(path15.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", {
         encoding: "utf8",
         flag: force ? "w" : "wx"
       }),
-      writeFile5(path13.join(targetDir, "README.md"), readmeSource(options.projectName), {
+      writeFile5(path15.join(targetDir, "README.md"), readmeSource(options.projectName), {
         encoding: "utf8",
         flag: force ? "w" : "wx"
       })
     ]);
   }
-  await mkdir4(path13.join(targetDir, "contracts"), { recursive: true });
-  await cp2(path13.join(scaffoldRoot(), "zk-circuit-stub"), path13.join(targetDir, "circuits"), {
+  await mkdir4(path15.join(targetDir, "contracts"), { recursive: true });
+  await cp2(path15.join(scaffoldRoot(), "zk-circuit-stub"), path15.join(targetDir, "circuits"), {
     recursive: true,
     force,
     errorOnExist: !force
   });
   await cp2(
-    path13.join(scaffoldRoot(), "zk-verifier"),
-    path13.join(targetDir, "contracts", "verifier"),
+    path15.join(scaffoldRoot(), "zk-verifier"),
+    path15.join(targetDir, "contracts", "verifier"),
     {
       recursive: true,
       force,
@@ -2218,13 +2743,13 @@ async function createZkProject(options) {
 // src/scaffold/create-minimal-project.ts
 import { cp as cp3, mkdir as mkdir5, writeFile as writeFile6 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
-import path14 from "path";
+import path16 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-var moduleDir2 = typeof __dirname === "string" ? __dirname : path14.dirname(fileURLToPath2(import.meta.url));
+var moduleDir2 = typeof __dirname === "string" ? __dirname : path16.dirname(fileURLToPath2(import.meta.url));
 function scaffoldRoot2() {
   const candidates = [
-    path14.resolve(moduleDir2, "../../scaffolds"),
-    path14.resolve(moduleDir2, "../scaffolds")
+    path16.resolve(moduleDir2, "../../scaffolds"),
+    path16.resolve(moduleDir2, "../scaffolds")
   ];
   const found = candidates.find((candidate) => existsSync3(candidate));
   return found ?? candidates[0];
@@ -2315,31 +2840,31 @@ Edit \`contracts/app/src/lib.rs\` to customize the contract. Add a frontend late
 `;
 }
 async function createMinimalProject(options) {
-  const targetDir = path14.resolve(options.targetDir);
+  const targetDir = path16.resolve(options.targetDir);
   const force = options.force ?? false;
   await mkdir5(targetDir, { recursive: true });
   await Promise.all([
-    writeFile6(path14.join(targetDir, "caatinga.config.ts"), configSource2(options.projectName), {
+    writeFile6(path16.join(targetDir, "caatinga.config.ts"), configSource2(options.projectName), {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     }),
-    writeFile6(path14.join(targetDir, "package.json"), packageJsonSource2(options.projectName), {
+    writeFile6(path16.join(targetDir, "package.json"), packageJsonSource2(options.projectName), {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     }),
-    writeFile6(path14.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", {
+    writeFile6(path16.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     }),
-    writeFile6(path14.join(targetDir, "README.md"), readmeSource2(options.projectName), {
+    writeFile6(path16.join(targetDir, "README.md"), readmeSource2(options.projectName), {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     })
   ]);
-  await mkdir5(path14.join(targetDir, "contracts"), { recursive: true });
+  await mkdir5(path16.join(targetDir, "contracts"), { recursive: true });
   await cp3(
-    path14.join(scaffoldRoot2(), "soroban-contract-stub"),
-    path14.join(targetDir, "contracts", "app"),
+    path16.join(scaffoldRoot2(), "soroban-contract-stub"),
+    path16.join(targetDir, "contracts", "app"),
     {
       recursive: true,
       force,
@@ -2354,36 +2879,24 @@ async function createMinimalProject(options) {
 }
 
 // src/ci/is-transient-testnet-smoke-failure.ts
-var NO_RETRY_CAATINGA_SUBSTRINGS = [
-  "CAATINGA_UNSUPPORTED_CLI_VERSION",
-  "CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED",
-  "CAATINGA_STELLAR_CLI_NOT_FOUND",
-  "CAATINGA_INVALID_CONFIG",
-  "CAATINGA_CONFIG_NOT_FOUND"
-];
-var TRANSIENT_PATTERN = /timeout|i\/o timeout|econnreset|connection reset|503|502|429|rate limit|temporar|bad gateway|fetch failed|network error|unavailable/i;
 function isTransientTestnetSmokeFailure(logText) {
-  if (!logText.trim()) {
-    return false;
-  }
-  for (const marker of NO_RETRY_CAATINGA_SUBSTRINGS) {
-    if (logText.includes(marker)) {
-      return false;
-    }
-  }
-  return TRANSIENT_PATTERN.test(logText);
+  return isTransientCommandFailure(logText);
 }
 export {
   BINDING_MARKER_FILENAME,
   BindingMarkerSchema,
   CAATINGA_CORE_VERSION,
+  CURRENT_ARTIFACTS_SCHEMA_VERSION,
   CaatingaArtifactsSchema,
   CaatingaConfigSchema,
   CaatingaError,
   CaatingaErrorCode,
+  DEFAULT_CLI_SOURCE,
   READ_CALL_FAILURE_REGEX,
   STELLAR_CLI_LAST_TESTED_VERSION,
   STELLAR_CLI_MIN_VERSION,
+  STELLAR_SDK_LAST_TESTED_VERSION,
+  STELLAR_SDK_MIN_VERSION,
   TemplateManifestSchema,
   WELL_KNOWN_NETWORKS,
   buildContract,
@@ -2391,6 +2904,7 @@ export {
   buildReadCallHint,
   checkBinary,
   checkStellarCliVersion,
+  checkStellarSdkVersion,
   collectProjectStatus,
   createInitialArtifacts,
   createMinimalProject,
@@ -2399,20 +2913,27 @@ export {
   defineConfig,
   deployContract,
   deployContractGraph,
+  describeCliSource,
+  estimateDeployCost,
   evaluateBindingFreshness,
   evaluateBindingsFreshness,
   evaluateStellarCliCompatibility,
+  evaluateStellarSdkCompatibility,
   formatCaatingaError,
   generateBindings,
   generateBindingsGraph,
+  inspectContract,
   invokeContract,
   isCargoBinMissingFromPath,
   isReadCallFailure,
   isTransientTestnetSmokeFailure,
   loadConfig,
+  migrateArtifactsFile,
+  migrateArtifactsToV2,
   parseContractId,
   parseInvokeTarget,
   parseStellarCliVersion,
+  parseStellarSdkVersion,
   readArtifacts,
   readBindingMarker,
   readContract,
@@ -2422,6 +2943,8 @@ export {
   resolveDeployOrder,
   resolveNetwork,
   resolveSubprocessEnv,
+  restoreArtifactFromHistory,
+  rollbackContractArtifact,
   runCommand,
   toCaatingaError,
   updateArtifact,