@optimystic/db-p2p 0.21.0 → 0.24.0

package/src/libp2p-node-rn.ts

@@ -1,30 +1,30 @@
-import type { Libp2p } from 'libp2p';
-import {
-	createLibp2pNodeBase,
-	type Libp2pTransports,
-	type NodeOptions,
-	type RawStorageProvider,
-} from './libp2p-node-base.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<Libp2p> {
-	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,
+} 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,
+	});
+}

package/src/libp2p-node.ts

@@ -1,36 +1,36 @@
-import type { Libp2p } from 'libp2p';
-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';
-
-export type { Libp2pTransports, NodeOptions, RawStorageProvider };
-
-export async function createLibp2pNode(options: NodeOptions): Promise<Libp2p> {
-	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,
+} 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,
+	});
+}

package/src/logger.ts

@@ -2,8 +2,25 @@ import debug from 'debug'
 
 const BASE_NAMESPACE = 'optimystic:db-p2p'
 
-export function createLogger(subNamespace: string): debug.Debugger {
-	return debug(`${BASE_NAMESPACE}:${subNamespace}`)
+/**
+ * Build a `debug` logger under `optimystic:db-p2p:<subNamespace>`, optionally suffixed with the
+ * owning node's peer id (`:<first 12 chars>`) so lines from several nodes sharing one process —
+ * every integration test — are attributable. Omit `peerId` and the namespace is byte-for-byte the
+ * un-suffixed one, so callers that don't know their peer id are unaffected.
+ *
+ * NOTE: 12 chars matches the truncation the rest of this package already uses in log payloads, but
+ * every Ed25519 peer id starts with the constant `12D3KooW`, so only ~4 base58 characters actually
+ * distinguish nodes (~11M combinations — ample for the handful of nodes a test process runs).
+ * Widen this only if a run ever needs to match a namespace against a full peer id.
+ *
+ * NOTE: only the two classes the diagnosability ticket named pass a peer id today
+ * (`Libp2pKeyPeerNetwork`, `CoordinatorRepo`); the package's other ~30 `createLogger` call sites
+ * still log under a flat namespace. Thread a peer id through any of them if a future diagnosis
+ * needs per-node attribution from that subsystem — the mechanism is already here.
+ */
+export function createLogger(subNamespace: string, peerId?: string): debug.Debugger {
+	const suffix = peerId ? `:${peerId.substring(0, 12)}` : ''
+	return debug(`${BASE_NAMESPACE}:${subNamespace}${suffix}`)
 }
 
 export const verbose = typeof process !== 'undefined'

package/src/matchmaking/aggregate-counts.ts

@@ -1,104 +1,104 @@
-/**
- * Matchmaking — root-cohort aggregate-count producer (db-p2p, wires the substrate to the sweep summary).
- *
- * `docs/matchmaking.md` §Multi-cohort sweep / §Aggregated provider counts. A *promoted* topic's root
- * cohort answers a sweeping seeker with an {@link AggregateCountV1}: log-bucketed provider counts per
- * tier-1 prefix shard, **threshold-signed** (an attested *registered*-provider count — unlike the
- * advisory, single-member-signed `QueryReplyV1`). This module is the thin db-p2p binding that builds
- * that message from the root's per-shard accounting and the cohort threshold signer.
- *
- * Two invariants the doc mandates, enforced here:
- *
- *  - **Depth gate.** The aggregate is produced **only** when the tree depth at this cohort is
- *    `>= aggregate_count_minimum_tier` (default 1). A cold cohort that fell through to `NoState` has no
- *    tier-1 children to summarize, so {@link buildAggregateCount} returns `undefined` and the seeker
- *    falls back to the single-cohort sample.
- *  - **Log-bucketing.** Raw per-shard counts are quantized through the db-core {@link logBucketCount}
- *    (largest power of two `<= n`), never forwarded exactly.
- *
- * Like the cohort query handler, the inputs are injected (records/accounting, epoch, depth, the threshold
- * signer), so this unit-tests without a live FRET/libp2p stack — the mock-tier e2e that drives it from a
- * real promoted root is a documented follow-on. In the FRET host the root `CoordEngine` supplies
- * `shardCounts` from its child-cohort accounting (the per-tier-1 `childCohortCount` / gossip-derived
- * summaries), `treeDepth` from its tier state, `cohortEpoch` from the membership, and `thresholdSign`
- * bound to the cohort signer's `/sign` assembly.
- */
-
-import {
-	bytesToB64url,
-	logBucketCount,
-	aggregateCountSigningPayload,
-	AGGREGATE_COUNT_MINIMUM_TIER,
-	DEFAULT_FANOUT,
-	DEFAULT_SWEEP_TARGET_TIER,
-	type AggregateBucketV1,
-	type AggregateCountV1,
-} from "@optimystic/db-core";
-
-/** Everything {@link buildAggregateCount} needs from the root cohort, all injected. */
-export interface AggregateCountContext {
-	/** The topic id being summarized, 32 bytes. */
-	readonly topicId: Uint8Array;
-	/** The current cohort epoch, 32 bytes. */
-	readonly cohortEpoch: Uint8Array;
-	/**
-	 * Tree depth at this cohort. The aggregate is produced only when `treeDepth >= minimumTier`; a cold
-	 * cohort (depth 0) summarizes nothing.
-	 */
-	readonly treeDepth: number;
-	/**
-	 * Raw per-tier-1-shard provider counts, keyed by `prefixSlot` (`0..fanout-1`). Slots absent from the
-	 * map count as `0`. The root derives these from its child-cohort accounting; this binding log-buckets
-	 * them and never trusts the caller to pre-bucket.
-	 */
-	readonly shardCounts: ReadonlyMap<number, number>;
-	/**
-	 * Assemble a cohort threshold signature over the canonical aggregate image (db-p2p binds the cohort
-	 * signer). Returns the multisig blob plus the `>= minSigs` signer subset that produced it.
-	 */
-	readonly thresholdSign: (payload: Uint8Array) => Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }>;
-	/** The tier whose shards are summarized. Default {@link DEFAULT_SWEEP_TARGET_TIER} (1). */
-	readonly targetTier?: number;
-	/** Number of prefix slots `F`. Default {@link DEFAULT_FANOUT} (16). */
-	readonly fanout?: number;
-	/** Depth gate. Default {@link AGGREGATE_COUNT_MINIMUM_TIER} (1). */
-	readonly minimumTier?: number;
-	/** Emit zero-count shards too (default `false` — empty shards are omitted to keep the summary compact). */
-	readonly includeEmptyShards?: boolean;
-}
-
-/**
- * Build the threshold-signed {@link AggregateCountV1} for the root's per-shard accounting, or `undefined`
- * when the depth gate is not met (`treeDepth < minimumTier`). Counts are log-bucketed; the canonical
- * image is order-independent (the signing payload sorts buckets), so signer and verifier agree.
- */
-export async function buildAggregateCount(ctx: AggregateCountContext): Promise<AggregateCountV1 | undefined> {
-	const minimumTier = ctx.minimumTier ?? AGGREGATE_COUNT_MINIMUM_TIER;
-	if (ctx.treeDepth < minimumTier) {
-		// Cold / unpromoted root: no tier-1 children to summarize (matches the seeker's NoState fallback).
-		return undefined;
-	}
-
-	const targetTier = ctx.targetTier ?? DEFAULT_SWEEP_TARGET_TIER;
-	const fanout = ctx.fanout ?? DEFAULT_FANOUT;
-	const bucketCounts: AggregateBucketV1[] = [];
-	for (let prefixSlot = 0; prefixSlot < fanout; prefixSlot++) {
-		const count = logBucketCount(ctx.shardCounts.get(prefixSlot) ?? 0);
-		if (count > 0 || ctx.includeEmptyShards === true) {
-			bucketCounts.push({ targetTier, prefixSlot, count });
-		}
-	}
-
-	const unsigned: Omit<AggregateCountV1, "signature" | "signers"> = {
-		v: 1,
-		topicId: bytesToB64url(ctx.topicId),
-		bucketCounts,
-		cohortEpoch: bytesToB64url(ctx.cohortEpoch),
-	};
-	const { thresholdSig, signers } = await ctx.thresholdSign(aggregateCountSigningPayload(unsigned));
-	return {
-		...unsigned,
-		signature: bytesToB64url(thresholdSig),
-		signers: signers.map(bytesToB64url),
-	};
-}
+/**
+ * Matchmaking — root-cohort aggregate-count producer (db-p2p, wires the substrate to the sweep summary).
+ *
+ * `docs/matchmaking.md` §Multi-cohort sweep / §Aggregated provider counts. A *promoted* topic's root
+ * cohort answers a sweeping seeker with an {@link AggregateCountV1}: log-bucketed provider counts per
+ * tier-1 prefix shard, **threshold-signed** (an attested *registered*-provider count — unlike the
+ * advisory, single-member-signed `QueryReplyV1`). This module is the thin db-p2p binding that builds
+ * that message from the root's per-shard accounting and the cohort threshold signer.
+ *
+ * Two invariants the doc mandates, enforced here:
+ *
+ *  - **Depth gate.** The aggregate is produced **only** when the tree depth at this cohort is
+ *    `>= aggregate_count_minimum_tier` (default 1). A cold cohort that fell through to `NoState` has no
+ *    tier-1 children to summarize, so {@link buildAggregateCount} returns `undefined` and the seeker
+ *    falls back to the single-cohort sample.
+ *  - **Log-bucketing.** Raw per-shard counts are quantized through the db-core {@link logBucketCount}
+ *    (largest power of two `<= n`), never forwarded exactly.
+ *
+ * Like the cohort query handler, the inputs are injected (records/accounting, epoch, depth, the threshold
+ * signer), so this unit-tests without a live FRET/libp2p stack — the mock-tier e2e that drives it from a
+ * real promoted root is a documented follow-on. In the FRET host the root `CoordEngine` supplies
+ * `shardCounts` from its child-cohort accounting (the per-tier-1 `childCohortCount` / gossip-derived
+ * summaries), `treeDepth` from its tier state, `cohortEpoch` from the membership, and `thresholdSign`
+ * bound to the cohort signer's `/sign` assembly.
+ */
+
+import {
+	bytesToB64url,
+	logBucketCount,
+	aggregateCountSigningPayload,
+	AGGREGATE_COUNT_MINIMUM_TIER,
+	DEFAULT_FANOUT,
+	DEFAULT_SWEEP_TARGET_TIER,
+	type AggregateBucketV1,
+	type AggregateCountV1,
+} from "@optimystic/db-core";
+
+/** Everything {@link buildAggregateCount} needs from the root cohort, all injected. */
+export interface AggregateCountContext {
+	/** The topic id being summarized, 32 bytes. */
+	readonly topicId: Uint8Array;
+	/** The current cohort epoch, 32 bytes. */
+	readonly cohortEpoch: Uint8Array;
+	/**
+	 * Tree depth at this cohort. The aggregate is produced only when `treeDepth >= minimumTier`; a cold
+	 * cohort (depth 0) summarizes nothing.
+	 */
+	readonly treeDepth: number;
+	/**
+	 * Raw per-tier-1-shard provider counts, keyed by `prefixSlot` (`0..fanout-1`). Slots absent from the
+	 * map count as `0`. The root derives these from its child-cohort accounting; this binding log-buckets
+	 * them and never trusts the caller to pre-bucket.
+	 */
+	readonly shardCounts: ReadonlyMap<number, number>;
+	/**
+	 * Assemble a cohort threshold signature over the canonical aggregate image (db-p2p binds the cohort
+	 * signer). Returns the multisig blob plus the `>= minSigs` signer subset that produced it.
+	 */
+	readonly thresholdSign: (payload: Uint8Array) => Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }>;
+	/** The tier whose shards are summarized. Default {@link DEFAULT_SWEEP_TARGET_TIER} (1). */
+	readonly targetTier?: number;
+	/** Number of prefix slots `F`. Default {@link DEFAULT_FANOUT} (16). */
+	readonly fanout?: number;
+	/** Depth gate. Default {@link AGGREGATE_COUNT_MINIMUM_TIER} (1). */
+	readonly minimumTier?: number;
+	/** Emit zero-count shards too (default `false` — empty shards are omitted to keep the summary compact). */
+	readonly includeEmptyShards?: boolean;
+}
+
+/**
+ * Build the threshold-signed {@link AggregateCountV1} for the root's per-shard accounting, or `undefined`
+ * when the depth gate is not met (`treeDepth < minimumTier`). Counts are log-bucketed; the canonical
+ * image is order-independent (the signing payload sorts buckets), so signer and verifier agree.
+ */
+export async function buildAggregateCount(ctx: AggregateCountContext): Promise<AggregateCountV1 | undefined> {
+	const minimumTier = ctx.minimumTier ?? AGGREGATE_COUNT_MINIMUM_TIER;
+	if (ctx.treeDepth < minimumTier) {
+		// Cold / unpromoted root: no tier-1 children to summarize (matches the seeker's NoState fallback).
+		return undefined;
+	}
+
+	const targetTier = ctx.targetTier ?? DEFAULT_SWEEP_TARGET_TIER;
+	const fanout = ctx.fanout ?? DEFAULT_FANOUT;
+	const bucketCounts: AggregateBucketV1[] = [];
+	for (let prefixSlot = 0; prefixSlot < fanout; prefixSlot++) {
+		const count = logBucketCount(ctx.shardCounts.get(prefixSlot) ?? 0);
+		if (count > 0 || ctx.includeEmptyShards === true) {
+			bucketCounts.push({ targetTier, prefixSlot, count });
+		}
+	}
+
+	const unsigned: Omit<AggregateCountV1, "signature" | "signers"> = {
+		v: 1,
+		topicId: bytesToB64url(ctx.topicId),
+		bucketCounts,
+		cohortEpoch: bytesToB64url(ctx.cohortEpoch),
+	};
+	const { thresholdSig, signers } = await ctx.thresholdSign(aggregateCountSigningPayload(unsigned));
+	return {
+		...unsigned,
+		signature: bytesToB64url(thresholdSig),
+		signers: signers.map(bytesToB64url),
+	};
+}

