@typeberry/lib 0.5.1-aff8b4f → 0.5.1-eb84786

package/packages/core/networking/crypto.d.ts

@@ -0,0 +1,15 @@
+import type { QUICClientCrypto, QUICServerCrypto } from "@matrixai/quic";
+import { type Ed25519Pair } from "#@typeberry/crypto";
+/**
+ * Crypto utilitiy functions required by the QUIC server.
+ *
+ * Implements `ed25519` signing and verification and presents the server key.
+ */
+export declare function getQuicServerCrypto(pair: Ed25519Pair): QUICServerCrypto;
+/**
+ * Crypto utilities functions required by the QUIC client.
+ *
+ * We just need to be able to get crypto-secure random bytes.
+ */
+export declare function getQuicClientCrypto(): QUICClientCrypto;
+//# sourceMappingURL=crypto.d.ts.map

package/packages/core/networking/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/crypto.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAA8C,KAAK,WAAW,EAAW,MAAM,mBAAmB,CAAC;AAE1G;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAsBvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAQtD"}

package/packages/core/networking/crypto.js

@@ -0,0 +1,54 @@
+import { webcrypto } from "node:crypto";
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { ED25519_KEY_BYTES, ED25519_SIGNATURE_BYTES, ed25519 } from "#@typeberry/crypto";
+/**
+ * Crypto utilitiy functions required by the QUIC server.
+ *
+ * Implements `ed25519` signing and verification and presents the server key.
+ */
+export function getQuicServerCrypto(pair) {
+    return {
+        key: toArrayBuffer(pair._privKey.raw),
+        ops: {
+            async sign(privKey, data) {
+                const key = await ed25519.privateKey(Bytes.fromBlob(new Uint8Array(privKey), ED25519_KEY_BYTES).asOpaque());
+                const sig = await ed25519.sign(key, BytesBlob.blobFrom(new Uint8Array(data)));
+                return toArrayBuffer(sig.raw);
+            },
+            async verify(privKey, data, signature) {
+                const key = await ed25519.privateKey(Bytes.fromBlob(new Uint8Array(privKey), ED25519_KEY_BYTES).asOpaque());
+                const res = await ed25519.verify([
+                    {
+                        signature: Bytes.fromBlob(new Uint8Array(signature), ED25519_SIGNATURE_BYTES).asOpaque(),
+                        key: key.pubKey,
+                        message: BytesBlob.blobFrom(new Uint8Array(data)),
+                    },
+                ]);
+                return res[0];
+            },
+        },
+    };
+}
+/**
+ * Crypto utilities functions required by the QUIC client.
+ *
+ * We just need to be able to get crypto-secure random bytes.
+ */
+export function getQuicClientCrypto() {
+    return {
+        ops: {
+            async randomBytes(data) {
+                webcrypto.getRandomValues(new Uint8Array(data));
+            },
+        },
+    };
+}
+function toArrayBuffer(data) {
+    if (data.buffer instanceof ArrayBuffer) {
+        return data.buffer.slice(data.byteOffset, data.byteOffset + data.length);
+    }
+    const buffer = new ArrayBuffer(data.length);
+    const copy = new Uint8Array(buffer);
+    copy.set(data, 0);
+    return buffer;
+}

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

@@ -0,0 +1,7 @@
+export { altNameRaw } from "./certificate.js";
+export * from "./message.js";
+export * from "./metrics.js";
+export * from "./network.js";
+export * from "./peers.js";
+export * from "./setup.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/packages/core/networking/index.js

@@ -0,0 +1,6 @@
+export { altNameRaw } from "./certificate.js";
+export * from "./message.js";
+export * from "./metrics.js";
+export * from "./network.js";
+export * from "./peers.js";
+export * from "./setup.js";

package/packages/core/networking/message.d.ts

@@ -0,0 +1,11 @@
+export declare const MSG_LEN_PREFIX_BYTES = 4;
+/** Encode message length into a buffer. */
+export declare function encodeMessageLength(message: Uint8Array): Uint8Array<ArrayBufferLike>;
+/**
+ * Only triggers the `callback` in case full data blob is received.
+ *
+ * Each message should be prefixed with a single U32 denoting the length of the next data
+ * frame that should be interpreted as single chunk.
+ */
+export declare function handleMessageFragmentation(callback: (data: Uint8Array) => void, onOverflow: () => void): (data: Uint8Array) => void;
+//# sourceMappingURL=message.d.ts.map

