@optimystic/db-p2p 1.0.0-beta.3 → 1.0.0

package/src/libp2p-node-base.ts

@@ -18,10 +18,13 @@ import { BlockStorage } from './storage/block-storage.js';
 import { MemoryRawStorage } from './storage/memory-storage.js';
 import { withReadCache, type ResolvedReadCache } from './storage/with-read-cache.js';
 import type { IRawStorage } from './storage/i-raw-storage.js';
+import type { IKVStore } from './storage/i-kv-store.js';
+import { MemoryKVStore } from './storage/memory-kv-store.js';
+import { KvUnderReplicationLedger } from './repo/kv-under-replication-ledger.js';
 import { latestClaimFromArchive, servableProof, type ArchiveServingRepo } from './storage/block-archive.js';
 import { createServedRepoProxy } from './repo/served-repo-proxy.js';
 import { seedOwnedBlocksFromStorage } from './owned-block-seed.js';
-import { clusterMember, type ReconcileBlockCallback, type CommitCertificateSink, type DeriveExpectedClusterCallback } from './cluster/cluster-repo.js';
+import { clusterMember, type ReconcileBlockCallback, type CommitCertificateSink, type CommittedHoldersSink, type DeriveExpectedClusterCallback } from './cluster/cluster-repo.js';
 import { createReconcileBlock } from './cluster/reconcile-block.js';
 import { resolveClusterPolicy, type ClusterPolicyOptions } from './cluster/cluster-policy.js';
 import { assertClusterSizeCoupling } from './cluster/cluster-size-coupling.js';
@@ -34,8 +37,11 @@ import { ClusterClient } from './cluster/client.js';
 import type { IRepo, ICluster, ITransactionValidator, BlockId, IBlockChangeNotifier } from '@optimystic/db-core';
 import type { ITransactionStateStore } from './cluster/i-transaction-state-store.js';
 import { networkManagerService, type NetworkManagerService } from './network/network-manager-service.js';
+import { assertCircuitRelayTransport, assertRelayAddrsAdvertisable, planRelayListenAddrs, superviseRelayReservations } from './network/relay-reservation.js';
 import type { SpreadOnChurnConfig, SpreadOnChurnMonitor } from './cluster/spread-on-churn.js';
 import { BlockTransferCoordinator } from './cluster/block-transfer.js';
+import { pushBlockToPeers } from './cluster/block-transfer-service.js';
+import { UnderReplicationDrain, type UnderReplicationDrainConfig } from './repo/under-replication-drain.js';
 import type { RebalanceMonitorConfig } from './cluster/rebalance-monitor.js';
 import { fretService, Libp2pFretService } from 'p2p-fret';
 import { syncService } from './sync/service.js';
@@ -85,6 +91,7 @@ import {
 	type PushStateInit,
 	type NotificationVerifier,
 } from '@optimystic/db-core';
+import { routingKeyForBlock } from '@optimystic/db-core';
 import { PartitionDetector } from './cluster/partition-detector.js';
 import { assertSuperMajorityCoupling } from './cluster/supermajority-coupling.js';
 import { createLogger } from './logger.js';
@@ -154,6 +161,9 @@ const wiringLog = createLogger('node-wiring');
  */
 export type RawStorageProvider = IRawStorage | (() => IRawStorage);
 
+/** Factory function or instance for the node's durable key-value store; see {@link NodeOptions.kvStore}. */
+export type KVStoreProvider = IKVStore | (() => IKVStore);
+
 /**
  * `ClusterPolicyOptions` is intersected in, not restated: `resolveClusterPolicy` consumes those
  * fields structurally, so a second copy of the shape here would let a newly added knob compile and
@@ -198,7 +208,22 @@ export type NodeOptions = ClusterPolicyOptions & {
 	relayServerInit?: CircuitRelayServerInit;
 	/** Storage provider - either an IRawStorage instance or a factory function. Defaults to MemoryRawStorage if not provided. See {@link RawStorageProvider} for the ownership rule. */
 	storage?: RawStorageProvider;
