@typeberry/lib 0.5.1-aff8b4f → 0.5.1-eb84786

package/packages/core/networking/testing.js

@@ -0,0 +1,206 @@
+import { WritableStream } from "node:stream/web";
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { ED25519_KEY_BYTES } from "#@typeberry/crypto";
+import { Logger } from "#@typeberry/logger";
+import { asOpaqueType, OK } from "#@typeberry/utils";
+import { PeersManagement, } from "./peers.js";
+const logger = Logger.new(import.meta.filename, "test:net");
+/**
+ * Stream implementation that allows manual control over
+ * received and sent bytes.
+ */
+export class TestManualStream {
+    streamId;
+    writable;
+    readable;
+    _writtenData = [];
+    _incomingData;
+    _onError = [];
+    constructor(streamId) {
+        this.streamId = streamId;
+        // simulate incoming data stream
+        const { writable, readable } = new TransformStream();
+        this.readable = readable;
+        this._incomingData = writable;
+        // intercept outgoing data
+        const _writtenData = this._writtenData;
+        this.writable = new WritableStream({
+            write(chunk) {
+                _writtenData.push(chunk);
+            },
+        });
+    }
+    addOnError(onError) {
+        this._onError.push(onError);
+    }
+    async destroy() {
+        await this.writable.abort("destroying");
+    }
+    _simulateIncomingData(kindData) {
+        const writer = this._incomingData.getWriter();
+        writer.write(kindData);
+        writer.releaseLock();
+    }
+}
+export class TestDuplexStream {
+    streamId;
+    readable;
+    writable;
+    static pair(id) {
+        const id1 = id;
+        const id2 = id + 1_000_000;
+        const { writable: w1, readable: r1 } = new TransformStream({
+            transform(chunk, ctrl) {
+                logger.trace `[${id}] <-- [${id2}] ${BytesBlob.blobFrom(chunk)}`;
+                ctrl.enqueue(chunk);
+            },
+        });
+        const { writable: w2, readable: r2 } = new TransformStream({
+            transform(chunk, ctrl) {
+                logger.trace `[${id}] --> [${id2}] ${BytesBlob.blobFrom(chunk)}`;
+                ctrl.enqueue(chunk);
+            },
+        });
+        return [new TestDuplexStream(id1, r1, w2), new TestDuplexStream(id2, r2, w1)];
+    }
+    _onError = [];
+    addOnError(onError) {
+        this._onError.push(onError);
+    }
+    constructor(streamId, readable, writable) {
+        this.streamId = streamId;
+        this.readable = readable;
+        this.writable = writable;
+    }
+    async destroy() { }
+}
+/**
+ * A representation of some remote peer, that's actually
+ * coupled with another instance of `TestPeer`.
+ *
+ * This allows us to have two peers connected together,
+ * so that when one opens a stream, the other one
+ * receives a callback about new stream being opened, etc.
+ */
+export class TestPeer {
+    _streamId;
+    connectionId;
+    address;
+    id;
+    key;
+    static pairUp(a, b) {
+        a._otherPeer = b;
+        b._otherPeer = a;
+        return [a, b];
+    }
+    _onIncomingStreams = [];
+    _otherPeer = null;
+    constructor(_streamId, connectionId, address, id, key) {
+        this._streamId = _streamId;
+        this.connectionId = connectionId;
+        this.address = address;
+        this.id = id;
+        this.key = key;
+        this.addOnIncomingStream((stream) => {
+            logger.log `[${this.id}] incoming stream: ${stream.streamId}: ${this._onIncomingStreams.length} listeners`;
+            return OK;
+        });
+    }
+    addOnIncomingStream(streamCallback) {
+        this._onIncomingStreams.push(streamCallback);
+    }
+    openStream() {
+        const streamId = this._streamId++;
+        const [txStream, rxStream] = TestDuplexStream.pair(streamId);
+        logger.log `[peer:${this.id}] --> [peer:${this._otherPeer?.id}] opening streams ${txStream.streamId} -> ${rxStream.streamId}`;
+        // Allow the "virtual" connection to be full estabilished,
+        // before triggering the callbacks. We currently assume
+        // this happens synchronously, but if that causes issues
+        // we may also trigger that manually.
+        setImmediate(() => {
+            for (const cb of this._otherPeer?._onIncomingStreams ?? []) {
+                cb(rxStream);
+            }
+        });
+        return txStream;
+    }
+    async disconnect() { }
+}
+export class TestPeerDisconnected {
+    connectionId;
+    address;
+    id;
+    key;
+    _streamId = 0;
+    _onIncomingStreams = [];
+    _openedStreams = [];
+    _disconnectCalled = false;
+    constructor(connectionId, address, id, key) {
+        this.connectionId = connectionId;
+        this.address = address;
+        this.id = id;
+        this.key = key;
+    }
+    addOnIncomingStream(streamCallback) {
+        this._onIncomingStreams.push(streamCallback);
+    }
+    openStream() {
+        const stream = new TestManualStream(this._streamId++);
+        this._openedStreams.push(stream);
+        return stream;
+    }
+    async disconnect() {
+        this._disconnectCalled = true;
+    }
+}
+/**
+ * Create a standalone test peer, that allows fine-grained control over the received
+ * and sent data.
+ */
+export function createDisconnectedPeer(id, host = "127.0.0.1", port = 8080) {
+    return new TestPeerDisconnected(`conn-${id}`, { host, port }, asOpaqueType(id), Bytes.zero(ED25519_KEY_BYTES).asOpaque());
+}
+/**
+ * Creates two peer objects that are interconnected - sending data
+ * over `writable` of one peer, will cause it to be receied on
+ * `readable` on the other peer and vice-versa.
+ */
+export function createTestPeerPair(streamIdx, id1, id2) {
+    const host = "127.0.0.1";
+    const port = 8080;
+    const key = Bytes.zero(ED25519_KEY_BYTES).asOpaque();
+    return TestPeer.pairUp(new TestPeer(streamIdx, `conn-${id1}-${id2}`, { host, port }, asOpaqueType(id1), key), new TestPeer(streamIdx + 10_000, `conn-${id1}-${id2}`, { host, port }, asOpaqueType(id2), key));
+}
+/**
+ * Mock Network implementation for testing
+ * Provides controlled peer connection/disconnection simulation
+ */
+export class MockNetwork {
+    name;
+    _peers = new PeersManagement();
+    constructor(name) {
+        this.name = name;
+        this.peers.onPeerConnected((peer) => {
+            logger.log `(network: ${this.name}) New peer connected: ${peer.id}.`;
+            return OK;
+        });
+        this.peers.onPeerDisconnected((peer) => {
+            logger.log `(network: ${this.name}) Peer disconnected: ${peer.id}.`;
+            return OK;
+        });
+    }
+    get peers() {
+        return this._peers;
+    }
+    async start() {
+        // Mock implementation
+    }
+    async stop() {
+        // Mock implementation
+    }
+    async dial(address, _options) {
+        const peer = createDisconnectedPeer(address.host);
+        this._peers.peerConnected(peer);
+        return peer;
+    }
+}

