@typeberry/lib 0.5.1-a4d7c93 → 0.5.1-eb84786

package/packages/jam/jam-host-calls/refine/historical-lookup.test.js

@@ -0,0 +1,182 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsServiceId } from "#@typeberry/block";
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { tryAsU64 } from "#@typeberry/numbers";
+import { HostCallMemory, HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { tryAsGas } from "#@typeberry/pvm-interface";
+import { gasCounter } from "#@typeberry/pvm-interpreter/gas.js";
+import { MemoryBuilder, tryAsMemoryIndex } from "#@typeberry/pvm-interpreter/memory/index.js";
+import { tryAsSbrkIndex } from "#@typeberry/pvm-interpreter/memory/memory-index.js";
+import { PAGE_SIZE } from "#@typeberry/pvm-interpreter/spi-decoder/memory-conts.js";
+import { TestRefineExt } from "../externalities/refine-externalities.test.js";
+import { HostCallResult } from "../general/results.js";
+import { emptyRegistersBuffer } from "../utils.js";
+import { HistoricalLookup } from "./historical-lookup.js";
+const gas = gasCounter(tryAsGas(0));
+const SERVICE_ID_REG = 7;
+const RESULT_REG = SERVICE_ID_REG;
+const HASH_START_REG = 8;
+const DEST_START_REG = 9;
+const DEST_OFFSET_REG = 10;
+const DEST_LEN_REG = 11;
+function prepareRegsAndMemory(serviceId, hash, offset, destinationLength, { skipHash = false, writableMemory = true } = {}) {
+    const hashAddress = 2 ** 16;
+    const memStart = 2 ** 20;
+    const registers = new HostCallRegisters(emptyRegistersBuffer());
+    registers.set(SERVICE_ID_REG, tryAsU64(serviceId));
+    registers.set(HASH_START_REG, tryAsU64(hashAddress));
+    registers.set(DEST_START_REG, tryAsU64(memStart));
+    registers.set(DEST_OFFSET_REG, tryAsU64(offset));
+    registers.set(DEST_LEN_REG, tryAsU64(destinationLength));
+    const builder = new MemoryBuilder();
+    if (!skipHash) {
+        builder.setReadablePages(tryAsMemoryIndex(hashAddress), tryAsMemoryIndex(hashAddress + PAGE_SIZE), hash.raw);
+    }
+    if (writableMemory) {
+        builder.setWriteablePages(tryAsMemoryIndex(memStart), tryAsMemoryIndex(memStart + PAGE_SIZE));
+    }
+    const memory = new HostCallMemory(builder.finalize(tryAsMemoryIndex(0), tryAsSbrkIndex(0)));
+    return {
+        registers,
+        memory,
+        readResult: () => {
+            const result = new Uint8Array(destinationLength);
+            assert.strictEqual(memory.loadInto(result, tryAsU64(memStart)).isOk, true);
+            return BytesBlob.blobFrom(result);
+        },
+    };
+}
+describe("HostCalls: Historical Lookup", () => {
+    it("should lookup key from an account", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory, readResult } = prepareRegsAndMemory(serviceId, hash, 0, 64);
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(data.length));
+        assert.deepStrictEqual(readResult().toString(), "0x68656c6c6f20776f726c640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000");
+    });
+    it("should lookup key longer than destination", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory, readResult } = prepareRegsAndMemory(serviceId, hash, 0, 3);
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(data.length));
+        assert.deepStrictEqual(readResult().toString(), "0x68656c");
+    });
+    it("should lookup key longer than destination + offset", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory, readResult } = prepareRegsAndMemory(serviceId, hash, 4, 3);
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(data.length));
+        assert.deepStrictEqual(readResult().toString(), "0x6f2077");
+    });
+    it("should handle missing value", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const { registers, memory, readResult } = prepareRegsAndMemory(serviceId, hash, 0, 32);
+        refine.historicalLookupData.set(null, serviceId, hash);
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), HostCallResult.NONE);
+        assert.deepStrictEqual(readResult().toString(), "0x0000000000000000000000000000000000000000000000000000000000000000");
+    });
+    it("should panic if no memory for key", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const { registers, memory } = prepareRegsAndMemory(serviceId, hash, 0, 32, { skipHash: true });
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(serviceId));
+    });
+    it("should panic if memory is not writable", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory } = prepareRegsAndMemory(serviceId, hash, 0, 32, { writableMemory: false });
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(serviceId));
+    });
+    it("should handle if the destination length is greater than data length", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory, readResult } = prepareRegsAndMemory(serviceId, hash, 0, 32);
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        registers.set(DEST_LEN_REG, tryAsU64(PAGE_SIZE + 1));
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(data.length));
+        assert.deepStrictEqual(readResult().toString(), "0x68656c6c6f20776f726c64000000000000000000000000000000000000000000");
+    });
+    it("should panic if the destination is beyond mem limit", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory } = prepareRegsAndMemory(serviceId, hash, 0, 32);
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        registers.set(DEST_START_REG, tryAsU64(2 ** 32 - 1));
+        registers.set(DEST_LEN_REG, tryAsU64(2 ** 10));
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(serviceId));
+    });
+    it("should handle 0-length destination", async () => {
+        const refine = new TestRefineExt();
+        const lookup = new HistoricalLookup(refine);
+        const serviceId = tryAsServiceId(10_000);
+        const hash = Bytes.fill(32, 3);
+        const data = "hello world";
+        const { registers, memory } = prepareRegsAndMemory(serviceId, hash, 0, 0);
+        refine.historicalLookupData.set(BytesBlob.blobFromString(data), serviceId, hash);
+        // when
+        const result = await lookup.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64(data.length));
+    });
+});

