@fluffylabs/anan-as 1.2.0 → 1.3.0-1ebcf8f

package/dist/build/js/assembly/api-debugger.js

@@ -0,0 +1,245 @@
+import { buildMemory } from "./api-internal";
+import { InitialChunk, InitialPage } from "./api-types";
+import { Decoder } from "./codec";
+import { Interpreter, Status } from "./interpreter";
+import { MaybePageFault, MemoryBuilder } from "./memory";
+import { Access, PAGE_SIZE } from "./memory-page";
+import { deblob, extractCodeAndMetadata, liftBytes } from "./program";
+import { NO_OF_REGISTERS, newRegisters, REG_SIZE_BYTES } from "./registers";
+import { decodeSpi } from "./spi";
+let interpreter = null;
+export function resetJAM(program, pc, initialGas, args, hasMetadata = false, useBlockGas = false) {
+    const code = hasMetadata ? extractCodeAndMetadata(liftBytes(program)).code : liftBytes(program);
+    const p = decodeSpi(code, liftBytes(args), 128, useBlockGas);
+    const int = new Interpreter(p.program, p.registers, p.memory);
+    int.nextPc = pc;
+    int.gas.set(initialGas);
+    if (interpreter !== null) {
+        interpreter.memory.free();
+    }
+    interpreter = int;
+}
+export function resetGeneric(program, flatRegisters, initialGas, hasMetadata = false, useBlockGas = false) {
+    const code = hasMetadata ? extractCodeAndMetadata(liftBytes(program)).code : liftBytes(program);
+    const p = deblob(code, useBlockGas);
+    const registers = newRegisters();
+    fillRegisters(registers, flatRegisters);
+    const int = new Interpreter(p, registers);
+    int.gas.set(initialGas);
+    if (interpreter !== null) {
+        interpreter.memory.free();
+    }
+    interpreter = int;
+}
+export function resetGenericWithMemory(program, flatRegisters, pageMap, chunks, initialGas, hasMetadata = false, useBlockGas = false) {
+    const code = hasMetadata ? extractCodeAndMetadata(liftBytes(program)).code : liftBytes(program);
+    const p = deblob(code, useBlockGas);
+    const registers = newRegisters();
+    fillRegisters(registers, flatRegisters);
+    const builder = new MemoryBuilder();
+    const memory = buildMemory(builder, readPages(pageMap), readChunks(chunks));
+    const int = new Interpreter(p, registers, memory);
+    int.gas.set(initialGas);
+    interpreter = int;
+}
+export function nextStep() {
+    if (interpreter !== null) {
+        const int = interpreter;
+        return int.nextSteps();
+    }
+    return false;
+}
+export function nSteps(steps) {
+    if (interpreter !== null) {
+        const int = interpreter;
+        return int.nextSteps(steps);
+    }
+    return false;
+}
+export function getProgramCounter() {
+    if (interpreter === null) {
+        return 0;
+    }
+    const int = interpreter;
+    return u32(int.pc);
+}
+export function setNextProgramCounter(pc) {
+    if (interpreter === null) {
+        return;
+    }
+    const int = interpreter;
+    int.nextPc = pc;
+}
+export function getStatus() {
+    if (interpreter === null) {
+        return Status.PANIC;
+    }
+    const int = interpreter;
+    return int.status;
+}
+export function getExitArg() {
+    if (interpreter === null) {
+        return 0;
+    }
+    const int = interpreter;
+    return int.exitCode || 0;
+}
+export function getGasLeft() {
+    if (interpreter === null) {
+        return i64(0);
+    }
+    const int = interpreter;
+    return int.gas.get();
+}
+export function setGasLeft(gas) {
+    if (interpreter !== null) {
+        const int = interpreter;
+        int.gas.set(gas);
+    }
+}
+export function getRegisters() {
+    const flat = new Uint8Array(NO_OF_REGISTERS * REG_SIZE_BYTES).fill(0);
+    if (interpreter === null) {
+        return flat;
+    }
+    const int = interpreter;
+    for (let i = 0; i < int.registers.length; i++) {
+        let val = int.registers[i];
+        for (let j = 0; j < REG_SIZE_BYTES; j++) {
+            const index = i * REG_SIZE_BYTES + j;
+            flat[index] = (val & u64(0xff));
+            val = val >> u64(8);
+        }
+    }
+    return flat;
+}
+export function setRegisters(flatRegisters) {
+    if (interpreter === null) {
+        return;
+    }
+    const int = interpreter;
+    fillRegisters(int.registers, flatRegisters);
+}
+export function getPageDump(index) {
+    if (interpreter === null) {
+        return new Uint8Array(PAGE_SIZE).fill(0);
+    }
+    const int = interpreter;
+    const page = int.memory.pageDump(index);
+    if (page === null) {
+        return new Uint8Array(PAGE_SIZE).fill(0);
+    }
+    return page;
+}
+/**
+ * Returns the WASM linear memory pointer (byte offset) for the backing buffer of the page at `page`.
+ *
+ * Returns `0` if the page does not exist or is not readable (page/access fault).
+ *
+ * Use this instead of `getMemory` to read memory efficiently from the JS side:
+ * ```ts
+ * let pagesRead = 0;
+ * for (let address = start; address < end; address += PAGE_SIZE) {
+ *   const page = address >> PAGE_SIZE_SHIFT;
+ *   const ptr = getPagePointer(page);
+ *   if (ptr === 0) {
+ *     throw new Error(`Page fault at ${page << PAGE_SIZE_SHIFT}`);
+ *   }
+ *   destination.set(
+ *     new Uint8Array(wasm.instance.exports.memory.buffer, ptr, Math.min(end - address, PAGE_SIZE)),
+ *     pagesRead << PAGE_SIZE_SHIFT,
+ *   );
+ *   pagesRead += 1;
+ * }
+ * ```
+ */
+export function getPagePointer(page) {
+    if (interpreter === null) {
+        return 0;
+    }
+    const int = interpreter;
+    return int.memory.getPagePointer(page);
+}
+/**
+ * Read a chunk of memory at `[address, address + length)`.
+ *
+ * Returns the requested memory chunk or `null` if reading triggered a page fault.
+ *
+ * @deprecated Getting memory like that is extremely inefficient (copying mulitple times)
+ * and error prone (we may not be able to allocate).
+ * Use `getPagePointer` instead to read memory directly from WASM linear memory on the JS side
+ * with no additional WASM-side allocations.
+ */
+export function getMemory(address, length) {
+    if (interpreter === null) {
+        return null;
+    }
+    const int = interpreter;
+    const faultRes = new MaybePageFault();
+    const result = int.memory.getMemory(faultRes, address, length);
+    if (faultRes.isFault) {
+        return null;
+    }
+    return result;
+}
+/**
+ * Write given `data` under memory indices `[address, address + data.length)`.
+ *
+ * Returns `true` if the write was successful and `false` if page fault has been triggered.
+ */
+export function setMemory(address, data) {
+    if (interpreter === null) {
+        return false;
+    }
+    const int = interpreter;
+    const end = address + data.length;
+    const faultRes = new MaybePageFault();
+    for (let i = address; i < end; i++) {
+        int.memory.setU8(faultRes, i, data[i - address]);
+        if (faultRes.isFault) {
+            return false;
+        }
+    }
+    return true;
+}
+function fillRegisters(registers, flat) {
+    const len = registers.length * REG_SIZE_BYTES;
+    if (len !== flat.length) {
+        throw new Error(`Mismatching  registers size, got: ${flat.length}, expected: ${len}`);
+    }
+    for (let i = 0; i < registers.length; i++) {
+        let num = u64(0);
+        for (let j = 0; j < REG_SIZE_BYTES; j++) {
+            const index = i * REG_SIZE_BYTES + j;
+            num |= flat[index] << u64(j * 8);
+        }
+        registers[i] = num;
+    }
+}
+function readPages(pageMap) {
+    const pages = [];
+    const codec = new Decoder(pageMap);
+    while (!codec.isExhausted()) {
+        const p = new InitialPage();
+        p.address = codec.u32();
+        p.length = codec.u32();
+        p.access = codec.u8() > 0 ? Access.Write : Access.Read;
+        pages.push(p);
+    }
+    return pages;
+}
+function readChunks(chunks) {
+    const res = [];
+    const codec = new Decoder(chunks);
+    while (!codec.isExhausted()) {
+        const c = new InitialChunk();
+        c.address = codec.u32();
+        const len = codec.u32();
+        const data = codec.bytes(len);
+        for (let i = 0; i < len; i++) {
+            c.data.push(data[i]);
+        }
+        res.push(c);
+    }
+    return res;
+}

