@layr-labs/ecloud-sdk 0.2.0-dev → 0.2.0-dev.1

package/dist/compute.cjs

@@ -40,6 +40,7 @@ module.exports = __toCommonJS(compute_exports);
 
 // src/client/modules/compute/app/index.ts
 var import_viem9 = require("viem");
+var import_accounts5 = require("viem/accounts");
 
 // src/client/common/config/environment.ts
 var SEPOLIA_CHAIN_ID = 11155111;
@@ -162,6 +163,7 @@ async function buildDockerImage(buildContext, dockerfilePath, tag, logger) {
     tag,
     "-f",
     dockerfilePath,
+    "--load",
     "--progress=plain",
     buildContext
   ];
@@ -287,7 +289,7 @@ async function pullDockerImage(docker, imageTag, platform2 = "linux/amd64", logg
 var child_process2 = __toESM(require("child_process"), 1);
 var import_child_process = require("child_process");
 var import_util2 = require("util");
-var execAsync = (0, import_util2.promisify)(import_child_process.exec);
+var execFileAsync = (0, import_util2.promisify)(import_child_process.execFile);
 async function pushDockerImage(docker, imageRef, logger) {
   logger?.info?.(`Pushing image ${imageRef}...`);
   return new Promise((resolve2, reject) => {
@@ -328,9 +330,9 @@ async function pushDockerImage(docker, imageRef, logger) {
       if (!output.includes("digest:") && !output.includes("pushed") && !output.includes("Pushed")) {
         logger?.debug?.("No clear success indicator in push output, verifying...");
       }
-      logger?.info?.("Image push completed successfully");
       try {
         await verifyImageExists(imageRef, logger);
+        logger?.info?.("Image push completed successfully");
         resolve2();
       } catch (error) {
         reject(error);
@@ -354,7 +356,7 @@ async function verifyImageExists(imageRef, logger) {
   let retries = 5;
   while (retries > 0) {
     try {
-      await execAsync(`docker manifest inspect ${imageRef}`, {
+      await execFileAsync("docker", ["manifest", "inspect", imageRef], {
         maxBuffer: 10 * 1024 * 1024,
         timeout: 1e4
         // 10 second timeout
@@ -828,10 +830,10 @@ async function setupLayeredBuildDirectory(environmentConfig, layeredDockerfileCo
 // src/client/common/registry/digest.ts
 var child_process3 = __toESM(require("child_process"), 1);
 var import_util3 = require("util");
-var execFileAsync = (0, import_util3.promisify)(child_process3.execFile);
+var execFileAsync2 = (0, import_util3.promisify)(child_process3.execFile);
 async function getImageDigestAndName(imageRef) {
   try {
-    const { stdout } = await execFileAsync(
+    const { stdout } = await execFileAsync2(
       "docker",
       ["manifest", "inspect", imageRef],
       { maxBuffer: 10 * 1024 * 1024 }
@@ -871,7 +873,7 @@ function extractDigestFromMultiPlatform(manifest, imageRef) {
 }
 async function extractDigestFromSinglePlatform(manifest, imageRef) {
   try {
-    const { stdout } = await execFileAsync("docker", ["inspect", imageRef], {
+    const { stdout } = await execFileAsync2("docker", ["inspect", imageRef], {
       maxBuffer: 10 * 1024 * 1024
     });
     const inspectData = JSON.parse(stdout);
@@ -1169,6 +1171,67 @@ Please verify the image exists: docker manifest inspect ${finalImageRef}`
   };
 }
 
+// src/client/common/release/prebuilt.ts
+async function createReleaseFromImageDigest(options, logger) {
+  const { imageRef, imageDigest, envFilePath, instanceType, environmentConfig, appId } = options;
+  if (!/^sha256:[0-9a-f]{64}$/i.test(imageDigest)) {
+    throw new Error(`imageDigest must be in format sha256:<64 hex>, got: ${imageDigest}`);
+  }
+  let publicEnv = {};
+  let privateEnv = {};
+  if (envFilePath) {
+    logger.info("Parsing environment file...");
+    const parsed = parseAndValidateEnvFile(envFilePath);
+    publicEnv = parsed.public;
+    privateEnv = parsed.private;
+  } else {
+    logger.info("Continuing without environment file");
+  }
+  publicEnv["EIGEN_MACHINE_TYPE_PUBLIC"] = instanceType;
+  logger.info(`Instance type: ${instanceType}`);
+  logger.info("Encrypting environment variables...");
+  const { encryptionKey } = getKMSKeysForEnvironment(
+    environmentConfig.name,
+    environmentConfig.build
+  );
+  const protectedHeaders = getAppProtectedHeaders(appId);
+  const privateEnvBytes = Buffer.from(JSON.stringify(privateEnv));
+  const encryptedEnvStr = await encryptRSAOAEPAndAES256GCM(
+    encryptionKey,
+    privateEnvBytes,
+    protectedHeaders
+  );
+  const digestHex = imageDigest.split(":")[1];
+  const digestBytes = new Uint8Array(Buffer.from(digestHex, "hex"));
+  if (digestBytes.length !== 32) {
+    throw new Error(`Digest must be exactly 32 bytes, got ${digestBytes.length}`);
+  }
+  const registry = extractRegistryNameNoDocker(imageRef);
+  return {
+    rmsRelease: {
+      artifacts: [{ digest: digestBytes, registry }],
+      upgradeByTime: Math.floor(Date.now() / 1e3) + 3600
+    },
+    publicEnv: new Uint8Array(Buffer.from(JSON.stringify(publicEnv))),
+    encryptedEnv: new Uint8Array(Buffer.from(encryptedEnvStr))
+  };
+}
+function extractRegistryNameNoDocker(imageRef) {
+  let name = imageRef;
+  const tagIndex = name.lastIndexOf(":");
+  if (tagIndex !== -1 && !name.substring(tagIndex + 1).includes("/")) {
+    name = name.substring(0, tagIndex);
+  }
+  const digestIndex = name.indexOf("@");
+  if (digestIndex !== -1) {
+    name = name.substring(0, digestIndex);
+  }
+  if ([...name].filter((c) => c === "/").length === 1) {
+    name = `docker.io/${name}`;
+  }
+  return name;
+}
+
 // src/client/common/contract/caller.ts
 var import_accounts2 = require("viem/accounts");
 
@@ -2205,8 +2268,55 @@ var ERC7702Delegator_default = [
 ];
 
 // src/client/common/contract/eip7702.ts
+var EXECUTE_BATCH_MODE = "0x0100000000000000000000000000000000000000000000000000000000000000";
+var GAS_LIMIT_BUFFER_PERCENTAGE = 20n;
+var GAS_PRICE_BUFFER_PERCENTAGE = 100n;
+function encodeExecuteBatchData(executions) {
+  const encodedExecutions = (0, import_viem.encodeAbiParameters)(
+    [
+      {
+        type: "tuple[]",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "callData", type: "bytes" }
+        ]
+      }
+    ],
+    [executions]
+  );
+  return (0, import_viem.encodeFunctionData)({
+    abi: ERC7702Delegator_default,
+    functionName: "execute",
+    args: [EXECUTE_BATCH_MODE, encodedExecutions]
+  });
+}
+async function estimateBatchGas(options) {
+  const { publicClient, account, executions } = options;
+  const executeBatchData = encodeExecuteBatchData(executions);
+  const [gasTipCap, block, estimatedGas] = await Promise.all([
+    publicClient.estimateMaxPriorityFeePerGas(),
+    publicClient.getBlock(),
+    publicClient.estimateGas({
+      account,
+      to: account,
+      data: executeBatchData
+    })
+  ]);
+  const baseFee = block.baseFeePerGas ?? 0n;
+  const maxFeePerGas = (baseFee + gasTipCap) * (100n + GAS_PRICE_BUFFER_PERCENTAGE) / 100n;
+  const gasLimit = estimatedGas * (100n + GAS_LIMIT_BUFFER_PERCENTAGE) / 100n;
+  const maxCostWei = gasLimit * maxFeePerGas;
+  return {
+    gasLimit,
+    maxFeePerGas,
+    maxPriorityFeePerGas: gasTipCap,
+    maxCostWei,
+    maxCostEth: formatETH(maxCostWei)
+  };
+}
 async function checkERC7702Delegation(publicClient, account, delegatorAddress) {
-  const code = await publicClient.getBytecode({ address: account });
+  const code = await publicClient.getCode({ address: account });
   if (!code) {
     return false;
   }
@@ -2223,36 +2333,7 @@ async function executeBatch(options, logger) {
   if (!chain) {
     throw new Error("Wallet client must have a chain");
   }
-  const encodedExecutions = (0, import_viem.encodeAbiParameters)(
-    [
-      {
-        type: "tuple[]",
-        components: [
-          { name: "target", type: "address" },
-          { name: "value", type: "uint256" },
-          { name: "callData", type: "bytes" }
-        ]
-      }
-    ],
-    [executions]
-  );
-  const executeBatchMode = "0x0100000000000000000000000000000000000000000000000000000000000000";
-  let executeBatchData;
-  try {
-    executeBatchData = (0, import_viem.encodeFunctionData)({
-      abi: ERC7702Delegator_default,
-      functionName: "execute",
-      args: [executeBatchMode, encodedExecutions]
-    });
-  } catch {
-    const functionSignature = "execute(bytes32,bytes)";
-    const selector = (0, import_viem.keccak256)((0, import_viem.toBytes)(functionSignature)).slice(0, 10);
-    const encodedParams = (0, import_viem.encodeAbiParameters)(
-      [{ type: "bytes32" }, { type: "bytes" }],
-      [executeBatchMode, encodedExecutions]
-    );
-    executeBatchData = (0, import_viem.concat)([selector, encodedParams]);
-  }
+  const executeBatchData = encodeExecuteBatchData(executions);
   const isDelegated2 = await checkERC7702Delegation(
     publicClient,
     account.address,
@@ -2401,7 +2482,7 @@ var CanViewAppLogsPermission = "0x2fd3f2fe";
 var CanViewSensitiveAppInfoPermission = "0x0e67b22f";
 var CanUpdateAppProfilePermission = "0x036fef61";
 function getDefaultClientId() {
-  const version = true ? "0.2.0-dev" : "0.0.0";
+  const version = true ? "0.2.0-dev.1" : "0.0.0";
   return `ecloud-sdk/v${version}`;
 }
 var UserApiClient = class {
@@ -4220,6 +4301,15 @@ var PermissionController_default = [
 ];
 
 // src/client/common/contract/caller.ts
+function formatETH(wei) {
+  const eth = Number(wei) / 1e18;
+  const costStr = eth.toFixed(6);
+  const trimmed = costStr.replace(/\.?0+$/, "");
+  if (trimmed === "0" && wei > 0n) {
+    return "<0.000001";
+  }
+  return trimmed;
+}
 async function calculateAppID(privateKey, rpcUrl, environmentConfig, salt) {
   const privateKeyHex = addHexPrefix(privateKey);
   const account = (0, import_accounts2.privateKeyToAccount)(privateKeyHex);
@@ -4324,20 +4414,20 @@ async function prepareDeployBatch(options, logger) {
     environmentConfig
   };
 }
-async function executeDeployBatch(prepared, gas, logger) {
+async function executeDeployBatch(data, context, gas, logger) {
   const pendingMessage = "Deploying new app...";
   const txHash = await executeBatch(
     {
-      walletClient: prepared.walletClient,
-      publicClient: prepared.publicClient,
-      environmentConfig: prepared.environmentConfig,
-      executions: prepared.executions,
+      walletClient: context.walletClient,
+      publicClient: context.publicClient,
+      environmentConfig: context.environmentConfig,
+      executions: data.executions,
       pendingMessage,
       gas
     },
     logger
   );
-  return { appId: prepared.appId, txHash };
+  return { appId: data.appId, txHash };
 }
 async function deployApp(options, logger) {
   const prepared = await prepareDeployBatch(
@@ -4351,7 +4441,17 @@ async function deployApp(options, logger) {
     },
     logger
   );
-  return executeDeployBatch(prepared, options.gas, logger);
+  const data = {
+    appId: prepared.appId,
+    salt: prepared.salt,
+    executions: prepared.executions
+  };
+  const context = {
+    walletClient: prepared.walletClient,
+    publicClient: prepared.publicClient,
+    environmentConfig: prepared.environmentConfig
+  };
+  return executeDeployBatch(data, context, options.gas, logger);
 }
 async function prepareUpgradeBatch(options) {
   const {
@@ -4447,14 +4547,14 @@ async function prepareUpgradeBatch(options) {
     environmentConfig
   };
 }
-async function executeUpgradeBatch(prepared, gas, logger) {
-  const pendingMessage = `Upgrading app ${prepared.appId}...`;
+async function executeUpgradeBatch(data, context, gas, logger) {
+  const pendingMessage = `Upgrading app ${data.appId}...`;
   const txHash = await executeBatch(
     {
-      walletClient: prepared.walletClient,
-      publicClient: prepared.publicClient,
-      environmentConfig: prepared.environmentConfig,
-      executions: prepared.executions,
+      walletClient: context.walletClient,
+      publicClient: context.publicClient,
+      environmentConfig: context.environmentConfig,
+      executions: data.executions,
       pendingMessage,
       gas
     },
@@ -4472,7 +4572,16 @@ async function upgradeApp(options, logger) {
     publicLogs: options.publicLogs,
     needsPermissionChange: options.needsPermissionChange
   });
-  return executeUpgradeBatch(prepared, options.gas, logger);
+  const data = {
+    appId: prepared.appId,
+    executions: prepared.executions
+  };
+  const context = {
+    walletClient: prepared.walletClient,
+    publicClient: prepared.publicClient,
+    environmentConfig: prepared.environmentConfig
+  };
+  return executeUpgradeBatch(data, context, options.gas, logger);
 }
 async function sendAndWaitForTransaction(options, logger) {
   const {
@@ -5143,6 +5252,97 @@ async function withSDKTelemetry(options, action) {
 }
 
 // src/client/modules/compute/app/deploy.ts
+async function prepareDeployFromVerifiableBuild(options, logger = defaultLogger) {
+  return withSDKTelemetry(
+    {
+      functionName: "prepareDeployFromVerifiableBuild",
+      skipTelemetry: options.skipTelemetry,
+      properties: {
+        environment: options.environment || "sepolia"
+      }
+    },
+    async () => {
+      if (!options.privateKey) throw new Error("privateKey is required for deployment");
+      if (!options.imageRef) throw new Error("imageRef is required for deployment");
+      if (!options.imageDigest) throw new Error("imageDigest is required for deployment");
+      assertValidImageReference(options.imageRef);
+      validateAppName(options.appName);
+      validateLogVisibility(options.logVisibility);
+      if (!/^sha256:[0-9a-f]{64}$/i.test(options.imageDigest)) {
+        throw new Error(
+          `imageDigest must be in format sha256:<64 hex>, got: ${options.imageDigest}`
+        );
+      }
+      const { publicLogs } = validateLogVisibility(options.logVisibility);
+      validateResourceUsageMonitoring(options.resourceUsageMonitoring);
+      logger.debug("Performing preflight checks...");
+      const preflightCtx = await doPreflightChecks(
+        {
+          privateKey: options.privateKey,
+          rpcUrl: options.rpcUrl,
+          environment: options.environment
+        },
+        logger
+      );
+      logger.debug("Checking quota availability...");
+      await checkQuotaAvailable(preflightCtx);
+      const salt = generateRandomSalt();
+      logger.debug(`Generated salt: ${Buffer.from(salt).toString("hex")}`);
+      logger.debug("Calculating app ID...");
+      const appIDToBeDeployed = await calculateAppID(
+        preflightCtx.privateKey,
+        options.rpcUrl || preflightCtx.rpcUrl,
+        preflightCtx.environmentConfig,
+        salt
+      );
+      logger.info(``);
+      logger.info(`App ID: ${appIDToBeDeployed}`);
+      logger.info(``);
+      const release = await createReleaseFromImageDigest(
+        {
+          imageRef: options.imageRef,
+          imageDigest: options.imageDigest,
+          envFilePath: options.envFilePath,
+          instanceType: options.instanceType,
+          environmentConfig: preflightCtx.environmentConfig,
+          appId: appIDToBeDeployed
+        },
+        logger
+      );
+      logger.debug("Preparing deploy batch...");
+      const batch = await prepareDeployBatch(
+        {
+          privateKey: preflightCtx.privateKey,
+          rpcUrl: options.rpcUrl || preflightCtx.rpcUrl,
+          environmentConfig: preflightCtx.environmentConfig,
+          salt,
+          release,
+          publicLogs
+        },
+        logger
+      );
+      logger.debug("Estimating gas...");
+      const gasEstimate = await estimateBatchGas({
+        publicClient: batch.publicClient,
+        account: batch.walletClient.account.address,
+        executions: batch.executions
+      });
+      const data = {
+        appId: batch.appId,
+        salt: batch.salt,
+        executions: batch.executions
+      };
+      return {
+        prepared: {
+          data,
+          appName: options.appName,
+          imageRef: options.imageRef
+        },
+        gasEstimate
+      };
+    }
+  );
+}
 function validateDeployOptions(options) {
   if (!options.privateKey) {
     throw new Error("privateKey is required for deployment");
@@ -5291,6 +5491,141 @@ function generateRandomSalt() {
   crypto.getRandomValues(salt);
   return salt;
 }
+async function prepareDeploy(options, logger = defaultLogger) {
+  return withSDKTelemetry(
+    {
+      functionName: "prepareDeploy",
+      skipTelemetry: options.skipTelemetry,
+      properties: {
+        environment: options.environment || "sepolia"
+      }
+    },
+    async () => {
+      validateDeployOptions(options);
+      const { logRedirect, publicLogs } = validateLogVisibility(options.logVisibility);
+      const resourceUsageAllow = validateResourceUsageMonitoring(options.resourceUsageMonitoring);
+      logger.debug("Performing preflight checks...");
+      const preflightCtx = await doPreflightChecks(
+        {
+          privateKey: options.privateKey,
+          rpcUrl: options.rpcUrl,
+          environment: options.environment
+        },
+        logger
+      );
+      logger.debug("Checking quota availability...");
+      await checkQuotaAvailable(preflightCtx);
+      logger.debug("Checking Docker...");
+      await ensureDockerIsRunning();
+      const dockerfilePath = options.dockerfilePath || "";
+      const imageRef = options.imageRef || "";
+      const appName = options.appName;
+      const envFilePath = options.envFilePath || "";
+      const instanceType = options.instanceType;
+      const salt = generateRandomSalt();
+      logger.debug(`Generated salt: ${Buffer.from(salt).toString("hex")}`);
+      logger.debug("Calculating app ID...");
+      const appIDToBeDeployed = await calculateAppID(
+        preflightCtx.privateKey,
+        options.rpcUrl || preflightCtx.rpcUrl,
+        preflightCtx.environmentConfig,
+        salt
+      );
+      logger.info(``);
+      logger.info(`App ID: ${appIDToBeDeployed}`);
+      logger.info(``);
+      logger.info("Preparing release...");
+      const { release, finalImageRef } = await prepareRelease(
+        {
+          dockerfilePath,
+          imageRef,
+          envFilePath,
+          logRedirect,
+          resourceUsageAllow,
+          instanceType,
+          environmentConfig: preflightCtx.environmentConfig,
+          appId: appIDToBeDeployed
+        },
+        logger
+      );
+      logger.debug("Preparing deploy batch...");
+      const batch = await prepareDeployBatch(
+        {
+          privateKey: preflightCtx.privateKey,
+          rpcUrl: options.rpcUrl || preflightCtx.rpcUrl,
+          environmentConfig: preflightCtx.environmentConfig,
+          salt,
+          release,
+          publicLogs
+        },
+        logger
+      );
+      logger.debug("Estimating gas...");
+      const gasEstimate = await estimateBatchGas({
+        publicClient: batch.publicClient,
+        account: batch.walletClient.account.address,
+        executions: batch.executions
+      });
+      const data = {
+        appId: batch.appId,
+        salt: batch.salt,
+        executions: batch.executions
+      };
+      return {
+        prepared: {
+          data,
+          appName,
+          imageRef: finalImageRef
+        },
+        gasEstimate
+      };
+    }
+  );
+}
+async function executeDeploy(options) {
+  const { prepared, context, gas, logger = defaultLogger, skipTelemetry } = options;
+  return withSDKTelemetry(
+    {
+      functionName: "executeDeploy",
+      skipTelemetry
+    },
+    async () => {
+      logger.info("Deploying on-chain...");
+      const { appId, txHash } = await executeDeployBatch(prepared.data, context, gas, logger);
+      return {
+        appId,
+        txHash,
+        appName: prepared.appName,
+        imageRef: prepared.imageRef
+      };
+    }
+  );
+}
+async function watchDeployment(appId, privateKey, rpcUrl, environment, logger = defaultLogger, clientId, skipTelemetry) {
+  return withSDKTelemetry(
+    {
+      functionName: "watchDeployment",
+      skipTelemetry,
+      properties: {
+        environment
+      }
+    },
+    async () => {
+      const environmentConfig = getEnvironmentConfig(environment);
+      logger.info("Waiting for app to start...");
+      return watchUntilRunning(
+        {
+          privateKey,
+          rpcUrl,
+          environmentConfig,
+          appId,
+          clientId
+        },
+        logger
+      );
+    }
+  );
+}
 
 // src/client/common/utils/permissions.ts
 var import_viem8 = require("viem");
@@ -5318,6 +5653,81 @@ async function checkAppLogPermission(preflightCtx, appAddress, logger) {
 }
 
 // src/client/modules/compute/app/upgrade.ts
+async function prepareUpgradeFromVerifiableBuild(options, logger = defaultLogger) {
+  return withSDKTelemetry(
+    {
+      functionName: "prepareUpgradeFromVerifiableBuild",
+      skipTelemetry: options.skipTelemetry,
+      properties: {
+        environment: options.environment || "sepolia"
+      }
+    },
+    async () => {
+      logger.debug("Performing preflight checks...");
+      const preflightCtx = await doPreflightChecks(
+        {
+          privateKey: options.privateKey,
+          rpcUrl: options.rpcUrl,
+          environment: options.environment
+        },
+        logger
+      );
+      const appID = validateUpgradeOptions(options);
+      assertValidImageReference(options.imageRef);
+      if (!/^sha256:[0-9a-f]{64}$/i.test(options.imageDigest)) {
+        throw new Error(
+          `imageDigest must be in format sha256:<64 hex>, got: ${options.imageDigest}`
+        );
+      }
+      const { publicLogs } = validateLogVisibility(options.logVisibility);
+      validateResourceUsageMonitoring(options.resourceUsageMonitoring);
+      const envFilePath = options.envFilePath || "";
+      logger.info("Preparing release (verifiable build, no local layering)...");
+      const release = await createReleaseFromImageDigest(
+        {
+          imageRef: options.imageRef,
+          imageDigest: options.imageDigest,
+          envFilePath,
+          instanceType: options.instanceType,
+          environmentConfig: preflightCtx.environmentConfig,
+          appId: appID
+        },
+        logger
+      );
+      logger.debug("Checking current log permission state...");
+      const currentlyPublic = await checkAppLogPermission(preflightCtx, appID, logger);
+      const needsPermissionChange = currentlyPublic !== publicLogs;
+      logger.debug("Preparing upgrade batch...");
+      const batch = await prepareUpgradeBatch({
+        privateKey: preflightCtx.privateKey,
+        rpcUrl: options.rpcUrl || preflightCtx.rpcUrl,
+        environmentConfig: preflightCtx.environmentConfig,
+        appId: appID,
+        release,
+        publicLogs,
+        needsPermissionChange
+      });
+      logger.debug("Estimating gas...");
+      const gasEstimate = await estimateBatchGas({
+        publicClient: batch.publicClient,
+        account: batch.walletClient.account.address,
+        executions: batch.executions
+      });
+      const data = {
+        appId: batch.appId,
+        executions: batch.executions
+      };
+      return {
+        prepared: {
+          data,
+          appId: appID,
+          imageRef: options.imageRef
+        },
+        gasEstimate
+      };
+    }
+  );
+}
 function validateUpgradeOptions(options) {
   if (!options.privateKey) {
     throw new Error("privateKey is required for upgrade");
@@ -5422,6 +5832,125 @@ async function upgrade(options, logger = defaultLogger) {
     }
   );
 }
+async function prepareUpgrade(options, logger = defaultLogger) {
+  return withSDKTelemetry(
+    {
+      functionName: "prepareUpgrade",
+      skipTelemetry: options.skipTelemetry,
+      properties: {
+        environment: options.environment || "sepolia"
+      }
+    },
+    async () => {
+      logger.debug("Performing preflight checks...");
+      const preflightCtx = await doPreflightChecks(
+        {
+          privateKey: options.privateKey,
+          rpcUrl: options.rpcUrl,
+          environment: options.environment
+        },
+        logger
+      );
+      const appID = validateUpgradeOptions(options);
+      const { logRedirect, publicLogs } = validateLogVisibility(options.logVisibility);
+      const resourceUsageAllow = validateResourceUsageMonitoring(options.resourceUsageMonitoring);
+      logger.debug("Checking Docker...");
+      await ensureDockerIsRunning();
+      const dockerfilePath = options.dockerfilePath || "";
+      const imageRef = options.imageRef || "";
+      const envFilePath = options.envFilePath || "";
+      const instanceType = options.instanceType;
+      logger.info("Preparing release...");
+      const { release, finalImageRef } = await prepareRelease(
+        {
+          dockerfilePath,
+          imageRef,
+          envFilePath,
+          logRedirect,
+          resourceUsageAllow,
+          instanceType,
+          environmentConfig: preflightCtx.environmentConfig,
+          appId: appID
+        },
+        logger
+      );
+      logger.debug("Checking current log permission state...");
+      const currentlyPublic = await checkAppLogPermission(preflightCtx, appID, logger);
+      const needsPermissionChange = currentlyPublic !== publicLogs;
+      logger.debug("Preparing upgrade batch...");
+      const batch = await prepareUpgradeBatch({
+        privateKey: preflightCtx.privateKey,
+        rpcUrl: options.rpcUrl || preflightCtx.rpcUrl,
+        environmentConfig: preflightCtx.environmentConfig,
+        appId: appID,
+        release,
+        publicLogs,
+        needsPermissionChange
+      });
+      logger.debug("Estimating gas...");
+      const gasEstimate = await estimateBatchGas({
+        publicClient: batch.publicClient,
+        account: batch.walletClient.account.address,
+        executions: batch.executions
+      });
+      const data = {
+        appId: batch.appId,
+        executions: batch.executions
+      };
+      return {
+        prepared: {
+          data,
+          appId: appID,
+          imageRef: finalImageRef
+        },
+        gasEstimate
+      };
+    }
+  );
+}
+async function executeUpgrade(options) {
+  const { prepared, context, gas, logger = defaultLogger, skipTelemetry } = options;
+  return withSDKTelemetry(
+    {
+      functionName: "executeUpgrade",
+      skipTelemetry
+    },
+    async () => {
+      logger.info("Upgrading on-chain...");
+      const txHash = await executeUpgradeBatch(prepared.data, context, gas, logger);
+      return {
+        appId: prepared.appId,
+        imageRef: prepared.imageRef,
+        txHash
+      };
+    }
+  );
+}
+async function watchUpgrade(appId, privateKey, rpcUrl, environment, logger = defaultLogger, clientId, skipTelemetry) {
+  return withSDKTelemetry(
+    {
+      functionName: "watchUpgrade",
+      skipTelemetry,
+      properties: {
+        environment
+      }
+    },
+    async () => {
+      const environmentConfig = getEnvironmentConfig(environment);
+      logger.info("Waiting for upgrade to complete...");
+      await watchUntilUpgradeComplete(
+        {
+          privateKey,
+          rpcUrl,
+          environmentConfig,
+          appId,
+          clientId
+        },
+        logger
+      );
+    }
+  );
+}
 
 // src/client/modules/compute/app/create.ts
 var fs7 = __toESM(require("fs"), 1);
@@ -5519,8 +6048,8 @@ var path4 = __toESM(require("path"), 1);
 var os3 = __toESM(require("os"), 1);
 var import_child_process2 = require("child_process");
 var import_util4 = require("util");
-var execAsync2 = (0, import_util4.promisify)(import_child_process2.exec);
-var execFileAsync2 = (0, import_util4.promisify)(import_child_process2.execFile);
+var execAsync = (0, import_util4.promisify)(import_child_process2.exec);
+var execFileAsync3 = (0, import_util4.promisify)(import_child_process2.execFile);
 async function fetchTemplate(repoURL, ref, targetDir, config, logger) {
   if (!repoURL) {
     throw new Error("repoURL is required");
@@ -5529,13 +6058,13 @@ async function fetchTemplate(repoURL, ref, targetDir, config, logger) {
 Cloning repo: ${repoURL} \u2192 ${targetDir}
 `);
   try {
-    await execAsync2(`git clone --no-checkout --progress ${repoURL} ${targetDir}`, {
+    await execAsync(`git clone --no-checkout --progress ${repoURL} ${targetDir}`, {
       maxBuffer: 10 * 1024 * 1024
     });
-    await execFileAsync2("git", ["-C", targetDir, "checkout", "--quiet", ref], {
+    await execFileAsync3("git", ["-C", targetDir, "checkout", "--quiet", ref], {
       maxBuffer: 10 * 1024 * 1024
     });
-    await execFileAsync2(
+    await execFileAsync3(
       "git",
       ["-C", targetDir, "submodule", "update", "--init", "--recursive", "--progress"],
       { maxBuffer: 10 * 1024 * 1024 }
@@ -5580,14 +6109,14 @@ Cloning template: ${repoURL} \u2192 extracting ${subPath}
 }
 async function cloneSparse(repoURL, ref, subPath, tempDir) {
   try {
-    await execFileAsync2("git", ["init", tempDir]);
-    await execFileAsync2("git", ["-C", tempDir, "remote", "add", "origin", repoURL]);
-    await execFileAsync2("git", ["-C", tempDir, "config", "core.sparseCheckout", "true"]);
+    await execFileAsync3("git", ["init", tempDir]);
+    await execFileAsync3("git", ["-C", tempDir, "remote", "add", "origin", repoURL]);
+    await execFileAsync3("git", ["-C", tempDir, "config", "core.sparseCheckout", "true"]);
     const sparseCheckoutPath = path4.join(tempDir, ".git/info/sparse-checkout");
     fs5.writeFileSync(sparseCheckoutPath, `${subPath}
 `);
-    await execFileAsync2("git", ["-C", tempDir, "fetch", "origin", ref]);
-    await execFileAsync2("git", ["-C", tempDir, "checkout", ref]);
+    await execFileAsync3("git", ["-C", tempDir, "fetch", "origin", ref]);
+    await execFileAsync3("git", ["-C", tempDir, "checkout", ref]);
   } catch (error) {
     throw new Error(`Failed to clone sparse repository: ${error.message}`);
   }
@@ -6162,6 +6691,187 @@ function createAppModule(ctx) {
         imageRef: result.imageRef
       };
     },
+    // Granular deploy control
+    async prepareDeploy(opts) {
+      return prepareDeploy(
+        {
+          privateKey,
+          rpcUrl: ctx.rpcUrl,
+          environment: ctx.environment,
+          appName: opts.name,
+          instanceType: opts.instanceType,
+          dockerfilePath: opts.dockerfile,
+          envFilePath: opts.envFile,
+          imageRef: opts.imageRef,
+          logVisibility: opts.logVisibility,
+          resourceUsageMonitoring: opts.resourceUsageMonitoring,
+          skipTelemetry
+        },
+        logger
+      );
+    },
+    async prepareDeployFromVerifiableBuild(opts) {
+      return prepareDeployFromVerifiableBuild(
+        {
+          privateKey,
+          rpcUrl: ctx.rpcUrl,
+          environment: ctx.environment,
+          appName: opts.name,
+          instanceType: opts.instanceType,
+          envFilePath: opts.envFile,
+          imageRef: opts.imageRef,
+          imageDigest: opts.imageDigest,
+          logVisibility: opts.logVisibility,
+          resourceUsageMonitoring: opts.resourceUsageMonitoring,
+          skipTelemetry
+        },
+        logger
+      );
+    },
+    async executeDeploy(prepared, gas) {
+      const account = (0, import_accounts5.privateKeyToAccount)(privateKey);
+      const chain = getChainFromID(environment.chainID);
+      const publicClient = (0, import_viem9.createPublicClient)({
+        chain,
+        transport: (0, import_viem9.http)(ctx.rpcUrl)
+      });
+      const walletClient = (0, import_viem9.createWalletClient)({
+        account,
+        chain,
+        transport: (0, import_viem9.http)(ctx.rpcUrl)
+      });
+      const result = await executeDeploy({
+        prepared,
+        context: {
+          walletClient,
+          publicClient,
+          environmentConfig: environment
+        },
+        gas,
+        logger,
+        skipTelemetry
+      });
+      return {
+        appId: result.appId,
+        txHash: result.txHash,
+        appName: result.appName,
+        imageRef: result.imageRef
+      };
+    },
+    async watchDeployment(appId) {
+      return watchDeployment(
+        appId,
+        privateKey,
+        ctx.rpcUrl,
+        ctx.environment,
+        logger,
+        ctx.clientId,
+        skipTelemetry
+      );
+    },
+    // Granular upgrade control
+    async prepareUpgrade(appId, opts) {
+      return prepareUpgrade(
+        {
+          appId,
+          privateKey,
+          rpcUrl: ctx.rpcUrl,
+          environment: ctx.environment,
+          instanceType: opts.instanceType,
+          dockerfilePath: opts.dockerfile,
+          envFilePath: opts.envFile,
+          imageRef: opts.imageRef,
+          logVisibility: opts.logVisibility,
+          resourceUsageMonitoring: opts.resourceUsageMonitoring,
+          skipTelemetry
+        },
+        logger
+      );
+    },
+    async prepareUpgradeFromVerifiableBuild(appId, opts) {
+      return prepareUpgradeFromVerifiableBuild(
+        {
+          appId,
+          privateKey,
+          rpcUrl: ctx.rpcUrl,
+          environment: ctx.environment,
+          instanceType: opts.instanceType,
+          envFilePath: opts.envFile,
+          imageRef: opts.imageRef,
+          imageDigest: opts.imageDigest,
+          logVisibility: opts.logVisibility,
+          resourceUsageMonitoring: opts.resourceUsageMonitoring,
+          skipTelemetry
+        },
+        logger
+      );
+    },
+    async executeUpgrade(prepared, gas) {
+      const account = (0, import_accounts5.privateKeyToAccount)(privateKey);
+      const chain = getChainFromID(environment.chainID);
+      const publicClient = (0, import_viem9.createPublicClient)({
+        chain,
+        transport: (0, import_viem9.http)(ctx.rpcUrl)
+      });
+      const walletClient = (0, import_viem9.createWalletClient)({
+        account,
+        chain,
+        transport: (0, import_viem9.http)(ctx.rpcUrl)
+      });
+      const result = await executeUpgrade({
+        prepared,
+        context: {
+          walletClient,
+          publicClient,
+          environmentConfig: environment
+        },
+        gas,
+        logger,
+        skipTelemetry
+      });
+      return {
+        appId: result.appId,
+        txHash: result.txHash,
+        imageRef: result.imageRef
+      };
+    },
+    async watchUpgrade(appId) {
+      return watchUpgrade(
+        appId,
+        privateKey,
+        ctx.rpcUrl,
+        ctx.environment,
+        logger,
+        ctx.clientId,
+        skipTelemetry
+      );
+    },
+    // Profile management
+    async setProfile(appId, profile) {
+      return withSDKTelemetry(
+        {
+          functionName: "setProfile",
+          skipTelemetry,
+          properties: { environment: ctx.environment }
+        },
+        async () => {
+          const userApiClient = new UserApiClient(
+            environment,
+            privateKey,
+            ctx.rpcUrl,
+            ctx.clientId
+          );
+          return userApiClient.uploadAppProfile(
+            appId,
+            profile.name,
+            profile.website,
+            profile.description,
+            profile.xURL,
+            profile.imagePath
+          );
+        }
+      );
+    },
     async logs(opts) {
       return logs(
         {