movehat 0.2.8 → 0.3.0

package/README.md

@@ -21,6 +21,8 @@
 - **Hardhat-style Harness API** — `Harness.createLocal`, `createFork`, `createLive` factory methods with explicit lifecycle (`cleanup()`) and use-after-cleanup safety (Proxy poisoning).
 - **Three execution modes** — full local blockchain, read-only fork of a remote network, or live testnet/mainnet binding.
 - **Auto-deploy in tests + auto-detect named addresses** — contracts compile and deploy automatically; no manual address wiring.
+- **Fast local boot with movelite** — on supported platforms an auto-installed [movelite](https://github.com/gilbertsahumada/movelite) binary boots the local test chain in under a second instead of ~15s, with transparent fallback to the full Movement node.
+- **Foundry-style execution traces** — raise verbosity (`-vv` … `-vvvv`) to render an indented call tree for each `contract.call(...)` with decoded arguments, gas, events, and the abort stack (movelite backend).
 - **Native fork system** — local JSON-backed snapshots of Movement L1 state, no BCS compatibility issues.
 - **TypeScript-first** — single `PRIVATE_KEY` across all networks (Hardhat-style); deployments tracked per-network in `deployments/`.
 - **SLSA-provenance releases** — every npm release ships with [Trusted Publishers](https://docs.npmjs.com/trusted-publishers) provenance. Verify with `npm view movehat@<version>`.

package/dist/cli.js

@@ -44,7 +44,7 @@ program
     .version(version)
     .option('--network <name>', 'Network to use (testnet, mainnet, local, etc.)')
     .option('--redeploy', 'Force redeploy even if already deployed')
-    .option('-v, --verbose', 'Show subprocess output (movement node, aptos move) for debugging')
+    .option('-v, --verbose', 'Increase output verbosity (repeatable: -v subprocess output, -vv..-vvvv transaction traces on movelite)', (_value, previous) => previous + 1, 0)
     .hook('preAction', (thisCommand) => {
     // Store network option in environment for commands to access
     const options = thisCommand.opts();
@@ -54,8 +54,13 @@ program
     if (options.redeploy) {
         process.env.MH_CLI_REDEPLOY = 'true';
     }
-    if (options.verbose) {
+    // `-v` is counted (0..4). Level >= 1 keeps the legacy MOVEHAT_VERBOSE=1
+    // contract (isVerbose + its callers); MOVEHAT_VERBOSITY carries the
+    // numeric level across the spawned test/script subprocess boundary.
+    const level = options.verbose ?? 0;
+    if (level >= 1) {
         process.env.MOVEHAT_VERBOSE = '1';
+        process.env.MOVEHAT_VERBOSITY = String(level);
     }
 });
 program

package/dist/core/Publisher.d.ts

@@ -1,4 +1,4 @@
-import { Account } from "@aptos-labs/ts-sdk";
+import { Account, Aptos } from "@aptos-labs/ts-sdk";
 import { MovehatConfig } from "../types/config.js";
 import { DeploymentInfo } from "./deployments.js";
 import type { ChildProcessAdapter } from "../utils/childProcessAdapter.js";
@@ -12,6 +12,13 @@ export interface PublishInput {
     config: MovehatConfig;
     account: Account;
     packageDir?: string | undefined;
+    /**
+     * Publish via the TypeScript SDK instead of the Movement CLI. Set when the
+     * backend is movelite, whose REST responses the Movement CLI cannot parse.
+     * Requires `aptos`.
+     */
+    sdkPublish?: boolean | undefined;
+    aptos?: Aptos | undefined;
 }
 /**
  * Publishes a Move module via the Movement CLI.
@@ -22,4 +29,16 @@ export declare class Publisher {
     private readonly deps;
     constructor(deps?: PublisherDeps);
     deploy(input: PublishInput): Promise<DeploymentInfo>;
+    /**
+     * Publish via the Movement CLI (`movement move publish`). The default path
+     * for real Movement nodes, forks, and testnet. Returns the parsed tx hash.
+     */
+    private publishViaCli;
+    /**
+     * Publish the already-built package via the TypeScript SDK. Used when the
+     * backend is movelite. Reads the compiled artifacts the CLI build produced
+     * under `<dir>/build/<pkg>/`, submits a `0x1::code::publish_package_txn`,
+     * and waits for it. Returns the on-chain tx hash.
+     */
+    private publishViaSdk;
 }

package/dist/core/Publisher.js

@@ -1,4 +1,6 @@
 import { PrivateKey, PrivateKeyVariants } from "@aptos-labs/ts-sdk";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
 import { extractNamedAddresses } from "../commands/compile.js";
 import { saveDeployment, loadDeployment, validateSafeName, } from "./deployments.js";
 import { validatePathSafety } from "./shell.js";
@@ -74,103 +76,34 @@ export class Publisher {
                         .join(","),
                 ]
                 : [];
+            // The SDK publish path reads package-metadata.bcs from the build
+            // output; `--save-metadata` makes the build emit it. The CLI path
+            // doesn't need it (`move publish` rebuilds metadata internally).
+            const saveMetadataArgs = input.sdkPublish ? ["--save-metadata"] : [];
             // Build first with named addresses
             const buildResult = await withSpinner("Building package", () => runCli({
                 command: "movement",
-                args: ["move", "build", "--package-dir", safeDir, ...namedAddrArgs],
+                args: [
+                    "move",
+                    "build",
+                    "--package-dir",
+                    safeDir,
+                    ...namedAddrArgs,
+                    ...saveMetadataArgs,
+                ],
                 timeoutMs: 120000, // 2 minutes for git dependency downloads
             }, { adapter: this.deps.adapter }));
             if (isVerbose() && buildResult.stdout) {
                 logger.info(buildResult.stdout.trim(), 2);
             }
-            // Publish using direct parameters (avoid config file issues)
-            // Format the private key into AIP-80 shape so the Movement CLI
-            // doesn't emit its raw-hex deprecation warning. `formatPrivateKey`
-            // is idempotent for already-prefixed inputs.
-            const formattedPrivateKey = PrivateKey.formatPrivateKey(config.privateKey, PrivateKeyVariants.Ed25519);
-            // Move.toml is NOT mutated. All address overrides flow through
-            // the `--named-addresses` flag above, which Movement CLI applies
-            // during build + publish. Rewriting Move.toml on disk would risk
-            // leaving the user's file mutated if the process died before the
-            // restore step.
-            let publishOut = "";
-            let publishErr = "";
-            // Pass the private key to Movement CLI via a 0o600 temp file
-            // (`--private-key-file <path>`) and the on-chain address via
-            // `--sender-account <addr>`. This avoids the CLI's profile-yaml
-            // lookup chain entirely — no CWD / HOME / .aptos / .movement
-            // dance, no CLI-variant dependency.
-            const keyFilePath = writeTempKeyFile(formattedPrivateKey);
-            // Register a sync cleanup hook BEFORE invoking the CLI. If the
-            // user Ctrl+C's (or the process is SIGTERM'd) between the file
-            // write and our finally, the SIGINT handler iterates every
-            // registered callback and unlinks this deploy's key file
-            // synchronously so the private key never persists on disk after
-            // an abnormal exit. The signal-handler path uses the
-            // best-effort variant because the event loop is dead and we
-            // cannot logger.warning.
-            ensureSignalHandler();
-            const syncCleanup = () => removeKeyFileSyncBestEffort(keyFilePath);
-            cleanupCallbacks.add(syncCleanup);
-            try {
-                // Execute publish command. Private key reaches the CLI via the
-                // temp key file path (--private-key-file) — never on the
-                // command line — so it can't leak through `ps aux`. runCli's
-                // stdout/stderr redaction still applies as defense in depth
-                // for any `ed25519-priv-…` substring that surfaces in CLI
-                // output (Movement CLI sometimes echoes the key on error).
-                const publishResult = await withSpinner("Publishing to blockchain", () => runCli({
-                    command: "movement",
-                    args: [
-                        "move",
-                        "publish",
-                        "--package-dir",
-                        safeDir,
-                        "--url",
-                        config.rpc,
-                        "--private-key-file",
-                        keyFilePath,
-                        "--sender-account",
-                        deployerAddress,
-                        "--assume-yes",
-                        ...namedAddrArgs,
-                    ],
-                    timeoutMs: 120000, // 2 minutes for blockchain transactions
-                }, { adapter: this.deps.adapter }));
-                publishOut = publishResult.stdout;
-                publishErr = publishResult.stderr;
-                // Both stdout and stderr from the publish subprocess are gated
-                // behind isVerbose() — Movement CLI emits progress to both
-                // streams ("Compiling, may take a little while..."), so a
-                // visible stderr line is not by itself a failure signal. The
-                // surrounding withSpinner converts the runCli throw on real
-                // failure into the visible spinner.fail() output instead.
-                if (isVerbose() && publishOut)
-                    logger.info(publishOut.trim(), 2);
-                if (isVerbose() && publishErr)
-                    logger.info(publishErr.trim(), 2);
-            }
-            finally {
-                // Unlink the temp key file via the observable cleanup helper.
-                // ENOENT and other already-gone outcomes are benign (null).
-                // A non-null Error means the unlink failed AND the file still
-                // exists on disk — the private key would persist silently
-                // otherwise, so we emit a warning with the manual-cleanup
-                // hint. The SIGINT signal handler's sync callback below also
-                // tries to remove the same file; if SIGINT fires before this
-                // finally runs the file is gone and the next finally call
-                // sees ENOENT (benign).
-                const cleanupErr = removeKeyFile(keyFilePath);
-                if (cleanupErr) {
-                    logger.warning(`Failed to remove temp key file '${keyFilePath}': ${cleanupErr.message}. ` +
-                        `The file has mode 0o600 but should be removed manually: rm ${keyFilePath}`);
-                }
-                cleanupCallbacks.delete(syncCleanup);
-            }
-            // Extract transaction hash from output via the shared helper
-            // (`utils/parseCliOutput.ts`). Same regex pair as before; lifted
-            // for reuse by harness/codeObject.ts and harness/script.ts.
-            const txHash = parseTxHash(publishOut);
+            // Publish the freshly-built package. movelite cannot consume the
+            // Movement CLI's `move publish` REST flow (its responses omit the
+            // ledger headers and fields the CLI requires), so when the backend
+            // is movelite we publish via the TypeScript SDK instead. Every other
+            // backend keeps the CLI path.
+            const txHash = input.sdkPublish
+                ? await this.publishViaSdk(input, safeDir)
+                : await this.publishViaCli(config, safeDir, deployerAddress, namedAddrArgs);
             logger.success("Module published successfully!");
             // ←← "Publish succeeded" boundary. Anything thrown below this
             // point did NOT cause the publish to fail — the module is on
@@ -226,4 +159,149 @@ export class Publisher {
             throw error;
         }
     }
+    /**
+     * Publish via the Movement CLI (`movement move publish`). The default path
+     * for real Movement nodes, forks, and testnet. Returns the parsed tx hash.
+     */
+    async publishViaCli(config, safeDir, deployerAddress, namedAddrArgs) {
+        // Format the private key into AIP-80 shape so the Movement CLI
+        // doesn't emit its raw-hex deprecation warning. `formatPrivateKey`
+        // is idempotent for already-prefixed inputs.
+        const formattedPrivateKey = PrivateKey.formatPrivateKey(config.privateKey, PrivateKeyVariants.Ed25519);
+        // Move.toml is NOT mutated. All address overrides flow through
+        // the `--named-addresses` flag above, which Movement CLI applies
+        // during build + publish. Rewriting Move.toml on disk would risk
+        // leaving the user's file mutated if the process died before the
+        // restore step.
+        let publishOut = "";
+        let publishErr = "";
+        // Pass the private key to Movement CLI via a 0o600 temp file
+        // (`--private-key-file <path>`) and the on-chain address via
+        // `--sender-account <addr>`. This avoids the CLI's profile-yaml
+        // lookup chain entirely — no CWD / HOME / .aptos / .movement
+        // dance, no CLI-variant dependency.
+        const keyFilePath = writeTempKeyFile(formattedPrivateKey);
+        // Register a sync cleanup hook BEFORE invoking the CLI. If the
+        // user Ctrl+C's (or the process is SIGTERM'd) between the file
+        // write and our finally, the SIGINT handler iterates every
+        // registered callback and unlinks this deploy's key file
+        // synchronously so the private key never persists on disk after
+        // an abnormal exit. The signal-handler path uses the
+        // best-effort variant because the event loop is dead and we
+        // cannot logger.warning.
+        ensureSignalHandler();
+        const syncCleanup = () => removeKeyFileSyncBestEffort(keyFilePath);
+        cleanupCallbacks.add(syncCleanup);
+        try {
+            // Execute publish command. Private key reaches the CLI via the
+            // temp key file path (--private-key-file) — never on the
+            // command line — so it can't leak through `ps aux`. runCli's
+            // stdout/stderr redaction still applies as defense in depth
+            // for any `ed25519-priv-…` substring that surfaces in CLI
+            // output (Movement CLI sometimes echoes the key on error).
+            const publishResult = await withSpinner("Publishing to blockchain", () => runCli({
+                command: "movement",
+                args: [
+                    "move",
+                    "publish",
+                    "--package-dir",
+                    safeDir,
+                    "--url",
+                    config.rpc,
+                    "--private-key-file",
+                    keyFilePath,
+                    "--sender-account",
+                    deployerAddress,
+                    "--assume-yes",
+                    ...namedAddrArgs,
+                ],
+                timeoutMs: 120000, // 2 minutes for blockchain transactions
+            }, { adapter: this.deps.adapter }));
+            publishOut = publishResult.stdout;
+            publishErr = publishResult.stderr;
+            // Both stdout and stderr from the publish subprocess are gated
+            // behind isVerbose() — Movement CLI emits progress to both
+            // streams ("Compiling, may take a little while..."), so a
+            // visible stderr line is not by itself a failure signal. The
+            // surrounding withSpinner converts the runCli throw on real
+            // failure into the visible spinner.fail() output instead.
+            if (isVerbose() && publishOut)
+                logger.info(publishOut.trim(), 2);
+            if (isVerbose() && publishErr)
+                logger.info(publishErr.trim(), 2);
+        }
+        finally {
+            // Unlink the temp key file via the observable cleanup helper.
+            // ENOENT and other already-gone outcomes are benign (null).
+            // A non-null Error means the unlink failed AND the file still
+            // exists on disk — the private key would persist silently
+            // otherwise, so we emit a warning with the manual-cleanup
+            // hint. The SIGINT signal handler's sync callback below also
+            // tries to remove the same file; if SIGINT fires before this
+            // finally runs the file is gone and the next finally call
+            // sees ENOENT (benign).
+            const cleanupErr = removeKeyFile(keyFilePath);
+            if (cleanupErr) {
+                logger.warning(`Failed to remove temp key file '${keyFilePath}': ${cleanupErr.message}. ` +
+                    `The file has mode 0o600 but should be removed manually: rm ${keyFilePath}`);
+            }
+            cleanupCallbacks.delete(syncCleanup);
+        }
+        // Extract transaction hash from output via the shared helper
+        // (`utils/parseCliOutput.ts`). Same regex pair as before; lifted
+        // for reuse by harness/codeObject.ts and harness/script.ts.
+        return parseTxHash(publishOut);
+    }
+    /**
+     * Publish the already-built package via the TypeScript SDK. Used when the
+     * backend is movelite. Reads the compiled artifacts the CLI build produced
+     * under `<dir>/build/<pkg>/`, submits a `0x1::code::publish_package_txn`,
+     * and waits for it. Returns the on-chain tx hash.
+     */
+    async publishViaSdk(input, safeDir) {
+        const aptos = input.aptos;
+        if (!aptos) {
+            throw new Error("sdkPublish requires an Aptos client");
+        }
+        const buildRoot = join(safeDir, "build");
+        // The root package's compiled output is the single directory under
+        // build/ that carries a package-metadata.bcs; dependency builds live
+        // in nested bytecode_modules/dependencies/ and have no metadata here.
+        const pkgDirs = existsSync(buildRoot)
+            ? readdirSync(buildRoot, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => join(buildRoot, e.name))
+                .filter((d) => existsSync(join(d, "package-metadata.bcs")))
+            : [];
+        if (pkgDirs.length !== 1) {
+            throw new Error(`Expected exactly one compiled package under ${buildRoot}, found ${pkgDirs.length}.`);
+        }
+        const pkgDir = pkgDirs[0];
+        const metadataBytes = new Uint8Array(readFileSync(join(pkgDir, "package-metadata.bcs")));
+        const modulesDir = join(pkgDir, "bytecode_modules");
+        const moduleBytecode = readdirSync(modulesDir)
+            .filter((f) => f.endsWith(".mv"))
+            .sort()
+            .map((f) => new Uint8Array(readFileSync(join(modulesDir, f))));
+        if (moduleBytecode.length === 0) {
+            throw new Error(`No compiled modules (*.mv) found in ${modulesDir}`);
+        }
+        return withSpinner("Publishing to blockchain", async () => {
+            const tx = await aptos.publishPackageTransaction({
+                account: input.account.accountAddress,
+                metadataBytes,
+                moduleBytecode,
+            });
+            const senderAuth = aptos.transaction.sign({
+                signer: input.account,
+                transaction: tx,
+            });
+            const committed = await aptos.transaction.submit.simple({
+                transaction: tx,
+                senderAuthenticator: senderAuth,
+            });
+            await aptos.waitForTransaction({ transactionHash: committed.hash });
+            return committed.hash;
+        });
+    }
 }

