@layr-labs/ecloud-sdk 0.0.1-rfc.1 → 0.1.0-dev.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Address, Hex } from 'viem';
+import { Address, Hex, WalletClient, PublicClient, PrivateKeyAccount } from 'viem';
 
 /**
  * Core types for ECloud SDK
@@ -7,24 +7,35 @@ import { Address, Hex } from 'viem';
 type AppId = Address;
 type logVisibility = "public" | "private" | "off";
 interface DeployAppOpts {
-    name?: string;
+    /** App name - required */
+    name: string;
+    /** Path to Dockerfile (if building from Dockerfile) - either this or imageRef is required */
     dockerfile?: string;
+    /** Path to .env file - optional */
     envFile?: string;
+    /** Image reference (registry/path:tag) - either this or dockerfile is required */
     imageRef?: string;
-    instanceType?: string;
-    logVisibility?: logVisibility;
+    /** Instance type SKU - required */
+    instanceType: string;
+    /** Log visibility setting - required */
+    logVisibility: logVisibility;
+    /** Optional gas params from estimation */
+    gas?: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
 }
 interface UpgradeAppOpts {
-    /** Path to Dockerfile (if building from Dockerfile) */
+    /** Path to Dockerfile (if building from Dockerfile) - either this or imageRef is required */
     dockerfile?: string;
-    /** Image reference (registry/path:tag) - optional, will prompt if not provided */
+    /** Image reference (registry/path:tag) - either this or dockerfile is required */
     imageRef?: string;
-    /** Path to .env file - optional, will use .env if exists or prompt */
+    /** Path to .env file - optional */
     envFile?: string;
-    /** Instance type - optional, will prompt if not provided */
-    instanceType?: string;
-    /** Log visibility setting - optional, will prompt if not provided */
-    logVisibility?: logVisibility;
+    /** Instance type SKU - required */
+    instanceType: string;
+    /** Log visibility setting - required */
+    logVisibility: logVisibility;
     gas?: {
         maxFeePerGas?: bigint;
         maxPriorityFeePerGas?: bigint;
@@ -35,7 +46,6 @@ interface LifecycleOpts {
         maxFeePerGas?: bigint;
         maxPriorityFeePerGas?: bigint;
     };
-    force?: boolean;
 }
 interface AppRecord {
     id: AppId;
@@ -67,7 +77,7 @@ interface DeployOptions {
 }
 interface DeployResult {
     /** App ID (contract address) */
-    appID: string;
+    appId: string;
     /** App name */
     appName: string;
     /** Final image reference */
@@ -209,8 +219,30 @@ interface BillingEnvironmentConfig {
  * Create command
  *
  * Creates a new app project from a template
+ *
+ * NOTE: This SDK function is non-interactive. All required parameters must be
+ * provided explicitly. Use the CLI for interactive parameter collection.
  */
 
+/**
+ * Required create app options for SDK (non-interactive)
+ */
+interface SDKCreateAppOpts {
+    /** Project name - required */
+    name: string;
+    /** Programming language - required (typescript, golang, rust, python) */
+    language: string;
+    /** Template name/category (e.g., "minimal") or custom template URL - optional, defaults to first available */
+    template?: string;
+    /** Template version/ref - optional */
+    templateVersion?: string;
+    /** Verbose output - optional */
+    verbose?: boolean;
+}
+/**
+ * Legacy interface for backward compatibility
+ * @deprecated Use SDKCreateAppOpts instead
+ */
 interface CreateAppOpts {
     name?: string;
     language?: string;
@@ -218,45 +250,102 @@ interface CreateAppOpts {
     templateVersion?: string;
     verbose?: boolean;
 }
+declare const PRIMARY_LANGUAGES: string[];
+/**
+ * Get available template categories for a language
+ */
+declare function getAvailableTemplates(language: string): Promise<Array<{
+    name: string;
+    description: string;
+}>>;
 /**
  * Create a new app project from template
+ *
+ * This function is non-interactive and requires all parameters to be provided explicitly.
+ *
+ * @param options - Required options including name and language
+ * @param logger - Optional logger instance
+ * @throws Error if required parameters are missing or invalid
  */
-declare function createApp(options: CreateAppOpts, logger?: Logger): Promise<void>;
+declare function createApp(options: SDKCreateAppOpts | CreateAppOpts, logger?: Logger): Promise<void>;
 
 /**
  * Logs command
  *
  * View app logs with optional watch mode
+ *
+ * NOTE: This SDK function is non-interactive. All required parameters must be
+ * provided explicitly. Use the CLI for interactive parameter collection.
  */
 
+/**
+ * Required logs options for SDK (non-interactive)
+ */
+interface SDKLogsOptions {
+    /** App ID (address) or app name - required */
+    appID: string | Address;
+    /** Watch logs continuously - optional */
+    watch?: boolean;
+    /** Environment name - optional, defaults to 'sepolia' */
+    environment?: string;
+    /** Private key for authenticated requests - optional */
+    privateKey?: string;
+    /** RPC URL - optional, uses environment default */
+    rpcUrl?: string;
+    /** Client ID for API requests - optional */
+    clientId?: string;
+}
+/**
+ * Legacy interface for backward compatibility
+ * @deprecated Use SDKLogsOptions instead
+ */
 interface LogsOptions {
     appID?: string | Address;
     watch?: boolean;
     environment?: string;
     privateKey?: string;
     rpcUrl?: string;
+    clientId?: string;
 }
 /**
  * View app logs
+ *
+ * This function is non-interactive and requires appID to be provided explicitly.
+ *
+ * @param options - Required options including appID
+ * @param logger - Optional logger instance
+ * @throws Error if appID is missing or invalid
  */
-declare function logs(options: LogsOptions, logger?: Logger): Promise<void>;
+declare function logs(options: SDKLogsOptions | LogsOptions, logger?: Logger): Promise<void>;
 
 /**
  * Main App namespace entry point
  */
 
+/**
+ * Encode start app call data for gas estimation
+ */
+declare function encodeStartAppData(appId: AppId): `0x${string}`;
+/**
+ * Encode stop app call data for gas estimation
+ */
+declare function encodeStopAppData(appId: AppId): `0x${string}`;
+/**
+ * Encode terminate app call data for gas estimation
+ */
+declare function encodeTerminateAppData(appId: AppId): `0x${string}`;
 interface AppModule {
     create: (opts: CreateAppOpts) => Promise<void>;
     deploy: (opts: DeployAppOpts) => Promise<{
-        appID: AppId;
+        appId: AppId;
         tx: `0x${string}`;
         appName: string;
         imageRef: string;
         ipAddress?: string;
     }>;
-    upgrade: (appID: AppId, opts: UpgradeAppOpts) => Promise<{
+    upgrade: (appId: AppId, opts: UpgradeAppOpts) => Promise<{
         tx: `0x${string}`;
-        appID: string;
+        appId: string;
         imageRef: string;
     }>;
     logs: (opts: LogsOptions) => Promise<void>;
@@ -269,12 +358,16 @@ interface AppModule {
     terminate: (appId: AppId, opts?: LifecycleOpts) => Promise<{
         tx: `0x${string}` | false;
     }>;
+    undelegate: () => Promise<{
+        tx: `0x${string}` | false;
+    }>;
 }
 interface AppModuleConfig {
     verbose?: boolean;
     privateKey: `0x${string}`;
     rpcUrl: string;
     environment: string;
+    clientId?: string;
 }
 declare function createAppModule(ctx: AppModuleConfig): AppModule;
 
@@ -294,85 +387,469 @@ interface BillingModuleConfig {
 declare function createBillingModule(config: BillingModuleConfig): BillingModule;
 
 /**
- * Interactive prompts using @inquirer/prompts
+ * Non-interactive validation utilities for SDK
+ *
+ * These functions validate parameters without any interactive prompts.
+ * They either return the validated value or throw an error.
  */
 
 /**
- * Prompt for Dockerfile selection
+ * Validate app name format
+ * @throws Error if name is invalid
  */
-declare function getDockerfileInteractive(dockerfilePath?: string): Promise<string>;
+declare function validateAppName(name: string): void;
 /**
- * Prompt for image reference
+ * Validate Docker image reference format
+ * @returns true if valid, error message string if invalid
  */
-declare function getImageReferenceInteractive(imageRef?: string, buildFromDockerfile?: boolean): Promise<string>;
+declare function validateImageReference(value: string): true | string;
 /**
- * Prompt for app name
+ * Validate image reference and throw if invalid
+ * @throws Error if image reference is invalid
  */
-declare function getOrPromptAppName(appName: string | undefined, environment: string, imageRef: string): Promise<string>;
+declare function assertValidImageReference(value: string): void;
 /**
- * Prompt for environment file
+ * Extract app name from image reference
  */
-declare function getEnvFileInteractive(envFilePath?: string): Promise<string>;
+declare function extractAppNameFromImage(imageRef: string): string;
+/**
+ * Validate that a file path exists
+ * @returns true if valid, error message string if invalid
+ */
+declare function validateFilePath(value: string): true | string;
+/**
+ * Validate file path and throw if invalid
+ * @throws Error if file path is invalid or doesn't exist
+ */
+declare function assertValidFilePath(value: string): void;
 /**
- * Prompt for instance type
+ * Validate instance type SKU against available types
+ * @returns the validated SKU
+ * @throws Error if SKU is not in the available types list
  */
-declare function getInstanceTypeInteractive(instanceType: string | undefined, defaultSKU: string, availableTypes: Array<{
+declare function validateInstanceTypeSKU(sku: string, availableTypes: Array<{
     sku: string;
-    description: string;
-}>): Promise<string>;
+}>): string;
 /**
- * Prompt for app ID (supports app name or address)
+ * Validate private key format
+ * Matches Go's common.ValidatePrivateKey() function
  */
-interface GetAppIDOptions {
-    appID?: string | Address;
-    environment: string;
-    privateKey?: string;
-    rpcUrl?: string;
-    action?: string;
-}
+declare function validatePrivateKeyFormat(key: string): boolean;
+/**
+ * Validate private key and throw if invalid
+ * @throws Error if private key format is invalid
+ */
+declare function assertValidPrivateKey(key: string): void;
+/**
+ * Validate URL format
+ * @returns undefined if valid, error message string if invalid
+ */
+declare function validateURL(rawURL: string): string | undefined;
+/**
+ * Validate X/Twitter URL format
+ * @returns undefined if valid, error message string if invalid
+ */
+declare function validateXURL(rawURL: string): string | undefined;
 /**
- * Prompt for app ID (supports app name or address)
+ * Validate description length
+ * @returns undefined if valid, error message string if invalid
  */
-declare function getOrPromptAppID(appIDOrOptions: string | Address | GetAppIDOptions | undefined, environment?: string): Promise<Address>;
+declare function validateDescription(description: string): string | undefined;
 /**
- * Prompt for log settings
+ * Validate image file path
+ * @returns undefined if valid, error message string if invalid
  */
-declare function getLogSettingsInteractive(logVisibility?: "public" | "private" | "off"): Promise<{
+declare function validateImagePath(filePath: string): string | undefined;
+/**
+ * Validate and normalize app ID address
+ * @param appID - App ID (must be a valid address)
+ * @returns Normalized app address
+ * @throws Error if app ID is not a valid address
+ *
+ * Note: Name resolution should be handled by CLI before calling SDK functions.
+ * The SDK only accepts resolved addresses.
+ */
+declare function validateAppID(appID: string | Address): Address;
+type LogVisibility = "public" | "private" | "off";
+/**
+ * Validate and convert log visibility setting to internal format
+ * @param logVisibility - Log visibility setting
+ * @returns Object with logRedirect and publicLogs settings
+ * @throws Error if log visibility value is invalid
+ */
+declare function validateLogVisibility(logVisibility: LogVisibility): {
     logRedirect: string;
     publicLogs: boolean;
+};
+type ResourceUsageMonitoring = "enable" | "disable";
+/**
+ * Validate and convert resource usage monitoring setting to internal format
+ * @param resourceUsageMonitoring - Resource usage monitoring setting
+ * @returns The resourceUsageAllow value for the Dockerfile label ("always" or "never")
+ * @throws Error if resource usage monitoring value is invalid
+ */
+declare function validateResourceUsageMonitoring(resourceUsageMonitoring: ResourceUsageMonitoring | undefined): string;
+/**
+ * Sanitize string (HTML escape and trim)
+ */
+declare function sanitizeString(s: string): string;
+/**
+ * Sanitize URL (add https:// if missing, validate)
+ * @throws Error if URL is invalid after sanitization
+ */
+declare function sanitizeURL(rawURL: string): string;
+/**
+ * Sanitize X/Twitter URL (handle username-only input, normalize)
+ * @throws Error if URL is invalid after sanitization
+ */
+declare function sanitizeXURL(rawURL: string): string;
+interface DeployParams {
+    dockerfilePath?: string;
+    imageRef?: string;
+    appName: string;
+    envFilePath?: string;
+    instanceType: string;
+    logVisibility: LogVisibility;
+}
+/**
+ * Validate deploy parameters
+ * @throws Error if required parameters are missing or invalid
+ */
+declare function validateDeployParams(params: Partial<DeployParams>): void;
+interface UpgradeParams {
+    appID: string | Address;
+    dockerfilePath?: string;
+    imageRef?: string;
+    envFilePath?: string;
+    instanceType: string;
+    logVisibility: LogVisibility;
+}
+/**
+ * Validate upgrade parameters
+ * @throws Error if required parameters are missing or invalid
+ */
+declare function validateUpgradeParams(params: Partial<UpgradeParams>): void;
+interface CreateAppParams {
+    name: string;
+    language: string;
+    template?: string;
+    templateVersion?: string;
+}
+/**
+ * Validate create app parameters
+ * @throws Error if required parameters are missing or invalid
+ */
+declare function validateCreateAppParams(params: Partial<CreateAppParams>): void;
+interface LogsParams {
+    appID: string | Address;
+    watch?: boolean;
+}
+/**
+ * Validate logs parameters
+ * @throws Error if required parameters are missing or invalid
+ */
+declare function validateLogsParams(params: Partial<LogsParams>): void;
+
+/**
+ * Contract interactions
+ *
+ * This module handles on-chain contract interactions using viem
+ */
+
+/**
+ * Gas estimation result
+ */
+interface GasEstimate {
+    /** Estimated gas limit for the transaction */
+    gasLimit: bigint;
+    /** Max fee per gas (EIP-1559) */
+    maxFeePerGas: bigint;
+    /** Max priority fee per gas (EIP-1559) */
+    maxPriorityFeePerGas: bigint;
+    /** Maximum cost in wei (gasLimit * maxFeePerGas) */
+    maxCostWei: bigint;
+    /** Maximum cost formatted as ETH string */
+    maxCostEth: string;
+}
+/**
+ * Options for estimating transaction gas
+ */
+interface EstimateGasOptions {
+    privateKey: string;
+    rpcUrl: string;
+    environmentConfig: EnvironmentConfig;
+    to: Address;
+    data: Hex;
+    value?: bigint;
+}
+/**
+ * Format Wei to ETH string
+ */
+declare function formatETH(wei: bigint): string;
+/**
+ * Estimate gas cost for a transaction
+ *
+ * Use this to get cost estimate before prompting user for confirmation.
+ */
+declare function estimateTransactionGas(options: EstimateGasOptions): Promise<GasEstimate>;
+/**
+ * Prepared deploy batch ready for gas estimation and execution
+ */
+interface PreparedDeployBatch {
+    /** The app ID that will be deployed */
+    appId: Address;
+    /** The salt used for deployment */
+    salt: Uint8Array;
+    /** Batch executions to be sent */
+    executions: Array<{
+        target: Address;
+        value: bigint;
+        callData: Hex;
+    }>;
+    /** Wallet client for sending transaction */
+    walletClient: WalletClient;
+    /** Public client for reading chain state */
+    publicClient: PublicClient;
+    /** Environment configuration */
+    environmentConfig: EnvironmentConfig;
+}
+/**
+ * Prepared upgrade batch ready for gas estimation and execution
+ */
+interface PreparedUpgradeBatch {
+    /** The app ID being upgraded */
+    appId: Address;
+    /** Batch executions to be sent */
+    executions: Array<{
+        target: Address;
+        value: bigint;
+        callData: Hex;
+    }>;
+    /** Wallet client for sending transaction */
+    walletClient: WalletClient;
+    /** Public client for reading chain state */
+    publicClient: PublicClient;
+    /** Environment configuration */
+    environmentConfig: EnvironmentConfig;
+}
+/**
+ * Get apps by creator (paginated)
+ */
+interface AppConfig {
+    release: any;
+    status: number;
+}
+/**
+ * Fetch all apps by a developer by auto-pagination
+ */
+declare function getAllAppsByDeveloper(rpcUrl: string, env: EnvironmentConfig, developer: Address, pageSize?: bigint): Promise<{
+    apps: Address[];
+    appConfigs: AppConfig[];
 }>;
-declare function extractAppNameFromImage(imageRef: string): string;
 /**
- * Confirm prompts the user to confirm an action with a yes/no question.
+ * Get latest release block numbers for multiple apps
  */
-declare function confirm(prompt: string): Promise<boolean>;
+declare function getAppLatestReleaseBlockNumbers(rpcUrl: string, environmentConfig: EnvironmentConfig, appIDs: Address[]): Promise<Map<Address, number>>;
 /**
- * ConfirmWithDefault prompts the user to confirm an action with a yes/no question and a default value.
+ * Get block timestamps for multiple block numbers
  */
-declare function confirmWithDefault(prompt: string, defaultValue?: boolean): Promise<boolean>;
+declare function getBlockTimestamps(rpcUrl: string, environmentConfig: EnvironmentConfig, blockNumbers: number[]): Promise<Map<number, number>>;
+
 /**
- * Prompt for RPC URL
- * Matches Go's getRPCURL() behavior with interactive prompt
+ * Main deploy function
+ *
+ * This is the main entry point for deploying applications to ecloud TEE.
+ * It orchestrates all the steps: build, push, encrypt, and deploy on-chain.
+ *
+ * NOTE: This SDK function is non-interactive. All required parameters must be
+ * provided explicitly. Use the CLI for interactive parameter collection.
  */
-declare function getRPCUrlInteractive(rpcUrl?: string, defaultRpcUrl?: string): Promise<string>;
+
 /**
- * Prompt for environment selection
- * Matches Go's GetEnvironmentConfig() behavior with interactive prompt
+ * Required deploy options for SDK (non-interactive)
  */
-declare function getEnvironmentInteractive(environment?: string): Promise<string>;
+interface SDKDeployOptions {
+    /** Private key for signing transactions (hex string with or without 0x prefix) */
+    privateKey: string;
+    /** RPC URL for blockchain connection - optional, uses environment default if not provided */
+    rpcUrl?: string;
+    /** Environment name (e.g., 'sepolia', 'mainnet-alpha') - defaults to 'sepolia' */
+    environment?: string;
+    /** Path to Dockerfile (if building from Dockerfile) - either this or imageRef is required */
+    dockerfilePath?: string;
+    /** Image reference (registry/path:tag) - either this or dockerfilePath is required */
+    imageRef?: string;
+    /** Path to .env file - optional */
+    envFilePath?: string;
+    /** App name - required */
+    appName: string;
+    /** Instance type SKU - required */
+    instanceType: string;
+    /** Log visibility setting - required */
+    logVisibility: LogVisibility;
+    /** Resource usage monitoring setting - optional, defaults to 'enable' */
+    resourceUsageMonitoring?: ResourceUsageMonitoring;
+    /** Optional gas params from estimation */
+    gas?: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+}
 /**
- * Prompt for private key with hidden input
- * Matches Go's output.InputHiddenString() function
+ * Prepared deployment ready for gas estimation and execution
+ */
+interface PreparedDeploy {
+    /** The prepared batch (executions, clients, etc.) */
+    batch: PreparedDeployBatch;
+    /** App name */
+    appName: string;
+    /** Final image reference */
+    imageRef: string;
+    /** Preflight context for post-deploy operations */
+    preflightCtx: {
+        privateKey: string;
+        rpcUrl: string;
+        environmentConfig: EnvironmentConfig;
+    };
+}
+/**
+ * Result from prepareDeploy - includes prepared batch and gas estimate
+ */
+interface PrepareDeployResult {
+    /** Prepared deployment state */
+    prepared: PreparedDeploy;
+    /** Gas estimate for the batch transaction */
+    gasEstimate: GasEstimate;
+}
+/**
+ * Prepare deployment - does all work up to the transaction
+ *
+ * This allows CLI to:
+ * 1. Call prepareDeploy to build image, prepare release, get gas estimate
+ * 2. Prompt user to confirm the cost
+ * 3. Call executeDeploy with confirmed gas params
+ */
+declare function prepareDeploy(options: Omit<SDKDeployOptions, "gas">, logger?: Logger): Promise<PrepareDeployResult>;
+/**
+ * Execute a prepared deployment
+ *
+ * Call this after prepareDeploy and user confirmation.
+ * Note: This only submits the on-chain transaction. Call watchDeployment separately
+ * to wait for the app to be running.
+ */
+declare function executeDeploy(prepared: PreparedDeploy, gas: {
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+} | undefined, logger?: Logger): Promise<DeployResult>;
+/**
+ * Watch a deployment until the app is running
+ *
+ * Call this after executeDeploy to wait for the app to be provisioned.
+ * Can be called separately to allow for intermediate operations (e.g., profile upload).
  */
-declare function getPrivateKeyInteractive(privateKey?: string): Promise<string>;
+declare function watchDeployment(appId: string, privateKey: string, rpcUrl: string, environment: string, logger?: Logger, clientId?: string): Promise<string | undefined>;
 
 /**
- * Collect app profile information interactively
- * If defaultName is provided, it will be used as the suggested name
- * If allowRetry is true, user can re-enter information on rejection (deploy flow)
- * If allowRetry is false, rejection returns an error (profile set flow)
+ * Main upgrade function
+ *
+ * This is the main entry point for upgrading existing applications on ecloud TEE.
+ * It orchestrates all the steps: build, push, encrypt, and upgrade on-chain.
+ *
+ * NOTE: This SDK function is non-interactive. All required parameters must be
+ * provided explicitly. Use the CLI for interactive parameter collection.
  */
-declare function getAppProfileInteractive(defaultName?: string, allowRetry?: boolean): Promise<AppProfile | null>;
+
+/**
+ * Required upgrade options for SDK (non-interactive)
+ */
+interface SDKUpgradeOptions {
+    /** App ID to upgrade - required */
+    appId: string | Address;
+    /** Private key for signing transactions (hex string with or without 0x prefix) */
+    privateKey: string;
+    /** RPC URL for blockchain connection - optional, uses environment default if not provided */
+    rpcUrl?: string;
+    /** Environment name (e.g., 'sepolia', 'mainnet-alpha') - defaults to 'sepolia' */
+    environment?: string;
+    /** Path to Dockerfile (if building from Dockerfile) - either this or imageRef is required */
+    dockerfilePath?: string;
+    /** Image reference (registry/path:tag) - either this or dockerfilePath is required */
+    imageRef?: string;
+    /** Path to .env file - optional */
+    envFilePath?: string;
+    /** Instance type SKU - required */
+    instanceType: string;
+    /** Log visibility setting - required */
+    logVisibility: LogVisibility;
+    /** Resource usage monitoring setting - optional, defaults to 'enable' */
+    resourceUsageMonitoring?: ResourceUsageMonitoring;
+    /** Optional gas params from estimation */
+    gas?: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+}
+interface UpgradeResult {
+    /** App ID (contract address) */
+    appId: string;
+    /** Final image reference */
+    imageRef: string;
+    /** Transaction hash */
+    txHash: `0x${string}`;
+}
+/**
+ * Prepared upgrade ready for gas estimation and execution
+ */
+interface PreparedUpgrade {
+    /** The prepared batch (executions, clients, etc.) */
+    batch: PreparedUpgradeBatch;
+    /** App ID being upgraded */
+    appId: string;
+    /** Final image reference */
+    imageRef: string;
+    /** Preflight context for post-upgrade operations */
+    preflightCtx: {
+        privateKey: string;
+        rpcUrl: string;
+        environmentConfig: EnvironmentConfig;
+    };
+}
+/**
+ * Result from prepareUpgrade - includes prepared batch and gas estimate
+ */
+interface PrepareUpgradeResult {
+    /** Prepared upgrade state */
+    prepared: PreparedUpgrade;
+    /** Gas estimate for the batch transaction */
+    gasEstimate: GasEstimate;
+}
+/**
+ * Prepare upgrade - does all work up to the transaction
+ *
+ * This allows CLI to:
+ * 1. Call prepareUpgrade to build image, prepare release, get gas estimate
+ * 2. Prompt user to confirm the cost
+ * 3. Call executeUpgrade with confirmed gas params
+ */
+declare function prepareUpgrade(options: Omit<SDKUpgradeOptions, "gas">, logger?: Logger): Promise<PrepareUpgradeResult>;
+/**
+ * Execute a prepared upgrade
+ *
+ * Call this after prepareUpgrade and user confirmation.
+ * Note: This only submits the on-chain transaction. Call watchUpgrade separately
+ * to wait for the upgrade to complete.
+ */
+declare function executeUpgrade(prepared: PreparedUpgrade, gas: {
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+} | undefined, logger?: Logger): Promise<UpgradeResult>;
+/**
+ * Watch an upgrade until it completes
+ *
+ * Call this after executeUpgrade to wait for the upgrade to finish.
+ * Can be called separately to allow for intermediate operations.
+ */
+declare function watchUpgrade(appId: string, privateKey: string, rpcUrl: string, environment: string, logger?: Logger, clientId?: string): Promise<void>;
 
 /**
  * Environment configuration for different networks
@@ -382,6 +859,7 @@ declare function getAppProfileInteractive(defaultName?: string, allowRetry?: boo
  * Get environment configuration
  */
 declare function getEnvironmentConfig(environment: string, chainID?: bigint): EnvironmentConfig;
+declare function getBuildType(): "dev" | "prod";
 /**
  * Get available environments based on build type
  * - dev: only "sepolia-dev"
@@ -392,6 +870,10 @@ declare function getAvailableEnvironments(): string[];
  * Check if an environment is available in the current build
  */
 declare function isEnvironmentAvailable(environment: string): boolean;
+/**
+ * Check if environment is mainnet (chain ID 1)
+ */
+declare function isMainnet(environmentConfig: EnvironmentConfig): boolean;
 
 /**
  * Billing utility functions
@@ -433,7 +915,7 @@ declare function storePrivateKey(privateKey: string): Promise<void>;
  * Note: Returns the single stored key for all environments.
  * The environment parameter is kept for API compatibility but is ignored.
  */
-declare function getPrivateKey(): Promise<string | null>;
+declare function getPrivateKey(): Promise<`0x${string}` | null>;
 /**
  * Delete a private key from OS keyring
  * Returns true if deletion was successful, false otherwise
@@ -486,7 +968,7 @@ declare function getAddressFromPrivateKey(privateKey: string): string;
  * 3. OS keyring (stored via `ecloud auth login`)
  */
 interface PrivateKeySource {
-    key: string;
+    key: `0x${string}`;
     source: string;
 }
 /**
@@ -510,41 +992,176 @@ declare function requirePrivateKey(options: {
 }): Promise<PrivateKeySource>;
 
 /**
- * Security Utilities
+ * Private Key Generation
  *
- * Provides secure display and input handling for sensitive data like private keys
+ * Generate new secp256k1 private keys for Ethereum
+ */
+interface GeneratedKey {
+    privateKey: string;
+    address: string;
+}
+/**
+ * Generate a new secp256k1 private key
  */
+declare function generateNewPrivateKey(): GeneratedKey;
+
 /**
- * Display sensitive content using system pager (less/more)
- * Returns true if content was displayed, false if user aborted
+ * TemplateEntry represents a single template in the catalog
  */
-declare function showPrivateKey(content: string): Promise<boolean>;
+interface TemplateEntry {
+    path: string;
+    description: string;
+    postProcess?: {
+        replaceNameIn?: string[];
+    };
+}
 /**
- * Clear terminal screen
+ * TemplateCatalog represents the structure of templates.json
+ * Organized by language first, then by category (e.g., "typescript" -> "minimal")
  */
-declare function clearTerminal(): void;
+interface TemplateCatalog {
+    [language: string]: {
+        [category: string]: TemplateEntry;
+    };
+}
 /**
- * Get hidden input (password-style)
+ * Fetch template catalog from remote URL or local file
+ * Uses a 15-minute in-memory cache to avoid excessive network requests
  */
-declare function getHiddenInput(message: string): Promise<string>;
+declare function fetchTemplateCatalog(): Promise<TemplateCatalog>;
 /**
- * Display multi-line warning for destructive operations
+ * Get template entry by language and category
  */
-declare function displayWarning(lines: string[]): void;
+declare function getTemplate(catalog: TemplateCatalog, category: string, language: string): TemplateEntry;
+/**
+ * Get category descriptions for a given language
+ */
+declare function getCategoryDescriptions(catalog: TemplateCatalog, language: string): Record<string, string>;
 
 /**
- * Private Key Generation
+ * EIP-7702 transaction handling
  *
- * Generate new secp256k1 private keys for Ethereum
+ * This module handles EIP-7702 delegation and batch execution
  */
-interface GeneratedKey {
+
+/**
+ * Options for estimating batch gas
+ */
+interface EstimateBatchGasOptions {
+    publicClient: PublicClient;
+    environmentConfig: EnvironmentConfig;
+    executions: Array<{
+        target: Address;
+        value: bigint;
+        callData: Hex;
+    }>;
+}
+/**
+ * Estimate gas cost for a batch transaction
+ *
+ * Use this to get cost estimate before prompting user for confirmation.
+ * Note: This provides a conservative estimate since batch transactions
+ * through EIP-7702 can have variable costs.
+ */
+declare function estimateBatchGas(options: EstimateBatchGasOptions): Promise<GasEstimate>;
+
+/**
+ * Preflight checks
+ */
+
+interface PreflightContext {
     privateKey: string;
-    address: string;
+    rpcUrl: string;
+    environmentConfig: EnvironmentConfig;
+    account: PrivateKeyAccount;
+    selfAddress: Address;
 }
+
 /**
- * Generate a new secp256k1 private key
+ * Instance type utilities
  */
-declare function generateNewPrivateKey(): GeneratedKey;
+
+/**
+ * Get current instance type for an app (best-effort)
+ * Returns empty string if unable to fetch (API unavailable, app info not ready, etc.).
+ * This is used as a convenience default for the upgrade flow.
+ */
+declare function getCurrentInstanceType(preflightCtx: PreflightContext, appID: Address, logger: Logger, clientId?: string): Promise<string>;
+
+/**
+ * UserAPI Client to manage interactions with the coordinator
+ */
+
+interface AppProfileInfo {
+    name: string;
+    website?: string;
+    description?: string;
+    xURL?: string;
+    imageURL?: string;
+}
+interface AppMetrics {
+    cpu_utilization_percent?: number;
+    memory_utilization_percent?: number;
+    memory_used_bytes?: number;
+    memory_total_bytes?: number;
+}
+interface DerivedAddress {
+    address: string;
+    derivationPath: string;
+}
+interface AppInfo {
+    address: Address;
+    status: string;
+    ip: string;
+    machineType: string;
+    profile?: AppProfileInfo;
+    metrics?: AppMetrics;
+    evmAddresses: DerivedAddress[];
+    solanaAddresses: DerivedAddress[];
+}
+declare class UserApiClient {
+    private readonly config;
+    private readonly account?;
+    private readonly rpcUrl?;
+    private readonly clientId;
+    constructor(config: EnvironmentConfig, privateKey?: string | Hex, rpcUrl?: string, clientId?: string);
+    getInfos(appIDs: Address[], addressCount?: number): Promise<AppInfo[]>;
+    /**
+     * Get available SKUs (instance types) from UserAPI
+     */
+    getSKUs(): Promise<{
+        skus: Array<{
+            sku: string;
+            description: string;
+        }>;
+    }>;
+    /**
+     * Get logs for an app
+     */
+    getLogs(appID: Address): Promise<string>;
+    /**
+     * Get statuses for apps
+     */
+    getStatuses(appIDs: Address[]): Promise<Array<{
+        address: Address;
+        status: string;
+    }>>;
+    /**
+     * Upload app profile information with optional image
+     */
+    uploadAppProfile(appAddress: Address, name: string, website?: string, description?: string, xURL?: string, imagePath?: string): Promise<{
+        name: string;
+        website?: string;
+        description?: string;
+        xURL?: string;
+        imageURL?: string;
+    }>;
+    private makeAuthenticatedRequest;
+    /**
+     * Generate authentication headers for UserAPI requests
+     */
+    private generateAuthHeaders;
+}
 
 /**
  * Main SDK Client entry point
@@ -563,4 +1180,4 @@ interface ECloudClient {
 }
 declare function createECloudClient(cfg: ClientConfig): ECloudClient;
 
-export { type AlreadyActiveResponse, type AppId, type AppModuleConfig, type AppProfile, type AppProfileResponse, type AppRecord, type BillingEnvironmentConfig, type BillingModuleConfig, type CancelResponse, type CancelSuccessResponse, type ChainID, type CheckoutCreatedResponse, type ClientConfig, type CreateAppOpts, type CreateSubscriptionResponse, type DeployAppOpts, type DeployOptions, type DeployResult, type DockerImageConfig, type ECloudClient, type Environment, type EnvironmentConfig, type GeneratedKey, type GetAppIDOptions, type ImageDigestResult, type LegacyKey, type LifecycleOpts, type Logger, type LogsOptions, type NoActiveSubscriptionResponse, type ParsedEnvironment, type PaymentIssueResponse, type PrivateKeySource, type ProductID, type ProductSubscriptionResponse, type Release, type StoredKey, type SubscribeResponse, type SubscriptionLineItem, type SubscriptionOpts, type SubscriptionStatus, type UpgradeAppOpts, clearTerminal, confirm, confirmWithDefault, createApp, createAppModule, createBillingModule, createECloudClient, deleteLegacyPrivateKey, deletePrivateKey, displayWarning, extractAppNameFromImage, generateNewPrivateKey, getAddressFromPrivateKey, getAppProfileInteractive, getAvailableEnvironments, getDockerfileInteractive, getEnvFileInteractive, getEnvironmentConfig, getEnvironmentInteractive, getHiddenInput, getImageReferenceInteractive, getInstanceTypeInteractive, getLegacyKeys, getLegacyPrivateKey, getLogSettingsInteractive, getOrPromptAppID, getOrPromptAppName, getPrivateKey, getPrivateKeyInteractive, getPrivateKeyWithSource, getRPCUrlInteractive, isEnvironmentAvailable, isSubscriptionActive, keyExists, listStoredKeys, type logVisibility, logs, requirePrivateKey, showPrivateKey, storePrivateKey, validatePrivateKey };
+export { type AlreadyActiveResponse, type AppId, type AppInfo, type AppMetrics, type AppModuleConfig, type AppProfile, type AppProfileInfo, type AppProfileResponse, type AppRecord, type BillingEnvironmentConfig, type BillingModuleConfig, type CancelResponse, type CancelSuccessResponse, type ChainID, type CheckoutCreatedResponse, type ClientConfig, type CreateAppOpts, type CreateAppParams, type CreateSubscriptionResponse, type DeployAppOpts, type DeployOptions, type DeployParams, type DeployResult, type DockerImageConfig, type ECloudClient, type Environment, type EnvironmentConfig, type EstimateBatchGasOptions, type EstimateGasOptions, type GasEstimate, type GeneratedKey, type ImageDigestResult, type LegacyKey, type LifecycleOpts, type LogVisibility, type Logger, type LogsOptions, type LogsParams, type NoActiveSubscriptionResponse, PRIMARY_LANGUAGES, type ParsedEnvironment, type PaymentIssueResponse, type PrepareDeployResult, type PrepareUpgradeResult, type PreparedDeploy, type PreparedUpgrade, type PrivateKeySource, type ProductID, type ProductSubscriptionResponse, type Release, type ResourceUsageMonitoring, type SDKCreateAppOpts, type SDKDeployOptions, type SDKLogsOptions, type SDKUpgradeOptions, type StoredKey, type SubscribeResponse, type SubscriptionLineItem, type SubscriptionOpts, type SubscriptionStatus, type UpgradeAppOpts, type UpgradeParams, UserApiClient, assertValidFilePath, assertValidImageReference, assertValidPrivateKey, createApp, createAppModule, createBillingModule, createECloudClient, deleteLegacyPrivateKey, deletePrivateKey, encodeStartAppData, encodeStopAppData, encodeTerminateAppData, estimateBatchGas, estimateTransactionGas, executeDeploy, executeUpgrade, extractAppNameFromImage, fetchTemplateCatalog, formatETH, generateNewPrivateKey, getAddressFromPrivateKey, getAllAppsByDeveloper, getAppLatestReleaseBlockNumbers, getAvailableEnvironments, getAvailableTemplates, getBlockTimestamps, getBuildType, getCategoryDescriptions, getCurrentInstanceType, getEnvironmentConfig, getLegacyKeys, getLegacyPrivateKey, getPrivateKey, getPrivateKeyWithSource, getTemplate, isEnvironmentAvailable, isMainnet, isSubscriptionActive, keyExists, listStoredKeys, type logVisibility, logs, prepareDeploy, prepareUpgrade, requirePrivateKey, sanitizeString, sanitizeURL, sanitizeXURL, storePrivateKey, validateAppID, validateAppName, validateCreateAppParams, validateDeployParams, validateDescription, validateFilePath, validateImagePath, validateImageReference, validateInstanceTypeSKU, validateLogVisibility, validateLogsParams, validatePrivateKey, validatePrivateKeyFormat, validateResourceUsageMonitoring, validateURL, validateUpgradeParams, validateXURL, watchDeployment, watchUpgrade };