hive-p2p 1.0.0

package/core/crypto-codex.mjs

@@ -0,0 +1,249 @@
+import { CLOCK, SIMULATION, NODE, IDENTITY, GOSSIP, UNICAST, LOG_CSS } from './parameters.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) {
+		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];
+	}
+
+	// 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}'.`);
+	}
+}

package/core/gossip.mjs

@@ -0,0 +1,159 @@
+import { CLOCK, GOSSIP, DISCOVERY } from './parameters.mjs';
+import { xxHash32 } from '../libs/xxhash32.mjs';
+
+export class GossipMessage { // TYPE DEFINITION
+	topic = 'gossip';
+	timestamp;
+	neighborsList;
+	HOPS;
+	senderId;
+	pubkey;
+	data;
+	signature;
+	signatureStart; // position in the serialized message where the signature starts
+	expectedEnd; // expected length of the serialized message
+
+	/** @param {string} topic @param {number} timestamp @param {string[]} neighborsList @param {number} HOPS @param {string} senderId @param {string} pubkey @param {string | Uint8Array | Object} data @param {string | undefined} signature @param {number} signatureStart @param {number} expectedEnd */
+	constructor(topic, timestamp, neighborsList, HOPS, senderId, pubkey, data, signature, signatureStart, expectedEnd) {
+		this.topic = topic; this.timestamp = timestamp; this.neighborsList = neighborsList;
+		this.HOPS = HOPS; this.senderId = senderId; this.pubkey = pubkey; this.data = data;
+		this.signature = signature; this.signatureStart = signatureStart; this.expectedEnd = expectedEnd;
+	}
+}
+
+/** - 'BloomFilterCacheEntry' Definition
+ * @typedef {Object} BloomFilterCacheEntry
+ * @property {string} hash
+ * @property {string} senderId
+ * @property {string} topic
+ * @property {Uint8Array} serializedMessage
+ * @property {number} expiration
+ */
+class DegenerateBloomFilter {
+	cryptoCodex;
+	xxHash32UsageCount = 0;
+	/** @type {Record<string, number>} */
+	seenTimeouts = {}; // Map of message hashes to their expiration timestamps
+	
+	/** @type {BloomFilterCacheEntry[]} */ cache = [];
+	cleanupFrequency = 100;
+	cleanupIn = 100;
+	cleanupDurationWarning = 10;
+
+	/** @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex */
+	constructor(cryptoCodex) { this.cryptoCodex = cryptoCodex; }
+
+	// PUBLIC API
+	/** @param {'asc' | 'desc'} order */
+	getGossipHistoryByTime(order = 'asc') {
+		const lightenHistory = this.cache.map(e => ({ senderId: e.senderId, topic: e.topic, data: e.serializedMessage }));
+		return order === 'asc' ? lightenHistory : lightenHistory.reverse();
+	}
+	/** @param {Uint8Array} serializedMessage */
+	addMessage(serializedMessage) {
+    	const n = CLOCK.time;
+		const { marker, neighLength, timestamp, dataLength, pubkey, associatedId } = this.cryptoCodex.readBufferHeader(serializedMessage);
+		if (n - timestamp > GOSSIP.EXPIRATION) return;
+
+		const hashableData = serializedMessage.subarray(0, 47 + neighLength + dataLength);
+		const h = xxHash32(hashableData);
+		this.xxHash32UsageCount++;
+		if (this.seenTimeouts[h]) return;
+
+		const topic = GOSSIP.MARKERS_BYTES[marker];
+		const senderId = associatedId;
+		const expiration = n + GOSSIP.CACHE_DURATION;
+		this.cache.push({ hash: h, senderId, topic, serializedMessage, timestamp, expiration });
+		this.seenTimeouts[h] = expiration;
+
+		if (--this.cleanupIn <= 0) this.#cleanupOldestEntries(n);
+		return { hash: h, isNew: !this.seenTimeouts[h] };
+	}
+	#cleanupOldestEntries(n = CLOCK.time) {
+		let firstValidIndex = -1;
+		for (let i = 0; i < this.cache.length; i++)
+			if (this.cache[i].expiration <= n) delete this.seenTimeouts[this.cache[i].hash];
+			else if (firstValidIndex === -1) firstValidIndex = i;
+		
+		if (firstValidIndex > 0) this.cache = this.cache.slice(firstValidIndex);
+		else if (firstValidIndex === -1) this.cache = [];
+		this.cleanupIn = this.cleanupFrequency;
+	}
+}
+
+export class Gossip {
+	/** @type {Record<string, Function[]>} */ callbacks = { message_handle: [] };
+	id; cryptoCodex; arbiter; peerStore; verbose; bloomFilter;
+
+	/** @param {string} selfId @param {import('./crypto-codex.mjs').CryptoCodex} cryptoCodex @param {import('./arbiter.mjs').Arbiter} arbiter @param {import('./peer-store.mjs').PeerStore} peerStore */
+	constructor(selfId, cryptoCodex, arbiter, peerStore, verbose = 0) {
+		this.id = selfId;
+		this.cryptoCodex = cryptoCodex;
+		this.arbiter = arbiter;
+		this.peerStore = peerStore;
+		this.verbose = verbose;
+		this.bloomFilter = new DegenerateBloomFilter(cryptoCodex);
+	}
+
+	/** @param {string} callbackType @param {Function} callback */
+	on(callbackType, callback) {
+		if (!this.callbacks[callbackType]) this.callbacks[callbackType] = [callback];
+		else this.callbacks[callbackType].push(callback);
+	}
+	/** Gossip a message to all connected peers > will be forwarded to all peers
+	 * @param {string | Uint8Array | Object} data @param {string} topic @param {number} [HOPS] */
+	broadcastToAll(data, topic = 'gossip', HOPS) {
+		const hops = HOPS || GOSSIP.HOPS[topic] || GOSSIP.HOPS.default;
+		const serializedMessage = this.cryptoCodex.createGossipMessage(topic, data, hops, this.peerStore.neighborsList);
+		if (!this.bloomFilter.addMessage(serializedMessage)) return; // avoid sending duplicate messages
+		if (this.verbose > 3) console.log(`(${this.id}) Gossip ${topic}, to ${JSON.stringify(this.peerStore.neighborsList)}: ${data}`);
+		for (const peerId of this.peerStore.neighborsList) this.#broadcastToPeer(peerId, serializedMessage);
+	}
+	/** @param {string} targetId @param {any} serializedMessage */
+	#broadcastToPeer(targetId, serializedMessage) {
+		if (targetId === this.id) throw new Error(`Refusing to send a gossip message to self (${this.id}).`);
+		const transportInstance = this.peerStore.connected[targetId]?.transportInstance;
+		if (!transportInstance) return { success: false, reason: `Transport instance is not available for peer ${targetId}.` };
+		try { transportInstance.send(serializedMessage); }
+		catch (error) { this.peerStore.connected[targetId]?.close(); }
+	}
+	sendGossipHistoryToPeer(peerId) {
+		const gossipHistory = this.bloomFilter.getGossipHistoryByTime('asc');
+		for (const entry of gossipHistory) this.#broadcastToPeer(peerId, entry.data);
+	}
+	/** @param {string} from @param {Uint8Array} serialized @returns {void} */
+	async handleGossipMessage(from, serialized) {
+		if (this.arbiter.isBanished(from)) return this.verbose >= 3 ? console.info(`%cReceived gossip message from banned peer ${from}, ignoring.`, 'color: red;') : null;
+		if (!this.arbiter.countMessageBytes(from, serialized.byteLength, 'gossip')) return; // ignore if flooding/banished
+		for (const cb of this.callbacks.message_handle || []) cb(serialized); // Simulator counter before filtering
+		if (!this.bloomFilter.addMessage(serialized)) return; // already processed this message
+
+		const message = this.cryptoCodex.readGossipMessage(serialized);
+		if (!message) return this.arbiter.countPeerAction(from, 'WRONG_SERIALIZATION');
+		await this.arbiter.digestMessage(from, message, serialized);
+		if (this.arbiter.isBanished(from)) return; // ignore messages from banished peers
+		if (this.arbiter.isBanished(message.senderId)) return; // ignore messages from banished peers
+
+		const { topic, timestamp, neighborsList, HOPS, senderId, data } = message;
+		if (senderId === this.id) throw new Error(`#${this.id}#${from}# Received our own message back from peer ${from}.`);
+		
+		if (this.verbose > 3) // LOGGING
+			if (senderId === from) console.log(`(${this.id}) Gossip ${topic} from ${senderId}: ${data}`);
+			else console.log(`(${this.id}) Gossip ${topic} from ${senderId} (by: ${from}): ${data}`);
+
+		this.peerStore.digestPeerNeighbors(senderId, neighborsList);
+		for (const cb of this.callbacks[topic] || []) cb(senderId, data, HOPS, message); // specific topic callback
+		if (HOPS < 1) return; // stop forwarding if HOPS is 0
+
+		const nCount = this.peerStore.neighborsList.length;
+		const trm = Math.max(1, nCount / GOSSIP.TRANSMISSION_RATE.NEIGHBOURS_PONDERATION);
+		const tRateBase = GOSSIP.TRANSMISSION_RATE[topic] || GOSSIP.TRANSMISSION_RATE.default;
+		const transmissionRate = Math.pow(tRateBase, trm);
+		const avoidTransmissionRate = nCount < GOSSIP.TRANSMISSION_RATE.MIN_NEIGHBOURS_TO_APPLY_PONDERATION;
+		const serializedToTransmit = this.cryptoCodex.decrementGossipHops(serialized);
+		for (const peerId of this.peerStore.neighborsList)
+			if (peerId === from) continue; // avoid sending back to sender
+			else if (!avoidTransmissionRate && Math.random() > transmissionRate) continue; // apply gossip transmission rate
+			else this.#broadcastToPeer(peerId, serializedToTransmit);
+	}
+}