-	/** Override libp2p listen multiaddrs. */
+	/**
+	 * Durable key-value store for node-local state that must survive a restart — today, the
+	 * under-replication ledger (which blocks this node acknowledged below full replication, and who
+	 * is still missing each). An instance or a factory, the same shape as {@link NodeOptions.storage}.
+	 * Absent → an in-memory store, with a `node-wiring` warning: the ledger still works, but what it
+	 * records is lost on restart. `FileKVStore` from `@optimystic/db-p2p-storage-fs` may share
+	 * `FileRawStorage`'s base path; see its README.
+	 */
+	kvStore?: KVStoreProvider;
+	/**
+	 * Override libp2p listen multiaddrs. An entry naming a relay (`<relay address>/p2p/<relay id>/p2p-circuit`)
+	 * is not handed to libp2p as written: the node listens on a bare `/p2p-circuit` and keeps the
+	 * reservation on that relay itself (`superviseRelayReservation` in `network/relay-reservation.ts`).
+	 * Such an entry needs a circuit-relay transport and cannot be combined with {@link NodeOptions.announceAddrs},
+	 * which would hide the circuit address; both are rejected before anything starts.
+	 */
 	listenAddrs?: string[];
 	/**
 	 * Multiaddrs to advertise INSTEAD OF the listen addrs. For a node behind a NAT / reverse proxy /
@@ -253,6 +278,18 @@ export type NodeOptions = ClusterPolicyOptions & {
 	 */
 	rebalance?: Partial<RebalanceMonitorConfig> & { enabled?: boolean };
 
+	/**
+	 * Under-replication drain tuning. The drain sends the copies the under-replication ledger says
+	 * this node still owes — blocks it acknowledged below full replication — to the missing members
+	 * as they become reachable, and fires `onBlockDurabilityReached` on the node's `storageRepo` when
+	 * a block finally has every copy. It needs only the key network and the node's own storage, so it
+	 * runs whether or not arachnode/FRET rebalancing is enabled. Absent -> enabled with defaults (see
+	 * `UnderReplicationDrainConfig`). Set { enabled: false } to leave the ledger unsent on this node.
+	 * The push deadlines are separate because they bound the wire, not the pass: `pushDialTimeoutMs`
+	 * (default 3000) and `pushResponseTimeoutMs` (default 10000), the same caps spread-on-churn uses.
+	 */
+	underReplicationDrain?: Partial<UnderReplicationDrainConfig> & { enabled?: boolean; pushDialTimeoutMs?: number; pushResponseTimeoutMs?: number };
+
 	/** Transaction validator for cluster consensus */
 	validator?: ITransactionValidator;
 
@@ -394,6 +431,24 @@ function resolveStorage(provider: RawStorageProvider | undefined, networkName: s
 	return withReadCache(storage, `node:${networkName}`);
 }
 
