@typeberry/lib 0.5.1-aff8b4f → 0.5.1-eb84786

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-one-offset-dispatcher.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { ArgumentType } from "../args-decoder/argument-type.js";
+import { instructionArgumentTypeMap } from "../args-decoder/instruction-argument-type-map.js";
+import { BasicBlocks } from "../basic-blocks/index.js";
+import { Instruction } from "../instruction.js";
+import { InstructionResult } from "../instruction-result.js";
+import { BranchOps } from "../ops/index.js";
+import { Registers } from "../registers.js";
+import { TwoRegsOneOffsetDispatcher } from "./two-regs-one-offset-dispatcher.js";
+test("TwoRegsOneOffsetDispatcher", async (t) => {
+    const regs = new Registers();
+    const instructionResult = new InstructionResult();
+    const basicBlocks = new BasicBlocks();
+    const branchOps = new BranchOps(regs, instructionResult, basicBlocks);
+    const mockFn = t.mock.fn();
+    function mockAllMethods(obj) {
+        const methodNames = Object.getOwnPropertyNames(Object.getPrototypeOf(obj));
+        for (const method of methodNames) {
+            t.mock.method(obj, method, mockFn);
+        }
+    }
+    t.before(() => {
+        mockAllMethods(branchOps);
+    });
+    t.after(() => {
+        t.mock.restoreAll();
+    });
+    t.beforeEach(() => {
+        mockFn.mock.resetCalls();
+    });
+    const argsMock = {};
+    const relevantInstructions = Object.entries(Instruction)
+        .filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "number")
+        .filter((entry) => instructionArgumentTypeMap[entry[1]] === ArgumentType.TWO_REGISTERS_ONE_OFFSET);
+    for (const [name, instruction] of relevantInstructions) {
+        await t.test(`checks if instruction ${name} = ${instruction} is handled by TwoRegsOneOffsetDispatcher`, () => {
+            const dispatcher = new TwoRegsOneOffsetDispatcher(branchOps);
+            dispatcher.dispatch(instruction, argsMock);
+            assert.strictEqual(mockFn.mock.calls.length, 1);
+        });
+    }
+    const otherInstructions = Object.entries(Instruction)
+        .filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "number")
+        .filter((entry) => instructionArgumentTypeMap[entry[1]] !== ArgumentType.TWO_REGISTERS_ONE_OFFSET);
+    for (const [name, instruction] of otherInstructions) {
+        await t.test(`checks if instruction ${name} = ${instruction} is not handled by TwoRegsOneOffsetDispatcher`, () => {
+            const dispatcher = new TwoRegsOneOffsetDispatcher(branchOps);
+            dispatcher.dispatch(instruction, argsMock);
+            assert.strictEqual(mockFn.mock.calls.length, 0);
+        });
+    }
+});

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.d.ts

@@ -0,0 +1,10 @@
+import type { TwoRegistersTwoImmediatesArgs } from "../args-decoder/args-decoder.js";
+import { Instruction } from "../instruction.js";
+import type { DynamicJumpOps, LoadOps } from "../ops/index.js";
+export declare class TwoRegsTwoImmsDispatcher {
+    private loadOps;
+    private dynamicJumpOps;
+    constructor(loadOps: LoadOps, dynamicJumpOps: DynamicJumpOps);
+    dispatch(instruction: Instruction, args: TwoRegistersTwoImmediatesArgs): void;
+}
+//# sourceMappingURL=two-regs-two-imms-dispatcher.d.ts.map

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-regs-two-imms-dispatcher.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/D,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,cAAc;gBADd,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,cAAc;IAGxC,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,6BAA6B;CAUvE"}

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.js

