@hive-p2p/server 1.0.19 → 1.0.20

package/core/arbiter.mjs

@@ -0,0 +1,125 @@
+import { CLOCK, NODE, GOSSIP, UNICAST, LOG_CSS } from './config.mjs';
+
+// TRUST_BALANCE = seconds of ban if negative - never exceed MAX_TRUST if positive
+// Growing each second by 1000ms until 0
+// Lowered each second by 100ms until 0 (avoid attacker growing balances on multiple disconnected peers)
+
+const BYTES_COUNT_PERIOD 			= 10_000; 		// 10 seconds
+const MAX_BYTES_PER_PERIOD 			= 1_000_000; 	// 1MB per period
+
+const MAX_TRUST 	= 		3_600_000; 		// +3600 seconds = 1 hour of good behavior
+export const TRUST_VALUES = {
+	// POSITIVE IDENTITY
+	VALID_SIGNATURE: 		+10_000, 		// +10 seconds
+	VALID_POW: 				+300_000, 		// +5 minutes
+	// POSITIVE MESSAGES
+	UNICAST_RELAYED: 		+5_000, 		// +5 seconds
+
+	// NEGATIVE IDENTITY
+	//WRONG_ID_PREFIX: 		-300_000, 		// -5 minutes
+	WRONG_SIGNATURE: 		-600_000, 		// -10 minutes
+	WRONG_POW: 				-100_000_000, 	// -100_000 seconds = 27 hours - should never happen with valid nodes
+
+	// NEGATIVE MESSAGES
+	WRONG_SERIALIZATION: 	-60_000, 		// -1 minute
+	GOSSIP_FLOOD: 			-60_000, 		// -1 minute per message
+	UNICAST_FLOOD: 			-30_000, 		// -30 seconds per message
+	HOPS_EXCEEDED: 			-300_000, 		// -5 minutes
+	UNICAST_INVALID_ROUTE: 	-60_000, 		// -1 minute
+	FAILED_HANDSHAKE: 		-600_000, 		// -10 minutes ??? => TODO
+	WRONG_LENGTH: 			-600_000, 		// -10 minutes
+};
+export class Arbiter {
+	id; cryptoCodex; verbose;
+
+	/** - Key: peerId,  Value: trustBalance
+	 * - trustBalance = milliseconds of ban if negative
+	 * @type {Record<string, number>} */
+	trustBalances = {};
+	bytesCounters = { gossip: 0, unicast: 0 };
+	bytesCounterResetIn = 0;
+
+	/** @param {string} selfId @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex @param {number} verbose */
+	constructor(selfId, cryptoCodex, verbose = 0) {
+		this.id = selfId; this.cryptoCodex = cryptoCodex; this.verbose = verbose;
+	}
+
+	tick() {
+		for (const peerId in this.trustBalances) {
+			let balance = this.trustBalances[peerId];
+			if (balance === 0) continue; // increase to 0 or decrease slowly to 0
+			else balance = balance < 0 ? Math.min(0, balance + 1_000) : Math.max(0, balance - 100);
+		}
+	
+		// RESET GOSSIP BYTES COUNTER
+		if (this.bytesCounterResetIn - 1_000 > 0) return;
+		this.bytesCounterResetIn = BYTES_COUNT_PERIOD;
+		this.bytesCounters = { gossip: 0, unicast: 0 };
+	}
+
+	/** Call from HiveP2P module only!
+	 * @param {string} peerId
+	 * @param {'WRONG_SERIALIZATION'} action */
+	countPeerAction(peerId, action) {
+		if (TRUST_VALUES[action]) return this.adjustTrust(peerId, TRUST_VALUES[action]);
+	}
+	/** @param {string} peerId @param {number} delta @param {string} [reason] */
+	adjustTrust(peerId, delta, reason = 'na') { // Internal and API use - return true if peer isn't banished
+		if (peerId === this.id) return; // self
+		if (delta) this.trustBalances[peerId] = Math.min(MAX_TRUST, (this.trustBalances[peerId] || 0) + delta);
+		if (delta && this.verbose > 2) console.log(`%c(Arbiter: ${this.id}) ${peerId} +${delta}ms (${reason}). Updated: ${this.trustBalances[peerId]}ms.`, LOG_CSS.ARBITER);
+		if (this.isBanished(peerId) && this.verbose > 1) console.log(`%c(Arbiter: ${this.id}) Peer ${peerId} is now banished.`, LOG_CSS.ARBITER);
+	}
+	isBanished(peerId = 'toto') { return (this.trustBalances[peerId] || 0) < 0; }
+
+	// MESSAGE VERIFICATION
+	/** @param {string} peerId @param {number} byteLength @param {'gossip' | 'unicast'} type */
+	countMessageBytes(peerId, byteLength, type) {
+		if (!this.bytesCounters[type]) this.bytesCounters[type] = 0;
+		this.bytesCounters[type] += byteLength;
+		if (this.bytesCounters[type] < MAX_BYTES_PER_PERIOD) return true;
+		return this.adjustTrust(peerId, type === 'gossip' ? TRUST_VALUES.GOSSIP_FLOOD : TRUST_VALUES.UNICAST_FLOOD, 'Message flood detected');
+	}
+	/** Call from HiveP2P module only! @param {string} from @param {any} message @param {Uint8Array} serialized @param {number} [powCheckFactor] default: 0.01 (1%) */
+	async digestMessage(from, message, serialized, powCheckFactor = .01) {
+		const { senderId, pubkey, topic, expectedEnd } = message; // avoid powControl() on banished peers
+		this.#signatureControl(from, message, serialized);
+		if (!this.#lengthControl(topic ? 'gossip' : 'unicast', serialized, expectedEnd)) return;
+
+		if (topic) this.#hopsControl(from, message);
+		else this.#routeLengthControl(from, message);
+		
+		if (this.isBanished(from) || this.isBanished(senderId)) return;
+		if (this.trustBalances[senderId] > TRUST_VALUES.VALID_POW) return;
+		if (Math.random() < powCheckFactor) await this.#powControl(senderId, pubkey);
+	}
+	/** @param {'gossip' | 'unicast'} type */
+	#lengthControl(type, serialized, expectedEnd) {
+		if (!expectedEnd || serialized.length === expectedEnd) return true;
+		this.adjustTrust(from, TRUST_VALUES.WRONG_LENGTH, `${type} message length mismatch`);
+	}
+	/** @param {string} from @param {import('./gossip.mjs').GossipMessage} message @param {Uint8Array} serialized */
+	#signatureControl(from, message, serialized) {
+		const { pubkey, signature, signatureStart } = message;
+		const signedData = serialized.subarray(0, signatureStart);
+		const signatureValid = this.cryptoCodex.verifySignature(pubkey, signature, signedData);
+		if (signatureValid) this.adjustTrust(from, TRUST_VALUES.VALID_SIGNATURE, 'Gossip signature valid');
+		else this.adjustTrust(from, TRUST_VALUES.WRONG_SIGNATURE, 'Gossip signature invalid');
+	}
+	/** GOSSIP only @param {string} from @param {import('./gossip.mjs').GossipMessage} message */
+	#hopsControl(from, message) {
+		if (message.HOPS <= (GOSSIP.HOPS[message.topic] || GOSSIP.HOPS.default)) return;
+		this.adjustTrust(from, TRUST_VALUES.HOPS_EXCEEDED, 'Gossip HOPS exceeded');
+	}
+	/** UNICAST only @param {string} from @param {import('./unicast.mjs').DirectMessage} message */
+	#routeLengthControl(from, message) {
+		if (message.route.length <= UNICAST.MAX_HOPS) return;
+		this.adjustTrust(from, TRUST_VALUES.HOPS_EXCEEDED, 'Unicast HOPS exceeded');
+	}
+	/** ONLY APPLY AFTER #signatureControl() - @param {string} senderId @param {Uint8Array} pubkey */
+	async #powControl(senderId, pubkey) {
+		const isValid = await this.cryptoCodex.pubkeyDifficultyCheck(pubkey);
+		if (isValid) this.adjustTrust(senderId, TRUST_VALUES.VALID_POW, 'Gossip PoW valid');
+		else this.adjustTrust(senderId, TRUST_VALUES.WRONG_POW, 'Gossip PoW invalid');
+	}
+}

