@typeberry/lib 0.5.1 → 0.5.2-03e1aed

package/packages/jam/jam-host-calls/general/write.test.js

@@ -0,0 +1,175 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsServiceGas, tryAsServiceId, tryAsTimeSlot } from "#@typeberry/block";
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { tryAsU32, tryAsU64 } from "#@typeberry/numbers";
+import { HostCallMemory, HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { tryAsGas } from "#@typeberry/pvm-interface";
+import { gasCounter } from "#@typeberry/pvm-interpreter";
+import { MemoryBuilder, tryAsMemoryIndex } from "#@typeberry/pvm-interpreter/memory/index.js";
+import { tryAsSbrkIndex } from "#@typeberry/pvm-interpreter/memory/memory-index.js";
+import { PAGE_SIZE } from "#@typeberry/pvm-interpreter/spi-decoder/memory-conts.js";
+import { ServiceAccountInfo } from "#@typeberry/state";
+import { asOpaqueType } from "#@typeberry/utils";
+import { TestAccounts } from "../externalities/test-accounts.js";
+import { emptyRegistersBuffer } from "../utils.js";
+import { HostCallResult } from "./results.js";
+import { Write } from "./write.js";
+const gas = gasCounter(tryAsGas(0));
+const RESULT_REG = 7;
+const KEY_START_REG = 7;
+const KEY_LEN_REG = 8;
+const DEST_START_REG = 9;
+const DEST_LEN_REG = 10;
+function prepareAccounts(serviceId, { balance, gratisStorage } = {}) {
+    const accounts = new TestAccounts(serviceId);
+    accounts.details.set(serviceId, ServiceAccountInfo.create({
+        codeHash: Bytes.fill(32, 5).asOpaque(),
+        balance: tryAsU64(balance ?? 150_000),
+        accumulateMinGas: tryAsServiceGas(0n),
+        onTransferMinGas: tryAsServiceGas(0n),
+        storageUtilisationBytes: tryAsU64(10_000),
+        storageUtilisationCount: tryAsU32(1_000),
+        gratisStorage: tryAsU64(gratisStorage ?? 0),
+        created: tryAsTimeSlot(0),
+        lastAccumulation: tryAsTimeSlot(0),
+        parentService: tryAsServiceId(0),
+    }));
+    return accounts;
+}
+function prepareRegsAndMemory(key, dataInMemory, { skipKey = false, skipValue = false } = {}) {
+    const keyAddress = 2 ** 18;
+    const memStart = 2 ** 16;
+    const registers = new HostCallRegisters(emptyRegistersBuffer());
+    registers.set(KEY_START_REG, tryAsU64(keyAddress));
+    registers.set(KEY_LEN_REG, tryAsU64(key.length));
+    registers.set(DEST_START_REG, tryAsU64(memStart));
+    registers.set(DEST_LEN_REG, tryAsU64(dataInMemory.length));
+    const builder = new MemoryBuilder();
+    if (!skipKey) {
+        builder.setReadablePages(tryAsMemoryIndex(keyAddress), tryAsMemoryIndex(keyAddress + PAGE_SIZE), key.raw);
+    }
+    if (!skipValue && dataInMemory.length > 0) {
+        builder.setReadablePages(tryAsMemoryIndex(memStart), tryAsMemoryIndex(memStart + PAGE_SIZE), dataInMemory.raw);
+    }
+    const memory = new HostCallMemory(builder.finalize(tryAsMemoryIndex(0), tryAsSbrkIndex(0)));
+    return {
+        registers,
+        memory,
+    };
+}
+describe("HostCalls: Write", () => {
+    it("should write data to account state", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId);
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("imma key");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world!"));
+        accounts.storage.set(BytesBlob.blobFromString("old data"), serviceId, asOpaqueType(key));
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64("old data".length));
+        assert.deepStrictEqual(accounts.storage.get(serviceId, asOpaqueType(key))?.asText(), "hello world!");
+        assert.deepStrictEqual(accounts.storage.data.size, 1);
+    });
+    it("should write data to account state when low balance but with gratisStorage", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId, { balance: 100n, gratisStorage: 150000n });
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("imma key");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world!"));
+        accounts.storage.set(BytesBlob.blobFromString("old data"), serviceId, asOpaqueType(key));
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), tryAsU64("old data".length));
+        assert.deepStrictEqual(accounts.storage.get(serviceId, asOpaqueType(key))?.asText(), "hello world!");
+        assert.deepStrictEqual(accounts.storage.data.size, 1);
+    });
+    it("should remove data from account state", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId);
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("xyz");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromNumbers([]));
+        accounts.storage.set(BytesBlob.blobFromString("hello world!"), serviceId, asOpaqueType(key));
+        accounts.storage.set(null, serviceId, asOpaqueType(key));
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), HostCallResult.NONE);
+        assert.deepStrictEqual(accounts.storage.get(serviceId, asOpaqueType(key)), undefined);
+    });
+    it("should fail if there is no memory for key", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId);
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("xyz");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world!"), {
+            skipKey: true,
+        });
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(accounts.storage.data.size, 0);
+    });
+    it("should fail if there is no memory for result", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId);
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("xyz");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world!"), {
+            skipValue: true,
+        });
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(accounts.storage.data.size, 0);
+    });
+    it("should fail if the key is not fully readable", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId);
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("xyz");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world!"));
+        registers.set(KEY_LEN_REG, tryAsU64(PAGE_SIZE + 1));
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(accounts.storage.data.size, 0);
+    });
+    it("should fail if the value is not fully readable", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId);
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("xyz");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world!"));
+        registers.set(DEST_LEN_REG, tryAsU64(PAGE_SIZE + 1));
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, PvmExecution.Panic);
+        assert.deepStrictEqual(accounts.storage.data.size, 0);
+    });
+    it("should handle storage full when low balance in the account", async () => {
+        const serviceId = tryAsServiceId(10_000);
+        const accounts = prepareAccounts(serviceId, { balance: 100n });
+        const write = new Write(serviceId, accounts);
+        const key = BytesBlob.blobFromString("imma key");
+        const { registers, memory } = prepareRegsAndMemory(key, BytesBlob.blobFromString("hello world! Is super long very very very."));
+        accounts.storage.set(BytesBlob.blobFromString("old data"), serviceId, asOpaqueType(key));
+        // when
+        const result = await write.execute(gas, registers, memory);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), HostCallResult.FULL);
+        assert.deepStrictEqual(accounts.storage.data.size, 1);
+    });
+});

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

