@typeberry/lib 0.5.1-a4d7c93 → 0.5.1-eb84786

package/packages/core/pvm-interpreter/memory/memory-utils.test.d.ts.map

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

package/packages/core/pvm-interpreter/memory/memory-utils.test.js

@@ -0,0 +1,77 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { MAX_MEMORY_INDEX, MEMORY_SIZE } from "#@typeberry/pvm-interface";
+import { PAGE_SIZE } from "./memory-consts.js";
+import { tryAsMemoryIndex, tryAsSbrkIndex } from "./memory-index.js";
+import { alignToPageSize, getPageNumber, getStartPageIndex, getStartPageIndexFromPageNumber } from "./memory-utils.js";
+import { tryAsPageNumber } from "./pages/page-utils.js";
+describe("memory-utils", () => {
+    describe("getPageNumber", () => {
+        it("should return 0 if address is less than page size", () => {
+            const address = tryAsMemoryIndex(5 % PAGE_SIZE);
+            const pageNumber = getPageNumber(address);
+            assert.strictEqual(pageNumber, tryAsPageNumber(0));
+        });
+        it("should return 1 if address is bigger than page size but less than 2x page size", () => {
+            const address = tryAsMemoryIndex(PAGE_SIZE + ((PAGE_SIZE + 5) % PAGE_SIZE));
+            const pageNumber = getPageNumber(address);
+            assert.strictEqual(pageNumber, tryAsPageNumber(1));
+        });
+        it("should return first page for max sbrk index", () => {
+            const address = tryAsSbrkIndex(MEMORY_SIZE);
+            const pageNumber = getPageNumber(address);
+            assert.strictEqual(pageNumber, 0);
+        });
+    });
+    describe("alignToPageSize", () => {
+        it("should return 0 for 0", () => {
+            const length = 0;
+            const lengthAligned = alignToPageSize(length);
+            assert.strictEqual(lengthAligned, 0);
+        });
+        it("should return PAGE_SIZE for 1", () => {
+            const length = 1;
+            const lengthAligned = alignToPageSize(length);
+            assert.strictEqual(lengthAligned, PAGE_SIZE);
+        });
+        it("should return 2xPAGE_SIZE for PAGE_SIZE + 1", () => {
+            const length = PAGE_SIZE + 1;
+            const lengthAligned = alignToPageSize(length);
+            assert.strictEqual(lengthAligned, 2 * PAGE_SIZE);
+        });
+    });
+    describe("getStartPageIndex", () => {
+        it("should return start index of 1st page", () => {
+            const address = tryAsMemoryIndex(1);
+            const expectedAddress = 0;
+            const startPageIndex = getStartPageIndex(address);
+            assert.strictEqual(startPageIndex, expectedAddress);
+        });
+        it("should return start index of 10th page", () => {
+            const address = tryAsMemoryIndex(1 + 10 * PAGE_SIZE);
+            const expectedAddress = 10 * PAGE_SIZE;
+            const startPageIndex = getStartPageIndex(address);
+            assert.strictEqual(startPageIndex, expectedAddress);
+        });
+    });
+    describe("getStartPageIndexFromPageNumber", () => {
+        it("should return a correct start index for page 0", () => {
+            const pageNumber = tryAsPageNumber(0);
+            const expectedMemoryIndex = tryAsMemoryIndex(0);
+            const startIndex = getStartPageIndexFromPageNumber(pageNumber);
+            assert.strictEqual(startIndex, expectedMemoryIndex);
+        });
+        it("should return a correct start index for page 1", () => {
+            const pageNumber = tryAsPageNumber(1);
+            const expectedMemoryIndex = tryAsMemoryIndex(PAGE_SIZE);
+            const startIndex = getStartPageIndexFromPageNumber(pageNumber);
+            assert.strictEqual(startIndex, expectedMemoryIndex);
+        });
+        it("should return a correct start index for the last page", () => {
+            const lastMemoryIndex = tryAsMemoryIndex(MAX_MEMORY_INDEX);
+            const pageNumber = getPageNumber(lastMemoryIndex);
+            const startIndex = getStartPageIndexFromPageNumber(pageNumber);
+            assert.strictEqual(startIndex, pageNumber * PAGE_SIZE);
+        });
+    });
+});

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