package/packages/core/networking/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/message.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAItC,2CAA2C;AAC3C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,+BAEtD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,EACpC,UAAU,EAAE,MAAM,IAAI,GACrB,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAmC5B"}

package/packages/core/networking/message.js

@@ -0,0 +1,45 @@
+import { Buffer } from "node:buffer";
+import { tryAsU32, u32AsLeBytes } from "#@typeberry/numbers";
+export const MSG_LEN_PREFIX_BYTES = 4;
+const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
+/** Encode message length into a buffer. */
+export function encodeMessageLength(message) {
+    return u32AsLeBytes(tryAsU32(message.length));
+}
+/**
+ * Only triggers the `callback` in case full data blob is received.
+ *
+ * Each message should be prefixed with a single U32 denoting the length of the next data
+ * frame that should be interpreted as single chunk.
+ */
+export function handleMessageFragmentation(callback, onOverflow) {
+    let buffer = Buffer.alloc(0);
+    let expectedLength = -1;
+    return (data) => {
+        buffer = Buffer.concat([buffer, data]);
+        do {
+            // we now expect a length prefix.
+            if (expectedLength === -1) {
+                // not enough data to parse the length, wait for more.
+                if (buffer.length < MSG_LEN_PREFIX_BYTES) {
+                    break;
+                }
+                expectedLength = buffer.readUint32LE();
+                buffer = buffer.subarray(MSG_LEN_PREFIX_BYTES);
+            }
+            // we don't have enough data, so let's wait.
+            if (buffer.length < expectedLength) {
+                break;
+            }
+            if (buffer.length > MAX_MESSAGE_BYTES) {
+                onOverflow();
+                break;
+            }
+            // full chunk can be parsed now, but there might be some more.
+            const chunk = buffer.subarray(0, expectedLength);
+            buffer = buffer.subarray(expectedLength);
+            expectedLength = -1;
+            callback(new Uint8Array(chunk));
+        } while (buffer.length > 0);
+    };
+}

package/packages/core/networking/message.test.d.ts

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

package/packages/core/networking/message.test.d.ts.map

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

package/packages/core/networking/message.test.js