@@ -0,0 +1,11 @@
+export * as accumulate from "./accumulate/index.js";
+export * from "./externalities/partial-state.js";
+export * from "./externalities/pending-transfer.js";
+export * from "./externalities/refine-externalities.js";
+export * from "./externalities/state-update.js";
+export * as general from "./general/index.js";
+export { codecServiceAccountInfoWithThresholdBalance as hostCallInfoAccount } from "./general/info.js";
+export * from "./general/results.js";
+export * as refine from "./refine/index.js";
+export * from "./utils.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/jam-host-calls/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC;AACxD,cAAc,iCAAiC,CAAC;AAChD,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,2CAA2C,IAAI,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACvG,cAAc,sBAAsB,CAAC;AACrC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,10 @@
+export * as accumulate from "./accumulate/index.js";
+export * from "./externalities/partial-state.js";
+export * from "./externalities/pending-transfer.js";
+export * from "./externalities/refine-externalities.js";
+export * from "./externalities/state-update.js";
+export * as general from "./general/index.js";
+export { codecServiceAccountInfoWithThresholdBalance as hostCallInfoAccount } from "./general/info.js";
+export * from "./general/results.js";
+export * as refine from "./refine/index.js";
+export * from "./utils.js";

package/packages/jam/jam-host-calls/logger.d.ts

@@ -0,0 +1,3 @@
+import { Logger } from "#@typeberry/logger";
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/packages/jam/jam-host-calls/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/jam-host-calls/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,eAAO,MAAM,MAAM,QAAiD,CAAC"}

package/packages/jam/jam-host-calls/logger.js

@@ -0,0 +1,2 @@
+import { Logger } from "#@typeberry/logger";
+export const logger = Logger.new(import.meta.filename, "host-calls");

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

