@fluffylabs/anan-as 1.1.3-e3864a9 → 1.1.3-eee81bd

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

@@ -1,22 +1,30 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import minimist from "minimist";
-import { disassemble, HasMetadata, InputKind, prepareProgram, runProgram } from "../build/release.js";
+import { disassemble, HasMetadata, InputKind, prepareProgram, pvmDestroy, 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";
 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]
+  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 replay-trace [--no-metadata] [--no-verify] [--no-logs] [--no-log-host-call] <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)
-  --pc <number>  Set initial program counter (default: 0)
-  --gas <number> Set initial gas amount (default: 0)
-  --help, -h     Show this help message`;
+  --spi               Treat input as JAM SPI format
+  --no-metadata       Input does not contain metadata
+  --no-logs           Disable execution logs
+  --no-log-host-call  Disable built-in handling of JIP-1 log host call (ecalli 100)
+  --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`;
 main();
 function main() {
     const args = process.argv.slice(2);
@@ -33,6 +41,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("");
@@ -42,8 +53,9 @@ function main() {
 }
 function handleDisassemble(args) {
     const parsed = minimist(args, {
-        boolean: ["spi", "no-metadata", "help"],
+        boolean: ["spi", "metadata", "help"],
         alias: { h: "help" },
+        default: { metadata: true },
     });
     if (parsed.help) {
         console.log(HELP_TEXT);
@@ -76,7 +88,7 @@ function handleDisassemble(args) {
         process.exit(1);
     }
     const kind = parsed.spi ? InputKind.SPI : InputKind.Generic;
-    const hasMetadata = parsed["no-metadata"] ? HasMetadata.No : HasMetadata.Yes;
+    const hasMetadata = parsed.metadata ? HasMetadata.Yes : HasMetadata.No;
     const f = readFileSync(file);
     const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
     console.log(`🤖 Assembly of ${file} (as ${name})`);
@@ -84,9 +96,11 @@ function handleDisassemble(args) {
 }
 function handleRun(args) {
     const parsed = minimist(args, {
-        boolean: ["spi", "no-logs", "no-metadata", "help"],
-        string: ["pc", "gas"],
+        boolean: ["spi", "logs", "metadata", "help", "log-host-call"],
+        /** Prevents parsing hex values as numbers. */
+        string: ["pc", "gas", "_"],
         alias: { h: "help" },
+        default: { metadata: true, logs: true, "log-host-call": true },
     });
     if (parsed.help) {
         console.log(HELP_TEXT);
@@ -100,16 +114,16 @@ function handleRun(args) {
     }
     const kind = parsed.spi ? InputKind.SPI : InputKind.Generic;
     let programFile;
-    let spiArgsFile;
+    let spiArgsStr;
     if (kind === InputKind.SPI) {
-        // For SPI programs, expect: <program.spi> [spi-args.bin]
+        // For SPI programs, expect: <program.spi> [spi-args.bin or hex]
         if (files.length > 2) {
             console.error("Error: Too many arguments for SPI run command.");
-            console.error("Usage: anan-as run --spi [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <program.spi> [spi-args.bin]");
+            console.error("Usage: anan-as run --spi [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <program.spi> [spi-args.bin or hex]");
             process.exit(1);
         }
         programFile = files[0];
-        spiArgsFile = files[1]; // optional
+        spiArgsStr = files[1]; // optional
     }
     else {
         // For generic programs, expect exactly one file
@@ -120,101 +134,159 @@ function handleRun(args) {
         }
         programFile = files[0];
     }
-    // Validate program file extension
-    const expectedExt = kind === InputKind.SPI ? ".spi" : ".jam";
-    const dotIndex = programFile.lastIndexOf(".");
-    if (dotIndex === -1) {
-        console.error(`Error: File '${programFile}' has no extension.`);
-        console.error(`Expected: ${expectedExt}`);
-        process.exit(1);
+    // Validate SPI args file if provided
+    const spiArgs = parseSpiArgs(spiArgsStr);
+    const logs = parsed.logs;
+    const logHostCall = parsed["log-host-call"];
+    const hasMetadata = parsed.metadata ? HasMetadata.Yes : HasMetadata.No;
+    // Parse and validate PC and gas options
+    const initialPc = parsePc(parsed);
+    const initialGas = parseGas(parsed);
+    const programCode = Array.from(readFileSync(programFile));
+    const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
+    console.log(`🚀 Running ${programFile} (as ${name})`);
+    try {
+        const program = prepareProgram(kind, hasMetadata, programCode, [], [], [], spiArgs);
+        const id = pvmStart(program, false);
+        let gas = initialGas;
+        let pc = initialPc;
+        for (;;) {
+            const pause = pvmResume(id, gas, pc, logs);
+            if (!pause) {
+                throw new Error("pvmResume returned null");
+            }
+            if (pause.status === STATUS.HOST && pause.exitCode === LOG_HOST_CALL_INDEX && logHostCall) {
+                printLogHostCall(id, pause.registers);
+                // Set r7 = WHAT
+                const regs = pause.registers;
+                regs[7] = WHAT;
+                pvmSetRegisters(id, regs);
+                // Deduct gas and advance PC
+                gas = pause.gas >= LOG_GAS_COST ? pause.gas - LOG_GAS_COST : 0n;
+                pc = pause.nextPc;
+            }
+            else {
+                console.warn(`Unhandled host call: ecalli ${pause.exitCode}. Finishing.`);
+                break;
+            }
+        }
+        const result = pvmDestroy(id);
+        console.log(`Status: ${result?.status}`);
+        console.log(`Exit code: ${result?.exitCode}`);
+        console.log(`Program counter: ${result?.pc}`);
+        console.log(`Gas remaining: ${result?.gas}`);
+        console.log(`Registers: [${result?.registers.join(", ")}]`);
+        console.log(`Result: [${hexEncode(result?.result ?? [])}]`);
     }
-    const ext = programFile.substring(dotIndex);
-    if (ext !== expectedExt) {
-        console.error(`Error: Invalid file extension '${ext}' for run command.`);
-        console.error(`Expected: ${expectedExt}`);
+    catch (error) {
+        console.error(`Error running ${programFile}:`, error);
         process.exit(1);
     }
-    // Validate SPI args file if provided
-    let spiArgs;
-    if (spiArgsFile) {
-        const argsDotIndex = spiArgsFile.lastIndexOf(".");
-        if (argsDotIndex === -1) {
-            console.error(`Error: SPI args file '${spiArgsFile}' has no extension.`);
-            console.error(`Expected: .bin`);
-            process.exit(1);
-        }
-        const argsExt = spiArgsFile.substring(argsDotIndex);
-        if (argsExt !== ".bin") {
-            console.error(`Error: SPI args file must have .bin extension, got '${argsExt}'.`);
-            process.exit(1);
-        }
-        spiArgs = new Uint8Array(readFileSync(spiArgsFile));
+}
+function handleReplayTrace(args) {
+    const parsed = minimist(args, {
+        boolean: ["metadata", "verify", "logs", "help", "log-host-call"],
+        alias: { h: "help" },
+        default: { metadata: true, logs: true, verify: true, "log-host-call": true },
+    });
+    if (parsed.help) {
+        console.log(HELP_TEXT);
+        return;
     }
-    const logs = !parsed["no-logs"];
-    const hasMetadata = parsed["no-metadata"] ? HasMetadata.No : HasMetadata.Yes;
-    // Parse and validate PC and gas options
-    let initialPc = 0;
-    if (parsed.pc !== undefined) {
-        // Ensure it's a string/number, not boolean
-        if (typeof parsed.pc === "boolean") {
-            console.error("Error: --pc requires a value.");
-            process.exit(1);
-        }
-        const pcStr = String(parsed.pc);
-        // Reject floats and non-integer strings
-        if (pcStr.includes(".") || !/^-?\d+$/.test(pcStr)) {
-            console.error("Error: --pc must be a valid integer.");
-            process.exit(1);
-        }
-        const pcValue = parseInt(pcStr, 10);
-        if (!Number.isInteger(pcValue) || pcValue < 0 || pcValue > 0xffffffff) {
-            console.error("Error: --pc must be a non-negative integer <= 2^32-1.");
-            process.exit(1);
-        }
-        initialPc = pcValue;
+    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);
     }
-    let initialGas = BigInt(0);
-    if (parsed.gas !== undefined) {
-        // Ensure it's a string/number, not boolean
-        if (typeof parsed.gas === "boolean") {
-            console.error("Error: --gas requires a value.");
-            process.exit(1);
-        }
-        const gasStr = String(parsed.gas);
-        // Reject floats and non-integer strings
-        if (gasStr.includes(".") || !/^-?\d+$/.test(gasStr)) {
-            console.error("Error: --gas must be a valid integer.");
-            process.exit(1);
-        }
-        let gasValue;
-        try {
-            gasValue = BigInt(gasStr);
-        }
-        catch (_e) {
-            console.error("Error: --gas must be a valid integer.");
-            process.exit(1);
-        }
-        const MAX_I64 = (1n << 63n) - 1n;
-        if (gasValue < 0n || gasValue > MAX_I64) {
-            console.error("Error: --gas must be a non-negative integer <= 2^63-1.");
-            process.exit(1);
-        }
-        initialGas = gasValue;
+    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 f = readFileSync(programFile);
-    const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
-    console.log(`🚀 Running ${programFile} (as ${name})`);
+    const file = files[0];
+    const hasMetadata = parsed.metadata ? HasMetadata.Yes : HasMetadata.No;
+    const verify = parsed.verify;
+    const logs = parsed.logs;
+    const logHostCall = parsed["log-host-call"];
     try {
-        const program = prepareProgram(kind, hasMetadata, Array.from(f), [], [], [], spiArgs ? Array.from(spiArgs) : []);
-        const result = runProgram(program, initialGas, initialPc, logs, false);
-        console.log(`Status: ${result.status}`);
-        console.log(`Exit code: ${result.exitCode}`);
-        console.log(`Program counter: ${result.pc}`);
-        console.log(`Gas remaining: ${result.gas}`);
-        console.log(`Registers: [${result.registers.join(", ")}]`);
+        const summary = replayTraceFile(file, {
+            logs,
+            hasMetadata,
+            verify,
+            logHostCall,
+        });
+        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 running ${programFile}:`, error);
+        console.error(`Error replaying trace ${file}:`, error);
+        process.exit(1);
+    }
+}
+function parseGas(parsed) {
+    if (parsed.gas === undefined) {
+        return BigInt(10_000);
+    }
+    // Ensure it's a string/number, not boolean
+    if (typeof parsed.gas === "boolean") {
+        console.error("Error: --gas requires a value.");
+        process.exit(1);
+    }
+    const gasStr = String(parsed.gas);
+    // Reject floats and non-integer strings
+    if (gasStr.includes(".") || !/^-?\d+$/.test(gasStr)) {
+        console.error("Error: --gas must be a valid integer.");
+        process.exit(1);
+    }
+    let gasValue;
+    try {
+        gasValue = BigInt(gasStr);
+    }
+    catch (_e) {
+        console.error("Error: --gas must be a valid integer.");
+        process.exit(1);
+    }
+    const MAX_I64 = (1n << 63n) - 1n;
+    if (gasValue < 0n || gasValue > MAX_I64) {
+        console.error("Error: --gas must be a non-negative integer <= 2^63-1.");
+        process.exit(1);
+    }
+    return gasValue;
+}
+function parseSpiArgs(spiArgsStr) {
+    if (!spiArgsStr) {
+        return [];
+    }
+    try {
+        return Array.from(hexDecode(spiArgsStr));
+    }
+    catch (e) {
+        console.log(`Attempting to read ${spiArgsStr} as a file, since it's not a hex value: ${e}`);
+        return Array.from(readFileSync(spiArgsStr));
+    }
+}
+function parsePc(parsed) {
+    if (parsed.pc === undefined) {
+        return 0;
+    }
+    // Ensure it's a string/number, not boolean
+    if (typeof parsed.pc === "boolean") {
+        console.error("Error: --pc requires a value.");
+        process.exit(1);
+    }
+    const pcStr = String(parsed.pc);
+    // Reject floats and non-integer strings
+    if (pcStr.includes(".") || !/^-?\d+$/.test(pcStr)) {
+        console.error("Error: --pc must be a valid integer.");
+        process.exit(1);
+    }
+    const pcValue = parseInt(pcStr, 10);
+    if (!Number.isInteger(pcValue) || pcValue < 0 || pcValue > 0xffffffff) {
+        console.error("Error: --pc must be a non-negative integer <= 2^32-1.");
         process.exit(1);
     }
+    return pcValue;
 }

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(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/log-host-call.js

@@ -0,0 +1,41 @@
+import { pvmReadMemory } from "../../build/release.js";
+export const LOG_HOST_CALL_INDEX = 100;
+export const LOG_GAS_COST = 10n;
+/** The WHAT return value - indicates the host call is not implemented / acknowledged. */
+export const WHAT = 0xfffffffffffffffen;
+const LOG_LEVELS = ["FATAL", "ERROR", "WARN", "INFO", "DEBUG"];
+const MAX_LOG_LEN = 8192;
+/**
+ * Print the log message from a JIP-1 log host call (ecalli 100).
+ *
+ * Reads the level, target, and message from the PVM registers and memory,
+ * then prints via console.info.
+ */
+export function printLogHostCall(pvmId, registers) {
+    const level = Number(registers[7]);
+    const targetPtr = Number(registers[8] & 0xffffffffn);
+    const targetLen = Math.min(Math.max(0, Number(registers[9] & 0xffffffffn)), MAX_LOG_LEN);
+    const messagePtr = Number(registers[10] & 0xffffffffn);
+    const messageLen = Math.min(Math.max(0, Number(registers[11] & 0xffffffffn)), MAX_LOG_LEN);
+    const levelStr = LOG_LEVELS[level] ?? `LEVEL(${level})`;
+    let target = "";
+    if (targetPtr !== 0 && targetLen > 0) {
+        const targetBytes = pvmReadMemory(pvmId, targetPtr, targetLen);
+        if (targetBytes) {
+            target = new TextDecoder().decode(targetBytes);
+        }
+    }
+    let message = "";
+    if (messagePtr !== 0 && messageLen > 0) {
+        const messageBytes = pvmReadMemory(pvmId, messagePtr, messageLen);
+        if (messageBytes) {
+            message = new TextDecoder().decode(messageBytes);
+        }
+    }
+    if (target) {
+        console.info(`[${levelStr}] ${target}: ${message}`);
+    }
+    else {
+        console.info(`[${levelStr}] ${message}`);
+    }
+}