@caatinga/core 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,72 +1,11 @@
-// src/errors/CaatingaErrorCode.ts
-var CaatingaErrorCode = {
-  CONFIG_NOT_FOUND: "CAATINGA_CONFIG_NOT_FOUND",
-  INVALID_CONFIG: "CAATINGA_INVALID_CONFIG",
-  COMMAND_FAILED: "CAATINGA_COMMAND_FAILED",
-  UNEXPECTED_ERROR: "CAATINGA_UNEXPECTED_ERROR",
-  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",
-  UNTESTED_CLI_VERSION: "CAATINGA_UNTESTED_CLI_VERSION",
-  RUST_NOT_FOUND: "CAATINGA_RUST_NOT_FOUND",
-  RUST_TARGET_NOT_FOUND: "CAATINGA_RUST_TARGET_NOT_FOUND",
-  DEPLOY_FAILED: "CAATINGA_DEPLOY_FAILED",
-  BUILD_FAILED: "CAATINGA_BUILD_FAILED",
-  BINDINGS_FAILED: "CAATINGA_BINDINGS_FAILED",
-  INVOKE_FAILED: "CAATINGA_INVOKE_FAILED",
-  CONTRACT_NOT_FOUND: "CAATINGA_CONTRACT_NOT_FOUND",
-  NETWORK_NOT_FOUND: "CAATINGA_NETWORK_NOT_FOUND",
-  ARTIFACT_NOT_FOUND: "CAATINGA_ARTIFACT_NOT_FOUND",
-  ARTIFACT_INVALID: "CAATINGA_ARTIFACT_INVALID",
-  CONTRACT_ID_NOT_FOUND: "CAATINGA_CONTRACT_ID_NOT_FOUND",
-  CONTRACT_ARTIFACT_NOT_FOUND: "CAATINGA_CONTRACT_ARTIFACT_NOT_FOUND",
-  CONTRACT_DEPENDENCY_NOT_FOUND: "CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND",
-  CONTRACT_DEPENDENCY_CYCLE: "CAATINGA_CONTRACT_DEPENDENCY_CYCLE",
-  CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND: "CAATINGA_CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND",
-  DEPLOY_ARG_PLACEHOLDER_INVALID: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_INVALID",
-  DEPLOY_ARG_PLACEHOLDER_UNRESOLVED: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED",
-  BINDING_CLIENT_NOT_FOUND: "CAATINGA_BINDING_CLIENT_NOT_FOUND",
-  BINDING_METHOD_NOT_FOUND: "CAATINGA_BINDING_METHOD_NOT_FOUND",
-  XDR_BUILD_FAILED: "CAATINGA_XDR_BUILD_FAILED",
-  XDR_PREPARE_FAILED: "CAATINGA_XDR_PREPARE_FAILED",
-  XDR_SIGN_FAILED: "CAATINGA_XDR_SIGN_FAILED",
-  XDR_SUBMIT_FAILED: "CAATINGA_XDR_SUBMIT_FAILED",
-  XDR_RESULT_FAILED: "CAATINGA_XDR_RESULT_FAILED",
-  WALLET_NOT_CONNECTED: "CAATINGA_WALLET_NOT_CONNECTED",
-  SOURCE_ACCOUNT_REQUIRED: "CAATINGA_SOURCE_ACCOUNT_REQUIRED",
-  UNSAFE_SOURCE_ACCOUNT: "CAATINGA_UNSAFE_SOURCE_ACCOUNT",
-  INVOKE_TARGET_INVALID: "CAATINGA_INVOKE_TARGET_INVALID",
-  TEMPLATE_NOT_FOUND: "CAATINGA_TEMPLATE_NOT_FOUND",
-  INVALID_TEMPLATE_MANIFEST: "CAATINGA_INVALID_TEMPLATE_MANIFEST",
-  TEMPLATE_MANIFEST_NOT_FOUND: "CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND",
-  TEMPLATE_INCOMPATIBLE: "CAATINGA_TEMPLATE_INCOMPATIBLE"
-};
-
-// src/errors/CaatingaError.ts
-var CaatingaError = class extends Error {
-  constructor(message, code, hint, cause) {
-    super(message);
-    this.code = code;
-    this.hint = hint;
-    this.cause = cause;
-    this.name = "CaatingaError";
-  }
-  code;
-  hint;
-  cause;
-};
-function toCaatingaError(error) {
-  if (error instanceof CaatingaError) {
-    return error;
-  }
-  if (error instanceof Error) {
-    return new CaatingaError(error.message, CaatingaErrorCode.UNEXPECTED_ERROR, void 0, error);
-  }
-  return new CaatingaError("An unexpected error occurred.", CaatingaErrorCode.UNEXPECTED_ERROR);
-}
+import {
+  CaatingaError,
+  CaatingaErrorCode,
+  toCaatingaError
+} from "./chunk-GMABXVEY.js";
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "0.2.0";
+var CAATINGA_CORE_VERSION = "0.2.2";
 
 // src/config/config.schema.ts
 import { z } from "zod";