@@ -0,0 +1,18 @@
+import { type HostCallHandler, type HostCallMemory, type HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { type IGasCounter } from "#@typeberry/pvm-interface";
+import type { RefineExternalities } from "../externalities/refine-externalities.js";
+/**
+ * Export a segment to be imported by some future `refine` invokation.
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/341d01341d01?v=0.6.7
+ */
+export declare class Export implements HostCallHandler {
+    private readonly refine;
+    index: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"HostCallIndex[U32]">;
+    basicGasCost: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"SmallGas[U32]">;
+    currentServiceId: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"ServiceId[u32]">;
+    tracedRegisters: (number & import("@typeberry/utils").WithOpaque<"register index">)[];
+    constructor(refine: RefineExternalities);
+    execute(_gas: IGasCounter, regs: HostCallRegisters, memory: HostCallMemory): Promise<PvmExecution | undefined>;
+}
+//# sourceMappingURL=export.d.ts.map

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

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

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

@@ -0,0 +1,49 @@
+import { SEGMENT_BYTES } from "#@typeberry/block";
+import { Bytes } from "#@typeberry/bytes";
+import { minU64, tryAsU64 } from "#@typeberry/numbers";
+import { PvmExecution, traceRegisters, tryAsHostCallIndex, } from "#@typeberry/pvm-host-calls";
+import { tryAsSmallGas } from "#@typeberry/pvm-interface";
+import { resultToString } from "#@typeberry/utils";
+import { HostCallResult } from "../general/results.js";
+import { logger } from "../logger.js";
+import { CURRENT_SERVICE_ID } from "../utils.js";
+const IN_OUT_REG = 7;
+/**
+ * Export a segment to be imported by some future `refine` invokation.
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/341d01341d01?v=0.6.7
+ */
+export class Export {
+    refine;
+    index = tryAsHostCallIndex(7);
+    basicGasCost = tryAsSmallGas(10);
+    currentServiceId = CURRENT_SERVICE_ID;
+    tracedRegisters = traceRegisters(IN_OUT_REG, 8);
+    constructor(refine) {
+        this.refine = refine;
+    }
+    async execute(_gas, regs, memory) {
+        // `p`: segment start address
+        const segmentStart = regs.get(IN_OUT_REG);
+        // `z`: segment bounded length
+        // NOTE [MaSo] it's always safe to cast to u32 (number) because the length is bounded by SEGMENT_BYTES.
+        const segmentLength = Number(minU64(regs.get(8), tryAsU64(SEGMENT_BYTES)));
+        // `x`: destination (padded with zeros).
+        const segment = Bytes.zero(SEGMENT_BYTES);
+        const segmentReadResult = memory.loadInto(segment.raw.subarray(0, segmentLength), segmentStart);
+        if (segmentReadResult.isError) {
+            logger.trace `[${this.currentServiceId}] EXPORT(${segment.toStringTruncated()}) <- PANIC`;
+            return PvmExecution.Panic;
+        }
+        // attempt to export a segment and fail if it's above the maximum.
+        const segmentExported = this.refine.exportSegment(segment);
+        logger.trace `[${this.currentServiceId}] EXPORT(${segment.toStringTruncated()}) <- ${resultToString(segmentExported)}`;
+        logger.insane `[${this.currentServiceId}] EXPORT(${segment}) <- ${resultToString(segmentExported)}`;
+        if (segmentExported.isOk) {
+            regs.set(IN_OUT_REG, tryAsU64(segmentExported.ok));
+        }
+        else {
+            regs.set(IN_OUT_REG, HostCallResult.FULL);
+        }
+    }
+}

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

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

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

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

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

@@ -0,0 +1,91 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { SEGMENT_BYTES, tryAsSegmentIndex, tryAsServiceId } from "#@typeberry/block";
+import { Bytes } from "#@typeberry/bytes";
+import { tryAsU64 } from "#@typeberry/numbers";
+import { HostCallMemory, HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { tryAsGas } from "#@typeberry/pvm-interface";
+import { gasCounter } from "#@typeberry/pvm-interpreter/gas.js";
+import { MemoryBuilder, tryAsMemoryIndex } from "#@typeberry/pvm-interpreter/memory/index.js";
+import { tryAsSbrkIndex } from "#@typeberry/pvm-interpreter/memory/memory-index.js";
+import { PAGE_SIZE } from "#@typeberry/pvm-interpreter/spi-decoder/memory-conts.js";
+import { Result } from "#@typeberry/utils";
+import { SegmentExportError } from "../externalities/refine-externalities.js";
+import { TestRefineExt } from "../externalities/refine-externalities.test.js";
+import { HostCallResult } from "../general/results.js";
+import { emptyRegistersBuffer } from "../utils.js";
+import { Export } from "./export.js";
+const gas = gasCounter(tryAsGas(0));
+const SEGMENT_START_REG = 7;
+const RESULT_REG = SEGMENT_START_REG;
+const SEGMENT_LENGTH_REG = 8;
+function prepareRegsAndMemory(segment, segmentLength = segment.length, { skipSegment = false } = {}) {
+    const memStart = 2 ** 23;
+    const registers = new HostCallRegisters(emptyRegistersBuffer());
+    registers.set(SEGMENT_START_REG, tryAsU64(memStart));
+    registers.set(SEGMENT_LENGTH_REG, tryAsU64(segmentLength));
+    const builder = new MemoryBuilder();
+    if (!skipSegment) {
+        builder.setReadablePages(tryAsMemoryIndex(memStart), tryAsMemoryIndex(memStart + 2 * PAGE_SIZE), segment.raw);
+    }
+    const memory = new HostCallMemory(builder.finalize(tryAsMemoryIndex(0), tryAsSbrkIndex(0)));
+    return {
+        registers,
+        memory,
+    };
+}
+describe("HostCalls: Export", () => {
+    it("should export a segment", async () => {
+        const refine = new TestRefineExt();
+        const exp = new Export(refine);
+        exp.currentServiceId = tryAsServiceId(10_000);
+        const segment = Bytes.fill(SEGMENT_BYTES, 15).asOpaque();
+        const { registers, memory } = prepareRegsAndMemory(segment);
+        refine.exportSegmentData.set(Result.ok(tryAsSegmentIndex(15)), segment);
+        // when
+        const result = await exp.execute(gas, registers, memory);
+        // then
+        assert.deepStrictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), 15n);
+    });
+    it("should zero-pad when exported value is small", async () => {
+        const refine = new TestRefineExt();
+        const exp = new Export(refine);
+        exp.currentServiceId = tryAsServiceId(10_000);
+        const segment = Bytes.fill(SEGMENT_BYTES, 15).asOpaque();
+        const { registers, memory } = prepareRegsAndMemory(segment, 2);
+        const expectedSegment = Bytes.zero(SEGMENT_BYTES);
+        expectedSegment.raw[0] = 15;
+        expectedSegment.raw[1] = 15;
+        refine.exportSegmentData.set(Result.ok(tryAsSegmentIndex(5)), expectedSegment);
+        // when
+        const result = await exp.execute(gas, registers, memory);
+        // then
+        assert.deepStrictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), 5n);
+    });
+    it("should panic if memory is not readable", async () => {
+        const refine = new TestRefineExt();
+        const exp = new Export(refine);
+        exp.currentServiceId = tryAsServiceId(10_000);
+        const segment = Bytes.fill(SEGMENT_BYTES, 15).asOpaque();
+        const { registers, memory } = prepareRegsAndMemory(segment, segment.length, { skipSegment: true });
+        // when
+        const result = await exp.execute(gas, registers, memory);
+        // then
+        assert.deepStrictEqual(result, PvmExecution.Panic);
+    });
+    it("should fail with FULL if export limit is reached", async () => {
+        const refine = new TestRefineExt();
+        const exp = new Export(refine);
+        exp.currentServiceId = tryAsServiceId(10_000);
+        const segment = Bytes.fill(SEGMENT_BYTES, 15).asOpaque();
+        const { registers, memory } = prepareRegsAndMemory(segment);
+        refine.exportSegmentData.set(Result.error(SegmentExportError, () => "Test: error occurred"), segment);
+        // when
+        const result = await exp.execute(gas, registers, memory);
+        // then
+        assert.deepStrictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), HostCallResult.FULL);
+    });
+});

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

