@typeberry/lib 0.5.1-aff8b4f → 0.5.1-eb84786

package/packages/core/pvm-host-calls/host-call-memory.js

@@ -0,0 +1,40 @@
+import { tryAsU32 } from "#@typeberry/numbers";
+import { OK, Result } from "#@typeberry/utils";
+export class HostCallMemory {
+    memory;
+    constructor(memory) {
+        this.memory = memory;
+    }
+    /**
+     * Save some bytes into memory under given address.
+     *
+     * NOTE: Given address is U64 (pure register value),
+     * but we use only lower 32-bits.
+     */
+    storeFrom(regAddress, bytes) {
+        if (bytes.length === 0) {
+            return Result.ok(OK);
+        }
+        // NOTE: We always take lower 32 bits from register value.
+        //
+        // https://graypaper.fluffylabs.dev/#/ab2cdbd/25ed0025ed00?v=0.7.2
+        const address = tryAsU32(Number(regAddress & 0xffffffffn));
+        return this.memory.store(address, bytes);
+    }
+    /**
+     * Read some bytes from memory under given address.
+     *
+     * NOTE: Given address is U64 (pure register value),
+     * but we use only lower 32-bits.
+     */
+    loadInto(output, regAddress) {
+        if (output.length === 0) {
+            return Result.ok(OK);
+        }
+        // https://graypaper.fluffylabs.dev/#/ab2cdbd/25ed0025ed00?v=0.7.2
+        //
+        // NOTE we are taking the the lower U32 part of the register, hence it's safe.
+        const address = tryAsU32(Number(regAddress & 0xffffffffn));
+        return this.memory.read(address, output);
+    }
+}

package/packages/core/pvm-host-calls/host-call-memory.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=host-call-memory.test.d.ts.map

package/packages/core/pvm-host-calls/host-call-memory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-call-memory.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-call-memory.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-host-calls/host-call-memory.test.js