package/packages/core/numbers/index.d.ts

@@ -0,0 +1,75 @@
+export declare const __REPRESENTATION_BYTES__: unique symbol;
+export type WithBytesRepresentation<Bytes extends number> = {
+    readonly [__REPRESENTATION_BYTES__]: Bytes;
+};
+export type FixedSizeNumber<Bytes extends number> = number & WithBytesRepresentation<Bytes>;
+/** Unsigned integer that can be represented as one byte. */
+export type U8 = FixedSizeNumber<1>;
+/** Unsigned integer that can be represented as two bytes. */
+export type U16 = FixedSizeNumber<2>;
+/** Unsigned integer that can be represented as 4 bytes. */
+export type U32 = FixedSizeNumber<4>;
+/** Unsigned integer that can be represented as 8 bytes. */
+export type U64 = bigint & WithBytesRepresentation<8>;
+/** Attempt to cast an input number into U8. */
+export declare const tryAsU8: (v: number) => U8;
+/** Check if given number is a valid U8 number. */
+export declare const isU8: (v: number) => v is U8;
+/** Attempt to cast an input number into U16. */
+export declare const tryAsU16: (v: number) => U16;
+/** Check if given number is a valid U16 number. */
+export declare const isU16: (v: number) => v is U16;
+/** Attempt to cast an input number into U32. */
+export declare const tryAsU32: (v: number) => U32;
+/** Check if given number is a valid U32 number. */
+export declare const isU32: (v: number) => v is U32;
+/** Attempt to cast an input number into U64. */
+export declare const tryAsU64: (x: number | bigint) => U64;
+/** Check if given number is a valid U64 number. */
+export declare const isU64: (v: bigint) => v is U64;
+/** Collate two U32 parts into one U64. */
+export declare const u64FromParts: ({ lower, upper }: {
+    lower: U32;
+    upper: U32;
+}) => U64;
+/** Split U64 into lower & upper parts. */
+export declare const u64IntoParts: (v: U64) => {
+    lower: U32;
+    upper: U32;
+};
+/** A result of modulo arithmetic. */
+export type Result<T> = {
+    /** Was there an overflow/underflow? */
+    overflow: boolean;
+    /** What's the value after the operation. */
+    value: T;
+};
+/**
+ * Sum all provided U64 values using modulo arithmetic.
+ * NOTE that the overflow may happen multiple times here!
+ */
+export declare function sumU64(...values: U64[]): {
+    overflow: boolean;
+    value: U64;
+};
+/**
+ * Sum all provided U32 values using modulo arithmetic.
+ * NOTE that the overflow may happen multiple times here!
+ */
+export declare function sumU32(...values: U32[]): {
+    overflow: boolean;
+    value: U32;
+};
+/**
+ * Transform provided U32 number to little-endian representation.
+ */
+export declare function u32AsLeBytes(value: U32): Uint8Array;
+/**
+ * Interpret 4-byte `Uint8Array` as U32 written as little endian.
+ */
+export declare function leBytesAsU32(uint8Array: Uint8Array): U32;
+/** Get the smallest value between U64 a and values given as input parameters. */
+export declare const minU64: (a: U64, ...values: U64[]) => U64;
+/** Get the biggest value between U64 a and values given as input parameters. */
+export declare const maxU64: (a: U64, ...values: U64[]) => U64;
+//# sourceMappingURL=index.d.ts.map

