@optimystic/db-p2p 0.13.5 → 0.14.1

package/src/matchmaking/seeker-walk-client.ts

@@ -0,0 +1,293 @@
+/**
+ * Matchmaking — seeker walk client (db-p2p, drives the hang-out-vs-continue walk over the substrate).
+ *
+ * `docs/matchmaking.md` §Hang-out vs. continue. This is the RPC orchestration on top of the pure
+ * db-core {@link decide} engine: starting at `d_max`, it registers the seeker, issues `QueryV1`,
+ * re-validates and dedupes returned providers, and on each `Accepted` reply asks {@link decide} whether
+ * to finish, hang out (renew + requery on the `requery_interval_ms` poll cadence), or escalate (withdraw
+ * + re-register one tier toward the root). At `d = 0` there is nowhere left to walk, so it hangs out for
+ * the remaining patience and returns whatever matched (possibly `< wantCount`).
+ *
+ * Patience is a single budget that **drains across hops** (`docs/matchmaking.md` §Patience budgeting):
+ * a wall-clock deadline is fixed at the start, so every walked tier and every hang-out poll consumes
+ * the same `patienceMs` — escalation makes the next tier's hang-out progressively less attractive, which
+ * is correct since the root is terminal.
+ *
+ * The transport, clock, sleep, and per-entry verifier are all injected, so the walk unit-tests without a
+ * live libp2p stack (mock-tier e2e is a documented follow-on). This client implements the **poll path**
+ * only; the arrival-push path (`pushOnArrival`) is a separate slice.
+ *
+ * Edge cases encoded here (`docs/matchmaking.md` §Edge cases — the rest live in {@link decide}):
+ * - **`topicTraffic` absent (case 1):** the cohort is treated as zero-rate; the seeker issues one query
+ *   (immediate-match) and walks one tier toward the root **without** hanging out.
+ * - **Stale `arrivalsPerMin = 0` after an epoch change (case 2):** never withdraw on a single zero
+ *   reading — the immediate `QueryV1` runs first; a cohort that actually holds `>= wantCount` providers
+ *   resolves to `done`, and only a query that also yields below threshold escalates.
+ * - **`UnwillingCohort`/`UnwillingMember` (case 3):** the hang-out decision is never entered (no
+ *   `Accepted`); the walk terminates with whatever matched and standard substrate back-off applies.
+ */
+
+import {
+	decide,
+	filterAcceptRatio,
+	matchesFilter,
+	newFilterAcceptRatioState,
+	observeYield,
+	verifyProviderEntry,
+	DEFAULT_HANG_OUT_CONFIG,
+	DEFAULT_MEAN_WANT_COUNT,
+	FILTER_ACCEPT_RATIO_INITIAL,
+	type CapabilityFilter,
+	type EntrySigVerifier,
+	type FilterAcceptRatioState,
+	type HangOutConfig,
+	type ProviderEntryV1,
+	type QueryReplyV1,
+} from "@optimystic/db-core";
+
+/** A seeker register/probe reply at a tree tier (the matchmaking-relevant subset of `RegisterReplyV1`). */
+export interface SeekerProbeReply {
+	readonly result: "accepted" | "no_state" | "promoted" | "unwilling_member" | "unwilling_cohort";
+	/** Present on `accepted` and `promoted` (the substrate's barometer); absent triggers edge case 1. */
+	readonly topicTraffic?: QueryReplyV1["topicTraffic"];
+	/** Present on `promoted` — the tier to descend to. */
+	readonly targetTier?: number;
+}
+
+/** The substrate seam the walk drives: register/query/renew/withdraw against a tree tier. */
+export interface SeekerWalkTransport {
+	/** Register (or re-register) the seeker at tree tier `treeTier`; resolves the probe reply. */
+	register(treeTier: number): Promise<SeekerProbeReply>;
+	/** Issue a `QueryV1` against the cohort the seeker is currently registered with. */
+	query(treeTier: number): Promise<QueryReplyV1>;
+	/** Renew the live seeker registration (hang-out keep-alive via TTL renewal). */
+	renew(): Promise<void>;
+	/** Withdraw the seeker registration before escalating (polite `RenewV1` TTL = 0; optional). */
+	withdraw(): Promise<void>;
+}
+
+/** Construction inputs for {@link SeekerWalkClient}. */
+export interface SeekerWalkClientDeps {
+	readonly transport: SeekerWalkTransport;
+	/** The matchmaking topic id (used to re-validate each forwarded entry's `registrationSig`). */
+	readonly topicId: Uint8Array;
+	/** Providers the seeker needs. */
+	readonly wantCount: number;
+	/** The starting tree tier `d_max`. */
+	readonly dMax: number;
+	/** Total patience budget (ms); drains across hops + hang-out. */
+	readonly patienceMs: number;
+	/** Optional capability filter (re-applied seeker-side over the returned set). */
+	readonly filter?: CapabilityFilter;
+	/** Per-entry signature verifier (db-p2p binds `verifyPeerSig`). */
+	readonly verifyEntry: EntrySigVerifier;
+	/** Hang-out decision config. Default {@link DEFAULT_HANG_OUT_CONFIG}. */
+	readonly config?: HangOutConfig;
+	/** Assumed competing-seeker mean `wantCount`. Default {@link DEFAULT_MEAN_WANT_COUNT}. */
+	readonly meanWantCount?: number;
+	/** Starting `filterAcceptRatio` (refined per walk). Default {@link FILTER_ACCEPT_RATIO_INITIAL}. */
+	readonly filterAcceptRatioInitial?: number;
+	/** Wall clock (unix ms); injectable for tests. Default `Date.now`. */
+	readonly clock?: () => number;
+	/** Sleep for the requery cadence; injectable for tests. Default a real timer. */
+	readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/** The result of a completed walk. */
+export interface SeekerWalkResult {
+	/** Matched, re-validated, deduped providers (up to whatever accumulated; may be `< wantCount`). */
+	readonly providers: ProviderEntryV1[];
+	/** Whether `wantCount` was met. */
+	readonly metWantCount: boolean;
+	/** The tier the walk terminated at. */
+	readonly terminalTier: number;
+	/** Total register hops issued (probes + escalations + descends). */
+	readonly hops: number;
+	/**
+	 * Max `topicTraffic.childCohortCount` observed across every `Accepted` reply this walk saw. `> 0`
+	 * means the topic has promoted (it is hot), so the single-cohort sample is unrepresentative — the
+	 * public seeker session / voting `QuorumDiscovery` binding uses this to decide whether to escalate to
+	 * the multi-cohort sweep (`docs/matchmaking.md` §Multi-cohort sweep).
+	 */
+	readonly maxChildCohortCount: number;
+}
+
+/** Outcome of evaluating one `Accepted` tier. */
+type AcceptedOutcome = "done" | "escalate" | "terminal";
+
+/** Drives the seeker hang-out-vs-continue walk for one matchmaking topic. See the module header. */
+export class SeekerWalkClient {
+	private readonly transport: SeekerWalkTransport;
+	private readonly topicId: Uint8Array;
+	private readonly wantCount: number;
+	private readonly dMax: number;
+	private readonly patienceMs: number;
+	private readonly filter?: CapabilityFilter;
+	private readonly verifyEntry: EntrySigVerifier;
+	private readonly config: HangOutConfig;
+	private readonly meanWantCount: number;
+	private readonly filterAcceptRatioInitial: number;
+	private readonly clock: () => number;
+	private readonly sleep: (ms: number) => Promise<void>;
+
+	/** Matched providers, deduped by `participantId` (a provider seen via two queries counts once). */
+	private readonly matched = new Map<string, ProviderEntryV1>();
+	private ratioState: FilterAcceptRatioState = newFilterAcceptRatioState();
+	private deadline = 0;
+	private hops = 0;
+	/** Max `childCohortCount` seen across `Accepted` replies — the hot-topic / sweep-escalation signal. */
+	private maxChildCohortCount = 0;
+
+	constructor(deps: SeekerWalkClientDeps) {
+		this.transport = deps.transport;
+		this.topicId = deps.topicId;
+		this.wantCount = deps.wantCount;
+		this.dMax = deps.dMax;
+		this.patienceMs = deps.patienceMs;
+		this.filter = deps.filter;
+		this.verifyEntry = deps.verifyEntry;
+		this.config = deps.config ?? DEFAULT_HANG_OUT_CONFIG;
+		this.meanWantCount = deps.meanWantCount ?? DEFAULT_MEAN_WANT_COUNT;
+		this.filterAcceptRatioInitial = deps.filterAcceptRatioInitial ?? FILTER_ACCEPT_RATIO_INITIAL;
+		this.clock = deps.clock ?? ((): number => Date.now());
+		this.sleep = deps.sleep ?? ((ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms)));
+	}
+
+	/** Run the walk from `d_max` toward the root; resolves the matched providers + termination info. */
+	async run(): Promise<SeekerWalkResult> {
+		this.deadline = this.clock() + this.patienceMs;
+		let d = this.dMax;
+
+		while (true) {
+			this.hops++;
+			const reply = await this.transport.register(d);
+			switch (reply.result) {
+				case "no_state": {
+					if (d <= 0) {
+						return this.finish(d);
+					}
+					d -= 1;
+					continue;
+				}
+				case "unwilling_member":
+				case "unwilling_cohort": {
+					// Substrate-level refusal — never received Accepted, so hang-out is not entered (case 3).
+					return this.finish(d);
+				}
+				case "promoted": {
+					const target = reply.targetTier ?? d + 1;
+					if (target <= d) {
+						return this.finish(d);
+					}
+					d = target;
+					continue;
+				}
+				case "accepted": {
+					const outcome = await this.handleAccepted(d, reply.topicTraffic);
+					if (outcome === "done" || outcome === "terminal") {
+						return this.finish(d);
+					}
+					await this.transport.withdraw();
+					d -= 1;
+					continue;
+				}
+			}
+		}
+	}
+
+	/** Remaining patience (ms); the wall-clock deadline drains uniformly across hops + hang-out. */
+	private remaining(): number {
+		return Math.max(0, this.deadline - this.clock());
+	}
+
+	/** Filter, re-validate (`registrationSig`), and dedupe a query reply's providers into {@link matched}. */
+	private collect(reply: QueryReplyV1): void {
+		const returned = reply.providers ?? [];
+		let matchedThisQuery = 0;
+		for (const entry of returned) {
+			if (!matchesFilter(entry, this.filter)) {
+				continue;
+			}
+			if (!verifyProviderEntry(this.topicId, entry, this.verifyEntry)) {
+				continue;
+			}
+			matchedThisQuery++;
+			this.matched.set(entry.participantId, entry);
+		}
+		this.ratioState = observeYield(this.ratioState, matchedThisQuery, returned.length);
+	}
+
+	/** Evaluate one `Accepted` tier: immediate query, then {@link decide} → done / hangOut / escalate. */
+	private async handleAccepted(d: number, traffic: SeekerProbeReply["topicTraffic"]): Promise<AcceptedOutcome> {
+		// Record the hottest tier seen as soon as this Accepted reply's traffic is available — *before* the
+		// immediate-match/done short-circuit below, so the single-cohort-vs-sweep decision (public session /
+		// voting QuorumDiscovery binding) still sees a hot topic even when one cohort's query already met
+		// wantCount. Folding it only on the `decide` path would drop the signal for a small quorum that a
+		// single hot cohort satisfies, leaving the assembler with a prefix-biased sample it should sweep.
+		if (traffic !== undefined) {
+			this.maxChildCohortCount = Math.max(this.maxChildCohortCount, traffic.childCohortCount);
+		}
+
+		// Immediate-match check runs in every case — also satisfies edge case 2 (a stale arrivalsPerMin=0
+		// cohort that actually holds enough providers resolves here rather than escalating spuriously).
+		this.collect(await this.transport.query(d));
+		if (this.matched.size >= this.wantCount) {
+			return "done";
+		}
+
+		// Edge case 1: a reply without topicTraffic is treated as zero-rate — walk one tier toward the
+		// root without hanging out (no estimation against absent inputs).
+		if (traffic === undefined) {
+			return d <= 0 ? "terminal" : "escalate";
+		}
+
+		const decision = decide(
+			{
+				currentMatches: this.matched.size,
+				directParticipants: traffic.directParticipants,
+				arrivalsPerMin: traffic.arrivalsPerMin,
+				queriesPerMin: traffic.queriesPerMin,
+				childCohortCount: traffic.childCohortCount,
+				wantCount: this.wantCount,
+				patienceMsRemaining: this.remaining(),
+				filterAcceptRatio: filterAcceptRatio(this.ratioState, this.filterAcceptRatioInitial),
+				meanWantCount: this.meanWantCount,
+			},
+			this.config,
+		);
+
+		if (decision.action === "hangOut") {
+			await this.hangOut(d, decision.requeryIntervalMs);
+			if (this.matched.size >= this.wantCount) {
+				return "done";
+			}
+			return d <= 0 ? "terminal" : "escalate";
+		}
+
+		// escalate — but at the root there is nowhere to walk: hang out the remaining patience, then end.
+		if (d <= 0) {
+			await this.hangOut(d, this.config.requeryIntervalMs);
+			return "terminal";
+		}
+		return "escalate";
+	}
+
+	/** Keep the registration alive and re-query on the poll cadence until `wantCount` met or patience drains. */
+	private async hangOut(d: number, requeryIntervalMs: number): Promise<void> {
+		while (this.remaining() > 0 && this.matched.size < this.wantCount) {
+			await this.sleep(Math.min(requeryIntervalMs, this.remaining()));
+			await this.transport.renew();
+			this.collect(await this.transport.query(d));
+		}
+	}
+
+	private finish(terminalTier: number): SeekerWalkResult {
+		return {
+			providers: [...this.matched.values()],
+			metWantCount: this.matched.size >= this.wantCount,
+			terminalTier,
+			hops: this.hops,
+			maxChildCohortCount: this.maxChildCohortCount,
+		};
+	}
+}

