@typeberry/lib 0.5.2-9afefa7 → 0.5.2-ab56433

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeberry/lib",
-  "version": "0.5.2-9afefa7",
+  "version": "0.5.2-ab56433",
   "description": "Typeberry Library",
   "main": "./bin/lib/index.js",
   "types": "./bin/lib/index.d.ts",

package/packages/core/pvm-host-calls/bin.js

@@ -1,11 +1,11 @@
 import { PvmBackend } from "#@typeberry/config";
 import { tryAsGas } from "#@typeberry/pvm-interface";
-import { HostCalls } from "./host-calls.js";
-import { HostCallsManager, NoopMissing } from "./host-calls-manager.js";
-import { InterpreterInstanceManager } from "./interpreter-instance-manager.js";
-const hostCalls = new HostCallsManager({ missing: new NoopMissing(), handlers: [] });
-const pvmInstanceManager = await InterpreterInstanceManager.new(PvmBackend.BuiltIn);
-const pvmHostCallExtension = new HostCalls(pvmInstanceManager, hostCalls);
+import { HostCalls, NoopMissing } from "./host-calls.js";
+import { HostCallsExecutor } from "./host-calls-executor.js";
+import { PvmInstanceManager } from "./pvm-instance-manager.js";
+const hostCalls = new HostCalls({ missing: new NoopMissing(), handlers: [] });
+const pvmInstanceManager = await PvmInstanceManager.new(PvmBackend.BuiltIn);
+const pvmHostCallExtension = new HostCallsExecutor(pvmInstanceManager, hostCalls);
 const program = new Uint8Array([
     0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x10, 0x1, 0x0, 0x0, 0xf9, 0x0, 0x0, 0x0, 0x0, 0x0, 0x80, 0xd9, 0x5, 0x12,
     0x0, 0x0, 0x0, 0x5, 0x11, 0x0, 0x0, 0x0, 0x5, 0xa3, 0x0, 0x0, 0x0, 0x5, 0xc6, 0x0, 0x4, 0x7, 0x13, 0x0, 0x2, 0x11,

package/packages/core/pvm-host-calls/ecalli-io-tracker.d.ts

@@ -0,0 +1,32 @@
+import type { U32, U64 } from "#@typeberry/numbers";
+import type { RegisterIndex } from "#@typeberry/pvm-interpreter";
+/**
+ * Interface for tracking PVM I/O operations during host call execution.
+ *
+ * Implementations record memory reads/writes and register modifications
+ * for debugging, tracing, or replay purposes.
+ */
+export interface IoTracker {
+    /** Record a register write operation. */
+    setReg(idx: number, val: U64): void;
+    /** Record a memory read operation. */
+    memRead(address: U32, data: Uint8Array): void;
+    /** Record a memory write operation. */
+    memWrite(address: U32, data: Uint8Array): void;
+    /** Clear all recorded operations. */
+    clear(): void;
+}
+/** Create a no-op tracker that discards all operations. */
+export declare function noopTracker(): NoopIoTracker;
+/**
+ * No-op implementation that discards all tracked operations.
+ * Used when I/O tracing is disabled.
+ */
+declare class NoopIoTracker implements IoTracker {
+    clear(): void;
+    setReg(_idx: RegisterIndex, _val: U64): void;
+    memRead(_address: U32, _data: Uint8Array): void;
+    memWrite(_address: U32, _data: Uint8Array): void;
+}
+export {};
+//# sourceMappingURL=ecalli-io-tracker.d.ts.map

package/packages/core/pvm-host-calls/ecalli-io-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecalli-io-tracker.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/ecalli-io-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IACpC,sCAAsC;IACtC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9C,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/C,qCAAqC;IACrC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,kBAE1B;AAED;;;GAGG;AACH,cAAM,aAAc,YAAW,SAAS;IACtC,KAAK,IAAI,IAAI;IACb,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAC5C,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAC/C,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;CACjD"}

package/packages/core/pvm-host-calls/ecalli-io-tracker.js

@@ -0,0 +1,14 @@
+/** Create a no-op tracker that discards all operations. */
+export function noopTracker() {
+    return new NoopIoTracker();
+}
+/**
+ * No-op implementation that discards all tracked operations.
+ * Used when I/O tracing is disabled.
+ */
+class NoopIoTracker {
+    clear() { }
+    setReg(_idx, _val) { }
+    memRead(_address, _data) { }
+    memWrite(_address, _data) { }
+}

package/packages/core/pvm-host-calls/ecalli-trace-logger.d.ts

@@ -0,0 +1,139 @@
+import type { U32, U64 } from "#@typeberry/numbers";
+import type { Gas } from "#@typeberry/pvm-interface";
+import type { IoTracker } from "./ecalli-io-tracker.js";
+import type { HostCallIndex } from "./host-call-handler.js";
+import type { HostCallRegisters } from "./host-call-registers.js";
+/**
+ * Output function type for IO trace logging.
+ * Each call should output a single line.
+ */
+export type IoTraceOutput = (line: string) => void;
+/**
+ * Ecalli PVM IO Trace Logger.
+ *
+ * Implements the logging format specified for PVM execution tracing.
+ * This format is designed to be:
+ * - Human-readable, newline-delimited text
+ * - Self-contained for stateless re-execution
+ * - Comparable using simple textual diff tools
+ *
+ * @see https://github.com/tomusdrw/JIPs/pull/2
+ */
+export declare class EcalliTraceLogger {
+    private readonly output;
+    /** Returns a tracker for IO operations. */
+    tracker(): IoTraceTracker | null;
+    /**
+     * Create an IoTraceLogger that outputs to the `ecalli` module logger.
+     *
+     * Returns `null` if the `ecalli` logger is not configured for at least TRACE level.
+     * Enable with: `JAM_LOG=ecalli=trace` or `JAM_LOG=trace`
+     */
+    static create(): EcalliTraceLogger | null;
+    /**
+     * Create a no-op IoTraceLogger that discards all output.
+     * Used when tracing is disabled.
+     */
+    static noop(): EcalliTraceLogger;
+    static new(output: IoTraceOutput): EcalliTraceLogger;
+    private constructor();
+    /**
+     * Log optional context lines (implementation metadata, execution environment).
+     */
+    logContext(context: string): void;
+    /**
+     * Log the program blob being executed and the write data (if any)
+     *
+     * Format: `program {hex-encoded-program-with-metadata}`
+     * Format: `memwrite {hex-encoded-address} len={blob-byte-length} <- {hex-encoded-bytes}`
+     */
+    logProgram(program: Uint8Array, args: Uint8Array): void;
+    /**
+     * Log initial execution state (prelude).
+     *
+     * Format: `start pc={pc} gas={gas} {register-dump}`
+     */
+    logStart(pc: number, gas: Gas, registers: HostCallRegisters): void;
+    /**
+     * Log ecalli invocation with register dump.
+     *
+     * Format: `ecalli={index} pc={pc} gas={gas} {register-dump}`
+     */
+    logEcalli(index: HostCallIndex, pc: number, gas: Gas, registers: HostCallRegisters): void;
+    /**
+     * Log memory read operation.
+     *
+     * Format: `memread {hex-encoded-address} len={blob-byte-length} -> {hex-encoded-data-read}`
+     */
+    logMemRead(address: number, len: number, data: string): void;
+    /**
+     * Log memory write operation.
+     *
+     * Format: `memwrite {hex-encoded-address} len={blob-byte-length} <- {hex-encoded-bytes}`
+     */
+    logMemWrite(address: number, len: number, data: string): void;
+    /**
+     * Log register write operation.
+     *
+     * Format: `setreg r{idx} <- {hex-encoded-value}`
+     */
+    logSetReg(index: number, value: bigint): void;
+    /**
+     * Log gas overwrite operation.
+     *
+     * Format: `setgas <- {gas}`
+     */
+    logSetGas(gas: Gas): void;
+    /**
+     * Log all host actions from a single ecalli invocation.
+     * Actions are logged in the order specified by JIP-6:
+     * 1. Memory reads (sorted by address)
+     * 2. Memory writes (sorted by address)
+     * 3. Register writes (sorted by index)
+     * 4. Gas overwrite
+     */
+    logHostActions(ioTracker: IoTraceTracker | null, gasBefore: Gas, gasAfter: Gas): void;
+    /**
+     * Log PANIC termination.
+     *
+     * Format: `PANIC={argument} pc={pc} gas={gas} {register-dump}`
+     */
+    logPanic(argument: number, pc: number, gas: Gas, registers: HostCallRegisters): void;
+    /**
+     * Log OOG (out of gas) termination.
+     *
+     * Format: `OOG pc={pc} gas={gas} {register-dump}`
+     */
+    logOog(pc: number, gas: Gas, registers: HostCallRegisters): void;
+    /**
+     * Log HALT termination.
+     *
+     * Format: `HALT pc={pc} gas={gas} {register-dump}`
+     */
+    logHalt(pc: number, gas: Gas, registers: HostCallRegisters): void;
+}
+type MemoryOperation = {
+    address: number;
+    hex: string;
+    len: number;
+};
+/**
+ * IoTracker implementation that records all I/O operations for trace logging.
+ *
+ * Stores memory reads, writes, and register modifications as hex-encoded strings
+ * for output via IoTraceLogger.
+ */
+export declare class IoTraceTracker implements IoTracker {
+    /** Recorded memory read operations (address + hex data + len). */
+    reads: MemoryOperation[];
+    /** Recorded memory write operations (address + hex data + len). */
+    writes: MemoryOperation[];
+    /** Recorded register write operations (index -> value). */
+    registers: Map<number, U64>;
+    setReg(idx: number, val: U64): void;
+    memRead(address: U32, data: Uint8Array): void;
+    memWrite(address: U32, data: Uint8Array): void;
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=ecalli-trace-logger.d.ts.map

package/packages/core/pvm-host-calls/ecalli-trace-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecalli-trace-logger.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/ecalli-trace-logger.ts"],"names":[],"mappings":"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"}

package/packages/core/pvm-host-calls/ecalli-trace-logger.js

@@ -0,0 +1,209 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { Level, Logger } from "#@typeberry/logger";
+const ecalliLogger = Logger.new(import.meta.filename, "ecalli");
+const defaultOutput = (line) => {
+    ecalliLogger.trace `${line}`;
+};
+const emptyOutput = () => { };
+/**
+ * Ecalli PVM IO Trace Logger.
+ *
+ * Implements the logging format specified for PVM execution tracing.
+ * This format is designed to be:
+ * - Human-readable, newline-delimited text
+ * - Self-contained for stateless re-execution
+ * - Comparable using simple textual diff tools
+ *
+ * @see https://github.com/tomusdrw/JIPs/pull/2
+ */
+export class EcalliTraceLogger {
+    output;
+    /** Returns a tracker for IO operations. */
+    tracker() {
+        return this.output === emptyOutput ? null : new IoTraceTracker();
+    }
+    /**
+     * Create an IoTraceLogger that outputs to the `ecalli` module logger.
+     *
+     * Returns `null` if the `ecalli` logger is not configured for at least TRACE level.
+     * Enable with: `JAM_LOG=ecalli=trace` or `JAM_LOG=trace`
+     */
+    static create() {
+        if (ecalliLogger.getLevel() > Level.TRACE) {
+            return null;
+        }
+        return EcalliTraceLogger.new(defaultOutput);
+    }
+    /**
+     * Create a no-op IoTraceLogger that discards all output.
+     * Used when tracing is disabled.
+     */
+    static noop() {
+        return new EcalliTraceLogger(emptyOutput);
+    }
+    static new(output) {
+        return new EcalliTraceLogger(output);
+    }
+    constructor(output) {
+        this.output = output;
+    }
+    /**
+     * Log optional context lines (implementation metadata, execution environment).
+     */
+    logContext(context) {
+        this.output(context);
+    }
+    /**
+     * Log the program blob being executed and the write data (if any)
+     *
+     * Format: `program {hex-encoded-program-with-metadata}`
+     * Format: `memwrite {hex-encoded-address} len={blob-byte-length} <- {hex-encoded-bytes}`
+     */
+    logProgram(program, args) {
+        const SPI_ARGS_SEGMENT = 0xfe_ff_00_00;
+        this.output(`program ${BytesBlob.blobFrom(program)}`);
+        if (args.length > 0) {
+            this.output(`memwrite ${toHexAddress(SPI_ARGS_SEGMENT)} len=${args.length} <- ${BytesBlob.blobFrom(args)}`);
+        }
+    }
+    /**
+     * Log initial execution state (prelude).
+     *
+     * Format: `start pc={pc} gas={gas} {register-dump}`
+     */
+    logStart(pc, gas, registers) {
+        const line = `start pc=${pc} gas=${gas} ${registers}`;
+        this.output(line);
+    }
+    /**
+     * Log ecalli invocation with register dump.
+     *
+     * Format: `ecalli={index} pc={pc} gas={gas} {register-dump}`
+     */
+    logEcalli(index, pc, gas, registers) {
+        const line = `ecalli=${index} pc=${pc} gas=${gas} ${registers}`;
+        this.output(line);
+    }
+    /**
+     * Log memory read operation.
+     *
+     * Format: `memread {hex-encoded-address} len={blob-byte-length} -> {hex-encoded-data-read}`
+     */
+    logMemRead(address, len, data) {
+        this.output(`memread ${toHexAddress(address)} len=${len} -> ${data}`);
+    }
+    /**
+     * Log memory write operation.
+     *
+     * Format: `memwrite {hex-encoded-address} len={blob-byte-length} <- {hex-encoded-bytes}`
+     */
+    logMemWrite(address, len, data) {
+        this.output(`memwrite ${toHexAddress(address)} len=${len} <- ${data}`);
+    }
+    /**
+     * Log register write operation.
+     *
+     * Format: `setreg r{idx} <- {hex-encoded-value}`
+     */
+    logSetReg(index, value) {
+        const paddedIdx = index.toString().padStart(2, "0");
+        this.output(`setreg r${paddedIdx} <- ${value.toString(16)}`);
+    }
+    /**
+     * Log gas overwrite operation.
+     *
+     * Format: `setgas <- {gas}`
+     */
+    logSetGas(gas) {
+        this.output(`setgas <- ${gas}`);
+    }
+    /**
+     * Log all host actions from a single ecalli invocation.
+     * Actions are logged in the order specified by JIP-6:
+     * 1. Memory reads (sorted by address)
+     * 2. Memory writes (sorted by address)
+     * 3. Register writes (sorted by index)
+     * 4. Gas overwrite
+     */
+    logHostActions(ioTracker, gasBefore, gasAfter) {
+        if (ioTracker === null) {
+            return;
+        }
+        const reads = ioTracker.reads.sort((a, b) => a.address - b.address);
+        for (const op of reads) {
+            this.logMemRead(op.address, op.len, op.hex);
+        }
+        const writes = ioTracker.writes.sort((a, b) => a.address - b.address);
+        for (const op of writes) {
+            this.logMemWrite(op.address, op.len, op.hex);
+        }
+        const sortedRegWrites = [...ioTracker.registers.entries()].sort((a, b) => a[0] - b[0]);
+        for (const op of sortedRegWrites) {
+            this.logSetReg(op[0], op[1]);
+        }
+        if (gasBefore !== gasAfter) {
+            this.logSetGas(gasAfter);
+        }
+    }
+    /**
+     * Log PANIC termination.
+     *
+     * Format: `PANIC={argument} pc={pc} gas={gas} {register-dump}`
+     */
+    logPanic(argument, pc, gas, registers) {
+        const line = `PANIC=${argument} pc=${pc} gas=${gas} ${registers}`;
+        this.output(line);
+    }
+    /**
+     * Log OOG (out of gas) termination.
+     *
+     * Format: `OOG pc={pc} gas={gas} {register-dump}`
+     */
+    logOog(pc, gas, registers) {
+        const line = `OOG pc=${pc} gas=${gas} ${registers}`;
+        this.output(line);
+    }
+    /**
+     * Log HALT termination.
+     *
+     * Format: `HALT pc={pc} gas={gas} {register-dump}`
+     */
+    logHalt(pc, gas, registers) {
+        const line = `HALT pc=${pc} gas=${gas} ${registers}`;
+        this.output(line);
+    }
+}
+/**
+ * Convert 32-bit address to 0x-prefixed hex string.
+ */
+function toHexAddress(address) {
+    return `0x${address.toString(16).padStart(8, "0")}`;
+}
+/**
+ * IoTracker implementation that records all I/O operations for trace logging.
+ *
+ * Stores memory reads, writes, and register modifications as hex-encoded strings
+ * for output via IoTraceLogger.
+ */
+export class IoTraceTracker {
+    /** Recorded memory read operations (address + hex data + len). */
+    reads = [];
+    /** Recorded memory write operations (address + hex data + len). */
+    writes = [];
+    /** Recorded register write operations (index -> value). */
+    registers = new Map();
+    setReg(idx, val) {
+        this.registers.set(idx, val);
+    }
+    memRead(address, data) {
+        this.reads.push({ address, hex: BytesBlob.blobFrom(data).toString(), len: data.length });
+    }
+    memWrite(address, data) {
+        this.writes.push({ address, hex: BytesBlob.blobFrom(data).toString(), len: data.length });
+    }
+    clear() {
+        this.reads.length = 0;
+        this.writes.length = 0;
+        this.registers.clear();
+    }
+}

package/packages/core/pvm-host-calls/ecalli-trace-logger.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ecalli-trace-logger.test.d.ts.map

package/packages/core/pvm-host-calls/ecalli-trace-logger.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecalli-trace-logger.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/ecalli-trace-logger.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-host-calls/ecalli-trace-logger.test.js

@@ -0,0 +1,231 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsU32, tryAsU64 } from "#@typeberry/numbers";
+import { NO_OF_REGISTERS, REGISTER_BYTE_SIZE, tryAsSmallGas } from "#@typeberry/pvm-interface";
+import { EcalliTraceLogger, IoTraceTracker } from "./ecalli-trace-logger.js";
+import { tryAsHostCallIndex } from "./host-call-handler.js";
+import { HostCallRegisters } from "./host-call-registers.js";
+/** Helper to create HostCallRegisters with specific values set. */
+function createRegisters(values) {
+    const bytes = new Uint8Array(NO_OF_REGISTERS * REGISTER_BYTE_SIZE);
+    const view = new DataView(bytes.buffer);
+    for (const [idx, value] of values) {
+        view.setBigUint64(idx * REGISTER_BYTE_SIZE, value, true);
+    }
+    return new HostCallRegisters(bytes);
+}
+describe("IoTraceLogger", () => {
+    describe("logProgram", () => {
+        it("formats program blob as hex", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logProgram(new Uint8Array([0x01, 0x02, 0xaa, 0xbb]), new Uint8Array());
+            assert.strictEqual(lines.length, 1);
+            assert.strictEqual(lines[0], "program 0x0102aabb");
+        });
+        it("handles empty program", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logProgram(new Uint8Array([]), new Uint8Array());
+            assert.strictEqual(lines[0], "program 0x");
+        });
+        it("logs args as initial memory write", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logProgram(new Uint8Array([0x01]), new Uint8Array([0x00, 0x01, 0x02]));
+            assert.strictEqual(lines.length, 2);
+            assert.strictEqual(lines[0], "program 0x01");
+            assert.strictEqual(lines[1], "memwrite 0xfeff0000 len=3 <- 0x000102");
+        });
+    });
+    describe("logStart", () => {
+        it("formats start with register dump", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map([
+                [7, 0x10n],
+                [9, 0x10000n],
+            ]));
+            logger.logStart(0, tryAsSmallGas(10000), regs);
+            assert.strictEqual(lines[0], "start pc=0 gas=10000 r07=10 r09=10000");
+        });
+        it("handles no non-zero registers", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map());
+            logger.logStart(42, tryAsSmallGas(5000), regs);
+            assert.strictEqual(lines[0], "start pc=42 gas=5000 ");
+        });
+    });
+    describe("logEcalli", () => {
+        it("formats ecalli with register dump", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map([
+                [1, 0x1n],
+                [3, 0x1000n],
+            ]));
+            logger.logEcalli(tryAsHostCallIndex(10), 42, tryAsSmallGas(10000), regs);
+            assert.strictEqual(lines[0], "ecalli=10 pc=42 gas=10000 r01=1 r03=1000");
+        });
+        it("omits zero registers", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map([
+                [0, 0n],
+                [1, 1n],
+            ]));
+            logger.logEcalli(tryAsHostCallIndex(5), 0, tryAsSmallGas(5000), regs);
+            assert.strictEqual(lines[0], "ecalli=5 pc=0 gas=5000 r01=1");
+        });
+        it("handles no non-zero registers", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map());
+            logger.logEcalli(tryAsHostCallIndex(0), 0, tryAsSmallGas(100), regs);
+            assert.strictEqual(lines[0], "ecalli=0 pc=0 gas=100 ");
+        });
+    });
+    describe("logMemRead", () => {
+        it("formats memory read", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logMemRead(0x1000, 4, "0x01020304");
+            assert.strictEqual(lines[0], "memread 0x00001000 len=4 -> 0x01020304");
+        });
+    });
+    describe("logMemWrite", () => {
+        it("formats memory write", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logMemWrite(0x2000, 2, "0xffee");
+            assert.strictEqual(lines[0], "memwrite 0x00002000 len=2 <- 0xffee");
+        });
+    });
+    describe("logSetReg", () => {
+        it("formats register write with padded index", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logSetReg(0, 0x100n);
+            assert.strictEqual(lines[0], "setreg r00 <- 100");
+        });
+        it("formats two-digit register index", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logSetReg(12, 0x4n);
+            assert.strictEqual(lines[0], "setreg r12 <- 4");
+        });
+    });
+    describe("logSetGas", () => {
+        it("formats gas write", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            logger.logSetGas(tryAsSmallGas(9950));
+            assert.strictEqual(lines[0], "setgas <- 9950");
+        });
+    });
+    describe("logHostActions", () => {
+        it("logs actions in correct order: reads, writes, regs, gas", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const tracker = new IoTraceTracker();
+            tracker.memWrite(tryAsU32(0x2000), new Uint8Array([0xab]));
+            tracker.memRead(tryAsU32(0x1000), new Uint8Array([0xcd]));
+            tracker.setReg(0, tryAsU64(0x100n));
+            logger.logHostActions(tracker, tryAsSmallGas(10000), tryAsSmallGas(9950));
+            assert.strictEqual(lines.length, 4);
+            assert.strictEqual(lines[0], "memread 0x00001000 len=1 -> 0xcd");
+            assert.strictEqual(lines[1], "memwrite 0x00002000 len=1 <- 0xab");
+            assert.strictEqual(lines[2], "setreg r00 <- 100");
+            assert.strictEqual(lines[3], "setgas <- 9950");
+        });
+        it("sorts reads by address", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const tracker = new IoTraceTracker();
+            tracker.memRead(tryAsU32(0x2000), new Uint8Array([0x01]));
+            tracker.memRead(tryAsU32(0x1000), new Uint8Array([0x02]));
+            logger.logHostActions(tracker, tryAsSmallGas(100), tryAsSmallGas(100));
+            assert.strictEqual(lines[0], "memread 0x00001000 len=1 -> 0x02");
+            assert.strictEqual(lines[1], "memread 0x00002000 len=1 -> 0x01");
+        });
+        it("skips setgas if unchanged", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const tracker = new IoTraceTracker();
+            logger.logHostActions(tracker, tryAsSmallGas(100), tryAsSmallGas(100));
+            assert.strictEqual(lines.length, 0);
+        });
+    });
+    describe("termination logging", () => {
+        it("logs HALT", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map([[0, 0x100n]]));
+            logger.logHalt(42, tryAsSmallGas(9920), regs);
+            assert.strictEqual(lines[0], "HALT pc=42 gas=9920 r00=100");
+        });
+        it("logs OOG", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map());
+            logger.logOog(100, tryAsSmallGas(0), regs);
+            assert.strictEqual(lines[0], "OOG pc=100 gas=0 ");
+        });
+        it("logs PANIC with argument", () => {
+            const lines = [];
+            const logger = EcalliTraceLogger.new((line) => lines.push(line));
+            const regs = createRegisters(new Map());
+            logger.logPanic(1, 50, tryAsSmallGas(500), regs);
+            assert.strictEqual(lines[0], "PANIC=1 pc=50 gas=500 ");
+        });
+    });
+    describe("noop logger", () => {
+        it("does not throw and produces no output", () => {
+            const logger = EcalliTraceLogger.noop();
+            logger.logContext("test");
+            logger.logProgram(new Uint8Array([1, 2, 3]), new Uint8Array());
+            logger.logSetGas(tryAsSmallGas(100));
+        });
+        it("returns null tracker", () => {
+            const logger = EcalliTraceLogger.noop();
+            const tracker = logger.tracker();
+            assert.strictEqual(tracker, null);
+        });
+    });
+    describe("IoTraceTracker", () => {
+        it("tracks memory reads", () => {
+            const tracker = new IoTraceTracker();
+            tracker.memRead(tryAsU32(0x1000), new Uint8Array([0x01, 0x02]));
+            tracker.memRead(tryAsU32(0x2000), new Uint8Array([0x03]));
+            assert.strictEqual(tracker.reads.length, 2);
+            assert.strictEqual(tracker.reads[0].address, 0x1000);
+            assert.strictEqual(tracker.reads[0].hex, "0x0102");
+        });
+        it("tracks memory writes", () => {
+            const tracker = new IoTraceTracker();
+            tracker.memWrite(tryAsU32(0x3000), new Uint8Array([0xaa, 0xbb]));
+            assert.strictEqual(tracker.writes.length, 1);
+            assert.strictEqual(tracker.writes[0].address, 0x3000);
+            assert.strictEqual(tracker.writes[0].hex, "0xaabb");
+        });
+        it("tracks register writes", () => {
+            const tracker = new IoTraceTracker();
+            tracker.setReg(5, tryAsU64(0x42n));
+            tracker.setReg(7, tryAsU64(0x100n));
+            assert.strictEqual(tracker.registers.size, 2);
+            assert.strictEqual(tracker.registers.get(5), tryAsU64(0x42n));
+            assert.strictEqual(tracker.registers.get(7), tryAsU64(0x100n));
+        });
+        it("clears all tracked data", () => {
+            const tracker = new IoTraceTracker();
+            tracker.memRead(tryAsU32(0x1000), new Uint8Array([0x01]));
+            tracker.memWrite(tryAsU32(0x2000), new Uint8Array([0x02]));
+            tracker.setReg(0, tryAsU64(0x100n));
+            tracker.clear();
+            assert.strictEqual(tracker.reads.length, 0);
+            assert.strictEqual(tracker.writes.length, 0);
+            assert.strictEqual(tracker.registers.size, 0);
+        });
+    });
+});