@@ -0,0 +1,38 @@
+import type { U32 } from "#@typeberry/numbers";
+import { type IMemory, type PageFault as InretpreterPageFault } from "#@typeberry/pvm-interface";
+import { OK, Result } from "#@typeberry/utils";
+import { PageFault } from "./errors.js";
+import { type MemoryIndex, type SbrkIndex } from "./memory-index.js";
+import type { MemoryPage } from "./pages/memory-page.js";
+import { type PageNumber } from "./pages/page-utils.js";
+type InitialMemoryState = {
+    memory: Map<PageNumber, MemoryPage>;
+    sbrkIndex: SbrkIndex;
+    endHeapIndex: SbrkIndex;
+};
+export declare class Memory implements IMemory {
+    private sbrkIndex;
+    private virtualSbrkIndex;
+    private endHeapIndex;
+    private memory;
+    static fromInitialMemory(initialMemoryState: InitialMemoryState): Memory;
+    constructor(sbrkIndex?: number & import("@typeberry/utils").WithOpaque<"sbrk index">, virtualSbrkIndex?: number & import("@typeberry/utils").WithOpaque<"sbrk index">, endHeapIndex?: number & import("@typeberry/utils").WithOpaque<"sbrk index">, memory?: Map<number & import("@typeberry/utils").WithOpaque<"memory page number">, MemoryPage>);
+    store(address: U32, bytes: Uint8Array): Result<OK, InretpreterPageFault>;
+    read(address: U32, output: Uint8Array): Result<OK, InretpreterPageFault>;
+    reset(): void;
+    copyFrom(memory: Memory): void;
+    storeFrom(address: MemoryIndex, bytes: Uint8Array): Result<OK, PageFault>;
+    private getPages;
+    /**
+     * Read content of the memory at `[address, address + result.length)` and
+     * write the result into the `result` buffer.
+     *
+     * Returns `null` if the data was read successfully or `PageFault` otherwise.
+     */
+    loadInto(result: Uint8Array, startAddress: MemoryIndex): Result<OK, PageFault>;
+    sbrk(length: number): SbrkIndex;
+    getPageDump(pageNumber: PageNumber): Uint8Array<ArrayBufferLike> | null;
+    getDirtyPages(): MapIterator<number & import("@typeberry/utils").WithOpaque<"memory page number">>;
+}
+export {};
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/memory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,IAAI,oBAAoB,EAAoB,MAAM,0BAA0B,CAAC;AAClH,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAe,SAAS,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAoC,MAAM,mBAAmB,CAAC;AAKvG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,UAAU,EAAkB,MAAM,uBAAuB,CAAC;AAExE,KAAK,kBAAkB,GAAG;IACxB,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACpC,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,SAAS,CAAC;CACzB,CAAC;AASF,qBAAa,MAAO,YAAW,OAAO;IAWlC,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,MAAM;IAbhB,MAAM,CAAC,iBAAiB,CAAC,kBAAkB,EAAE,kBAAkB;gBAUrD,SAAS,+DAA4C,EACrD,gBAAgB,+DAA4C,EAC5D,YAAY,+DAAmC,EAC/C,MAAM,wFAAoC;IAGpD,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAIxE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAIxE,KAAK;IAOL,QAAQ,CAAC,MAAM,EAAE,MAAM;IAOvB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IA8BzE,OAAO,CAAC,QAAQ;IAoChB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAgC9E,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAkC/B,WAAW,CAAC,UAAU,EAAE,UAAU;IAKlC,aAAa;CAGd"}

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

