@fluffylabs/anan-as 1.1.3-dde58f0 → 1.1.3-dffbae7

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 or hex]
+  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: 10_000)
-  --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("");
@@ -85,11 +96,11 @@ function handleDisassemble(args) {
 }
 function handleRun(args) {
     const parsed = minimist(args, {
-        boolean: ["spi", "logs", "metadata", "help"],
+        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 },
+        default: { metadata: true, logs: true, "log-host-call": true },
     });
     if (parsed.help) {
         console.log(HELP_TEXT);
@@ -126,6 +137,7 @@ function handleRun(args) {
     // 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);
@@ -134,20 +146,87 @@ function handleRun(args) {
     const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
     console.log(`🚀 Running ${programFile} (as ${name})`);
     try {
-        const program = prepareProgram(kind, hasMetadata, programCode, [], [], [], 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(", ")}]`);
-        console.log(`Result: [${hexEncode(result.result)}]`);
+        const preallocateMemoryPages = 128;
+        const program = prepareProgram(kind, hasMetadata, programCode, [], [], [], spiArgs, preallocateMemoryPages);
+        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 ?? [])}]`);
     }
     catch (error) {
         console.error(`Error running ${programFile}:`, error);
         process.exit(1);
     }
 }
+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 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;
+    const logHostCall = parsed["log-host-call"];
+    try {
+        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 replaying trace ${file}:`, error);
+        process.exit(1);
+    }
+}
 function parseGas(parsed) {
     if (parsed.gas === undefined) {
         return BigInt(10_000);
@@ -212,27 +291,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;
@@ -21,7 +21,7 @@ export function fuzz(data) {
             .join(",")
             .split(",")
             .map(() => BigInt(0));
-        const exe = prepareProgram(InputKind.Generic, HasMetadata.No, Array.from(program), registers, [], [], []);
+        const exe = prepareProgram(InputKind.Generic, HasMetadata.No, Array.from(program), registers, [], [], [], 0);
         const output = runProgram(exe, gas, pc, printDebugInfo);
         const vmRegisters = decodeRegistersFromTypeberry(vm);
         collectErrors((assertFn) => {
@@ -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}`);
+    }
+}