package/dist/build/js/assembly/api-internal.d.ts

@@ -0,0 +1,13 @@
+import { InitialChunk, InitialPage, VmInput, VmOutput, VmRunOptions } from "./api-types";
+import { Interpreter } from "./interpreter";
+import { Memory, MemoryBuilder } from "./memory";
+import { Program } from "./program";
+export declare function getAssembly(p: Program): string;
+export declare function buildMemory(builder: MemoryBuilder, pages: InitialPage[], chunks: InitialChunk[]): Memory;
+/** Initialize new VM for execution. */
+export declare function vmInit(input: VmInput): Interpreter;
+/** Initialize & run & destroy a VM in a single go. */
+export declare function vmRunOnce(input: VmInput, options: VmRunOptions): VmOutput;
+export declare function vmExecute(int: Interpreter, logs?: boolean): void;
+/** Destroy a running VM and consume the output. */
+export declare function vmDestroy(int: Interpreter, dumpMemory?: boolean): VmOutput;

package/dist/build/js/assembly/api-internal.js

@@ -0,0 +1,191 @@
+import { InitialChunk, VmOutput } from "./api-types";
+import { Args, RELEVANT_ARGS } from "./arguments";
+import { INSTRUCTIONS, MISSING_INSTRUCTION } from "./instructions";
+import { Interpreter, Status } from "./interpreter";
+import { MaybePageFault } from "./memory";
+import { Access, PAGE_SIZE, RESERVED_MEMORY } from "./memory-page";
+import { portable } from "./portable";
+import { decodeArguments, resolveArguments } from "./program";
+export function getAssembly(p) {
+    const len = p.code.length;
+    if (len === 0) {
+        return "<seems that there is no code>";
+    }
+    let v = "";
+    const argsRes = new Args();
+    for (let i = 0; i < len; i++) {
+        if (!p.mask.isInstruction(i)) {
+            throw new Error("We should iterate only over instructions!");
+        }
+        const instruction = p.code[i];
+        const iData = instruction >= INSTRUCTIONS.length ? MISSING_INSTRUCTION : INSTRUCTIONS[instruction];
+        v += "\n";
+        v += `${i}: `;
+        v += iData.name;
+        v += `(${instruction})`;
+        const skipBytes = p.mask.skipBytesToNextInstruction(i);
+        const args = decodeArguments(argsRes, iData.kind, p.code, i + 1, skipBytes);
+        const argsArray = [args.a, args.b, args.c, args.d];
+        const relevantArgs = RELEVANT_ARGS[iData.kind];
+        for (let i = 0; i < relevantArgs; i++) {
+            v += ` ${argsArray[i]}, `;
+        }
+        i += skipBytes;
+    }
+    return v;
+}
+export function buildMemory(builder, pages, chunks) {
+    let sbrkIndex = RESERVED_MEMORY;
+    for (let i = 0; i < pages.length; i++) {
+        const initPage = pages[i];
+        builder.setData(initPage.access, initPage.address, new Uint8Array(initPage.length));
+        // find the highest writeable page and set the sbrk index to the end of that range.
+        if (initPage.access === Access.Write) {
+            const pageEnd = initPage.address + initPage.length;
+            sbrkIndex = pageEnd < sbrkIndex ? sbrkIndex : pageEnd;
+        }
+    }
+    for (let i = 0; i < chunks.length; i++) {
+        const initChunk = chunks[i];
+        // access should not matter now, since we created the pages already.
+        const data = new Uint8Array(initChunk.data.length);
+        for (let j = 0; j < data.length; j++) {
+            data[j] = initChunk.data[j];
+        }
+        builder.setData(Access.None, initChunk.address, data);
+        // consider initialized chunk lengths when setting sbrk index
+        const chunkEnd = initChunk.address + initChunk.data.length;
+        sbrkIndex = chunkEnd < sbrkIndex ? sbrkIndex : chunkEnd;
+    }
+    return builder.build(sbrkIndex);
+}
+/** Initialize new VM for execution. */
+export function vmInit(input) {
+    const int = new Interpreter(input.program, input.registers, input.memory);
+    int.nextPc = input.pc;
+    int.gas.set(input.gas);
+    return int;
+}
+/** Initialize & run & destroy a VM in a single go. */
+export function vmRunOnce(input, options) {
+    const int = vmInit(input);
+    vmExecute(int, options.logs);
+    return vmDestroy(int, options.dumpMemory);
+}
+export function vmExecute(int, logs = false) {
+    let isOk = true;
+    const argsRes = new Args();
+    for (;;) {
+        if (!isOk) {
+            if (logs)
+                console.log(`REGISTERS (final) = [${int.registers.map((x) => `${x} (0x${x.toString(16)})`).join(", ")}]`);
+            if (logs)
+                console.log(`Finished with status: ${int.status}`);
+            if (logs)
+                console.log(`Exit code: ${int.exitCode}`);
+            break;
+        }
+        if (logs)
+            console.log(`PC = ${int.pc}`);
+        if (logs)
+            console.log(`GAS = ${int.gas.get()}`);
+        if (logs)
+            console.log(`STATUS = ${int.status}`);
+        if (logs)
+            console.log(`REGISTERS = [${int.registers.map((x) => `${x} (0x${x.toString(16)})`).join(", ")}]`);
+        if (logs && int.pc < u32(int.program.code.length)) {
+            const instruction = int.program.code[int.pc];
+            const iData = instruction >= INSTRUCTIONS.length ? MISSING_INSTRUCTION : INSTRUCTIONS[instruction];
+            const skipBytes = int.program.mask.skipBytesToNextInstruction(int.pc);
+            const args = resolveArguments(argsRes, iData.kind, int.program.code, int.pc + 1, skipBytes, int.registers);
+            if (args !== null) {
+                console.log(`ARGUMENTS:
+  ${args.a} (${args.decoded.a}) = 0x${u64(args.a).toString(16)},
+  ${args.b} (${args.decoded.b}) = 0x${u64(args.b).toString(16)},
+  ${args.c} (${args.decoded.c}) = 0x${u64(args.c).toString(16)},
+  ${args.d} (${args.decoded.d}) = 0x${u64(args.d).toString(16)}`);
+            }
+        }
+        isOk = int.nextSteps();
+    }
+}
+/** Destroy a running VM and consume the output. */
+export function vmDestroy(int, dumpMemory = false) {
+    const output = new VmOutput();
+    output.status = int.status;
+    output.registers = int.registers.slice(0);
+    output.pc = int.pc;
+    output.gas = int.gas.get();
+    if (dumpMemory) {
+        output.memory = getOutputChunks(int.memory);
+    }
+    output.exitCode = int.exitCode;
+    output.result = readResult(int);
+    int.memory.free();
+    return output;
+}
+function readResult(int) {
+    if (int.status !== Status.HALT) {
+        return [];
+    }
+    // JAM return convention
+    const ptr_start = u32(int.registers[7] & u64(4294967295));
+    const ptr_end = u32(int.registers[8] & u64(4294967295));
+    // invalid output result
+    if (ptr_start >= ptr_end) {
+        return [];
+    }
+    // attempt to read the output memory (up to 1MB)
+    const totalLength = ptr_end - ptr_start;
+    if (totalLength > 1024 * 1024) {
+        return [];
+    }
+    const result = new Uint8Array(totalLength);
+    const faultRes = new MaybePageFault();
+    int.memory.bytesRead(faultRes, ptr_start, result, 0);
+    // we couldn't access the mem - i.e. no output
+    if (faultRes.isFault) {
+        return [];
+    }
+    // copy the Uint8Array to a regular array
+    const out = new Array(totalLength);
+    for (let i = 0; i < totalLength; i++) {
+        out[i] = result[i];
+    }
+    return out;
+}
+function getOutputChunks(memory) {
+    const chunks = [];
+    // @ts-ignore: AS returns T[], JS returns iterator - asArray handles both
+    const pages = portable.asArray(memory.pages.keys());
+    let currentChunk = null;
+    for (let i = 0; i < pages.length; i++) {
+        const pageIdx = pages[i];
+        const page = memory.pages.get(pageIdx);
+        // skip empty pages
+        if (page.raw.page === null) {
+            continue;
+        }
+        for (let n = 0; n < page.raw.data.length; n++) {
+            const v = page.raw.data[n];
+            if (v !== 0) {
+                if (currentChunk !== null) {
+                    currentChunk.data.push(v);
+                }
+                else {
+                    currentChunk = new InitialChunk();
+                    currentChunk.address = pageIdx * PAGE_SIZE + n;
+                    currentChunk.data = [v];
+                }
+            }
+            else if (currentChunk !== null) {
+                chunks.push(currentChunk);
+                currentChunk = null;
+            }
+        }
+    }
+    if (currentChunk !== null) {
+        chunks.push(currentChunk);
+    }
+    return chunks;
+}