package/packages/core/numbers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/numbers/index.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,CAAC,MAAM,wBAAwB,EAAE,OAAO,MAAM,CAAC;AAE7D,MAAM,MAAM,uBAAuB,CAAC,KAAK,SAAS,MAAM,IAAI;IAC1D,QAAQ,CAAC,CAAC,wBAAwB,CAAC,EAAE,KAAK,CAAC;CAC5C,CAAC;AAKF,MAAM,MAAM,eAAe,CAAC,KAAK,SAAS,MAAM,IAAI,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;AAE5F,4DAA4D;AAC5D,MAAM,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AAEpC,6DAA6D;AAC7D,MAAM,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AAErC,2DAA2D;AAC3D,MAAM,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AAErC,2DAA2D;AAC3D,MAAM,MAAM,GAAG,GAAG,MAAM,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAGtD,+CAA+C;AAC/C,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,KAAG,EAGnC,CAAC;AACF,kDAAkD;AAClD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,EAA8B,CAAC;AAErE,gDAAgD;AAChD,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,KAAG,GAGpC,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,GAAgC,CAAC;AAExE,gDAAgD;AAChD,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,KAAG,GAGpC,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,GAAsC,CAAC;AAE9E,gDAAgD;AAChD,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,GAAG,MAAM,KAAG,GAI7C,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,GAAgC,CAAC;AAExE,0CAA0C;AAC1C,eAAO,MAAM,YAAY,GAAI,kBAAkB;IAAE,KAAK,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,KAAG,GAG3E,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,YAAY,GAAI,GAAG,GAAG,KAAG;IAAE,KAAK,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAS7D,CAAC;AAEF,qCAAqC;AACrC,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IACtB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,CAAC,CAAC;CACV,CAAC;AAEF;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE;;;EAWtC;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE;;;EAWtC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,UAAU,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,GAAG,CAGxD;AAED,iFAAiF;AACjF,eAAO,MAAM,MAAM,GAAI,GAAG,GAAG,EAAE,GAAG,QAAQ,GAAG,EAAE,KAAG,GAAoE,CAAC;AAEvH,gFAAgF;AAChF,eAAO,MAAM,MAAM,GAAI,GAAG,GAAG,EAAE,GAAG,QAAQ,GAAG,EAAE,KAAG,GAAoE,CAAC"}

package/packages/core/numbers/index.js