@@ -0,0 +1,75 @@
+import { beforeEach, describe, it } from "node:test";
+import { tryAsU32, tryAsU64 } from "#@typeberry/numbers";
+import { getPageStartAddress, MAX_MEMORY_INDEX, MEMORY_SIZE, } from "#@typeberry/pvm-interface";
+import { deepEqual, OK, Result } from "#@typeberry/utils";
+import { HostCallMemory } from "./host-call-memory.js";
+class FakeMemory {
+    store(address, bytes) {
+        const pageStart = getPageStartAddress(tryAsU32((address + bytes.length) % 2 ** 32));
+        return Result.error({ address: tryAsU32(pageStart) }, () => `Page fault: attempted to access reserved page ${pageStart}`);
+    }
+    read(address, result) {
+        const pageStart = getPageStartAddress(tryAsU32((address + result.length) % 2 ** 32));
+        return Result.error({ address: tryAsU32(pageStart) }, () => `Page fault: attempted to access reserved page ${pageStart}`);
+    }
+}
+describe("HostCallMemory", () => {
+    let memory;
+    let hostCallMemory;
+    beforeEach(() => {
+        memory = new FakeMemory();
+        hostCallMemory = new HostCallMemory(memory);
+    });
+    describe("storeFrom", () => {
+        it("should always allow 0-length bytes", () => {
+            const bytes = new Uint8Array([]);
+            const address = tryAsU64(2 ** 40);
+            const result = hostCallMemory.storeFrom(address, bytes);
+            deepEqual(result, Result.ok(OK));
+        });
+        it("should pass through the result of the underlying memory's storeFrom method", () => {
+            const bytes = new Uint8Array([1, 2, 3, 4]);
+            const address = tryAsU64(0);
+            const result = hostCallMemory.storeFrom(address, bytes);
+            deepEqual(result, Result.error({ address: tryAsU32(0) }, () => "Page fault: attempted to access reserved page 0"));
+        });
+        it("should return OutOfBounds error when address + length exceeds MEMORY_SIZE", () => {
+            const address = tryAsU64(MEMORY_SIZE - 2);
+            const bytes = new Uint8Array([1, 2, 3]);
+            const result = hostCallMemory.storeFrom(address, bytes);
+            deepEqual(result, Result.error({ address: tryAsU32(0) }, () => "Page fault: attempted to access reserved page 0"));
+        });
+        it("should wrap address when exceeds MAX_MEMORY_INDEX and throw", () => {
+            const address = tryAsU64(MAX_MEMORY_INDEX + 1);
+            const bytes = new Uint8Array([1, 2, 3]);
+            const res = hostCallMemory.storeFrom(address, bytes);
+            deepEqual(res, Result.error({ address: tryAsU32(0) }, () => "Page fault: attempted to access reserved page 0"));
+        });
+    });
+    describe("loadInto", () => {
+        it("should always allow 0-length bytes", () => {
+            const bytes = new Uint8Array([]);
+            const address = tryAsU64(2 ** 40);
+            const result = hostCallMemory.loadInto(bytes, address);
+            deepEqual(result, Result.ok(OK));
+        });
+        it("should pass through the result of the underlying memory's loadInto method", () => {
+            const bytes = new Uint8Array([1, 2, 3, 4]);
+            const address = tryAsU64(0);
+            const result = hostCallMemory.loadInto(bytes, address);
+            deepEqual(result, Result.error({ address: tryAsU32(0) }, () => "Page fault: attempted to access reserved page 0"));
+        });
+        it("should return OutOfBounds error when address + length exceeds MEMORY_SIZE", () => {
+            const address = tryAsU64(MEMORY_SIZE - 2);
+            const result = new Uint8Array(3);
+            const res = hostCallMemory.loadInto(result, address);
+            deepEqual(res, Result.error({ address: tryAsU32(0) }, () => "Page fault: attempted to access reserved page 0"));
+        });
+        it("should wrap address when exceeds MAX_MEMORY_INDEX and throw", () => {
+            const address = tryAsU64(MAX_MEMORY_INDEX + 1);
+            const result = new Uint8Array([1, 2, 3]);
+            const res = hostCallMemory.loadInto(result, address);
+            deepEqual(res, Result.error({ address: tryAsU32(0) }, () => "Page fault: attempted to access reserved page 0"));
+        });
+    });
+});

package/packages/core/pvm-host-calls/host-call-registers.d.ts

@@ -0,0 +1,13 @@
+import { type U64 } from "#@typeberry/numbers";
+export declare class HostCallRegisters {
+    private readonly bytes;
+    private readonly registers;
+    constructor(bytes: Uint8Array);
+    /** Get U64 register value. */
+    get(registerIndex: number): U64;
+    /** Set U64 register value. */
+    set(registerIndex: number, value: U64): void;
+    /** Get all registers encoded into little-endian bytes. */
+    getEncoded(): Uint8Array;
+}
+//# sourceMappingURL=host-call-registers.d.ts.map

package/packages/core/pvm-host-calls/host-call-registers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-call-registers.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-call-registers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGxD,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;gBAER,KAAK,EAAE,UAAU;IAI9C,8BAA8B;IAC9B,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG;IAI/B,8BAA8B;IAC9B,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG;IAIrC,0DAA0D;IAC1D,UAAU,IAAI,UAAU;CAGzB"}

package/packages/core/pvm-host-calls/host-call-registers.js