@@ -0,0 +1,19 @@
+import { Instruction } from "../instruction.js";
+export class TwoRegsTwoImmsDispatcher {
+    loadOps;
+    dynamicJumpOps;
+    constructor(loadOps, dynamicJumpOps) {
+        this.loadOps = loadOps;
+        this.dynamicJumpOps = dynamicJumpOps;
+    }
+    dispatch(instruction, args) {
+        switch (instruction) {
+            case Instruction.LOAD_IMM_JUMP_IND: {
+                const address = this.dynamicJumpOps.caluclateJumpAddress(args.secondImmediateDecoder, args.secondRegisterIndex);
+                this.loadOps.loadImmediate(args.firstRegisterIndex, args.firstImmediateDecoder);
+                this.dynamicJumpOps.jumpInd(address);
+                break;
+            }
+        }
+    }
+}

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.test.d.ts

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

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-regs-two-imms-dispatcher.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-interpreter/ops-dispatchers/two-regs-two-imms-dispatcher.test.js

@@ -0,0 +1,93 @@
+import assert from "node:assert";
+import { after, before, beforeEach, describe, it, mock } from "node:test";
+import { ArgumentType } from "../args-decoder/argument-type.js";
+import { ImmediateDecoder } from "../args-decoder/decoders/immediate-decoder.js";
+import { instructionArgumentTypeMap } from "../args-decoder/instruction-argument-type-map.js";
+import { BasicBlocks } from "../basic-blocks/index.js";
+import { Instruction } from "../instruction.js";
+import { InstructionResult } from "../instruction-result.js";
+import { Memory } from "../memory/index.js";
+import { DynamicJumpOps, LoadOps } from "../ops/index.js";
+import { JumpTable } from "../program-decoder/jump-table.js";
+import { Registers } from "../registers.js";
+import { TwoRegsTwoImmsDispatcher } from "./two-regs-two-imms-dispatcher.js";
+describe("TwoRegsTwoImmsDispatcher", () => {
+    describe("check if it handles expected instructions", () => {
+        const regs = new Registers();
+        const memory = new Memory();
+        const jumpTable = new JumpTable(1, new Uint8Array([1]));
+        const instructionResult = new InstructionResult();
+        const loadOps = new LoadOps(regs, memory, instructionResult);
+        const basicBlocks = new BasicBlocks();
+        const dynamicJumpOps = new DynamicJumpOps(regs, jumpTable, instructionResult, basicBlocks);
+        const loadImmediateMock = mock.fn();
+        const jumpIndMock = mock.fn();
+        after(() => {
+            mock.restoreAll();
+        });
+        beforeEach(() => {
+            loadImmediateMock.mock.resetCalls();
+            jumpIndMock.mock.resetCalls();
+        });
+        before(() => {
+            mock.method(dynamicJumpOps, "jumpInd", jumpIndMock);
+            mock.method(loadOps, "loadImmediate", loadImmediateMock);
+        });
+        const argsMock = {
+            firstRegisterIndex: 1,
+            secondRegisterIndex: 2,
+            firstImmediateDecoder: new ImmediateDecoder(),
+            secondImmediateDecoder: new ImmediateDecoder(),
+        };
+        it("should call LoadOps.loadImmediate", () => {
+            const dispatcher = new TwoRegsTwoImmsDispatcher(loadOps, dynamicJumpOps);
+            dispatcher.dispatch(Instruction.LOAD_IMM_JUMP_IND, argsMock);
+            assert.strictEqual(loadImmediateMock.mock.calls.length, 1);
+        });
+        it("should call DynamicJumpOps.jumpInd", () => {
+            const dispatcher = new TwoRegsTwoImmsDispatcher(loadOps, dynamicJumpOps);
+            dispatcher.dispatch(Instruction.LOAD_IMM_JUMP_IND, argsMock);
+            assert.strictEqual(jumpIndMock.mock.calls.length, 1);
+        });
+    });
+    describe("check if it handles other instructions than expected", () => {
+        const instructionResult = new InstructionResult();
+        const regs = new Registers();
+        const memory = new Memory();
+        const loadOps = new LoadOps(regs, memory, instructionResult);
+        const jumpTable = new JumpTable(1, new Uint8Array([1]));
+        const basicBlocks = new BasicBlocks();
+        const dynamicJumpOps = new DynamicJumpOps(regs, jumpTable, instructionResult, basicBlocks);
+        const mockFn = mock.fn();
+        function mockAllMethods(obj) {
+            const methodNames = Object.getOwnPropertyNames(Object.getPrototypeOf(obj));
+            for (const method of methodNames) {
+                mock.method(obj, method, mockFn);
+            }
+        }
+        before(() => {
+            mockAllMethods(dynamicJumpOps);
+            mockAllMethods(loadOps);
+        });
+        after(() => {
+            mock.restoreAll();
+        });
+        beforeEach(() => {
+            mockFn.mock.resetCalls();
+        });
+        const argsMock = {
+            firstImmediateDecoder: new ImmediateDecoder(),
+            secondImmediateDecoder: new ImmediateDecoder(),
+        };
+        const otherInstructions = Object.entries(Instruction)
+            .filter((entry) => typeof entry[0] === "string" && typeof entry[1] === "number")
+            .filter((entry) => instructionArgumentTypeMap[entry[1]] !== ArgumentType.TWO_REGISTERS_TWO_IMMEDIATES);
+        for (const [name, instruction] of otherInstructions) {
+            it(`checks if instruction ${name} = ${instruction} is not handled by TwoRegsOneImmDispatcher`, () => {
+                const dispatcher = new TwoRegsTwoImmsDispatcher(loadOps, dynamicJumpOps);
+                dispatcher.dispatch(instruction, argsMock);
+                assert.strictEqual(mockFn.mock.calls.length, 0);
+            });
+        }
+    });
+});