@@ -0,0 +1,94 @@
+import { check } from "#@typeberry/utils";
+const asTypedNumber = (v) => v;
+const MAX_VALUE_U8 = 0xff;
+const MAX_VALUE_U16 = 0xffff;
+const MAX_VALUE_U32 = 0xffff_ffff;
+const MAX_VALUE_U64 = 0xffffffffffffffffn;
+/** Attempt to cast an input number into U8. */
+export const tryAsU8 = (v) => {
+    check `${isU8(v)} input must have one-byte representation, got ${v}`;
+    return asTypedNumber(v);
+};
+/** Check if given number is a valid U8 number. */
+export const isU8 = (v) => (v & MAX_VALUE_U8) === v;
+/** Attempt to cast an input number into U16. */
+export const tryAsU16 = (v) => {
+    check `${isU16(v)} input must have two-byte representation, got ${v}`;
+    return asTypedNumber(v);
+};
+/** Check if given number is a valid U16 number. */
+export const isU16 = (v) => (v & MAX_VALUE_U16) === v;
+/** Attempt to cast an input number into U32. */
+export const tryAsU32 = (v) => {
+    check `${isU32(v)} input must have four-byte representation, got ${v}`;
+    return asTypedNumber(v);
+};
+/** Check if given number is a valid U32 number. */
+export const isU32 = (v) => (v & MAX_VALUE_U32) >>> 0 === v;
+/** Attempt to cast an input number into U64. */
+export const tryAsU64 = (x) => {
+    const v = BigInt(x);
+    check `${isU64(v)} input must have eight-byte representation, got ${x}`;
+    return asTypedNumber(v);
+};
+/** Check if given number is a valid U64 number. */
+export const isU64 = (v) => (v & MAX_VALUE_U64) === v;
+/** Collate two U32 parts into one U64. */
+export const u64FromParts = ({ lower, upper }) => {
+    const val = (BigInt(upper) << 32n) + BigInt(lower);
+    return asTypedNumber(val);
+};
+/** Split U64 into lower & upper parts. */
+export const u64IntoParts = (v) => {
+    // Number(...) safe: both parts are <= 0xffffffff
+    const lower = Number(v & (2n ** 32n - 1n));
+    const upper = Number(v >> 32n);
+    return {
+        lower: asTypedNumber(lower),
+        upper: asTypedNumber(upper),
+    };
+};
+/**
+ * Sum all provided U64 values using modulo arithmetic.
+ * NOTE that the overflow may happen multiple times here!
+ */
+export function sumU64(...values) {
+    let sum = 0n;
+    for (const v of values) {
+        sum = sum + v;
+    }
+    const overflow = !isU64(sum);
+    sum = sum & 0xffffffffffffffffn;
+    return { overflow, value: tryAsU64(sum) };
+}
+/**
+ * Sum all provided U32 values using modulo arithmetic.
+ * NOTE that the overflow may happen multiple times here!
+ */
+export function sumU32(...values) {
+    let sum = 0;
+    let overflow = false;
+    for (const v of values) {
+        const prev = sum;
+        sum = (sum + v) >>> 0;
+        overflow ||= prev > sum;
+    }
+    return { overflow, value: tryAsU32(sum) };
+}
+/**
+ * Transform provided U32 number to little-endian representation.
+ */
+export function u32AsLeBytes(value) {
+    return new Uint8Array([value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff, (value >> 24) & 0xff]);
+}
+/**
+ * Interpret 4-byte `Uint8Array` as U32 written as little endian.
+ */
+export function leBytesAsU32(uint8Array) {
+    check `${uint8Array.length === 4} Input must be a Uint8Array of length 4`;
+    return asTypedNumber(uint8Array[0] | (uint8Array[1] << 8) | (uint8Array[2] << 16) | (uint8Array[3] << 24));
+}
+/** Get the smallest value between U64 a and values given as input parameters. */
+export const minU64 = (a, ...values) => values.reduce((min, value) => (value > min ? min : value), a);
+/** Get the biggest value between U64 a and values given as input parameters. */
+export const maxU64 = (a, ...values) => values.reduce((max, value) => (value < max ? max : value), a);

package/packages/core/numbers/index.test.d.ts

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

package/packages/core/numbers/index.test.d.ts.map

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

package/packages/core/numbers/index.test.js