@@ -0,0 +1,22 @@
+import { tryAsU64 } from "#@typeberry/numbers";
+import { REGISTER_BYTE_SIZE } from "#@typeberry/pvm-interface";
+export class HostCallRegisters {
+    bytes;
+    registers;
+    constructor(bytes) {
+        this.bytes = bytes;
+        this.registers = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    /** Get U64 register value. */
+    get(registerIndex) {
+        return tryAsU64(this.registers.getBigUint64(registerIndex * REGISTER_BYTE_SIZE, true));
+    }
+    /** Set U64 register value. */
+    set(registerIndex, value) {
+        this.registers.setBigUint64(registerIndex * REGISTER_BYTE_SIZE, value, true);
+    }
+    /** Get all registers encoded into little-endian bytes. */
+    getEncoded() {
+        return this.bytes;
+    }
+}

package/packages/core/pvm-host-calls/host-call-registers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=host-call-registers.test.d.ts.map

package/packages/core/pvm-host-calls/host-call-registers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-call-registers.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-call-registers.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-host-calls/host-call-registers.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsU64 } from "#@typeberry/numbers";
+import { HostCallRegisters } from "./host-call-registers.js";
+describe("HostCallRegisters", () => {
+    describe("getAllEncoded", () => {
+        it("reads a u64 value from the underlying registers", () => {
+            const regs = new BigUint64Array(13);
+            regs[0] = 0xfffffffffffffffdn;
+            const hostCallRegisters = new HostCallRegisters(new Uint8Array(regs.buffer));
+            assert.strictEqual(hostCallRegisters.get(0), tryAsU64(0xfffffffffffffffdn));
+        });
+    });
+    describe("setAllEncoded", () => {
+        it("writes a u64 value to the underlying registers", () => {
+            const regs = new BigUint64Array(13);
+            const hostCallRegisters = new HostCallRegisters(new Uint8Array(regs.buffer));
+            hostCallRegisters.set(0, tryAsU64(0xfffffffffffffffdn));
+            const view = new DataView(hostCallRegisters.getEncoded().buffer);
+            assert.strictEqual(view.getBigUint64(0, true), tryAsU64(0xfffffffffffffffdn));
+            assert.strictEqual(regs[0], tryAsU64(0xfffffffffffffffdn));
+        });
+    });
+});

package/packages/core/pvm-host-calls/host-calls-manager.d.ts

@@ -0,0 +1,23 @@
+import { type Gas } from "#@typeberry/pvm-interface";
+import { type HostCallHandler, type HostCallIndex, type PvmExecution } from "./host-call-handler.js";
+import type { HostCallRegisters } from "./host-call-registers.js";
+/** Container for all available host calls. */
+export declare class HostCallsManager {
+    private readonly hostCalls;
+    private readonly missing;
+    constructor({ missing, handlers, }: {
+        missing: HostCallHandler;
+        handlers?: HostCallHandler[];
+    });
+    /** Get a host call by index. */
+    get(hostCallIndex: HostCallIndex): HostCallHandler;
+    traceHostCall(context: string, hostCallIndex: HostCallIndex, hostCallHandler: HostCallHandler, registers: HostCallRegisters, gas: Gas): void;
+}
+export declare class NoopMissing implements HostCallHandler {
+    index: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"HostCallIndex[U32]">;
+    basicGasCost: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"SmallGas[U32]">;
+    currentServiceId: import("@typeberry/numbers").U32;
+    tracedRegisters: never[];
+    execute(): Promise<undefined | PvmExecution>;
+}
+//# sourceMappingURL=host-calls-manager.d.ts.map

package/packages/core/pvm-host-calls/host-calls-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-calls-manager.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-calls-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,GAAG,EAAiB,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAIlE,8CAA8C;AAC9C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6C;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAEb,EACV,OAAO,EACP,QAAa,GACd,EAAE;QACD,OAAO,EAAE,eAAe,CAAC;QACzB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;KAC9B;IASD,gCAAgC;IAChC,GAAG,CAAC,aAAa,EAAE,aAAa,GAAG,eAAe;IAIlD,aAAa,CACX,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,eAAe,EAChC,SAAS,EAAE,iBAAiB,EAC5B,GAAG,EAAE,GAAG;CAcX;AAED,qBAAa,WAAY,YAAW,eAAe;IACjD,KAAK,iIAAmC;IACxC,YAAY,4HAAoB;IAChC,gBAAgB,mCAAe;IAC/B,eAAe,UAAM;IAEf,OAAO,IAAI,OAAO,CAAC,SAAS,GAAG,YAAY,CAAC;CAGnD"}