@@ -0,0 +1,18 @@
+import { type HostCallHandler, type HostCallRegisters, type PvmExecution } from "#@typeberry/pvm-host-calls";
+import { type IGasCounter } from "#@typeberry/pvm-interface";
+import { type RefineExternalities } from "../externalities/refine-externalities.js";
+/**
+ * Forget a previously started nested machine.
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/358502358502?v=0.6.7
+ */
+export declare class Expunge implements HostCallHandler {
+    private readonly refine;
+    index: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"HostCallIndex[U32]">;
+    basicGasCost: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"SmallGas[U32]">;
+    currentServiceId: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"ServiceId[u32]">;
+    tracedRegisters: (number & import("@typeberry/utils").WithOpaque<"register index">)[];
+    constructor(refine: RefineExternalities);
+    execute(_gas: IGasCounter, regs: HostCallRegisters): Promise<PvmExecution | undefined>;
+}
+//# sourceMappingURL=expunge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expunge.d.ts","sourceRoot":"","sources":["../../../../../../packages/jam/jam-host-calls/refine/expunge.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGlB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAE3E,OAAO,EAAE,KAAK,mBAAmB,EAAkB,MAAM,0CAA0C,CAAC;AAOpG;;;;GAIG;AACH,qBAAa,OAAQ,YAAW,eAAe;IAMjC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,KAAK,iIAA0B;IAC/B,YAAY,4HAAqB;IACjC,gBAAgB,6HAAsB;IACtC,eAAe,uEAA8B;gBAEhB,MAAM,EAAE,mBAAmB;IAElD,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CAe7F"}

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