package/packages/core/pvm-interpreter/program-decoder/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./jump-table.js";
+export * from "./mask.js";
+export * from "./program-decoder.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/core/pvm-interpreter/program-decoder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC"}

package/packages/core/pvm-interpreter/program-decoder/index.js

@@ -0,0 +1,3 @@
+export * from "./jump-table.js";
+export * from "./mask.js";
+export * from "./program-decoder.js";

package/packages/core/pvm-interpreter/program-decoder/jump-table.d.ts

@@ -0,0 +1,11 @@
+export declare class JumpTable {
+    private indices;
+    constructor(itemByteLength: number, bytes: Uint8Array);
+    private decodeNext;
+    hasIndex(index: number): boolean;
+    getDestination(index: number): number;
+    static empty(): JumpTable;
+    getSize(): number;
+    copyFrom(jt: JumpTable): void;
+}
+//# sourceMappingURL=jump-table.d.ts.map

package/packages/core/pvm-interpreter/program-decoder/jump-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jump-table.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/jump-table.ts"],"names":[],"mappings":"AAEA,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAc;gBAEjB,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAerD,OAAO,CAAC,UAAU;IAgBlB,QAAQ,CAAC,KAAK,EAAE,MAAM;IAItB,cAAc,CAAC,KAAK,EAAE,MAAM;IAI5B,MAAM,CAAC,KAAK;IAIZ,OAAO;IAIP,QAAQ,CAAC,EAAE,EAAE,SAAS;CAGvB"}

package/packages/core/pvm-interpreter/program-decoder/jump-table.js

@@ -0,0 +1,43 @@
+import { check } from "#@typeberry/utils";
+export class JumpTable {
+    indices;
+    constructor(itemByteLength, bytes) {
+        check `
+      ${itemByteLength === 0 || bytes.length % itemByteLength === 0}
+      Length of jump table (${bytes.length}) should be a multiple of item lenght (${itemByteLength})!
+    `;
+        const length = itemByteLength === 0 ? 0 : bytes.length / itemByteLength;
+        this.indices = new Uint32Array(length);
+        for (let i = 0; i < length; i++) {
+            this.indices[i] = this.decodeNext(bytes.subarray(i * itemByteLength, (i + 1) * itemByteLength));
+        }
+    }
+    decodeNext(bytes) {
+        const itemByteLength = bytes.length;
+        let value = 0;
+        for (let i = 0; i < itemByteLength; i++) {
+            if ((value & 0xff00_0000) > 0) {
+                // the value is going to exceed u32 so we can clamp it
+                return 2 ** 32 - 1;
+            }
+            value <<= 8;
+            value |= bytes[itemByteLength - i - 1];
+        }
+        return value;
+    }
+    hasIndex(index) {
+        return index < this.indices.length && index >= 0;
+    }
+    getDestination(index) {
+        return this.indices[index];
+    }
+    static empty() {
+        return new JumpTable(0, new Uint8Array());
+    }
+    getSize() {
+        return this.indices.length;
+    }
+    copyFrom(jt) {
+        this.indices = jt.indices;
+    }
+}