@@ -0,0 +1,68 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { maxU64, minU64, sumU32, sumU64, tryAsU32, tryAsU64, u32AsLeBytes } from "./index.js";
+describe("sumU32", () => {
+    it("should sum and handle overflow", () => {
+        const res1 = sumU32(tryAsU32(3), tryAsU32(5), tryAsU32(10));
+        const res2 = sumU32(tryAsU32(2 ** 32 - 1), tryAsU32(1));
+        const res3 = sumU32(tryAsU32(2 ** 32 - 1), tryAsU32(2 ** 32 - 1));
+        const res4 = sumU32(tryAsU32(2 ** 32 - 1), tryAsU32(2 ** 32 - 1), tryAsU32(2 ** 32 - 1));
+        assert.deepStrictEqual(res1, { overflow: false, value: tryAsU32(18) });
+        assert.deepStrictEqual(res2, { overflow: true, value: tryAsU32(0) });
+        assert.deepStrictEqual(res3, { overflow: true, value: tryAsU32(2 ** 32 - 2) });
+        assert.deepStrictEqual(res4, { overflow: true, value: tryAsU32(2 ** 32 - 3) });
+    });
+});
+describe("sumU64", () => {
+    it("should sum and handle overflow", () => {
+        const res1 = sumU64(tryAsU64(3), tryAsU64(5), tryAsU64(10));
+        const res2 = sumU64(tryAsU64(2n ** 64n - 1n), tryAsU64(1n));
+        const res3 = sumU64(tryAsU64(2n ** 64n - 1n), tryAsU64(2n ** 64n - 1n));
+        const res4 = sumU64(tryAsU64(2n ** 64n - 1n), tryAsU64(2n ** 64n - 1n), tryAsU64(2n ** 64n - 1n));
+        assert.deepStrictEqual(res1, { overflow: false, value: tryAsU64(18) });
+        assert.deepStrictEqual(res2, { overflow: true, value: tryAsU64(0) });
+        assert.deepStrictEqual(res3, { overflow: true, value: tryAsU64(2n ** 64n - 2n) });
+        assert.deepStrictEqual(res4, { overflow: true, value: tryAsU64(2n ** 64n - 3n) });
+    });
+});
+describe("u32AsLittleEndian", () => {
+    const createTestCase = (value, expectedResult) => ({ value: tryAsU32(value), expectedResult });
+    const testCases = [
+        createTestCase(2 ** 32 - 1, new Uint8Array([0xff, 0xff, 0xff, 0xff])),
+        createTestCase(2147483647, new Uint8Array([0xff, 0xff, 0xff, 0x7f])),
+        createTestCase(5, new Uint8Array([5, 0, 0, 0])),
+        createTestCase(0, new Uint8Array([0, 0, 0, 0])),
+    ];
+    for (const { value, expectedResult } of testCases) {
+        it(`should return little endian representation of ${value}`, () => {
+            const result = u32AsLeBytes(value);
+            assert.deepStrictEqual(result, expectedResult);
+        });
+    }
+});
+describe("tryAsU32", () => {
+    it("should cast numbers", () => {
+        const v = 1234;
+        assert.deepStrictEqual(tryAsU32(v), 1234);
+    });
+    it("should throw if value exceeds u32", () => {
+        const v = 2 ** 32;
+        assert.throws(() => tryAsU32(v), `input must have four-byte representation, got ${v}`);
+    });
+});
+describe("minU64", () => {
+    it("should return minimal value", () => {
+        const minimal = tryAsU64(1n);
+        const middle = tryAsU64(2n ** 16n + 48n);
+        const maximal = tryAsU64(2n ** 64n - 1n);
+        assert.deepStrictEqual(minU64(middle, maximal, minimal), minimal);
+    });
+});
+describe("maxU64", () => {
+    it("should return maximal value", () => {
+        const minimal = tryAsU64(1n);
+        const middle = tryAsU64(2n ** 16n + 48n);
+        const maximal = tryAsU64(2n ** 64n - 1n);
+        assert.deepStrictEqual(maxU64(middle, maximal, minimal), maximal);
+    });
+});

package/packages/core/ordering/index.d.ts

