@typeberry/lib 0.5.1 → 0.5.2-03e1aed

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

@@ -0,0 +1,76 @@
+import { MAX_NUMBER_OF_PAGES, PAGE_SIZE } from "./memory-consts.js";
+import { getPageNumber } from "./memory-utils.js";
+import { getNextPageNumber, tryAsPageNumber } from "./pages/page-utils.js";
+/**
+ * A half-open range of memory pages. Similarly to [`MemoryRange`], can be empty
+ * or wrapped around the memory.
+ */
+export class PageRange {
+    start;
+    length;
+    /**
+     * Exclusive end of the page range.
+     *
+     * NOTE: it may be smaller than `start` in case the range is wrapped.
+     */
+    end;
+    constructor(start, length) {
+        this.start = start;
+        this.length = length;
+        this.end = tryAsPageNumber((this.start + this.length) % MAX_NUMBER_OF_PAGES);
+    }
+    /**
+     * 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) {
+        const startPage = getPageNumber(range.start);
+        if (range.isEmpty()) {
+            return new PageRange(startPage, 0);
+        }
+        // lastIndex is not null because we just ensured that the range is not empty
+        const pageWithLastIndex = getPageNumber(range.lastIndex ?? range.end);
+        const endPage = getNextPageNumber(pageWithLastIndex);
+        if ((startPage === endPage || startPage === pageWithLastIndex) && range.length > PAGE_SIZE) {
+            // full range
+            return new PageRange(startPage, MAX_NUMBER_OF_PAGES);
+        }
+        const length = startPage < endPage ? endPage - startPage : MAX_NUMBER_OF_PAGES - startPage + endPage;
+        return PageRange.fromStartAndLength(startPage, length);
+    }
+    /** Creates a page range from given starting point and length */
+    static fromStartAndLength(start, length) {
+        if (!Number.isInteger(length) || length < 0 || length > MAX_NUMBER_OF_PAGES) {
+            throw new TypeError(`length must be a non-negative integer and less than ${MAX_NUMBER_OF_PAGES}, got ${length}`);
+        }
+        return new PageRange(start, length);
+    }
+    /** Returns true if the page range is wrapped (`start` >= `end`) and is not empty */
+    isWrapped() {
+        return this.start >= this.end && !this.isEmpty();
+    }
+    /** Checks if given page number is within the range */
+    isInRange(page) {
+        if (this.isWrapped()) {
+            return page >= this.start || page < this.end;
+        }
+        return page >= this.start && page < this.end;
+    }
+    /** Checks if a range is empty (`length === 0`) */
+    isEmpty() {
+        return this.length === 0;
+    }
+    *[Symbol.iterator]() {
+        if (this.isEmpty()) {
+            return;
+        }
+        const end = this.end;
+        let i = this.start;
+        do {
+            yield i;
+            i = getNextPageNumber(i);
+        } while (i !== end);
+    }
+}

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

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

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

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

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