package/packages/core/pvm-host-calls/host-calls-manager.js

@@ -0,0 +1,44 @@
+import { Logger } from "#@typeberry/logger";
+import { tryAsU32 } from "#@typeberry/numbers";
+import { tryAsSmallGas } from "#@typeberry/pvm-interface";
+import { check } from "#@typeberry/utils";
+import { tryAsHostCallIndex, } from "./host-call-handler.js";
+const logger = Logger.new(import.meta.filename, "host-calls-pvm");
+/** Container for all available host calls. */
+export class HostCallsManager {
+    hostCalls = new Map();
+    missing;
+    constructor({ missing, handlers = [], }) {
+        this.missing = missing;
+        for (const handler of handlers) {
+            check `${this.hostCalls.get(handler.index) === undefined} Overwriting host call handler at index ${handler.index}`;
+            this.hostCalls.set(handler.index, handler);
+        }
+    }
+    /** Get a host call by index. */
+    get(hostCallIndex) {
+        return this.hostCalls.get(hostCallIndex) ?? this.missing;
+    }
+    traceHostCall(context, hostCallIndex, hostCallHandler, registers, gas) {
+        const { currentServiceId } = hostCallHandler;
+        const requested = hostCallIndex !== hostCallHandler.index ? ` (${hostCallIndex})` : "";
+        const name = `${hostCallHandler.constructor.name}:${hostCallHandler.index}`;
+        const registerValues = hostCallHandler.tracedRegisters
+            .map((idx) => [idx.toString().padStart(2, "0"), registers.get(idx)])
+            .filter((v) => v[1] !== 0n)
+            .map(([idx, value]) => {
+            return `r${idx}=${value} (0x${value.toString(16)})`;
+        })
+            .join(", ");
+        logger.insane `[${currentServiceId}] ${context} ${name}${requested}.  Gas: ${gas}. Regs: ${registerValues}.`;
+    }
+}
+export class NoopMissing {
+    index = tryAsHostCallIndex(2 ** 32 - 1);
+    basicGasCost = tryAsSmallGas(0);
+    currentServiceId = tryAsU32(0);
+    tracedRegisters = [];
+    async execute() {
+        return;
+    }
+}

package/packages/core/pvm-host-calls/host-calls.d.ts

@@ -0,0 +1,29 @@
+import { type Gas, Status } from "#@typeberry/pvm-interface";
+import type { HostCallsManager } from "./host-calls-manager.js";
+import type { InterpreterInstanceManager } from "./interpreter-instance-manager.js";
+declare class ReturnValue {
+    consumedGas: Gas;
+    status: Status | null;
+    memorySlice: Uint8Array | null;
+    private constructor();
+    static fromStatus(consumedGas: Gas, status: Status): ReturnValue;
+    static fromMemorySlice(consumedGas: Gas, memorySlice: Uint8Array): ReturnValue;
+    hasMemorySlice(): this is this & {
+        status: null;
+        memorySlice: Uint8Array;
+    };
+    hasStatus(): this is this & {
+        status: Status;
+        memorySlice: null;
+    };
+}
+export declare class HostCalls {
+    private pvmInstanceManager;
+    private hostCalls;
+    constructor(pvmInstanceManager: InterpreterInstanceManager, hostCalls: HostCallsManager);
+    private getReturnValue;
+    private execute;
+    runProgram(program: Uint8Array, args: Uint8Array, initialPc: number, initialGas: Gas): Promise<ReturnValue>;
+}
+export {};
+//# sourceMappingURL=host-calls.d.ts.map

