@optimystic/db-p2p 0.0.1

package/src/libp2p-key-network.ts

@@ -0,0 +1,334 @@
+import type { AbortOptions, Libp2p, PeerId, Stream } from "@libp2p/interface";
+import { toString as u8ToString } from 'uint8arrays/to-string'
+import type { ClusterPeers, FindCoordinatorOptions, IKeyNetwork, IPeerNetwork } from "@optimystic/db-core";
+import { peerIdFromString } from '@libp2p/peer-id'
+import { multiaddr } from '@multiformats/multiaddr'
+import type { FretService } from 'p2p-fret'
+import { hashKey } from 'p2p-fret'
+import { createLogger } from './logger.js'
+
+interface WithFretService { services?: { fret?: FretService } }
+
+/**
+ * Configuration options for self-coordination behavior
+ */
+export interface SelfCoordinationConfig {
+	/** Time (ms) after last connection before allowing self-coordination. Default: 30000 */
+	gracePeriodMs?: number;
+	/** Threshold for suspicious network shrinkage (0-1). >50% drop is suspicious. Default: 0.5 */
+	shrinkageThreshold?: number;
+	/** Allow self-coordination at all. Default: true (for testing). Set false in production. */
+	allowSelfCoordination?: boolean;
+}
+
+/**
+ * Decision result from self-coordination guard
+ */
+export interface SelfCoordinationDecision {
+	allow: boolean;
+	reason: 'bootstrap-node' | 'partition-detected' | 'suspicious-shrinkage' | 'grace-period-not-elapsed' | 'extended-isolation' | 'disabled';
+	warn?: boolean;
+}
+
+export class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
+	private readonly selfCoordinationConfig: Required<SelfCoordinationConfig>;
+	private networkHighWaterMark = 1;
+	private lastConnectedTime = Date.now();
+
+	constructor(
+		private readonly libp2p: Libp2p,
+		private readonly clusterSize: number = 16,
+		selfCoordinationConfig?: SelfCoordinationConfig
+	) {
+		this.selfCoordinationConfig = {
+			gracePeriodMs: selfCoordinationConfig?.gracePeriodMs ?? 30_000,
+			shrinkageThreshold: selfCoordinationConfig?.shrinkageThreshold ?? 0.5,
+			allowSelfCoordination: selfCoordinationConfig?.allowSelfCoordination ?? true
+		};
+		this.setupConnectionTracking();
+	}
+
+	// coordinator cache: key (base64url) -> peerId until expiry (bounded LRU-ish via Map insertion order)
+	private readonly coordinatorCache = new Map<string, { id: PeerId, expires: number }>()
+	private static readonly MAX_CACHE_ENTRIES = 1000
+	private readonly log = createLogger('libp2p-key-network')
+
+	private toCacheKey(key: Uint8Array): string { return u8ToString(key, 'base64url') }
+
+	/**
+	 * Set up connection event tracking to update high water mark and last connected time.
+	 */
+	private setupConnectionTracking(): void {
+		this.libp2p.addEventListener('connection:open', () => {
+			this.updateNetworkObservations();
+		});
+	}
+
+	/**
+	 * Update network high water mark and last connected time.
+	 * Called on new connections.
+	 */
+	private updateNetworkObservations(): void {
+		const connections = this.libp2p.getConnections?.() ?? [];
+		if (connections.length > 0) {
+			this.lastConnectedTime = Date.now();
+		}
+
+		try {
+			const fret = this.getFret();
+			const estimate = fret.getNetworkSizeEstimate();
+			if (estimate.size_estimate > this.networkHighWaterMark) {
+				this.networkHighWaterMark = estimate.size_estimate;
+				this.log('network-hwm-updated mark=%d confidence=%f', this.networkHighWaterMark, estimate.confidence);
+			}
+		} catch {
+			// FRET not available - use connection count as fallback
+			const connectionCount = this.libp2p.getConnections?.().length ?? 0;
+			const observedSize = connectionCount + 1; // +1 for self
+			if (observedSize > this.networkHighWaterMark) {
+				this.networkHighWaterMark = observedSize;
+				this.log('network-hwm-updated mark=%d (from connections)', this.networkHighWaterMark);
+			}
+		}
+	}
+
+	/**
+	 * Determine if self-coordination should be allowed based on network observations.
+	 *
+	 * Principle: If we've ever seen a larger network, assume our connectivity is the problem,
+	 * not the network shrinking.
+	 */
+	shouldAllowSelfCoordination(): SelfCoordinationDecision {
+		// Check global disable
+		if (!this.selfCoordinationConfig.allowSelfCoordination) {
+			return { allow: false, reason: 'disabled' };
+		}
+
+		// Case 1: New/bootstrap node (never seen larger network)
+		if (this.networkHighWaterMark <= 1) {
+			return { allow: true, reason: 'bootstrap-node' };
+		}
+
+		// Case 2: Check for partition via FRET
+		try {
+			const fret = this.getFret();
+			if (fret.detectPartition()) {
+				this.log('self-coord-blocked: partition-detected');
+				return { allow: false, reason: 'partition-detected' };
+			}
+
+			// Case 3: Suspicious network shrinkage (>threshold drop)
+			const estimate = fret.getNetworkSizeEstimate();
+			const shrinkage = 1 - (estimate.size_estimate / this.networkHighWaterMark);
+			if (shrinkage > this.selfCoordinationConfig.shrinkageThreshold) {
+				this.log('self-coord-blocked: suspicious-shrinkage current=%d hwm=%d shrinkage=%f',
+					estimate.size_estimate, this.networkHighWaterMark, shrinkage);
+				return { allow: false, reason: 'suspicious-shrinkage' };
+			}
+		} catch {
+			// FRET not available - be conservative
+			const connections = this.libp2p.getConnections?.() ?? [];
+			if (this.networkHighWaterMark > 1 && connections.length === 0) {
+				// We've seen peers before but have none now - suspicious
+				const timeSinceConnection = Date.now() - this.lastConnectedTime;
+				if (timeSinceConnection < this.selfCoordinationConfig.gracePeriodMs) {
+					this.log('self-coord-blocked: grace-period-not-elapsed since=%dms', timeSinceConnection);
+					return { allow: false, reason: 'grace-period-not-elapsed' };
+				}
+			}
+		}
+
+		// Case 4: Recently connected (grace period not elapsed)
+		const timeSinceConnection = Date.now() - this.lastConnectedTime;
+		if (timeSinceConnection < this.selfCoordinationConfig.gracePeriodMs) {
+			const connections = this.libp2p.getConnections?.() ?? [];
+			// Only block if we have no connections but did recently
+			if (connections.length === 0) {
+				this.log('self-coord-blocked: grace-period-not-elapsed since=%dms', timeSinceConnection);
+				return { allow: false, reason: 'grace-period-not-elapsed' };
+			}
+		}
+
+		// Case 5: Extended isolation with gradual shrinkage - allow with warning
+		this.log('self-coord-allowed: extended-isolation (warn)');
+		return { allow: true, reason: 'extended-isolation', warn: true };
+	}
+
+	public recordCoordinator(key: Uint8Array, peerId: PeerId, ttlMs = 30 * 60 * 1000): void {
+		const k = this.toCacheKey(key)
+		const now = Date.now()
+		for (const [ck, entry] of this.coordinatorCache) {
+			if (entry.expires <= now) this.coordinatorCache.delete(ck)
+		}
+		this.coordinatorCache.set(k, { id: peerId, expires: now + ttlMs })
+		while (this.coordinatorCache.size > Libp2pKeyPeerNetwork.MAX_CACHE_ENTRIES) {
+			const firstKey = this.coordinatorCache.keys().next().value as string | undefined
+			if (firstKey == null) break
+			this.coordinatorCache.delete(firstKey)
+		}
+	}
+
+	private getCachedCoordinator(key: Uint8Array): PeerId | undefined {
+		const k = this.toCacheKey(key)
+		const hit = this.coordinatorCache.get(k)
+		if (hit && hit.expires > Date.now()) return hit.id
+		if (hit) this.coordinatorCache.delete(k)
+		return undefined
+	}
+
+	connect(peerId: PeerId, protocol: string, _options?: AbortOptions): Promise<Stream> {
+		const conns = (this.libp2p as any).getConnections?.(peerId) ?? []
+		if (Array.isArray(conns) && conns.length > 0 && typeof conns[0]?.newStream === 'function') {
+			return conns[0].newStream([protocol]) as Promise<Stream>
+		}
+		const dialOptions = { runOnLimitedConnection: true, negotiateFully: false } as const
+		return this.libp2p.dialProtocol(peerId, [protocol], dialOptions)
+	}
+
+	private getFret(): FretService {
+		const svc = (this.libp2p as unknown as WithFretService).services?.fret
+		if (svc == null) throw new Error('FRET service is not registered on this libp2p node')
+		return svc
+	}
+
+	private async getNeighborIdsForKey(key: Uint8Array, wants: number): Promise<string[]> {
+		const fret = this.getFret()
+		const coord = await hashKey(key)
+		const both = fret.getNeighbors(coord, 'both', wants)
+		return Array.from(new Set(both)).slice(0, wants)
+	}
+
+	async findCoordinator(key: Uint8Array, _options?: Partial<FindCoordinatorOptions>): Promise<PeerId> {
+		const excludedSet = new Set<string>((_options?.excludedPeers ?? []).map(p => p.toString()))
+		const keyStr = this.toCacheKey(key).substring(0, 12);
+
+		this.log('findCoordinator:start key=%s excluded=%o', keyStr, Array.from(excludedSet).map(s => s.substring(0, 12)))
+
+		// honor cache if not excluded
+		const cached = this.getCachedCoordinator(key)
+		if (cached != null && !excludedSet.has(cached.toString())) {
+			this.log('findCoordinator:cached-hit key=%s coordinator=%s', keyStr, cached.toString().substring(0, 12))
+			return cached
+		}
+
+		// Retry logic: connections can be temporarily down, so retry a few times with delay
+		const maxRetries = 3;
+		const retryDelayMs = 500;
+
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			// Get currently connected peers for filtering
+			const connected = (this.libp2p.getConnections?.() ?? []).map((c: any) => c.remotePeer) as PeerId[]
+			const connectedSet = new Set(connected.map(p => p.toString()))
+			this.log('findCoordinator:connected-peers key=%s count=%d peers=%o attempt=%d', keyStr, connected.length, connected.map(p => p.toString().substring(0, 12)), attempt)
+
+			// prefer FRET neighbors that are also connected, pick first non-excluded
+			try {
+				const ids = await this.getNeighborIdsForKey(key, this.clusterSize)
+				this.log('findCoordinator:fret-neighbors key=%s candidates=%o', keyStr, ids.map(s => s.substring(0, 12)))
+
+				// Filter to only connected FRET neighbors
+				const connectedFretIds = ids.filter(id => connectedSet.has(id) || id === this.libp2p.peerId.toString())
+				this.log('findCoordinator:fret-connected key=%s count=%d peers=%o', keyStr, connectedFretIds.length, connectedFretIds.map(s => s.substring(0, 12)))
+
+				const pick = connectedFretIds.find(id => !excludedSet.has(id))
+				if (pick) {
+					const pid = peerIdFromString(pick)
+					this.recordCoordinator(key, pid)
+					this.log('findCoordinator:fret-selected key=%s coordinator=%s', keyStr, pick.substring(0, 12))
+					return pid
+				}
+			} catch (err) {
+				this.log('findCoordinator getNeighborIdsForKey failed - %o', err)
+			}
+
+			// fallback: prefer any existing connected peer that's not excluded
+			const connectedPick = connected.find(p => !excludedSet.has(p.toString()))
+			if (connectedPick) {
+				this.recordCoordinator(key, connectedPick)
+				this.log('findCoordinator:connected-fallback key=%s coordinator=%s', keyStr, connectedPick.toString().substring(0, 12))
+				return connectedPick
+			}
+
+			// If no connections and not the last attempt, wait and retry
+			if (connected.length === 0 && attempt < maxRetries - 1) {
+				this.log('findCoordinator:no-connections-retry key=%s attempt=%d delay=%dms', keyStr, attempt, retryDelayMs)
+				await new Promise(resolve => setTimeout(resolve, retryDelayMs))
+				continue
+			}
+		}
+
+		// last resort: prefer self only if not excluded and guard allows
+		const self = this.libp2p.peerId
+		if (!excludedSet.has(self.toString())) {
+			const decision = this.shouldAllowSelfCoordination();
+			if (!decision.allow) {
+				this.log('findCoordinator:self-coord-blocked key=%s reason=%s', keyStr, decision.reason);
+				throw new Error(`Self-coordination blocked: ${decision.reason}. No coordinator available for key.`);
+			}
+			if (decision.warn) {
+				this.log('findCoordinator:self-selected-warn key=%s coordinator=%s reason=%s',
+					keyStr, self.toString().substring(0, 12), decision.reason);
+			} else {
+				this.log('findCoordinator:self-selected key=%s coordinator=%s reason=%s',
+					keyStr, self.toString().substring(0, 12), decision.reason);
+			}
+			return self
+		}
+
+		this.log('findCoordinator:all-excluded key=%s self=%s', keyStr, self.toString().substring(0, 12))
+		throw new Error('No coordinator available for key (all candidates excluded)')
+	}
+
+	private getConnectedAddrsByPeer(): Record<string, string[]> {
+		const conns = this.libp2p.getConnections()
+		const byPeer: Record<string, string[]> = {}
+		for (const c of conns) {
+			const id = c.remotePeer.toString()
+			const addr = c.remoteAddr?.toString?.()
+			if (addr) (byPeer[id] ??= []).push(addr)
+		}
+		return byPeer
+	}
+
+	private parseMultiaddrs(addrs: string[]): ReturnType<typeof multiaddr>[] {
+		const out: ReturnType<typeof multiaddr>[] = []
+		for (const a of addrs) {
+			try { out.push(multiaddr(a)) } catch (err) { console.warn('invalid multiaddr from connection', a, err) }
+		}
+		return out
+	}
+
+	async findCluster(key: Uint8Array): Promise<ClusterPeers> {
+		const fret = this.getFret()
+		const coord = await hashKey(key)
+		const cohort = fret.assembleCohort(coord, this.clusterSize)
+		const keyStr = this.toCacheKey(key).substring(0, 12);
+
+		// Include self in the cohort
+		const ids = Array.from(new Set([...cohort, this.libp2p.peerId.toString()]))
+
+		const connectedByPeer = this.getConnectedAddrsByPeer()
+		const connectedPeerIds = Object.keys(connectedByPeer)
+
+		this.log('findCluster key=%s fretCohort=%d connected=%d cohortPeers=%o',
+			keyStr, cohort.length, connectedPeerIds.length, ids.map(s => s.substring(0, 12)))
+
+		const peers: ClusterPeers = {}
+
+		for (const idStr of ids) {
+			if (idStr === this.libp2p.peerId.toString()) {
+				peers[idStr] = { multiaddrs: this.libp2p.getMultiaddrs(), publicKey: this.libp2p.peerId.publicKey?.raw ?? new Uint8Array() }
+				continue
+			}
+			const strings = connectedByPeer[idStr] ?? []
+			const addrs = this.parseMultiaddrs(strings)
+			peers[idStr] = { multiaddrs: addrs, publicKey: new Uint8Array() }
+		}
+
+		this.log('findCluster:result key=%s clusterSize=%d withAddrs=%d connectedInCohort=%d',
+			keyStr, Object.keys(peers).length,
+			Object.values(peers).filter(p => p.multiaddrs.length > 0).length,
+			ids.filter(id => connectedPeerIds.includes(id) || id === this.libp2p.peerId.toString()).length)
+		return peers
+	}
+}