+/**
+ * Resolve the node's durable key-value store, beside {@link resolveStorage}. The memory fallback is
+ * LOUD on purpose: a silent one would look like the under-replication ledger works and then fail the
+ * one case it exists for — a shortfall recorded before a restart being there after it.
+ *
+ * NOTE: with a key-value store always present, `PersistentTransactionStateStore` is now
+ * constructible here from the same instance. Wiring it changes commit-retry recovery behaviour and
+ * belongs to `feat-long-lived-pend-completes-as-members-appear`, not to this resolver;
+ * `NodeOptions.transactionStateStore` stays the only way it is supplied.
+ */
+function resolveKvStore(provider: KVStoreProvider | undefined): IKVStore {
+	if (provider !== undefined) {
+		return typeof provider === 'function' ? provider() : provider;
+	}
+	wiringLog('WARN: no kvStore supplied — using an in-memory store. The under-replication ledger (blocks this node acknowledged before every cohort member held them) will NOT survive a restart, so copies owed at shutdown are never sent. Supply NodeOptions.kvStore (e.g. FileKVStore) to keep it.');
+	return new MemoryKVStore();
+}
+
 /**
  * Resolve the full FRET engine the cohort-topic host needs.
  *
@@ -435,6 +490,8 @@ export async function createLibp2pNodeBase(
 	}
 ): Promise<OptimysticNode> {
 	const { storage: rawStorage, lease } = resolveStorage(options.storage, options.networkName);
+	const kvStore = resolveKvStore(options.kvStore);
+	const underReplicationLedger = new KvUnderReplicationLedger(kvStore);
 
 	// Create placeholder restore callback (will be replaced after node starts)
 	let restoreCallback: RestoreCallback = async (_blockId, _rev?) => {
@@ -487,7 +544,26 @@ export async function createLibp2pNodeBase(
 
 	const nodePrivateKey = options.privateKey ?? await generateKeyPair('Ed25519');
 
-	const listenAddrs = options.listenAddrs ?? defaults.listenAddrs;
+	// A listen address naming a relay (`<relay>/p2p/<id>/p2p-circuit`, the only shape a phone or browser
+	// can take) is handed to libp2p as a bare `/p2p-circuit` and the relay is supervised by this node
+	// instead, so the reservation survives relay restarts, dropped relay connections and libp2p's own
+	// renewal. See `network/relay-reservation.ts` for why the configured shape cannot recover.
+	// NOTE: accepted tradeoff — a bare `/p2p-circuit` listener also turns on libp2p's relay discovery,
+	// whose topology handler can reserve on ANY connected peer serving the relay hop protocol (every
+	// Optimystic node started with `relay: true` does), and that reservation takes the pending slot
+	// meant for the named relay. The node then stays reachable, but through that other relay, so a
+	// partner that enrolled its circuit address through the named relay cannot dial it until that
+	// reservation drops; the supervisor reports it as `relay-reservation:slot-taken` and retries at its
+	// backoff cap. It happens only when a relay-only node is directly connected to a second relay server,
+	// and Sereus runs with the same behaviour. Revisit on a deployment that connects relay-only nodes to
+	// more than one relay server, or on the libp2p upgrade below.
+	// NOTE: circuit-relay-v2 >= 4.2 (needs @libp2p/interface ^3.3) refreshes reservations in place and
+	// re-applies a configured reservation for its own relay; when the libp2p line moves, revisit keeping
+	// the host's configured address and re-requesting with 'configured', which drops the rewrite and the
+	// discovery side effect.
+	const relayPlan = planRelayListenAddrs(options.listenAddrs ?? defaults.listenAddrs);
+	assertRelayAddrsAdvertisable(relayPlan.supervisedRelays, options.announceAddrs);
+	const listenAddrs = relayPlan.listenAddrs;
 	const transports = options.transports ?? defaults.transports;
 
 	// --- cohort-topic substrate activation (opt-in; default off → today's bare behavior, zero cost) ---
@@ -544,13 +620,14 @@ export async function createLibp2pNodeBase(
 		transports,
 		connectionEncrypters: [noise()],
 		streamMuxers: [yamux()],
-		// Narrow cast confined to the `services` field: the built-in factories (identify/dcutr/…) are
-		// typed against a SECOND copy of `@libp2p/interface` pulled in transitively (via `@libp2p/crypto`),
-		// whose `Uint8Array<ArrayBuffer>` vs `<ArrayBufferLike>` PeerId/key shapes are structurally
-		// incompatible with the top-level copy — a dependency-dedup artifact, not a real mismatch. The cast
-		// stays on this field alone so the rest of `libp2pOptions` remains fully typed as `Libp2pInit`.
-		// NOTE: this cast exists ONLY because of the duplicate @libp2p/interface install; if that dedups
-		// (or on a libp2p bump) drop `as unknown as NonNullable<Libp2pInit['services']>` and type the map directly.
+		// Narrow cast confined to the `services` field, so the rest of `libp2pOptions` stays typed as
+		// `Libp2pInit`: `@libp2p/dcutr` and `@libp2p/autonat` are typed against `@libp2p/interface` 3.2.x
+		// while `libp2p` resolves 3.1.x, and the two minors disagree on `Uint8Array<ArrayBuffer>` vs
+		// `<ArrayBufferLike>` — a type-level artifact of the minor split, not a runtime mismatch.
+		// NOTE: accepted tradeoff — raising this package's `@libp2p/interface` pin to ^3.2 to drop the cast
+		// was declined: the 3.1/3.2 split is deliberate (scripts/shared-majors.cjs), and `libp2p` and its
+		// core services resolve 3.1.0 regardless, so the cast would only move. Revisit when that libp2p
+		// release line itself declares `@libp2p/interface@^3.2` or later.
 		services: ({
 			// `@libp2p/identify` is the ONE service here whose protocol id it builds itself:
 			// `Identify`/`IdentifyPush` both emit `/${protocolPrefix}/id[/push]/1.0.0`, always
@@ -643,15 +720,14 @@ export async function createLibp2pNodeBase(
 					responsibilityK: options.responsibilityK ?? 1,
 					...inboundAuthorization
 				});
-				// RepoService.checkRedirect needs the running node (network manager for the
-				// responsible-set computation, self id for the membership check, connection
-				// addrs for redirect targets). The libp2p components.libp2p proxy does NOT
-				// reliably resolve from inside a service at request time, so the node is
-				// injected explicitly post-construction via setLibp2p(node) below — the same
-				// mechanism networkManager/fret use — rather than forwarded here. checkRedirect
-				// keys the responsible set on the RAW encoded block id
-				// (getCluster(encode(blockKey)) → hashKey(encode(...))), matching the
-				// coordinator's findCluster(encode(blockId)) — same cohort, no spurious redirect.
+				// RepoService.checkRedirect needs the running node (its `keyNetwork` attachment for
+				// the responsible set, self id for the membership check, connection addrs for
+				// redirect targets). The libp2p components.libp2p proxy does NOT reliably resolve
+				// from inside a service at request time, so the node is injected explicitly
+				// post-construction via setLibp2p(node) below — the same mechanism networkManager/fret
+				// use — rather than forwarded here. checkRedirect asks the node's own key network for
+				// the block's routing key (`routingKeyForBlock`), the same call the writer and the
+				// coordinator make — one rule, so a correctly routed request is never redirected.
 				return serviceFactory({
 					registrar: components.registrar,
 					repo: repoProxy
@@ -712,6 +788,10 @@ export async function createLibp2pNodeBase(
 					capacity: 2048,
 					profile: options.fretProfile ?? ((options.bootstrapNodes?.length ?? 0) > 0 ? 'core' : 'edge'),
 					networkName: options.networkName,
+					// NOTE: FRET's `seedFromBootstraps` seeds the FIRST `/p2p/` id of each entry, so a partner's circuit
+					// address (`<relay>/p2p/<relay>/p2p-circuit/p2p/<partner>`) seeds the relay, not the partner. Harmless
+					// today: the partner is learned once its connection opens, and the relay is classified foreign. If a
+					// phone ever fails to find a partner it was given only as a circuit bootstrap, fix FRET to take the last id.
 					bootstraps: options.bootstrapNodes ?? []
 				});
 				const svc = svcFactory(components) as Libp2pFretService;
@@ -768,12 +848,18 @@ export async function createLibp2pNodeBase(
 	const wired = node.services as unknown as WiredServices;
 	wired.fret.setLibp2p(node);
 	wired.networkManager.setLibp2p(node);
-	// RepoService.checkRedirect resolves the network manager / self id / connection
+	// RepoService.checkRedirect resolves the key network / self id / connection
 	// addrs through this injected node (the components.libp2p proxy is unreliable
 	// from inside a service at request time). Done before start() so the protocol
-	// handler is live with a resolvable node from its first request.
+	// handler is live with a resolvable node from its first request; the `keyNetwork`
+	// attachment itself arrives after start(), and until then checkRedirect handles locally.
 	wired.repo.setLibp2p(node);
 
+	// A relay-naming listen address with no circuit-relay transport can never be reserved on. Checked
+	// here, before start(), so the caller sees the omission by name rather than libp2p's generic
+	// unsupported-listen-address error for the bare `/p2p-circuit` the plan substituted.
+	assertCircuitRelayTransport(node, relayPlan.supervisedRelays);
+
 	await node.start();
 
 	// Everything from here to the `return` runs against an ALREADY STARTED node (open transports,
@@ -782,6 +868,24 @@ export async function createLibp2pNodeBase(
 	// for the caller and enough to block the port for the next start attempt. So the whole post-start
 	// body rolls back: see the `catch` at the bottom of this function.
 	try {
+		// Keep every relay-naming listen address's reservation alive (see `relayPlan` above). Started
+		// first, with its stop wrapper installed before anything is awaited, so the rollback `catch`
+		// below stops it too. Awaiting the first drives keeps today's startup contract: a relay that
+		// cannot be reserved rejects node creation, naming the relay, exactly as libp2p's own
+		// `listen()` on the configured shape did. A host that would rather start offline and let the
+		// supervisor recover is a separate decision, not an option here.
+		if (relayPlan.supervisedRelays.length > 0) {
+			const relaySupervisors = superviseRelayReservations(node, relayPlan.supervisedRelays);
+			const previousStop = node.stop.bind(node);
+			node.stop = async () => {
+				try {
+					relaySupervisors.stop();
+				} finally {
+					await previousStop();
+				}
+			};
+			await relaySupervisors.awaitFirstDrives();
+		}
 
 		// Initialize peer reputation service
 		const reputation = new PeerReputationService();
@@ -867,7 +971,7 @@ export async function createLibp2pNodeBase(
 		// voting, so a self-shrunk minority-partition set cannot be voted into super-majority (see cluster-repo
 		// admitMembership). No FRET ⇒ confidence 0 ⇒ the gate fails closed for any downsize.
 		const deriveExpectedCluster: DeriveExpectedClusterCallback = async (blockId) => {
-			const peers = await keyNetwork.findCluster(new TextEncoder().encode(blockId));
+			const peers = await keyNetwork.findCluster(routingKeyForBlock(blockId));
 			let confidence = 0;
 			if (fretSvc) {
 				try {
@@ -879,6 +983,13 @@ export async function createLibp2pNodeBase(
 			return { peers: peers ?? {}, confidence };
 		};
 
+		// Who holds each commit this node holds, for the rebalance monitor (so it does not push freshly
+		// committed blocks back to the members that stored them). Late-bound: the member and coordinator
+		// are built here, the monitor much further down inside the arachnode gate — and not at all when
+		// rebalance or FRET is off, in which case reports go nowhere.
+		let committedHoldersTarget: CommittedHoldersSink | undefined;
+		const onCommittedHolders: CommittedHoldersSink = (committed) => committedHoldersTarget?.(committed);
+
 		clusterImpl = clusterMember({
 			storageRepo,
 			peerNetwork: keyNetwork,
@@ -893,6 +1004,7 @@ export async function createLibp2pNodeBase(
 			stateStore: options.transactionStateStore,
 			reconcileBlock,
 			onCommitCertificate,
+			onCommittedHolders,
 			deriveExpectedCluster
 			// `recomputeArbitratorSet` (invalidation layer-2) is intentionally NOT wired here yet: a live FRET
 			// recompute needs a churn-tolerance window so it does not false-reject legitimate certificates from
@@ -993,7 +1105,11 @@ export async function createLibp2pNodeBase(
 			// funnel. `clusterLatestCallback` alone can only tell the reader WHICH revision the cohort
 			// holds; this is what moves the bytes. Only reached once a corroborated revision exists, so a
 			// genuinely absent block still costs no archive fetch.
-			acquireBlockFromCohort: reconcileBlock
+			acquireBlockFromCohort: reconcileBlock,
+			// Records who is still missing each block of a commit acknowledged below `full`. Nothing
+			// drains it yet: sending those copies is `under-replication-drain-and-full-replication-event`.
+			underReplicationLedger,
+			onCommittedHolders
 		});
 
 		// Fail-fast coupling: the cluster member (what accepts a super-majority as sufficient) and the
@@ -1102,6 +1218,47 @@ export async function createLibp2pNodeBase(
 			};
 		}
 
+		// --- Under-replication drain: send the copies the ledger says this node still owes ---
+		// The coordinator repo above records, per block it acknowledged below `full`, who is still
+		// missing a copy; this pushes those copies as the missing members become reachable and fires
+		// the full-replication event on storageRepo when a block has every copy. Deliberately OUTSIDE
+		// the arachnode `if (fret)` gate below: it needs the key network (cohort re-resolution for an
+		// entry that could not name its members), the node's own store and dialer, and libp2p's
+		// connection events — not the fretAdapter or the restoration coordinator. It overlaps the
+		// rebalance growth arm and spread-on-churn on purpose: all three may push the same block to
+		// the same peer, and the receiver is idempotent, so no cross-monitor coordination is added.
+		// The sink it emits through is one method wide, so it can reach nothing else on the repo.
+		let underReplicationDrain: UnderReplicationDrain | undefined;
+		if ((options.underReplicationDrain?.enabled ?? true) !== false) {
+			const { enabled: _enabled, pushDialTimeoutMs, pushResponseTimeoutMs, ...drainConfig } = options.underReplicationDrain ?? {};
+			underReplicationDrain = new UnderReplicationDrain({
+				libp2p: node,
+				ledger: underReplicationLedger,
+				keyNetwork,
+				partitionDetector,
+				protocolPrefix,
+				pushBlock: (blockId, peerIds) => pushBlockToPeers(storageRepo, keyNetwork, blockId, peerIds, {
+					reason: 'replication',
+					protocolPrefix,
+					dialTimeoutMs: pushDialTimeoutMs ?? 3000,
+					responseTimeoutMs: pushResponseTimeoutMs ?? 10_000
+				}),
+				emit: (event) => storageRepo.emitBlockDurabilityReached(event)
+			}, drainConfig);
+			await underReplicationDrain.start();
+			const previousStop = node.stop.bind(node);
+			node.stop = async () => {
+				try {
+					await underReplicationDrain!.stop();
+				} finally {
+					await previousStop();
+				}
+			};
+		}
+		// Expose for tests/diagnostics (mirrors node.spreadOnChurnMonitor / node.rebalanceMonitor).
+		(node as any).underReplicationDrain = underReplicationDrain;
+		(node as any).underReplicationLedger = underReplicationLedger;
+
 		// Initialize Arachnode ring membership and restoration
 		const enableArachnode = options.arachnode?.enableRingZulu ?? true;
 		if (enableArachnode) {
@@ -1203,9 +1360,11 @@ export async function createLibp2pNodeBase(
 							partitionDetector,
 							fretAdapter,
 							ownedBlocks,
+							keyNetwork,
 							options.rebalance,
 						);
 						await rebalanceMonitor.start();
+						committedHoldersTarget = (committed) => rebalanceMonitor.recordCommittedHolders(committed);
 
 						// onRebalance fires synchronously from the monitor's debounced check; the coordinator's
 						// reaction (pull gained / push lost, each partition-guarded) is async, so hop it off the
@@ -1648,8 +1807,8 @@ export async function createLibp2pNodeBase(
 						return undefined; // tail-less (read-driven promotion) never originates (the gate also returns first)
 					}
 					return {
-						// MUST reuse the gate's `reactivityTailBytes` (utf8), NOT db-core's double-hashing
-						// blockIdToBytes — else origination derives a different coord than subscribers resolve.
+						// MUST reuse the gate's `reactivityTailBytes` (raw utf8, the tail's routing key), never
+						// a pre-hashed digest — else origination derives a different coord than subscribers resolve.
 						tailId: reactivityTailBytes(event.tailId),
 						deltaMaxBytes: reactivityPolicy.deltaMaxBytes,
 						// rotationHint stays undefined on a live node: the successor tail id is not knowable at the
@@ -1720,8 +1879,8 @@ export async function createLibp2pNodeBase(
 			});
 
 			// Inbound serve handler: decode (bounded) → verify the dialing peer's signature → freshness/replay gate →
-			// resolve the live PushState off the forwarder host → serveBackfill/serveResume → reply (no reply on any
-			// failure; the stream aborts and the subscriber walks/chain-reads). One node-level replay guard is shared
+			// resolve the live PushState off the forwarder host → serveBackfill/serveResume → reply (a decline on any
+			// failure; the subscriber's transport tries the next cohort member). One node-level replay guard is shared
 			// across all recover requests — a plain pruned-on-access map, so no new timer to tear down.
 			registerRecoverHandler(node, reactivityProtocols.recover, {
 				pushStateFor: forwarderHost.pushStateFor.bind(forwarderHost),

package/src/libp2p-node-rn.ts

@@ -1,30 +1,31 @@
-import {
-	createLibp2pNodeBase,
-	type Libp2pTransports,
-	type NodeOptions,
-	type RawStorageProvider,
-} from './libp2p-node-base.js';
-import type { OptimysticNode } from './optimystic-node.js';
-
-export type { Libp2pTransports, NodeOptions, RawStorageProvider };
-
-/**
- * React Native-friendly libp2p node factory.
- *
- * This entrypoint intentionally does not import Node-only transports (like `@libp2p/tcp`).
- * Callers must provide `options.transports` (and typically `options.listenAddrs`).
- */
-export async function createLibp2pNode(options: NodeOptions): Promise<OptimysticNode> {
-	const transports = options.transports;
-	if (!transports || transports.length === 0) {
-		throw new Error(
-			'createLibp2pNode (RN) requires options.transports. ' +
-				'Provide an RN-compatible transport (e.g. WebSockets) and any required listenAddrs.'
-		);
-	}
-
-	return await createLibp2pNodeBase(options, {
-		listenAddrs: [],
-		transports,
-	});
-}
+import {
+	createLibp2pNodeBase,
+	type Libp2pTransports,
+	type NodeOptions,
+	type RawStorageProvider,
+	type KVStoreProvider,
+} from './libp2p-node-base.js';
+import type { OptimysticNode } from './optimystic-node.js';
+
+export type { Libp2pTransports, NodeOptions, RawStorageProvider, KVStoreProvider };
+
+/**
+ * React Native-friendly libp2p node factory.
+ *
+ * This entrypoint intentionally does not import Node-only transports (like `@libp2p/tcp`).
+ * Callers must provide `options.transports` (and typically `options.listenAddrs`).
+ */
+export async function createLibp2pNode(options: NodeOptions): Promise<OptimysticNode> {
+	const transports = options.transports;
+	if (!transports || transports.length === 0) {
+		throw new Error(
+			'createLibp2pNode (RN) requires options.transports. ' +
+				'Provide an RN-compatible transport (e.g. WebSockets) and any required listenAddrs.'
+		);
+	}
+
+	return await createLibp2pNodeBase(options, {
+		listenAddrs: [],
+		transports,
+	});
+}