@@ -0,0 +1,88 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { encodeMessageLength, handleMessageFragmentation, MSG_LEN_PREFIX_BYTES } from "./message.js";
+describe("encodeMessageLength", () => {
+    it("should encode message length for normal message", () => {
+        const message = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+        const result = encodeMessageLength(message);
+        assert.strictEqual(result.length, MSG_LEN_PREFIX_BYTES);
+        assert.strictEqual(result[0], 4); // length = 4 in little endian
+        assert.strictEqual(result[1], 0);
+        assert.strictEqual(result[2], 0);
+        assert.strictEqual(result[3], 0);
+    });
+    it("should encode message length for empty message", () => {
+        const message = new Uint8Array([]);
+        const result = encodeMessageLength(message);
+        assert.strictEqual(result.length, MSG_LEN_PREFIX_BYTES);
+        assert.strictEqual(result[0], 0); // length = 0
+        assert.strictEqual(result[1], 0);
+        assert.strictEqual(result[2], 0);
+        assert.strictEqual(result[3], 0);
+    });
+});
+describe("handleMessageFragmentation", () => {
+    it("should handle complete message received at once", () => {
+        const receivedMessages = [];
+        const handler = handleMessageFragmentation((data) => {
+            receivedMessages.push(data);
+        }, () => { });
+        const message = new Uint8Array([0x01, 0x02, 0x03]);
+        const lengthPrefix = new Uint8Array([3, 0, 0, 0]); // length = 3 in little endian
+        const completeFrame = new Uint8Array([...lengthPrefix, ...message]);
+        handler(completeFrame);
+        assert.strictEqual(receivedMessages.length, 1);
+        assert.deepStrictEqual(receivedMessages[0], message);
+    });
+    it("should handle message received in fragments", () => {
+        const receivedMessages = [];
+        const handler = handleMessageFragmentation((data) => {
+            receivedMessages.push(data);
+        }, () => { });
+        const message = new Uint8Array([0x01, 0x02, 0x03]);
+        const lengthPrefix = new Uint8Array([3, 0, 0, 0]); // length = 3 in little endian
+        // Send length prefix first
+        handler(lengthPrefix.subarray(0, 2));
+        assert.strictEqual(receivedMessages.length, 0);
+        // Complete length prefix
+        handler(lengthPrefix.subarray(2));
+        assert.strictEqual(receivedMessages.length, 0);
+        // Send partial message
+        handler(message.subarray(0, 1));
+        assert.strictEqual(receivedMessages.length, 0);
+        // Complete message
+        handler(message.subarray(1));
+        assert.strictEqual(receivedMessages.length, 1);
+        assert.deepStrictEqual(receivedMessages[0], message);
+    });
+    it("should handle multiple consecutive messages", () => {
+        const receivedMessages = [];
+        const handler = handleMessageFragmentation((data) => {
+            receivedMessages.push(data);
+        }, () => { });
+        const message1 = new Uint8Array([0x01, 0x02]);
+        const message2 = new Uint8Array([0x03, 0x04, 0x05]);
+        const lengthPrefix1 = new Uint8Array([2, 0, 0, 0]); // length = 2
+        const lengthPrefix2 = new Uint8Array([3, 0, 0, 0]); // length = 3
+        const combinedFrame = new Uint8Array([...lengthPrefix1, ...message1, ...lengthPrefix2, ...message2]);
+        handler(combinedFrame);
+        assert.strictEqual(receivedMessages.length, 2);
+        assert.deepStrictEqual(receivedMessages[0], message1);
+        assert.deepStrictEqual(receivedMessages[1], message2);
+    });
+    it("should reject if message is too big", () => {
+        const receivedMessages = [];
+        let overflowCalled = false;
+        const handler = handleMessageFragmentation((data) => {
+            receivedMessages.push(data);
+        }, () => {
+            overflowCalled = true;
+        });
+        const message1 = new Uint8Array(16 * 1024 * 1024 + 1);
+        const lengthPrefix1 = new Uint8Array([0, 0, 0, 1]);
+        const combinedFrame = new Uint8Array([...lengthPrefix1, ...message1]);
+        handler(combinedFrame);
+        assert.deepStrictEqual(receivedMessages, []);
+        assert.strictEqual(overflowCalled, true);
+    });
+});

package/packages/core/networking/metrics.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Network metrics for JAM implementation.
+ *
+ * https://github.com/polkadot-fellows/JIPs/blob/main/JIP-3.md#networking-events
+ */
+export declare function createMetrics(): {
+    recordConnectionRefused(peerAddress: string): void;
+    recordConnectingIn(peerAddress: string): void;
+    recordConnectInFailed(reason: string): void;
+    recordConnectedIn(peerId: string): void;
+    recordConnectingOut(peerId: string, peerAddress: string): void;
+    recordConnectOutFailed(reason: string): void;
+    recordConnectedOut(peerId: string): void;
+    recordDisconnected(peerId: string, side: "in" | "out", reason: string, durationMs: number): void;
+    recordPeerMisbehaved(peerId: string, reason: string): void;
+};
+//# sourceMappingURL=metrics.d.ts.map

package/packages/core/networking/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/metrics.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,wBAAgB,aAAa;yCAiEY,MAAM,GAAG,IAAI;oCAIlB,MAAM,GAAG,IAAI;kCAIf,MAAM,GAAG,IAAI;8BAIjB,MAAM,GAAG,IAAI;gCAIX,MAAM,eAAe,MAAM,GAAG,IAAI;mCAI/B,MAAM,GAAG,IAAI;+BAIjB,MAAM,GAAG,IAAI;+BAIb,MAAM,QAAQ,IAAI,GAAG,KAAK,UAAU,MAAM,cAAc,MAAM,GAAG,IAAI;iCAKnE,MAAM,UAAU,MAAM,GAAG,IAAI;EAI7D"}

package/packages/core/networking/metrics.js