package/dist/core/contract.d.ts

@@ -8,9 +8,10 @@ export declare class MoveContract {
     private aptos;
     private moduleAddress;
     private moduleName;
-    constructor(aptos: Aptos, moduleAddress: string, moduleName: string);
+    private traceRpcUrl?;
+    constructor(aptos: Aptos, moduleAddress: string, moduleName: string, traceRpcUrl?: string | undefined);
     call(signer: Account, functionName: string, args?: any[], typeArgs?: string[]): Promise<TransactionResult>;
     view<T = unknown>(functionName: string, args?: any[], typeArgs?: string[]): Promise<T>;
     getModuleId(): string;
 }
-export declare function getContract(aptos: Aptos, moduleAddress: string, moduleName: string): MoveContract;
+export declare function getContract(aptos: Aptos, moduleAddress: string, moduleName: string, traceRpcUrl?: string): MoveContract;

package/dist/core/contract.js

@@ -1,12 +1,20 @@
 import { logger } from "../ui/index.js";
+import { traceTransaction } from "./trace/client.js";
+import { renderTrace } from "./trace/renderer.js";
 export class MoveContract {
     aptos;
     moduleAddress;
     moduleName;
-    constructor(aptos, moduleAddress, moduleName) {
+    traceRpcUrl;
+    constructor(aptos, moduleAddress, moduleName, 
+    // movelite RPC base (ending in `/v1`). Presence enables Foundry-style
+    // execution traces at verbosity level >= 2. Undefined on the Movement node
+    // (no trace endpoint) — calls use the normal submit path.
+    traceRpcUrl) {
         this.aptos = aptos;
         this.moduleAddress = moduleAddress;
         this.moduleName = moduleName;
+        this.traceRpcUrl = traceRpcUrl;
     }
     async call(signer, functionName, 
     // any[]: Move entry-function arguments are heterogeneous primitives
@@ -29,6 +37,33 @@ export class MoveContract {
             signer,
             transaction,
         });
+        // Trace path: on movelite at raised verbosity, route through the
+        // instrumented `/transactions/trace?commit=true` endpoint, which executes
+        // AND commits in one pass (so we must NOT also submit), then render the
+        // returned call tree.
+        const traceLevel = logger.getVerbosityLevel();
+        if (this.traceRpcUrl && traceLevel >= 2) {
+            const { response, elapsedMs } = await traceTransaction({
+                rpcUrl: this.traceRpcUrl,
+                transaction,
+                senderAuthenticator: signature,
+            });
+            // A render failure must never fail a transaction that already committed.
+            try {
+                renderTrace(response, { level: traceLevel, elapsedMs });
+            }
+            catch (renderError) {
+                const msg = renderError instanceof Error ? renderError.message : String(renderError);
+                logger.warning(`Failed to render trace: ${msg}`);
+            }
+            logger.success(`Transaction ${response.txn_hash} committed with status: ${response.vm_status}`);
+            logger.newline();
+            return {
+                hash: response.txn_hash,
+                success: response.success,
+                vm_status: response.vm_status,
+            };
+        }
         const committedTxn = await this.aptos.transaction.submit.simple({
             transaction,
             senderAuthenticator: signature,
@@ -61,6 +96,6 @@ export class MoveContract {
         return `${this.moduleAddress}::${this.moduleName}`;
     }
 }
-export function getContract(aptos, moduleAddress, moduleName) {
-    return new MoveContract(aptos, moduleAddress, moduleName);
+export function getContract(aptos, moduleAddress, moduleName, traceRpcUrl) {
+    return new MoveContract(aptos, moduleAddress, moduleName, traceRpcUrl);
 }

package/dist/core/trace/client.d.ts

@@ -0,0 +1,18 @@
+import { type AccountAuthenticator, type AnyRawTransaction } from "@aptos-labs/ts-sdk";
+import type { TraceResponse } from "./types.js";
+/**
+ * Execute a signed transaction through movelite's instrumented VM and return
+ * the Foundry-style call tree. `commit=true` runs the trace AND commits in a
+ * single pass, so this is the sole execution — the caller must NOT also submit.
+ *
+ * @param rpcUrl movelite RPC base, already ending in `/v1`.
+ * @throws if the endpoint returns a non-2xx status (a submission failure).
+ */
+export declare function traceTransaction(args: {
+    rpcUrl: string;
+    transaction: AnyRawTransaction;
+    senderAuthenticator: AccountAuthenticator;
+}): Promise<{
+    response: TraceResponse;
+    elapsedMs: number;
+}>;

package/dist/core/trace/client.js

@@ -0,0 +1,58 @@
+import { generateSignedTransaction, } from "@aptos-labs/ts-sdk";
+/** Content type movelite requires for BCS-signed transaction bodies. */
+const BCS_SIGNED_TXN_CONTENT_TYPE = "application/x.aptos.signed_transaction+bcs";
+/**
+ * Pull a readable detail out of a movelite error body. movelite (>= 0.2.1)
+ * returns structured JSON errors (`{ message, error_code, vm_error_code }`);
+ * older versions return plain text. Returns the `message` plus any codes when
+ * the body is JSON, otherwise the raw text unchanged.
+ */
+function extractErrorDetail(body) {
+    if (!body)
+        return "";
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed.message === "string") {
+            const codes = [parsed.error_code, parsed.vm_error_code].filter((c) => c !== undefined && c !== null);
+            return codes.length > 0
+                ? `${parsed.message} (${codes.join(", ")})`
+                : parsed.message;
+        }
+    }
+    catch {
+        // Not JSON (e.g. older movelite plain-text errors) — fall through.
+    }
+    return body;
+}
+/**
+ * Execute a signed transaction through movelite's instrumented VM and return
+ * the Foundry-style call tree. `commit=true` runs the trace AND commits in a
+ * single pass, so this is the sole execution — the caller must NOT also submit.
+ *
+ * @param rpcUrl movelite RPC base, already ending in `/v1`.
+ * @throws if the endpoint returns a non-2xx status (a submission failure).
+ */
+export async function traceTransaction(args) {
+    const { rpcUrl, transaction, senderAuthenticator } = args;
+    const bytes = generateSignedTransaction({ transaction, senderAuthenticator });
+    const url = `${rpcUrl}/transactions/trace?commit=true`;
+    const start = performance.now();
+    const res = await fetch(url, {
+        method: "POST",
+        // No Accept header (response is JSON); no auth header (movelite runs --no-auth).
+        // Copy into a fresh ArrayBuffer-backed Uint8Array: the SDK returns
+        // `Uint8Array<ArrayBufferLike>`, which the fetch `BodyInit` type rejects
+        // under this TS lib config (the ArrayBuffer / SharedArrayBuffer split).
+        headers: { "Content-Type": BCS_SIGNED_TXN_CONTENT_TYPE },
+        body: new Uint8Array(bytes),
+    });
+    const elapsedMs = performance.now() - start;
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        const detail = extractErrorDetail(body);
+        throw new Error(`movelite trace request failed (${res.status} ${res.statusText})` +
+            (detail ? `: ${detail}` : ""));
+    }
+    const response = (await res.json());
+    return { response, elapsedMs };
+}

package/dist/core/trace/renderer.d.ts

@@ -0,0 +1,12 @@
+import type { TraceResponse } from "./types.js";
+/**
+ * Pure formatter — turns a trace into display lines. Snapshot-testable without
+ * touching stdout. `level` is the verbosity level (2..4); per-frame `gas` is in
+ * internal VM units while the footer `gas_used` is in octas (never mixed).
+ */
+export declare function formatTraceLines(response: TraceResponse, level: number, elapsedMs: number): string[];
+/** Render a trace to the terminal. Wraps {@link formatTraceLines}. */
+export declare function renderTrace(response: TraceResponse, opts: {
+    level: number;
+    elapsedMs: number;
+}): void;

package/dist/core/trace/renderer.js

@@ -0,0 +1,197 @@
+import { logger } from "../../ui/index.js";
+import { colors, rgbToAnsi, shouldUseColor } from "../../ui/colors.js";
+import { symbols } from "../../ui/symbols.js";
+// rgbToAnsi emits raw escapes unconditionally, so guard these two ourselves
+// (unlike colors.*, which already no-op when color is disabled).
+const orange = (s) => shouldUseColor() ? `${rgbToAnsi(255, 165, 0)}${s}\x1b[0m` : s;
+const brightBlue = (s) => shouldUseColor() ? `${rgbToAnsi(90, 170, 255)}${s}\x1b[0m` : s;
+const indent = (depth) => "  ".repeat(depth);
+/** Shorten a 0x-prefixed address for display (`0xf903..9b16`); leave short
+ *  framework addresses like `0x1` untouched. */
+const shortAddr = (addr) => addr.startsWith("0x") && addr.length > 12
+    ? `${addr.slice(0, 6)}..${addr.slice(-4)}`
+    : addr;
+/** Shorten the address part of a `address::module[::Name]` path. */
+const shortenPath = (path) => {
+    const [addr, ...rest] = path.split("::");
+    if (addr === undefined || rest.length === 0)
+        return path;
+    return [shortAddr(addr), ...rest].join("::");
+};
+const isFramework = (module) => module !== null && module.startsWith("0x1::");
+/** Visible at level 3 (user-module tree): not a framework frame, not a native. */
+const isUserFrame = (node) => !isFramework(node.module) && node.kind !== "native";
+const NUMERIC = /^\d+$/;
+const leafValue = (value) => {
+    const s = String(value);
+    if (NUMERIC.test(s))
+        return orange(s);
+    if (s.startsWith("0x") && s.length > 12)
+        return shortAddr(s);
+    return s;
+};
+/** Format a decoded value. Struct (and vector) values arrive as objects with
+ *  by-index keys; their fields can themselves be structs, so recurse rather
+ *  than `String()`-ing a nested object into `[object Object]`. */
+const formatValue = (value) => {
+    if (value !== null && typeof value === "object") {
+        return `{ ${Object.values(value)
+            .map(formatValue)
+            .join(", ")} }`;
+    }
+    return leafValue(value);
+};
+const formatArgValue = (arg) => {
+    if (arg.value === null)
+        return "()";
+    return formatValue(arg.value);
+};
+const formatArgs = (args) => args.map(formatArgValue).join(", ");
+const frameName = (node) => {
+    const base = node.module
+        ? `${shortenPath(node.module)}::${node.function ?? "?"}`
+        : node.function ?? `<${node.kind}>`;
+    return base;
+};
+const frameLabel = (node) => {
+    const name = frameName(node);
+    const colored = isFramework(node.module) || node.kind === "native"
+        ? colors.dim(name)
+        : colors.bold(colors.info(name));
+    const gas = colors.dim(` [${node.gas}]`);
+    return `${colored}(${formatArgs(node.args)})${gas}`;
+};
+const formatData = (data) => {
+    if (data === null || data === undefined)
+        return "";
+    try {
+        return colors.dim(JSON.stringify(data));
+    }
+    catch {
+        return colors.dim(String(data));
+    }
+};
+const eventLine = (event) => `${colors.warning(`emit ${shortenPath(event.type)}`)} ${formatData(event.data)}`.trimEnd();
+const storageLine = (op) => `${colors.primary(`${op.op} ${shortenPath(op.type)}`)}${op.address ? colors.dim(` @${shortAddr(op.address)}`) : ""}`;
+/** Non-unit return values only; null when nothing to show. */
+const returnLine = (ret) => {
+    const meaningful = ret.filter((r) => r.type !== "()" && r.value !== null);
+    if (meaningful.length === 0)
+        return null;
+    return colors.success(`← ${meaningful.map(formatArgValue).join(", ")}`);
+};
+/** Collect every event in the tree with its emitting module — for the flat
+ *  level-2 view. */
+const collectEvents = (node, out) => {
+    for (const e of node.events)
+        out.push({ module: node.module, event: e });
+    for (const c of node.children)
+        collectEvents(c, out);
+};
+/** Level 3: descend through hidden (framework / native) frames, bubbling their
+ *  events up and surfacing the nearest visible frames as children. */
+const gatherHidden = (children, bubbled, visible) => {
+    for (const child of children) {
+        if (isUserFrame(child)) {
+            visible.push(child);
+        }
+        else {
+            bubbled.push(...child.events);
+            gatherHidden(child.children, bubbled, visible);
+        }
+    }
+};
+const renderNode = (node, depth, showFull, lines) => {
+    lines.push(indent(depth) + frameLabel(node));
+    const childDepth = depth + 1;
+    if (showFull) {
+        for (const e of node.events)
+            lines.push(indent(childDepth) + eventLine(e));
+        for (const s of node.storage)
+            lines.push(indent(childDepth) + storageLine(s));
+        const ret = returnLine(node.return);
+        if (ret)
+            lines.push(indent(childDepth) + ret);
+        for (const c of node.children)
+            renderNode(c, childDepth, showFull, lines);
+        return;
+    }
+    // Level 3: own events + events bubbled from hidden descendants, then the
+    // nearest visible child frames.
+    const bubbled = [];
+    const visibleChildren = [];
+    gatherHidden(node.children, bubbled, visibleChildren);
+    for (const e of [...node.events, ...bubbled]) {
+        lines.push(indent(childDepth) + eventLine(e));
+    }
+    for (const c of visibleChildren)
+        renderNode(c, childDepth, showFull, lines);
+};
+const formatAbort = (abort) => {
+    const lines = [];
+    let header = colors.error(`${symbols.error} Aborted: code ${abort.code}`);
+    if (abort.sub_status !== null) {
+        header += colors.error(` (sub_status ${abort.sub_status})`);
+    }
+    if (abort.module !== null) {
+        header += colors.dim(` in ${shortenPath(abort.module)}`);
+    }
+    lines.push(header);
+    for (const entry of abort.stack) {
+        const mod = entry.module !== null ? shortenPath(entry.module) : "<unknown>";
+        const fn = entry.function ?? "<unknown>";
+        const off = entry.offset !== null ? ` @${entry.offset}` : "";
+        lines.push("  " + colors.error(`at ${mod}::${fn}${off}`));
+    }
+    return lines;
+};
+const formatFooter = (response, elapsedMs) => {
+    const status = response.success
+        ? colors.success(`${symbols.success} Executed successfully`)
+        : colors.error(`${symbols.error} Aborted`);
+    const sep = colors.dim(" · ");
+    const gas = colors.dim(`gas_used: ${response.gas_used} octas`);
+    const timed = brightBlue(`traced in ${Math.round(elapsedMs)}ms`);
+    return `${status}${sep}${gas}${sep}${timed}`;
+};
+/**
+ * Pure formatter — turns a trace into display lines. Snapshot-testable without
+ * touching stdout. `level` is the verbosity level (2..4); per-frame `gas` is in
+ * internal VM units while the footer `gas_used` is in octas (never mixed).
+ */
+export function formatTraceLines(response, level, elapsedMs) {
+    const lines = [];
+    if (level <= 2) {
+        const events = [];
+        collectEvents(response.root, events);
+        if (events.length === 0) {
+            lines.push(colors.dim("(no events emitted)"));
+        }
+        else {
+            lines.push(colors.bold("Events"));
+            for (const { event } of events)
+                lines.push("  " + eventLine(event));
+        }
+    }
+    else {
+        // Aborts always show the full tree so the failing frame is visible.
+        const showFull = level >= 4 || !response.success;
+        lines.push(colors.bold("Trace"));
+        renderNode(response.root, 0, showFull, lines);
+    }
+    if (!response.success && response.abort) {
+        lines.push("");
+        lines.push(...formatAbort(response.abort));
+    }
+    lines.push("");
+    lines.push(formatFooter(response, elapsedMs));
+    return lines;
+}
+/** Render a trace to the terminal. Wraps {@link formatTraceLines}. */
+export function renderTrace(response, opts) {
+    logger.newline();
+    for (const line of formatTraceLines(response, opts.level, opts.elapsedMs)) {
+        logger.plain(line);
+    }
+    logger.newline();
+}

package/dist/core/trace/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * TypeScript mirror of the JSON contract movelite's `/v1/transactions/trace`
+ * endpoint serializes. Field names and shapes match the Rust structs exactly;
+ * do not rename keys (`return` is keyed literally, `address` is nullable, etc.).
+ */
+/** A decoded argument or return value. `value` shape depends on `type`:
+ *  primitives like `u64` arrive as strings (`"5"`); a `struct` arrives as an
+ *  object keyed by field index (`{ "0": .., "1": .. }`); the unit type `()` has
+ *  `value: null`. */
+export interface TracedArg {
+    type: string;
+    value: unknown;
+}
+/** An event emitted within a frame. `data` is the decoded event payload. */
+export interface TracedEvent {
+    type: string;
+    data: unknown;
+}
+/** A storage access. `address` is populated for `load_resource` and null for
+ *  `move_to` / `borrow_global_mut`. */
+export interface StorageOp {
+    op: string;
+    type: string;
+    address: string | null;
+}
+/** One frame of the abort stack, innermost first. Any field may be null when
+ *  the VM could not resolve it. */
+export interface AbortStackEntry {
+    module: string | null;
+    function: string | null;
+    offset: number | null;
+}
+/** Abort details, present only when `TraceResponse.success` is false. */
+export interface AbortInfo {
+    code: number;
+    sub_status: number | null;
+    module: string | null;
+    stack: AbortStackEntry[];
+}
+/** A single call frame in the execution tree. */
+export interface CallNode {
+    kind: "function" | "native" | "script";
+    module: string | null;
+    function: string | null;
+    type_args: string[];
+    args: TracedArg[];
+    /** Keyed literally as `return` to match the wire format. */
+    return: TracedArg[];
+    /**
+     * Self gas of this frame in **internal** VM gas units. These are much larger
+     * than, and NOT comparable to, the external octa `gas_used` on the response —
+     * never mix the two when rendering.
+     */
+    gas: number;
+    events: TracedEvent[];
+    storage: StorageOp[];
+    children: CallNode[];
+}
+/** The full trace response. */
+export interface TraceResponse {
+    txn_hash: string;
+    success: boolean;
+    /** Transaction-level gas in octas (the external unit). */
+    gas_used: number;
+    vm_status: string;
+    abort: AbortInfo | null;
+    root: CallNode;
+}

package/dist/core/trace/types.js

@@ -0,0 +1,6 @@
+/**
+ * TypeScript mirror of the JSON contract movelite's `/v1/transactions/trace`
+ * endpoint serializes. Field names and shapes match the Rust structs exactly;
+ * do not rename keys (`return` is keyed literally, `address` is nullable, etc.).
+ */
+export {};

package/dist/helpers/setupLocalTesting.js

@@ -96,6 +96,17 @@ export async function setupLocalTesting(options = {}) {
         };
     }
 }