package/dist/build/js/assembly/api-types.d.ts

@@ -0,0 +1,45 @@
+/** We split out type definitions, because they can't be exported from WASM. */
+import { Gas } from "./gas";
+import { Status } from "./interpreter";
+import { Memory } from "./memory";
+import { Access } from "./memory-page";
+import { Program } from "./program";
+import { Registers } from "./registers";
+export declare class InitialPage {
+    address: u32;
+    length: u32;
+    access: Access;
+}
+export declare class InitialChunk {
+    address: u32;
+    data: u8[];
+}
+export declare class VmRunOptions {
+    logs: boolean;
+    dumpMemory: boolean;
+}
+export declare class VmInput {
+    readonly program: Program;
+    readonly memory: Memory;
+    readonly registers: Registers;
+    pc: u32;
+    gas: Gas;
+    constructor(program: Program, memory: Memory, registers: Registers);
+}
+export declare class VmPause {
+    status: Status;
+    exitCode: u32;
+    pc: u32;
+    nextPc: u32;
+    gas: Gas;
+    registers: u64[];
+}
+export declare class VmOutput {
+    status: Status;
+    exitCode: u32;
+    pc: u32;
+    gas: Gas;
+    result: u8[];
+    registers: u64[];
+    memory: InitialChunk[];
+}