package/packages/core/pvm-interpreter/program-decoder/jump-table.test.d.ts

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

package/packages/core/pvm-interpreter/program-decoder/jump-table.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jump-table.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/jump-table.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-interpreter/program-decoder/jump-table.test.js

@@ -0,0 +1,58 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { JumpTable } from "./jump-table.js";
+describe("JumpTable", () => {
+    it("should return true when an index exist in jump table", () => {
+        const jumpTableItemLength = 4;
+        const bytes = new Uint8Array([0x78, 0x56, 0x34, 0x12]);
+        const jumpTable = new JumpTable(jumpTableItemLength, bytes);
+        const indexToCheck = 0;
+        const result = jumpTable.hasIndex(indexToCheck);
+        assert.strictEqual(result, true);
+    });
+    it("should return false when an index not exist in jump table", () => {
+        const jumpTableItemLength = 4;
+        const bytes = new Uint8Array([0x78, 0x56, 0x34, 0x12]);
+        const jumpTable = new JumpTable(jumpTableItemLength, bytes);
+        const indexToCheck = 5;
+        const result = jumpTable.hasIndex(indexToCheck);
+        assert.strictEqual(result, false);
+    });
+    it("should return correct destination", () => {
+        const jumpTableItemLength = 4;
+        const expectedValue = 0x12_34_56_78;
+        const bytes = new Uint8Array([0xff, 0xff, 0xff, 0xff, 0x78, 0x56, 0x34, 0x12]);
+        const jumpTable = new JumpTable(jumpTableItemLength, bytes);
+        const indexToCheck = 1;
+        const result = jumpTable.getDestination(indexToCheck);
+        assert.strictEqual(result, expectedValue);
+    });
+    it("should load jump table that has u64 item that is bigger than 2 ** 32 - 1", () => {
+        const jumpTableItemLength = 8;
+        const expectedValue = 0xff_ff_ff_ff;
+        const bytes = new Uint8Array([0xff, 0xff, 0xff, 0xff, 0x78, 0x56, 0x34, 0x12]);
+        const jumpTable = new JumpTable(jumpTableItemLength, bytes);
+        const indexToCheck = 0;
+        const result = jumpTable.getDestination(indexToCheck);
+        assert.strictEqual(result, expectedValue);
+    });
+    it("should load jump table that has u64 item that is lower than 2 ** 32 - 1", () => {
+        const jumpTableItemLength = 8;
+        const expectedValue = 0x00_00_00_00_12_34_56_78;
+        const bytes = new Uint8Array([0x78, 0x56, 0x34, 0x12, 0, 0, 0, 0]);
+        const jumpTable = new JumpTable(jumpTableItemLength, bytes);
+        const indexToCheck = 0;
+        const result = jumpTable.getDestination(indexToCheck);
+        assert.strictEqual(result, expectedValue);
+    });
+    it("should load huge jump table", () => {
+        const jumpTableItemLength = 255;
+        const expectedValue = 2 ** 32 - 1;
+        const bytes = new Uint8Array(255);
+        bytes.fill(1);
+        const jumpTable = new JumpTable(jumpTableItemLength, bytes);
+        const indexToCheck = 0;
+        const result = jumpTable.getDestination(indexToCheck);
+        assert.strictEqual(result, expectedValue);
+    });
+});

package/packages/core/pvm-interpreter/program-decoder/mask.d.ts