package/packages/core/pvm-host-calls/host-calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-calls.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-calls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAwB,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAKlF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,cAAM,WAAW;IAEN,WAAW,EAAE,GAAG;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI;IACrB,WAAW,EAAE,UAAU,GAAG,IAAI;IAHvC,OAAO;IAWP,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM;IAIlD,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU;IAIhE,cAAc,IAAI,IAAI,IAAI,IAAI,GAAG;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,UAAU,CAAA;KAAE;IAI1E,SAAS,IAAI,IAAI,IAAI,IAAI,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,IAAI,CAAA;KAAE;CAGlE;AACD,qBAAa,SAAS;IAElB,OAAO,CAAC,kBAAkB;IAC1B,OAAO,CAAC,SAAS;gBADT,kBAAkB,EAAE,0BAA0B,EAC9C,SAAS,EAAE,gBAAgB;IAGrC,OAAO,CAAC,cAAc;YA2BR,OAAO;IAiEf,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC;CASlH"}

package/packages/core/pvm-host-calls/host-calls.js

@@ -0,0 +1,119 @@
+import { Status } from "#@typeberry/pvm-interface";
+import { assertNever, check, safeAllocUint8Array } from "#@typeberry/utils";
+import { PvmExecution, tryAsHostCallIndex } from "./host-call-handler.js";
+import { HostCallMemory } from "./host-call-memory.js";
+import { HostCallRegisters } from "./host-call-registers.js";
+class ReturnValue {
+    consumedGas;
+    status;
+    memorySlice;
+    constructor(consumedGas, status, memorySlice) {
+        this.consumedGas = consumedGas;
+        this.status = status;
+        this.memorySlice = memorySlice;
+        check `
+      ${(status === null && memorySlice !== null) || (status !== null && memorySlice === null)}
+      'status' and 'memorySlice' must not both be null or both be non-null — exactly one must be provided
+    `;
+    }
+    static fromStatus(consumedGas, status) {
+        return new ReturnValue(consumedGas, status, null);
+    }
+    static fromMemorySlice(consumedGas, memorySlice) {
+        return new ReturnValue(consumedGas, null, memorySlice);
+    }
+    hasMemorySlice() {
+        return this.memorySlice instanceof Uint8Array && this.status === null;
+    }
+    hasStatus() {
+        return !this.hasMemorySlice();
+    }
+}
+export class HostCalls {
+    pvmInstanceManager;
+    hostCalls;
+    constructor(pvmInstanceManager, hostCalls) {
+        this.pvmInstanceManager = pvmInstanceManager;
+        this.hostCalls = hostCalls;
+    }
+    getReturnValue(status, pvmInstance) {
+        const gasConsumed = pvmInstance.gas.used();
+        if (status === Status.OOG) {
+            return ReturnValue.fromStatus(gasConsumed, status);
+        }
+        if (status === Status.HALT) {
+            const regs = new HostCallRegisters(pvmInstance.registers.getAllEncoded());
+            const memory = new HostCallMemory(pvmInstance.memory);
+            const address = regs.get(7);
+            // NOTE we are taking the the lower U32 part of the register, hence it's safe.
+            const length = Number(regs.get(8) & 0xffffffffn);
+            const result = safeAllocUint8Array(length);
+            const loadResult = memory.loadInto(result, address);
+            if (loadResult.isError) {
+                return ReturnValue.fromMemorySlice(gasConsumed, new Uint8Array());
+            }
+            return ReturnValue.fromMemorySlice(gasConsumed, result);
+        }
+        return ReturnValue.fromStatus(gasConsumed, Status.PANIC);
+    }
+    async execute(pvmInstance) {
+        pvmInstance.runProgram();
+        for (;;) {
+            let status = pvmInstance.getStatus();
+            if (status !== Status.HOST) {
+                return this.getReturnValue(status, pvmInstance);
+            }
+            check `
+        ${pvmInstance.getExitParam() !== null}
+        "We know that the exit param is not null, because the status is 'Status.HOST'
+      `;
+            const hostCallIndex = pvmInstance.getExitParam() ?? -1;
+            const gas = pvmInstance.gas;
+            const regs = new HostCallRegisters(pvmInstance.registers.getAllEncoded());
+            const memory = new HostCallMemory(pvmInstance.memory);
+            const index = tryAsHostCallIndex(hostCallIndex);
+            const hostCall = this.hostCalls.get(index);
+            const gasBefore = gas.get();
+            // NOTE: `basicGasCost(regs)` function is for compatibility reasons: pre GP 0.7.2
+            const basicGasCost = typeof hostCall.basicGasCost === "number" ? hostCall.basicGasCost : hostCall.basicGasCost(regs);
+            const underflow = gas.sub(basicGasCost);
+            const pcLog = `[PC: ${pvmInstance.getPC()}]`;
+            if (underflow) {
+                this.hostCalls.traceHostCall(`${pcLog} OOG`, index, hostCall, regs, gas.get());
+                return ReturnValue.fromStatus(gas.used(), Status.OOG);
+            }
+            this.hostCalls.traceHostCall(`${pcLog} Invoking`, index, hostCall, regs, gasBefore);
+            const result = await hostCall.execute(gas, regs, memory);
+            this.hostCalls.traceHostCall(result === undefined ? `${pcLog} Result` : `${pcLog} Status(${PvmExecution[result]})`, index, hostCall, regs, gas.get());
+            pvmInstance.registers.setAllEncoded(regs.getEncoded());
+            if (result === PvmExecution.Halt) {
+                status = Status.HALT;
+                return this.getReturnValue(status, pvmInstance);
+            }
+            if (result === PvmExecution.Panic) {
+                status = Status.PANIC;
+                return this.getReturnValue(status, pvmInstance);
+            }
+            if (result === PvmExecution.OOG) {
+                status = Status.OOG;
+                return this.getReturnValue(status, pvmInstance);
+            }
+            if (result === undefined) {
+                pvmInstance.runProgram();
+                status = pvmInstance.getStatus();
+                continue;
+            }
+            assertNever(result);
+        }
+    }
+    async runProgram(program, args, initialPc, initialGas) {
+        const pvmInstance = await this.pvmInstanceManager.getInstance();
+        pvmInstance.resetJam(program, args, initialPc, initialGas);
+        try {
+            return await this.execute(pvmInstance);
+        }
+        finally {
+            this.pvmInstanceManager.releaseInstance(pvmInstance);
+        }
+    }
+}