package/dist/build/js/assembly/api-types.js

@@ -0,0 +1,52 @@
+/** We split out type definitions, because they can't be exported from WASM. */
+import { Status } from "./interpreter";
+import { Access } from "./memory-page";
+export class InitialPage {
+    constructor() {
+        this.address = 0;
+        this.length = 0;
+        this.access = Access.None;
+    }
+}
+export class InitialChunk {
+    constructor() {
+        this.address = 0;
+        this.data = [];
+    }
+}
+export class VmRunOptions {
+    constructor() {
+        this.logs = false;
+        this.dumpMemory = false;
+    }
+}
+export class VmInput {
+    constructor(program, memory, registers) {
+        this.program = program;
+        this.memory = memory;
+        this.registers = registers;
+        this.pc = 0;
+        this.gas = u64(0);
+    }
+}
+export class VmPause {
+    constructor() {
+        this.status = Status.OK;
+        this.exitCode = 0;
+        this.pc = 0;
+        this.nextPc = 0;
+        this.gas = u64(0);
+        this.registers = [];
+    }
+}
+export class VmOutput {
+    constructor() {
+        this.status = Status.OK;
+        this.exitCode = 0;
+        this.pc = 0;
+        this.gas = u64(0);
+        this.result = [];
+        this.registers = [];
+        this.memory = [];
+    }
+}