package/src/matchmaking/traffic-validation.ts

@@ -0,0 +1,195 @@
+/**
+ * Matchmaking — seeker-side adversarial traffic-reporting bounds + reputation cross-check hooks (db-p2p).
+ *
+ * `docs/matchmaking.md` §Adversarial cohort traffic reporting. A `QueryReplyV1.topicTraffic` (and the
+ * registration reply's traffic) is signed by the cohort **primary's single member key, not a threshold
+ * signature**, because the response is advisory — so a malicious primary can over- or under-report. The
+ * doc proves the harm is bounded either way; this module makes those bounds explicit for the seeker walk
+ * and emits the cross-check signals the reputation subsystem consumes.
+ *
+ *  - **Over-reporting** (fake *hot* tier ⇒ seeker hangs out): bounded by the seeker's `patienceMs`. The
+ *    worst case is wasted patience plus the one `register → walk` hop after timeout — there is **no
+ *    spatial flood**, because the decision rule only ever walks *toward the root*, never speculatively
+ *    outward. {@link boundReportedTraffic} therefore caps any hang-out to the seeker's remaining
+ *    wall-clock patience ({@link TrafficBoundResult.capPatienceMs}).
+ *  - **Under-reporting** (fake *cold* tier ⇒ seeker escalates): bounded to **one extra hop per affected
+ *    tier**, terminating at the root where aggregated truth is hardest to fake
+ *    ({@link TrafficBoundResult.escalateAfterTiers}).
+ *  - **Cross-check via cohort gossip → reputation.** Other cohort members can detect a primary whose
+ *    reported rate diverges from the gossip-derived view. Detection *routing* is the reputation
+ *    subsystem's job (out of scope to implement); this module provides the **emission points**
+ *    ({@link TrafficCrossCheckSignal}) and a thin bridge ({@link reportTrafficCrossCheck}) into the
+ *    existing {@link IPeerReputation}. It scores nothing itself — the reputation subsystem owns the
+ *    aggregation/decay policy that turns a stream of advisory signals into an actual penalty.
+ *
+ * **GROUNDING (matchmaking.md §Adversarial traffic reporting):** no threshold signature is added per
+ * `QueryReplyV1` — the single-member signature stands; the bounded worst-case here does not justify the
+ * per-reply threshold cost. This module enforces the bounds purely seeker-side instead.
+ */
+
+import { type QueryReplyV1 } from "@optimystic/db-core";
+import { PenaltyReason, type IPeerReputation } from "../reputation/index.js";
+
+/**
+ * The seeker's running walk state at the moment a reply lands — enough to bound the reply's reported
+ * traffic and attribute a cross-check signal. The seeker walk client (or the public seeker session)
+ * supplies it per reply.
+ */
+export interface SeekerWalkState {
+	/** Tree tier `d` the reply came from. */
+	readonly currentTier: number;
+	/** Starting tier `d_max` (the walk only descends from here toward `0`). */
+	readonly dMax: number;
+	/** Register hops issued so far (probes + escalations). Bounded by `d_max + 1` — the walk never loops. */
+	readonly tiersWalked: number;
+	/** Total patience budget for the task (ms). */
+	readonly patienceMs: number;
+	/** Patience left on the wall-clock deadline (ms) — the hang-out cap. */
+	readonly patienceRemainingMs: number;
+	/** Filter-matched providers the seeker's *own* immediate `QueryV1` at this tier actually returned. */
+	readonly observedMatches: number;
+	/** The reply's cohort primary peer id, for reputation attribution (absent → no attribution). */
+	readonly primaryId?: string;
+}
+
+/** Tunables for {@link boundReportedTraffic}. */
+export interface TrafficBoundConfig {
+	/**
+	 * Upper bound on extra register hops a single under-reported tier may cost. The doc fixes this at
+	 * **1** ("one extra hop per affected tier"); exposed for tests / future policy, not meant to change.
+	 */
+	readonly maxExtraHopsPerTier: number;
+	/**
+	 * Over-report plausibility ratio. When a reply claims `directParticipants` more than this multiple of
+	 * the seeker's *own* query yield, the over-report is flagged *suspect* (a cross-check signal — never a
+	 * hard reject; the patience cap already bounds the harm).
+	 */
+	readonly overReportSuspectRatio: number;
+}
+
+/** The documented defaults (`maxExtraHopsPerTier = 1`; suspect ratio chosen to tolerate normal churn). */
+export const DEFAULT_TRAFFIC_BOUND_CONFIG: TrafficBoundConfig = {
+	maxExtraHopsPerTier: 1,
+	overReportSuspectRatio: 8,
+};
+
+/** The kind of divergence a {@link TrafficCrossCheckSignal} reports. */
+export type TrafficCrossCheckKind = "over-report-suspected" | "under-report-suspected";
+
+/**
+ * One advisory cross-check observation about a cohort primary's reported traffic. Emitted by
+ * {@link boundReportedTraffic}; consumed by the reputation subsystem (via {@link reportTrafficCrossCheck}
+ * or a custom sink). Carries the raw discrepancy so the reputation policy — not this module — decides
+ * whether it warrants a penalty.
+ */
+export interface TrafficCrossCheckSignal {
+	readonly kind: TrafficCrossCheckKind;
+	/** The cohort primary peer id (the subject), if the walk state attributed one. */
+	readonly subjectId?: string;
+	/** The tier the reply came from. */
+	readonly tier: number;
+	/** `topicTraffic.directParticipants` as reported. */
+	readonly reportedDirectParticipants: number;
+	/** `topicTraffic.arrivalsPerMin` as reported. */
+	readonly reportedArrivalsPerMin: number;
+	/** The seeker's own immediate-query yield, which the report is cross-checked against. */
+	readonly observedMatches: number;
+}
+
+/** The outcome of {@link boundReportedTraffic}. */
+export interface TrafficBoundResult {
+	/** Whether the reported traffic is within plausible bounds (advisory; a flag, not an admission). */
+	readonly trusted: boolean;
+	/**
+	 * Over-report bound: never hang out at this tier beyond the seeker's remaining wall-clock patience.
+	 * Equals `max(0, patienceRemainingMs)` — so a fabricated hot tier wastes at most that, then the walk
+	 * proceeds with its one register hop.
+	 */
+	readonly capPatienceMs: number;
+	/** Under-report bound: at most this many extra register hops attributable to one tier (== config). */
+	readonly escalateAfterTiers: number;
+	/** Cross-check emission points (possibly empty). Forward to the reputation subsystem if desired. */
+	readonly reputationSignals: TrafficCrossCheckSignal[];
+}
+
+/**
+ * Bound the harm of a (possibly adversarial) `topicTraffic` report and emit cross-check signals. Pure —
+ * no I/O, no clock, no reputation scoring. The seeker walk consults `capPatienceMs` before hanging out
+ * and treats `escalateAfterTiers` as the per-tier hop ceiling; the bounds it returns hold *by
+ * construction* of the toward-root-only walk, so this function documents + asserts them rather than
+ * changing the walk topology.
+ */
+export function boundReportedTraffic(
+	reply: QueryReplyV1,
+	walkState: SeekerWalkState,
+	cfg: TrafficBoundConfig = DEFAULT_TRAFFIC_BOUND_CONFIG,
+): TrafficBoundResult {
+	const traffic = reply.topicTraffic;
+	const signals: TrafficCrossCheckSignal[] = [];
+
+	// Over-report: a primary advertising a hot tier (many directParticipants) whose own query yields far
+	// fewer matches is suspect. Harm is bounded regardless — the patience cap below means a fabricated hot
+	// tier can only waste the seeker's remaining patience before it walks on (no spatial flood, since the
+	// walk only steps toward the root).
+	const overReportSuspect =
+		traffic.directParticipants > cfg.overReportSuspectRatio * Math.max(walkState.observedMatches, 1);
+	if (overReportSuspect) {
+		signals.push(crossCheckSignal("over-report-suspected", traffic, walkState));
+	}
+
+	// Under-report: a primary claiming a cold tier (zero arrivals) while the seeker's own query yields
+	// matches is suspect. Either way the escalation costs at most one extra hop for this tier and
+	// terminates at the root.
+	const underReportSuspect = traffic.arrivalsPerMin === 0 && walkState.observedMatches > 0;
+	if (underReportSuspect) {
+		signals.push(crossCheckSignal("under-report-suspected", traffic, walkState));
+	}
+
+	return {
+		trusted: !overReportSuspect && !underReportSuspect,
+		capPatienceMs: Math.max(0, walkState.patienceRemainingMs),
+		escalateAfterTiers: cfg.maxExtraHopsPerTier,
+		reputationSignals: signals,
+	};
+}
+
+function crossCheckSignal(kind: TrafficCrossCheckKind, traffic: QueryReplyV1["topicTraffic"], walkState: SeekerWalkState): TrafficCrossCheckSignal {
+	const signal: TrafficCrossCheckSignal = {
+		kind,
+		tier: walkState.currentTier,
+		reportedDirectParticipants: traffic.directParticipants,
+		reportedArrivalsPerMin: traffic.arrivalsPerMin,
+		observedMatches: walkState.observedMatches,
+	};
+	if (walkState.primaryId !== undefined) {
+		(signal as { subjectId: string }).subjectId = walkState.primaryId;
+	}
+	return signal;
+}
+
+/**
+ * The total hop budget the toward-root-only walk can consume under any sequence of (honest or
+ * adversarial) traffic reports: at most `maxExtraHopsPerTier` per tier from `d_max` down to the root,
+ * plus the terminal hop — i.e. `(dMax + 1) * maxExtraHopsPerTier`. Exposed so the walk and its tests can
+ * assert the under-report bound holds (the walk never exceeds it, because escalation is monotone toward
+ * `d = 0`).
+ */
+export function maxWalkHops(dMax: number, cfg: TrafficBoundConfig = DEFAULT_TRAFFIC_BOUND_CONFIG): number {
+	return Math.max(0, dMax + 1) * cfg.maxExtraHopsPerTier;
+}
+
+/**
+ * Integration hook: forward cross-check signals into the reputation subsystem. This is the **emission
+ * point only** — it records a `ProtocolViolation` against the reporting primary; the reputation
+ * subsystem's own weighting, decay, and deprioritize/ban thresholds (`PeerReputationService`) decide
+ * whether an accumulation of these advisory signals actually penalizes the peer. Signals without an
+ * attributed `subjectId` are skipped.
+ */
+export function reportTrafficCrossCheck(reputation: IPeerReputation, signals: readonly TrafficCrossCheckSignal[]): void {
+	for (const signal of signals) {
+		if (signal.subjectId === undefined) {
+			continue;
+		}
+		reputation.reportPeer(signal.subjectId, PenaltyReason.ProtocolViolation, `matchmaking:${signal.kind}`);
+	}
+}