@@ -0,0 +1,36 @@
+import { traceRegisters, tryAsHostCallIndex, } from "#@typeberry/pvm-host-calls";
+import { tryAsSmallGas } from "#@typeberry/pvm-interface";
+import { resultToString } from "#@typeberry/utils";
+import { tryAsMachineId } from "../externalities/refine-externalities.js";
+import { HostCallResult } from "../general/results.js";
+import { logger } from "../logger.js";
+import { CURRENT_SERVICE_ID } from "../utils.js";
+const IN_OUT_REG = 7;
+/**
+ * Forget a previously started nested machine.
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/358502358502?v=0.6.7
+ */
+export class Expunge {
+    refine;
+    index = tryAsHostCallIndex(13);
+    basicGasCost = tryAsSmallGas(10);
+    currentServiceId = CURRENT_SERVICE_ID;
+    tracedRegisters = traceRegisters(IN_OUT_REG);
+    constructor(refine) {
+        this.refine = refine;
+    }
+    async execute(_gas, regs) {
+        // `n`: machine index
+        const machineIndex = tryAsMachineId(regs.get(IN_OUT_REG));
+        const expungeResult = await this.refine.machineExpunge(machineIndex);
+        logger.trace `[${this.currentServiceId}] EXPUNGE(${machineIndex}) <- ${resultToString(expungeResult)}`;
+        if (expungeResult.isOk) {
+            regs.set(IN_OUT_REG, expungeResult.ok);
+        }
+        else {
+            regs.set(IN_OUT_REG, HostCallResult.WHO);
+        }
+        return;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,57 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsServiceId } from "#@typeberry/block";
+import { HostCallMemory, HostCallRegisters } from "#@typeberry/pvm-host-calls";
+import { tryAsGas } from "#@typeberry/pvm-interface";
+import { gasCounter, MemoryBuilder } from "#@typeberry/pvm-interpreter";
+import { tryAsMemoryIndex, tryAsSbrkIndex } from "#@typeberry/pvm-interpreter/memory/memory-index.js";
+import { Result } from "#@typeberry/utils";
+import { NoMachineError, tryAsMachineId, tryAsProgramCounter, } from "../externalities/refine-externalities.js";
+import { TestRefineExt } from "../externalities/refine-externalities.test.js";
+import { HostCallResult } from "../general/results.js";
+import { emptyRegistersBuffer } from "../utils.js";
+import { Expunge } from "./expunge.js";
+const gas = gasCounter(tryAsGas(0));
+const RESULT_REG = 7;
+function prepareRegsAndMemory(machineId) {
+    const registers = new HostCallRegisters(emptyRegistersBuffer());
+    registers.set(7, machineId);
+    const builder = new MemoryBuilder();
+    const memory = new HostCallMemory(builder.finalize(tryAsMemoryIndex(0), tryAsSbrkIndex(0)));
+    return {
+        registers,
+        memory,
+    };
+}
+function prepareTest(result) {
+    const refine = new TestRefineExt();
+    const expunge = new Expunge(refine);
+    expunge.currentServiceId = tryAsServiceId(10_000);
+    const machineId = tryAsMachineId(10_000);
+    const { registers, memory } = prepareRegsAndMemory(machineId);
+    refine.machineExpungeData.set(result, machineId);
+    return {
+        expunge,
+        registers,
+        memory,
+    };
+}
+describe("HostCalls: Expunge", () => {
+    it("should expunge machine and return its program counter", async () => {
+        const programCounter = tryAsProgramCounter(0x123456789abcdef0n);
+        const { expunge, registers } = prepareTest(Result.ok(programCounter));
+        // when
+        const result = await expunge.execute(gas, registers);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), programCounter);
+    });
+    it("should return WHO if machine unknown", async () => {
+        const { expunge, registers } = prepareTest(Result.error(NoMachineError, () => "Test: error occurred"));
+        // when
+        const result = await expunge.execute(gas, registers);
+        // then
+        assert.strictEqual(result, undefined);
+        assert.deepStrictEqual(registers.get(RESULT_REG), HostCallResult.WHO);
+    });
+});