@@ -0,0 +1,30 @@
+/** A return value of some comparator. */
+export declare enum OrderingValue {
+    /** `self < other` */
+    Less = -1,
+    /** `self === other` */
+    Equal = 0,
+    /** `self > other` */
+    Greater = 1
+}
+/** A class that provides utility methods to check the type of ordering. */
+export declare class Ordering {
+    readonly value: OrderingValue;
+    private constructor();
+    static Less: Ordering;
+    static Greater: Ordering;
+    static Equal: Ordering;
+    isLess(): boolean;
+    isGreater(): boolean;
+    isEqual(): boolean;
+    isNotEqual(): boolean;
+    isGreaterOrEqual(): boolean;
+    isLessOrEqual(): boolean;
+}
+/**
+ * A type that compares the `self` value to `other` and returns an ordering in respect to `self`.
+ *
+ * e.g. `self < other => Ordering.Less`, `self > other => Ordering.Greater`
+ */
+export type Comparator<V> = (self: V, other: V) => Ordering;
+//# sourceMappingURL=index.d.ts.map

package/packages/core/ordering/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/ordering/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oBAAY,aAAa;IACvB,qBAAqB;IACrB,IAAI,KAAK;IACT,uBAAuB;IACvB,KAAK,IAAI;IACT,qBAAqB;IACrB,OAAO,IAAI;CACZ;AAED,2EAA2E;AAC3E,qBAAa,QAAQ;aACiB,KAAK,EAAE,aAAa;IAAxD,OAAO;IAEP,MAAM,CAAC,IAAI,WAAoC;IAC/C,MAAM,CAAC,OAAO,WAAuC;IACrD,MAAM,CAAC,KAAK,WAAqC;IAEjD,MAAM;IAIN,SAAS;IAIT,OAAO;IAIP,UAAU;IAIV,gBAAgB;IAIhB,aAAa;CAGd;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,QAAQ,CAAC"}

package/packages/core/ordering/index.js

@@ -0,0 +1,38 @@
+/** A return value of some comparator. */
+export var OrderingValue;
+(function (OrderingValue) {
+    /** `self < other` */
+    OrderingValue[OrderingValue["Less"] = -1] = "Less";
+    /** `self === other` */
+    OrderingValue[OrderingValue["Equal"] = 0] = "Equal";
+    /** `self > other` */
+    OrderingValue[OrderingValue["Greater"] = 1] = "Greater";
+})(OrderingValue || (OrderingValue = {}));
+/** A class that provides utility methods to check the type of ordering. */
+export class Ordering {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    static Less = new Ordering(OrderingValue.Less);
+    static Greater = new Ordering(OrderingValue.Greater);
+    static Equal = new Ordering(OrderingValue.Equal);
+    isLess() {
+        return this.value === OrderingValue.Less;
+    }
+    isGreater() {
+        return this.value === OrderingValue.Greater;
+    }
+    isEqual() {
+        return this.value === OrderingValue.Equal;
+    }
+    isNotEqual() {
+        return !this.isEqual();
+    }
+    isGreaterOrEqual() {
+        return this.isEqual() || this.isGreater();
+    }
+    isLessOrEqual() {
+        return this.isEqual() || this.isLess();
+    }
+}

package/packages/core/pvm-host-calls/bin.d.ts

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

package/packages/core/pvm-host-calls/bin.d.ts.map

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

package/packages/core/pvm-host-calls/bin.js