@@ -253,7 +192,7 @@ import { execa } from "execa";
 
 // src/stellar-cli/version.ts
 import semver from "semver";
-var STELLAR_CLI_MIN_VERSION = "22.0.0";
+var STELLAR_CLI_MIN_VERSION = "23.0.0";
 var STELLAR_CLI_TESTED_MAX_VERSION = "25.2.0";
 var STELLAR_CLI_SEMVER_REGEX = /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?)\b/;
 function parseStellarCliVersion(output) {
@@ -386,6 +325,146 @@ function parseContractId(output) {
   return match[0];
 }
 
+// src/stellar-cli/build-stellar-network-args.ts
+function matchesWellKnownNetwork(name, config) {
+  const known = WELL_KNOWN_NETWORKS[name];
+  if (!known) {
+    return false;
+  }
+  return known.rpcUrl === config.rpcUrl && known.networkPassphrase === config.networkPassphrase;
+}
+function buildRpcNetworkArgs(config) {
+  return [
+    "--rpc-url",
+    config.rpcUrl,
+    "--network-passphrase",
+    config.networkPassphrase
+  ];
+}
+function buildStellarNetworkArgsFromConfig(config) {
+  for (const [name, known] of Object.entries(WELL_KNOWN_NETWORKS)) {
+    if (known.rpcUrl === config.rpcUrl && known.networkPassphrase === config.networkPassphrase) {
+      return ["--network", name];
+    }
+  }
+  return buildRpcNetworkArgs(config);
+}
+function buildStellarNetworkArgs(network) {
+  if (matchesWellKnownNetwork(network.name, network.config)) {
+    return ["--network", network.name];
+  }
+  return buildStellarNetworkArgsFromConfig(network.config);
+}
+
+// src/stellar-cli/recover-deploy-contract-id.ts
+var TX_HASH_REGEX = /Transaction hash is ([a-f0-9]{64})/i;
+var DEPLOY_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
+var HORIZON_URL_BY_PASSPHRASE = {
+  "Test SDF Network ; September 2015": "https://horizon-testnet.stellar.org",
+  "Public Global Stellar Network ; September 2015": "https://horizon.stellar.org"
+};
+function isLikelyPublicKeySource(source) {
+  return /^G[A-Z2-7]{55}$/.test(source);
+}
+function decimalSaltToHex(salt) {
+  return BigInt(salt).toString(16).padStart(64, "0");
+}
+function resolveHorizonUrl(network) {
+  const horizonUrl = HORIZON_URL_BY_PASSPHRASE[network.networkPassphrase];
+  if (!horizonUrl) {
+    throw new CaatingaError(
+      `No Horizon URL mapping for network passphrase "${network.networkPassphrase}".`,
+      CaatingaErrorCode.NETWORK_NOT_FOUND,
+      "Use testnet or mainnet, or extend Caatinga network metadata."
+    );
+  }
+  return horizonUrl;
+}
+async function fetchCreateContractSalt(horizonUrl, transactionHash, fetchImpl = fetch) {
+  const response = await fetchImpl(`${horizonUrl}/transactions/${transactionHash}/operations`);
+  if (!response.ok) {
+    return null;
+  }
+  const body = await response.json();
+  const operation = body._embedded?.records?.find(
+    (record) => record.transaction_successful === true && record.type === "invoke_host_function" && record.function === "HostFunctionTypeHostFunctionTypeCreateContract" && typeof record.salt === "string"
+  );
+  return operation?.salt ?? null;
+}
+async function resolveContractIdFromDeploySalt(options) {
+  const saltHex = decimalSaltToHex(options.salt);
+  const result = await runCommand("stellar", [
+    "contract",
+    "id",
+    "wasm",
+    "--salt",
+    saltHex,
+    "--source-account",
+    options.source,
+    ...buildStellarNetworkArgsFromConfig(options.network)
+  ], {
+    cwd: options.cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli,
+    skipStellarVersionCheck: true
+  });
+  return parseContractId(result.all || `${result.stdout}
+${result.stderr}`);
+}
+async function tryRecoverContractIdFromDeployFailure(options) {
+  if (!DEPLOY_SIGNING_FAILURE_REGEX.test(options.output)) {
+    return null;
+  }
+  const hashMatch = options.output.match(TX_HASH_REGEX);
+  if (!hashMatch) {
+    return null;
+  }
+  const horizonUrl = resolveHorizonUrl(options.network);
+  const salt = await fetchCreateContractSalt(horizonUrl, hashMatch[1], options.fetchImpl);
+  if (!salt) {
+    return null;
+  }
+  return resolveContractIdFromDeploySalt({
+    salt,
+    source: options.source,
+    network: options.network,
+    cwd: options.cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+}
+
+// src/contracts/validate-source-shape.ts
+function validateSourceShape(source) {
+  if (source.startsWith("S")) {
+    return new CaatingaError(
+      "Refusing to accept a Stellar secret key as --source.",
+      CaatingaErrorCode.SOURCE_IS_SECRET_KEY,
+      "Use a Stellar CLI identity alias instead, for example: --source alice"
+    );
+  }
+  if (source.trim().includes(" ")) {
+    return new CaatingaError(
+      "Refusing to accept a seed phrase as --source.",
+      CaatingaErrorCode.SOURCE_IS_SEED_PHRASE,
+      "Use a Stellar CLI identity alias instead, for example: --source alice"
+    );
+  }
+  if (isLikelyPublicKeySource(source)) {
+    return new CaatingaError(
+      `Public account address cannot sign transactions: ${source}`,
+      CaatingaErrorCode.SOURCE_IS_PUBLIC_KEY,
+      "Use a Stellar CLI identity with a secret key. Example: stellar keys generate alice --fund --network testnet, then --source alice"
+    );
+  }
+  if (source.startsWith("G")) {
+    return new CaatingaError(
+      "Refusing to accept a public account address as --source.",
+      CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
+      "Use a Stellar CLI identity alias, not a public address. Example: --source alice"
+    );
+  }
+  return void 0;
+}
+
 // src/contracts/resolve-contract.ts
 import path4 from "path";
 function resolveContract(config, contractName, cwd = process.cwd()) {
@@ -407,25 +486,99 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
 
 // src/contracts/wasm.ts
 import { createHash } from "crypto";
-import { access as access2, readFile as readFile2 } from "fs/promises";
-async function assertWasmExists(wasmPath) {
+import { access as access2, readdir, readFile as readFile2, stat } from "fs/promises";
+import path5 from "path";
+var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
+var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
+function toCurrentWasmTargetPath(wasmPath) {
+  if (!wasmPath.includes(LEGACY_RUST_WASM_TARGET)) {
+    return wasmPath;
+  }
+  return wasmPath.replaceAll(LEGACY_RUST_WASM_TARGET, CURRENT_RUST_WASM_TARGET);
+}
+function wasmNotFoundError(configuredWasmPath, options) {
+  const migratedPath = options?.migratedPath;
+  const hint = migratedPath === void 0 ? "Run caatinga build before deploy or generate." : [
+    "Run caatinga build before deploy or generate.",
+    `Soroban builds use the "${CURRENT_RUST_WASM_TARGET}" target.`,
+    `Update wasm in caatinga.config.ts to "${toConfigRelativeWasmPath(migratedPath)}" or an equivalent path under target/${CURRENT_RUST_WASM_TARGET}/release/.`
+  ].join(" ");
+  return new CaatingaError(
+    `WASM output was not found at ${configuredWasmPath}.`,
+    CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+    hint
+  );
+}
+function toConfigRelativeWasmPath(absoluteWasmPath) {
+  const relative = path5.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path5.sep).join("/")}`;
+}
+async function resolveWasmArtifactPath(configuredWasmPath) {
   try {
-    await access2(wasmPath);
+    await access2(configuredWasmPath);
+    return configuredWasmPath;
   } catch {
-    throw new CaatingaError(
-      `WASM output was not found at ${wasmPath}.`,
-      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
-      "Run caatinga build before deploy or generate."
-    );
+    const currentTargetPath = toCurrentWasmTargetPath(configuredWasmPath);
+    if (currentTargetPath === configuredWasmPath) {
+      throw wasmNotFoundError(configuredWasmPath);
+    }
+    try {
+      await access2(currentTargetPath);
+      return currentTargetPath;
+    } catch {
+      throw wasmNotFoundError(configuredWasmPath, { migratedPath: currentTargetPath });
+    }
   }
 }
 async function hashWasm(wasmPath) {
   const bytes = await readFile2(wasmPath);
   return createHash("sha256").update(bytes).digest("hex");
 }
+async function getNewestMtimeInDirectory(directory) {
+  try {
+    await access2(directory);
+  } catch {
+    return void 0;
+  }
+  let newest = 0;
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path5.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(entryPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const fileStat = await stat(entryPath);
+      newest = Math.max(newest, fileStat.mtimeMs);
+    }
+  }
+  await walk(directory);
+  return newest > 0 ? newest : void 0;
+}
+async function isWasmOlderThanSources(input) {
+  const srcDir = path5.join(input.contractPath, "src");
+  const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
+  if (newestSourceMtime === void 0) {
+    return false;
+  }
+  let wasmStat;
+  try {
+    wasmStat = await stat(input.wasmPath);
+  } catch {
+    return false;
+  }
+  return wasmStat.mtimeMs < newestSourceMtime;
+}
+function formatStaleWasmWarning(contractName) {
+  return `WASM for "${contractName}" may be stale: contract sources under src/ are newer than the WASM file. Run \`caatinga build\` before deploy.`;
+}
 
 // src/contracts/build-contract.ts
-var RUST_WASM_TARGET = "wasm32-unknown-unknown";
+var RUST_WASM_TARGET = "wasm32v1-none";
 var MISSING_WASM_TARGET_HINT_SUBSTRINGS = [
   "not installed",
   "not found",
@@ -467,21 +620,24 @@ async function buildContract(options) {
       throw new CaatingaError(
         `Required Rust wasm target "${RUST_WASM_TARGET}" is missing.`,
         CaatingaErrorCode.RUST_TARGET_NOT_FOUND,
-        `Run \`rustup target add ${RUST_WASM_TARGET}\` and retry the build.`,
+        `Run \`rustup target add ${RUST_WASM_TARGET}\` and retry.`,
         error
       );
     }
     throw error;
   }
-  await assertWasmExists(contract.wasmPath);
+  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath);
   return {
-    contract,
+    contract: {
+      ...contract,
+      wasmPath
+    },
     output: result.all || result.stdout
   };
 }
 
 // src/contracts/deploy-contract.ts
-import path5 from "path";
+import path6 from "path";
 
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
@@ -529,15 +685,12 @@ function assertSafeSourceAccount(source) {
     throw new CaatingaError(
       "A source account or Stellar CLI identity is required.",
       CaatingaErrorCode.SOURCE_ACCOUNT_REQUIRED,
-      "Pass --source alice or --source G...; do not pass secret keys or seed phrases."
+      "Pass a Stellar CLI identity alias, for example: --source alice"
     );
   }
-  if (source.startsWith("S") || source.trim().includes(" ")) {
-    throw new CaatingaError(
-      "Refusing to accept a likely secret key or seed phrase as --source.",
-      CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
-      "Use a Stellar CLI identity alias or public account address instead."
-    );
+  const unsafeSource = validateSourceShape(source);
+  if (unsafeSource) {
+    throw unsafeSource;
   }
   return source;
 }
@@ -565,17 +718,32 @@ async function deployContract(options) {
   await checkBinary("stellar", "Install Stellar CLI before running caatinga deploy.", {
     allowUntestedStellarCli: options.allowUntestedStellarCli
   });
-  await assertWasmExists(contract.wasmPath);
+  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath);
+  const contractWithWasm = {
+    ...contract,
+    wasmPath
+  };
+  let staleWasmWarning;
+  if (options.checkStaleWasm !== false) {
+    const stale = await isWasmOlderThanSources({
+      wasmPath,
+      contractPath: contract.sourcePath
+    });
+    if (stale) {
+      staleWasmWarning = formatStaleWasmWarning(contract.name);
+    }
+  }
   const artifactsBefore = await readArtifacts(cwd);
   const existing = artifactsBefore.networks[network.name]?.contracts[contract.name];
   if (existing?.contractId && !options.force) {
     return {
-      contract,
+      contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: path5.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: path6.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
-      skipped: true
+      skipped: true,
+      staleWasmWarning
     };
   }
   const rawDeployArgs = contract.config.deployArgs;
@@ -606,24 +774,46 @@ async function deployContract(options) {
     "contract",
     "deploy",
     "--wasm",
-    contract.wasmPath,
+    wasmPath,
     "--source-account",
     source,
-    "--rpc-url",
-    network.config.rpcUrl,
-    "--network-passphrase",
-    network.config.networkPassphrase,
+    ...buildStellarNetworkArgs(network),
     ...constructorArgs
   ];
-  const result = await runCommand("stellar", stellarArgs, {
-    cwd,
-    allowUntestedStellarCli: options.allowUntestedStellarCli,
-    failureCode: CaatingaErrorCode.DEPLOY_FAILED
-  });
-  const output = result.all || `${result.stdout}
+  let output = "";
+  let contractId;
+  try {
+    const result = await runCommand("stellar", stellarArgs, {
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      failureCode: CaatingaErrorCode.DEPLOY_FAILED
+    });
+    output = result.all || `${result.stdout}
 ${result.stderr}`;
-  const contractId = parseContractId(output);
-  const wasmHash = await hashWasm(contract.wasmPath);
+    contractId = parseContractId(output);
+  } 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,
+      allowUntestedStellarCli: options.allowUntestedStellarCli
+    });
+    if (!recoveredContractId) {
+      throw error;
+    }
+    contractId = recoveredContractId;
+    output = [
+      error.hint ?? "",
+      "Caatinga recovered the contract ID from the on-chain deploy transaction.",
+      `Contract ID: ${contractId}`
+    ].filter(Boolean).join("\n");
+  }
+  const wasmHash = await hashWasm(wasmPath);
   const dependencyGraph = buildDependencyGraph(options.config.contracts);
   const dependencies = options.dependencies ?? contract.config.dependsOn;
   const nextArtifacts = updateArtifact(
@@ -643,12 +833,13 @@ ${result.stderr}`;
   );
   const artifactsPath = await writeArtifacts(nextArtifacts, cwd);
   return {
-    contract,
+    contract: contractWithWasm,
     network,
     contractId,
     artifactsPath,
     output,
-    skipped: false
+    skipped: false,
+    staleWasmWarning
   };
 }
 