@@ -0,0 +1,90 @@
+import { metrics } from "@opentelemetry/api";
+import packageJson from "./package.json" with { type: "json" };
+/**
+ * Network metrics for JAM implementation.
+ *
+ * https://github.com/polkadot-fellows/JIPs/blob/main/JIP-3.md#networking-events
+ */
+export function createMetrics() {
+    const meter = metrics.getMeter(packageJson.name, packageJson.version);
+    const connectionDuration = meter.createHistogram("jam.connectionTime", {
+        description: "Duration of connection to another peer",
+        unit: "ms",
+    });
+    // JIP
+    // 20
+    const connectionRefusedCounter = meter.createCounter("jam.jip3.connection_refused", {
+        description: "Connection refused events",
+        unit: "events",
+    });
+    // 21
+    const connectingInCounter = meter.createCounter("jam.jip3.connecting_in", {
+        description: "Inbound connection attempts",
+        unit: "events",
+    });
+    // 22
+    const connectInFailedCounter = meter.createCounter("jam.jip3.connect_in_failed", {
+        description: "Inbound connection failures",
+        unit: "errors",
+    });
+    // 23
+    const connectedInCounter = meter.createCounter("jam.jip3.connected_in", {
+        description: "Successful inbound connections",
+        unit: "connections",
+    });
+    // 24
+    const connectingOutCounter = meter.createCounter("jam.jip3.connecting_out", {
+        description: "Outbound connection attempts",
+        unit: "events",
+    });
+    // 25
+    const connectOutFailedCounter = meter.createCounter("jam.jip3.connect_out_failed", {
+        description: "Outbound connection failures",
+        unit: "errors",
+    });
+    // 26
+    const connectedOutCounter = meter.createCounter("jam.jip3.connected_out", {
+        description: "Successful outbound connections",
+        unit: "connections",
+    });
+    // 27
+    const disconnectedCounter = meter.createCounter("jam.jip3.disconnected", {
+        description: "Disconnection events",
+        unit: "events",
+    });
+    // 28
+    const peerMisbehavedCounter = meter.createCounter("jam.jip3.peer_misbehaved", {
+        description: "Peer misbehavior events",
+        unit: "events",
+    });
+    return {
+        recordConnectionRefused(peerAddress) {
+            connectionRefusedCounter.add(1, { peer_address: peerAddress });
+        },
+        recordConnectingIn(peerAddress) {
+            connectingInCounter.add(1, { peer_address: peerAddress });
+        },
+        recordConnectInFailed(reason) {
+            connectInFailedCounter.add(1, { reason });
+        },
+        recordConnectedIn(peerId) {
+            connectedInCounter.add(1, { peer_id: peerId });
+        },
+        recordConnectingOut(peerId, peerAddress) {
+            connectingOutCounter.add(1, { peer_id: peerId, peer_address: peerAddress });
+        },
+        recordConnectOutFailed(reason) {
+            connectOutFailedCounter.add(1, { reason });
+        },
+        recordConnectedOut(peerId) {
+            connectedOutCounter.add(1, { peer_id: peerId });
+        },
+        recordDisconnected(peerId, side, reason, durationMs) {
+            disconnectedCounter.add(1, { peer_id: peerId, side, reason });
+            connectionDuration.record(durationMs, { side });
+        },
+        recordPeerMisbehaved(peerId, reason) {
+            peerMisbehavedCounter.add(1, { peer_id: peerId, reason });
+        },
+    };
+}

package/packages/core/networking/network.d.ts

@@ -0,0 +1,20 @@
+import type { Peer, PeerAddress, Peers } from "./peers.js";
+/** Peer dialing options. */
+export type DialOptions = {
+    /** Verify the expected peer name after connection. */
+    verifyName?: string;
+    /** Abort connection on demand. */
+    signal?: AbortSignal;
+};
+/** Networking abstraction. */
+export interface Network<T extends Peer> {
+    /** Peers management. */
+    peers: Peers<T>;
+    /** Start networking interface. */
+    start(): Promise<void>;
+    /** Stop networking interface and terminate existing connections. */
+    stop(): Promise<void>;
+    /** Initiate a new connection to some peer. */
+    dial(address: PeerAddress, options: DialOptions): Promise<T>;
+}
+//# sourceMappingURL=network.d.ts.map

package/packages/core/networking/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE3D,4BAA4B;AAC5B,MAAM,MAAM,WAAW,GAAG;IACxB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,8BAA8B;AAC9B,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,IAAI;IACrC,wBAAwB;IACxB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAEhB,kCAAkC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,oEAAoE;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,8CAA8C;IAC9C,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9D"}

package/packages/core/networking/network.js

