@caatinga/core 3.2.0 → 3.3.1

package/dist/index.cjs

@@ -33,13 +33,17 @@ __export(index_exports, {
   BINDING_MARKER_FILENAME: () => BINDING_MARKER_FILENAME,
   BindingMarkerSchema: () => BindingMarkerSchema,
   CAATINGA_CORE_VERSION: () => CAATINGA_CORE_VERSION,
+  CURRENT_ARTIFACTS_SCHEMA_VERSION: () => CURRENT_ARTIFACTS_SCHEMA_VERSION,
   CaatingaArtifactsSchema: () => CaatingaArtifactsSchema,
   CaatingaConfigSchema: () => CaatingaConfigSchema,
   CaatingaError: () => CaatingaError,
   CaatingaErrorCode: () => CaatingaErrorCode,
+  DEFAULT_CLI_SOURCE: () => DEFAULT_CLI_SOURCE,
   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,
+  STELLAR_SDK_LAST_TESTED_VERSION: () => STELLAR_SDK_LAST_TESTED_VERSION,
+  STELLAR_SDK_MIN_VERSION: () => STELLAR_SDK_MIN_VERSION,
   TemplateManifestSchema: () => TemplateManifestSchema,
   WELL_KNOWN_NETWORKS: () => WELL_KNOWN_NETWORKS,
   buildContract: () => buildContract,
@@ -47,6 +51,7 @@ __export(index_exports, {
   buildReadCallHint: () => buildReadCallHint,
   checkBinary: () => checkBinary,
   checkStellarCliVersion: () => checkStellarCliVersion,
+  checkStellarSdkVersion: () => checkStellarSdkVersion,
   collectProjectStatus: () => collectProjectStatus,
   createInitialArtifacts: () => createInitialArtifacts,
   createMinimalProject: () => createMinimalProject,
@@ -55,20 +60,27 @@ __export(index_exports, {
   defineConfig: () => defineConfig,
   deployContract: () => deployContract,
   deployContractGraph: () => deployContractGraph,
+  describeCliSource: () => describeCliSource,
+  estimateDeployCost: () => estimateDeployCost,
   evaluateBindingFreshness: () => evaluateBindingFreshness,
   evaluateBindingsFreshness: () => evaluateBindingsFreshness,
   evaluateStellarCliCompatibility: () => evaluateStellarCliCompatibility,
+  evaluateStellarSdkCompatibility: () => evaluateStellarSdkCompatibility,
   formatCaatingaError: () => formatCaatingaError,
   generateBindings: () => generateBindings,
   generateBindingsGraph: () => generateBindingsGraph,
+  inspectContract: () => inspectContract,
   invokeContract: () => invokeContract,
   isCargoBinMissingFromPath: () => isCargoBinMissingFromPath,
   isReadCallFailure: () => isReadCallFailure,
   isTransientTestnetSmokeFailure: () => isTransientTestnetSmokeFailure,
   loadConfig: () => loadConfig,
+  migrateArtifactsFile: () => migrateArtifactsFile,
+  migrateArtifactsToV2: () => migrateArtifactsToV2,
   parseContractId: () => parseContractId,
   parseInvokeTarget: () => parseInvokeTarget,
   parseStellarCliVersion: () => parseStellarCliVersion,
+  parseStellarSdkVersion: () => parseStellarSdkVersion,
   readArtifacts: () => readArtifacts,
   readBindingMarker: () => readBindingMarker,
   readContract: () => readContract,
@@ -78,6 +90,8 @@ __export(index_exports, {
   resolveDeployOrder: () => resolveDeployOrder,
   resolveNetwork: () => resolveNetwork,
   resolveSubprocessEnv: () => resolveSubprocessEnv,
+  restoreArtifactFromHistory: () => restoreArtifactFromHistory,
+  rollbackContractArtifact: () => rollbackContractArtifact,
   runCommand: () => runCommand,
   toCaatingaError: () => toCaatingaError,
   updateArtifact: () => updateArtifact,
@@ -97,6 +111,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",
@@ -139,6 +155,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"
 };
 
@@ -327,6 +345,14 @@ async function loadConfig(options = {}) {
 
 // src/artifacts/artifact.schema.ts
 var import_zod3 = require("zod");
+var ArtifactSupersedeReasonSchema = import_zod3.z.enum(["upgrade", "rollback", "force-redeploy"]);
+var ContractArtifactHistoryEntrySchema = import_zod3.z.object({
+  contractId: import_zod3.z.string().min(1),
+  wasmHash: import_zod3.z.string().min(1),
+  deployedAt: import_zod3.z.string().datetime(),
+  supersededAt: import_zod3.z.string().datetime(),
+  reason: ArtifactSupersedeReasonSchema.optional()
+});
 var ContractArtifactSchema = import_zod3.z.object({
   contractId: import_zod3.z.string().min(1),
   wasmHash: import_zod3.z.string().min(1),
@@ -334,17 +360,28 @@ var ContractArtifactSchema = import_zod3.z.object({
   sourcePath: import_zod3.z.string().min(1),
   wasmPath: import_zod3.z.string().min(1),
   dependencies: import_zod3.z.array(import_zod3.z.string().min(1)).default([]),
-  resolvedDeployArgs: import_zod3.z.record(import_zod3.z.string().min(1), import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean()])).default({})
+  resolvedDeployArgs: import_zod3.z.record(import_zod3.z.string().min(1), import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean()])).default({}),
+  history: import_zod3.z.array(ContractArtifactHistoryEntrySchema).optional()
 });
 var NetworkArtifactsSchema = import_zod3.z.object({
   contracts: import_zod3.z.record(import_zod3.z.string().min(1), ContractArtifactSchema).default({}),
   dependencyGraph: import_zod3.z.record(import_zod3.z.string().min(1), import_zod3.z.array(import_zod3.z.string().min(1))).default({})
 });
-var CaatingaArtifactsSchema = import_zod3.z.object({
+var CaatingaArtifactsBaseSchema = import_zod3.z.object({
   project: import_zod3.z.string().min(1),
-  version: import_zod3.z.literal(1),
   networks: import_zod3.z.record(import_zod3.z.string().min(1), NetworkArtifactsSchema).default({})
 });
+var CaatingaArtifactsV1Schema = CaatingaArtifactsBaseSchema.extend({
+  version: import_zod3.z.literal(1)
+});
+var CaatingaArtifactsV2Schema = CaatingaArtifactsBaseSchema.extend({
+  version: import_zod3.z.literal(2)
+});
+var CaatingaArtifactsSchema = import_zod3.z.union([
+  CaatingaArtifactsV1Schema,
+  CaatingaArtifactsV2Schema
+]);
+var CURRENT_ARTIFACTS_SCHEMA_VERSION = 2;
 
 // src/artifacts/read-artifacts.ts
 var import_promises2 = require("fs/promises");
@@ -396,29 +433,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) {
@@ -685,6 +832,35 @@ function evaluateStellarCliCompatibility(input) {
   };
 }
 
+// src/stellar-cli/probe-stellar-cli-features.ts
+var import_semver3 = __toESM(require("semver"), 1);
+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 (import_semver3.default.valid(version) && import_semver3.default.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;
@@ -704,9 +880,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) {
@@ -852,6 +1031,122 @@ function parseContractId(output) {
   return match[0];
 }
 
+// src/stellar-sdk/check-stellar-sdk-version.ts
+var import_promises6 = require("fs/promises");
+var import_node_path7 = __toESM(require("path"), 1);
+
+// src/stellar-sdk/compat.ts
+var import_semver4 = __toESM(require("semver"), 1);
+
+// 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 = import_semver4.default.parse(input.version);
+  if (!parsed || !import_semver4.default.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 = import_semver4.default.valid(input.lastTestedVersion ?? STELLAR_SDK_LAST_TESTED_VERSION) ?? STELLAR_SDK_LAST_TESTED_VERSION;
+  const warnings = [];
+  let status = "supported";
+  if (import_semver4.default.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 (import_semver4.default.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 = import_node_path7.default.join(cwd, "node_modules", "@stellar", "stellar-sdk", "package.json");
+    const raw = await (0, import_promises6.readFile)(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];
@@ -989,8 +1284,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
-var import_node_path7 = __toESM(require("path"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 function resolveContract(config, contractName, cwd = process.cwd()) {
   const contract = config.contracts[contractName];
   if (!contract) {
@@ -1003,8 +1328,8 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
   return {
     name: contractName,
     config: contract,
-    sourcePath: import_node_path7.default.resolve(cwd, contract.path),
-    wasmPath: import_node_path7.default.resolve(cwd, contract.wasm)
+    sourcePath: import_node_path8.default.resolve(cwd, contract.path),
+    wasmPath: import_node_path8.default.resolve(cwd, contract.wasm)
   };
 }
 
@@ -1023,8 +1348,8 @@ function resolveDefaultContractName(config) {
 
 // src/contracts/wasm.ts
 var import_node_crypto = require("crypto");
-var import_promises6 = require("fs/promises");
-var import_node_path8 = __toESM(require("path"), 1);
+var import_promises7 = require("fs/promises");
+var import_node_path9 = __toESM(require("path"), 1);
 var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
 var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
 function toCurrentWasmTargetPath(wasmPath) {
@@ -1055,18 +1380,18 @@ function wasmNotFoundError(configuredWasmPath, options) {
   );
 }
 function toConfigRelativeWasmPath(absoluteWasmPath) {
-  const relative = import_node_path8.default.relative(process.cwd(), absoluteWasmPath);
-  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(import_node_path8.default.sep).join("/")}`;
+  const relative = import_node_path9.default.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(import_node_path9.default.sep).join("/")}`;
 }
 function wasmFileName(configuredWasmPath) {
-  return import_node_path8.default.basename(configuredWasmPath);
+  return import_node_path9.default.basename(configuredWasmPath);
 }
 function buildAlternateWasmCandidates(configuredWasmPath, options) {
   const fileName = wasmFileName(configuredWasmPath);
   const candidates = [];
   const seen = /* @__PURE__ */ new Set();
   function addCandidate(candidate) {
-    const resolved = import_node_path8.default.resolve(candidate);
+    const resolved = import_node_path9.default.resolve(candidate);
     if (seen.has(resolved)) {
       return;
     }
@@ -1075,15 +1400,15 @@ function buildAlternateWasmCandidates(configuredWasmPath, options) {
   }
   const cargoTargetDir = process.env.CARGO_TARGET_DIR;
   if (cargoTargetDir) {
-    addCandidate(import_node_path8.default.join(cargoTargetDir, CURRENT_RUST_WASM_TARGET, "release", fileName));
-    addCandidate(import_node_path8.default.join(cargoTargetDir, LEGACY_RUST_WASM_TARGET, "release", fileName));
+    addCandidate(import_node_path9.default.join(cargoTargetDir, CURRENT_RUST_WASM_TARGET, "release", fileName));
+    addCandidate(import_node_path9.default.join(cargoTargetDir, LEGACY_RUST_WASM_TARGET, "release", fileName));
   }
   if (options?.sourcePath) {
     addCandidate(
-      import_node_path8.default.join(options.sourcePath, "target", CURRENT_RUST_WASM_TARGET, "release", fileName)
+      import_node_path9.default.join(options.sourcePath, "target", CURRENT_RUST_WASM_TARGET, "release", fileName)
     );
     addCandidate(
-      import_node_path8.default.join(options.sourcePath, "target", LEGACY_RUST_WASM_TARGET, "release", fileName)
+      import_node_path9.default.join(options.sourcePath, "target", LEGACY_RUST_WASM_TARGET, "release", fileName)
     );
   }
   return candidates;
@@ -1091,7 +1416,7 @@ function buildAlternateWasmCandidates(configuredWasmPath, options) {
 async function firstExistingPath(paths) {
   for (const candidate of paths) {
     try {
-      await (0, import_promises6.access)(candidate);
+      await (0, import_promises7.access)(candidate);
       return candidate;
     } catch {
       continue;
@@ -1100,9 +1425,9 @@ async function firstExistingPath(paths) {
   return void 0;
 }
 async function resolveWasmArtifactPath(configuredWasmPath, options) {
-  const resolvedConfiguredPath = import_node_path8.default.resolve(configuredWasmPath);
+  const resolvedConfiguredPath = import_node_path9.default.resolve(configuredWasmPath);
   try {
-    await (0, import_promises6.access)(resolvedConfiguredPath);
+    await (0, import_promises7.access)(resolvedConfiguredPath);
     return resolvedConfiguredPath;
   } catch {
     const currentTargetPath = toCurrentWasmTargetPath(resolvedConfiguredPath);
@@ -1124,20 +1449,20 @@ async function resolveWasmArtifactPath(configuredWasmPath, options) {
   }
 }
 async function hashWasm(wasmPath) {
-  const bytes = await (0, import_promises6.readFile)(wasmPath);
+  const bytes = await (0, import_promises7.readFile)(wasmPath);
   return (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
 }
 async function getNewestMtimeInDirectory(directory) {
   try {
-    await (0, import_promises6.access)(directory);
+    await (0, import_promises7.access)(directory);
   } catch {
     return void 0;
   }
   let newest = 0;
   async function walk(dir) {
-    const entries = await (0, import_promises6.readdir)(dir, { withFileTypes: true });
+    const entries = await (0, import_promises7.readdir)(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const entryPath = import_node_path8.default.join(dir, entry.name);
+      const entryPath = import_node_path9.default.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(entryPath);
         continue;
@@ -1145,7 +1470,7 @@ async function getNewestMtimeInDirectory(directory) {
       if (!entry.isFile()) {
         continue;
       }
-      const fileStat = await (0, import_promises6.stat)(entryPath);
+      const fileStat = await (0, import_promises7.stat)(entryPath);
       newest = Math.max(newest, fileStat.mtimeMs);
     }
   }
@@ -1153,14 +1478,14 @@ async function getNewestMtimeInDirectory(directory) {
   return newest > 0 ? newest : void 0;
 }
 async function isWasmOlderThanSources(input) {
-  const srcDir = import_node_path8.default.join(input.contractPath, "src");
+  const srcDir = import_node_path9.default.join(input.contractPath, "src");
   const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
   if (newestSourceMtime === void 0) {
     return false;
   }
   let wasmStat;
   try {
-    wasmStat = await (0, import_promises6.stat)(input.wasmPath);
+    wasmStat = await (0, import_promises7.stat)(input.wasmPath);
   } catch {
     return false;
   }
@@ -1228,7 +1553,38 @@ async function buildContract(options) {
 }
 
 // src/contracts/deploy-contract.ts
-var import_node_path9 = __toESM(require("path"), 1);
+var import_node_path10 = __toESM(require("path"), 1);
+
+// 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) {
@@ -1270,26 +1626,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();
 }
@@ -1334,7 +1677,7 @@ async function deployContract(options) {
       contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: import_node_path9.default.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: import_node_path10.default.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
       skipped: true,
       staleWasmWarning
@@ -1374,40 +1717,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,
@@ -1421,7 +1793,7 @@ ${error.hint ?? ""}`,
       dependencies,
       resolvedDeployArgs
     },
-    { dependencyGraph }
+    { dependencyGraph, supersedeReason }
   );
   const artifactsPath = await writeArtifacts(nextArtifacts, cwd);
   return {
@@ -1585,9 +1957,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({
@@ -1610,12 +1984,12 @@ async function deployContractGraph(options) {
 }
 
 // src/contracts/generate-bindings.ts
-var import_promises8 = require("fs/promises");
-var import_node_path11 = __toESM(require("path"), 1);
+var import_promises9 = require("fs/promises");
+var import_node_path12 = __toESM(require("path"), 1);
 
 // src/bindings/patch-generated-binding-package.ts
-var import_promises7 = require("fs/promises");
-var import_node_path10 = __toESM(require("path"), 1);
+var import_promises8 = require("fs/promises");
+var import_node_path11 = __toESM(require("path"), 1);
 var BUNDLER_ENTRY = "./src/index.ts";
 var ROOT_BINDING_INDEX_CONTENT = 'export * from "./src/index.js";\n';
 function resolveExportEntry(exportsField) {
@@ -1650,22 +2024,22 @@ function shouldPatchPackageJson(packageJson) {
   return pointsToDist(packageJson.main) || pointsToDist(packageJson.types) || !pointsToBundlerSource(exportEntry);
 }
 async function ensureRootBindingIndex(outputDir) {
-  const rootIndexPath = import_node_path10.default.join(outputDir, "index.ts");
+  const rootIndexPath = import_node_path11.default.join(outputDir, "index.ts");
   try {
-    const existing = await (0, import_promises7.readFile)(rootIndexPath, "utf8");
+    const existing = await (0, import_promises8.readFile)(rootIndexPath, "utf8");
     if (existing === ROOT_BINDING_INDEX_CONTENT) {
       return;
     }
     return;
   } catch {
-    await (0, import_promises7.writeFile)(rootIndexPath, ROOT_BINDING_INDEX_CONTENT, "utf8");
+    await (0, import_promises8.writeFile)(rootIndexPath, ROOT_BINDING_INDEX_CONTENT, "utf8");
   }
 }
 async function patchGeneratedBindingPackage(outputDir) {
-  const packageJsonPath = import_node_path10.default.join(outputDir, "package.json");
-  const entryPath = import_node_path10.default.join(outputDir, "src", "index.ts");
+  const packageJsonPath = import_node_path11.default.join(outputDir, "package.json");
+  const entryPath = import_node_path11.default.join(outputDir, "src", "index.ts");
   try {
-    await (0, import_promises7.access)(entryPath);
+    await (0, import_promises8.access)(entryPath);
   } catch {
     throw new CaatingaError(
       "Generated binding package is missing src/index.ts.",
@@ -1675,7 +2049,7 @@ async function patchGeneratedBindingPackage(outputDir) {
   }
   let raw;
   try {
-    raw = await (0, import_promises7.readFile)(packageJsonPath, "utf8");
+    raw = await (0, import_promises8.readFile)(packageJsonPath, "utf8");
   } catch {
     throw new CaatingaError(
       "Generated binding package is missing package.json.",
@@ -1700,7 +2074,7 @@ async function patchGeneratedBindingPackage(outputDir) {
       ...typeof packageJson.exports === "object" && packageJson.exports !== null && !Array.isArray(packageJson.exports) ? packageJson.exports : {},
       ".": BUNDLER_ENTRY
     };
-    await (0, import_promises7.writeFile)(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}
+    await (0, import_promises8.writeFile)(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}
 `, "utf8");
   }
   await ensureRootBindingIndex(outputDir);
@@ -1716,14 +2090,14 @@ function buildGenerateNetworkArgs(network) {
 
 // src/contracts/generate-bindings.ts
 function toBindingImportPath(bindingsOutput, contractName) {
-  const normalized = bindingsOutput.replace(/^\.\//, "").split(import_node_path11.default.sep).join("/");
-  return `./${import_node_path11.default.posix.join(normalized, contractName)}`;
+  const normalized = bindingsOutput.replace(/^\.\//, "").split(import_node_path12.default.sep).join("/");
+  return `./${import_node_path12.default.posix.join(normalized, contractName)}`;
 }
 async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
-  const legacyPath = import_node_path11.default.resolve(cwd, bindingsOutput, `${contractName}.ts`);
+  const legacyPath = import_node_path12.default.resolve(cwd, bindingsOutput, `${contractName}.ts`);
   try {
-    await (0, import_promises8.access)(legacyPath);
-    await (0, import_promises8.unlink)(legacyPath);
+    await (0, import_promises9.access)(legacyPath);
+    await (0, import_promises9.unlink)(legacyPath);
     return true;
   } catch {
     return false;
@@ -1748,8 +2122,9 @@ async function generateBindings(options) {
       "Run caatinga deploy for this contract and network before generating bindings."
     );
   }
-  const outputDir = import_node_path11.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
-  await (0, import_promises8.mkdir)(outputDir, { recursive: true });
+  const outputDir = import_node_path12.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  await (0, import_promises9.mkdir)(outputDir, { recursive: true });
+  await checkStellarSdkVersion({ cwd });
   const result = await runCommand(
     "npx",
     [
@@ -1974,14 +2349,172 @@ async function readContract(options) {
   };
 }
 
+// src/contracts/estimate-deploy-cost.ts
+var import_node_path13 = __toESM(require("path"), 1);
+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: import_node_path13.default.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
-var import_promises9 = require("fs/promises");
-var import_node_path12 = __toESM(require("path"), 1);
+var import_promises10 = require("fs/promises");
+var import_node_path14 = __toESM(require("path"), 1);
 var import_zod7 = require("zod");
 
 // src/templates/template-manifest.schema.ts
 var import_zod6 = require("zod");
-var import_semver3 = __toESM(require("semver"), 1);
+var import_semver5 = __toESM(require("semver"), 1);
 var CURRENT_TEMPLATE_VERSION = 1;
 var TemplateManifestSchema = import_zod6.z.object({
   name: import_zod6.z.string().min(1),
@@ -2005,14 +2538,14 @@ var TemplateManifestSchema = import_zod6.z.object({
   })
 });
 function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
-  const version = import_semver3.default.valid(import_semver3.default.coerce(coreVersion));
+  const version = import_semver5.default.valid(import_semver5.default.coerce(coreVersion));
   if (!version) {
     throw new Error(`Invalid core version: ${coreVersion}`);
   }
   return `^${version}`;
 }
 function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
-  return import_semver3.default.satisfies(coreVersion, range);
+  return import_semver5.default.satisfies(coreVersion, range);
 }
 function getTemplateCompatibilityIssue(manifest, coreVersion = CAATINGA_CORE_VERSION) {
   if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
@@ -2047,10 +2580,10 @@ 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 = import_node_path12.default.resolve(options.targetDir);
-  const templateDir = import_node_path12.default.resolve(options.templateDir);
+  const targetDir = import_node_path14.default.resolve(options.targetDir);
+  const templateDir = import_node_path14.default.resolve(options.templateDir);
   try {
-    await (0, import_promises9.stat)(templateDir);
+    await (0, import_promises10.stat)(templateDir);
   } catch {
     throw new CaatingaError(
       `Template directory was not found: ${templateDir}`,
@@ -2060,8 +2593,8 @@ async function createProjectFromTemplate(options) {
   }
   const manifest = await readTemplateManifest(templateDir);
   const mergeIntoExisting = Boolean(options.filter);
-  await (0, import_promises9.mkdir)(targetDir, { recursive: true });
-  await (0, import_promises9.cp)(templateDir, targetDir, {
+  await (0, import_promises10.mkdir)(targetDir, { recursive: true });
+  await (0, import_promises10.cp)(templateDir, targetDir, {
     recursive: true,
     force: true,
     errorOnExist: false,
@@ -2089,9 +2622,9 @@ async function ensureArtifacts(targetDir, projectName) {
   }
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = import_node_path12.default.join(templateDir, "caatinga.template.json");
+  const manifestPath = import_node_path14.default.join(templateDir, "caatinga.template.json");
   try {
-    const rawManifest = await (0, import_promises9.readFile)(manifestPath, "utf8");
+    const rawManifest = await (0, import_promises10.readFile)(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
     const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
     if (compatibilityIssue) {
@@ -2124,51 +2657,57 @@ async function readTemplateManifest(templateDir) {
   }
 }
 async function replaceTemplateVariables(dir, projectName) {
-  const entries = await (0, import_promises9.readdir)(dir);
+  const entries = await (0, import_promises10.readdir)(dir);
   await Promise.all(
     entries.map(async (entry) => {
-      const entryPath = import_node_path12.default.join(dir, entry);
-      const entryStat = await (0, import_promises9.stat)(entryPath);
+      if (TEMPLATE_COPY_EXCLUDED_DIRS.has(entry)) {
+        return;
+      }
+      const entryPath = import_node_path14.default.join(dir, entry);
+      const entryStat = await (0, import_promises10.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 (0, import_promises9.readFile)(entryPath, "utf8");
-      await (0, import_promises9.writeFile)(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
+      const content = await (0, import_promises10.readFile)(entryPath, "utf8");
+      await (0, import_promises10.writeFile)(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
     })
   );
 }
 function shouldCopyTemplateEntry(templateDir, source, userFilter) {
-  const relativePath = import_node_path12.default.relative(templateDir, source);
+  const relativePath = import_node_path14.default.relative(templateDir, source);
   if (!relativePath || relativePath === ".") {
     return true;
   }
-  const normalizedPath = relativePath.split(import_node_path12.default.sep).join("/");
+  const normalizedPath = relativePath.split(import_node_path14.default.sep).join("/");
   if (userFilter && !userFilter(normalizedPath)) {
     return false;
   }
-  return !relativePath.split(import_node_path12.default.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
+  return !relativePath.split(import_node_path14.default.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
 }
 function isTextTemplateFile(filePath) {
   return [".json", ".md", ".rs", ".toml", ".ts", ".tsx", ".css", ".html"].includes(
-    import_node_path12.default.extname(filePath)
+    import_node_path14.default.extname(filePath)
   );
 }
 
 // src/scaffold/create-zk-project.ts
-var import_promises10 = require("fs/promises");
+var import_promises11 = require("fs/promises");
 var import_node_fs2 = require("fs");
-var import_node_path13 = __toESM(require("path"), 1);
+var import_node_path15 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 var import_meta3 = {};
-var moduleDir = typeof __dirname === "string" ? __dirname : import_node_path13.default.dirname((0, import_node_url.fileURLToPath)(import_meta3.url));
+var moduleDir = typeof __dirname === "string" ? __dirname : import_node_path15.default.dirname((0, import_node_url.fileURLToPath)(import_meta3.url));
 function scaffoldRoot() {
   const candidates = [
-    import_node_path13.default.resolve(moduleDir, "../../scaffolds"),
-    import_node_path13.default.resolve(moduleDir, "../scaffolds")
+    import_node_path15.default.resolve(moduleDir, "../../scaffolds"),
+    import_node_path15.default.resolve(moduleDir, "../scaffolds")
   ];
   const found = candidates.find((candidate) => (0, import_node_fs2.existsSync)(candidate));
   return found ?? candidates[0];
@@ -2259,39 +2798,39 @@ Replace \`circuits/main.circom\` with your circuit. Keep the entry point named \
 `;
 }
 async function createZkProject(options) {
-  const targetDir = import_node_path13.default.resolve(options.targetDir);
+  const targetDir = import_node_path15.default.resolve(options.targetDir);
   const force = options.force ?? false;
   const projectFiles = options.projectFiles ?? true;
-  await (0, import_promises10.mkdir)(targetDir, { recursive: true });
+  await (0, import_promises11.mkdir)(targetDir, { recursive: true });
   if (projectFiles) {
     await Promise.all([
-      (0, import_promises10.writeFile)(import_node_path13.default.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), {
+      (0, import_promises11.writeFile)(import_node_path15.default.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), {
         encoding: "utf8",
         flag: force ? "w" : "wx"
       }),
-      (0, import_promises10.writeFile)(import_node_path13.default.join(targetDir, "package.json"), packageJsonSource(options.projectName), {
+      (0, import_promises11.writeFile)(import_node_path15.default.join(targetDir, "package.json"), packageJsonSource(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", {
+      (0, import_promises11.writeFile)(import_node_path15.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"), readmeSource(options.projectName), {
+      (0, import_promises11.writeFile)(import_node_path15.default.join(targetDir, "README.md"), readmeSource(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(scaffoldRoot(), "zk-circuit-stub"), import_node_path13.default.join(targetDir, "circuits"), {
+  await (0, import_promises11.mkdir)(import_node_path15.default.join(targetDir, "contracts"), { recursive: true });
+  await (0, import_promises11.cp)(import_node_path15.default.join(scaffoldRoot(), "zk-circuit-stub"), import_node_path15.default.join(targetDir, "circuits"), {
     recursive: true,
     force,
     errorOnExist: !force
   });
-  await (0, import_promises10.cp)(
-    import_node_path13.default.join(scaffoldRoot(), "zk-verifier"),
-    import_node_path13.default.join(targetDir, "contracts", "verifier"),
+  await (0, import_promises11.cp)(
+    import_node_path15.default.join(scaffoldRoot(), "zk-verifier"),
+    import_node_path15.default.join(targetDir, "contracts", "verifier"),
     {
       recursive: true,
       force,
@@ -2308,16 +2847,16 @@ async function createZkProject(options) {
 }
 
 // src/scaffold/create-minimal-project.ts
-var import_promises11 = require("fs/promises");
+var import_promises12 = require("fs/promises");
 var import_node_fs3 = require("fs");
-var import_node_path14 = __toESM(require("path"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 var import_meta4 = {};
-var moduleDir2 = typeof __dirname === "string" ? __dirname : import_node_path14.default.dirname((0, import_node_url2.fileURLToPath)(import_meta4.url));
+var moduleDir2 = typeof __dirname === "string" ? __dirname : import_node_path16.default.dirname((0, import_node_url2.fileURLToPath)(import_meta4.url));
 function scaffoldRoot2() {
   const candidates = [
-    import_node_path14.default.resolve(moduleDir2, "../../scaffolds"),
-    import_node_path14.default.resolve(moduleDir2, "../scaffolds")
+    import_node_path16.default.resolve(moduleDir2, "../../scaffolds"),
+    import_node_path16.default.resolve(moduleDir2, "../scaffolds")
   ];
   const found = candidates.find((candidate) => (0, import_node_fs3.existsSync)(candidate));
   return found ?? candidates[0];
@@ -2408,31 +2947,31 @@ Edit \`contracts/app/src/lib.rs\` to customize the contract. Add a frontend late
 `;
 }
 async function createMinimalProject(options) {
-  const targetDir = import_node_path14.default.resolve(options.targetDir);
+  const targetDir = import_node_path16.default.resolve(options.targetDir);
   const force = options.force ?? false;
-  await (0, import_promises11.mkdir)(targetDir, { recursive: true });
+  await (0, import_promises12.mkdir)(targetDir, { recursive: true });
   await Promise.all([
-    (0, import_promises11.writeFile)(import_node_path14.default.join(targetDir, "caatinga.config.ts"), configSource2(options.projectName), {
+    (0, import_promises12.writeFile)(import_node_path16.default.join(targetDir, "caatinga.config.ts"), configSource2(options.projectName), {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     }),
-    (0, import_promises11.writeFile)(import_node_path14.default.join(targetDir, "package.json"), packageJsonSource2(options.projectName), {
+    (0, import_promises12.writeFile)(import_node_path16.default.join(targetDir, "package.json"), packageJsonSource2(options.projectName), {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     }),
-    (0, import_promises11.writeFile)(import_node_path14.default.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", {
+    (0, import_promises12.writeFile)(import_node_path16.default.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     }),
-    (0, import_promises11.writeFile)(import_node_path14.default.join(targetDir, "README.md"), readmeSource2(options.projectName), {
+    (0, import_promises12.writeFile)(import_node_path16.default.join(targetDir, "README.md"), readmeSource2(options.projectName), {
       encoding: "utf8",
       flag: force ? "w" : "wx"
     })
   ]);
-  await (0, import_promises11.mkdir)(import_node_path14.default.join(targetDir, "contracts"), { recursive: true });
-  await (0, import_promises11.cp)(
-    import_node_path14.default.join(scaffoldRoot2(), "soroban-contract-stub"),
-    import_node_path14.default.join(targetDir, "contracts", "app"),
+  await (0, import_promises12.mkdir)(import_node_path16.default.join(targetDir, "contracts"), { recursive: true });
+  await (0, import_promises12.cp)(
+    import_node_path16.default.join(scaffoldRoot2(), "soroban-contract-stub"),
+    import_node_path16.default.join(targetDir, "contracts", "app"),
     {
       recursive: true,
       force,
@@ -2447,37 +2986,25 @@ 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);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   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,
@@ -2485,6 +3012,7 @@ function isTransientTestnetSmokeFailure(logText) {
   buildReadCallHint,
   checkBinary,
   checkStellarCliVersion,
+  checkStellarSdkVersion,
   collectProjectStatus,
   createInitialArtifacts,
   createMinimalProject,
@@ -2493,20 +3021,27 @@ function isTransientTestnetSmokeFailure(logText) {
   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,
@@ -2516,6 +3051,8 @@ function isTransientTestnetSmokeFailure(logText) {
   resolveDeployOrder,
   resolveNetwork,
   resolveSubprocessEnv,
+  restoreArtifactFromHistory,
+  rollbackContractArtifact,
   runCommand,
   toCaatingaError,
   updateArtifact,