@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/cohort-topic/topic-router.ts

@@ -1,77 +1,77 @@
-import type { ITopicRouter, PeerRef, RingCoord } from "@optimystic/db-core";
-import { bytesToB64url, b64urlToBytes, encodeCohortMessage } from "@optimystic/db-core";
-import type { Libp2p } from "libp2p";
-import type { FretService, RouteAndMaybeActV1, NearAnchorV1 } from "p2p-fret";
-import { bytesToPeerId } from "./peer-codec.js";
-import { requestResponse, DEFAULT_STREAM_MAX_BYTES } from "./stream-util.js";
-import { PROTOCOL_COHORT_REGISTER } from "./protocols.js";
-
-/** A FRET `routeAct` result carrying a cohort reply. */
-function isCommit(res: NearAnchorV1 | { commitCertificate: string }): res is { commitCertificate: string } {
-	return typeof res === "object" && res !== null && "commitCertificate" in res;
-}
-
-export interface FretTopicRouterOptions {
-	/** The `/register` protocol id (defaults to the canonical one). */
-	readonly registerProtocol?: string;
-	/** RPC TTL hops for `RouteAndMaybeAct`. Default 16. */
-	readonly ttl?: number;
-	/** Per-frame ceiling. Default {@link DEFAULT_STREAM_MAX_BYTES}. */
-	readonly maxBytes?: number;
-	/** Monotonic clock (unix ms); injectable for tests. Default `Date.now`. */
-	readonly clock?: () => number;
-}
-
-/**
- * FRET-backed {@link ITopicRouter}.
- *
- * `routeAndAct` maps onto FRET's `RouteAndMaybeAct` (`FretService.routeAct`): the `RegisterV1` frame
- * rides the `activity` field (base64url), routed to the cohort owning `key = coord_d(self, topicId)`,
- * collecting `want_k = k` participants and `min_sigs = k − x`. The cohort's activity callback (set by
- * the host) runs the willingness / cold-start / admission decision and returns the encoded
- * `RegisterReplyV1` as the `commitCertificate`; this adapter decodes it back to bytes. A bare
- * `NearAnchorV1` (no in-cluster activity ran) is surfaced to the walk as `no_state`.
- *
- * `dialMember` is the post-registration direct path: a libp2p dial of the `/register` protocol to the
- * cached primary, used by the renewal ping (`docs/cohort-topic.md` §FRET integration L457-460).
- */
-export class FretTopicRouter implements ITopicRouter {
-	private readonly registerProtocol: string;
-	private readonly ttl: number;
-	private readonly maxBytes: number;
-	private readonly clock: () => number;
-
-	constructor(private readonly node: Libp2p, private readonly fret: FretService, options: FretTopicRouterOptions = {}) {
-		this.registerProtocol = options.registerProtocol ?? PROTOCOL_COHORT_REGISTER;
-		this.ttl = options.ttl ?? 16;
-		this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
-		this.clock = options.clock ?? ((): number => Date.now());
-	}
-
-	async routeAndAct(key: RingCoord, activity: Uint8Array, opts: { wantK: number; minSigs: number }): Promise<Uint8Array> {
-		const now = this.clock();
-		const msg: RouteAndMaybeActV1 = {
-			v: 1,
-			key: bytesToB64url(key),
-			want_k: opts.wantK,
-			min_sigs: opts.minSigs,
-			ttl: this.ttl,
-			activity: bytesToB64url(activity),
-			correlation_id: bytesToB64url(key) + ":" + now,
-			timestamp: now,
-			signature: "",
-		};
-		const res = await this.fret.routeAct(msg);
-		if (isCommit(res)) {
-			return b64urlToBytes(res.commitCertificate);
-		}
-		// No in-cluster activity ran (we only reached an anchor hint): the walk treats this as NoState
-		// and steps toward the root.
-		return encodeCohortMessage({ v: 1, result: "no_state" }, this.maxBytes);
-	}
-
-	async dialMember(member: PeerRef, activity: Uint8Array): Promise<Uint8Array> {
-		const peer = bytesToPeerId(member.id);
-		return requestResponse(this.node, peer, this.registerProtocol, activity, this.maxBytes);
-	}
-}
+import type { ITopicRouter, PeerRef, RingCoord } from "@optimystic/db-core";
+import { bytesToB64url, b64urlToBytes, encodeCohortMessage } from "@optimystic/db-core";
+import type { Libp2p } from "libp2p";
+import type { FretService, RouteAndMaybeActV1, NearAnchorV1 } from "p2p-fret";
+import { bytesToPeerId } from "./peer-codec.js";
+import { requestResponse, DEFAULT_STREAM_MAX_BYTES } from "./stream-util.js";
+import { PROTOCOL_COHORT_REGISTER } from "./protocols.js";
+
+/** A FRET `routeAct` result carrying a cohort reply. */
+function isCommit(res: NearAnchorV1 | { commitCertificate: string }): res is { commitCertificate: string } {
+	return typeof res === "object" && res !== null && "commitCertificate" in res;
+}
+
+export interface FretTopicRouterOptions {
+	/** The `/register` protocol id (defaults to the canonical one). */
+	readonly registerProtocol?: string;
+	/** RPC TTL hops for `RouteAndMaybeAct`. Default 16. */
+	readonly ttl?: number;
+	/** Per-frame ceiling. Default {@link DEFAULT_STREAM_MAX_BYTES}. */
+	readonly maxBytes?: number;
+	/** Monotonic clock (unix ms); injectable for tests. Default `Date.now`. */
+	readonly clock?: () => number;
+}
+
+/**
+ * FRET-backed {@link ITopicRouter}.
+ *
+ * `routeAndAct` maps onto FRET's `RouteAndMaybeAct` (`FretService.routeAct`): the `RegisterV1` frame
+ * rides the `activity` field (base64url), routed to the cohort owning `key = coord_d(self, topicId)`,
+ * collecting `want_k = k` participants and `min_sigs = k − x`. The cohort's activity callback (set by
+ * the host) runs the willingness / cold-start / admission decision and returns the encoded
+ * `RegisterReplyV1` as the `commitCertificate`; this adapter decodes it back to bytes. A bare
+ * `NearAnchorV1` (no in-cluster activity ran) is surfaced to the walk as `no_state`.
+ *
+ * `dialMember` is the post-registration direct path: a libp2p dial of the `/register` protocol to the
+ * cached primary, used by the renewal ping (`docs/cohort-topic.md` §FRET integration L457-460).
+ */
+export class FretTopicRouter implements ITopicRouter {
+	private readonly registerProtocol: string;
+	private readonly ttl: number;
+	private readonly maxBytes: number;
+	private readonly clock: () => number;
+
+	constructor(private readonly node: Libp2p, private readonly fret: FretService, options: FretTopicRouterOptions = {}) {
+		this.registerProtocol = options.registerProtocol ?? PROTOCOL_COHORT_REGISTER;
+		this.ttl = options.ttl ?? 16;
+		this.maxBytes = options.maxBytes ?? DEFAULT_STREAM_MAX_BYTES;
+		this.clock = options.clock ?? ((): number => Date.now());
+	}
+
+	async routeAndAct(key: RingCoord, activity: Uint8Array, opts: { wantK: number; minSigs: number }): Promise<Uint8Array> {
+		const now = this.clock();
+		const msg: RouteAndMaybeActV1 = {
+			v: 1,
+			key: bytesToB64url(key),
+			want_k: opts.wantK,
+			min_sigs: opts.minSigs,
+			ttl: this.ttl,
+			activity: bytesToB64url(activity),
+			correlation_id: bytesToB64url(key) + ":" + now,
+			timestamp: now,
+			signature: "",
+		};
+		const res = await this.fret.routeAct(msg);
+		if (isCommit(res)) {
+			return b64urlToBytes(res.commitCertificate);
+		}
+		// No in-cluster activity ran (we only reached an anchor hint): the walk treats this as NoState
+		// and steps toward the root.
+		return encodeCohortMessage({ v: 1, result: "no_state" }, this.maxBytes);
+	}
+
+	async dialMember(member: PeerRef, activity: Uint8Array): Promise<Uint8Array> {
+		const peer = bytesToPeerId(member.id);
+		return requestResponse(this.node, peer, this.registerProtocol, activity, this.maxBytes);
+	}
+}

