@fluffylabs/anan-as 1.1.3-c154c6b → 1.1.3-c185e54

package/README.md

@@ -48,9 +48,26 @@ import ananAs from '@fluffylabs/anan-as/release-mini';
 // make sure to call GC after multiple independent runs
 ananAs.__collect();
 
+// Release build with stub host functions (for standalone testing)
+import ananAs from '@fluffylabs/anan-as/release-stub';
+
+// Compiler module (for PVM bytecode compilation)
+import ananAs from '@fluffylabs/anan-as/compiler';
+```
+
+### Inline Builds
+
+Inline builds bundle the WASM binary directly into the JavaScript module (base64 encoded),
+eliminating the need to fetch a separate `.wasm` file:
+
+```javascript
+import ananAs from '@fluffylabs/anan-as/debug-inline';
+import ananAs from '@fluffylabs/anan-as/release-inline';
+import ananAs from '@fluffylabs/anan-as/release-mini-inline';
+import ananAs from '@fluffylabs/anan-as/release-stub-inline';
 ```
 
-## Raw Bindings
+### Raw Bindings
 
 Raw bindings give you direct access to WebAssembly exports
 without the JavaScript wrapper layer.
@@ -69,7 +86,6 @@ const module = await WebAssembly.instantiateStreaming(
   imports
 );
 const ananAs = await instantiate(module);
-
 ```
 
 ## Version Tags