+/**
+ * Resolve whether to prefer movelite. Explicit `useMovelite` wins; otherwise
+ * the `MOVEHAT_USE_MOVELITE` env var acts as an override (`0` disables, `1`
+ * enables); default is enabled. Lets tooling force a backend without editing
+ * test code.
+ */
+function resolveUseMovelite(useMovelite) {
+    if (useMovelite !== undefined)
+        return useMovelite;
+    return process.env.MOVEHAT_USE_MOVELITE !== "0";
+}
 /**
  * Setup using local Movement node (full blockchain)
  */
@@ -112,7 +123,7 @@ async function setupWithLocalNode(options, accountLabels, autoFund, defaultBalan
         }
         nodeInfo = localNode.getNodeInfo();
     }
-    else if (options.useMovelite !== false && findMoveliteBinary()) {
+    else if (resolveUseMovelite(options.useMovelite) && findMoveliteBinary()) {
         localNode = new MoveliteManager(findMoveliteBinary());
         nodeInfo = await localNode.start();
         ownsNode = true;
@@ -160,9 +171,14 @@ async function setupWithLocalNode(options, accountLabels, autoFund, defaultBalan
         if (!deployerPrivateKey) {
             throw new Error("Failed to get deployer private key");
         }
+        // movelite exposes the /transactions/trace endpoint that powers
+        // Foundry-style execution traces; a real Movement node does not. Compute
+        // this once and reuse it for both the trace wiring and SDK publish below.
+        const isMovelite = localNode instanceof MoveliteManager;
         const runtime = await initRuntime({
             network: "local",
             accountManager,
+            ...(isMovelite ? { traceRpcUrl: `${nodeInfo.rpcUrl}/v1` } : {}),
             configOverride: {
                 networks: {
                     local: {
@@ -179,11 +195,14 @@ async function setupWithLocalNode(options, accountLabels, autoFund, defaultBalan
             logger.step(`Auto-deploying ${options.autoDeploy.length} module(s)...`);
             const previousRedeploy = process.env.MH_CLI_REDEPLOY;
             process.env.MH_CLI_REDEPLOY = 'true';
+            // movelite's REST responses can't drive the Movement CLI publish flow,
+            // so deploy through the TypeScript SDK when it is the spawned backend.
+            const sdkPublish = isMovelite;
             try {
                 for (const moduleName of options.autoDeploy) {
                     try {
                         logger.plain(`   Deploying ${moduleName}...`);
-                        await runtime.deployContract(moduleName);
+                        await runtime.deployContract(moduleName, { sdkPublish });
                         logger.success(`${moduleName} deployed`, 2);
                     }
                     catch (error) {

package/dist/node/LocalNodeManager.js

@@ -94,7 +94,7 @@ export class LocalNodeManager {
                 ...(usesDefaultAdapter ? { env: sanitizeMovementEnv() } : {}),
                 stdio: this.options.silent ? "ignore" : "pipe",
             });
-            // Subprocess output handling (see §9 Console UX in CLAUDE.md):
+            // Subprocess output handling (verbosity-gated console UX):
             //   - stdout chatter is hidden by default; gated by isVerbose()
             //   - lines matching CRITICAL_NODE_OUTPUT always surface as warnings
             //     so the user is never silenced through a real failure

package/dist/runtime.d.ts

@@ -17,6 +17,14 @@ export interface InitRuntimeOptions {
      * key it extracts ends up on the same manager the runtime exposes.
      */
     accountManager?: AccountManager;
+    /**
+     * movelite RPC base URL (already ending in `/v1`) enabling Foundry-style
+     * execution traces on `contract.call(...)` at verbosity level >= 2. Set only
+     * when the active backend is movelite (its `/transactions/trace` endpoint
+     * does not exist on a real Movement node). When omitted, contracts use the
+     * normal submit path and never trace.
+     */
+    traceRpcUrl?: string;
 }
 /**
  * Initialize the Movehat Runtime Environment.

package/dist/runtime.js

@@ -55,7 +55,7 @@ export async function initRuntime(options = {}) {
     };
     // Helper functions
     const getContractHelper = (address, moduleName) => {
-        return getContract(aptos, address, moduleName);
+        return getContract(aptos, address, moduleName, options.traceRpcUrl);
     };
     const deployContract = async (moduleName, options) => {
         // Thin orchestrator; the actual logic lives in core/Publisher.ts.
@@ -64,6 +64,8 @@ export async function initRuntime(options = {}) {
             config,
             account,
             packageDir: options?.packageDir,
+            sdkPublish: options?.sdkPublish,
+            aptos,
         });
     };
     const getDeployment = (moduleName) => {

package/dist/types/runtime.d.ts

@@ -24,6 +24,12 @@ export interface MovehatRuntime {
          * leave this undefined so the default spawn-based adapter is used.
          */
         adapter?: ChildProcessAdapter;
+        /**
+         * Publish the compiled package via the TypeScript SDK instead of the
+         * Movement CLI. Internal: setupLocalTesting sets this when the backend
+         * is movelite, whose REST responses the Movement CLI cannot consume.
+         */
+        sdkPublish?: boolean;
     }) => Promise<DeploymentInfo>;
     getDeployment: (moduleName: string) => DeploymentInfo | null;
     getDeployments: () => Record<string, DeploymentInfo>;

package/dist/ui/logger.d.ts

@@ -29,6 +29,21 @@ export interface LoggerConfig {
  * callers opt in before the CLI parses args, e.g. in shell scripts).
  */
 export declare const isVerbose: () => boolean;
+/**
+ * Numeric verbosity level (0..4) for level-gated output such as the
+ * transaction-trace renderer. Driven by the counted `-v` CLI flag via the
+ * `MOVEHAT_VERBOSITY` env var, so it survives the spawned test/script
+ * subprocess boundary the same way {@link isVerbose} reads `MOVEHAT_VERBOSE`.
+ * Falls back to the legacy boolean `MOVEHAT_VERBOSE=1` (level 1) for callers
+ * that set only that.
+ *
+ * - 0 default — system logs only
+ * - 1 `-v`    — + subprocess stdout (see {@link isVerbose})
+ * - 2 `-vv`   — + decoded events per call
+ * - 3 `-vvv`  — + user-module call tree
+ * - 4 `-vvvv` — + framework frames, natives, storage, return values
+ */
+export declare const getVerbosityLevel: () => number;
 /**
  * Configure logger globally
  *
@@ -202,6 +217,7 @@ export declare const item: (text: string, indent?: number) => void;
 export declare const logger: {
     configure: (newConfig: Partial<LoggerConfig>) => void;
     isVerbose: () => boolean;
+    getVerbosityLevel: () => number;
     info: (message: string, indent?: number) => void;
     success: (message: string, indent?: number) => void;
     error: (message: string, indent?: number) => void;

package/dist/ui/logger.js

@@ -16,6 +16,29 @@ let config = {
  * callers opt in before the CLI parses args, e.g. in shell scripts).
  */
 export const isVerbose = () => config.verbosity === 'verbose' || process.env.MOVEHAT_VERBOSE === '1';
+/**
+ * Numeric verbosity level (0..4) for level-gated output such as the
+ * transaction-trace renderer. Driven by the counted `-v` CLI flag via the
+ * `MOVEHAT_VERBOSITY` env var, so it survives the spawned test/script
+ * subprocess boundary the same way {@link isVerbose} reads `MOVEHAT_VERBOSE`.
+ * Falls back to the legacy boolean `MOVEHAT_VERBOSE=1` (level 1) for callers
+ * that set only that.
+ *
+ * - 0 default — system logs only
+ * - 1 `-v`    — + subprocess stdout (see {@link isVerbose})
+ * - 2 `-vv`   — + decoded events per call
+ * - 3 `-vvv`  — + user-module call tree
+ * - 4 `-vvvv` — + framework frames, natives, storage, return values
+ */
+export const getVerbosityLevel = () => {
+    const raw = process.env.MOVEHAT_VERBOSITY;
+    if (raw !== undefined) {
+        const n = parseInt(raw, 10);
+        if (!Number.isNaN(n))
+            return Math.max(0, Math.min(4, n));
+    }
+    return process.env.MOVEHAT_VERBOSE === '1' ? 1 : 0;
+};
 /**
  * Configure logger globally
  *
@@ -261,6 +284,7 @@ export const item = (text, indent = 0) => {
 export const logger = {
     configure: configureLogger,
     isVerbose,
+    getVerbosityLevel,
     info,
     success,
     error,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "movehat",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "type": "module",
   "description": "Hardhat-like development framework for Movement L1 smart contracts",
   "bin": {
@@ -71,7 +71,7 @@
     "tsx": "^4.7.0"
   },
   "optionalDependencies": {
-    "movelite": "^0.1.0"
+    "movelite": "^0.2.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",