package/core/config.mjs

@@ -0,0 +1,226 @@
+const isNode = (typeof window === 'undefined');
+if (!isNode) (await import('../libs/simplepeer-9.11.1.min.js')).default;
+import { Clock } from '../services/clock.mjs';
+
+// HOLD: GLOBAL CONFIG FOR THE LIBRARY
+// AVOID: CIRCULAR DEPENDENCIES AND TOO MANY FUNCTION/CONSTRUCTOR CONFIG
+// SIMPLIFY: IMPORTS, SIMULATOR AND BROWSER SUPPORT
+
+/** Synchronized clock that can be used outside the library */
+export const CLOCK = Clock.instance;
+
+export const SIMULATION = {
+	/** Specify setInterval() avoidance for faster simulation (true = avoid intervals) | Default: true */
+	AVOID_INTERVALS: false,
+	/** Use test transports (WebSocket server and SimplePeer replacement) | Default: false */
+	USE_TEST_TRANSPORTS: false,
+	/** Ice candidates delay simulation | Default: { min: 250, max: 3000 } */
+	ICE_DELAY: { min: 250, max: 3000 },
+	/** ICE offer failure rate simulation (0 to 1) | Default: .2 (20%) */
+	ICE_OFFER_FAILURE_RATE: .2,
+	/** ICE answer failure rate simulation (0 to 1) | Default: .15 (15%) */
+	ICE_ANSWER_FAILURE_RATE: .15,
+	// -------------------------------------------------|
+	/** Avoid creating follower nodes | Default: false */
+	AVOID_FOLLOWERS_NODES: false,
+	/** Auto start the simulation when creating the first node | Default: true */
+	AUTO_START: true,				// auto start the simulation, false to wait the frontend | Default: true
+	/** Number of public nodes to create in the simulation
+	 * - Default: 100
+	 * - min: 1, medium: 3, strong: 20, hardcore: 100 */
+	PUBLIC_PEERS_COUNT: 100,
+	/** Number of standard nodes to create in the simulation
+	 * - Default: 1860
+	 * - stable: 12, medium: 250, strong: 2000, hardcore: 5000 */
+	PEERS_COUNT: 1860,
+	/** Number of bootstrap(public) nodes to provide as bootstrap to each peer on creation | Default: 10, null = all of them */
+	BOOTSTRAPS_PER_PEER: 10,
+	/** Delay between each peer.start() in milliseconds
+	 * - Default: 60 (60sec to start 1000 peers)
+	 * - 0 = faster for simulating big networks but > 0 = should be more realistic */
+	DELAY_BETWEEN_INIT: 10,
+	/** Random unicast(direct) messages to send per second | Default: 0, max: 1 (per peer) */
+	RANDOM_UNICAST_PER_SEC: 0,
+	/** Random gossip(to all) messages to send per second | Default: 0, max: 1 (per peer) */
+	RANDOM_GOSSIP_PER_SEC: 0,
+	/** Delay between each diffusion test in milliseconds | Default: 10_000 (10 seconds) */
+	DIFFUSION_TEST_DELAY: 10_000,
+}
+
+export const NODE = {
+	/** 0: none, 1: errors, 2: +important info, 3: +debug, 4: +everything | Can be bypass by some constructors */
+	DEFAULT_VERBOSE: 1,
+	/** Timeout for upgrading a "connecting" peer to "connected" | Default: 15_000 (15 seconds) */
+	CONNECTION_UPGRADE_TIMEOUT: 15_000,
+	/** Flag to indicate if we are running in a browser environment | DON'T MODIFY THIS VALUE */
+	IS_BROWSER: isNode ? false : true,
+}
+
+export const SERVICE = {
+	/** If the node is a public node (domain provided), it will start a WebSocket server on this port | Default: 8080 */
+	PORT: 8080,
+	/** The public node kicking basis delay | Default: 60_000 (1 minute) */
+	AUTO_KICK_DELAY: 60_000,
+	/** The public node kicking duration | Default: 30_000 (30 seconds) */
+	AUTO_KICK_DURATION: 30_000,
+	/** The public node will limit the maximum incoming connections to this value | Default: 20 */
+	MAX_WS_IN_CONNS: 20,
+}
+
+export const IDENTITY = {
+	/** Difficulty level for anti-sybil measures, based on Argon2id Proof-of-Work
+	 * - Follow a logarithmic scale (2^x)
+	 * - Default: 0 (disabled)
+	 * - RECOMMENDED: 7 (medium security, reasonable CPU usage)
+	 * - HIGH SECURITY: 10 (high security, significant CPU usage)
+	 * - Note: This setting is applied only if ARE_IDS_HEX = TRUE */
+	DIFFICULTY: 0,
+	/** Memory usage in KiB for Argon2
+	 * - Follow a logarithmic scale (2^x)
+	 * - Default: 2**16 = 65_536 (64 MiB)
+	 * - RECOMMENDED: 2**17 = 131_072 (128 MiB)
+	 * - HIGH SECURITY: 2**18 = 262_144 (256 MiB)
+	 * - VERY HIGH SECURITY: 2**19 = 524_288 (512 MiB)
+	 * - Note: This setting is applied only if ARE_IDS_HEX = TRUE */
+	ARGON2_MEM: 2**16,
+	/** Boolean to indicate if we use hex ids, Default: true = hex | false = strings as Bytes (can involve in serialization failures) */
+	ARE_IDS_HEX: true,
+	/** Identifier prefix for public nodes | Default: '0' */
+	PUBLIC_PREFIX: '0',
+	/** Identifier prefix for standard nodes | Default: '1' */
+	STANDARD_PREFIX: '1',
+	/** !!EVEN NUMBER ONLY!! length of peer id | Default: 16 */
+	ID_LENGTH: 16,
+	PUBKEY_LENGTH: 32,
+	PRIVATEKEY_LENGTH: 32,
+	SIGNATURE_LENGTH: 64,
+}
+
+export const TRANSPORTS = {
+	/** Maximum SDP offers to create in advance to be ready for new connections | Default: 2 */
+	MAX_SDP_OFFERS: 2,
+	/** Time to wait for ICE gathering to complete | Default: 1_000 (1 second) */
+	ICE_COMPLETE_TIMEOUT: 1_000,
+	/** Time to wait for signal before destroying WTRC connection | Default: 8_000 (8 seconds) */
+	SIGNAL_CREATION_TIMEOUT: 8_000,
+	/** Time to consider an SDP offer as valid | Default: 40_000 (40 seconds) */
+	SDP_OFFER_EXPIRATION: 40_000, 
+	
+	WS_CLIENT: WebSocket,
+	WS_SERVER: isNode ? (await import('ws')).WebSocketServer : null,
+	PEER: isNode ? (await import('simple-peer')).default : window.SimplePeer
+}
+
+export const DISCOVERY = {
+	/** Delay between two peer declaring their connection to each other | Default: 10_000 (10 seconds) */
+	PEER_LINK_DELAY: 10_000,
+	/** Time to consider a peer connection as valid | Default: 60_000 (60 seconds) */
+	PEER_LINK_EXPIRATION: 60_000,
+	/** Delay between two discovery loops | Default: 2_500 (2.5 seconds) */
+	LOOP_DELAY: 2_500,
+	/** Target number of neighbors to maintain, higher values improve connectivity/resilience but increase resource usage
+	 * - Default: 5
+	 * - Light: 4, Medium: 5, Strong: 8, Hardcore: 12 */
+	TARGET_NEIGHBORS_COUNT: 5,
+
+	ON_CONNECT_DISPATCH: {		// => on Node.#onConnect() // DEPRECATING
+		DELAY: 0, 					// delay before dispatching events | Default: 100 (.1 seconds)
+		BROADCAST_EVENT: false,		// Boolean to indicate if we broadcast 'peer_connected'
+		OVER_NEIGHBORED: true,		// Boolean to indicate if we broadcast 'over_neighbored' event when we are over neighbored | Default: true
+		SHARE_HISTORY: false,		// Boolean to indicate if we broadcastToPeer some gossip history to the new peer | Default: true
+	},
+	ON_DISCONNECT_DISPATCH: {	// => on Node.#onDisconnect() // DEPRECATING
+		DELAY: 0, 					// delay before dispatching the 'disconnected' event | Default: 500 (.5 seconds)
+		BROADCAST_EVENT: false,		// Boolean to indicate if we broadcast 'peer_disconnected'
+	},
+	ON_UNICAST: {				// => UnicastMessager.handleDirectMessage()
+		DIGEST_TRAVELED_ROUTE: true, // Boolean to indicate if we digest the traveled route for each unicast message | Default: true
+	}
+}
+
+export const UNICAST = { // MARKERS RANGE: 0-127
+	/** Maximum number of hops(relaying) for direct message | Default: 8
+	 * - Default: 8, light: 6, super-light: 4, direct-only: 2 */
+	MAX_HOPS: 8,
+	/** Maximum number of nodes to consider during BFS
+	 * - Default: 1728 (12³), light: 512 (8³), super-light: 144 (8²) */
+	MAX_NODES: 256,
+	/** Maximum number of routes to consider during BFS
+	 * - Default: 5, light: 3, super-light: 1 */
+	MAX_ROUTES: 5,
+	/** First byte markers for unicast messages | RANGE: 0-127 */
+	MARKERS_BYTES: {
+		message: 0,
+		'0': 'message',
+		handshake: 1,
+		'1': 'handshake',
+		signal_answer: 2,
+		'2': 'signal_answer',
+		signal_offer: 3,
+		'3': 'signal_offer',
+	},
+}
+
+export const GOSSIP = { // MARKERS RANGE: 128-255
+	/** Time to consider a message as valid | Default: 10_000 (10 seconds) */
+	EXPIRATION: 10_000,
+	/** Time to keep messages in cache to avoid reprocessing | Default: 20_000 (20 seconds) */
+	CACHE_DURATION: 20_000,
+	/** Maximum number of hops for gossip messages | Default: 20 
+	 * - Here you can set different max hops for different message types */
+	HOPS: {
+		default: 20, 		// 16 should be the maximum
+		signal_offer: 6, 	// works with 3 ?
+		diffusion_test: 100, // must be high to reach all peers
+		over_neighbored: 6,
+		// peer_connected: 3,
+		// peer_disconnected: 3,
+	},
+	/** Ponderation to lower the transmission rate based on neighbors count
+	 * - Lowering the transmission rate based on neighbors count, but involve a lower gossip diffusion
+	 * - As well you can apply different ponderation factors for different message types */
+	TRANSMISSION_RATE: {
+		/** Minimum neighbors to apply ponderation, Default: 2
+		 * - Decrease to apply ponderation sooner */
+		MIN_NEIGHBOURS_TO_APPLY_PONDERATION: 2,
+		/** Ponderation factor based on neighbors count, Default: 5
+		 * - Decrease to lower transmission rate based on neighbors count */
+		NEIGHBOURS_PONDERATION: 5,
+
+		Default: 1, 				// 1 === 100%
+		signal_offer: .618, 		// .618 === 61.8%
+		// peer_connected: .5, 		// we can reduce this, but lowering the map quality
+		// peer_disconnected: .618
+	},
+	/** First byte markers for gossip messages | RANGE: 128-255 */
+	MARKERS_BYTES: {
+		gossip: 128,
+		'128': 'gossip',
+		signal_offer: 129,
+		'129': 'signal_offer',
+		peer_connected: 130,
+		'130': 'peer_connected',
+		peer_disconnected: 131,
+		'131': 'peer_disconnected',
+		diffusion_test: 132,
+		'132': 'diffusion_test',
+		over_neighbored: 133,
+		'133': 'over_neighbored',
+	},
+}
+
+/** CSS styles for console logging */
+export const LOG_CSS = {
+	SIMULATOR: 'color: yellow; font-weight: bold;',
+	ARBITER: 'color: white;',
+	CRYPTO_CODEX: 'color: green;',
+	GOSSIP: 'color: fuchsia;',
+	UNICAST: 'color: cyan;',
+	PEER_STORE: 'color: orange;',
+	SERVICE: 'color: teal;',
+	PUNISHER: { BAN: 'color: red; font-weight: bold;', KICK: 'color: darkorange; font-weight: bold;' },
+}
+
+export default {
+	CLOCK, SIMULATION, NODE, TRANSPORTS, DISCOVERY, IDENTITY, UNICAST, GOSSIP, LOG_CSS
+};