package/packages/jam/jam-host-calls/refine/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./export.js";
+export * from "./expunge.js";
+export * from "./historical-lookup.js";
+export * from "./invoke.js";
+export * from "./machine.js";
+export * from "./pages.js";
+export * from "./peek.js";
+export * from "./poke.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/jam/jam-host-calls/refine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/jam/jam-host-calls/refine/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}

package/packages/jam/jam-host-calls/refine/index.js

@@ -0,0 +1,8 @@
+export * from "./export.js";
+export * from "./expunge.js";
+export * from "./historical-lookup.js";
+export * from "./invoke.js";
+export * from "./machine.js";
+export * from "./pages.js";
+export * from "./peek.js";
+export * from "./poke.js";

package/packages/jam/jam-host-calls/refine/invoke.d.ts

@@ -0,0 +1,18 @@
+import { type HostCallHandler, type HostCallMemory, HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { type IGasCounter } from "#@typeberry/pvm-interface";
+import { type RefineExternalities } from "../externalities/refine-externalities.js";
+/**
+ * Kick off (run) a PVM instance given the machine index and the destination memory (which contains gas and registers values).
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/354301354301?v=0.6.7
+ */
+export declare class Invoke implements HostCallHandler {
+    private readonly refine;
+    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: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"ServiceId[u32]">;
+    tracedRegisters: (number & import("@typeberry/utils").WithOpaque<"register index">)[];
+    constructor(refine: RefineExternalities);
+    execute(_gas: IGasCounter, regs: HostCallRegisters, memory: HostCallMemory): Promise<PvmExecution | undefined>;
+}
+//# sourceMappingURL=invoke.d.ts.map

package/packages/jam/jam-host-calls/refine/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../../../../../packages/jam/jam-host-calls/refine/invoke.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,iBAAiB,EACjB,YAAY,EAGb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,WAAW,EAMjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,0CAA0C,CAAC;AAapG;;;;GAIG;AACH,qBAAa,MAAO,YAAW,eAAe;IAMhC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,KAAK,iIAA0B;IAC/B,YAAY,4HAAqB;IACjC,gBAAgB,6HAAsB;IACtC,eAAe,uEAA8C;gBAEhC,MAAM,EAAE,mBAAmB;IAElD,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CAyErH"}

package/packages/jam/jam-host-calls/refine/invoke.js

@@ -0,0 +1,93 @@
+import { Bytes } from "#@typeberry/bytes";
+import { codec, Decoder, Encoder, tryAsExactBytes } from "#@typeberry/codec";
+import { tryAsU64 } from "#@typeberry/numbers";
+import { HostCallRegisters, PvmExecution, traceRegisters, tryAsHostCallIndex, } from "#@typeberry/pvm-host-calls";
+import { NO_OF_REGISTERS, REGISTER_BYTE_SIZE, Status, tryAsBigGas, tryAsSmallGas, } from "#@typeberry/pvm-interface";
+import { check, resultToString } from "#@typeberry/utils";
+import { tryAsMachineId } from "../externalities/refine-externalities.js";
+import { HostCallResult } from "../general/results.js";
+import { logger } from "../logger.js";
+import { CURRENT_SERVICE_ID } from "../utils.js";
+const IN_OUT_REG_1 = 7;
+const IN_OUT_REG_2 = 8;
+const gasAndRegistersCodec = codec.object({
+    gas: codec.i64,
+    registers: codec.bytes(NO_OF_REGISTERS * REGISTER_BYTE_SIZE),
+});
+const GAS_REGISTERS_SIZE = tryAsExactBytes(gasAndRegistersCodec.sizeHint);
+/**
+ * Kick off (run) a PVM instance given the machine index and the destination memory (which contains gas and registers values).
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/354301354301?v=0.6.7
+ */
+export class Invoke {
+    refine;
+    index = tryAsHostCallIndex(12);
+    basicGasCost = tryAsSmallGas(10);
+    currentServiceId = CURRENT_SERVICE_ID;
+    tracedRegisters = traceRegisters(IN_OUT_REG_1, IN_OUT_REG_2);
+    constructor(refine) {
+        this.refine = refine;
+    }
+    async execute(_gas, regs, memory) {
+        // `n`: machine index
+        const machineIndex = tryAsMachineId(regs.get(IN_OUT_REG_1));
+        // `o`: destination memory start (local)
+        const destinationStart = regs.get(IN_OUT_REG_2);
+        // extracting gas and registers from memory
+        const initialData = Bytes.zero(GAS_REGISTERS_SIZE);
+        const readResult = memory.loadInto(initialData.raw, destinationStart);
+        if (readResult.isError) {
+            logger.trace `[${this.currentServiceId}] INVOKE(${machineIndex}) <- PANIC (read)`;
+            return PvmExecution.Panic;
+        }
+        // we also need to make sure that the memory is writeable, so we attempt to
+        // write the data back. This is a bit redundant, but saves us from creating
+        // the weird `isWriteable` method.
+        const writeResult = memory.storeFrom(destinationStart, initialData.raw);
+        if (writeResult.isError) {
+            logger.trace `[${this.currentServiceId}] INVOKE(${machineIndex}) <- PANIC (write)`;
+            return PvmExecution.Panic;
+        }
+        const gasRegisters = Decoder.decodeObject(gasAndRegistersCodec, initialData);
+        // `g`
+        const gasCost = tryAsBigGas(gasRegisters.gas);
+        // `w`
+        const registers = new HostCallRegisters(gasRegisters.registers.raw);
+        // try run the machine
+        const state = await this.refine.machineInvoke(machineIndex, gasCost, registers);
+        logger.trace `[${this.currentServiceId}] INVOKE(${machineIndex}, ${gasCost}, ${registers}) <- ${resultToString(state)}`;
+        // machine not found
+        if (state.isError) {
+            regs.set(IN_OUT_REG_1, HostCallResult.WHO);
+            return;
+        }
+        const machineState = state.ok;
+        // save the result to the destination memory
+        const resultData = Encoder.encodeObject(gasAndRegistersCodec, {
+            gas: machineState.gas,
+            registers: Bytes.fromBlob(machineState.registers.getEncoded(), NO_OF_REGISTERS * REGISTER_BYTE_SIZE),
+        });
+        // this fault does not need to be handled, because we've ensured it's
+        // already writeable earlier.
+        const storeResult = memory.storeFrom(destinationStart, resultData.raw);
+        check `${storeResult.isOk} Memory writeability has been checked already.`;
+        const returnState = machineState.result;
+        if (returnState.status === Status.HOST) {
+            regs.set(IN_OUT_REG_1, tryAsU64(returnState.status));
+            regs.set(IN_OUT_REG_2, returnState.hostCallIndex);
+            return;
+        }
+        if (returnState.status === Status.FAULT) {
+            regs.set(IN_OUT_REG_1, tryAsU64(returnState.status));
+            regs.set(IN_OUT_REG_2, returnState.address);
+            return;
+        }
+        if ([Status.PANIC, Status.HALT, Status.OOG].includes(returnState.status)) {
+            regs.set(IN_OUT_REG_1, tryAsU64(returnState.status));
+            return;
+        }
+        const statusName = Status[returnState.status] !== undefined ? Status[returnState.status] : "Unknown";
+        throw new Error(`Unexpected inner PVM result: ${returnState.status} (${statusName})`);
+    }
+}

package/packages/jam/jam-host-calls/refine/invoke.test.d.ts

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

package/packages/jam/jam-host-calls/refine/invoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/jam/jam-host-calls/refine/invoke.test.ts"],"names":[],"mappings":""}

package/packages/jam/jam-host-calls/refine/invoke.test.js

@@ -0,0 +1,180 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsServiceId } from "#@typeberry/block";
+import { Bytes } from "#@typeberry/bytes";
+import { tryAsU64 } from "#@typeberry/numbers";
+import { HostCallMemory, HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { Status, tryAsGas } from "#@typeberry/pvm-interface";
+import { gasCounter, MemoryBuilder } from "#@typeberry/pvm-interpreter";
+import { RESERVED_NUMBER_OF_PAGES } from "#@typeberry/pvm-interpreter/memory/memory-consts.js";
+import { tryAsMemoryIndex, tryAsSbrkIndex } from "#@typeberry/pvm-interpreter/memory/memory-index.js";
+import { PAGE_SIZE } from "#@typeberry/pvm-interpreter/spi-decoder/memory-conts.js";
+import { MachineInstance, tryAsMachineId, } from "../externalities/refine-externalities.js";
+import { TestRefineExt } from "../externalities/refine-externalities.test.js";
+import { HostCallResult } from "../general/results.js";
+import { emptyRegistersBuffer } from "../utils.js";
+import { Invoke } from "./invoke.js";
+const gas = gasCounter(tryAsGas(0));
+const MACHINE_INDEX_REG = 7;
+const RESULT_REG_1 = MACHINE_INDEX_REG;
+const DEST_REG = 8;
+const RESULT_REG_2 = DEST_REG;
+const GAS_REG_SIZE = 112;
+const MEM_START = RESERVED_NUMBER_OF_PAGES * PAGE_SIZE;
+function prepareRegsAndMemory(machineIndex, destinationStart, data, { registerMemory = true } = {}) {
+    const registers = new HostCallRegisters(emptyRegistersBuffer());
+    registers.set(MACHINE_INDEX_REG, machineIndex);
+    registers.set(DEST_REG, tryAsU64(destinationStart));
+    const memory = new HostCallMemory(prepareMemory(data, destinationStart, PAGE_SIZE, { registerMemory }));
+    return {
+        registers,
+        memory,
+    };
+}
+function prepareMemory(data, address, size, { registerMemory = true } = {}) {
+    const builder = new MemoryBuilder();
+    const addressAsNumber = Number(address);
+    if (registerMemory) {
+        builder.setWriteablePages(tryAsMemoryIndex(addressAsNumber), tryAsMemoryIndex(addressAsNumber + size), data.raw);
+    }
+    return builder.finalize(tryAsMemoryIndex(0), tryAsSbrkIndex(0));
+}
+async function prepareMachine(machineStatus, { registerMachine = true } = {}) {
+    const refine = new TestRefineExt();
+    const machineId = tryAsMachineId(10_000);
+    if (registerMachine) {
+        refine.machineInvokeData.set(machineId, new MachineInstance());
+        refine.machineInvokeStatus = machineStatus;
+    }
+    return [refine, machineId];
+}
+describe("HostCalls: Invoke", () => {
+    it("should return panic if memory is unwritable", async () => {
+        const [refine, machineId] = await prepareMachine({
+            status: Status.OK,
+        }, {
+            registerMachine: false,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code, { registerMemory: false });
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), w7);
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), w8);
+    });
+    it("should return `who` if machine is not found (machine not initialized)", async () => {
+        const [refine, machineId] = await prepareMachine({
+            status: Status.OK,
+        }, {
+            registerMachine: false,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), HostCallResult.WHO);
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), w8);
+    });
+    it("should return `who` if machine is not found (machine id is not valid)", async () => {
+        const [refine, machineId] = await prepareMachine({
+            status: Status.OK,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId + 1n);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), HostCallResult.WHO);
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), w8);
+    });
+    it("should run the machine and finish with `host` status", async () => {
+        const hostCallIndex = tryAsU64(10);
+        const [refine, machineId] = await prepareMachine({
+            status: Status.HOST,
+            hostCallIndex,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), tryAsU64(Status.HOST));
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), hostCallIndex);
+    });
+    it("should run the machine and finish with `fault` status", async () => {
+        const address = tryAsU64(2 ** 20);
+        const [refine, machineId] = await prepareMachine({
+            status: Status.FAULT,
+            address,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), tryAsU64(Status.FAULT));
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), address);
+    });
+    it("should run the machine and finish with `oog` status", async () => {
+        const [refine, machineId] = await prepareMachine({
+            status: Status.OOG,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), tryAsU64(Status.OOG));
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), w8);
+    });
+    it("should run the machine and finish with `panic` status", async () => {
+        const [refine, machineId] = await prepareMachine({
+            status: Status.PANIC,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), tryAsU64(Status.PANIC));
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), w8);
+    });
+    it("should run the machine and finish with `halt` status", async () => {
+        const [refine, machineId] = await prepareMachine({
+            status: Status.HALT,
+        });
+        const invoke = new Invoke(refine);
+        invoke.currentServiceId = tryAsServiceId(10_000);
+        const w7 = tryAsU64(machineId);
+        const w8 = tryAsU64(MEM_START);
+        const code = Bytes.zero(GAS_REG_SIZE);
+        const { registers, memory } = prepareRegsAndMemory(w7, w8, code);
+        const result = await invoke.execute(gas, registers, memory);
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG_1), tryAsU64(Status.HALT));
+        assert.deepStrictEqual(registers.get(RESULT_REG_2), w8);
+    });
+});