package/core/ice-offer-manager.mjs

@@ -0,0 +1,175 @@
+import { CLOCK, NODE, TRANSPORTS, LOG_CSS } from './parameters.mjs';
+import { xxHash32 } from '../libs/xxhash32.mjs';
+import wrtc from 'wrtc';
+
+/** - 'OfferObj' Definition
+ * @typedef {Object} OfferObj
+ * @property {number} timestamp
+ * @property {boolean} isUsed // => if true => should be deleted
+ * @property {number} sentCounter
+ * @property {Object} signal
+ * @property {import('simple-peer').Instance} offererInstance
+ * @property {boolean} isDigestingOneAnswer Flag to avoid multiple answers handling at the same time (DISCOVERY.LOOP_DELAY (2.5s) will be doubled (5s) between two answers handling)
+ * @property {Array<{peerId: string, signal: any, timestamp: number, used: boolean}>} answers
+ * @property {Record<string, boolean>} answerers key: peerId, value: true */
+
+export class OfferManager { // Manages the creation of SDP offers and handling of answers
+	id;
+	verbose;
+	stunUrls;
+
+	/** @param {string} id @param {Array<{urls: string}>} stunUrls */
+	constructor(id, stunUrls, verbose = 0) { this.id = id; this.verbose = verbose; this.stunUrls = stunUrls; }
+
+	onSignalAnswer = null; 		// function(remoteId, signalData, offerHash)
+	onConnect = null; 			// function(remoteId, transportInstance)
+	
+	/** @type {Record<number, import('simple-peer').Instance>} key: expiration timestamp */
+	offerInstanceByExpiration = {};
+	creatingOffer = false; 		// flag to avoid multiple simultaneous creations (shared between all offers)
+	offerCreationTimeout = null; // sequential creation timeout (shared between all offers)
+	offersToCreate = TRANSPORTS.MAX_SDP_OFFERS;
+	/** @type {Record<string, OfferObj>} key: offerHash **/ offers = {};
+
+	tick() { // called in peerStore to avoid multiple intervals
+		const now = CLOCK.time;
+		// CLEAR EXPIRED CREATOR OFFER INSTANCES
+		for (const expiration in this.offerInstanceByExpiration) {
+			const instance = this.offerInstanceByExpiration[expiration];
+			if (now < expiration) continue; // not expired yet
+			instance?.destroy();
+			delete this.offerInstanceByExpiration[expiration];
+			this.creatingOffer = false; // release flag
+		}
+			
+		// CLEAR USED AND EXPIRED OFFERS
+		for (const hash in this.offers) {
+			const offer = this.offers[hash];
+			if (offer.offererInstance.destroyed) { delete this.offers[hash]; continue; } // offerer destroyed
+			if (offer.isUsed) { delete this.offers[hash]; continue; } // used offer => remove it (handled by peerStore)
+			if (offer.timestamp + TRANSPORTS.SDP_OFFER_EXPIRATION > now) continue; // not expired yet
+			offer.offererInstance?.destroy();
+			delete this.offers[hash];
+		}
+
+		// TRY TO USE AVAILABLE ANSWERS
+		let offerCount = 0;
+		for (const hash in this.offers) {
+			offerCount++; // [live at the first line of the loop] used just below -> avoid Object.keys() call
+			const offer = this.offers[hash];
+			if (offer.isDigestingOneAnswer) { offer.isDigestingOneAnswer = false; continue; }
+			if (offer.offererInstance.destroyed) continue; // offerer destroyed
+			
+			const unusedAnswers = offer.answers.filter(a => !a.used);
+			if (!unusedAnswers.length) continue; // no answers available
+			
+			const newestAnswer = unusedAnswers.reduce((a, b) => a.timestamp > b.timestamp ? a : b);
+			if (!newestAnswer) continue; // all answers are used
+
+			newestAnswer.used = true;
+			const receivedSince = now - newestAnswer.timestamp;
+			if (receivedSince > NODE.CONNECTION_UPGRADE_TIMEOUT / 2) continue; // remote peer will break the connection soon, don't use this answer
+			offer.offererInstance.signal(newestAnswer.signal);
+			offer.isDigestingOneAnswer = true;
+			if (this.verbose > 2) console.log(`(${this.id}) Using answer from ${newestAnswer.peerId} for offer ${hash} (received since ${receivedSince} ms)`);
+		}
+
+		if (this.creatingOffer) return; // already creating one or unable to send
+		if (offerCount >= this.offersToCreate) return; // already have enough offers
+		
+		// CREATE NEW OFFER
+		this.creatingOffer = true;
+		const expiration = now + (TRANSPORTS.SIGNAL_CREATION_TIMEOUT || 8_000);
+		const instance = this.#createOffererInstance(expiration);
+		this.offerInstanceByExpiration[expiration] = instance;
+	};
+	#createOffererInstance(expiration) {
+		const instance = new TRANSPORTS.PEER({ initiator: true, trickle: false, wrtc, config: { iceServers: this.stunUrls } });
+		instance.on('error', error => this.#onError(error));
+		instance.on('signal', data => { // trickle: false => only one signal event with the full offer
+			const { candidate, type } = data; // with trickle, we need to adapt the approach.
+			if (!data || candidate) throw new Error('Unexpected signal data from offerer instance: ' + JSON.stringify(data));
+			if (type !== 'offer') throw new Error('Unexpected signal type from offerer instance: ' + type);
+			
+			// OFFER READY
+			delete this.offerInstanceByExpiration[expiration];
+			const offerHash = xxHash32(JSON.stringify(data)); // UN PEU BLOQUE ICI (connect on voudrait identifer le peer)
+			instance.on('connect', () => { // cb > peerStore > Node > Node.#onConnect()
+				if (this.offers[offerHash]) this.offers[offerHash].isUsed = true;
+				this.onConnect(undefined, instance);
+			});
+			this.offers[offerHash] = { timestamp: CLOCK.time, sentCounter: 0, signal: data, offererInstance: instance, answers: [], answerers: {}, isUsed: false };
+			this.creatingOffer = false; // release flag
+		});
+
+		return instance;
+	}
+	/** @param {Error} error @param {string} incl @param {number} level @param {'includes' | 'startsWith'} searchMode (Prefer 'startsWith' for performance) */
+	#logAndOrIgnore(error, incl = '', level = 2, searchMode = 'includes') { // if false => log it fully, if true => ignore it (message logged or ignored based on level)
+		if (searchMode[0] === 'i' && !error.message.includes(incl)) return false;
+		else if (!error.message.startsWith(incl)) return false;
+		if (this.verbose >= level) console.info(`%cOfferManager => ${error.message}`, LOG_CSS.PEER_STORE);
+		return true;
+	}
+	#onError = (error) => {
+		if (this.verbose < 1) return; // avoid logging
+		// PRODUCTION (SimplePeer ERRORS) --|
+		if (this.#logAndOrIgnore(error, 'Ice connection failed', 2)) return;
+		if (this.#logAndOrIgnore(error, 'Connection failed', 2)) return;
+		// --PRODUCTION ----------------- --|
+
+		if (this.#logAndOrIgnore(error, 'Remote transport instance', 3, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Simulated failure', 4, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'No peer found', 4, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Missing transport instance', 2, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Failed to create answer', 2, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'Transport instance', 3, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'cannot signal after peer is destroyed', 3, 'startsWith')) return;
+		if (this.#logAndOrIgnore(error, 'No pending', 3)) return;
+		if (this.#logAndOrIgnore(error, 'is already linked', 3)) return;
+		if (this.#logAndOrIgnore(error, 'There is already a pending', 3)) return;
+		if (this.#logAndOrIgnore(error, 'closed the connection', 3)) return;
+		if (this.#logAndOrIgnore(error, 'No transport instance found for id:', 3)) return;
+
+		if (this.verbose > 0) console.error(`transportInstance ERROR => `, error.stack);
+	};
+	/** @param {string} remoteId @param {{type: 'answer', sdp: Record<string, string>}} signal @param {string} offerHash @param {number} timestamp receptionTimestamp */
+	addSignalAnswer(remoteId, signal, offerHash, timestamp) {
+		if (!signal || signal.type !== 'answer' || !offerHash) return; // ignore non-answers or missing offerHash
+		if (!this.offers[offerHash] || this.offers[offerHash].answerers[remoteId]) return; // already have an answer from this peerId
+		this.offers[offerHash].answerers[remoteId] = true; // mark as having answered - one answer per peerId
+		this.offers[offerHash].answers.push({ peerId: remoteId, signal, timestamp });
+		if (this.verbose > 3) console.log(`(OfferManager) Added answer from ${remoteId} for offer ${offerHash}`);
+	}
+	/** @param {string} remoteId @param {{type: 'offer' | 'answer', sdp: Record<string, string>}} signal @param {string} [offerHash] offer only */
+	getTransportInstanceForSignal(remoteId, signal, offerHash) {
+		try {
+			if (!signal || !signal.type || !signal.sdp) throw new Error('Wrong remote SDP provided');
+			
+			const { type, sdp } = signal;
+			if (type !== 'offer' && type !== 'answer') throw new Error('Invalid remote SDP type');
+			if (type === 'offer' && !sdp) throw new Error('No SDP in the remote SDP offer');
+			if (type === 'answer' && !sdp) throw new Error('No SDP in the remote SDP answer');
+			
+			if (type === 'answer') { // NEED TO FIND THE PENDING OFFERER INSTANCE
+				const instance = offerHash ? this.offers[offerHash]?.offererInstance : null;
+				if (!instance) throw new Error('No pending offer found for the given offer hash to accept the answer');
+				return instance;
+			}
+			
+			// type === 'offer' => CREATE ANSWERER INSTANCE
+			const instance = new TRANSPORTS.PEER({ initiator: false, trickle: false, wrtc, config: { iceServers: this.stunUrls } });
+			instance.on('error', (error) => this.#onError(error));
+			instance.on('signal', (data) => this.onSignalAnswer(remoteId, data, offerHash));
+			instance.on('connect', () => this.onConnect(remoteId, instance));
+			return instance;
+		} catch (error) {
+			if (error.message.startsWith('No pending offer found') && this.verbose < 2) return null; // avoid logging
+			if (this.verbose > 1 && error.message.startsWith('No pending offer found')) return console.info(`%c${error.message}`, LOG_CSS.PEER_STORE);
+			if (this.verbose > 0) console.error(error.stack);
+		}
+	}
+	destroy() {
+		for (const offerHash in this.offers) this.offers[offerHash].offererInstance?.destroy();
+	}
+}