@leofcoin/peernet 1.2.30 → 3.0.0

package/README.md

@@ -10,6 +10,19 @@ Peer-to-peer networking for Leofcoin and distributed applications.
 
 ## Installation
 
+### Breaking content-address format in 2.0
+
+Peernet 2.x uses `@leofcoin/codec-format-interface` 2.x. All generated content
+addresses use canonical `codec → digest byte length → digest` headers. Length-first
+hashes are not supported by the hash parser. Stored 1.x content-address indexes
+and linked manifests are not automatically migrated or rewritten.
+
+Upgrade all message producers and consumers together. For a chain deployment,
+coordinate the messages, workers, browser node and genesis migration before
+starting against new state. Back up existing stores and owner identities; this
+package does not delete or reset them. Do not mix old content-addressed chainstate
+with the new format or treat an installation update as a completed network reset.
+
 ```sh
 npm install @leofcoin/peernet
 ```

package/docs/automatic-transport.md

@@ -0,0 +1,37 @@
+# Peernet 3: automatic relay discovery
+
+Peernet 3 adopts the published `@netpeer/swarm@0.10.0` transport. Normal nodes keep
+the same startup API and configured discovery stars; no WebTransport URL, relay
+secret, public certificate or extra relay process is required on ordinary peers.
+Explicit `transport` restrictions/overrides remain supported.
+
+Release verification builds both Node and browser bundles, keeps native transport
+loaders out of browser resolution, cleans stale generated chunks, and tests a
+packed artifact in a clean npm installation with registry-only dependencies.
+
+This is a major release because the supported Node runtime moves from 19+ to
+**24.15+**, matching the new native backend and Leofcoin launcher. The canonical
+codec-first message format from peernet 2 is unchanged. This release does not
+regenerate genesis, change allocations, replace identities, or delete stores.
+
+## Operators
+
+Upgrade discovery infrastructure and peer software together for the new fallback
+handshakes. Public stars running swarm 0.10 can host their relay within the star
+process and advertise it only after QUIC is listening. Existing DNS, trusted TLS
+and UDP firewall configuration are infrastructure prerequisites, not client setup.
+
+WebRTC remains the default direct transport. A ready relay is discovered from the
+configured star and used on fallback, with tickets requested over that same star
+connection. Circuit fallback also requires an actual reciprocal handshake before
+reporting a peer connected; larger circuit payloads use shared PeerCore chunking.
+
+Transport connectivity is not proof of chain synchronization or finality. Check
+real block/state synchronization and finalized transactions after public rollout.
+
+## Leofcoin release order
+
+Publish peernet 3 only after review and build/tests. Then update chain's peernet
+minimum to `^3.0.0` using the actual npm registry metadata and regenerate the
+monorepo lockfile. Rebuild and verify a standalone launcher install before
+publishing chain/launch-chain. Do not commit local tarball or Git overrides.

package/exports/browser/{browser-DvU1xNFS.js → browser-CCfR9KOM.js}