package/packages/core/pvm-host-calls/index.d.ts

@@ -0,0 +1,7 @@
+export { type HostCallHandler, PvmExecution, traceRegisters, tryAsHostCallIndex } from "./host-call-handler.js";
+export { HostCallMemory } from "./host-call-memory.js";
+export { HostCallRegisters } from "./host-call-registers.js";
+export { HostCalls as PvmHostCallExtension } from "./host-calls.js";
+export { HostCallsManager as HostCalls } from "./host-calls-manager.js";
+export { InterpreterInstanceManager as PvmInstanceManager } from "./interpreter-instance-manager.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/core/pvm-host-calls/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAChH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,SAAS,IAAI,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,0BAA0B,IAAI,kBAAkB,EAAE,MAAM,mCAAmC,CAAC"}

package/packages/core/pvm-host-calls/index.js

@@ -0,0 +1,6 @@
+export { PvmExecution, traceRegisters, tryAsHostCallIndex } from "./host-call-handler.js";
+export { HostCallMemory } from "./host-call-memory.js";
+export { HostCallRegisters } from "./host-call-registers.js";
+export { HostCalls as PvmHostCallExtension } from "./host-calls.js";
+export { HostCallsManager as HostCalls } from "./host-calls-manager.js";
+export { InterpreterInstanceManager as PvmInstanceManager } from "./interpreter-instance-manager.js";

package/packages/core/pvm-host-calls/interpreter-instance-manager.d.ts

@@ -0,0 +1,11 @@
+import { PvmBackend } from "#@typeberry/config";
+import type { IPvmInterpreter } from "#@typeberry/pvm-interface";
+export declare class InterpreterInstanceManager {
+    private readonly instances;
+    private waitingQueue;
+    private constructor();
+    static new(interpreter: PvmBackend): Promise<InterpreterInstanceManager>;
+    getInstance(): Promise<IPvmInterpreter>;
+    releaseInstance(pvm: IPvmInterpreter): void;
+}
+//# sourceMappingURL=interpreter-instance-manager.d.ts.map