@@ -105,24 +121,33 @@ To run the example in the browser at [http://localhost:3000](http://localhost:30
 npm run web
 ```
 
-To run JSON test vectors.
+To run tests:
 
 ```cmd
-npm start ./path/to/tests/*.json
+# Run AssemblyScript unit tests and trace replay tests
+npm test
+
+# Run W3F test vectors
+npm run test:w3f
+
+# Run gas cost tests
+npm run test:gas-cost
 ```
 
 ## CLI Usage
 
-The package includes a CLI tool for disassembling and running PVM bytecode:
+The package includes a CLI tool for disassembling, running, and replaying PVM bytecode:
 
 ```bash
 # Disassemble bytecode to assembly
 npx @fluffylabs/anan-as disassemble [--spi] [--no-metadata] <file.(jam|pvm|spi|bin)>
 
 # Run JAM programs
-npx @fluffylabs/anan-as run [--spi] [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <file.jam> [spi-args.bin]
+npx @fluffylabs/anan-as run [--spi] [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <file.jam> [spi-args.bin or hex]
 
-The `run` command executes PVM bytecode until it encounters a `halt` instruction or the first host call. For full execution including host call handling, use the disassemble command or other tooling.
+# Replay an ecalli trace
+# Learn more: https://github.com/tomusdrw/JIPs/blob/td-jip6-ecalliloggin/JIP-6.md
+npx @fluffylabs/anan-as replay-trace [--no-metadata] [--no-verify] [--no-logs] <trace.log>
 
 # Show help
 npx @fluffylabs/anan-as --help
@@ -130,18 +155,23 @@ npx @fluffylabs/anan-as disassemble --help
 npx @fluffylabs/anan-as run --help
 ```
 
+The `run` command executes PVM bytecode until it encounters a `halt` instruction or a host call.
+The `replay-trace` command re-executes an ecalli trace, replaying recorded host call responses.
+
 ### Commands
 
 - `disassemble`: Convert PVM bytecode to human-readable assembly
 - `run`: Execute PVM bytecode and show results
+- `replay-trace`: Re-execute an ecalli trace with recorded host call responses
 
 ### Flags
 
 - `--spi`: Treat input as JAM SPI format instead of generic PVM
 - `--no-metadata`: Input does not start with metadata
-- `--no-logs`: Disable execution logs (run command only)
+- `--no-logs`: Disable execution logs (run and replay-trace commands)
+- `--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: 0)
+- `--gas <number>`: Set initial gas amount (default: 10,000)
 - `--help`, `-h`: Show help information
 
 ### Examples
@@ -168,6 +198,13 @@ npx @fluffylabs/anan-as run --no-logs program.jam
 # Run a JAM program with custom initial PC and gas
 npx @fluffylabs/anan-as run --pc 100 --gas 10000 program.jam
 
-# Run SPI program with arguments
+# Run SPI program with arguments (file or hex)
 npx @fluffylabs/anan-as run --spi program.spi args.bin
+npx @fluffylabs/anan-as run --spi program.spi 0xdeadbeef
+
+# Replay an ecalli trace
+npx @fluffylabs/anan-as replay-trace trace.log
+
+# Replay without verification
+npx @fluffylabs/anan-as replay-trace --no-verify trace.log
 ```

package/dist/bin/index.js

@@ -2,18 +2,23 @@
 import { readFileSync } from "node:fs";
 import minimist from "minimist";
 import { disassemble, HasMetadata, InputKind, prepareProgram, runProgram } from "../build/release.js";
+import { replayTraceFile } from "./src/trace-replay.js";
+import { hexDecode, hexEncode } from "./src/utils.js";
 const HELP_TEXT = `Usage:
   anan-as disassemble [--spi] [--no-metadata] <file.(jam|pvm|spi|bin)>
   anan-as run [--spi] [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <file.jam> [spi-args.bin or hex]
+  anan-as replay-trace [--no-metadata] [--no-verify] [--no-logs] <trace.log>
 
 Commands:
   disassemble  Disassemble PVM bytecode to assembly
   run          Execute PVM bytecode
+  replay-trace  Re-execute a ecalli IO trace
 
 Flags:
   --spi          Treat input as JAM SPI format
   --no-metadata  Input does not contain metadata
-  --no-logs      Disable execution logs (run command only)
+  --no-logs      Disable execution logs
+  --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)
   --help, -h     Show this help message`;
@@ -33,6 +38,9 @@ function main() {
         case "run":
             handleRun(args.slice(1));
             break;
+        case "replay-trace":
+            handleReplayTrace(args.slice(1));
+            break;
         default:
             console.error(`Error: Unknown sub-command '${subCommand}'`);
             console.error("");
@@ -148,6 +156,47 @@ function handleRun(args) {
         process.exit(1);
     }
 }
+function handleReplayTrace(args) {
+    const parsed = minimist(args, {
+        boolean: ["metadata", "verify", "logs", "help"],
+        alias: { h: "help" },
+        default: { metadata: true, logs: true, verify: true },
+    });
+    if (parsed.help) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    const files = parsed._;
+    if (files.length === 0) {
+        console.error("Error: No trace file provided for replay-trace command.");
+        console.error("Usage: anan-as replay-trace [--no-metadata] [--no-verify] [--no-logs] <trace.log>");
+        process.exit(1);
+    }
+    if (files.length > 1) {
+        console.error("Error: Only one trace file can be replayed at a time.");
+        console.error("Usage: anan-as replay-trace [--no-metadata] [--no-verify] [--no-logs] <trace.log>");
+        process.exit(1);
+    }
+    const file = files[0];
+    const hasMetadata = parsed.metadata ? HasMetadata.Yes : HasMetadata.No;
+    const verify = parsed.verify;
+    const logs = parsed.logs;
+    try {
+        const summary = replayTraceFile(file, {
+            logs,
+            hasMetadata,
+            verify,
+        });
+        console.log(`✅ Replay complete: ${summary.ecalliCount} ecalli entries`);
+        console.log(`Status: ${summary.termination.type}`);
+        console.log(`Program counter: ${summary.termination.pc}`);
+        console.log(`Gas remaining: ${summary.termination.gas}`);
+    }
+    catch (error) {
+        console.error(`Error replaying trace ${file}:`, error);
+        process.exit(1);
+    }
+}
 function parseGas(parsed) {
     if (parsed.gas === undefined) {
         return BigInt(10_000);
@@ -212,27 +261,3 @@ function parsePc(parsed) {
     }
     return pcValue;
 }
-function hexEncode(result) {
-    return `0x${result.map((x) => x.toString(16).padStart(2, "0")).join("")}`;
-}
-function hexDecode(data) {
-    if (!data.startsWith("0x")) {
-        throw new Error("hex input must start with 0x");
-    }
-    const hex = data.substring(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 byteIndex = i / 2;
-        const value = parseInt(c, 16);
-        if (Number.isNaN(value)) {
-            throw new Error(`hexDecode: invalid hex pair "${c}" in data "${data}" for bytes[${byteIndex}]`);
-        }
-        bytes[byteIndex] = value;
-    }
-    return bytes;
-}

package/dist/bin/{fuzz.js → src/fuzz.js}

@@ -3,7 +3,7 @@ import "json-bigint-patch";
 import fs from "node:fs";
 import { tryAsGas } from "@typeberry/lib/pvm-interface";
 import { Interpreter } from "@typeberry/lib/pvm-interpreter";
-import { disassemble, HasMetadata, InputKind, prepareProgram, runProgram, wrapAsProgram } from "../build/release.js";
+import { disassemble, HasMetadata, InputKind, prepareProgram, runProgram, wrapAsProgram } from "../../build/release.js";
 const runNumber = 0;
 export function fuzz(data) {
     const gas = 200n;
@@ -56,30 +56,13 @@ export function fuzz(data) {
         throw e;
     }
 }
+import { hexEncode } from "./utils.js";
 function programHex(program) {
-    return Array.from(program)
-        .map((x) => x.toString(16).padStart(2, "0"))
-        .join("");
+    return hexEncode(Array.from(program), false);
 }
 function linkTo(programHex) {
     return `https://pvm.fluffylabs.dev/?program=0x${programHex}#/`;
 }
-const REGISTER_BYTE_WIDTH = 8;
-function _decodeRegisters(value) {
-    if (value.length === 0) {
-        return [];
-    }
-    if (value.length % REGISTER_BYTE_WIDTH !== 0) {
-        throw new Error(`Invalid register buffer size: ${value.length}`);
-    }
-    const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
-    const registerCount = value.length / REGISTER_BYTE_WIDTH;
-    const registers = new Array(registerCount);
-    for (let i = 0; i < registerCount; i++) {
-        registers[i] = view.getBigUint64(i * REGISTER_BYTE_WIDTH, true);
-    }
-    return registers;
-}
 function decodeRegistersFromTypeberry(vm) {
     const registers = [];
     // Try to get up to 13 registers (common register count)

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

@@ -0,0 +1,315 @@
+const NO_OF_REGISTERS = 13;
+// Access.Write = 2 from assembly/memory-page.ts
+const ACCESS_WRITE = 2;
+export const STATUS = {
+    OK: 255,
+    HALT: 0,
+    PANIC: 1,
+    FAULT: 2,
+    HOST: 3,
+    OOG: 4,
+};
+export const ARGS_SEGMENT_START = 0xfeff0000;
+const LINE_PATTERN = /(program\s+0x|memwrite\s+0x|start\s+pc=|ecalli=\d+|memread\s+0x|setreg\s+r\d+|setgas\s+<-|HALT\s+pc=|OOG\s+pc=|PANIC=)/;
+export function parseTrace(input) {
+    const lines = input.split(/\r?\n/);
+    let program = null;
+    const initialMemWrites = [];
+    let start = null;
+    const ecalliEntries = [];
+    let currentEntry = null;
+    let termination = null;
+    for (const rawLine of lines) {
+        const line = extractPayload(rawLine);
+        if (!line) {
+            continue;
+        }
+        if (line.startsWith("program ")) {
+            program = parseHexBytes(line.replace("program ", "").trim());
+            continue;
+        }
+        if (line.startsWith("memwrite ")) {
+            const memwrite = parseMemWrite(line);
+            if (currentEntry) {
+                currentEntry.memWrites.push(memwrite);
+            }
+            else {
+                initialMemWrites.push(memwrite);
+            }
+            continue;
+        }
+        if (line.startsWith("start ")) {
+            start = parseStart(line);
+            continue;
+        }
+        if (line.startsWith("ecalli=")) {
+            const entry = parseEcalli(line);
+            ecalliEntries.push(entry);
+            currentEntry = entry;
+            continue;
+        }
+        if (line.startsWith("memread ")) {
+            if (!currentEntry) {
+                throw new Error(`memread without active ecalli: ${line}`);
+            }
+            currentEntry.memReads.push(parseMemRead(line));
+            continue;
+        }
+        if (line.startsWith("setreg ")) {
+            if (!currentEntry) {
+                throw new Error(`setreg without active ecalli: ${line}`);
+            }
+            const setReg = parseSetReg(line);
+            currentEntry.setRegs.push(setReg);
+            continue;
+        }
+        if (line.startsWith("setgas ")) {
+            if (!currentEntry) {
+                throw new Error(`setgas without active ecalli: ${line}`);
+            }
+            currentEntry.setGas = parseSetGas(line);
+            continue;
+        }
+        if (line.startsWith("HALT ") || line.startsWith("OOG ") || line.startsWith("PANIC=")) {
+            termination = parseTermination(line);
+            currentEntry = null;
+        }
+    }
+    if (!program) {
+        throw new Error("Missing program line in trace");
+    }
+    if (!start) {
+        throw new Error("Missing start line in trace");
+    }
+    if (!termination) {
+        throw new Error("Missing termination line in trace");
+    }
+    return {
+        program,
+        initialMemWrites,
+        start,
+        ecalliEntries,
+        termination,
+    };
+}
+function extractPayload(line) {
+    const match = LINE_PATTERN.exec(line);
+    if (!match || match.index === undefined) {
+        return null;
+    }
+    return line.slice(match.index).trim();
+}
+function parseStart(line) {
+    const match = /^start pc=(\d+) gas=(\d+)(.*)$/.exec(line);
+    if (!match) {
+        throw new Error(`Invalid start line: ${line}`);
+    }
+    return {
+        pc: parseInt(match[1], 10),
+        gas: BigInt(match[2]),
+        registers: parseRegisterDump(match[3]),
+    };
+}
+function parseEcalli(line) {
+    const match = /^ecalli=(\d+) pc=(\d+) gas=(\d+)(.*)$/.exec(line);
+    if (!match) {
+        throw new Error(`Invalid ecalli line: ${line}`);
+    }
+    return {
+        index: parseInt(match[1], 10),
+        pc: parseInt(match[2], 10),
+        gas: BigInt(match[3]),
+        registers: parseRegisterDump(match[4]),
+        memReads: [],
+        memWrites: [],
+        setRegs: [],
+    };
+}
+function parseMemWrite(line) {
+    const match = /^memwrite\s+0x([0-9a-f]+)\s+len=(\d+)\s+<-\s+0x([0-9a-f]+)$/i.exec(line);
+    if (!match) {
+        throw new Error(`Invalid memwrite line: ${line}`);
+    }
+    const address = parseInt(match[1], 16);
+    const data = parseHexBytes(`0x${match[3]}`);
+    const len = parseInt(match[2], 10);
+    if (data.length !== len) {
+        throw new Error(`memwrite length mismatch: expected ${len}, got ${data.length}`);
+    }
+    return { address, data };
+}
+function parseMemRead(line) {
+    const match = /^memread\s+0x([0-9a-f]+)\s+len=(\d+)\s+->\s+0x([0-9a-f]+)$/i.exec(line);
+    if (!match) {
+        throw new Error(`Invalid memread line: ${line}`);
+    }
+    const address = parseInt(match[1], 16);
+    const data = parseHexBytes(`0x${match[3]}`);
+    const len = parseInt(match[2], 10);
+    if (data.length !== len) {
+        throw new Error(`memread length mismatch: expected ${len}, got ${data.length}`);
+    }
+    return { address, data };
+}
+function parseSetReg(line) {
+    const match = /^setreg\s+r(\d+)\s+<-\s+0x([0-9a-f]+)$/i.exec(line);
+    if (!match) {
+        throw new Error(`Invalid setreg line: ${line}`);
+    }
+    const index = parseInt(match[1], 10);
+    if (index < 0 || index >= NO_OF_REGISTERS) {
+        throw new Error(`Register index out of range: ${index}`);
+    }
+    return {
+        index,
+        value: BigInt(`0x${match[2]}`),
+    };
+}
+function parseSetGas(line) {
+    const match = /^setgas\s+<-\s+(\d+)$/i.exec(line);
+    if (!match) {
+        throw new Error(`Invalid setgas line: ${line}`);
+    }
+    return BigInt(match[1]);
+}
+function parseTermination(line) {
+    if (line.startsWith("HALT ")) {
+        const match = /^HALT pc=(\d+) gas=(\d+)(.*)$/.exec(line);
+        if (!match) {
+            throw new Error(`Invalid HALT line: ${line}`);
+        }
+        return {
+            type: "HALT",
+            pc: parseInt(match[1], 10),
+            gas: BigInt(match[2]),
+            registers: parseRegisterDump(match[3]),
+        };
+    }
+    if (line.startsWith("OOG ")) {
+        const match = /^OOG pc=(\d+) gas=(\d+)(.*)$/.exec(line);
+        if (!match) {
+            throw new Error(`Invalid OOG line: ${line}`);
+        }
+        return {
+            type: "OOG",
+            pc: parseInt(match[1], 10),
+            gas: BigInt(match[2]),
+            registers: parseRegisterDump(match[3]),
+        };
+    }
+    if (line.startsWith("PANIC=")) {
+        const match = /^PANIC=([^\s]+) pc=(\d+) gas=(\d+)(.*)$/.exec(line);
+        if (!match) {
+            throw new Error(`Invalid PANIC line: ${line}`);
+        }
+        return {
+            type: "PANIC",
+            pc: parseInt(match[2], 10),
+            gas: BigInt(match[3]),
+            registers: parseRegisterDump(match[4]),
+            panicArg: parseNumber(match[1]),
+        };
+    }
+    throw new Error(`Unknown termination line: ${line}`);
+}
+function parseRegisterDump(input) {
+    const dump = new Map();
+    const regex = /r(\d+)=0x([0-9a-f]+)/gi;
+    for (const match of input.matchAll(regex)) {
+        const index = parseInt(match[1], 10);
+        if (index < 0 || index >= NO_OF_REGISTERS) {
+            throw new Error(`Register index out of range: ${index}`);
+        }
+        const value = BigInt(`0x${match[2]}`);
+        dump.set(index, value);
+    }
+    return dump;
+}
+function parseHexBytes(hex) {
+    if (!hex.startsWith("0x")) {
+        throw new Error(`Hex value must start with 0x: ${hex}`);
+    }
+    const data = hex.slice(2);
+    if (data.length % 2 !== 0) {
+        throw new Error(`Hex value must have even length: ${hex}`);
+    }
+    const bytes = new Uint8Array(data.length / 2);
+    for (let i = 0; i < data.length; i += 2) {
+        const pair = data.slice(i, i + 2);
+        if (!/^[0-9a-fA-F]{2}$/.test(pair)) {
+            throw new Error(`Invalid hex pair "${pair}" in hex value: ${hex}`);
+        }
+        bytes[i / 2] = Number.parseInt(pair, 16);
+    }
+    return bytes;
+}
+export function encodeRegistersFromDump(dump) {
+    const registers = new Array(NO_OF_REGISTERS).fill(0n);
+    for (const [index, value] of dump) {
+        registers[index] = value;
+    }
+    return registers;
+}
+export function buildInitialPages(memWrites) {
+    return memWrites
+        .filter((write) => write.data.length > 0)
+        .map((write) => ({
+        address: write.address,
+        length: write.data.length,
+        access: ACCESS_WRITE,
+    }));
+}
+export function buildInitialChunks(memWrites) {
+    return memWrites
+        .filter((write) => write.data.length > 0)
+        .map((write) => ({
+        address: write.address,
+        data: Array.from(write.data),
+    }));
+}
+export function isSpiTrace(start, memWrites) {
+    const r07 = start.registers.get(7);
+    if (r07 === BigInt(ARGS_SEGMENT_START)) {
+        return true;
+    }
+    return memWrites.some((write) => write.address === ARGS_SEGMENT_START);
+}
+export function extractSpiArgs(start, memWrites) {
+    const argLenBig = start.registers.get(8) ?? 0n;
+    // Validate bounds: must be non-negative and <= 1 MiB (2^20)
+    const MAX_ARG_LEN = 1n << 20n;
+    if (argLenBig < 0n || argLenBig > MAX_ARG_LEN) {
+        return new Uint8Array(0);
+    }
+    const argLen = Number(argLenBig);
+    if (argLen <= 0) {
+        return new Uint8Array(0);
+    }
+    const buffer = new Uint8Array(argLen);
+    for (const write of memWrites) {
+        if (write.address < ARGS_SEGMENT_START) {
+            continue;
+        }
+        const offset = write.address - ARGS_SEGMENT_START;
+        if (offset >= buffer.length) {
+            continue;
+        }
+        buffer.set(write.data.subarray(0, buffer.length - offset), offset);
+    }
+    return buffer;
+}
+export function statusToTermination(status) {
+    if (status === STATUS.HALT) {
+        return "HALT";
+    }
+    if (status === STATUS.OOG) {
+        return "OOG";
+    }
+    return "PANIC";
+}
+function parseNumber(value) {
+    if (value.startsWith("0x")) {
+        return Number.parseInt(value, 16);
+    }
+    return Number.parseInt(value, 10);
+}