@@ -703,6 +894,53 @@ function resolveDeployOrder(input) {
   }
 }
 
+// src/contracts/verify-dependency-contract.ts
+async function verifyDependencyContract(options) {
+  try {
+    await runCommand("stellar", [
+      "contract",
+      "info",
+      "interface",
+      "--contract-id",
+      options.contractId,
+      ...buildStellarNetworkArgs(options.network)
+    ], {
+      cwd: options.cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      failureCode: CaatingaErrorCode.DEPENDENCY_CONTRACT_NOT_FOUND
+    });
+  } catch (error) {
+    if (error instanceof CaatingaError && error.code === CaatingaErrorCode.DEPENDENCY_CONTRACT_NOT_FOUND) {
+      throw new CaatingaError(
+        `Dependency "${options.dependencyName}" is not deployed on "${options.network.name}" (contract ID ${options.contractId}).`,
+        CaatingaErrorCode.DEPENDENCY_CONTRACT_NOT_FOUND,
+        "Deploy the dependency on this network, fix caatinga.artifacts.json, or omit --verify-deps.",
+        error.cause
+      );
+    }
+    throw error;
+  }
+}
+async function verifyDependencyContracts(options) {
+  for (const dependencyName of options.dependencies) {
+    const contractArtifact = options.artifacts.networks[options.network.name]?.contracts[dependencyName];
+    if (!contractArtifact?.contractId) {
+      throw new CaatingaError(
+        `No dependency artifact found for "${dependencyName}" on "${options.network.name}".`,
+        CaatingaErrorCode.CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND,
+        "Deploy the dependency first or run deploy without --no-deps."
+      );
+    }
+    await verifyDependencyContract({
+      dependencyName,
+      contractId: contractArtifact.contractId,
+      network: options.network,
+      cwd: options.cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli
+    });
+  }
+}
+
 // src/contracts/deploy-contract-graph.ts
 async function deployContractGraph(options) {
   const cwd = options.cwd ?? process.cwd();
@@ -713,17 +951,33 @@ async function deployContractGraph(options) {
     includeDependencies: options.includeDependencies
   });
   const deployedContracts = [];