package/packages/core/pvm-host-calls/interpreter-instance-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter-instance-manager.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/interpreter-instance-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAQhE,qBAAa,0BAA0B;IAGjB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAF9C,OAAO,CAAC,YAAY,CAAmB;IAEvC,OAAO;WAEM,GAAG,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAmBxE,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAU7C,eAAe,CAAC,GAAG,EAAE,eAAe;CAOrC"}

package/packages/core/pvm-host-calls/interpreter-instance-manager.js

@@ -0,0 +1,44 @@
+import { PvmBackend } from "#@typeberry/config";
+import { Interpreter } from "#@typeberry/pvm-interpreter";
+import { AnanasInterpreter } from "#@typeberry/pvm-interpreter-ananas";
+import { assertNever } from "#@typeberry/utils";
+// TODO [MaSo] Delete this & also make host calls independent from intepreters.
+export class InterpreterInstanceManager {
+    instances;
+    waitingQueue = [];
+    constructor(instances) {
+        this.instances = instances;
+    }
+    static async new(interpreter) {
+        const instances = [];
+        switch (interpreter) {
+            case PvmBackend.BuiltIn:
+                instances.push(new Interpreter({
+                    useSbrkGas: false,
+                }));
+                break;
+            case PvmBackend.Ananas:
+                instances.push(await AnanasInterpreter.new());
+                break;
+            default:
+                assertNever(interpreter);
+        }
+        return new InterpreterInstanceManager(instances);
+    }
+    async getInstance() {
+        const instance = this.instances.pop();
+        if (instance !== undefined) {
+            return Promise.resolve(instance);
+        }
+        return new Promise((resolve) => {
+            this.waitingQueue.push(resolve);
+        });
+    }
+    releaseInstance(pvm) {
+        const waiting = this.waitingQueue.shift();
+        if (waiting !== undefined) {
+            return waiting(pvm);
+        }
+        this.instances.push(pvm);
+    }
+}

package/packages/core/pvm-interface/gas.d.ts

@@ -0,0 +1,48 @@
+import { type U32, type U64 } from "#@typeberry/numbers";
+import { type Opaque } from "#@typeberry/utils";
+/** A U64 version of `Gas`. */
+export type BigGas = Opaque<U64, "BigGas[U64]">;
+/** A U32 version of `Gas`. */
+export type SmallGas = Opaque<U32, "SmallGas[U32]">;
+/** Gas measuring type. Can be either U64 or U32 for performance reasons. */
+export type Gas = BigGas | SmallGas;
+/** Attempt to convert given number into U32 gas representation. */
+export declare const tryAsSmallGas: (v: number) => SmallGas;
+/** Attempt to convert given number into U64 gas representation. */
+export declare const tryAsBigGas: (v: number | bigint) => BigGas;
+/** Attempt to convert given number into gas. */
+export declare const tryAsGas: (v: number | bigint) => Gas;
+/** An abstraction over gas counter.
+ *
+ * It can be optimized to use numbers instead of bigint in case of small gas.
+ */
+export interface IGasCounter {
+    /**
+     * Set during initialization of GasCounter.
+     *
+     * NOTE: Needed to calculate `used()` gas.
+     */
+    initialGas: Gas;
+    /** Return remaining gas. */
+    get(): Gas;
+    /**
+     * Overwrite remaining gas.
+     *
+     * NOTE: Could cause `used()` gas calculation to be incorrect.
+     *
+     * @see
+     * Prefer sub method instead.
+     */
+    set(g: Gas): void;
+    /** Returns true if there was an underflow. */
+    sub(g: Gas): boolean;
+    /**
+     * Calculates used gas since creation of GasCounter.
+     *
+     * The interface does not handle negative or more than `initialGas` values.
+     *
+     * NOTE: We can use at most `initialGas` and as little as `0`.
+     */
+    used(): Gas;
+}
+//# sourceMappingURL=gas.d.ts.map