package/src/dispute/arbitrator-selection.ts

@@ -1,138 +1,138 @@
-/**
- * Verifiable dispersed arbitrator sampling.
- *
- * The old selection walked the ring positions *immediately adjacent* to the disputed block (sort every
- * peer by XOR distance to `hash(blockId)`, skip the original cluster, take the next K). That recruits
- * from exactly the neighborhood an attacker already had to own to capture the block's cluster — so
- * "independent" arbitration drew from the *least* independent population (see `docs/correctness.md` §7.1
- * Sybil, Theorems 8 & 10).
- *
- * Instead we derive `count` pseudo-random ring coordinates from `hash(blockId ‖ round ‖ epoch ‖ i)` and
- * pick the peer nearest each coordinate. SHA-256 output is uniform over the ring, so the coordinates land
- * spread across the whole keyspace and the sampled arbitrators are drawn from the whole population, not
- * the block's neighborhood. To capture them an attacker needs IDs near many independent random points —
- * a fraction of the *entire* network, not one locale.
- *
- * Two properties both hold:
- *  - **Deterministic & independently verifiable** — every honest node, given the same
- *    `(blockId, round, epoch)` and the same agreed membership, computes the identical set. This is what
- *    lets the dispute verify path re-derive the eligible set instead of trusting a declared one.
- *  - **Unpredictable / not pre-positionable** — the coordinates for round r are pinned only once
- *    `(blockId, round, epoch)` are all fixed. `round` advances in real time during the dispute; `epoch`
- *    is the agreed membership epoch, which rotates with membership and cannot be freely advanced by the
- *    attacker. So the attacker cannot know far enough ahead which coordinates to migrate IDs toward.
- */
-
-/**
- * Resolve the peer-id strings nearest a ring coordinate, in ascending distance order.
- * Production: FRET `assembleCohort(coord, wants)`. Tests: sort a fixed `KnownPeer[]` by XOR distance.
- * May return fewer than `wants` — that signals the whole eligible membership fit in the slice.
- */
-export type NearestResolver = (coord: Uint8Array, wants: number) => string[] | Promise<string[]>;
-
-/** FRET-compatible ring hash of arbitrary bytes → coordinate (SHA-256; see db-core `RingHash.H` / FRET `hashKey`). */
-export type RingHashFn = (bytes: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-
-export interface ArbitratorSamplingParams {
-	/** Disputed block id bytes (messageHash fallback), as bound into the dispute. */
-	readonly blockId: Uint8Array;
-	/** Escalation round, 0-based. Round 0 is the first arbitration. */
-	readonly round: number;
-	/**
-	 * Agreed membership epoch bytes. Pins the draw to an epoch the attacker cannot freely advance.
-	 * Interim source (until `design-cluster-membership-agreement` lands): hash of the agreed responsible
-	 * set the admission gate already converges on (`cluster-membership-admission-gate`).
-	 */
-	readonly epoch: Uint8Array;
-	/** Number of fresh, distinct arbitrators to draw this round. */
-	readonly count: number;
-	/** Peer-id strings to exclude: original cluster + self + arbitrators already drawn in prior rounds. */
-	readonly exclude: ReadonlySet<string>;
-}
-
-/** Little-endian u32 encoding of `n` — the canonical wire encoding for `round` and the coordinate index. */
-function u32le(n: number): Uint8Array {
-	const out = new Uint8Array(4);
-	new DataView(out.buffer).setUint32(0, n >>> 0, true);
-	return out;
-}
-
-/** Concatenate byte spans left-to-right. */
-function concatBytes(parts: Uint8Array[]): Uint8Array {
-	let total = 0;
-	for (const p of parts) total += p.length;
-	const out = new Uint8Array(total);
-	let off = 0;
-	for (const p of parts) { out.set(p, off); off += p.length; }
-	return out;
-}
-
-/**
- * The exact preimage the i-th coordinate of a round hashes: `blockId ‖ u32le(round) ‖ epoch ‖ u32le(i)`.
- * Folding `round`, `epoch`, and `i` in gives: (a) each round samples a distinct population (round changes
- * every coordinate); (b) each of the `count` coordinates is an independent uniform draw (dispersion);
- * (c) a replacement for an offline/duplicate pick is the *next* peer in the same coordinate's ordering,
- * never a fresh challenger-chosen peer. The canonical little-endian encoding is asserted by a golden
- * vector so two implementations hash identical bytes.
- */
-export function coordinatePreimage(blockId: Uint8Array, round: number, epoch: Uint8Array, i: number): Uint8Array {
-	return concatBytes([blockId, u32le(round), epoch, u32le(i)]);
-}
-
-/**
- * Deterministic dispersed arbitrator draw. Returns up to `count` distinct peer-id strings; fewer only
- * when the network is too small to yield that many (small-network fallback) — never duplicates, never
- * loops. In the degenerate all-peers-in-cluster case, returns `[]`.
- *
- * For each coordinate `i` the nearest unseen peer is chosen. When a coordinate's nearest slice is
- * entirely `seen` (excluded, or already picked for an earlier coordinate) the slice is widened
- * (`wants` grows) and retried; if widening exposes the whole eligible membership with nobody fresh, the
- * entire membership is exhausted and the (short) picks are returned. Replacement of an offline/duplicate
- * pick is thus the deterministic next peer in the same coordinate's ordering, identical on every honest
- * node, so disputing parties cannot steer it.
- */
-export async function sampleArbitrators(
-	params: ArbitratorSamplingParams,
-	nearest: NearestResolver,
-	hash: RingHashFn,
-): Promise<string[]> {
-	const { blockId, round, epoch, count, exclude } = params;
-	const picks: string[] = [];
-	if (count <= 0) return picks;
-
-	const seen = new Set<string>(exclude);
-
-	for (let i = 0; picks.length < count; i++) {
-		const coord = await hash(coordinatePreimage(blockId, round, epoch, i));
-
-		// Walk this coordinate's ascending-distance ordering for the first peer we have not yet seen,
-		// widening the slice until we find one or have proven the whole eligible membership is exhausted.
-		// NOTE: `wants` starts at `seen.size + 1` (conservative — guarantees exhaustion is provable in one
-		// widen). Starting at 1 and widening only on a seen-collision is also correct and asks the resolver
-		// for far fewer peers per coordinate; if `assembleCohort` ever shows up as hot here, start smaller.
-		let wants = seen.size + 1;
-		let prevLen = -1;
-		let picked: string | undefined;
-		let membershipExhausted = false;
-		for (;;) {
-			const cands = await nearest(coord, wants);
-			const fresh = cands.find(c => !seen.has(c));
-			if (fresh !== undefined) { picked = fresh; break; }
-			// No fresh peer in this slice. If the resolver returned fewer than we asked (or the slice
-			// stopped growing), we have seen the whole eligible membership from this coordinate — and
-			// since every one of them is already `seen`, no future coordinate can yield anything new.
-			if (cands.length < wants || cands.length <= prevLen) { membershipExhausted = true; break; }
-			prevLen = cands.length;
-			wants *= 2;
-		}
-
-		if (picked !== undefined) {
-			picks.push(picked);
-			seen.add(picked);
-		} else if (membershipExhausted) {
-			break;
-		}
-	}
-
-	return picks;
-}
+/**
+ * Verifiable dispersed arbitrator sampling.
+ *
+ * The old selection walked the ring positions *immediately adjacent* to the disputed block (sort every
+ * peer by XOR distance to `hash(blockId)`, skip the original cluster, take the next K). That recruits
+ * from exactly the neighborhood an attacker already had to own to capture the block's cluster — so
+ * "independent" arbitration drew from the *least* independent population (see `docs/correctness.md` §7.1
+ * Sybil, Theorems 8 & 10).
+ *
+ * Instead we derive `count` pseudo-random ring coordinates from `hash(blockId ‖ round ‖ epoch ‖ i)` and
+ * pick the peer nearest each coordinate. SHA-256 output is uniform over the ring, so the coordinates land
+ * spread across the whole keyspace and the sampled arbitrators are drawn from the whole population, not
+ * the block's neighborhood. To capture them an attacker needs IDs near many independent random points —
+ * a fraction of the *entire* network, not one locale.
+ *
+ * Two properties both hold:
+ *  - **Deterministic & independently verifiable** — every honest node, given the same
+ *    `(blockId, round, epoch)` and the same agreed membership, computes the identical set. This is what
+ *    lets the dispute verify path re-derive the eligible set instead of trusting a declared one.
+ *  - **Unpredictable / not pre-positionable** — the coordinates for round r are pinned only once
+ *    `(blockId, round, epoch)` are all fixed. `round` advances in real time during the dispute; `epoch`
+ *    is the agreed membership epoch, which rotates with membership and cannot be freely advanced by the
+ *    attacker. So the attacker cannot know far enough ahead which coordinates to migrate IDs toward.
+ */
+
+/**
+ * Resolve the peer-id strings nearest a ring coordinate, in ascending distance order.
+ * Production: FRET `assembleCohort(coord, wants)`. Tests: sort a fixed `KnownPeer[]` by XOR distance.
+ * May return fewer than `wants` — that signals the whole eligible membership fit in the slice.
+ */
+export type NearestResolver = (coord: Uint8Array, wants: number) => string[] | Promise<string[]>;
+
+/** FRET-compatible ring hash of arbitrary bytes → coordinate (SHA-256; see db-core `RingHash.H` / FRET `hashKey`). */
+export type RingHashFn = (bytes: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+
+export interface ArbitratorSamplingParams {
+	/** Disputed block id bytes (messageHash fallback), as bound into the dispute. */
+	readonly blockId: Uint8Array;
+	/** Escalation round, 0-based. Round 0 is the first arbitration. */
+	readonly round: number;
+	/**
+	 * Agreed membership epoch bytes. Pins the draw to an epoch the attacker cannot freely advance.
+	 * Interim source (until `design-cluster-membership-agreement` lands): hash of the agreed responsible
+	 * set the admission gate already converges on (`cluster-membership-admission-gate`).
+	 */
+	readonly epoch: Uint8Array;
+	/** Number of fresh, distinct arbitrators to draw this round. */
+	readonly count: number;
+	/** Peer-id strings to exclude: original cluster + self + arbitrators already drawn in prior rounds. */
+	readonly exclude: ReadonlySet<string>;
+}
+
+/** Little-endian u32 encoding of `n` — the canonical wire encoding for `round` and the coordinate index. */
+function u32le(n: number): Uint8Array {
+	const out = new Uint8Array(4);
+	new DataView(out.buffer).setUint32(0, n >>> 0, true);
+	return out;
+}
+
+/** Concatenate byte spans left-to-right. */
+function concatBytes(parts: Uint8Array[]): Uint8Array {
+	let total = 0;
+	for (const p of parts) total += p.length;
+	const out = new Uint8Array(total);
+	let off = 0;
+	for (const p of parts) { out.set(p, off); off += p.length; }
+	return out;
+}
+
+/**
+ * The exact preimage the i-th coordinate of a round hashes: `blockId ‖ u32le(round) ‖ epoch ‖ u32le(i)`.
+ * Folding `round`, `epoch`, and `i` in gives: (a) each round samples a distinct population (round changes
+ * every coordinate); (b) each of the `count` coordinates is an independent uniform draw (dispersion);
+ * (c) a replacement for an offline/duplicate pick is the *next* peer in the same coordinate's ordering,
+ * never a fresh challenger-chosen peer. The canonical little-endian encoding is asserted by a golden
+ * vector so two implementations hash identical bytes.
+ */
+export function coordinatePreimage(blockId: Uint8Array, round: number, epoch: Uint8Array, i: number): Uint8Array {
+	return concatBytes([blockId, u32le(round), epoch, u32le(i)]);
+}
+
+/**
+ * Deterministic dispersed arbitrator draw. Returns up to `count` distinct peer-id strings; fewer only
+ * when the network is too small to yield that many (small-network fallback) — never duplicates, never
+ * loops. In the degenerate all-peers-in-cluster case, returns `[]`.
+ *
+ * For each coordinate `i` the nearest unseen peer is chosen. When a coordinate's nearest slice is
+ * entirely `seen` (excluded, or already picked for an earlier coordinate) the slice is widened
+ * (`wants` grows) and retried; if widening exposes the whole eligible membership with nobody fresh, the
+ * entire membership is exhausted and the (short) picks are returned. Replacement of an offline/duplicate
+ * pick is thus the deterministic next peer in the same coordinate's ordering, identical on every honest
+ * node, so disputing parties cannot steer it.
+ */
+export async function sampleArbitrators(
+	params: ArbitratorSamplingParams,
+	nearest: NearestResolver,
+	hash: RingHashFn,
+): Promise<string[]> {
+	const { blockId, round, epoch, count, exclude } = params;
+	const picks: string[] = [];
+	if (count <= 0) return picks;
+
+	const seen = new Set<string>(exclude);
+
+	for (let i = 0; picks.length < count; i++) {
+		const coord = await hash(coordinatePreimage(blockId, round, epoch, i));
+
+		// Walk this coordinate's ascending-distance ordering for the first peer we have not yet seen,
+		// widening the slice until we find one or have proven the whole eligible membership is exhausted.
+		// NOTE: `wants` starts at `seen.size + 1` (conservative — guarantees exhaustion is provable in one
+		// widen). Starting at 1 and widening only on a seen-collision is also correct and asks the resolver
+		// for far fewer peers per coordinate; if `assembleCohort` ever shows up as hot here, start smaller.
+		let wants = seen.size + 1;
+		let prevLen = -1;
+		let picked: string | undefined;
+		let membershipExhausted = false;
+		for (;;) {
+			const cands = await nearest(coord, wants);
+			const fresh = cands.find(c => !seen.has(c));
+			if (fresh !== undefined) { picked = fresh; break; }
+			// No fresh peer in this slice. If the resolver returned fewer than we asked (or the slice
+			// stopped growing), we have seen the whole eligible membership from this coordinate — and
+			// since every one of them is already `seen`, no future coordinate can yield anything new.
+			if (cands.length < wants || cands.length <= prevLen) { membershipExhausted = true; break; }
+			prevLen = cands.length;
+			wants *= 2;
+		}
+
+		if (picked !== undefined) {
+			picks.push(picked);
+			seen.add(picked);
+		} else if (membershipExhausted) {
+			break;
+		}
+	}
+
+	return picks;
+}