package/src/libp2p-node.ts

@@ -1,36 +1,37 @@
-import { tcp } from '@libp2p/tcp';
-import { webSockets } from '@libp2p/websockets';
-import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
-import {
-	createLibp2pNodeBase,
-	type Libp2pTransports,
-	type NodeOptions,
-	type RawStorageProvider,
-} from './libp2p-node-base.js';
-import type { OptimysticNode } from './optimystic-node.js';
-
-export type { Libp2pTransports, NodeOptions, RawStorageProvider };
-
-export async function createLibp2pNode(options: NodeOptions): Promise<OptimysticNode> {
-	const port = options.port ?? 0;
-	const wsHost = options.wsHost ?? '0.0.0.0';
-
-	const defaultTransports: Libp2pTransports = [];
-	const defaultListenAddrs: string[] = [];
-
-	if (!options.disableTcp) {
-		defaultTransports.push(tcp());
-		defaultListenAddrs.push(`/ip4/0.0.0.0/tcp/${port}`);
-	}
-	if (options.wsPort !== undefined) {
-		defaultTransports.push(webSockets());
-		defaultListenAddrs.push(`/ip4/${wsHost}/tcp/${options.wsPort}/ws`);
-	}
-	// Always include the relay transport so this node can dial through relays
-	defaultTransports.push(circuitRelayTransport());
-
-	return await createLibp2pNodeBase(options, {
-		listenAddrs: defaultListenAddrs,
-		transports: defaultTransports,
-	});
-}
+import { tcp } from '@libp2p/tcp';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+import {
+	createLibp2pNodeBase,
+	type Libp2pTransports,
+	type NodeOptions,
+	type RawStorageProvider,
+	type KVStoreProvider,
+} from './libp2p-node-base.js';
+import type { OptimysticNode } from './optimystic-node.js';
+
+export type { Libp2pTransports, NodeOptions, RawStorageProvider, KVStoreProvider };
+
+export async function createLibp2pNode(options: NodeOptions): Promise<OptimysticNode> {
+	const port = options.port ?? 0;
+	const wsHost = options.wsHost ?? '0.0.0.0';
+
+	const defaultTransports: Libp2pTransports = [];
+	const defaultListenAddrs: string[] = [];
+
+	if (!options.disableTcp) {
+		defaultTransports.push(tcp());
+		defaultListenAddrs.push(`/ip4/0.0.0.0/tcp/${port}`);
+	}
+	if (options.wsPort !== undefined) {
+		defaultTransports.push(webSockets());
+		defaultListenAddrs.push(`/ip4/${wsHost}/tcp/${options.wsPort}/ws`);
+	}
+	// Always include the relay transport so this node can dial through relays
+	defaultTransports.push(circuitRelayTransport());
+
+	return await createLibp2pNodeBase(options, {
+		listenAddrs: defaultListenAddrs,
+		transports: defaultTransports,
+	});
+}

