@fluffylabs/anan-as 1.1.3-cc868cf → 1.1.3-e01d5ea

package/README.md

@@ -2,14 +2,11 @@
 
 AssemblyScript implementation of the JAM PVM (64-bit).
 
-[Demo](https://todr.me/anan-as)
+Gray Paper compatibility:
 
-## Todo
+- [x] 0.7.2
 
-- [x] Memory
-- [x] [JAM tests](https://github.com/w3f/jamtestvectors/pull/3) compatibility
-- [x] 64-bit & new instructions ([GrayPaper v0.5.0](https://graypaper.fluffylabs.dev))
-- [x] GP 0.5.4 compatibility (ZBB extensions)
+[Demo](https://todr.me/anan-as)
 
 ## Why?
 
@@ -19,7 +16,7 @@ AssemblyScript implementation of the JAM PVM (64-bit).
 
 ## Useful where?
 
-- Potentially as an alternative implementation for [`typeberry`](https://github.com/fluffylabs).
+- Main PVM backend of [`typeberry`](https://github.com/fluffylabs) JAM client.
 - To test out the [PVM debugger](https://pvm.fluffylabs.dev).
 
 ## Installation
@@ -113,3 +110,64 @@ To run JSON test vectors.
 ```cmd
 npm start ./path/to/tests/*.json
 ```
+
+## CLI Usage
+
+The package includes a CLI tool for disassembling and running 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]
+
+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.
+
+# Show help
+npx @fluffylabs/anan-as --help
+npx @fluffylabs/anan-as disassemble --help
+npx @fluffylabs/anan-as run --help
+```
+
+### Commands
+
+- `disassemble`: Convert PVM bytecode to human-readable assembly
+- `run`: Execute PVM bytecode and show results
+
+### 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)
+- `--pc <number>`: Set initial program counter (default: 0)
+- `--gas <number>`: Set initial gas amount (default: 0)
+- `--help`, `-h`: Show help information
+
+### Examples
+
+```bash
+# Disassemble a JAM file (includes metadata by default)
+npx @fluffylabs/anan-as disassemble program.jam
+
+# Disassemble without metadata
+npx @fluffylabs/anan-as disassemble --no-metadata program.jam
+
+# Disassemble SPI program
+npx @fluffylabs/anan-as disassemble --spi program.spi
+
+# Run a JAM program with logs (includes metadata by default)
+npx @fluffylabs/anan-as run program.jam
+
+# Run a JAM program without metadata
+npx @fluffylabs/anan-as run --no-metadata program.jam
+
+# Run a JAM program quietly
+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
+npx @fluffylabs/anan-as run --spi program.spi args.bin
+```

package/dist/bin/build-inline.js

@@ -0,0 +1,70 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+// Load asconfig.json
+const asconfigPath = resolve(projectRoot, "asconfig.json");
+const asconfig = JSON.parse(readFileSync(asconfigPath, "utf-8"));
+console.log("Building inline JS files with base64-encoded WASM...\n");
+// Process each target
+for (const [targetName, config] of Object.entries(asconfig.targets)) {
+    const wasmPath = resolve(projectRoot, config.outFile);
+    try {
+        // Read the WASM file
+        const wasmBuffer = readFileSync(wasmPath);
+        // Base64 encode
+        const wasmBase64 = wasmBuffer.toString("base64");
+        // Generate the output JS file name
+        // e.g., "build/release.wasm" -> "build/release-inline.js"
+        const wasmFileName = basename(config.outFile, ".wasm");
+        const outputPath = resolve(projectRoot, dirname(config.outFile), `${wasmFileName}-inline.js`);
+        // Create the JS content
+        const jsContent = `// Auto-generated inline WASM module
+// Target: ${targetName}
+// Source: ${config.outFile}
+
+import * as raw from './debug-raw.js';
+
+export const wasmBase64 = "${wasmBase64}";
+let compiledModulePromise = null;
+
+// Helper function to decode and instantiate the module
+export async function instantiate(imports) {
+	if (compiledModulePromise === null) {
+		compiledModulePromise = WebAssembly.compile(getWasmBytes());
+	}
+	const module = await compiledModulePromise;
+	return raw.instantiate(module, imports);
+}
+
+// Helper function to just get the bytes
+export function getWasmBytes() {
+	return Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0));
+}
+`;
+        // Write the JS file
+        writeFileSync(outputPath, jsContent, "utf-8");
+        // Generate and write the .d.ts file
+        const dtsPath = outputPath.replace(/\.js$/, ".d.ts");
+        const dtsContent = `// Auto-generated type definitions for inline WASM module
+// Target: ${targetName}
+// Source: ${config.outFile}
+
+import {__AdaptedExports} from "./debug-raw.d.ts";
+
+export const wasmBase64: string;
+
+export function instantiate(imports?: { env?: any }): Promise<typeof __AdaptedExports>;
+
+export function getWasmBytes(): Uint8Array;
+`;
+        writeFileSync(dtsPath, dtsContent, "utf-8");
+        console.log(`✓ ${targetName}: ${outputPath} (${Math.round(wasmBase64.length / 1024)} KB base64)`);
+    }
+    catch (error) {
+        console.error(`✗ ${targetName}: Failed to process ${wasmPath}`);
+        console.error(`  ${error instanceof Error ? error.message : error}`);
+    }
+}
+console.log("\nDone!");

package/dist/bin/fuzz.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+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";
+const runNumber = 0;
+export function fuzz(data) {
+    const gas = 200n;
+    const pc = 0;
+    const vm = new Interpreter();
+    const program = wrapAsProgram(new Uint8Array(data));
+    if (program.length > 100) {
+        return;
+    }
+    try {
+        vm.resetGeneric(program, pc, tryAsGas(gas));
+        vm.runProgram();
+        const printDebugInfo = false;
+        const registers = Array(13)
+            .join(",")
+            .split(",")
+            .map(() => BigInt(0));
+        const exe = prepareProgram(InputKind.Generic, HasMetadata.No, Array.from(program), registers, [], [], []);
+        const output = runProgram(exe, gas, pc, printDebugInfo);
+        const vmRegisters = decodeRegistersFromTypeberry(vm);
+        collectErrors((assertFn) => {
+            assertFn(normalizeStatus(vm.getStatus()), normalizeStatus(output.status), "status");
+            assertFn(vm.gas.get(), output.gas, "gas");
+            assertFn(vmRegisters, output.registers, "registers");
+            assertFn(vm.getPC(), output.pc, "pc");
+        });
+        try {
+            if (runNumber % 100000 === 0) {
+                writeTestCase(program, {
+                    pc,
+                    gas,
+                    registers,
+                }, {
+                    status: normalizeStatus(vm.getStatus()),
+                    gasLeft: vm.gas.get(),
+                    pc: vm.getPC(),
+                    registers: vmRegisters,
+                });
+            }
+        }
+        catch (e) {
+            console.warn("Unable to write file", e);
+        }
+    }
+    catch (e) {
+        const hex = programHex(program);
+        console.log(program);
+        console.log(linkTo(hex));
+        console.log(disassemble(Array.from(program), InputKind.Generic, HasMetadata.No));
+        throw e;
+    }
+}
+function programHex(program) {
+    return Array.from(program)
+        .map((x) => x.toString(16).padStart(2, "0"))
+        .join("");
+}
+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)
+    for (let i = 0; i < 13; i++) {
+        try {
+            registers.push(vm.registers.getU64(i));
+        }
+        catch (_e) {
+            // If we can't get a register, break
+            break;
+        }
+    }
+    return registers;
+}
+function normalizeStatus(status) {
+    if (status === 2) {
+        return 1;
+    }
+    return status;
+}
+function assert(tb, an, comment = "") {
+    let condition = tb !== an;
+    if (Array.isArray(tb) && Array.isArray(an)) {
+        condition = tb.toString() !== an.toString();
+    }
+    if (condition) {
+        const alsoAsHex = (f) => {
+            if (Array.isArray(f)) {
+                return `${f.map(alsoAsHex).join(", ")}`;
+            }
+            if (typeof f === "number" || typeof f === "bigint") {
+                if (BigInt(f) !== 0n) {
+                    return `${f} | 0x${f.toString(16)}`;
+                }
+                return `${f}`;
+            }
+            return f;
+        };
+        throw new Error(`Diverging value: ${comment}
+\t(typeberry) ${alsoAsHex(tb)}
+\t(ananas)    ${alsoAsHex(an)}`);
+    }
+}
+function collectErrors(cb) {
+    const errors = [];
+    cb((tb, an, comment = "") => {
+        try {
+            assert(tb, an, comment);
+        }
+        catch (e) {
+            errors.push(`${e}`);
+        }
+    });
+    if (errors.length > 0) {
+        throw new Error(errors.join("\n"));
+    }
+}
+function writeTestCase(program, initial, expected) {
+    const hex = programHex(program);
+    fs.mkdirSync(`../tests/length_${hex.length}`, { recursive: true });
+    fs.writeFileSync(`../tests/length_${hex.length}/${hex}.json`, JSON.stringify({
+        name: linkTo(hex),
+        "initial-regs": initial.registers,
+        "initial-pc": initial.pc,
+        "initial-page-map": [],
+        "initial-memory": [],
+        "initial-gas": initial.gas,
+        program: Array.from(program),
+        "expected-status": statusToStr(expected.status),
+        "expected-regs": Array.from(expected.registers),
+        "expected-pc": expected.pc,
+        "expected-gas": expected.gasLeft,
+        "expected-memory": [],
+    }));
+}
+function statusToStr(status) {
+    if (status === 0) {
+        return "halt";
+    }
+    if (status === 1) {
+        return "trap";
+    }
+    if (status === 4) {
+        return "oog";
+    }
+    if (status === 3) {
+        return "host";
+    }
+    throw new Error(`unexpected status: ${status}`);
+}

package/dist/bin/index.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import minimist from "minimist";
+import { disassemble, HasMetadata, InputKind, prepareProgram, runProgram } from "../build/release.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]
+
+Commands:
+  disassemble  Disassemble PVM bytecode to assembly
+  run          Execute PVM bytecode
+
+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`;
+main();
+function main() {
+    const args = process.argv.slice(2);
+    // Handle global help flags
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    const subCommand = args[0];
+    switch (subCommand) {
+        case "disassemble":
+            handleDisassemble(args.slice(1));
+            break;
+        case "run":
+            handleRun(args.slice(1));
+            break;
+        default:
+            console.error(`Error: Unknown sub-command '${subCommand}'`);
+            console.error("");
+            console.error(HELP_TEXT);
+            process.exit(1);
+    }
+}
+function handleDisassemble(args) {
+    const parsed = minimist(args, {
+        boolean: ["spi", "no-metadata", "help"],
+        alias: { h: "help" },
+    });
+    if (parsed.help) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    const files = parsed._;
+    if (files.length === 0) {
+        console.error("Error: No file provided for disassemble command.");
+        console.error("Usage: anan-as disassemble [--spi] [--no-metadata] <file.(jam|pvm|spi|bin)>");
+        process.exit(1);
+    }
+    if (files.length > 1) {
+        console.error("Error: Only one file can be disassembled at a time.");
+        console.error("Usage: anan-as disassemble [--spi] [--no-metadata] <file.(jam|pvm|spi|bin)>");
+        process.exit(1);
+    }
+    const file = files[0];
+    // Validate file extension for disassemble command
+    const validExtensions = [".jam", ".pvm", ".spi", ".bin"];
+    const dotIndex = file.lastIndexOf(".");
+    if (dotIndex === -1) {
+        console.error(`Error: File '${file}' has no extension.`);
+        console.error("Supported extensions: .jam, .pvm, .spi, .bin");
+        process.exit(1);
+    }
+    const ext = file.substring(dotIndex);
+    if (!validExtensions.includes(ext)) {
+        console.error(`Error: Invalid file extension '${ext}' for disassemble command.`);
+        console.error("Supported extensions: .jam, .pvm, .spi, .bin");
+        process.exit(1);
+    }
+    const kind = parsed.spi ? InputKind.SPI : InputKind.Generic;
+    const hasMetadata = parsed["no-metadata"] ? HasMetadata.No : HasMetadata.Yes;
+    const f = readFileSync(file);
+    const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
+    console.log(`🤖 Assembly of ${file} (as ${name})`);
+    console.log(disassemble(Array.from(f), kind, hasMetadata));
+}
+function handleRun(args) {
+    const parsed = minimist(args, {
+        boolean: ["spi", "no-logs", "no-metadata", "help"],
+        string: ["pc", "gas"],
+        alias: { h: "help" },
+    });
+    if (parsed.help) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    const files = parsed._;
+    if (files.length === 0) {
+        console.error("Error: No file provided for run command.");
+        console.error("Usage: anan-as run [--spi] [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <file.jam> [spi-args.bin]");
+        process.exit(1);
+    }
+    const kind = parsed.spi ? InputKind.SPI : InputKind.Generic;
+    let programFile;
+    let spiArgsFile;
+    if (kind === InputKind.SPI) {
+        // For SPI programs, expect: <program.spi> [spi-args.bin]
+        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]");
+            process.exit(1);
+        }
+        programFile = files[0];
+        spiArgsFile = files[1]; // optional
+    }
+    else {
+        // For generic programs, expect exactly one file
+        if (files.length > 1) {
+            console.error("Error: Only one file can be run at a time.");
+            console.error("Usage: anan-as run [--no-logs] [--no-metadata] [--pc <number>] [--gas <number>] <file.jam>");
+            process.exit(1);
+        }
+        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);
+    }
+    const ext = programFile.substring(dotIndex);
+    if (ext !== expectedExt) {
+        console.error(`Error: Invalid file extension '${ext}' for run command.`);
+        console.error(`Expected: ${expectedExt}`);
+        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));
+    }
+    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;
+    }
+    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;
+    }
+    const f = readFileSync(programFile);
+    const name = kind === InputKind.Generic ? "generic PVM" : "JAM SPI";
+    console.log(`🚀 Running ${programFile} (as ${name})`);
+    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(", ")}]`);
+    }
+    catch (error) {
+        console.error(`Error running ${programFile}:`, error);
+        process.exit(1);
+    }
+}

package/dist/bin/test-gas-cost.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import "json-bigint-patch";
+import * as assert from "node:assert";
+import { disassemble, getGasCosts, HasMetadata, InputKind } from "../build/release.js";
+import { ERR, OK, read, run } from "./test-json.js";
+// Run the CLI application
+main();
+// Main function
+function main() {
+    const options = {
+        isDebug: false,
+        isSilent: false,
+        useSbrkGas: false,
+    };
+    run(processGasCost, options);
+}
+function processGasCost(data, options, filePath) {
+    if (options.isDebug) {
+        console.info(`🤖 reading ${filePath}`);
+    }
+    // input
+    const input = {
+        program: read(data, "program"),
+        blockGasCosts: read(data, "block_gas_costs"),
+    };
+    if (options.isDebug) {
+        const assembly = disassemble(input.program, InputKind.Generic, HasMetadata.No);
+        console.info("===========");
+        console.info(assembly);
+        console.info("\n^^^^^^^^^^^\n");
+    }
+    const result = asMap(getGasCosts(input.program, InputKind.Generic, HasMetadata.No));
+    // silent mode - just put our vals into expected (comparison done externally)
+    if (options.isSilent) {
+        data.block_gas_costs = result;
+        if (filePath !== "-") {
+            console.log(JSON.stringify(data, null, 2));
+        }
+        return data;
+    }
+    try {
+        assert.deepStrictEqual(result, input.blockGasCosts);
+        console.log(`${OK} ${filePath}`);
+    }
+    catch (e) {
+        console.log(`${ERR} ${filePath}`);
+        throw e;
+    }
+    return data;
+}
+function asMap(costs) {
+    const obj = {};
+    for (const { pc, gas } of costs) {
+        obj[pc] = Number(gas);
+    }
+    return obj;
+}