package/packages/jam/jam-host-calls/refine/machine.d.ts

@@ -0,0 +1,18 @@
+import { type HostCallHandler, type HostCallMemory, type HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { type IGasCounter } from "#@typeberry/pvm-interface";
+import { type RefineExternalities } from "../externalities/refine-externalities.js";
+/**
+ * Initiate a PVM instance with given program code and entrypoint (program counter).
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/34aa0134aa01?v=0.6.7
+ */
+export declare class Machine implements HostCallHandler {
+    private readonly refine;
+    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: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"ServiceId[u32]">;
+    tracedRegisters: (number & import("@typeberry/utils").WithOpaque<"register index">)[];
+    constructor(refine: RefineExternalities);
+    execute(_gas: IGasCounter, regs: HostCallRegisters, memory: HostCallMemory): Promise<PvmExecution | undefined>;
+}
+//# sourceMappingURL=machine.d.ts.map

package/packages/jam/jam-host-calls/refine/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../../../../packages/jam/jam-host-calls/refine/machine.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,YAAY,EAGb,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAE3E,OAAO,EAAE,KAAK,mBAAmB,EAAuB,MAAM,0CAA0C,CAAC;AAOzG;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,eAAe;IAMjC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,KAAK,iIAAyB;IAC9B,YAAY,4HAAqB;IACjC,gBAAgB,6HAAsB;IACtC,eAAe,uEAAoC;gBAEtB,MAAM,EAAE,mBAAmB;IAElD,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CA2BrH"}

package/packages/jam/jam-host-calls/refine/machine.js

@@ -0,0 +1,49 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { PvmExecution, traceRegisters, tryAsHostCallIndex, } from "#@typeberry/pvm-host-calls";
+import { tryAsSmallGas } from "#@typeberry/pvm-interface";
+import { resultToString, safeAllocUint8Array } from "#@typeberry/utils";
+import { tryAsProgramCounter } from "../externalities/refine-externalities.js";
+import { HostCallResult } from "../general/results.js";
+import { logger } from "../logger.js";
+import { CURRENT_SERVICE_ID, clampU64ToU32 } from "../utils.js";
+const IN_OUT_REG = 7;
+/**
+ * Initiate a PVM instance with given program code and entrypoint (program counter).
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/34aa0134aa01?v=0.6.7
+ */
+export class Machine {
+    refine;
+    index = tryAsHostCallIndex(8);
+    basicGasCost = tryAsSmallGas(10);
+    currentServiceId = CURRENT_SERVICE_ID;
+    tracedRegisters = traceRegisters(IN_OUT_REG, 8, 9);
+    constructor(refine) {
+        this.refine = refine;
+    }
+    async execute(_gas, regs, memory) {
+        // `p_o`: memory index where there program code starts
+        const codeStart = regs.get(IN_OUT_REG);
+        // `p_z`: length of the program code
+        const codeLength = regs.get(8);
+        // `i`: starting program counter
+        const entrypoint = tryAsProgramCounter(regs.get(9));
+        const codeLengthClamped = clampU64ToU32(codeLength);
+        const code = BytesBlob.blobFrom(safeAllocUint8Array(codeLengthClamped));
+        const codeLoadResult = memory.loadInto(code.raw, codeStart);
+        if (codeLoadResult.isError) {
+            logger.trace `[${this.currentServiceId}] MACHINE(${code.toStringTruncated()}, ${entrypoint}) <- PANIC`;
+            return PvmExecution.Panic;
+        }
+        // NOTE: Highly unlikely, but machineId could potentially collide with HOST_CALL_RESULT.
+        const machinInitResult = await this.refine.machineInit(code, entrypoint);
+        logger.trace `[${this.currentServiceId}] MACHINE(${code.toStringTruncated()}, ${entrypoint}) <- ${resultToString(machinInitResult)}`;
+        logger.insane `[${this.currentServiceId}] MACHINE(${code}, ${entrypoint}) <- ${resultToString(machinInitResult)}`;
+        if (machinInitResult.isError) {
+            regs.set(IN_OUT_REG, HostCallResult.HUH);
+        }
+        else {
+            regs.set(IN_OUT_REG, machinInitResult.ok);
+        }
+    }
+}

package/packages/jam/jam-host-calls/refine/machine.test.d.ts

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

package/packages/jam/jam-host-calls/refine/machine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/jam/jam-host-calls/refine/machine.test.ts"],"names":[],"mappings":""}