@fluffylabs/anan-as 1.2.0-9723cd9 → 1.2.0-9f08a39

package/dist/bin/index.js

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { disassemble, HasMetadata, InputKind, prepareProgram, pvmDestroy, pvmResume, pvmSetRegisters, pvmStart, } from "../build/release.js";
+import { disassemble, HasMetadata, InputKind, prepareProgram, pvmDestroy, pvmReadMemory, pvmResume, pvmSetRegisters, pvmStart, } from "../build/release.js";
 import { LOG_GAS_COST, LOG_HOST_CALL_INDEX, printLogHostCall, WHAT } from "./src/log-host-call.js";
 import { STATUS } from "./src/trace-parse.js";
 import { replayTraceFile } from "./src/trace-replay.js";
 import { hexDecode, hexEncode } from "./src/utils.js";
+// Page access modes (matches assembly/memory-page.ts Access enum)
+const ACCESS_READ = 1;
+const ACCESS_WRITE = 2;
 const HELP_TEXT = `Usage:
   anan-as disassemble [--spi] [--no-metadata] <file.(jam|pvm|spi|bin)>
-  anan-as run [--spi] [--no-logs] [--no-metadata] [--no-log-host-call] [--pc <number>] [--gas <number>] <file.jam> [spi-args.bin or hex]
+  anan-as run [--spi] [--no-logs] [--no-metadata] [--no-log-host-call] [--pc <number>] [--gas <number>] [--regs <r0,r1,...,r12>] <file.jam> [spi-args.bin or hex]
   anan-as replay-trace [--no-metadata] [--no-verify] [--no-logs] [--no-log-host-call] <trace.log>
 
 Commands:
@@ -24,6 +27,10 @@ Flags:
   --no-verify         Skip verification against trace data (replay-trace only)
   --pc <number>       Set initial program counter (default: 0)
   --gas <number>      Set initial gas amount (default: 10_000)
+  --regs <values>     Set initial registers (comma-separated, 13 values: r0,r1,...,r12; supports decimal and 0x hex)
+  --pages <specs>     Add memory pages (semicolon-separated: "addr:size;addr:size:ro"; append ":r" or ":ro" for read-only)
+  --mem <specs>       Initialize memory (semicolon-separated: "addr:hex_bytes;addr:hex_bytes")
+  --dump <specs>      Dump memory after execution (semicolon-separated: "addr:len;addr:len")
   --help, -h          Show this help message`;
 main();
 function main() {
@@ -84,7 +91,7 @@ function handleDisassemble(args) {
         console.error("Supported extensions: .jam, .pvm, .spi, .bin");
         process.exit(1);
     }
-    const ext = file.substring(dotIndex);
+    const ext = file.slice(dotIndex);
     if (!validExtensions.includes(ext)) {
         console.error(`Error: Invalid file extension '${ext}' for disassemble command.`);
         console.error("Supported extensions: .jam, .pvm, .spi, .bin");
@@ -109,6 +116,10 @@ function handleRun(args) {
             help: { type: "boolean", short: "h", default: false },
             pc: { type: "string" },
             gas: { type: "string" },
+            regs: { type: "string" },
+            pages: { type: "string" },
+            mem: { type: "string" },
+            dump: { type: "string" },
         },
     });
     if (values.help) {
@@ -150,13 +161,17 @@ function handleRun(args) {
     // Parse and validate PC and gas options
     const initialPc = parsePc(values.pc);
     const initialGas = parseGas(values.gas);
+    const initialRegisters = parseRegs(values.regs);
+    const initialPages = parsePages(values.pages);
+    const initialMemory = parseMem(values.mem);
+    const dumpRegions = parseDump(values.dump);
     const programCode = Array.from(readFileSync(programFile));
     const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
     console.log(`🚀 Running ${programFile} (as ${name})`);
     try {
         const preallocateMemoryPages = 128;
         const useBlockGas = true;
-        const program = prepareProgram(kind, hasMetadata, programCode, [], [], [], spiArgs, preallocateMemoryPages, useBlockGas);
+        const program = prepareProgram(kind, hasMetadata, programCode, initialRegisters, initialPages, initialMemory, spiArgs, preallocateMemoryPages, useBlockGas);
         const id = pvmStart(program);
         let gas = initialGas;
         let pc = initialPc;
@@ -180,6 +195,24 @@ function handleRun(args) {
                 break;
             }
         }
+        // Dump memory regions before destroying the VM
+        for (const region of dumpRegions) {
+            const data = pvmReadMemory(id, region.address, region.length);
+            const addrHex = `0x${region.address.toString(16)}`;
+            if (data) {
+                console.log(`\nMemory @ ${addrHex} (${region.length} bytes):`);
+                for (let off = 0; off < data.length; off += 16) {
+                    const addr = region.address + off;
+                    const slice = Array.from(data.slice(off, Math.min(off + 16, data.length)));
+                    const hex = slice.map((b) => b.toString(16).padStart(2, "0")).join(" ");
+                    const ascii = slice.map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : ".")).join("");
+                    console.log(`  ${addr.toString(16).padStart(8, "0")}:  ${hex.padEnd(47)}  ${ascii}`);
+                }
+            }
+            else {
+                console.log(`\nMemory @ ${addrHex}: <page fault>`);
+            }
+        }
         const result = pvmDestroy(id);
         console.log(`Status: ${result?.status}`);
         console.log(`Exit code: ${result?.exitCode}`);