@@ -0,0 +1,159 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { Logger } from "#@typeberry/logger";
+import { MAX_MEMORY_INDEX } from "#@typeberry/pvm-interface";
+import { OK, Result } from "#@typeberry/utils";
+import { OutOfMemory, PageFault } from "./errors.js";
+import { PAGE_SIZE, RESERVED_NUMBER_OF_PAGES } from "./memory-consts.js";
+import { tryAsMemoryIndex, tryAsSbrkIndex } from "./memory-index.js";
+import { MemoryRange, RESERVED_MEMORY_RANGE } from "./memory-range.js";
+import { alignToPageSize, getPageNumber } from "./memory-utils.js";
+import { PageRange } from "./page-range.js";
+import { WriteablePage } from "./pages/index.js";
+import { tryAsPageIndex } from "./pages/page-utils.js";
+var AccessType;
+(function (AccessType) {
+    AccessType[AccessType["READ"] = 0] = "READ";
+    AccessType[AccessType["WRITE"] = 1] = "WRITE";
+})(AccessType || (AccessType = {}));
+const logger = Logger.new(import.meta.filename, "pvm:mem");
+export class Memory {
+    sbrkIndex;
+    virtualSbrkIndex;
+    endHeapIndex;
+    memory;
+    static fromInitialMemory(initialMemoryState) {
+        return new Memory(initialMemoryState?.sbrkIndex, initialMemoryState?.sbrkIndex, initialMemoryState?.endHeapIndex, initialMemoryState?.memory);
+    }
+    constructor(sbrkIndex = tryAsSbrkIndex(RESERVED_MEMORY_RANGE.end), virtualSbrkIndex = tryAsSbrkIndex(RESERVED_MEMORY_RANGE.end), endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX), memory = new Map()) {
+        this.sbrkIndex = sbrkIndex;
+        this.virtualSbrkIndex = virtualSbrkIndex;
+        this.endHeapIndex = endHeapIndex;
+        this.memory = memory;
+    }
+    store(address, bytes) {
+        return this.storeFrom(tryAsMemoryIndex(address), bytes);
+    }
+    read(address, output) {
+        return this.loadInto(output, tryAsMemoryIndex(address));
+    }
+    reset() {
+        this.sbrkIndex = tryAsSbrkIndex(RESERVED_MEMORY_RANGE.end);
+        this.virtualSbrkIndex = tryAsSbrkIndex(RESERVED_MEMORY_RANGE.end);
+        this.endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+        this.memory = new Map(); // TODO [MaSi]: We should keep allocated pages somewhere and reuse it when it is possible
+    }
+    copyFrom(memory) {
+        this.sbrkIndex = memory.sbrkIndex;
+        this.virtualSbrkIndex = memory.virtualSbrkIndex;
+        this.endHeapIndex = memory.endHeapIndex;
+        this.memory = memory.memory;
+    }
+    storeFrom(address, bytes) {
+        if (bytes.length === 0) {
+            return Result.ok(OK);
+        }
+        logger.insane `MEM[${address}] <- ${BytesBlob.blobFrom(bytes)}`;
+        const pagesResult = this.getPages(address, bytes.length, AccessType.WRITE);
+        if (pagesResult.isError) {
+            return Result.error(pagesResult.error, pagesResult.details);
+        }
+        const pages = pagesResult.ok;
+        let currentPosition = address;
+        let bytesLeft = bytes.length;
+        for (const page of pages) {
+            const pageStartIndex = tryAsPageIndex(currentPosition % PAGE_SIZE);
+            const bytesToWrite = Math.min(PAGE_SIZE - pageStartIndex, bytesLeft);
+            const sourceStartIndex = currentPosition - address;
+            const source = bytes.subarray(sourceStartIndex, sourceStartIndex + bytesToWrite);
+            page.storeFrom(pageStartIndex, source);
+            currentPosition += bytesToWrite;
+            bytesLeft -= bytesToWrite;
+        }
+        return Result.ok(OK);
+    }
+    getPages(startAddress, length, accessType) {
+        if (length === 0) {
+            return Result.ok([]);
+        }
+        const memoryRange = MemoryRange.fromStartAndLength(startAddress, length);
+        const pageRange = PageRange.fromMemoryRange(memoryRange);
+        const pages = [];
+        for (const pageNumber of pageRange) {
+            if (pageNumber < RESERVED_NUMBER_OF_PAGES) {
+                return Result.error(PageFault.fromPageNumber(pageNumber, true), () => `Page fault: attempted to access reserved page ${pageNumber}`);
+            }
+            const page = this.memory.get(pageNumber);
+            if (page === undefined) {
+                return Result.error(PageFault.fromPageNumber(pageNumber), () => `Page fault: page ${pageNumber} not allocated`);
+            }
+            if (accessType === AccessType.WRITE && !page.isWriteable()) {
+                return Result.error(PageFault.fromPageNumber(pageNumber, true), () => `Page fault: attempted to write to read-only page ${pageNumber}`);
+            }
+            pages.push(page);
+        }
+        return Result.ok(pages);
+    }
+    /**
+     * Read content of the memory at `[address, address + result.length)` and
+     * write the result into the `result` buffer.
+     *
+     * Returns `null` if the data was read successfully or `PageFault` otherwise.
+     */
+    loadInto(result, startAddress) {
+        if (result.length === 0) {
+            return Result.ok(OK);
+        }
+        const pagesResult = this.getPages(startAddress, result.length, AccessType.READ);
+        if (pagesResult.isError) {
+            return Result.error(pagesResult.error, pagesResult.details);
+        }
+        const pages = pagesResult.ok;
+        let currentPosition = startAddress;
+        let bytesLeft = result.length;
+        for (const page of pages) {
+            const pageStartIndex = tryAsPageIndex(currentPosition % PAGE_SIZE);
+            const bytesToRead = Math.min(PAGE_SIZE - pageStartIndex, bytesLeft);
+            const destinationStartIndex = currentPosition - startAddress;
+            const destination = result.subarray(destinationStartIndex);
+            page.loadInto(destination, pageStartIndex, bytesToRead);
+            currentPosition += bytesToRead;
+            bytesLeft -= bytesToRead;
+        }
+        logger.insane `MEM[${startAddress}] => ${BytesBlob.blobFrom(result)}`;
+        return Result.ok(OK);
+    }
+    sbrk(length) {
+        const currentSbrkIndex = this.sbrkIndex;
+        const currentVirtualSbrkIndex = this.virtualSbrkIndex;
+        // new sbrk index is bigger than 2 ** 32 or endHeapIndex
+        if (MAX_MEMORY_INDEX < currentVirtualSbrkIndex + length || currentVirtualSbrkIndex + length > this.endHeapIndex) {
+            throw new OutOfMemory();
+        }
+        const newVirtualSbrkIndex = tryAsSbrkIndex(this.virtualSbrkIndex + length);
+        // no alllocation needed
+        if (newVirtualSbrkIndex <= currentSbrkIndex) {
+            this.virtualSbrkIndex = newVirtualSbrkIndex;
+            return currentVirtualSbrkIndex;
+        }
+        // standard allocation using "Writeable" pages
+        const newSbrkIndex = tryAsSbrkIndex(alignToPageSize(newVirtualSbrkIndex));
+        // TODO [MaSi]: `getPageNumber` works incorrectly for SbrkIndex. Sbrk index should be changed to MemoryIndex
+        const firstPageNumber = getPageNumber(currentSbrkIndex);
+        const pagesToAllocate = (newSbrkIndex - currentSbrkIndex) / PAGE_SIZE;
+        const rangeToAllocate = PageRange.fromStartAndLength(firstPageNumber, pagesToAllocate);
+        for (const pageNumber of rangeToAllocate) {
+            const page = new WriteablePage(pageNumber);
+            this.memory.set(pageNumber, page);
+        }
+        this.virtualSbrkIndex = newVirtualSbrkIndex;
+        this.sbrkIndex = newSbrkIndex;
+        return currentVirtualSbrkIndex;
+    }
+    getPageDump(pageNumber) {
+        const page = this.memory.get(pageNumber);
+        return page?.getPageDump() ?? null;
+    }
+    getDirtyPages() {
+        return this.memory.keys();
+    }
+}