@@ -0,0 +1,26 @@
+import { BitVec } from "#@typeberry/bytes";
+/**
+ * Mask class is an implementation of skip function defined in GP.
+ *
+ * https://graypaper.fluffylabs.dev/#/5f542d7/237201239801
+ */
+export declare class Mask {
+    /**
+     * The lookup table will have `0` at the index which corresponds to an instruction on the same index in the bytecode.
+     * In case the value is non-zero it signifies the offset to the index with next instruction.
+     *
+     * Example:
+     * ```
+     * 0..1..2..3..4..5..6..7..8..9 # Indices
+     * 0..2..1..0..1..0..3..2..1..0 # lookupTable forward values
+     * ```
+     * There are instructions at indices `0, 3, 5, 9`.
+     */
+    private lookupTableForward;
+    constructor(mask: BitVec);
+    isInstruction(index: number): boolean;
+    getNoOfBytesToNextInstruction(index: number): number;
+    private buildLookupTableForward;
+    static empty(): Mask;
+}
+//# sourceMappingURL=mask.d.ts.map

package/packages/core/pvm-interpreter/program-decoder/mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/mask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAQ1C;;;;GAIG;AACH,qBAAa,IAAI;IACf;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB,CAAa;gBAE3B,IAAI,EAAE,MAAM;IAIxB,aAAa,CAAC,KAAK,EAAE,MAAM;IAI3B,6BAA6B,CAAC,KAAK,EAAE,MAAM;IAK3C,OAAO,CAAC,uBAAuB;IAc/B,MAAM,CAAC,KAAK;CAGb"}

package/packages/core/pvm-interpreter/program-decoder/mask.js

@@ -0,0 +1,52 @@
+import { BitVec } from "#@typeberry/bytes";
+import { check, safeAllocUint8Array } from "#@typeberry/utils";
+/**
+ * Upper bound of instruction distance - it is equal to max value of GP's skip function + 1
+ */
+const MAX_INSTRUCTION_DISTANCE = 25;
+/**
+ * Mask class is an implementation of skip function defined in GP.
+ *
+ * https://graypaper.fluffylabs.dev/#/5f542d7/237201239801
+ */
+export class Mask {
+    /**
+     * The lookup table will have `0` at the index which corresponds to an instruction on the same index in the bytecode.
+     * In case the value is non-zero it signifies the offset to the index with next instruction.
+     *
+     * Example:
+     * ```
+     * 0..1..2..3..4..5..6..7..8..9 # Indices
+     * 0..2..1..0..1..0..3..2..1..0 # lookupTable forward values
+     * ```
+     * There are instructions at indices `0, 3, 5, 9`.
+     */
+    lookupTableForward;
+    constructor(mask) {
+        this.lookupTableForward = this.buildLookupTableForward(mask);
+    }
+    isInstruction(index) {
+        return this.lookupTableForward[index] === 0;
+    }
+    getNoOfBytesToNextInstruction(index) {
+        check `${index >= 0} index (${index}) cannot be a negative number`;
+        return Math.min(this.lookupTableForward[index] ?? 0, MAX_INSTRUCTION_DISTANCE);
+    }
+    buildLookupTableForward(mask) {
+        const table = safeAllocUint8Array(mask.bitLength);
+        let lastInstructionOffset = 0;
+        for (let i = mask.bitLength - 1; i >= 0; i--) {
+            if (mask.isSet(i)) {
+                lastInstructionOffset = 0;
+            }
+            else {
+                lastInstructionOffset++;
+            }
+            table[i] = lastInstructionOffset;
+        }
+        return table;
+    }
+    static empty() {
+        return new Mask(BitVec.empty(0));
+    }
+}

package/packages/core/pvm-interpreter/program-decoder/mask.test.d.ts

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

package/packages/core/pvm-interpreter/program-decoder/mask.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/mask.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-interpreter/program-decoder/mask.test.js