package/src/network/network-manager-service.ts

@@ -92,13 +92,16 @@ export class NetworkManagerService implements Startable {
 
 	/**
 	 * Initialize the spread-on-churn monitor. Call after libp2p, FRET are available.
-	 * Caller provides repo and peerNetwork (not held by NetworkManagerService directly).
+	 * Caller provides repo and peerNetwork (not held by NetworkManagerService directly),
+	 * plus the node's protocolPrefix (/optimystic/<networkName>) so churn pushes dial the
+	 * same block-transfer protocol the node registers its handler under.
 	 */
 	initSpreadOnChurnMonitor(
 		partitionDetector: PartitionDetector,
 		repo: SpreadOnChurnDeps['repo'],
 		peerNetwork: SpreadOnChurnDeps['peerNetwork'],
 		clusterSize: number,
+		protocolPrefix: string,
 		config?: Partial<SpreadOnChurnConfig>
 	): SpreadOnChurnMonitor {
 		const libp2p = this.getLibp2p()
@@ -106,8 +109,12 @@ export class NetworkManagerService implements Startable {
 		if (!libp2p || !fret) {
 			throw new Error('Cannot init SpreadOnChurnMonitor: libp2p or FRET not available')
 		}
+		// protocolPrefix MUST flow into SpreadOnChurnDeps: performSpread builds its
+		// BlockTransferClient with it, and the receiving node registers the block-transfer
+		// handler under /optimystic/<networkName>. A missing/empty prefix dials the wrong
+		// protocol and every churn push fails to connect.
 		this.spreadOnChurnMonitor = new SpreadOnChurnMonitor(
-			{ libp2p, fret, partitionDetector, repo, peerNetwork, clusterSize },
+			{ libp2p, fret, partitionDetector, repo, peerNetwork, clusterSize, protocolPrefix },
 			config
 		)
 		return this.spreadOnChurnMonitor

package/src/protocol-client.ts

@@ -23,6 +23,23 @@ export class DialTimeoutError extends Error {
 	}
 }
 
+/**
+ * Thrown when a peer dialed successfully but the response-read deadline expired
+ * before it wrote a reply (it connected, then went silent). Distinct from
+ * {@link DialTimeoutError} (never connected) and from a parent cancellation
+ * (`options.signal`), so callers/diagnostics can tell "peer went quiet" apart
+ * from "peer was unreachable" and "we cancelled". `.code === RESPONSE_TIMEOUT_ERROR_CODE`.
+ */
+export const RESPONSE_TIMEOUT_ERROR_CODE = 'RESPONSE_TIMEOUT';
+
+export class ResponseTimeoutError extends Error {
+	readonly code = RESPONSE_TIMEOUT_ERROR_CODE;
+	constructor(peer: string, protocol: string, ms: number) {
+		super(`response timeout: peer=${peer} protocol=${protocol} after ${ms}ms`);
+		this.name = 'ResponseTimeoutError';
+	}
+}
+
 /** Base class for clients that communicate via a libp2p protocol */
 export class ProtocolClient {
 	constructor(
@@ -33,7 +50,7 @@ export class ProtocolClient {
 	protected async processMessage<T>(
 		message: unknown,
 		protocol: string,
-		options?: { signal?: AbortSignal; correlationId?: string; dialTimeoutMs?: number }
+		options?: { signal?: AbortSignal; correlationId?: string; dialTimeoutMs?: number; responseTimeoutMs?: number }
 	): Promise<T> {
 		const peer = this.peerId.toString();
 		const cid = options?.correlationId;
@@ -90,7 +107,34 @@ export class ProtocolClient {
 		}
 		log('dial:ok peer=%s ms=%d%s', peer, Date.now() - t0, cid ? ` cid=${cid}` : '');
 
+		// Per-peer response deadline. The dial controller is already cleared once a
+		// stream is established, so a peer that connects but then never writes a frame
+		// (and never closes the stream) would hang the `first(...)` read below forever.
+		// Setting a timer alone is not enough — the underlying `for await` over the
+		// libp2p stream keeps awaiting regardless. The decisive action is to actively
+		// `stream.abort(...)`, which rejects the stream's async iterator and unblocks
+		// the read. A parent `options.signal` abort is forwarded the same way so a
+		// cancelled caller tears the stream down rather than leaking it. When neither
+		// `responseTimeoutMs` nor `signal` is supplied, no cap is imposed — preserving
+		// every existing caller (mirrors how omitting `dialTimeoutMs` imposes no dial cap).
+		const responseTimeoutMs = options?.responseTimeoutMs;
+		let responseTimer: ReturnType<typeof setTimeout> | undefined;
+		let responseTimeoutError: ResponseTimeoutError | undefined;
+		const onParentAbortResponse = () => {
+			try { stream.abort(options?.signal?.reason ?? new Error('aborted')); } catch { /* already torn down */ }
+		};
 		try {
+			if (responseTimeoutMs && responseTimeoutMs > 0) {
+				responseTimer = setTimeout(() => {
+					responseTimeoutError = new ResponseTimeoutError(peer, protocol, responseTimeoutMs);
+					try { stream.abort(responseTimeoutError); } catch { /* already torn down */ }
+				}, responseTimeoutMs);
+			}
+			if (options?.signal) {
+				if (options.signal.aborted) onParentAbortResponse();
+				else options.signal.addEventListener('abort', onParentAbortResponse, { once: true });
+			}
+
 			// Send the request using length-prefixed encoding
 			const encoded = pipe(
 				[new TextEncoder().encode(JSON.stringify(message))],
@@ -118,11 +162,28 @@ export class ProtocolClient {
 				}
 			) as AsyncIterable<T>;
 
-			const result = await first(() => source, () => { throw new Error('No response received') });
+			let result: T;
+			try {
+				result = await first(() => source, () => { throw new Error('No response received') });
+			} catch (err) {
+				// Aborting the stream (our timer or a parent abort) surfaces here as an
+				// iterator error. Translate it so callers see why the read ended.
+				if (responseTimeoutError) {
+					log('response:timeout peer=%s protocol=%s ms=%d%s', peer, protocol, Date.now() - t0, cid ? ` cid=${cid}` : '');
+					throw responseTimeoutError;
+				}
+				if (options?.signal?.aborted) {
+					throw options.signal.reason;
+				}
+				throw err;
+			}
 			log('response peer=%s protocol=%s ms=%d%s', peer, protocol, Date.now() - t0, cid ? ` cid=${cid}` : '');
 			return result;
 		} finally {
-			await stream.close();
+			if (responseTimer) clearTimeout(responseTimer);
+			if (options?.signal) options.signal.removeEventListener('abort', onParentAbortResponse);
+			// Closing an already-aborted stream must be safe.
+			try { await stream.close(); } catch { /* already torn down */ }
 		}
 	}
 }