package/src/matchmaking/index.ts

@@ -1,20 +1,20 @@
-/**
- * Matchmaking — db-p2p wiring to the cohort-topic substrate.
- *
- * The db-core `matchmaking` module owns the wire codecs, anchor, config, provider/seeker
- * decision/state, the capability filter, the pure query evaluation, and the hang-out decision engine;
- * these db-p2p bindings wire that logic to the cohort-topic substrate: the register/renew/withdraw
- * managers (tier T2), the cohort-side `QueryV1` handler, and the seeker walk client that drives the
- * hang-out-vs-continue walk. See `docs/matchmaking.md` §Provider registration / §Seeker query /
- * §Hang-out vs. continue.
- */
-
-export * from "./protocols.js";
-export * from "./provider-manager.js";
-export * from "./seeker-manager.js";
-export * from "./query-handler.js";
-export * from "./query-transport.js";
-export * from "./seeker-walk-client.js";
-export * from "./aggregate-counts.js";
-export * from "./traffic-validation.js";
-export * from "./module.js";
+/**
+ * Matchmaking — db-p2p wiring to the cohort-topic substrate.
+ *
+ * The db-core `matchmaking` module owns the wire codecs, anchor, config, provider/seeker
+ * decision/state, the capability filter, the pure query evaluation, and the hang-out decision engine;
+ * these db-p2p bindings wire that logic to the cohort-topic substrate: the register/renew/withdraw
+ * managers (tier T2), the cohort-side `QueryV1` handler, and the seeker walk client that drives the
+ * hang-out-vs-continue walk. See `docs/matchmaking.md` §Provider registration / §Seeker query /
+ * §Hang-out vs. continue.
+ */
+
+export * from "./protocols.js";
+export * from "./provider-manager.js";
+export * from "./seeker-manager.js";
+export * from "./query-handler.js";
+export * from "./query-transport.js";
+export * from "./seeker-walk-client.js";
+export * from "./aggregate-counts.js";
+export * from "./traffic-validation.js";
+export * from "./module.js";