+  const skippedContracts = [];
+  const staleWasmWarnings = [];
   for (const contractName of order) {
     const artifacts = await readArtifacts(cwd);
     const existing = artifacts.networks[network.name]?.contracts[contractName];
     const contractConfig = options.config.contracts[contractName];
+    if (options.verifyDeps && contractConfig.dependsOn.length > 0) {
+      await verifyDependencyContracts({
+        dependencies: contractConfig.dependsOn,
+        artifacts,
+        network,
+        cwd,
+        allowUntestedStellarCli: options.allowUntestedStellarCli
+      });
+    }
     const resolvedDeployArgs = resolveDeployArgs({
       deployArgs: contractConfig.deployArgs,
       artifacts,
       network: network.name
     });
     if (existing?.contractId && !options.force) {
-      deployedContracts.push({ name: contractName, contractId: existing.contractId });
+      skippedContracts.push({
+        name: contractName,
+        contractId: existing.contractId,
+        network: network.name,
+        reason: "already-deployed"
+      });
       continue;
     }
     const result = await deployContract({
@@ -734,20 +988,38 @@ async function deployContractGraph(options) {
       cwd,
       allowUntestedStellarCli: options.allowUntestedStellarCli,
       force: options.force,
+      checkStaleWasm: options.checkStaleWasm,
       resolvedDeployArgs,
       dependencies: contractConfig.dependsOn
     });
-    deployedContracts.push({ name: contractName, contractId: result.contractId });
+    if (result.staleWasmWarning) {
+      staleWasmWarnings.push({
+        contract: contractName,
+        message: result.staleWasmWarning
+      });
+    }
+    if (result.skipped) {
+      skippedContracts.push({
+        name: contractName,
+        contractId: result.contractId,
+        network: network.name,
+        reason: "already-deployed"
+      });
+    } else {
+      deployedContracts.push({ name: contractName, contractId: result.contractId });
+    }
   }
   return {
     network,
-    deployedContracts
+    deployedContracts,
+    skippedContracts,
+    staleWasmWarnings
   };
 }
 
 // src/contracts/generate-bindings.ts
 import { mkdir as mkdir2 } from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 async function generateBindings(options) {
   const cwd = options.cwd ?? process.cwd();
   const network = resolveNetwork(options.config, options.networkName);
@@ -763,7 +1035,7 @@ async function generateBindings(options) {
   await checkBinary("stellar", "Install Stellar CLI before running caatinga generate.", {
     allowUntestedStellarCli: options.allowUntestedStellarCli
   });
-  const outputDir = path6.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const outputDir = path7.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   await mkdir2(outputDir, { recursive: true });
   const result = await runCommand("stellar", [
     "contract",
@@ -774,10 +1046,7 @@ async function generateBindings(options) {
     "--output-dir",
     outputDir,
     "--overwrite",
-    "--rpc-url",
-    network.config.rpcUrl,
-    "--network-passphrase",
-    network.config.networkPassphrase
+    ...buildStellarNetworkArgs(network)
   ], {
     cwd,
     allowUntestedStellarCli: options.allowUntestedStellarCli,
@@ -792,6 +1061,7 @@ async function generateBindings(options) {
 }
 
 // src/contracts/invoke-contract.ts
+var INVOKE_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
 function parseInvokeTarget(target) {
   const [contractName, method, extra] = target.split(".");
   if (!contractName || !method || extra) {
@@ -820,25 +1090,43 @@ async function invokeContract(options) {
   await checkBinary("stellar", "Install Stellar CLI before running caatinga invoke.", {
     allowUntestedStellarCli: options.allowUntestedStellarCli
   });
-  const result = await runCommand("stellar", [
-    "contract",
-    "invoke",
-    "--id",
-    contractArtifact.contractId,
-    "--source-account",
-    source,
-    "--rpc-url",
-    network.config.rpcUrl,
-    "--network-passphrase",
-    network.config.networkPassphrase,
-    "--",
-    target.method,
-    ...options.args ?? []
-  ], {
-    cwd,
-    allowUntestedStellarCli: options.allowUntestedStellarCli,
-    failureCode: CaatingaErrorCode.INVOKE_FAILED
-  });
+  let result;
+  try {
+    result = await runCommand("stellar", [
+      "contract",
+      "invoke",
+      "--id",
+      contractArtifact.contractId,
+      "--source-account",
+      source,
+      ...buildStellarNetworkArgs(network),
+      "--",
+      target.method,
+      ...options.args ?? []
+    ], {
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      failureCode: CaatingaErrorCode.INVOKE_FAILED
+    });
+  } catch (error) {
+    if (error instanceof CaatingaError && error.code === CaatingaErrorCode.INVOKE_FAILED && INVOKE_SIGNING_FAILURE_REGEX.test(`${error.message}
+${error.hint ?? ""}`)) {
+      throw new CaatingaError(
+        error.message,
+        error.code,
+        [
+          "Stellar CLI could not sign the invoke transaction (xdr value invalid).",
+          "Stellar CLI 22.x has a known invoke signing bug; upgrade to 23.0.0 or newer (25.2.0 recommended).",
+          "  stellar --version",
+          "Then retry with a funded identity, for example:",
+          "  stellar keys generate alice --fund --network testnet",
+          "  npx caatinga invoke counter.increment --network testnet --source alice"
+        ].join("\n"),
+        error
+      );
+    }
+    throw error;
+  }
   return {
     target,
     network,
@@ -847,8 +1135,8 @@ async function invokeContract(options) {
 }
 
 // src/templates/create-project-from-template.ts
-import { cp, mkdir as mkdir3, readFile as readFile3, readdir, stat, writeFile as writeFile2 } from "fs/promises";
-import path7 from "path";
+import { cp, mkdir as mkdir3, readFile as readFile3, readdir as readdir2, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import path8 from "path";
 import { z as z6 } from "zod";
 
 // src/templates/template-manifest.schema.ts
@@ -876,16 +1164,52 @@ var TemplateManifestSchema = z5.object({
     artifacts: z5.string().default("caatinga.artifacts.json")
   })
 });
+function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
+  const version = semver2.valid(semver2.coerce(coreVersion));
+  if (!version) {
+    throw new Error(`Invalid core version: ${coreVersion}`);
+  }
+  return `^${version}`;
+}
 function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
   return semver2.satisfies(coreVersion, range);
 }
+function getTemplateCompatibilityIssue(manifest, coreVersion = CAATINGA_CORE_VERSION) {
+  if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
+    return {
+      kind: "template-version",
+      expected: CURRENT_TEMPLATE_VERSION,
+      actual: manifest.caatinga.templateVersion
+    };
+  }
+  if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore, coreVersion)) {
+    return {
+      kind: "core-range",
+      requiredRange: manifest.caatinga.compatibleCore,
+      runningVersion: coreVersion
+    };
+  }
+  return null;
+}
+function formatTemplateCompatibilityMessage(issue) {
+  if (issue.kind === "template-version") {
+    return `Template manifest version ${issue.actual} is not supported; Caatinga requires templateVersion ${issue.expected}.`;
+  }
+  return `Template requires @caatinga/core ${issue.requiredRange} but running ${issue.runningVersion}.`;
+}
+function formatTemplateCompatibilityHint(issue) {
+  if (issue.kind === "template-version") {
+    return "Use a template built for this Caatinga release or upgrade Caatinga.";
+  }
+  return `Use a template with compatibleCore ${defaultCompatibleCoreRange(issue.runningVersion)} or install a matching Caatinga version.`;
+}
 
 // src/templates/create-project-from-template.ts
 async function createProjectFromTemplate(options) {
-  const targetDir = path7.resolve(options.targetDir);
-  const templateDir = path7.resolve(options.templateDir);
+  const targetDir = path8.resolve(options.targetDir);
+  const templateDir = path8.resolve(options.templateDir);
   try {
-    await stat(templateDir);
+    await stat2(templateDir);
   } catch {
     throw new CaatingaError(
       `Template directory was not found: ${templateDir}`,
@@ -905,22 +1229,16 @@ async function createProjectFromTemplate(options) {
   return { targetDir, template: manifest };
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = path7.join(templateDir, "caatinga.template.json");
+  const manifestPath = path8.join(templateDir, "caatinga.template.json");
   try {
     const rawManifest = await readFile3(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
-    if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
-      throw new CaatingaError(
-        "Template is not compatible with this Caatinga version.",
-        CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
-        "Use a compatible template version or upgrade Caatinga."
-      );
-    }
-    if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore)) {
+    const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
+    if (compatibilityIssue) {
       throw new CaatingaError(
-        "Template is not compatible with this Caatinga version.",
+        formatTemplateCompatibilityMessage(compatibilityIssue),
         CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
-        "Use a compatible template version or upgrade Caatinga."
+        formatTemplateCompatibilityHint(compatibilityIssue)
       );
     }
     return manifest;
@@ -946,10 +1264,10 @@ async function readTemplateManifest(templateDir) {
   }
 }
 async function replaceTemplateVariables(dir, projectName) {
-  const entries = await readdir(dir);
+  const entries = await readdir2(dir);
   await Promise.all(entries.map(async (entry) => {
-    const entryPath = path7.join(dir, entry);
-    const entryStat = await stat(entryPath);
+    const entryPath = path8.join(dir, entry);
+    const entryStat = await stat2(entryPath);
     if (entryStat.isDirectory()) {
       await replaceTemplateVariables(entryPath, projectName);
       return;
@@ -971,7 +1289,7 @@ function isTextTemplateFile(filePath) {
     ".tsx",
     ".css",
     ".html"
-  ].includes(path7.extname(filePath));
+  ].includes(path8.extname(filePath));
 }
 
 // src/ci/is-transient-testnet-smoke-failure.ts
@@ -1029,5 +1347,6 @@ export {
   runCommand,
   toCaatingaError,
   updateArtifact,
+  validateSourceShape,
   writeArtifacts
 };