@@ -0,0 +1,27 @@
+import { PvmBackend } from "#@typeberry/config";
+import { tryAsGas } from "#@typeberry/pvm-interface";
+import { HostCalls } from "./host-calls.js";
+import { HostCallsManager, NoopMissing } from "./host-calls-manager.js";
+import { InterpreterInstanceManager } from "./interpreter-instance-manager.js";
+const hostCalls = new HostCallsManager({ missing: new NoopMissing(), handlers: [] });
+const pvmInstanceManager = await InterpreterInstanceManager.new(PvmBackend.BuiltIn);
+const pvmHostCallExtension = new HostCalls(pvmInstanceManager, hostCalls);
+const program = new Uint8Array([
+    0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x10, 0x1, 0x0, 0x0, 0xf9, 0x0, 0x0, 0x0, 0x0, 0x0, 0x80, 0xd9, 0x5, 0x12,
+    0x0, 0x0, 0x0, 0x5, 0x11, 0x0, 0x0, 0x0, 0x5, 0xa3, 0x0, 0x0, 0x0, 0x5, 0xc6, 0x0, 0x4, 0x7, 0x13, 0x0, 0x2, 0x11,
+    0xa4, 0x3, 0x10, 0x58, 0x3, 0x15, 0x54, 0x3, 0x16, 0x50, 0xd, 0x11, 0x1c, 0xd, 0x11, 0x18, 0xd, 0x11, 0x14, 0xd, 0x11,
+    0x10, 0xd, 0x11, 0xc, 0xd, 0x11, 0x8, 0xd, 0x11, 0x4, 0xd, 0x1, 0xd, 0x11, 0x3c, 0xd, 0x11, 0x38, 0xd, 0x11, 0x34,
+    0xd, 0x11, 0x30, 0xd, 0x11, 0x2c, 0xd, 0x11, 0x28, 0xd, 0x11, 0x24, 0xd, 0x11, 0x20, 0xd, 0x11, 0x40, 0x52, 0x18, 0x4,
+    0x9, 0x20, 0x2, 0x1a, 0x40, 0x4, 0xb, 0x4, 0x4, 0x7, 0x4e, 0x2, 0x1, 0x15, 0x40, 0xd, 0x11, 0x44, 0x2, 0x18, 0x20,
+    0x4, 0x9, 0x20, 0x2, 0x1a, 0x44, 0x4, 0xb, 0x4, 0x4, 0x7, 0x4e, 0x2, 0x1, 0x16, 0x44, 0x3, 0x15, 0x48, 0x52, 0x17,
+    0x4, 0x8, 0x20, 0x2, 0x19, 0x48, 0x4, 0xa, 0x4, 0x4e, 0x3, 0x3, 0x16, 0x4c, 0x2, 0x17, 0x20, 0x4, 0x8, 0x20, 0x2,
+    0x19, 0x4c, 0x4, 0xa, 0x4, 0x4e, 0x3, 0x4, 0x7, 0x1, 0x10, 0x58, 0x1, 0x15, 0x54, 0x1, 0x16, 0x50, 0x2, 0x11, 0x5c,
+    0x13, 0x0, 0x2, 0x11, 0xec, 0x3, 0x10, 0x10, 0xd, 0x11, 0x8, 0xd, 0x11, 0x4, 0xd, 0x1, 0x1a, 0x11, 0xf, 0x2, 0x17,
+    0xf, 0x4, 0x8, 0x1, 0x52, 0x19, 0x4, 0xa, 0xc, 0x4e, 0x3, 0x4, 0x7, 0x1, 0x10, 0x10, 0x2, 0x11, 0x14, 0x13, 0x0, 0x4,
+    0x7, 0x13, 0x0, 0x21, 0x84, 0x54, 0x92, 0x24, 0x49, 0x92, 0x92, 0x24, 0x49, 0x52, 0x92, 0x4a, 0x92, 0xa4, 0x92, 0x92,
+    0x94, 0x24, 0xa9, 0x24, 0x29, 0x49, 0x4a, 0x52, 0x2a, 0xa9, 0x0,
+]);
+const args = new Uint8Array();
+(async () => {
+    await pvmHostCallExtension.runProgram(program, args, 5, tryAsGas(1000));
+})();

package/packages/core/pvm-host-calls/host-call-handler.d.ts

@@ -0,0 +1,44 @@
+import { type U32 } from "#@typeberry/numbers";
+import type { Gas, IGasCounter, SmallGas } from "#@typeberry/pvm-interface";
+import { type RegisterIndex } from "#@typeberry/pvm-interpreter/registers.js";
+import { type Opaque } from "#@typeberry/utils";
+import type { HostCallMemory } from "./host-call-memory.js";
+import type { HostCallRegisters } from "./host-call-registers.js";
+/** Strictly-typed host call index. */
+export type HostCallIndex = Opaque<U32, "HostCallIndex[U32]">;
+/** Attempt to convert a number into `HostCallIndex`. */
+export declare const tryAsHostCallIndex: (v: number) => HostCallIndex;
+/**
+ * Host-call exit reason.
+ *
+ * https://graypaper.fluffylabs.dev/#/ab2cdbd/24a30124a501?v=0.7.2
+ */
+export declare enum PvmExecution {
+    Halt = 0,
+    Panic = 1,
+    OOG = 2
+}
+/** A utility function to easily trace a bunch of registers. */
+export declare function traceRegisters(...regs: number[]): (number & import("@typeberry/utils").WithOpaque<"register index">)[];
+/** An interface for a host call implementation */
+export interface HostCallHandler {
+    /** Index of that host call (i.e. what PVM invokes via `ecalli`) */
+    readonly index: HostCallIndex;
+    /**
+     * The gas cost of invocation of that host call.
+     *
+     * NOTE: `((reg: HostCallRegisters) => Gas)` function is for compatibility reasons: pre GP 0.7.2
+     */
+    readonly basicGasCost: SmallGas | ((reg: HostCallRegisters) => Gas);
+    /** Currently executing service id. */
+    readonly currentServiceId: U32;
+    /** Input&Output registers that we should add to tracing log. */
+    readonly tracedRegisters: RegisterIndex[];
+    /**
+     * Actually execute the host call.
+     *
+     * NOTE the call is ALLOWED and expected to modify registers and memory.
+     */
+    execute(gas: IGasCounter, regs: HostCallRegisters, memory: HostCallMemory): Promise<undefined | PvmExecution>;
+}
+//# sourceMappingURL=host-call-handler.d.ts.map