package/src/logger.ts

@@ -113,7 +113,12 @@ function formatError(v: Error, indent = ''): string {
 }
 
 function isAggregateError(err?: any): err is AggregateError {
-	return err instanceof AggregateError || (err?.name === 'AggregateError' && Array.isArray(err.errors))
+	// `typeof` guards the bare identifier: if Hermes (React Native's JS engine) doesn't
+	// define a global `AggregateError`, `err instanceof AggregateError` would throw a
+	// ReferenceError right here on the error-formatting path — exactly where a thrown
+	// exception would otherwise go unreported. `typeof` never throws for an undeclared
+	// global, so this falls straight through to the duck-typed check either way.
+	return (typeof AggregateError !== 'undefined' && err instanceof AggregateError) || (err?.name === 'AggregateError' && Array.isArray(err.errors))
 }
 
 function printError(err: Error, indent = ''): string {

package/src/matchmaking/query-transport.ts

@@ -28,10 +28,9 @@
  * milestone); a *serving* tier-`d ≥ 1` query is gated on the promotion follow-ons, exactly as the seeker
  * walk is mock-tier-tagged-unimplemented. So this resolves the tier-0 engine for `coord_0(topicId)` only.
  *
- * **No-engine = no reply (anti-DoS).** A query for a topic this node holds no serving engine for produces
- * **no reply frame** — the handler never instantiates a `CoordEngine` from an inbound query (that would be
- * a DoS amplifier). The seeker maps a no-reply to a benign empty advisory result (the seeker ticket owns
- * that mapping).
+ * **No-engine = no result (anti-DoS).** A query for a topic this node holds no serving engine for gets
+ * **no result** (a zero-length reply) — the handler never instantiates a `CoordEngine` from an inbound query
+ * (that would be a DoS amplifier). The seeker maps a no-result to a benign empty advisory result.
  *
  * **Per-coord scoping.** The reply is built from exactly the `coord_0(topicId)` engine's store, nothing
  * cross-coord — matching how the register handler recomputes a served coord per frame. The serve side does