@@ -0,0 +1 @@
+export {};

package/packages/core/networking/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "@typeberry/networking",
+    "version": "0.5.1",
+    "description": "QUIC-based p2p networking.",
+    "license": "MPL-2.0",
+    "author": "Fluffy Labs",
+    "bin": "./bin/test.ts",
+    "main": "index.ts",
+    "type": "module",
+    "scripts": {
+        "start": "tsx ./bin/test.ts",
+        "test": "tsx --test $(find . -type f -name '*.test.ts' | tr '\\n' ' ')"
+    },
+    "dependencies": {
+        "@matrixai/quic": "2.0.9",
+        "@opentelemetry/api": "1.9.0",
+        "@peculiar/webcrypto": "1.5.0",
+        "@peculiar/x509": "1.12.3",
+        "@typeberry/bytes": "*",
+        "@typeberry/config": "*",
+        "@typeberry/crypto": "*",
+        "@typeberry/logger": "*",
+        "@typeberry/numbers": "*",
+        "@typeberry/utils": "*"
+    }
+}

package/packages/core/networking/peer-verification.d.ts

@@ -0,0 +1,10 @@
+import { native } from "@matrixai/quic";
+import { type PeerInfo, VerifyCertError } from "./certificate.js";
+export declare function peerVerification(): {
+    info: PeerInfo | null;
+    /** Takes all certicates the peer presented and all local certifcates from Certificate Authorities (unused) */
+    verifyCallback: (certs: Uint8Array[], cas: Uint8Array[]) => Promise<ReturnType<typeof asCryptoError> | undefined>;
+};
+declare function asCryptoError(error: VerifyCertError | undefined): native.CryptoError.BadCertificate | native.CryptoError.IllegalParameter | native.CryptoError.InsufficientSecurity | native.CryptoError.CertificateRequired | undefined;
+export {};
+//# sourceMappingURL=peer-verification.d.ts.map

package/packages/core/networking/peer-verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-verification.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/peer-verification.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,KAAK,QAAQ,EAAE,eAAe,EAAqB,MAAM,kBAAkB,CAAC;AAErF,wBAAgB,gBAAgB;UAEtB,QAAQ,GAAG,IAAI;IACrB,8GAA8G;oBAC9F,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,SAAS,CAAC;EAapH;AAED,iBAAS,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,0KAkBxD"}

package/packages/core/networking/peer-verification.js

@@ -0,0 +1,35 @@
+import { native } from "@matrixai/quic";
+import { VerifyCertError, verifyCertificate } from "./certificate.js";
+export function peerVerification() {
+    const peer = {
+        info: null,
+        verifyCallback: async (certs, _cas) => {
+            const verification = await verifyCertificate(certs);
+            if (verification.isError) {
+                return asCryptoError(verification.error);
+            }
+            peer.info = verification.ok;
+            return undefined;
+        },
+    };
+    return peer;
+}
+function asCryptoError(error) {
+    if (error === undefined) {
+        return error;
+    }
+    switch (error) {
+        case VerifyCertError.AltNameMismatch:
+            return native.CryptoError.IllegalParameter;
+        case VerifyCertError.NotEd25519:
+            return native.CryptoError.InsufficientSecurity;
+        case VerifyCertError.PublicKeyTypeMismatch:
+            return native.CryptoError.BadCertificate;
+        case VerifyCertError.NoCertificate:
+            return native.CryptoError.CertificateRequired;
+        case VerifyCertError.IncorrectSignature:
+            return native.CryptoError.BadCertificate;
+        default:
+            throw new Error(`Unexpected VerifyCertError: ${error}`);
+    }
+}

package/packages/core/networking/peers.d.ts