package/packages/core/pvm-host-calls/host-call-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-call-handler.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-call-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,yCAAyC,CAAC;AACjG,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,sCAAsC;AACtC,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;AAC9D,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,GAAG,MAAM,KAAG,aAA0C,CAAC;AAE1F;;;;GAIG;AACH,oBAAY,YAAY;IACtB,IAAI,IAAI;IACR,KAAK,IAAI;IACT,GAAG,IAAI;CACR;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,wEAE/C;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,GAAG,CAAC,CAAC,GAAG,EAAE,iBAAiB,KAAK,GAAG,CAAC,CAAC;IAEpE,sCAAsC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC;IAE/B,gEAAgE;IAChE,QAAQ,CAAC,eAAe,EAAE,aAAa,EAAE,CAAC;IAE1C;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,GAAG,YAAY,CAAC,CAAC;CAC/G"}

package/packages/core/pvm-host-calls/host-call-handler.js

@@ -0,0 +1,20 @@
+import { tryAsU32 } from "#@typeberry/numbers";
+import { tryAsRegisterIndex } from "#@typeberry/pvm-interpreter/registers.js";
+import { asOpaqueType } from "#@typeberry/utils";
+/** Attempt to convert a number into `HostCallIndex`. */
+export const tryAsHostCallIndex = (v) => asOpaqueType(tryAsU32(v));
+/**
+ * Host-call exit reason.
+ *
+ * https://graypaper.fluffylabs.dev/#/ab2cdbd/24a30124a501?v=0.7.2
+ */
+export var PvmExecution;
+(function (PvmExecution) {
+    PvmExecution[PvmExecution["Halt"] = 0] = "Halt";
+    PvmExecution[PvmExecution["Panic"] = 1] = "Panic";
+    PvmExecution[PvmExecution["OOG"] = 2] = "OOG";
+})(PvmExecution || (PvmExecution = {}));
+/** A utility function to easily trace a bunch of registers. */
+export function traceRegisters(...regs) {
+    return regs.map(tryAsRegisterIndex);
+}

package/packages/core/pvm-host-calls/host-call-memory.d.ts

@@ -0,0 +1,22 @@
+import { type U64 } from "#@typeberry/numbers";
+import type { IMemory, PageFault } from "#@typeberry/pvm-interface";
+import { OK, Result } from "#@typeberry/utils";
+export declare class HostCallMemory {
+    private readonly memory;
+    constructor(memory: IMemory);
+    /**
+     * Save some bytes into memory under given address.
+     *
+     * NOTE: Given address is U64 (pure register value),
+     * but we use only lower 32-bits.
+     */
+    storeFrom(regAddress: U64, bytes: Uint8Array): Result<OK, PageFault>;
+    /**
+     * Read some bytes from memory under given address.
+     *
+     * NOTE: Given address is U64 (pure register value),
+     * but we use only lower 32-bits.
+     */
+    loadInto(output: Uint8Array, regAddress: U64): Result<OK, PageFault>;
+}
+//# sourceMappingURL=host-call-memory.d.ts.map

package/packages/core/pvm-host-calls/host-call-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-call-memory.d.ts","sourceRoot":"","sources":["../../../../../packages/core/pvm-host-calls/host-call-memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE9C,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,OAAO;IAE5C;;;;;OAKG;IACH,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;IAYpE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,GAAG,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC;CAWrE"}