@@ -1,4 +1,4 @@
-import { m as getDefaultExportFromCjs } from './identity-CYVPDmkf.js';
+import { m as getDefaultExportFromCjs } from './identity-Cf8KKnho.js';
 
 function _mergeNamespaces(n, m) {
 	m.forEach(function (e) {

package/exports/browser/{client-86Tnax66.js → client-C_pBoi1g.js}

@@ -1,5 +1,5 @@
-import { L as LittlePubSub, d as deflate_1, i as inflate_1, c as createDebugger } from './peernet-CbI0-jFn.js';
-import './identity-CYVPDmkf.js';
+import { L as LittlePubSub, d as deflate_1, i as inflate_1, c as createDebugger } from './peernet-Db43ag2D.js';
+import './identity-Cf8KKnho.js';
 import 'crypto';
 import './value-C3vAp-wb.js';
 
@@ -232,7 +232,7 @@ class SocketRequestClient {
             const init = async () => {
                 // @ts-ignore
                 if (!globalThis.WebSocket && !this.#experimentalWebsocket)
-                    globalThis.WebSocket = (await import('./browser-DvU1xNFS.js').then(function (n) { return n.b; })).default.w3cwebsocket;
+                    globalThis.WebSocket = (await import('./browser-CCfR9KOM.js').then(function (n) { return n.b; })).default.w3cwebsocket;
                 const client = new WebSocket(this.#url, this.#protocol);
                 if (this.#experimentalWebsocket) {
                     client.addEventListener('error', this.onerror);
@@ -819,8 +819,61 @@ class WebRTCPeer {
     }
 }
 
-const getWebTransportCtor = () => {
+// WebTransport streams carry bytes, not application message boundaries.
+const MAX_FRAME_BYTES = 64 * 1024;
+const encodeFrame = (payload) => {
+    if (!(payload instanceof Uint8Array) || !payload.length || payload.length > MAX_FRAME_BYTES) {
+        throw new Error('invalid transport frame length');
+    }
+    const frame = new Uint8Array(payload.length + 4);
+    new DataView(frame.buffer).setUint32(0, payload.length);
+    frame.set(payload, 4);
+    return frame;
+};
+class FrameReader {
+    constructor(reader) { this.reader = reader; this.chunk = new Uint8Array(); this.offset = 0; }
+    async exact(length, allowEnd = false) {
+        const result = new Uint8Array(length);
+        let written = 0;
+        while (written < length) {
+            if (this.offset === this.chunk.length) {
+                const { done, value } = await this.reader.read();
+                if (done) {
+                    if (allowEnd && written === 0)
+                        return null;
+                    throw new Error('truncated transport frame');
+                }
+                this.chunk = value;
+                this.offset = 0;
+                if (!value?.length)
+                    continue;
+            }
+            const count = Math.min(length - written, this.chunk.length - this.offset);
+            result.set(this.chunk.subarray(this.offset, this.offset + count), written);
+            this.offset += count;
+            written += count;
+        }
+        return result;
+    }
+    async read() {
+        const header = await this.exact(4, true);
+        if (!header)
+            return null;
+        const length = new DataView(header.buffer).getUint32(0);
+        if (!length || length > MAX_FRAME_BYTES)
+            throw new Error('invalid transport frame length');
+        return this.exact(length);
+    }
+}
+const jsonBytes = (value) => new TextEncoder().encode(JSON.stringify(value));
+const parseJson = (bytes) => JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+
+const getWebTransportCtor = async () => {
     const candidate = globalThis;
+    if (!candidate.WebTransport && candidate.process?.versions?.node) {
+        const { WebTransport } = await import('@fails-components/webtransport');
+        return WebTransport;
+    }
     if (!candidate.WebTransport) {
         throw new Error('WebTransport is not available in this runtime');
     }
@@ -854,7 +907,12 @@ class WebTransportPeer {
             kind: 'webtransport-bidi',
             isConnected: () => this.connected,
             sendRaw: (payload) => {
-                void this.#sendRaw(payload);
+                void this.#sendRaw(payload).catch(error => {
+                    if (!this.#destroyed) {
+                        this.#emit('error', error);
+                        this.destroy();
+                    }
+                });
             }
         }, {
             maxMessageSize: MAX_MESSAGE_SIZE,
@@ -865,7 +923,7 @@ class WebTransportPeer {
             }
         });
         queueMicrotask(() => {
-            void this.#open(options.url);
+            void this.#open(options);
         });
     }
     #createMessageId() {
@@ -892,41 +950,55 @@ class WebTransportPeer {
         for (const handler of listeners)
             handler(...args);
     }
-    async #open(url) {
+    async #open(options) {
         try {
-            const WebTransportCtor = getWebTransportCtor();
-            const session = new WebTransportCtor(url);
+            const ticket = await options.getTicket();
+            if (this.#destroyed)
+                return;
+            const WebTransportCtor = await getWebTransportCtor();
+            const session = new WebTransportCtor(options.url);
             this.#session = session;
+            void session.closed.then(() => this.destroy(), error => {
+                if (!this.#destroyed) {
+                    this.#emit('error', error);
+                    this.destroy();
+                }
+            });
             await session.ready;
+            if (this.#destroyed)
+                return;
             const stream = (await session.createBidirectionalStream());
+            if (this.#destroyed)
+                return;
             this.#reader = stream.readable.getReader();
             this.#writer = stream.writable.getWriter();
+            const frames = new FrameReader(this.#reader);
+            await this.#writer.write(encodeFrame(jsonBytes({ protocol: 'swarm-relay/1', ticket })));
+            const ready = parseJson(await frames.read());
+            if (ready.protocol !== 'swarm-relay/1' || ready.peerId !== this.peerId || String(ready.version) !== this.version) {
+                throw new Error('invalid WebTransport relay handshake');
+            }
+            if (this.#destroyed)
+                return;
             this.#connected = true;
             this.#emit('connect');
-            void this.#readLoop();
-            void session.closed.catch((error) => {
-                if (this.#destroyed)
-                    return;
-                this.#emit('error', error instanceof Error ? error : new Error(String(error)));
-            });
+            void this.#readLoop(frames);
         }
         catch (error) {
             this.#emit('error', error instanceof Error ? error : new Error(String(error)));
             this.destroy();
         }
     }
-    async #readLoop() {
+    async #readLoop(frames) {
         const reader = this.#reader;
         if (!reader)
             return;
         try {
             while (!this.#destroyed) {
                 // eslint-disable-next-line no-await-in-loop
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
+                const value = await frames.read();
                 if (!value)
-                    continue;
+                    break;
                 this.bw.down += value.length;
                 this.#emit('data', value);
             }
@@ -942,7 +1014,7 @@ class WebTransportPeer {
     async #sendRaw(payload) {
         if (!this.#writer)
             throw new Error('WebTransport writer is not ready');
-        await this.#writer.write(payload);
+        await this.#writer.write(encodeFrame(payload));
     }
     on(event, handler) {
         const listeners = this.#listeners.get(event) ?? new Set();
@@ -972,13 +1044,13 @@ class WebTransportPeer {
         this.#destroyed = true;
         this.#connected = false;
         try {
-            void this.#reader?.cancel?.();
+            void this.#reader?.cancel?.().catch(() => { });
         }
         catch (e) { }
         this.#reader?.releaseLock?.();
         this.#reader = null;
         try {
-            void this.#writer?.close?.();
+            void this.#writer?.close?.().catch(() => { });
         }
         catch (e) { }
         this.#writer?.releaseLock?.();
@@ -1006,6 +1078,7 @@ class CircuitPeer {
     #destroyed = false;
     #connected = false;
     #sendViaCircuit;
+    #core;
     initiator = true;
     peerId;
     channelName;
@@ -1019,12 +1092,40 @@ class CircuitPeer {
         this.channelName = `circuit:${options.from}:${options.to}`;
         this.version = String(options.version);
         this.#sendViaCircuit = options.sendViaCircuit;
-        setTimeout(() => {
-            if (this.#destroyed)
-                return;
-            this.#connected = true;
-            this.#emit('connect');
-        }, 0);
+        this.#core = new PeerCore({
+            kind: 'circuit',
+            isConnected: () => this.connected,
+            sendRaw: data => {
+                void this.#sendViaCircuit({ id: this.#createMessageId(), data: Array.from(data) }).catch(error => {
+                    if (this.#destroyed)
+                        return;
+                    this.#emit('error', error);
+                    this.destroy();
+                });
+            }
+        }, {
+            // JSON byte arrays expand up to four characters per byte. Keep the whole
+            // WebSocket frame below its default 64 KiB limit, including wrapper/ID.
+            maxMessageSize: 14_000,
+            compressionThreshold: 0.98,
+            getPubSub,
+            onPayloadSend: bytes => { this.bw.up += bytes; }
+        });
+        queueMicrotask(async () => {
+            try {
+                await options.handshake();
+                if (this.#destroyed)
+                    return;
+                this.#connected = true;
+                this.#emit('connect');
+            }
+            catch (error) {
+                if (this.#destroyed)
+                    return;
+                this.#emit('error', error);
+                this.destroy();
+            }
+        });
     }
     #createMessageId() {
         const randomUUID = globalThis.crypto?.randomUUID;
@@ -1054,43 +1155,21 @@ class CircuitPeer {
         // Circuit transport does not use SDP/ICE signaling.
     }
     send(data, id = this.#createMessageId()) {
+        if (new TextEncoder().encode(id).length > 1024) {
+            this.#emit('error', new Error('circuit message id exceeds 1024 bytes'));
+            return;
+        }
         if (this.#destroyed) {
             this.#emit('error', new Error('circuit peer is destroyed'));
             return;
         }
-        this.bw.up += data.length;
-        void this.#sendViaCircuit({ id, data: Array.from(data) }).catch((error) => {
-            this.#emit('error', error instanceof Error ? error : new Error(String(error)));
-        });
+        this.#core.send(data, id);
     }
     request(data, id = this.#createMessageId()) {
-        const pubsub = getPubSub();
-        if (!pubsub) {
-            return Promise.reject(new Error('globalThis.pubsub is not available'));
+        if (new TextEncoder().encode(id).length > 1024) {
+            return Promise.reject(new Error('circuit message id exceeds 1024 bytes'));
         }
-        return new Promise((resolve, reject) => {
-            let timeout;
-            let settled = false;
-            const finish = (fn) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timeout);
-                try {
-                    pubsub.unsubscribe(id, onResponse);
-                }
-                catch (e) { }
-                fn();
-            };
-            const onResponse = ({ data: response }) => {
-                finish(() => resolve(response));
-            };
-            timeout = setTimeout(() => {
-                finish(() => reject(new Error(`request for ${id} timed out`)));
-            }, 30_000);
-            pubsub.subscribe(id, onResponse);
-            this.send(data, id);
-        });
+        return this.#core.request(data, id);
     }
     async getNetworkStats() {
         return null;
@@ -1163,6 +1242,8 @@ class Client {
     #fallbackCircuitMethod = 'swarm:fallback:send';
     #testHooks;
     #webTransportUrlTemplate;
+    #discoverWebTransport = true;
+    #relayUrls = new WeakMap();
     #circuitHandlers = new Map();
     #pendingCircuitRequests = new Map();
     #circuitRequestTimeoutMs = 30_000;
@@ -1201,7 +1282,9 @@ class Client {
             ? options.transport.kinds
             : options.transport?.kind
                 ? [options.transport.kind]
-                : ['webrtc', 'webtransport'];
+                : (options.transport?.webtransport?.urlTemplate
+                    ? ['webrtc', 'webtransport']
+                    : ['webrtc']);
         this.#supportedTransports = new Set(this.#normalizeTransportKinds(configuredKinds));
         if (!this.#supportedTransports.size)
             this.#supportedTransports.add('webrtc');
@@ -1212,6 +1295,11 @@ class Client {
                 ? 'webrtc'
                 : 'webtransport';
         this.#webTransportUrlTemplate = options.transport?.webtransport?.urlTemplate;
+        this.#discoverWebTransport = !options.transport?.kind && !options.transport?.kinds ||
+            !!options.transport?.kinds?.includes('webtransport') || options.transport?.kind === 'webtransport';
+        if (this.#discoverWebTransport && (typeof globalThis.WebTransport === 'function' || globalThis.process?.versions?.node)) {
+            this.#supportedTransports.add('webtransport');
+        }
         const wrtcBackend = options.transport?.webrtc?.backend ||
             globalThis.process?.env?.NETPEER_SWARM_WRTC_BACKEND ||
             'vandeurenglenn';
@@ -1229,6 +1317,9 @@ class Client {
         if (options?.retry)
             this.#retryOptions = { ...this.#retryOptions, ...options.retry };
         this.#circuitHandlers.set(this.#fallbackCircuitMethod, (payload, context) => this.#handleFallbackCircuitPayload(payload, context));
+        this.#circuitHandlers.set('swarm:fallback:hello', () => ({
+            peerId: this.peerId, version: this.version, encoding: 'peer-core/1'
+        }));
         if (!this.#testHooks?.skipInit) {
             this._init();
         }
@@ -1367,6 +1458,30 @@ class Client {
         const onServerData = (message) => {
             globalThis.pubsub.publish('server:data', message);
         };
+        const onRelayReady = (message) => {
+            if (!this.#discoverWebTransport || message?.protocol !== 'swarm-relay/1' || typeof message.url !== 'string')
+                return;
+            let url;
+            try {
+                url = new URL(message.url);
+            }
+            catch {
+                return;
+            }
+            if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+                return;
+            if (this.#relayUrls.get(starConnection) === url.href)
+                return;
+            this.#relayUrls.set(starConnection, url.href);
+            this.#supportedTransports.add('webtransport');
+            // Update capabilities on this same authenticated star connection. The
+            // server sends relay metadata before its peer snapshot, so fallback can
+            // resolve a real endpoint without users configuring transport URLs.
+            starConnection.send({ url: 'join', params: {
+                    version: this.version, peerId: this.peerId,
+                    transport: { kind: this.#preferredTransportKind, kinds: [...this.#supportedTransports] }
+                } });
+        };
         starConnection.pubsub.subscribe('peer:joined', onPeerJoined);
         starConnection.pubsub.subscribe('peer:left', onPeerLeft);
         starConnection.pubsub.subscribe('star:joined', onStarJoined);
@@ -1374,6 +1489,7 @@ class Client {
         starConnection.pubsub.subscribe('signal', onSignal);
         starConnection.pubsub.subscribe('circuit', onCircuit);
         starConnection.pubsub.subscribe('server:data', onServerData);
+        starConnection.pubsub.subscribe('relay:ready', onRelayReady);
         this.#starListeners[starId] = [
             { topic: 'peer:joined', handler: onPeerJoined },
             { topic: 'peer:left', handler: onPeerLeft },
@@ -1381,7 +1497,8 @@ class Client {
             { topic: 'star:left', handler: onStarLeft },
             { topic: 'signal', handler: onSignal },
             { topic: 'circuit', handler: onCircuit },
-            { topic: 'server:data', handler: onServerData }
+            { topic: 'server:data', handler: onServerData },
+            { topic: 'relay:ready', handler: onRelayReady }
         ];
     }
     #starJoined = (id) => {
@@ -1587,12 +1704,12 @@ class Client {
             peer = this.#createRTCPeerConnection(peerId, attempt.star, attempt.version, attempt.initiator);
         }
         else if (transportKind === 'webtransport') {
-            const url = this.#resolveWebTransportUrl(peerId);
+            const url = this.#resolveWebTransportUrl(peerId, attempt.star);
             if (!url) {
                 this.#advanceTransportAttempt(peerId);
                 return;
             }
-            peer = this.#createWebTransportConnection(peerId, url, attempt.version);
+            peer = this.#createWebTransportConnection(peerId, url, attempt.version, attempt.star);
         }
         else {
             peer = this.#createCircuitConnection(peerId, attempt.version);
@@ -1639,7 +1756,25 @@ class Client {
         if (!peer) {
             peer = this.#createCircuitConnection(context.from, this.version);
         }
-        this.#noticeMessage(decoded.data, decoded.id, context.from, peer);
+        if (!peer)
+            throw new Error('circuit peer unavailable');
+        if (!peer.connected) {
+            const waitingPeer = peer;
+            await new Promise((resolve, reject) => {
+                const finish = (error) => {
+                    clearTimeout(timer);
+                    waitingPeer.off('connect', onConnect);
+                    waitingPeer.off('close', onClose);
+                    error ? reject(error) : resolve();
+                };
+                const onConnect = () => finish();
+                const onClose = () => finish(new Error('circuit peer closed during handshake'));
+                const timer = setTimeout(() => finish(new Error('circuit handshake timed out')), this.#transportConnectTimeoutMs);
+                waitingPeer.on('connect', onConnect);
+                waitingPeer.on('close', onClose);
+            });
+        }
+        this.#peerData(peer, decoded.data);
         return { ok: true };
     }
     #createCircuitId() {
@@ -1697,15 +1832,22 @@ class Client {
                 this.#pendingCircuitRequests.delete(id);
                 reject(new Error(`circuit request for ${id} timed out`));
             }, timeoutMs);
-            this.#pendingCircuitRequests.set(id, { resolve, reject, timeout });
-            this.#sendCircuit(starConnection, {
-                to: peerId,
-                from: this.peerId,
-                id,
-                phase: 'request',
-                method,
-                data: this.#encodeCircuitData(data)
-            });
+            this.#pendingCircuitRequests.set(id, { resolve, reject, timeout, peerId, starConnection });
+            try {
+                this.#sendCircuit(starConnection, {
+                    to: peerId,
+                    from: this.peerId,
+                    id,
+                    phase: 'request',
+                    method,
+                    data: this.#encodeCircuitData(data)
+                });
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                this.#pendingCircuitRequests.delete(id);
+                reject(error);
+            }
         });
     }
     #inComingCircuit = async ({ from, to, id, phase, method, data, error }, starConnection) => {
@@ -1715,6 +1857,10 @@ class Client {
             const pending = this.#pendingCircuitRequests.get(id);
             if (!pending)
                 return;
+            if (pending.starConnection !== starConnection)
+                return;
+            if (from !== pending.peerId && !(from === 'server' && error))
+                return;
             clearTimeout(pending.timeout);
             this.#pendingCircuitRequests.delete(id);
             if (error) {
@@ -1788,17 +1934,16 @@ class Client {
     connectWebTransport(peerId, url) {
         this.#createWebTransportConnection(peerId, url, this.version);
     }
-    #resolveWebTransportUrl(peerId) {
-        const urlTemplate = this.#webTransportUrlTemplate;
+    #resolveWebTransportUrl(peerId, starConnection) {
+        const urlTemplate = this.#webTransportUrlTemplate || (starConnection && this.#relayUrls.get(starConnection));
         if (!urlTemplate) {
-            console.warn('WebTransport requires transport.webtransport.urlTemplate in client options');
             return null;
         }
         return urlTemplate
             .replace('{peerId}', encodeURIComponent(peerId))
             .replace('{selfId}', encodeURIComponent(this.peerId));
     }
-    #createWebTransportConnection(peerId, url, version) {
+    #createWebTransportConnection(peerId, url, version, starConnection) {
         if (this.#connections[peerId]) {
             debug(`peer ${peerId} already connected`);
             return null;
@@ -1823,7 +1968,27 @@ class Client {
             from: this.peerId,
             to: peerId,
             version,
-            url
+            url,
+            getTicket: async () => {
+                const star = starConnection || this.#pickStarConnection();
+                if (!star)
+                    throw new Error('no connected star available for WebTransport ticket');
+                let timer;
+                try {
+                    const response = await Promise.race([
+                        star.request({ url: 'webtransport-ticket', params: { from: this.peerId, to: peerId } }),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new Error('WebTransport ticket request timed out')), this.#transportConnectTimeoutMs);
+                        })
+                    ]);
+                    if (typeof response?.ticket !== 'string')
+                        throw new Error('star did not authorize WebTransport relay');
+                    return response.ticket;
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
         });
         peer.on('connect', () => this.#peerConnect(peer));
         peer.on('close', () => this.#peerClose(peer));
@@ -1857,6 +2022,12 @@ class Client {
             from: this.peerId,
             to: peerId,
             version,
+            handshake: async () => {
+                const response = await this.circuitRequest(peerId, 'swarm:fallback:hello', undefined, this.#transportConnectTimeoutMs);
+                if (response?.peerId !== peerId || String(response?.version) !== String(version) || response.encoding !== 'peer-core/1') {
+                    throw new Error('invalid circuit handshake response');
+                }
+            },
             sendViaCircuit: (payload) => this.circuitRequest(peerId, this.#fallbackCircuitMethod, payload)
         });
         peer.on('connect', () => this.#peerConnect(peer));
@@ -2173,6 +2344,11 @@ class Client {
         peer.destroy();
     };
     async close() {
+        for (const pending of this.#pendingCircuitRequests.values()) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('client closed'));
+        }
+        this.#pendingCircuitRequests.clear();
         for (const peerId of this.#peerTransportAttempts.keys()) {
             this.#clearTransportAttempt(peerId);
         }