package/packages/core/pvm-interpreter/memory/memory.test.d.ts

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

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

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

package/packages/core/pvm-interpreter/memory/memory.test.js

@@ -0,0 +1,277 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { MAX_MEMORY_INDEX } from "#@typeberry/pvm-interface";
+import { deepEqual, OK, Result } from "#@typeberry/utils";
+import { PageFault } from "./errors.js";
+import { Memory } from "./memory.js";
+import { MIN_ALLOCATION_LENGTH, PAGE_SIZE, RESERVED_NUMBER_OF_PAGES } from "./memory-consts.js";
+import { tryAsMemoryIndex, tryAsSbrkIndex } from "./memory-index.js";
+import { ReadablePage, WriteablePage } from "./pages/index.js";
+import { tryAsPageNumber } from "./pages/page-utils.js";
+describe("Memory", () => {
+    describe("loadInto", () => {
+        it("should return PageFault if the page does not exist", () => {
+            const memory = new Memory();
+            const lengthToLoad = 4;
+            const result = new Uint8Array(lengthToLoad);
+            const addressToLoad = tryAsMemoryIndex(1 + RESERVED_NUMBER_OF_PAGES * PAGE_SIZE);
+            const loadResult = memory.loadInto(result, addressToLoad);
+            deepEqual(loadResult, Result.error(PageFault.fromMemoryIndex(addressToLoad), () => "Page fault: page 16 not allocated"));
+        });
+        it("should correctly load data from one page", () => {
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+            const page = new ReadablePage(pageNumber, bytes);
+            const memoryMap = new Map();
+            memoryMap.set(pageNumber, page);
+            const sbrkIndex = tryAsSbrkIndex(20 * PAGE_SIZE);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const lengthToLoad = 4;
+            const result = new Uint8Array(lengthToLoad);
+            const addressToLoad = tryAsMemoryIndex(1 + RESERVED_NUMBER_OF_PAGES * PAGE_SIZE);
+            const expectedResult = bytes.subarray(addressToLoad % PAGE_SIZE, (addressToLoad % PAGE_SIZE) + lengthToLoad);
+            const loadResult = memory.loadInto(result, addressToLoad);
+            assert.deepStrictEqual(loadResult, Result.ok(OK));
+            assert.deepStrictEqual(result, expectedResult);
+        });
+        it("should correctly load data from two pages", () => {
+            const firstPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const secondPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 1);
+            const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+            const firstPage = new ReadablePage(firstPageNumber, new Uint8Array([...new Uint8Array(PAGE_SIZE - bytes.length), ...bytes]));
+            const secondPage = new ReadablePage(secondPageNumber, bytes);
+            const memoryMap = new Map();
+            memoryMap.set(firstPageNumber, firstPage);
+            memoryMap.set(secondPageNumber, secondPage);
+            const sbrkIndex = tryAsSbrkIndex(20 * PAGE_SIZE);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const lengthToLoad = 4;
+            const result = new Uint8Array(lengthToLoad);
+            const addressToLoad = tryAsMemoryIndex(secondPageNumber * PAGE_SIZE - 2);
+            const expectedResult = new Uint8Array([4, 5, 1, 2]);
+            const loadResult = memory.loadInto(result, addressToLoad);
+            assert.deepStrictEqual(loadResult, Result.ok(OK));
+            assert.deepStrictEqual(result, expectedResult);
+        });
+        it("should return PageFault if case of loading data from 2 pages but one of them does not exist", () => {
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const bytes = new Uint8Array();
+            const page = new ReadablePage(pageNumber, bytes);
+            const memoryMap = new Map();
+            memoryMap.set(pageNumber, page);
+            const sbrkIndex = tryAsSbrkIndex(0);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const lengthToLoad = 4;
+            const result = new Uint8Array(lengthToLoad);
+            const addressToLoad = tryAsMemoryIndex(17 * PAGE_SIZE - 2);
+            const loadResult = memory.loadInto(result, addressToLoad);
+            deepEqual(loadResult, Result.error(PageFault.fromPageNumber(17), () => "Page fault: page 17 not allocated"));
+        });
+        it("should return fault when load data from the last page and the first page", () => {
+            const firstPageNumber = tryAsPageNumber((MAX_MEMORY_INDEX - PAGE_SIZE + 1) / PAGE_SIZE);
+            const secondPageNumber = tryAsPageNumber(0);
+            const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+            const firstPage = new ReadablePage(firstPageNumber, new Uint8Array([...new Uint8Array(PAGE_SIZE - bytes.length), ...bytes]));
+            const secondPage = new ReadablePage(secondPageNumber, new Uint8Array([...bytes, ...new Uint8Array(PAGE_SIZE - bytes.length)]));
+            const memoryMap = new Map();
+            memoryMap.set(firstPageNumber, firstPage);
+            memoryMap.set(secondPageNumber, secondPage);
+            const sbrkIndex = tryAsSbrkIndex(20 * PAGE_SIZE);
+            const endHeapIndex = tryAsSbrkIndex(30 * PAGE_SIZE);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const lengthToLoad = 4;
+            const result = new Uint8Array(lengthToLoad);
+            const addressToLoad = tryAsMemoryIndex(MAX_MEMORY_INDEX - 1);
+            const expectedResult = new Uint8Array(lengthToLoad);
+            const loadResult = memory.loadInto(result, addressToLoad);
+            deepEqual(loadResult, Result.error(PageFault.fromPageNumber(0, true), () => "Page fault: attempted to access reserved page 0"));
+            assert.deepStrictEqual(result, expectedResult);
+        });
+    });
+    describe("storeFrom", () => {
+        it("should return PageFault if the page does not exist", () => {
+            const memory = new Memory();
+            const addressToStore = tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 1);
+            const dataToStore = new Uint8Array([1, 2, 3, 4]);
+            const storeResult = memory.storeFrom(addressToStore, dataToStore);
+            deepEqual(storeResult, Result.error(PageFault.fromMemoryIndex(addressToStore), () => "Page fault: page 16 not allocated"));
+        });
+        it("should not return PageFault if the page does not exist and stored array length is 0 (standard page)", () => {
+            const memory = new Memory();
+            const addressToStore = tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 1);
+            const storeResult = memory.storeFrom(addressToStore, new Uint8Array());
+            assert.deepStrictEqual(storeResult, Result.ok(OK));
+        });
+        it("should not return PageFault if the page does not exist and stored array length is 0 - even it is a reserved page", () => {
+            const memory = new Memory();
+            const addressToStore = tryAsMemoryIndex(1);
+            const storeResult = memory.storeFrom(addressToStore, new Uint8Array());
+            assert.deepStrictEqual(storeResult, Result.ok(OK));
+        });
+        it("should correctly store data on one page", () => {
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const page = new WriteablePage(pageNumber, new Uint8Array());
+            const memoryMap = new Map();
+            const sbrkIndex = tryAsSbrkIndex((RESERVED_NUMBER_OF_PAGES + 4) * PAGE_SIZE);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            memoryMap.set(pageNumber, page);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const dataToStore = new Uint8Array([1, 2, 3, 4]);
+            const addressToStore = tryAsMemoryIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 1);
+            const expectedMemoryMap = new Map();
+            expectedMemoryMap.set(pageNumber, new WriteablePage(pageNumber, new Uint8Array([0, ...dataToStore, ...new Uint8Array(MIN_ALLOCATION_LENGTH - dataToStore.length - 1)])));
+            const expectedMemory = {
+                sbrkIndex,
+                virtualSbrkIndex: sbrkIndex,
+                endHeapIndex,
+                memory: expectedMemoryMap,
+            };
+            const storeResult = memory.storeFrom(addressToStore, dataToStore);
+            assert.deepStrictEqual(storeResult, Result.ok(OK));
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should correctly store data on two pages", () => {
+            const firstPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const secondPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 1);
+            const firstPage = new WriteablePage(firstPageNumber, new Uint8Array(PAGE_SIZE));
+            const secondPage = new WriteablePage(secondPageNumber, new Uint8Array());
+            const memoryMap = new Map();
+            const sbrkIndex = tryAsSbrkIndex(20 * PAGE_SIZE);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            memoryMap.set(firstPageNumber, firstPage);
+            memoryMap.set(secondPageNumber, secondPage);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const dataToStore = new Uint8Array([1, 2, 3, 4]);
+            const addressToStore = tryAsMemoryIndex(17 * PAGE_SIZE - 2);
+            const expectedMemoryMap = new Map();
+            expectedMemoryMap.set(firstPageNumber, new WriteablePage(firstPageNumber, new Uint8Array([...new Uint8Array(PAGE_SIZE - 2), 1, 2])));
+            expectedMemoryMap.set(secondPageNumber, new WriteablePage(secondPageNumber, new Uint8Array([3, 4, ...new Uint8Array(MIN_ALLOCATION_LENGTH - 2)])));
+            const expectedMemory = {
+                sbrkIndex,
+                virtualSbrkIndex: sbrkIndex,
+                endHeapIndex,
+                memory: expectedMemoryMap,
+            };
+            const storeResult = memory.storeFrom(addressToStore, dataToStore);
+            assert.deepStrictEqual(storeResult, Result.ok(OK));
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should return PageFault if case of storing data on 2 pages but one of them does not exist", () => {
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const bytes = new Uint8Array();
+            const page = new WriteablePage(pageNumber, bytes);
+            const memoryMap = new Map();
+            memoryMap.set(pageNumber, page);
+            const sbrkIndex = tryAsSbrkIndex(RESERVED_NUMBER_OF_PAGES * PAGE_SIZE);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const addressToStore = tryAsMemoryIndex(17 * PAGE_SIZE - 2);
+            const storeResult = memory.storeFrom(addressToStore, new Uint8Array(4));
+            deepEqual(storeResult, Result.error(PageFault.fromPageNumber(17), () => "Page fault: page 17 not allocated"));
+        });
+        it("should return fault when store data on two pages - the last page and the first page", () => {
+            const firstPageNumber = tryAsPageNumber((MAX_MEMORY_INDEX - PAGE_SIZE + 1) / PAGE_SIZE);
+            const secondPageNumber = tryAsPageNumber(0);
+            const firstPage = new WriteablePage(firstPageNumber, new Uint8Array(PAGE_SIZE));
+            const secondPage = new WriteablePage(secondPageNumber, new Uint8Array(PAGE_SIZE));
+            const memoryMap = new Map();
+            const sbrkIndex = tryAsSbrkIndex(0);
+            const endHeapIndex = tryAsSbrkIndex(MAX_MEMORY_INDEX);
+            memoryMap.set(firstPageNumber, firstPage);
+            memoryMap.set(secondPageNumber, secondPage);
+            const memory = Memory.fromInitialMemory({ memory: memoryMap, sbrkIndex, endHeapIndex });
+            const dataToStore = new Uint8Array([1, 2, 3, 4]);
+            const addressToStore = tryAsMemoryIndex(MAX_MEMORY_INDEX - 2);
+            const expectedMemoryMap = new Map();
+            expectedMemoryMap.set(firstPageNumber, new WriteablePage(firstPageNumber, new Uint8Array(PAGE_SIZE)));
+            expectedMemoryMap.set(secondPageNumber, new WriteablePage(secondPageNumber, new Uint8Array(PAGE_SIZE)));
+            const expectedMemory = {
+                sbrkIndex,
+                virtualSbrkIndex: sbrkIndex,
+                endHeapIndex,
+                memory: expectedMemoryMap,
+            };
+            const storeResult = memory.storeFrom(addressToStore, dataToStore);
+            deepEqual(storeResult, Result.error(PageFault.fromPageNumber(0, true), () => "Page fault: attempted to access reserved page 0"));
+            assert.deepEqual(memory, expectedMemory);
+        });
+    });
+    describe("sbrk", () => {
+        it("should allocate one page", () => {
+            const memory = new Memory();
+            const lengthToAllocate = 5;
+            const expectedMemoryMap = new Map();
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            expectedMemoryMap.set(pageNumber, new WriteablePage(pageNumber, new Uint8Array(MIN_ALLOCATION_LENGTH)));
+            const expectedMemory = {
+                sbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + PAGE_SIZE,
+                virtualSbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + lengthToAllocate,
+                endHeapIndex: MAX_MEMORY_INDEX,
+                memory: expectedMemoryMap,
+            };
+            memory.sbrk(lengthToAllocate);
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should allocate two pages", () => {
+            const memory = new Memory();
+            const lengthToAllocate = PAGE_SIZE + 5;
+            const expectedMemoryMap = new Map();
+            const firstPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const secondPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 1);
+            expectedMemoryMap.set(firstPageNumber, new WriteablePage(firstPageNumber, new Uint8Array(MIN_ALLOCATION_LENGTH)));
+            expectedMemoryMap.set(secondPageNumber, new WriteablePage(secondPageNumber, new Uint8Array(MIN_ALLOCATION_LENGTH)));
+            const expectedMemory = {
+                sbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 2 * PAGE_SIZE,
+                virtualSbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + lengthToAllocate,
+                endHeapIndex: MAX_MEMORY_INDEX,
+                memory: expectedMemoryMap,
+            };
+            memory.sbrk(lengthToAllocate);
+            assert.deepEqual(memory, expectedMemory);
+        });
+        it("should not allocate if virtualSbrkIndex + length < sbrkIndex", () => {
+            const memory = new Memory();
+            const lengthToAllocate = 5;
+            const expectedMemoryMap = new Map();
+            const pageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            expectedMemoryMap.set(pageNumber, new WriteablePage(pageNumber, new Uint8Array(MIN_ALLOCATION_LENGTH)));
+            const expectedMemoryAfterFirstAllocation = {
+                sbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + PAGE_SIZE,
+                virtualSbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + lengthToAllocate,
+                endHeapIndex: MAX_MEMORY_INDEX,
+                memory: expectedMemoryMap,
+            };
+            memory.sbrk(lengthToAllocate);
+            assert.deepEqual(memory, expectedMemoryAfterFirstAllocation);
+            const expectedMemoryAfterSecondAllocation = {
+                sbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + PAGE_SIZE,
+                virtualSbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 2 * lengthToAllocate,
+                endHeapIndex: MAX_MEMORY_INDEX,
+                memory: expectedMemoryMap,
+            };
+            memory.sbrk(lengthToAllocate);
+            assert.deepEqual(memory, expectedMemoryAfterSecondAllocation);
+        });
+        it("should allocate two pages one by one", () => {
+            const memory = new Memory();
+            const lengthToAllocate = PAGE_SIZE;
+            const expectedMemoryMap = new Map();
+            const firstPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES);
+            const secondPageNumber = tryAsPageNumber(RESERVED_NUMBER_OF_PAGES + 1);
+            expectedMemoryMap.set(firstPageNumber, new WriteablePage(firstPageNumber, new Uint8Array(MIN_ALLOCATION_LENGTH)));
+            expectedMemoryMap.set(secondPageNumber, new WriteablePage(secondPageNumber, new Uint8Array(MIN_ALLOCATION_LENGTH)));
+            const expectedMemory = {
+                sbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 2 * PAGE_SIZE,
+                virtualSbrkIndex: RESERVED_NUMBER_OF_PAGES * PAGE_SIZE + 2 * PAGE_SIZE,
+                endHeapIndex: MAX_MEMORY_INDEX,
+                memory: expectedMemoryMap,
+            };
+            memory.sbrk(lengthToAllocate);
+            memory.sbrk(lengthToAllocate);
+            assert.deepEqual(memory, expectedMemory);
+        });
+    });
+});