@@ -0,0 +1,90 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { BitVec } from "#@typeberry/bytes";
+import { Mask } from "./mask.js";
+describe("Mask", () => {
+    describe("isInstruction", () => {
+        it("should return true (single byte)", () => {
+            const input = [0b0000_0001];
+            const index = 0;
+            const expectedResult = true;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 3));
+            const result = mask.isInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return false (single byte)", () => {
+            const input = [0b0000_0001];
+            const index = 1;
+            const expectedResult = false;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 3));
+            const result = mask.isInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return true (2 bytes)", () => {
+            const input = [0x0, 0b0000_0001];
+            const index = 8;
+            const expectedResult = true;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 11));
+            const result = mask.isInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return false (2 bytes)", () => {
+            const input = [0xff, 0b0000_0001];
+            const index = 10;
+            const expectedResult = false;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 11));
+            const result = mask.isInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+    });
+    describe("getNoOfBytesToNextInstruction", () => {
+        it("should return distance to the end of program", () => {
+            const input = [0b0000_0001];
+            const index = 1;
+            const expectedResult = 2;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 3));
+            const result = mask.getNoOfBytesToNextInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return distance to the next instruction in single byte", () => {
+            const input = [0b0000_1001];
+            const index = 1;
+            const expectedResult = 2;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 8));
+            const result = mask.getNoOfBytesToNextInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return 0 if the bit value is 1", () => {
+            const input = [0b0000_0001];
+            const index = 0;
+            const expectedResult = 0;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 3));
+            const result = mask.getNoOfBytesToNextInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return number of 0s between two 1 in 2 bytes", () => {
+            const input = [0b0001_1001, 0b0001_1000];
+            const index = 5;
+            const expectedResult = 6;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 16));
+            const result = mask.getNoOfBytesToNextInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return distance to the end of program", () => {
+            const input = [0b0001_1001];
+            const index = 5;
+            const expectedResult = 3;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), 8));
+            const result = mask.getNoOfBytesToNextInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+        it("should return MAX_INSTRUCTION_DISTANCE = 24 if the real distance is longer", () => {
+            const input = [0b0000_0001, 0b0000_0000, 0b0000_0000, 0b1000_0000];
+            const index = 1;
+            const expectedResult = 25;
+            const mask = new Mask(BitVec.fromBlob(new Uint8Array(input), input.length * 8));
+            const result = mask.getNoOfBytesToNextInstruction(index);
+            assert.strictEqual(result, expectedResult);
+        });
+    });
+});

package/packages/core/pvm-interpreter/program-decoder/program-decoder.d.ts

@@ -0,0 +1,19 @@
+import { Result } from "#@typeberry/utils";
+import { JumpTable } from "./jump-table.js";
+import { Mask } from "./mask.js";
+export declare enum ProgramDecoderError {
+    InvalidProgramError = 0
+}
+export declare class ProgramDecoder {
+    private code;
+    private mask;
+    private jumpTable;
+    constructor(rawProgram: Uint8Array);
+    private decodeProgram;
+    getMask(): Mask;
+    getCode(): Uint8Array<ArrayBufferLike>;
+    getJumpTable(): JumpTable;
+    /** https://graypaper.fluffylabs.dev/#/68eaa1f/23f400234701?v=0.6.4 */
+    static deblob(program: Uint8Array): Result<ProgramDecoder, ProgramDecoderError>;
+}
+//# sourceMappingURL=program-decoder.d.ts.map

package/packages/core/pvm-interpreter/program-decoder/program-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-decoder.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/program-decoder.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,oBAAY,mBAAmB;IAC7B,mBAAmB,IAAI;CACxB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,SAAS,CAAY;gBAEjB,UAAU,EAAE,UAAU;IAQlC,OAAO,CAAC,aAAa;IAwBrB,OAAO;IAIP,OAAO;IAIP,YAAY;IAIZ,sEAAsE;IACtE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC,cAAc,EAAE,mBAAmB,CAAC;CAQhF"}

package/packages/core/pvm-interpreter/program-decoder/program-decoder.js

