movehat 0.2.9 → 0.4.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 (full tree on the movelite backend; the Movement node renders a degraded flat trace — events, state changes, and gas).
 - **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/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,21 @@
 import { logger } from "../ui/index.js";
+import { traceTransaction } from "./trace/client.js";
+import { renderTrace } from "./trace/renderer.js";
+import { renderNodeTrace } from "./trace/nodeRenderer.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 +38,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,
@@ -36,6 +72,24 @@ export class MoveContract {
         const response = await this.aptos.waitForTransaction({
             transactionHash: committedTxn.hash,
         });
+        // Degraded trace: the Movement node does not expose internal call frames,
+        // but the REST response already carries the events, write-set, and gas.
+        // At raised verbosity render that flat view (a render failure must never
+        // fail a transaction that already committed).
+        //
+        // waitForTransaction returns the CommittedTransactionResponse union; the
+        // `in` guards narrow it to the user-transaction shape that carries events
+        // and changes, so renderNodeTrace receives a typed value without a cast.
+        const nodeLevel = logger.getVerbosityLevel();
+        if (nodeLevel >= 2 && "events" in response && "changes" in response) {
+            try {
+                renderNodeTrace(response, { level: nodeLevel });
+            }
+            catch (renderError) {
+                const msg = renderError instanceof Error ? renderError.message : String(renderError);
+                logger.warning(`Failed to render trace: ${msg}`);
+            }
+        }
         logger.success(`Transaction ${committedTxn.hash} committed with status: ${response.vm_status}`);
         logger.newline();
         return {
@@ -61,6 +115,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/format.d.ts

@@ -0,0 +1,27 @@
+export declare const brightBlue: (s: string) => string;
+export declare const indent: (depth: number) => string;
+/** Shorten a 0x-prefixed address for display (`0xf903..9b16`); leave short
+ *  framework addresses like `0x1` untouched. */
+export declare const shortAddr: (addr: string) => string;
+/** Shorten the address part of a `address::module[::Name]` path. */
+export declare const shortenPath: (path: string) => string;
+/** 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]`. */
+export declare const formatValue: (value: unknown) => string;
+export declare const formatData: (data: unknown) => string;
+/** One emitted-event line: `emit <module>::<Event> {…data}`. Reads only `type`
+ *  and `data`, so it accepts both the movelite `TracedEvent` and the SDK's
+ *  `Event` shape. */
+export declare const formatEventLine: (event: {
+    type: string;
+    data: unknown;
+}) => string;
+/** One storage / state-change line: `<op> <module>::<Resource> [@addr]`. The
+ *  `op` object is duck-typed so both movelite storage ops and SDK write-set
+ *  changes (after reshaping) feed it. */
+export declare const storageLine: (op: {
+    op: string;
+    type: string;
+    address: string | null;
+}) => string;

package/dist/core/trace/format.js

@@ -0,0 +1,61 @@
+import { colors, rgbToAnsi, shouldUseColor } from "../../ui/colors.js";
+// Generic, stateless formatting helpers shared by the movelite call-tree
+// renderer (renderer.ts) and the node degraded-trace renderer (nodeRenderer.ts).
+// None of these are tied to a specific response shape.
+// rgbToAnsi emits raw escapes unconditionally, so guard these ourselves
+// (unlike colors.*, which already no-op when color is disabled). `orange` is
+// module-private (only `leafValue` uses it); `brightBlue` is consumed by the
+// movelite renderer's footer.
+const orange = (s) => shouldUseColor() ? `${rgbToAnsi(255, 165, 0)}${s}\x1b[0m` : s;
+export const brightBlue = (s) => shouldUseColor() ? `${rgbToAnsi(90, 170, 255)}${s}\x1b[0m` : s;
+export const indent = (depth) => "  ".repeat(depth);
+/** Shorten a 0x-prefixed address for display (`0xf903..9b16`); leave short
+ *  framework addresses like `0x1` untouched. */
+export 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. */
+export const shortenPath = (path) => {
+    const [addr, ...rest] = path.split("::");
+    if (addr === undefined || rest.length === 0)
+        return path;
+    return [shortAddr(addr), ...rest].join("::");
+};
+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]`. */
+export const formatValue = (value) => {
+    if (value !== null && typeof value === "object") {
+        return `{ ${Object.values(value)
+            .map(formatValue)
+            .join(", ")} }`;
+    }
+    return leafValue(value);
+};
+export const formatData = (data) => {
+    if (data === null || data === undefined)
+        return "";
+    try {
+        return colors.dim(JSON.stringify(data));
+    }
+    catch {
+        return colors.dim(String(data));
+    }
+};
+/** One emitted-event line: `emit <module>::<Event> {…data}`. Reads only `type`
+ *  and `data`, so it accepts both the movelite `TracedEvent` and the SDK's
+ *  `Event` shape. */
+export const formatEventLine = (event) => `${colors.warning(`emit ${shortenPath(event.type)}`)} ${formatData(event.data)}`.trimEnd();
+/** One storage / state-change line: `<op> <module>::<Resource> [@addr]`. The
+ *  `op` object is duck-typed so both movelite storage ops and SDK write-set
+ *  changes (after reshaping) feed it. */
+export const storageLine = (op) => `${colors.primary(`${op.op} ${shortenPath(op.type)}`)}${op.address ? colors.dim(` @${shortAddr(op.address)}`) : ""}`;

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

@@ -0,0 +1,44 @@
+/**
+ * Minimal structural view of a committed transaction, as the Aptos SDK's
+ * `waitForTransaction` returns it (`UserTransactionResponse`). Typed loosely so
+ * unit tests can feed plain fixtures and so we never depend on the full SDK
+ * response union. The real Movement node REST API does NOT expose internal call
+ * frames, so this is a flat, degraded trace — events + write-set + gas — rather
+ * than the movelite call tree.
+ */
+export interface NodeTxView {
+    success: boolean;
+    vm_status: string;
+    /** Transaction gas in octas (external unit). */
+    gas_used: string;
+    events: {
+        type: string;
+        data: unknown;
+    }[];
+    changes: NodeWriteSetChange[];
+}
+/** Loose shape of an SDK `WriteSetChange` — only the fields we render. */
+interface NodeWriteSetChange {
+    type: string;
+    address?: string;
+    /** `write_resource` payload (a `MoveResource` `{type,data}`); typed `unknown`
+     *  and narrowed at the use sites since the shape varies by change type. */
+    data?: unknown;
+    /** `delete_resource` carries the resource type as a string here. */
+    resource?: string;
+    /** Table-item changes carry a `handle` instead of an `address`. */
+    handle?: string;
+}
+/**
+ * Pure formatter for the node degraded trace. Snapshot-testable without
+ * touching stdout. `level` is the verbosity level (2..4): L2 = events, L3 =
+ * + state changes, L4 = + each change's decoded data. The footer carries the
+ * status and the octa `gas_used` (there is no per-frame trace timing off the
+ * node).
+ */
+export declare function formatNodeTraceLines(tx: NodeTxView, level: number): string[];
+/** Render a node degraded trace to the terminal. Wraps {@link formatNodeTraceLines}. */
+export declare function renderNodeTrace(tx: NodeTxView, opts: {
+    level: number;
+}): void;
+export {};

package/dist/core/trace/nodeRenderer.js

@@ -0,0 +1,90 @@
+import { logger } from "../../ui/index.js";
+import { colors } from "../../ui/colors.js";
+import { symbols } from "../../ui/symbols.js";
+import { formatData, formatEventLine, storageLine } from "./format.js";
+/** Reshape an SDK write-set change into the shared `storageLine` duck-type. */
+const changeToOp = (c) => {
+    const address = typeof c.address === "string" ? c.address : null;
+    switch (c.type) {
+        case "write_resource": {
+            const t = c.data && typeof c.data === "object" && "type" in c.data
+                ? String(c.data.type ?? "?")
+                : "?";
+            return { op: c.type, type: t, address };
+        }
+        case "delete_resource":
+            return { op: c.type, type: c.resource ?? "?", address };
+        case "write_module":
+        case "delete_module":
+            return { op: c.type, type: "module", address };
+        case "write_table_item":
+        case "delete_table_item":
+            // Table items have no resource type; key off the table `handle`.
+            return { op: c.type, type: "table_item", address: c.handle ?? null };
+        default:
+            return { op: c.type, type: "?", address };
+    }
+};
+/** Level-4 payload for a change: the resource's decoded fields when present. */
+const changePayload = (c) => {
+    if (c.data && typeof c.data === "object" && "data" in c.data) {
+        return c.data.data;
+    }
+    return c.data;
+};
+const nodeFooter = (tx) => {
+    const status = tx.success
+        ? colors.success(`${symbols.success} ${tx.vm_status}`)
+        : colors.error(`${symbols.error} ${tx.vm_status}`);
+    const sep = colors.dim(" · ");
+    const gas = colors.dim(`gas_used: ${tx.gas_used} octas`);
+    return `${status}${sep}${gas}`;
+};
+/**
+ * Pure formatter for the node degraded trace. Snapshot-testable without
+ * touching stdout. `level` is the verbosity level (2..4): L2 = events, L3 =
+ * + state changes, L4 = + each change's decoded data. The footer carries the
+ * status and the octa `gas_used` (there is no per-frame trace timing off the
+ * node).
+ */
+export function formatNodeTraceLines(tx, level) {
+    const lines = [];
+    // Events (level 2+).
+    if (tx.events.length === 0) {
+        lines.push(colors.dim("(no events emitted)"));
+    }
+    else {
+        lines.push(colors.bold("Events"));
+        for (const e of tx.events)
+            lines.push("  " + formatEventLine(e));
+    }
+    // State changes (level 3+).
+    if (level >= 3) {
+        lines.push("");
+        if (tx.changes.length === 0) {
+            lines.push(colors.dim("(no state changes)"));
+        }
+        else {
+            lines.push(colors.bold("State changes"));
+            for (const c of tx.changes) {
+                lines.push("  " + storageLine(changeToOp(c)));
+                if (level >= 4) {
+                    const payload = formatData(changePayload(c));
+                    if (payload)
+                        lines.push("    " + payload);
+                }
+            }
+        }
+    }
+    lines.push("");
+    lines.push(nodeFooter(tx));
+    return lines;
+}
+/** Render a node degraded trace to the terminal. Wraps {@link formatNodeTraceLines}. */
+export function renderNodeTrace(tx, opts) {
+    logger.newline();
+    for (const line of formatNodeTraceLines(tx, opts.level)) {
+        logger.plain(line);
+    }
+    logger.newline();
+}

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,149 @@
+import { logger } from "../../ui/index.js";
+import { colors } from "../../ui/colors.js";
+import { symbols } from "../../ui/symbols.js";
+import { brightBlue, formatEventLine, formatValue, indent, shortenPath, storageLine, } from "./format.js";
+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 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}`;
+};
+/** 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) + formatEventLine(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) + formatEventLine(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("  " + formatEventLine(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

@@ -171,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: {
@@ -192,7 +197,7 @@ async function setupWithLocalNode(options, accountLabels, autoFund, defaultBalan
             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 = localNode instanceof MoveliteManager;
+            const sdkPublish = isMovelite;
             try {
                 for (const moduleName of options.autoDeploy) {
                     try {

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.

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.9",
+  "version": "0.4.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",