package/src/libp2p-node.ts

@@ -0,0 +1,335 @@
+import { createLibp2p, type Libp2p } from 'libp2p';
+import { tcp } from '@libp2p/tcp';
+import { noise } from '@chainsafe/libp2p-noise';
+import { yamux } from '@chainsafe/libp2p-yamux';
+import { identify } from '@libp2p/identify';
+import { ping } from '@libp2p/ping';
+import { gossipsub } from '@chainsafe/libp2p-gossipsub';
+import { bootstrap } from '@libp2p/bootstrap';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { clusterService } from './cluster/service.js';
+import { repoService } from './repo/service.js';
+import { StorageRepo } from './storage/storage-repo.js';
+import { BlockStorage } from './storage/block-storage.js';
+import { MemoryRawStorage } from './storage/memory-storage.js';
+import { FileRawStorage } from './storage/file-storage.js';
+import type { IRawStorage } from './storage/i-raw-storage.js';
+import { clusterMember } from './cluster/cluster-repo.js';
+import { coordinatorRepo } from './repo/coordinator-repo.js';
+import { Libp2pKeyPeerNetwork } from './libp2p-key-network.js';
+import { ClusterClient } from './cluster/client.js';
+import type { IRepo, ICluster, ITransactionValidator } from '@optimystic/db-core';
+import { multiaddr } from '@multiformats/multiaddr';
+import { networkManagerService } from './network/network-manager-service.js';
+import { fretService, Libp2pFretService } from 'p2p-fret';
+import { syncService } from './sync/service.js';
+import { RestorationCoordinator } from './storage/restoration-coordinator-v2.js';
+import { RingSelector } from './storage/ring-selector.js';
+import { StorageMonitor } from './storage/storage-monitor.js';
+import type { StorageMonitorConfig } from './storage/storage-monitor.js';
+import { ArachnodeFretAdapter } from './storage/arachnode-fret-adapter.js';
+import type { RestoreCallback } from './storage/struct.js';
+import type { FretService } from 'p2p-fret';
+import { PartitionDetector } from './cluster/partition-detector.js';
+
+export type NodeOptions = {
+	port: number;
+	bootstrapNodes: string[];
+	networkName: string;
+	fretProfile?: 'edge' | 'core';
+	id?: string; // optional peer id
+	relay?: boolean; // enable relay service
+	storageType?: 'memory' | 'file'; // storage backend type
+	storagePath?: string; // path for file storage (required if storageType is 'file')
+	clusterSize?: number; // desired cluster size per key
+	clusterPolicy?: {
+		allowDownsize?: boolean;
+		sizeTolerance?: number; // acceptable relative difference (e.g. 0.5 = +/-50%)
+		superMajorityThreshold?: number; // fraction of peers needed for super-majority (default: 0.67)
+	};
+
+	/** Arachnode storage configuration */
+	arachnode?: {
+		enableRingZulu?: boolean; // default: true
+		storage?: StorageMonitorConfig;
+	};
+
+	/** Transaction validator for cluster consensus */
+	validator?: ITransactionValidator;
+};
+
+export async function createLibp2pNode(options: NodeOptions): Promise<Libp2p> {
+	// Create storage based on type
+	const storageType = options.storageType ?? 'memory';
+	let rawStorage: IRawStorage;
+
+	if (storageType === 'file') {
+		if (!options.storagePath) {
+			throw new Error('storagePath is required when storageType is "file"');
+		}
+		rawStorage = new FileRawStorage(options.storagePath);
+	} else {
+		rawStorage = new MemoryRawStorage();
+	}
+
+	// Create placeholder restore callback (will be replaced after node starts)
+	let restoreCallback: RestoreCallback = async (_blockId, _rev?) => {
+		return undefined;
+	};
+
+	// Create shared storage layers with restoration callback
+	const storageRepo = new StorageRepo((blockId) =>
+		new BlockStorage(blockId, rawStorage, restoreCallback)
+	);
+
+	let clusterImpl: ICluster | undefined;
+	let coordinatedRepo: IRepo | undefined;
+
+	const clusterProxy: ICluster = {
+		async update(record) {
+			if (!clusterImpl) {
+				throw new Error('ClusterMember not initialized');
+			}
+			return await clusterImpl.update(record);
+		}
+	};
+
+	const repoProxy: IRepo = {
+		async get(blockGets, options) {
+			const target = coordinatedRepo ?? storageRepo;
+			return await target.get(blockGets, options);
+		},
+		async pend(request, options) {
+			const target = coordinatedRepo ?? storageRepo;
+			return await target.pend(request, options);
+		},
+		async cancel(trxRef, options) {
+			const target = coordinatedRepo ?? storageRepo;
+			return await target.cancel(trxRef, options);
+		},
+		async commit(request, options) {
+			const target = coordinatedRepo ?? storageRepo;
+			return await target.commit(request, options);
+		}
+	};
+
+	// Parse peer ID if provided
+	const peerId = options.id ? await peerIdFromString(options.id) : undefined;
+
+	const libp2pOptions: any = {
+		start: false,
+		...(peerId ? { peerId } : {}),
+		addresses: {
+			listen: [`/ip4/0.0.0.0/tcp/${options.port}`]
+		},
+		connectionManager: {
+			autoDial: true,
+			minConnections: 1,
+			maxConnections: 16,
+			inboundConnectionUpgradeTimeout: 10_000,
+			dialQueue: { concurrency: 2, attempts: 2 }
+		},
+		transports: [tcp()],
+		connectionEncrypters: [noise()],
+		streamMuxers: [yamux()],
+		services: {
+			identify: identify({
+				protocolPrefix: `/optimystic/${options.networkName}`
+			}),
+			ping: ping(),
+			pubsub: gossipsub({
+				allowPublishToZeroTopicPeers: true,
+				heartbeatInterval: 7000
+			}),
+
+			// Custom services - create wrapper factories that inject dependencies
+			cluster: (components: any) => {
+				const serviceFactory = clusterService({
+					protocolPrefix: `/optimystic/${options.networkName}`,
+					configuredClusterSize: options.clusterSize ?? 10,
+					allowClusterDownsize: options.clusterPolicy?.allowDownsize ?? true,
+					clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5
+				});
+				return serviceFactory({
+					logger: components.logger,
+					registrar: components.registrar,
+					cluster: clusterProxy
+				});
+			},
+
+			repo: (components: any) => {
+				const serviceFactory = repoService({
+					protocolPrefix: `/optimystic/${options.networkName}`
+				});
+				return serviceFactory({
+					logger: components.logger,
+					registrar: components.registrar,
+					repo: repoProxy
+				});
+			},
+
+			sync: (components: any) => {
+				const serviceFactory = syncService({
+					protocolPrefix: `/optimystic/${options.networkName}`
+				});
+				return serviceFactory({
+					logger: components.logger,
+					registrar: components.registrar,
+					repo: repoProxy
+				});
+			},
+
+			networkManager: (components: any) => {
+				const svcFactory = networkManagerService({
+					clusterSize: options.clusterSize ?? 10,
+					expectedRemotes: (options.bootstrapNodes?.length ?? 0) > 0,
+					allowClusterDownsize: options.clusterPolicy?.allowDownsize ?? true,
+					clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5
+				})
+				const svc = svcFactory(components)
+				try { (svc as any).setLibp2p?.(components.libp2p) } catch { }
+				return svc
+			},
+			fret: (components: any) => {
+				const svcFactory = fretService({
+					k: 15,
+					m: 8,
+					capacity: 2048,
+					profile: options.fretProfile ?? ((options.bootstrapNodes?.length ?? 0) > 0 ? 'core' : 'edge'),
+					networkName: options.networkName,
+					bootstraps: options.bootstrapNodes ?? []
+				});
+				const svc = svcFactory(components) as Libp2pFretService;
+				try { svc.setLibp2p(components.libp2p); } catch { }
+				return svc;
+			}
+		},
+		// Add bootstrap nodes as needed
+		peerDiscovery: [
+			...(options.bootstrapNodes?.length ? [bootstrap({ list: options.bootstrapNodes })] : [])
+		],
+	};
+
+	const node = await createLibp2p(libp2pOptions);
+
+	// Inject libp2p reference into services that need it before start
+	try { ((node as any).services?.fret as any)?.setLibp2p?.(node) } catch { }
+	try { ((node as any).services?.networkManager as any)?.setLibp2p?.(node) } catch { }
+
+	await node.start();
+
+	// Initialize cluster coordination components
+	const keyNetwork = new Libp2pKeyPeerNetwork(node);
+	const protocolPrefix = `/optimystic/${options.networkName}`;
+	const createClusterClient = (peerId: any) => ClusterClient.create(peerId, keyNetwork, protocolPrefix);
+
+	// Create partition detector and get FRET service
+	const partitionDetector = new PartitionDetector();
+	const fretSvc = (node as any).services?.fret as FretService | undefined;
+
+	clusterImpl = clusterMember({
+		storageRepo,
+		peerNetwork: keyNetwork,
+		peerId: node.peerId,
+		protocolPrefix,
+		partitionDetector,
+		fretService: fretSvc,
+		validator: options.validator
+	});
+
+	const coordinatorRepoFactory = coordinatorRepo(
+		keyNetwork,
+		createClusterClient,
+		{
+			clusterSize: options.clusterSize ?? 10,
+			superMajorityThreshold: options.clusterPolicy?.superMajorityThreshold ?? 0.67,
+			simpleMajorityThreshold: 0.51,
+			minAbsoluteClusterSize: 2,     // Allow 2-node clusters for development/small networks
+			allowClusterDownsize: options.clusterPolicy?.allowDownsize ?? true,
+			clusterSizeTolerance: options.clusterPolicy?.sizeTolerance ?? 0.5,
+			partitionDetectionWindow: 60000
+		},
+		fretSvc
+	);
+
+	coordinatedRepo = coordinatorRepoFactory({
+		storageRepo,
+		localCluster: clusterImpl,
+		localPeerId: node.peerId
+	});
+
+	// Initialize Arachnode ring membership and restoration
+	const enableArachnode = options.arachnode?.enableRingZulu ?? true;
+	if (enableArachnode) {
+		const log = (node as any).logger?.forComponent?.('db-p2p:arachnode');
+		const fret = (node as any).services?.fret as any;
+
+		if (fret) {
+			const fretAdapter = new ArachnodeFretAdapter(fret);
+
+			const storageMonitor = new StorageMonitor(rawStorage, options.arachnode?.storage ?? {});
+			const ringSelector = new RingSelector(fretAdapter, storageMonitor, {
+				minCapacity: 100 * 1024 * 1024, // 100MB minimum
+				thresholds: {
+					moveOut: 0.85,
+					moveIn: 0.40
+				}
+			});
+
+			// Determine and announce ring membership
+			const peerId = node.peerId.toString();
+			const arachnodeInfo = await ringSelector.createArachnodeInfo(peerId);
+			fretAdapter.setArachnodeInfo(arachnodeInfo);
+
+			log?.('Announced Arachnode membership: Ring %d', arachnodeInfo.ringDepth);
+
+			// Setup restoration coordinator with FRET adapter
+			const restorationCoordinatorV2 = new RestorationCoordinator(
+				fretAdapter,
+				{ connect: (pid, protocol) => node.dialProtocol(pid, [protocol]) },
+				`/optimystic/${options.networkName}`
+			);
+
+			// Update restore callback to use new coordinator
+			const newRestoreCallback: RestoreCallback = async (blockId, rev?) => {
+				return await restorationCoordinatorV2.restore(blockId, rev);
+			};
+
+			// Replace the restore callback (this is a bit hacky, but works for now)
+			// In production, we'd want to properly manage this
+			(storageRepo as any).createBlockStorage = (blockId: string) =>
+				new BlockStorage(blockId, rawStorage, newRestoreCallback);
+
+			// Monitor capacity and adjust ring periodically
+			const monitorInterval = setInterval(async () => {
+				const transition = await ringSelector.shouldTransition();
+				if (transition.shouldMove) {
+					log?.('Ring transition needed: moving %s to Ring %d',
+						transition.direction, transition.newRingDepth);
+
+					// Update Arachnode info with new ring
+					const updatedInfo = await ringSelector.createArachnodeInfo(peerId);
+					fretAdapter.setArachnodeInfo(updatedInfo);
+				}
+			}, 60_000); // Check every minute
+
+			// Cleanup on node stop
+			const originalStop = node.stop.bind(node);
+			node.stop = async () => {
+				clearInterval(monitorInterval);
+				await originalStop();
+			};
+		} else {
+			log?.('FRET service not available, Arachnode disabled');
+		}
+	}
+
+	// Skip proactive bootstrap dials; rely on discovery and minimal churn
+
+	// Expose coordinated repo and storage for external use
+	(node as any).coordinatedRepo = coordinatedRepo;
+	(node as any).storageRepo = storageRepo;
+	(node as any).keyNetwork = keyNetwork;
+
+	return node;
+}

package/src/logger.ts

@@ -0,0 +1,9 @@
+import debug from 'debug'
+
+const BASE_NAMESPACE = 'optimystic:db-p2p'
+
+export function createLogger(subNamespace: string): debug.Debugger {
+	return debug(`${BASE_NAMESPACE}:${subNamespace}`)
+}
+
+

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

@@ -0,0 +1,17 @@
+import type { Libp2p } from 'libp2p'
+import type { NetworkManagerService } from './network-manager-service.js'
+import { createLogger } from '../logger.js'
+
+const log = createLogger('network:get-manager')
+
+export function getNetworkManager(node: Libp2p): NetworkManagerService {
+  const svc = (node as any).services?.networkManager
+  if (svc == null) {
+    throw new Error('networkManager service is not registered on this libp2p node')
+  }
+  // Provide libp2p reference early to avoid MissingServiceError from components accessor
+  try { (svc as any).setLibp2p?.(node) } catch (err) { log('getNetworkManager setLibp2p failed - %o', err) }
+  return svc as NetworkManagerService
+}
+
+