@@ -293,3 +326,102 @@ function parsePc(pcStr) {
     }
     return pcValue;
 }
+function parseRegs(regsStr) {
+    if (regsStr === undefined) {
+        return [];
+    }
+    const parts = regsStr.split(",");
+    if (parts.length !== 13) {
+        throw new Error(`--regs must have exactly 13 comma-separated values (got ${parts.length}).\nFormat: --regs r0,r1,r2,r3,r4,r5,r6,r7,r8,r9,r10,r11,r12`);
+    }
+    return parts.map((s, i) => {
+        try {
+            return BigInt.asUintN(64, BigInt(s.trim()));
+        }
+        catch (_e) {
+            throw new Error(`--regs value at index ${i} ("${s.trim()}") is not a valid integer.`);
+        }
+    });
+}
+function parseNum(s) {
+    return Number(s.trim());
+}
+function parsePages(pagesStr) {
+    if (pagesStr === undefined) {
+        return [];
+    }
+    // Format: "addr:size;addr:size" — all pages are writable
+    // Or "addr:size:ro" (or "addr:size:r") for read-only
+    const specs = pagesStr.split(";").filter((s) => s.trim().length > 0);
+    return specs.map((spec, i) => {
+        const parts = spec.split(":");
+        if (parts.length < 2 || parts.length > 3) {
+            throw new Error(`--pages entry ${i} ("${spec}") must be "addr:size" or "addr:size:ro" (or "addr:size:r").`);
+        }
+        const address = parseNum(parts[0]);
+        const length = parseNum(parts[1]);
+        const flag = parts[2]?.trim();
+        const access = flag === "ro" || flag === "r" ? ACCESS_READ : ACCESS_WRITE;
+        if (Number.isNaN(address) || Number.isNaN(length) || length <= 0) {
+            throw new Error(`--pages entry ${i} ("${spec}") has invalid address or size.`);
+        }
+        return { address, length, access };
+    });
+}
+function parseMem(memStr) {
+    if (memStr === undefined) {
+        return [];
+    }
+    // Format: "addr:hexbytes;addr:hexbytes"
+    // Example: "0x20000:0500000000000000;0x20008:0300000000000000"
+    const specs = memStr.split(";").filter((s) => s.trim().length > 0);
+    return specs.map((spec, i) => {
+        const colonIdx = spec.indexOf(":");
+        if (colonIdx === -1) {
+            throw new Error(`--mem entry ${i} ("${spec}") must be "addr:hexbytes".`);
+        }
+        const addrStr = spec.slice(0, colonIdx).trim();
+        let hexStr = spec.slice(colonIdx + 1).trim();
+        const address = parseNum(addrStr);
+        if (Number.isNaN(address)) {
+            throw new Error(`--mem entry ${i} has invalid address "${addrStr}".`);
+        }
+        // Strip 0x prefix from hex data
+        if (hexStr.startsWith("0x") || hexStr.startsWith("0X")) {
+            hexStr = hexStr.slice(2);
+        }
+        if (hexStr.length % 2 !== 0) {
+            throw new Error(`--mem entry ${i} hex data has odd length.`);
+        }
+        const data = [];
+        for (let j = 0; j < hexStr.length; j += 2) {
+            const pair = hexStr.slice(j, j + 2);
+            if (!/^[0-9a-fA-F]{2}$/.test(pair)) {
+                throw new Error(`--mem entry ${i} has invalid hex byte at position ${j}: "${pair}".`);
+            }
+            const byte = parseInt(pair, 16);
+            data.push(byte);
+        }
+        return { address, data };
+    });
+}
+function parseDump(dumpStr) {
+    if (dumpStr === undefined) {
+        return [];
+    }
+    // Format: "addr:len;addr:len"
+    // Example: "0x20000:64;0x20100:32"
+    const specs = dumpStr.split(";").filter((s) => s.trim().length > 0);
+    return specs.map((spec, i) => {
+        const parts = spec.split(":");
+        if (parts.length !== 2) {
+            throw new Error(`--dump entry ${i} ("${spec}") must be "addr:len".`);
+        }
+        const address = parseNum(parts[0]);
+        const length = parseNum(parts[1]);
+        if (Number.isNaN(address) || Number.isNaN(length) || length <= 0) {
+            throw new Error(`--dump entry ${i} ("${spec}") has invalid address or length.`);
+        }
+        return { address, length };
+    });
+}