package/packages/core/pvm-interpreter/memory/page-range.d.ts

@@ -0,0 +1,34 @@
+import type { MemoryRange } from "./memory-range.js";
+import { type PageNumber } from "./pages/page-utils.js";
+/**
+ * A half-open range of memory pages. Similarly to [`MemoryRange`], can be empty
+ * or wrapped around the memory.
+ */
+export declare class PageRange {
+    readonly start: PageNumber;
+    readonly length: number;
+    /**
+     * Exclusive end of the page range.
+     *
+     * NOTE: it may be smaller than `start` in case the range is wrapped.
+     */
+    readonly end: PageNumber;
+    private constructor();
+    /**
+     * Creates range of pages that includes all indices in a given memory range.
+     *
+     * Example: For memory range `[PAGE_SIZE, MEMORY_SIZE - PAGE_SIZE)`
+     *                  we will get `[1, MAX_NUMBER_OF_PAGES - 1)` page range.
+     */
+    static fromMemoryRange(range: MemoryRange): PageRange;
+    /** Creates a page range from given starting point and length */
+    static fromStartAndLength(start: PageNumber, length: number): PageRange;
+    /** Returns true if the page range is wrapped (`start` >= `end`) and is not empty */
+    isWrapped(): boolean;
+    /** Checks if given page number is within the range */
+    isInRange(page: PageNumber): boolean;
+    /** Checks if a range is empty (`length === 0`) */
+    isEmpty(): boolean;
+    [Symbol.iterator](): Generator<number & import("@typeberry/utils").WithOpaque<"memory page number">, void, unknown>;
+}
+//# sourceMappingURL=page-range.d.ts.map

package/packages/core/pvm-interpreter/memory/page-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-range.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/pvm-interpreter/memory/page-range.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAqB,KAAK,UAAU,EAAmB,MAAM,uBAAuB,CAAC;AAE5F;;;GAGG;AACH,qBAAa,SAAS;aASF,KAAK,EAAE,UAAU;aACjB,MAAM,EAAE,MAAM;IAThC;;;;OAIG;IACH,SAAgB,GAAG,EAAE,UAAU,CAAC;IAEhC,OAAO;IAOP;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,WAAW;IAoBzC,gEAAgE;IAChE,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM;IAO3D,oFAAoF;IACpF,SAAS;IAIT,sDAAsD;IACtD,SAAS,CAAC,IAAI,EAAE,UAAU;IAQ1B,kDAAkD;IAClD,OAAO;IAIN,CAAC,MAAM,CAAC,QAAQ,CAAC;CAanB"}