@@ -0,0 +1,163 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { MAX_MEMORY_INDEX, MEMORY_SIZE } from "#@typeberry/pvm-interface";
+import { MAX_NUMBER_OF_PAGES, PAGE_SIZE } from "./memory-consts.js";
+import { tryAsMemoryIndex } from "./memory-index.js";
+import { MemoryRange } from "./memory-range.js";
+import { PageRange } from "./page-range.js";
+import { tryAsPageNumber } from "./pages/page-utils.js";
+describe("PageRange", () => {
+    describe("create from memory range", () => {
+        const createMemoryRange = (start, length) => MemoryRange.fromStartAndLength(tryAsMemoryIndex(start), length);
+        it("should create a PageRange from an empty MemoryRange", () => {
+            const range = createMemoryRange(5, 0);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.strictEqual(pageRange.start, 0);
+            assert.strictEqual(pageRange.end, 0);
+            assert.deepStrictEqual(pageNumbers, []);
+        });
+        it("should create a PageRange from a MemoryRange on one page", () => {
+            const range = createMemoryRange(1, 4);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.strictEqual(pageRange.start, 0);
+            assert.strictEqual(pageRange.end, 1);
+            assert.deepStrictEqual(pageNumbers, [0]);
+        });
+        it("should create a PageRange from a MemoryRange that spans a few pages", () => {
+            const range = createMemoryRange(5000, PAGE_SIZE * 3);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.strictEqual(pageRange.start, 1);
+            assert.strictEqual(pageRange.end, 5);
+            assert.deepStrictEqual(pageNumbers, [1, 2, 3, 4]);
+        });
+        it("should create a PageRange from full MemoryRange", () => {
+            const range = createMemoryRange(0, MEMORY_SIZE);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.strictEqual(pageRange.start, 0);
+            assert.strictEqual(pageRange.end, 0);
+            assert.strictEqual(pageNumbers.length, MAX_NUMBER_OF_PAGES);
+        });
+        it("should create a PageRange from full MemoryRange but different than [0; 2**32)", () => {
+            const range = createMemoryRange(5 * PAGE_SIZE + 5, MEMORY_SIZE);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.strictEqual(pageRange.start, 5);
+            assert.strictEqual(pageRange.end, 5);
+            assert.strictEqual(pageNumbers.length, MAX_NUMBER_OF_PAGES);
+        });
+        it("should create a PageRange from a wrapped range", () => {
+            const range = createMemoryRange(MEMORY_SIZE - 3 * PAGE_SIZE + 5, PAGE_SIZE * 4);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.strictEqual(pageRange.start, MAX_NUMBER_OF_PAGES - 3);
+            assert.strictEqual(pageRange.end, 2);
+            assert.deepStrictEqual(pageNumbers, [
+                MAX_NUMBER_OF_PAGES - 3,
+                MAX_NUMBER_OF_PAGES - 2,
+                MAX_NUMBER_OF_PAGES - 1,
+                0,
+                1,
+            ]);
+        });
+    });
+    describe("iterator", () => {
+        it("should return page numbers for an empty range", () => {
+            const start = tryAsPageNumber(1);
+            const length = 0;
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            const pageNumbers = Array.from(pageRange);
+            assert.deepStrictEqual(pageNumbers, []);
+        });
+        it("should return page numbers for a non-empty range", () => {
+            const start = tryAsPageNumber(1);
+            const length = tryAsPageNumber(2);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            const pageNumbers = Array.from(pageRange);
+            assert.deepStrictEqual(pageNumbers, [1, 2]);
+        });
+        it("should return page numbers for a non-empty wrapped range", () => {
+            const start = tryAsPageNumber(MAX_NUMBER_OF_PAGES - 2);
+            const length = 4;
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            const pageNumbers = Array.from(pageRange);
+            assert.deepStrictEqual(pageNumbers, [MAX_NUMBER_OF_PAGES - 2, MAX_NUMBER_OF_PAGES - 1, 0, 1]);
+        });
+        it("should return page numbers for a short memory range that spans last and first pages ", () => {
+            const start = tryAsMemoryIndex(MAX_MEMORY_INDEX - 2);
+            const length = 4;
+            const range = MemoryRange.fromStartAndLength(start, length);
+            const pageRange = PageRange.fromMemoryRange(range);
+            const pageNumbers = Array.from(pageRange);
+            assert.deepStrictEqual(pageNumbers, [MAX_NUMBER_OF_PAGES - 1, 0]);
+        });
+    });
+    describe("isWrapped", () => {
+        it("should return true for a wrapped range", () => {
+            const start = tryAsPageNumber(3);
+            const length = MAX_NUMBER_OF_PAGES - 1;
+            const memoryRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isWrapped(), true);
+        });
+        it("should return false for a non-wrapped range", () => {
+            const start = tryAsPageNumber(1);
+            const length = 5;
+            const memoryRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(memoryRange.isWrapped(), false);
+        });
+    });
+    describe("isInRange", () => {
+        it("should return true for a page number that is in range (non-wrapped)", () => {
+            const start = tryAsPageNumber(1);
+            const length = 3;
+            const page = tryAsPageNumber(2);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), true);
+        });
+        it("should return true for a page number that is in range (wrapped)", () => {
+            const start = tryAsPageNumber(MAX_NUMBER_OF_PAGES - 2);
+            const length = 5;
+            const page = tryAsPageNumber(2);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), true);
+        });
+        it("should return false for a page number that is not in range (non-wrapped)", () => {
+            const start = tryAsPageNumber(1);
+            const length = 1;
+            const page = tryAsPageNumber(3);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), false);
+        });
+        it("should return false for a page number that is not in range (wrapped)", () => {
+            const start = tryAsPageNumber(MAX_NUMBER_OF_PAGES - 2);
+            const length = 5;
+            const page = tryAsPageNumber(6);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), false);
+        });
+        it("should return false for an empty range", () => {
+            const start = tryAsPageNumber(1);
+            const length = 0;
+            const page = tryAsPageNumber(1);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), false);
+        });
+        it("should return true for a page number that is equal to `start`", () => {
+            const start = tryAsPageNumber(1);
+            const length = 1;
+            const page = tryAsPageNumber(1);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), true);
+        });
+        it("should return false for a page number that is equal to `end`", () => {
+            const start = tryAsPageNumber(1);
+            const length = 1;
+            const page = tryAsPageNumber(2);
+            const pageRange = PageRange.fromStartAndLength(start, length);
+            assert.strictEqual(pageRange.isInRange(page), false);
+        });
+    });
+});

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