package/packages/core/pvm-interface/gas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-interface/gas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;AAChD,8BAA8B;AAC9B,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AACpD,4EAA4E;AAC5E,MAAM,MAAM,GAAG,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,KAAG,QAAqC,CAAC;AAEhF,mEAAmE;AACnE,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,GAAG,MAAM,KAAG,MAAmC,CAAC;AAErF,gDAAgD;AAChD,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,GAAG,MAAM,KAAG,GAC4B,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,UAAU,EAAE,GAAG,CAAC;IAEhB,4BAA4B;IAC5B,GAAG,IAAI,GAAG,CAAC;IAEX;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAElB,8CAA8C;IAC9C,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC;IAErB;;;;;;OAMG;IACH,IAAI,IAAI,GAAG,CAAC;CACb"}

package/packages/core/pvm-interface/gas.js

@@ -0,0 +1,8 @@
+import { tryAsU32, tryAsU64 } from "#@typeberry/numbers";
+import { asOpaqueType } from "#@typeberry/utils";
+/** Attempt to convert given number into U32 gas representation. */
+export const tryAsSmallGas = (v) => asOpaqueType(tryAsU32(v));
+/** Attempt to convert given number into U64 gas representation. */
+export const tryAsBigGas = (v) => asOpaqueType(tryAsU64(v));
+/** Attempt to convert given number into gas. */
+export const tryAsGas = (v) => typeof v === "number" && v < 2 ** 32 ? tryAsSmallGas(v) : tryAsBigGas(v);

package/packages/core/pvm-interface/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./gas.js";
+export * from "./memory.js";
+export * from "./pvm.js";
+export * from "./registers.js";
+export * from "./status.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/core/pvm-interface/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-interface/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/packages/core/pvm-interface/index.js

@@ -0,0 +1,5 @@
+export * from "./gas.js";
+export * from "./memory.js";
+export * from "./pvm.js";
+export * from "./registers.js";
+export * from "./status.js";

package/packages/core/pvm-interface/memory.d.ts

@@ -0,0 +1,16 @@
+import { type U32 } from "#@typeberry/numbers";
+import type { OK, Result } from "#@typeberry/utils";
+export declare const MAX_MEMORY_INDEX = 4294967295;
+export declare const MEMORY_SIZE: number;
+export type PageFault = {
+    address: U32;
+};
+export declare function getPageStartAddress(address: U32): U32;
+/** Allows store and read segments of memory. */
+export interface IMemory {
+    /** Store bytes into memory at given address. */
+    store(address: U32, bytes: Uint8Array): Result<OK, PageFault>;
+    /** Load bytes from memory from given address into given buffer. */
+    read(address: U32, result: Uint8Array): Result<OK, PageFault>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/packages/core/pvm-interface/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-interface/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEnD,eAAO,MAAM,gBAAgB,aAAc,CAAC;AAC5C,eAAO,MAAM,WAAW,QAAuB,CAAC;AAIhD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,GAAG,CAAC;CACd,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG,GAAG,GAAG,CAErD;AAED,gDAAgD;AAChD,MAAM,WAAW,OAAO;IACtB,gDAAgD;IAChD,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,mEAAmE;IACnE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;CAC/D"}

package/packages/core/pvm-interface/memory.js

@@ -0,0 +1,7 @@
+import { tryAsU32 } from "#@typeberry/numbers";
+export const MAX_MEMORY_INDEX = 0xffff_ffff;
+export const MEMORY_SIZE = MAX_MEMORY_INDEX + 1;
+const PAGE_SIZE_SHIFT = 12;
+export function getPageStartAddress(address) {
+    return tryAsU32(((address >>> PAGE_SIZE_SHIFT) << PAGE_SIZE_SHIFT) >>> 0);
+}