@@ -0,0 +1,95 @@
+import type { ReadableWritablePair } from "node:stream/web";
+import type { PeerAddress, PeerId } from "#@typeberry/config";
+import type { Ed25519Key } from "#@typeberry/crypto";
+import type { OK } from "#@typeberry/utils";
+export type { PeerAddress, PeerId } from "#@typeberry/config";
+/**
+ * Error callback maybe be triggered multiple times.
+ *
+ * In case of an exception result we will usually see a sequence of:
+ * 1. Exception
+ * 2. LocalClose (since we detected exception and want to close connection)
+ * 3. RemoteClose (since the remote peer detected the exceptional behavior as well)
+ *
+ * However in case of clean disconnects, we may see just local close or remote close
+ * first in case it was either us or them closing the connection.
+ *
+ * `LocalClose` is also trigerred mutliple times (readable stream, writeable stream,
+ * connection). If that's too much, we can tone it down in the future.
+ */
+export declare enum StreamErrorKind {
+    /** An error or closing event that originates locally. */
+    LocalClose = 0,
+    /** Remote peer triggering close event. */
+    RemoteClose = 1,
+    /** Some exceptional behavior on the stream. */
+    Exception = 2
+}
+/** The callback that should be triggered when an error/close on stream occurs. */
+export type StreamErrorCallback = (e: unknown, kind: StreamErrorKind) => void;
+/** Communication stream. */
+export interface Stream extends ReadableWritablePair<Uint8Array, Uint8Array> {
+    /** Add a callback to be notified about stream errors. */
+    addOnError(onError: StreamErrorCallback): void;
+    /** Unique stream identifier. */
+    streamId: number;
+    /** Destroy the stream. */
+    destroy(): Promise<void>;
+}
+/** Peer interface. */
+export interface Peer {
+    /** ID unique per connection. */
+    connectionId: string;
+    /** Connection address. */
+    address: PeerAddress;
+    /** Peer id (alpn of the cert). */
+    id: PeerId;
+    /** Peer's public key. */
+    key: Ed25519Key;
+    /** Add a handler for when others open new streams with us. */
+    addOnIncomingStream(streamCallback: StreamCallback): void;
+    /** Initiate a new stream. */
+    openStream(): Stream;
+    /** Close the connection to that peer. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Function called when a new stream is opened.
+ *
+ * NOTE: the callbacks are required to return `OK` to indicate,
+ * that any asynchronous work has to be handled separately
+ * with all possible exceptions handled.
+ */
+export type StreamCallback<S extends Stream = Stream> = (onStream: S) => OK;
+/**
+ * Function called when a new peer is connected or disconnected.
+ *
+ * NOTE the callbacks are required to return `OK` to indicate,
+ * that any asynchronous work has to be handled separately
+ * with all possible exceptions handled.
+ */
+export type PeerCallback<T extends Peer> = (onPeer: T) => OK;
+type Unsubscribe = () => void;
+export interface Peers<T extends Peer> {
+    /** Check that peer with given id is currently connected. */
+    isConnected(id: PeerId): boolean;
+    /** Get number of connected peers. */
+    noOfConnectedPeers(): number;
+    /** Add a callback triggered every time new peers is connected. */
+    onPeerConnected(cb: PeerCallback<T>): Unsubscribe;
+    /** Add a callback triggered every time a peer is disconnected. */
+    onPeerDisconnected(cb: PeerCallback<T>): Unsubscribe;
+}
+/** Peer management. */
+export declare class PeersManagement<T extends Peer> implements Peers<T> {
+    private readonly _onPeerConnected;
+    private readonly _onPeerDisconnected;
+    private readonly peers;
+    peerConnected(peer: T): void;
+    peerDisconnected(peer: T): void;
+    isConnected(id: PeerId): boolean;
+    noOfConnectedPeers(): number;
+    onPeerConnected(cb: PeerCallback<T>): () => void;
+    onPeerDisconnected(cb: PeerCallback<T>): () => void;
+}
+//# sourceMappingURL=peers.d.ts.map

package/packages/core/networking/peers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peers.d.ts","sourceRoot":"","sources":["../../../../../packages/core/networking/peers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAE3C,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,oBAAY,eAAe;IACzB,yDAAyD;IACzD,UAAU,IAAI;IACd,0CAA0C;IAC1C,WAAW,IAAI;IACf,+CAA+C;IAC/C,SAAS,IAAI;CACd;AAED,kFAAkF;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;AAE9E,4BAA4B;AAC5B,MAAM,WAAW,MAAO,SAAQ,oBAAoB,CAAC,UAAU,EAAE,UAAU,CAAC;IAC1E,yDAAyD;IACzD,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC/C,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,sBAAsB;AACtB,MAAM,WAAW,IAAI;IACnB,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,OAAO,EAAE,WAAW,CAAC;IACrB,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,GAAG,EAAE,UAAU,CAAC;IAEhB,8DAA8D;IAC9D,mBAAmB,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IAE1D,6BAA6B;IAC7B,UAAU,IAAI,MAAM,CAAC;IAErB,yCAAyC;IACzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC;AAC5E;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;AAS7D,KAAK,WAAW,GAAG,MAAM,IAAI,CAAC;AAE9B,MAAM,WAAW,KAAK,CAAC,CAAC,SAAS,IAAI;IACnC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,qCAAqC;IACrC,kBAAkB,IAAI,MAAM,CAAC;IAE7B,kEAAkE;IAClE,eAAe,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;IAClD,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;CACtD;AAED,uBAAuB;AACvB,qBAAa,eAAe,CAAC,CAAC,SAAS,IAAI,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAyB;IAC1D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyB;IAE7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEtD,aAAa,CAAC,IAAI,EAAE,CAAC;IAarB,gBAAgB,CAAC,IAAI,EAAE,CAAC;IAQxB,WAAW,CAAC,EAAE,EAAE,MAAM;IAItB,kBAAkB;IAIlB,eAAe,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;IAUnC,kBAAkB,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;CASvC"}

package/packages/core/networking/peers.js

@@ -0,0 +1,78 @@
+import { Logger } from "#@typeberry/logger";
+/**
+ * Error callback maybe be triggered multiple times.
+ *
+ * In case of an exception result we will usually see a sequence of:
+ * 1. Exception
+ * 2. LocalClose (since we detected exception and want to close connection)
+ * 3. RemoteClose (since the remote peer detected the exceptional behavior as well)
+ *
+ * However in case of clean disconnects, we may see just local close or remote close
+ * first in case it was either us or them closing the connection.
+ *
+ * `LocalClose` is also trigerred mutliple times (readable stream, writeable stream,
+ * connection). If that's too much, we can tone it down in the future.
+ */
+export var StreamErrorKind;
+(function (StreamErrorKind) {
+    /** An error or closing event that originates locally. */
+    StreamErrorKind[StreamErrorKind["LocalClose"] = 0] = "LocalClose";
+    /** Remote peer triggering close event. */
+    StreamErrorKind[StreamErrorKind["RemoteClose"] = 1] = "RemoteClose";
+    /** Some exceptional behavior on the stream. */
+    StreamErrorKind[StreamErrorKind["Exception"] = 2] = "Exception";
+})(StreamErrorKind || (StreamErrorKind = {}));
+const logger = Logger.new(import.meta.filename, "peers");
+/** Peer ID and address in a standardized format. */
+function displayId(peer) {
+    return `${peer.id}@${peer.address.host}:${peer.address.port}`;
+}
+/** Peer management. */
+export class PeersManagement {
+    _onPeerConnected = [];
+    _onPeerDisconnected = [];
+    peers = new Map();
+    peerConnected(peer) {
+        logger.info `💡 Peer ${displayId(peer)} connected.`;
+        const oldPeerData = this.peers.get(peer.id);
+        if (oldPeerData !== undefined) {
+            // TODO [ToDr] replacing old connection?
+            logger.warn `Replacing older connection.`;
+        }
+        this.peers.set(peer.id, peer);
+        for (const callback of this._onPeerConnected) {
+            callback(peer);
+        }
+    }
+    peerDisconnected(peer) {
+        logger.info `⚡︎Peer ${displayId(peer)} disconnected.`;
+        this.peers.delete(peer.id);
+        for (const callback of this._onPeerDisconnected) {
+            callback(peer);
+        }
+    }
+    isConnected(id) {
+        return this.peers.has(id);
+    }
+    noOfConnectedPeers() {
+        return this.peers.size;
+    }
+    onPeerConnected(cb) {
+        this._onPeerConnected.push(cb);
+        return () => {
+            const idx = this._onPeerConnected.indexOf(cb);
+            if (idx !== -1) {
+                this._onPeerConnected.splice(idx, 1);
+            }
+        };
+    }
+    onPeerDisconnected(cb) {
+        this._onPeerDisconnected.push(cb);
+        return () => {
+            const idx = this._onPeerDisconnected.indexOf(cb);
+            if (idx !== -1) {
+                this._onPeerDisconnected.splice(idx, 1);
+            }
+        };
+    }
+}

package/packages/core/networking/peers.test.d.ts

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