@@ -79,7 +78,7 @@ import type { CoordRegistry } from "../cohort-topic/host.js";
 import { peerIdToBytes } from "../cohort-topic/peer-codec.js";
 import { signPeer, verifyPeerSig } from "../cohort-topic/peer-sig.js";
 import { FretSizeEstimator } from "../cohort-topic/size-estimator.js";
-import { handleRequestResponse, requestResponse, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
+import { handleRequestResponse, requestResponse, requireReply, DEFAULT_STREAM_MAX_BYTES } from "../cohort-topic/stream-util.js";
 import { DEFAULT_COHORT_TOPIC_PROTOCOLS } from "../cohort-topic/protocols.js";
 import { handleMatchmakingQuery } from "./query-handler.js";
 import { PROTOCOL_MATCHMAKING_QUERY, DEFAULT_MATCHMAKING_PROTOCOLS } from "./protocols.js";
@@ -339,9 +338,9 @@ export function createLibp2pMatchmakingTransport(deps: Libp2pMatchmakingTranspor
 		}
 		try {
 			const frame = await requestResponse(node, peerIdFromString(primary), queryProtocol, encodeQueryV1(q, maxBytes), maxBytes);
-			// The serve handler returns no frame for a topic it does not serve; map it (and any decode/dial
-			// failure) to a benign empty reply so SeekerWalkClient.collect keeps walking rather than throwing.
-			return frame.length === 0 ? emptyReply() : decodeQueryReplyV1(frame, maxBytes);
+			// The serve handler has no result for a topic it does not serve (`undefined`); map it (and any
+			// decode/dial failure) to a benign empty reply so SeekerWalkClient.collect keeps walking rather than throwing.
+			return frame === undefined ? emptyReply() : decodeQueryReplyV1(frame, maxBytes);
 		} catch (err) {
 			log("matchmaking query: dial/decode failed for primary %s (empty reply): %o", primary, err);
 			return emptyReply();
@@ -390,7 +389,8 @@ export function createLibp2pMatchmakingTransport(deps: Libp2pMatchmakingTranspor
 			throw new Error("matchmaking register: FRET routed the cohort primary to self; provide deps.selfServe.register");
 		}
 		const frame = await requestResponse(node, peerIdFromString(primary), registerProtocol, encodeCohortMessage(reg, maxBytes), maxBytes);
-		return validateRegisterReplyV1(decodeCohortMessage(frame, maxBytes));
+		// The `/register` responder always writes a frame, so a no-result reply is a non-conforming peer: reject.
+		return validateRegisterReplyV1(decodeCohortMessage(requireReply(frame, "matchmaking register"), maxBytes));
 	};
 
 	/** Map a `RegisterReplyV1` to the walk's {@link SeekerProbeReply} (pass `result`; copy traffic/targetTier). */