@@ -0,0 +1,3 @@
+export { ReadablePage } from "./readable-page.js";
+export { WriteablePage } from "./writeable-page.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/pvm-interpreter/memory/pages/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,2 @@
+export { ReadablePage } from "./readable-page.js";
+export { WriteablePage } from "./writeable-page.js";

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

@@ -0,0 +1,33 @@
+import type { OK, Result } from "#@typeberry/utils";
+import type { PageFault } from "../errors.js";
+import type { MemoryIndex } from "../memory-index.js";
+import type { PageIndex, PageNumber } from "./page-utils.js";
+export declare abstract class MemoryPage {
+    start: MemoryIndex;
+    constructor(pageNumber: PageNumber);
+    /** Returns `true` if the page is writeable. */
+    abstract isWriteable(): boolean;
+    /**
+     * Load exactly `length` bytes from memory page, starting at index `address`
+     * into the `res` array.
+     *
+     * Note that the `res` might be bigger than the number of bytes length, but cannot be smaller.
+     *
+     * Returns `null` if copying was successful and [`PageFault`] otherwise.
+     * NOTE That the `result` might be partially modified in case `PageFault` occurs!
+     */
+    abstract loadInto(res: Uint8Array, address: PageIndex, length: number): Result<OK, PageFault>;
+    /**
+     * Copy all bytes from the `data` into the page at index `address`.
+     *
+     * Returns `null` if copying was successful and [`PageFault`] otherwise.
+     */
+    abstract storeFrom(address: PageIndex, data: Uint8Array): Result<OK, PageFault>;
+    /**
+     * Get dump of the entire page. Should only be used for the debugger-adapter because it
+     * might be inefficient.
+     */
+    abstract getPageDump(): Uint8Array;
+    abstract setData(pageIndex: PageIndex, data: Uint8Array): void;
+}
+//# sourceMappingURL=memory-page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-page.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/pvm-interpreter/memory/pages/memory-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,8BAAsB,UAAU;IACvB,KAAK,EAAE,WAAW,CAAC;gBAEd,UAAU,EAAE,UAAU;IAIlC,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,IAAI,OAAO;IAE/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAE7F;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAC/E;;;OAGG;IACH,QAAQ,CAAC,WAAW,IAAI,UAAU;IAElC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;CAC/D"}

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