package/dist/build/js/assembly/api-utils.d.ts

@@ -0,0 +1,79 @@
+import { InitialChunk, InitialPage, VmOutput, VmPause } from "./api-types";
+import { Gas } from "./gas";
+import { ProgramCounter } from "./program";
+import { StandardProgram } from "./spi";
+export declare enum InputKind {
+    Generic = 0,
+    SPI = 1
+}
+export declare enum HasMetadata {
+    Yes = 0,
+    No = 1
+}
+declare class BlockGasCost {
+    pc: ProgramCounter;
+    gas: Gas;
+}
+export declare function getBlockGasCosts(input: u8[], kind: InputKind, withMetadata: HasMetadata): BlockGasCost[];
+export declare function disassemble(input: u8[], kind: InputKind, withMetadata: HasMetadata): string;
+export declare function prepareProgram(kind: InputKind, hasMetadata: HasMetadata, program: u8[], 
+/** NOTE: ignored in case of SPI. */
+initialRegisters: u64[], 
+/** NOTE: ignored in case of SPI. */
+initialPageMap: InitialPage[], 
+/** NOTE: ignored in case of SPI. */
+initialMemory: InitialChunk[], 
+/** NOTE: ONLY needed for SPI. */
+args: u8[], 
+/** Preallocate a bunch of memory pages for faster execution. */
+preallocateMemoryPages: u32, 
+/** Compute gas per-block instead of per-instruction. */
+useBlockGas: boolean): StandardProgram;
+/** Execute PVM program and stop. */
+export declare function runProgram(program: StandardProgram, initialGas?: i64, programCounter?: u32, logs?: boolean, dumpMemory?: boolean): VmOutput;
+/**
+ * Allocate new PVM instance to execute given program.
+ *
+ * NOTE: the PVM MUST be de-allocated using `pvmDestroy`.
+ */
+export declare function pvmStart(program: StandardProgram): u32;
+/** Deallocate PVM resources. */
+export declare function pvmDestroy(pvmId: u32): VmOutput | null;
+/** Set register values of a paused PVM. */
+export declare function pvmSetRegisters(pvmId: u32, registers: u64[]): void;
+/**
+ * Read a continuous chunk of memory from given PVM instance.
+ *
+ * @deprecated Use `pvmGetPagePointer` instead to read memory directly from WASM linear memory
+ * on the JS side with no additional WASM-side allocations.
+ */
+export declare function pvmReadMemory(pvmId: u32, address: u32, length: u32): Uint8Array | null;
+/**
+ * Returns the WASM linear memory pointer (byte offset) for the backing buffer of the page at `page`
+ * in the given PVM instance.
+ *
+ * Returns `0` if the PVM does not exist, the page does not exist, or the page is not readable.
+ *
+ * Use this instead of `pvmReadMemory` to read memory efficiently from the JS side:
+ * ```ts
+ * let pagesRead = 0;
+ * for (let address = start; address < end; address += PAGE_SIZE) {
+ *   const page = address >> PAGE_SIZE_SHIFT;
+ *   const ptr = pvmGetPagePointer(pvmId, page);
+ *   if (ptr === 0) {
+ *     throw new Error(`Page fault at ${page << PAGE_SIZE_SHIFT}`);
+ *   }
+ *   destination.set(
+ *     new Uint8Array(wasm.instance.exports.memory.buffer, ptr, Math.min(end - address, PAGE_SIZE)),
+ *     pagesRead << PAGE_SIZE_SHIFT,
+ *   );
+ *   pagesRead += 1;
+ * }
+ * ```
+ */
+export declare function pvmGetPagePointer(pvmId: u32, page: u32): usize;
+/** Write a chunk of memory to given PVM instance. */
+export declare function pvmWriteMemory(pvmId: u32, address: u32, data: Uint8Array): boolean;
+/** Resume execution of paused VM. */
+export declare function pvmResume(pvmId: u32, gas: Gas, pc: u32, logs?: boolean): VmPause | null;
+export {};