@@ -0,0 +1,60 @@
+import { Decoder } from "#@typeberry/codec";
+import { Logger } from "#@typeberry/logger";
+import { Result } from "#@typeberry/utils";
+import { JumpTable } from "./jump-table.js";
+import { Mask } from "./mask.js";
+const logger = Logger.new(import.meta.filename, "pvm-interpreter");
+export var ProgramDecoderError;
+(function (ProgramDecoderError) {
+    ProgramDecoderError[ProgramDecoderError["InvalidProgramError"] = 0] = "InvalidProgramError";
+})(ProgramDecoderError || (ProgramDecoderError = {}));
+export class ProgramDecoder {
+    code;
+    mask;
+    jumpTable;
+    constructor(rawProgram) {
+        const { code, mask, jumpTable, jumpTableItemLength } = this.decodeProgram(rawProgram);
+        this.code = new Uint8Array(code);
+        this.mask = new Mask(mask);
+        this.jumpTable = new JumpTable(jumpTableItemLength, jumpTable);
+    }
+    decodeProgram(program) {
+        const decoder = Decoder.fromBlob(program);
+        // number of items in the jump table
+        const jumpTableLength = decoder.varU32();
+        // how many bytes are used to encode a single item of the jump table
+        const jumpTableItemLength = decoder.u8();
+        // the length of the code (in bytes).
+        const codeLength = decoder.varU32();
+        const jumpTableLengthInBytes = jumpTableLength * jumpTableItemLength;
+        const jumpTable = decoder.bytes(jumpTableLengthInBytes).raw;
+        const code = decoder.bytes(codeLength).raw;
+        const mask = decoder.bitVecFixLen(codeLength);
+        decoder.finish();
+        return {
+            mask,
+            code,
+            jumpTableItemLength,
+            jumpTable,
+        };
+    }
+    getMask() {
+        return this.mask;
+    }
+    getCode() {
+        return this.code;
+    }
+    getJumpTable() {
+        return this.jumpTable;
+    }
+    /** https://graypaper.fluffylabs.dev/#/68eaa1f/23f400234701?v=0.6.4 */
+    static deblob(program) {
+        try {
+            return Result.ok(new ProgramDecoder(program));
+        }
+        catch (e) {
+            logger.error `Invalid program: ${e}`;
+            return Result.error(ProgramDecoderError.InvalidProgramError, () => `Program decoder error: ${e}`);
+        }
+    }
+}

package/packages/core/pvm-interpreter/program-decoder/program-decoder.test.d.ts

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

package/packages/core/pvm-interpreter/program-decoder/program-decoder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-decoder.test.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/program-decoder/program-decoder.test.ts"],"names":[],"mappings":""}

package/packages/core/pvm-interpreter/program-decoder/program-decoder.test.js

@@ -0,0 +1,28 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { BitVec } from "#@typeberry/bytes";
+import { JumpTable } from "./jump-table.js";
+import { Mask } from "./mask.js";
+import { ProgramDecoder } from "./program-decoder.js";
+const code = [4, 7, 246, 4, 8, 10, 41, 135, 4, 0, 4, 7, 239, 190, 173, 222];
+const jumpTableItemLength = 1;
+const jumpTable = [5];
+const bitMask = [73, 6];
+const program = new Uint8Array([jumpTable.length, jumpTableItemLength, 16, ...jumpTable, ...code, ...bitMask]);
+describe("ProgramDecoder", () => {
+    it("should corectly decode instructions", () => {
+        const programDecoder = new ProgramDecoder(program);
+        const result = programDecoder.getCode();
+        assert.deepStrictEqual(result, new Uint8Array(code));
+    });
+    it("should corectly decode mask", () => {
+        const programDecoder = new ProgramDecoder(program);
+        const result = programDecoder.getMask();
+        assert.deepStrictEqual(result, new Mask(BitVec.fromBlob(new Uint8Array(bitMask), code.length)));
+    });
+    it("should corectly decode jump table", () => {
+        const programDecoder = new ProgramDecoder(program);
+        const result = programDecoder.getJumpTable();
+        assert.deepStrictEqual(result, new JumpTable(jumpTableItemLength, new Uint8Array(jumpTable)));
+    });
+});