package/packages/jam/jam-host-calls/refine/historical-lookup.d.ts

@@ -0,0 +1,18 @@
+import { type HostCallHandler, type HostCallMemory, type HostCallRegisters, PvmExecution } from "#@typeberry/pvm-host-calls";
+import { type IGasCounter } from "#@typeberry/pvm-interface";
+import type { RefineExternalities } from "../externalities/refine-externalities.js";
+/**
+ * Lookup a historical preimage.
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/343b00343b00?v=0.6.7
+ */
+export declare class HistoricalLookup implements HostCallHandler {
+    private readonly refine;
+    index: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"HostCallIndex[U32]">;
+    basicGasCost: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"SmallGas[U32]">;
+    currentServiceId: number & import("@typeberry/numbers").WithBytesRepresentation<4> & import("@typeberry/utils").WithOpaque<"ServiceId[u32]">;
+    tracedRegisters: (number & import("@typeberry/utils").WithOpaque<"register index">)[];
+    constructor(refine: RefineExternalities);
+    execute(_gas: IGasCounter, regs: HostCallRegisters, memory: HostCallMemory): Promise<PvmExecution | undefined>;
+}
+//# sourceMappingURL=historical-lookup.d.ts.map

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

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

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

@@ -0,0 +1,58 @@
+import { Bytes } from "#@typeberry/bytes";
+import { HASH_SIZE } from "#@typeberry/hash";
+import { minU64, tryAsU64 } from "#@typeberry/numbers";
+import { PvmExecution, traceRegisters, tryAsHostCallIndex, } from "#@typeberry/pvm-host-calls";
+import { tryAsSmallGas } from "#@typeberry/pvm-interface";
+import { HostCallResult } from "../general/results.js";
+import { logger } from "../logger.js";
+import { CURRENT_SERVICE_ID, getServiceIdOrCurrent } from "../utils.js";
+const IN_OUT_REG = 7;
+/**
+ * Lookup a historical preimage.
+ *
+ * https://graypaper.fluffylabs.dev/#/7e6ff6a/343b00343b00?v=0.6.7
+ */
+export class HistoricalLookup {
+    refine;
+    index = tryAsHostCallIndex(6);
+    basicGasCost = tryAsSmallGas(10);
+    currentServiceId = CURRENT_SERVICE_ID;
+    tracedRegisters = traceRegisters(IN_OUT_REG, 8, 9);
+    constructor(refine) {
+        this.refine = refine;
+    }
+    async execute(_gas, regs, memory) {
+        // a
+        const serviceId = getServiceIdOrCurrent(IN_OUT_REG, regs, this.currentServiceId);
+        // h
+        const hashStart = regs.get(8);
+        // o
+        const destinationStart = regs.get(9);
+        const hash = Bytes.zero(HASH_SIZE);
+        const hashLoadingResult = memory.loadInto(hash.raw, hashStart);
+        // we return Panic in case the key can't be loaded.
+        if (hashLoadingResult.isError) {
+            logger.trace `[${this.currentServiceId}] HISTORICAL_LOOKUP(${serviceId}, ${hash}) <- PANIC`;
+            return PvmExecution.Panic;
+        }
+        const value = await this.refine.historicalLookup(serviceId, hash);
+        logger.trace `[${this.currentServiceId}] HISTORICAL_LOOKUP(${serviceId}, ${hash}) <- ${value}`;
+        const length = tryAsU64(value === null ? 0 : value.raw.length);
+        // f
+        const offset = minU64(regs.get(10), length);
+        // l
+        const destinationLength = minU64(regs.get(11), tryAsU64(length - offset));
+        // NOTE: casting to u32 (number) is safe here because we are bounded by length which is less than 2^32.
+        const data = value === null ? new Uint8Array() : value.raw.subarray(Number(offset), Number(offset + destinationLength));
+        const segmentWriteResult = memory.storeFrom(destinationStart, data);
+        if (segmentWriteResult.isError) {
+            return PvmExecution.Panic;
+        }
+        if (value === null) {
+            regs.set(IN_OUT_REG, HostCallResult.NONE);
+            return;
+        }
+        // copy value to the memory and set the length to register 7
+        regs.set(IN_OUT_REG, length);
+    }
+}

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

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

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

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