package/core/crypto-codex.mjs

@@ -0,0 +1,257 @@
+import { CLOCK, SIMULATION, NODE, IDENTITY, GOSSIP, UNICAST, LOG_CSS } from './config.mjs';
+import { GossipMessage } from './gossip.mjs';
+import { DirectMessage, ReroutedDirectMessage } from './unicast.mjs';
+import { Converter } from '../services/converter.mjs';
+import { ed25519, Argon2Unified } from '../services/cryptos.mjs';
+
+export class CryptoCodex {
+	argon2 = new Argon2Unified();
+	converter = new Converter();
+	AVOID_CRYPTO = false;
+	verbose = NODE.DEFAULT_VERBOSE;
+	/** @type {string} */ id;
+    /** @type {Uint8Array} */ publicKey;
+    /** @type {Uint8Array} */ privateKey;
+
+	/** @param {string} [nodeId] If provided: used to generate a fake keypair > disable crypto operations */
+	constructor(nodeId, verbose = NODE.DEFAULT_VERBOSE) {
+		this.verbose = verbose;
+		if (!nodeId) return; // IF NOT PROVIDED: generate() should be called.
+		this.AVOID_CRYPTO = true;
+		this.id = nodeId.padEnd(IDENTITY.ID_LENGTH, ' ').slice(0, IDENTITY.ID_LENGTH);
+		this.privateKey = new Uint8Array(32).fill(0); this.publicKey = new Uint8Array(32).fill(0);
+		const idBytes = new TextEncoder().encode(this.id); // use nodeId to create a fake public key
+		for (let i = 0; i < IDENTITY.ID_LENGTH; i++) this.publicKey[i] = idBytes[i];
+	}
+
+	/** @param {boolean} asPublicNode Default: false @param {Uint8Array} seed PrivateKey *-optional* */
+	static async createCryptoCodex(asPublicNode, seed) {
+		const cryptoCodex = new CryptoCodex(undefined, this.verbose);
+		await cryptoCodex.generate(asPublicNode, seed);
+		return cryptoCodex;
+	}
+
+	// IDENTITY
+	/** @param {string} id Check the first character against the PUBLIC_PREFIX */
+	static isPublicNode(id) { return (IDENTITY.ARE_IDS_HEX ? Converter.hexToBits(id[0]) : id).startsWith(IDENTITY.PUBLIC_PREFIX); }
+	/** @param {string} id */
+	get idLength() { return IDENTITY.ARE_IDS_HEX ? IDENTITY.ID_LENGTH / 2 : IDENTITY.ID_LENGTH; }
+	isPublicNode(id) { return CryptoCodex.isPublicNode(id); }
+    /** @param {boolean} asPublicNode @param {Uint8Array} [seed] The privateKey. DON'T USE IN SIMULATION */
+	async generate(asPublicNode, seed) { // Generate Ed25519 keypair cross-platform | set id only for simulator
+		if (this.nodeId) return;
+		await this.#generateAntiSybilIdentity(seed, asPublicNode);
+		if (!this.id) throw new Error('Failed to generate identity');
+    }
+	/** Check if the pubKey meets the difficulty using Argon2 derivation @param {Uint8Array} publicKey */
+	async pubkeyDifficultyCheck(publicKey) {
+		if (this.AVOID_CRYPTO || !IDENTITY.DIFFICULTY) return true;
+		const { bitsString } = await this.argon2.hash(publicKey, 'HiveP2P', IDENTITY.ARGON2_MEM) || {};
+		if (bitsString && bitsString.startsWith('0'.repeat(IDENTITY.DIFFICULTY))) return true;
+	}
+	#idFromPublicKey(publicKey) {
+		if (IDENTITY.ARE_IDS_HEX) return this.converter.bytesToHex(publicKey.slice(0, this.idLength), IDENTITY.ID_LENGTH);
+		return this.converter.bytesToString(publicKey.slice(0, IDENTITY.ID_LENGTH));
+	}
+	/** @param {Uint8Array} seed The privateKey. @param {boolean} asPublicNode */
+	async #generateAntiSybilIdentity(seed, asPublicNode) {
+		const maxIterations = (2 ** IDENTITY.DIFFICULTY) * 100; // avoid infinite loop
+		for (let i = 0; i < maxIterations; i++) { // avoid infinite loop
+			const { secretKey, publicKey } = ed25519.keygen(seed);
+			const id = this.#idFromPublicKey(publicKey);
+			if (asPublicNode && !this.isPublicNode(id)) continue; // Check prefix
+			if (!asPublicNode && this.isPublicNode(id)) continue; // Check prefix
+			if (!await this.pubkeyDifficultyCheck(publicKey)) continue; // Check difficulty
+
+			this.id = id;
+			this.privateKey = secretKey; this.publicKey = publicKey;
+			if (this.verbose > 2) console.log(`%cNode generated id: ${this.id} (isPublic: ${asPublicNode}, difficulty: ${IDENTITY.DIFFICULTY}) after ${((i + 1) / 2).toFixed(1)} iterations`, LOG_CSS.CRYPTO_CODEX);
+			return;
+		}
+		if (this.verbose > 0) console.log(`%cFAILED to generate id after ${maxIterations} iterations. Try lowering the difficulty.`, LOG_CSS.CRYPTO_CODEX);
+	}
+
+	// MESSSAGE CREATION (SERIALIZATION AND SIGNATURE INCLUDED)
+	signBufferViewAndAppendSignature(bufferView, privateKey, signaturePosition = bufferView.length - IDENTITY.SIGNATURE_LENGTH) {
+		if (this.AVOID_CRYPTO) return;
+		const dataToSign = bufferView.subarray(0, signaturePosition);
+		bufferView.set(ed25519.sign(dataToSign, privateKey), signaturePosition);
+	}
+	/** @param {string} topic @param {string | Uint8Array | Object} data @param {number} [HOPS] @param {string[]} route @param {string[]} [neighbors] */
+	createGossipMessage(topic, data, HOPS = 3, neighbors = [], timestamp = CLOCK.time) {
+		const MARKER = GOSSIP.MARKERS_BYTES[topic];
+		if (MARKER === undefined) throw new Error(`Failed to create gossip message: unknown topic '${topic}'.`);
+		
+		const neighborsBytes = this.#idsToBytes(neighbors);
+		const { dataCode, dataBytes } = this.#dataToBytes(data);
+		const totalBytes = 1 + 1 + 1 + 8 + 4 + 32 + neighborsBytes.length + dataBytes.length + IDENTITY.SIGNATURE_LENGTH + 1;
+		const buffer = new ArrayBuffer(totalBytes);
+		const bufferView = new Uint8Array(buffer);
+		this.#setBufferHeader(bufferView, MARKER, dataCode, neighbors.length, timestamp, dataBytes, this.publicKey);
+		
+		bufferView.set(neighborsBytes, 47); 					// X bytes for neighbors
+		bufferView.set(dataBytes, 47 + neighborsBytes.length); 	// X bytes for data
+		bufferView.set([Math.min(255, HOPS)], totalBytes - 1); 	// 1 byte for HOPS (Unsigned)
+		this.signBufferViewAndAppendSignature(bufferView, this.privateKey, totalBytes - IDENTITY.SIGNATURE_LENGTH - 1);
+		return bufferView;
+	}
+	/** @param {Uint8Array} serializedMessage */
+	decrementGossipHops(serializedMessage) { // Here we just need to decrement the HOPS value => last byte of the message
+		const clone = new Uint8Array(serializedMessage); // avoid modifying the original message
+		const hops = serializedMessage[serializedMessage.length - 1];
+		clone[serializedMessage.length - 1] = Math.max(0, hops - 1);
+		return clone;
+	}
+	/** @param {string} type @param {string | Uint8Array | Object} data @param {string[]} route @param {string[]} [neighbors] */
+	createUnicastMessage(type, data, route, neighbors = [], timestamp = CLOCK.time) {
+		const MARKER = UNICAST.MARKERS_BYTES[type];
+		if (MARKER === undefined) throw new Error(`Failed to create unicast message: unknown type '${type}'.`);
+		if (route.length < 2) throw new Error('Failed to create unicast message: route must have at least 2 nodes (next hop and target).');
+		if (route.length > UNICAST.MAX_HOPS) throw new Error(`Failed to create unicast message: route exceeds max hops (${UNICAST.MAX_HOPS}).`);
+		
+		const neighborsBytes = this.#idsToBytes(neighbors);
+		const { dataCode, dataBytes } = this.#dataToBytes(data);
+		const routeBytes = this.#idsToBytes(route);
+		const totalBytes = 1 + 1 + 1 + 8 + 4 + 32 + neighborsBytes.length + 1 + routeBytes.length + dataBytes.length + IDENTITY.SIGNATURE_LENGTH;
+		const buffer = new ArrayBuffer(totalBytes);
+		const bufferView = new Uint8Array(buffer);
+		this.#setBufferHeader(bufferView, MARKER, dataCode, neighbors.length, timestamp, dataBytes, this.publicKey);
+		
+		const NDBL = neighborsBytes.length + dataBytes.length;
+		bufferView.set(neighborsBytes, 47); 					// X bytes for neighbors
+		bufferView.set(dataBytes, 47 + neighborsBytes.length); 	// X bytes for data
+		bufferView.set([route.length], 47 + NDBL);				// 1 byte for route length
+		bufferView.set(routeBytes, 47 + 1 + NDBL);				// X bytes for route
+
+		this.signBufferViewAndAppendSignature(bufferView, this.privateKey, totalBytes - IDENTITY.SIGNATURE_LENGTH);
+		return bufferView;
+	}
+	/** @param {Uint8Array} serialized @param {string[]} newRoute */
+	createReroutedUnicastMessage(serialized, newRoute) {
+		if (newRoute.length < 2) throw new Error('Failed to create rerouted unicast message: route must have at least 2 nodes (next hop and target).');
+		if (newRoute.length > UNICAST.MAX_HOPS) throw new Error(`Failed to create rerouted unicast message: route exceeds max hops (${UNICAST.MAX_HOPS}).`);
+	
+		const routeBytesArray = newRoute.map(id => this.converter.stringToBytes(id));
+		const totalBytes = serialized.length + 32 + (IDENTITY.ID_LENGTH * routeBytesArray.length) + IDENTITY.SIGNATURE_LENGTH;
+		const buffer = new ArrayBuffer(totalBytes);
+		const bufferView = new Uint8Array(buffer);
+		bufferView.set(serialized, 0); // original serialized message
+		bufferView.set(this.publicKey, serialized.length); // 32 bytes for new public key
+		for (let i = 0; i < routeBytesArray.length; i++) bufferView.set(routeBytesArray[i], serialized.length + 32 + (i * IDENTITY.ID_LENGTH)); // new route
+		
+		this.signBufferViewAndAppendSignature(bufferView, this.privateKey, totalBytes - IDENTITY.SIGNATURE_LENGTH);
+		return bufferView;
+	}
+	/** @param {string[]} ids */
+	#idsToBytes(ids) {
+		if (IDENTITY.ARE_IDS_HEX) return this.converter.hexToBytes(ids.join(''), IDENTITY.ID_LENGTH * ids.length);
+		return this.converter.stringToBytes(ids.join(''));
+	}
+	/** @param {string | Uint8Array | Object} data */
+	#dataToBytes(data) { // typeCodes: 1=string, 2=Uint8Array, 3=JSON
+		if (typeof data === 'string') return { dataCode: 1, dataBytes: this.converter.stringToBytes(data) };
+		if (data instanceof Uint8Array) return { dataCode: 2, dataBytes: data };
+		return { dataCode: 3, dataBytes: this.converter.stringToBytes(JSON.stringify(data)) };
+	}
+	/** @param {Uint8Array} bufferView @param {number} marker @param {number} dataCode @param {number} neighborsCount @param {number} timestamp @param {Uint8Array} dataBytes @param {Uint8Array} publicKey */
+	#setBufferHeader(bufferView, marker, dataCode, neighborsCount, timestamp, dataBytes, publicKey) {
+		const timestampBytes = this.converter.numberTo8Bytes(timestamp);
+		const dataLengthBytes = this.converter.numberTo4Bytes(dataBytes.length);
+		bufferView.set([marker], 0);			// 1 byte for marker
+		bufferView.set([dataCode], 1);			// 1 byte for data type code
+		bufferView.set([neighborsCount], 2);	// 1 byte for neighbors length
+		bufferView.set(timestampBytes, 3);		// 8 bytes for timestamp
+		bufferView.set(dataLengthBytes, 11);	// 4 bytes for data length
+		bufferView.set(publicKey, 15);			// 32 bytes for pubkey
+	}
+
+	// MESSSAGE READING (DESERIALIZATION AND SIGNATURE VERIFICATION INCLUDED)
+	/** @param {Uint8Array} publicKey @param {Uint8Array} dataToVerify @param {Uint8Array} signature */
+	verifySignature(publicKey, dataToVerify, signature) {
+		if (this.AVOID_CRYPTO) return true;
+		return ed25519.verify(dataToVerify, signature, publicKey);
+	}
+	/** @param {Uint8Array} bufferView */
+	readBufferHeader(bufferView, readAssociatedId = true) {
+		const marker = bufferView[0]; 				// 1 byte for marker
+		const dataCode = bufferView[1];				// 1 byte for data type code
+		const neighborsCount = bufferView[2];		// 1 byte for neighbors length
+		const tBytes = bufferView.slice(3, 11);		// 8 bytes for timestamp
+		const lBytes = bufferView.slice(11, 15);	// 4 bytes for data length
+		const pubkey = bufferView.slice(15, 47);	// 32 bytes for pubkey
+		const associatedId = readAssociatedId ? this.#idFromPublicKey(pubkey) : null;
+		const neighLength = neighborsCount * this.idLength;
+		const timestamp = this.converter.bytes8ToNumber(tBytes);
+		const dataLength = this.converter.bytes4ToNumber(lBytes);
+		return { marker, dataCode, neighLength, timestamp, dataLength, pubkey, associatedId };
+	}
+	/** @param {Uint8Array | ArrayBuffer} serialized @return {GossipMessage | null } */
+	readGossipMessage(serialized) {
+		if (this.verbose > 3) console.log(`%creadGossipMessage ${serialized.byteLength} bytes`, LOG_CSS.CRYPTO_CODEX);
+		if (this.verbose > 3) console.log(`%c${serialized}`, LOG_CSS.CRYPTO_CODEX);
+		try { // 1, 1, 1, 8, 4, 32, X, 64, 1
+			const { marker, dataCode, neighLength, timestamp, dataLength, pubkey, associatedId } = this.readBufferHeader(serialized);
+			const topic = GOSSIP.MARKERS_BYTES[marker];
+			if (topic === undefined) throw new Error(`Failed to deserialize gossip message: unknown marker byte ${d[0]}.`);
+			const NDBL = neighLength + dataLength;
+			const neighbors = this.#bytesToIds(serialized.slice(47, 47 + neighLength));
+			const deserializedData = this.#bytesToData(dataCode, serialized.slice(47 + neighLength, 47 + NDBL));
+			const signatureStart = 47 + NDBL;
+			const signature = serialized.slice(signatureStart, signatureStart + IDENTITY.SIGNATURE_LENGTH);
+			const HOPS = serialized[serialized.length - 1];
+			const expectedEnd = signatureStart + IDENTITY.SIGNATURE_LENGTH + 1;
+			const senderId = associatedId;
+			return new GossipMessage(topic, timestamp, neighbors, HOPS, senderId, pubkey, deserializedData, signature, signatureStart, expectedEnd);
+		} catch (error) { if (this.verbose > 1) console.warn(`Error deserializing ${topic || 'unknown'} gossip message:`, error.stack); }
+		return null;
+	}
+	/** @param {Uint8Array | ArrayBuffer} serialized @return {DirectMessage | ReroutedDirectMessage | null} */
+	readUnicastMessage(serialized) {
+		if (this.verbose > 3) console.log(`%creadUnicastMessage ${serialized.byteLength} bytes`, LOG_CSS.CRYPTO_CODEX);
+		if (this.verbose > 3) console.log(`%c${serialized}`, LOG_CSS.CRYPTO_CODEX);
+		try { // 1, 1, 1, 8, 4, 32, X, 1, X, 64
+			const { marker, dataCode, neighLength, timestamp, dataLength, pubkey } = this.readBufferHeader(serialized, false);
+			const type = UNICAST.MARKERS_BYTES[marker];
+			if (type === undefined) throw new Error(`Failed to deserialize unicast message: unknown marker byte ${d[0]}.`);
+			const NDBL = neighLength + dataLength;
+			const neighbors = this.#bytesToIds(serialized.slice(47, 47 + neighLength));
+			const deserializedData = this.#bytesToData(dataCode, serialized.slice(47 + neighLength, 47 + NDBL));
+			const routeLength = serialized[47 + NDBL];
+			const routeBytesLength = routeLength * this.idLength;
+			const signatureStart = 47 + NDBL + 1 + routeBytesLength;
+			const routeBytes = serialized.slice(47 + NDBL + 1, signatureStart);
+			const route = this.#bytesToIds(routeBytes);
+			const initialMessageEnd = signatureStart + IDENTITY.SIGNATURE_LENGTH;
+			const signature = serialized.slice(signatureStart, initialMessageEnd);
+			const isPatched = (serialized.length > initialMessageEnd);
+
+			if (!isPatched) return new DirectMessage(type, timestamp, neighbors, route, pubkey, deserializedData, signature, signatureStart, initialMessageEnd);
+
+			const rerouterPubkey = serialized.slice(initialMessageEnd, initialMessageEnd + 32);
+			const newRoute = this.#bytesToIds(serialized.slice(initialMessageEnd + 32, serialized.length - IDENTITY.SIGNATURE_LENGTH));
+			const rerouterSignature = serialized.slice(serialized.length - IDENTITY.SIGNATURE_LENGTH);
+			return new ReroutedDirectMessage(type, timestamp, neighbors, route, pubkey, deserializedData, signature, rerouterPubkey, newRoute, rerouterSignature, serialized.length);
+		} catch (error) { if (this.verbose > 1) console.warn(`Error deserializing ${type || 'unknown'} unicast message:`, error.stack); }
+		return null;
+	}
+	/** @param {Uint8Array} serialized */
+	#bytesToIds(serialized) {
+		const ids = [];
+		const idLength = this.idLength;
+		if (serialized.length % idLength !== 0) throw new Error('Failed to parse ids: invalid serialized length.');
+
+		for (let i = 0; i < serialized.length / idLength; i++) {
+			const idBytes = serialized.slice(i * idLength, (i + 1) * idLength);
+			if (IDENTITY.ARE_IDS_HEX) ids.push(this.converter.bytesToHex(idBytes, IDENTITY.ID_LENGTH));
+			else ids.push(this.converter.bytesToString(idBytes));
+		}
+		return ids;
+	}
+	/** @param {1 | 2 | 3} dataCode @param {Uint8Array} dataBytes @return {string | Uint8Array | Object} */
+	#bytesToData(dataCode, dataBytes) {
+		if (dataCode === 1) return this.converter.bytesToString(dataBytes);
+		if (dataCode === 2) return dataBytes;
+		if (dataCode === 3) return JSON.parse(this.converter.bytesToString(dataBytes));
+		throw new Error(`Failed to parse data: unknown data code '${dataCode}'.`);
+	}
+}