@@ -0,0 +1,7 @@
+import { getStartPageIndexFromPageNumber } from "../memory-utils.js";
+export class MemoryPage {
+    start;
+    constructor(pageNumber) {
+        this.start = getStartPageIndexFromPageNumber(pageNumber);
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type Opaque } from "#@typeberry/utils";
+export type PageIndex = Opaque<number, "memory page index">;
+export type PageNumber = Opaque<number, "memory page number">;
+/** Ensure that given memory `index` is within `[0...PAGE_SIZE)` and can be used to index a page */
+export declare const tryAsPageIndex: (index: number) => PageIndex;
+/** Ensure that given `index` represents an index of one of the pages. */
+export declare const tryAsPageNumber: (index: number) => PageNumber;
+/**
+ * Get the next page number and wrap the result if it is bigger than LAST_PAGE_NUMBER
+ *
+ * GP references:
+ * 1. The modulo subscription operator is used in all load/store instructions, for example:
+ * https://graypaper.fluffylabs.dev/#/579bd12/25af0125af01
+ *
+ * 2. Here is the definition of the modulo subscription operator:
+ * https://graypaper.fluffylabs.dev/#/579bd12/073a00073a00
+ */
+export declare function getNextPageNumber(pageNumber: PageNumber): PageNumber;
+//# sourceMappingURL=page-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page-utils.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/pvm-interpreter/memory/pages/page-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAIpE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAE9D,mGAAmG;AACnG,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,SAG9C,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,UAG/C,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAGpE"}

package/packages/core/pvm-interpreter/memory/pages/page-utils.js

@@ -0,0 +1,26 @@
+import { asOpaqueType, check } from "#@typeberry/utils";
+import { LAST_PAGE_NUMBER, PAGE_SIZE } from "../memory-consts.js";
+/** Ensure that given memory `index` is within `[0...PAGE_SIZE)` and can be used to index a page */
+export const tryAsPageIndex = (index) => {
+    check `${index >= 0 && index < PAGE_SIZE}, Incorect page index: ${index}!`;
+    return asOpaqueType(index);
+};
+/** Ensure that given `index` represents an index of one of the pages. */
+export const tryAsPageNumber = (index) => {
+    check `${index >= 0 && index <= LAST_PAGE_NUMBER}, Incorect page number: ${index}!`;
+    return asOpaqueType(index);
+};
+/**
+ * Get the next page number and wrap the result if it is bigger than LAST_PAGE_NUMBER
+ *
+ * GP references:
+ * 1. The modulo subscription operator is used in all load/store instructions, for example:
+ * https://graypaper.fluffylabs.dev/#/579bd12/25af0125af01
+ *
+ * 2. Here is the definition of the modulo subscription operator:
+ * https://graypaper.fluffylabs.dev/#/579bd12/073a00073a00
+ */
+export function getNextPageNumber(pageNumber) {
+    const newPageNumber = pageNumber === LAST_PAGE_NUMBER ? 0 : pageNumber + 1;
+    return tryAsPageNumber(newPageNumber);
+}

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

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

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

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

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

@@ -0,0 +1,16 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { LAST_PAGE_NUMBER } from "../memory-consts.js";
+import { getNextPageNumber, tryAsPageNumber } from "./page-utils.js";
+describe("page-utils / getNextPageNumber", () => {
+    it("should increment the page number", () => {
+        const pageNumber = tryAsPageNumber(5);
+        const nextPageNumber = getNextPageNumber(pageNumber);
+        assert.strictEqual(nextPageNumber, pageNumber + 1);
+    });
+    it("should return 0 for the last page number", () => {
+        const pageNumber = tryAsPageNumber(LAST_PAGE_NUMBER);
+        const nextPageNumber = getNextPageNumber(pageNumber);
+        assert.strictEqual(nextPageNumber, 0);
+    });
+});

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

@@ -0,0 +1,14 @@
+import { OK, Result } from "#@typeberry/utils";
+import { PageFault } from "../errors.js";
+import { MemoryPage } from "./memory-page.js";
+import type { PageIndex, PageNumber } from "./page-utils.js";
+export declare class ReadablePage extends MemoryPage {
+    private data;
+    constructor(pageNumber: PageNumber, data: Uint8Array);
+    loadInto(result: Uint8Array, startIndex: PageIndex, length: number): Result<OK, PageFault>;
+    storeFrom(_address: PageIndex, _data: Uint8Array): Result<OK, PageFault>;
+    setData(pageIndex: PageIndex, data: Uint8Array): void;
+    isWriteable(): boolean;
+    getPageDump(): Uint8Array<ArrayBufferLike>;
+}
+//# sourceMappingURL=readable-page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readable-page.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/pvm-interpreter/memory/pages/readable-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,qBAAa,YAAa,SAAQ,UAAU;IAGxC,OAAO,CAAC,IAAI;gBADZ,UAAU,EAAE,UAAU,EACd,IAAI,EAAE,UAAU;IAK1B,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAiB1F,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAOxE,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU;IAI9C,WAAW;IAIX,WAAW;CAGZ"}

package/packages/core/pvm-interpreter/memory/pages/readable-page.js

@@ -0,0 +1,34 @@
+import { OK, Result } from "#@typeberry/utils";
+import { PageFault } from "../errors.js";
+import { PAGE_SIZE } from "../memory-consts.js";
+import { MemoryPage } from "./memory-page.js";
+export class ReadablePage extends MemoryPage {
+    data;
+    constructor(pageNumber, data) {
+        super(pageNumber);
+        this.data = data;
+    }
+    loadInto(result, startIndex, length) {
+        const endIndex = startIndex + length;
+        if (endIndex > PAGE_SIZE) {
+            return Result.error(PageFault.fromMemoryIndex(this.start + PAGE_SIZE), () => `Page fault: read beyond page boundary at ${this.start + PAGE_SIZE}`);
+        }
+        const bytes = this.data.subarray(startIndex, endIndex);
+        // we zero the bytes, since data might not yet be initialized at `endIndex`.
+        result.fill(0, bytes.length, length);
+        result.set(bytes);
+        return Result.ok(OK);
+    }
+    storeFrom(_address, _data) {
+        return Result.error(PageFault.fromMemoryIndex(this.start, true), () => `Page fault: attempted to write to read-only page at ${this.start}`);
+    }
+    setData(pageIndex, data) {
+        this.data.set(data, pageIndex);
+    }
+    isWriteable() {
+        return false;
+    }
+    getPageDump() {
+        return this.data;
+    }
+}

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

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

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

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

package/packages/core/pvm-interpreter/memory/pages/readable-page.test.js

@@ -0,0 +1,45 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { deepEqual, OK, Result } from "#@typeberry/utils";
+import { PageFault } from "../errors.js";
+import { tryAsMemoryIndex } from "../memory-index.js";
+import { tryAsPageIndex, tryAsPageNumber } from "./page-utils.js";
+import { ReadablePage } from "./readable-page.js";
+describe("ReadablePage", () => {
+    it("should load 4 byts from memory", () => {
+        const bytes = new Uint8Array([1, 2, 3, 4]);
+        const initialMemory = new Uint8Array([0, ...bytes]);
+        const startIndex = tryAsMemoryIndex(0);
+        const pageNumber = tryAsPageNumber(0);
+        const readablePage = new ReadablePage(pageNumber, initialMemory);
+        const lengthToLoad = 4;
+        const result = new Uint8Array(lengthToLoad);
+        const expectedResult = bytes;
+        const loadIndex = tryAsPageIndex(startIndex + 1);
+        const loadResult = readablePage.loadInto(result, loadIndex, lengthToLoad);
+        assert.deepStrictEqual(loadResult, Result.ok(OK));
+        assert.deepStrictEqual(result, expectedResult);
+    });
+    it("should fill missing bytes with zeros", () => {
+        const bytes = new Uint8Array([1, 2, 3, 4]);
+        const initialMemory = new Uint8Array([0, ...bytes]);
+        const startIndex = tryAsMemoryIndex(0);
+        const pageNumber = tryAsPageNumber(0);
+        const readablePage = new ReadablePage(pageNumber, initialMemory);
+        const lengthToLoad = 4;
+        const result = new Uint8Array(lengthToLoad);
+        const expectedResult = new Uint8Array([3, 4, 0, 0]);
+        const loadIndex = tryAsPageIndex(startIndex + 3);
+        const loadResult = readablePage.loadInto(result, loadIndex, lengthToLoad);
+        assert.deepStrictEqual(loadResult, Result.ok(OK));
+        assert.deepStrictEqual(result, expectedResult);
+    });
+    it("should throw a page fault error when store is used", () => {
+        const initialMemory = new Uint8Array();
+        const storeIndex = tryAsPageIndex(0);
+        const pageNumber = tryAsPageNumber(0);
+        const readablePage = new ReadablePage(pageNumber, initialMemory);
+        const storeResult = readablePage.storeFrom(storeIndex, new Uint8Array());
+        deepEqual(storeResult, Result.error(PageFault.fromPageNumber(0, true), () => "Page fault: attempted to write to read-only page at 0"));
+    });
+});

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

@@ -0,0 +1,30 @@
+import { OK, Result } from "#@typeberry/utils";
+import { PageFault } from "../errors.js";
+import { MemoryPage } from "./memory-page.js";
+import type { PageIndex, PageNumber } from "./page-utils.js";
+/**
+ * I had to extend ArrayBuffer type to use resizable ArrayBuffer.
+ * We will be able to remove it when this is merged: https://github.com/microsoft/TypeScript/pull/58573
+ * And then a new version of TypeScript is released.
+ */
+declare global {
+    interface ArrayBufferConstructor {
+        new (length: number, options?: {
+            maxByteLength: number;
+        }): ArrayBuffer;
+    }
+    interface ArrayBuffer {
+        resize(length: number): void;
+    }
+}
+export declare class WriteablePage extends MemoryPage {
+    private buffer;
+    private view;
+    constructor(pageNumber: PageNumber, initialData?: Uint8Array);
+    loadInto(result: Uint8Array, startIndex: PageIndex, length: number): Result<OK, PageFault>;
+    storeFrom(startIndex: PageIndex, bytes: Uint8Array): Result<OK, PageFault>;
+    setData(pageIndex: PageIndex, data: Uint8Array): void;
+    isWriteable(): boolean;
+    getPageDump(): Uint8Array<ArrayBufferLike>;
+}
+//# sourceMappingURL=writeable-page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeable-page.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/pvm-interpreter/memory/pages/writeable-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D;;;;GAIG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,sBAAsB;QAC9B,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;YAAE,aAAa,EAAE,MAAM,CAAA;SAAE,GAAG,WAAW,CAAC;KACxE;IAED,UAAU,WAAW;QACnB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B;CACF;AAED,qBAAa,aAAc,SAAQ,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,IAAI,CAAa;gBAEb,UAAU,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,UAAU;IAW5D,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAiB1F,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAU1E,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU;IAQ9C,WAAW;IAIX,WAAW;CAGZ"}

package/packages/core/pvm-interpreter/memory/pages/writeable-page.js

@@ -0,0 +1,50 @@
+import { OK, Result } from "#@typeberry/utils";
+import { PageFault } from "../errors.js";
+import { MIN_ALLOCATION_LENGTH, PAGE_SIZE } from "../memory-consts.js";
+import { MemoryPage } from "./memory-page.js";
+export class WriteablePage extends MemoryPage {
+    buffer;
+    view;
+    constructor(pageNumber, initialData) {
+        super(pageNumber);
+        const dataLength = initialData?.length ?? 0;
+        const initialPageLength = Math.min(PAGE_SIZE, Math.max(dataLength, MIN_ALLOCATION_LENGTH));
+        this.buffer = new ArrayBuffer(initialPageLength, { maxByteLength: PAGE_SIZE });
+        this.view = new Uint8Array(this.buffer);
+        if (initialData !== undefined) {
+            this.view.set(initialData);
+        }
+    }
+    loadInto(result, startIndex, length) {
+        const endIndex = startIndex + length;
+        if (endIndex > PAGE_SIZE) {
+            return Result.error(PageFault.fromMemoryIndex(this.start + PAGE_SIZE), () => `Page fault: read beyond page boundary at ${this.start + PAGE_SIZE}`);
+        }
+        const bytes = this.view.subarray(startIndex, endIndex);
+        // we zero the bytes, since the view might not yet be initialized at `endIndex`.
+        result.fill(0, bytes.length, length);
+        result.set(bytes);
+        return Result.ok(OK);
+    }
+    storeFrom(startIndex, bytes) {
+        if (this.buffer.byteLength < startIndex + bytes.length && this.buffer.byteLength < PAGE_SIZE) {
+            const newLength = Math.min(PAGE_SIZE, Math.max(MIN_ALLOCATION_LENGTH, startIndex + bytes.length));
+            this.buffer.resize(newLength);
+        }
+        this.view.set(bytes, startIndex);
+        return Result.ok(OK);
+    }
+    setData(pageIndex, data) {
+        if (this.buffer.byteLength < pageIndex + data.length && this.buffer.byteLength < PAGE_SIZE) {
+            const newLength = Math.min(PAGE_SIZE, Math.max(MIN_ALLOCATION_LENGTH, pageIndex + data.length));
+            this.buffer.resize(newLength);
+        }
+        this.view.set(data, pageIndex);
+    }
+    isWriteable() {
+        return true;
+    }
+    getPageDump() {
+        return this.view;
+    }
+}

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

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

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

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