package/dist/bin/src/trace-parse.js

@@ -1,3 +1,4 @@
+// Trace format: https://github.com/FluffyLabs/jam-ecalli-trace/blob/main/ecalli-trace-jip.md
 const NO_OF_REGISTERS = 13;
 // Access.Write = 2 from assembly/memory-page.ts
 const ACCESS_WRITE = 2;

package/dist/bin/src/trace-replay.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import * as defaultPvm from "../../build/release.js";
 import { LOG_HOST_CALL_INDEX, printLogHostCall } from "./log-host-call.js";
-import { ARGS_SEGMENT_START, buildInitialChunks, buildInitialPages, encodeRegistersFromDump, extractSpiArgs, isSpiTrace, parseTrace, STATUS, statusToTermination, } from "./trace-parse.js";
+import { buildInitialChunks, buildInitialPages, encodeRegistersFromDump, extractSpiArgs, isSpiTrace, parseTrace, STATUS, statusToTermination, } from "./trace-parse.js";
 import { ConsoleTracer } from "./tracer.js";
 import { hexEncode } from "./utils.js";
 export function replayTraceFile(filePath, options) {
@@ -25,11 +25,12 @@ export function replayTraceFile(filePath, options) {
     try {
         let gas = start.gas;
         let pc = start.pc;
-        // Print start line
-        tracer.start(pc, gas, start.registers);
-        if (spiArgs.length > 0) {
-            tracer.spiArgs(ARGS_SEGMENT_START, spiArgs);
+        // Print prelude: program, initial memwrites, start
+        tracer.program(program);
+        for (const write of initialMemWrites) {
+            tracer.memwrite(write.address, write.data);
         }
+        tracer.start(pc, gas, start.registers);
         for (;;) {
             const pause = pvmResume(id, gas, pc, options.logs);
             if (!pause) {

package/dist/bin/src/tracer.js

@@ -1,29 +1,29 @@
-import { hexEncode } from "./utils.js";
+// Trace output format: https://github.com/FluffyLabs/jam-ecalli-trace/blob/main/ecalli-trace-jip.md
 export class ConsoleTracer {
+    program(data) {
+        console.log(`program ${formatHex(data)}`);
+    }
     start(pc, gas, registers) {
         console.log(`start pc=${pc} gas=${gas} ${formatRegisters(registers)}`);
     }
-    spiArgs(address, data) {
-        console.log(`  memwrite ${address} len=${data.length} <- ${hexEncode(data)}`);
-    }
     ecalli(index, pc, gas, registers) {
-        console.log(`\necalli=${index} pc=${pc} gas=${gas} ${formatRegisters(registers)}`);
+        console.log(`ecalli=${index} pc=${pc} gas=${gas} ${formatRegisters(registers)}`);
     }
     memread(address, data) {
-        console.log(`  memread 0x${address.toString(16)} len=${data.length} -> ${formatHex(data)}`);
+        console.log(` memread ${formatAddress(address)} len=${data.length} -> ${formatHex(data)}`);
     }
     memwrite(address, data) {
-        console.log(`  memwrite 0x${address.toString(16)} len=${data.length} <- ${formatHex(data)}`);
+        console.log(` memwrite ${formatAddress(address)} len=${data.length} <- ${formatHex(data)}`);
     }
     setreg(index, value) {
-        console.log(`  setreg r${index.toString().padStart(2, "0")} <- 0x${value.toString(16)}`);
+        console.log(` setreg r${index.toString().padStart(2, "0")} <- 0x${value.toString(16)}`);
     }
     setgas(gas) {
-        console.log(`  setgas <- ${gas}`);
+        console.log(` setgas <- ${gas}`);
     }
     termination(type, exitCode, pc, gas, registers) {
-        let termLine = `\n------\n${type}`;
-        if (type === "PANIC" && exitCode !== 0) {
+        let termLine = `${type}`;
+        if (type === "PANIC") {
             termLine += `=${exitCode}`;
         }
         termLine += ` pc=${pc} gas=${gas} ${formatRegisters(registers)}`;
@@ -31,8 +31,8 @@ export class ConsoleTracer {
     }
 }
 export class NoOpTracer {
+    program() { }
     start() { }
-    spiArgs() { }
     ecalli() { }
     memread() { }
     memwrite() { }
@@ -56,9 +56,12 @@ function formatRegisters(registers) {
     }
     return entries
         .sort((a, b) => a.idx - b.idx)
-        .map((e) => `r${e.idx}=0x${e.val.toString(16)}`)
+        .map((e) => `r${e.idx.toString().padStart(2, "0")}=0x${e.val.toString(16)}`)
         .join(" ");
 }
+function formatAddress(address) {
+    return `0x${Number(address).toString(16).padStart(8, "0")}`;
+}
 function formatHex(data) {
     return `0x${Buffer.from(data).toString("hex")}`;
 }

package/dist/bin/src/utils.js

@@ -6,14 +6,14 @@ export function hexDecode(data) {
     if (!data.startsWith("0x")) {
         throw new Error("hex input must start with 0x");
     }
-    const hex = data.substring(2);
+    const hex = data.slice(2);
     const len = hex.length;
     if (len % 2 === 1) {
         throw new Error("Odd number of nibbles");
     }
     const bytes = new Uint8Array(len / 2);
     for (let i = 0; i < len; i += 2) {
-        const c = hex.substring(i, i + 2);
+        const c = hex.slice(i, i + 2);
         const byteIndex = i / 2;
         if (!/^[0-9a-fA-F]{2}$/.test(c)) {
             throw new Error(`hexDecode: invalid hex pair "${c}" in data "${data}" for bytes[${byteIndex}]`);