@optimystic/db-p2p 0.0.1

package/src/repo/coordinator-repo.ts

@@ -0,0 +1,137 @@
+import type { PendRequest, ActionBlocks, IRepo, MessageOptions, CommitResult, GetBlockResults, PendResult, BlockGets, CommitRequest, RepoMessage, IKeyNetwork, ICluster, ClusterConsensusConfig } from "@optimystic/db-core";
+import { ClusterCoordinator } from "./cluster-coordinator.js";
+import type { ClusterClient } from "../cluster/client.js";
+import type { PeerId } from "@libp2p/interface";
+import type { FretService } from "p2p-fret";
+
+interface CoordinatorRepoComponents {
+	storageRepo: IRepo;
+	localCluster?: ICluster;
+	localPeerId?: PeerId;
+}
+
+export function coordinatorRepo(
+	keyNetwork: IKeyNetwork,
+	createClusterClient: (peerId: PeerId) => ClusterClient,
+	cfg?: Partial<ClusterConsensusConfig> & { clusterSize?: number },
+	fretService?: FretService
+): (components: CoordinatorRepoComponents) => CoordinatorRepo {
+	return (components: CoordinatorRepoComponents) => new CoordinatorRepo(keyNetwork, createClusterClient, components.storageRepo, cfg, components.localCluster, components.localPeerId, fretService);
+}
+
+/** Cluster coordination repo - uses local store, as well as distributes changes to other nodes using cluster consensus. */
+export class CoordinatorRepo implements IRepo {
+	private coordinator: ClusterCoordinator;
+	private readonly DEFAULT_TIMEOUT = 30000; // 30 seconds default timeout
+
+	constructor(
+		readonly keyNetwork: IKeyNetwork,
+		readonly createClusterClient: (peerId: PeerId) => ClusterClient,
+		private readonly storageRepo: IRepo,
+		cfg?: Partial<ClusterConsensusConfig> & { clusterSize?: number },
+		localCluster?: ICluster,
+		localPeerId?: PeerId,
+		fretService?: FretService
+	) {
+		const policy: ClusterConsensusConfig & { clusterSize: number } = {
+			clusterSize: cfg?.clusterSize ?? 10,
+			superMajorityThreshold: cfg?.superMajorityThreshold ?? 0.75,
+			simpleMajorityThreshold: cfg?.simpleMajorityThreshold ?? 0.51,
+			minAbsoluteClusterSize: cfg?.minAbsoluteClusterSize ?? 3,
+			allowClusterDownsize: cfg?.allowClusterDownsize ?? true,
+			clusterSizeTolerance: cfg?.clusterSizeTolerance ?? 0.5,
+			partitionDetectionWindow: cfg?.partitionDetectionWindow ?? 60000
+		};
+		const localClusterRef = localCluster && localPeerId ? { update: localCluster.update.bind(localCluster), peerId: localPeerId } : undefined;
+		this.coordinator = new ClusterCoordinator(keyNetwork, createClusterClient, policy, localClusterRef, fretService);
+	}
+
+	async get(blockGets: BlockGets, options?: MessageOptions): Promise<GetBlockResults> {
+		// TODO: Verify that we are a proximate node for all block IDs in the request
+
+		// For read operations, just use the local store
+		// TODO: Implement read-path cluster verification without creating full 2PC transactions
+		return await this.storageRepo.get(blockGets, options);
+	}
+
+	async pend(request: PendRequest, options?: MessageOptions): Promise<PendResult> {
+		const allBlockIds = Object.keys(request.transforms);
+		const coordinatingBlockIds = (options as any)?.coordinatingBlockIds ?? allBlockIds;
+
+		const peerCount = await this.coordinator.getClusterSize(coordinatingBlockIds[0]!)
+		if (peerCount <= 1) {
+			return await this.storageRepo.pend(request, options)
+		}
+
+		const message: RepoMessage = {
+			operations: [{ pend: request }],
+			expiration: options?.expiration ?? Date.now() + this.DEFAULT_TIMEOUT,
+			coordinatingBlockIds
+		};
+
+		try {
+			await this.coordinator.executeClusterTransaction(coordinatingBlockIds[0]!, message, options);
+			return await this.storageRepo.pend(request, options);
+		} catch (error) {
+			console.error('Failed to complete pend operation:', error)
+			throw error
+		}
+	}
+
+	async cancel(actionRef: ActionBlocks, options?: MessageOptions): Promise<void> {
+		// TODO: Verify that we are a proximate node for all block IDs in the request
+
+		// Extract all block IDs affected by this cancel operation
+		const blockIds = actionRef.blockIds;
+
+		// Create a message for this cancel operation with timeout
+		const message: RepoMessage = {
+			operations: [{ cancel: { actionRef } }],
+			expiration: options?.expiration ?? Date.now() + this.DEFAULT_TIMEOUT
+		};
+
+		try {
+			// For each block ID, execute a cluster transaction
+			const clusterPromises = blockIds.map(blockId =>
+				this.coordinator.executeClusterTransaction(blockId, message, options)
+			);
+
+			// Wait for all cluster transactions to complete
+			await Promise.all(clusterPromises);
+
+			// If all cluster transactions succeeded, apply the cancel to the local store
+			await this.storageRepo.cancel(actionRef, options);
+		} catch (error) {
+			console.error('Failed to complete cancel operation:', error);
+			throw error;
+		}
+	}
+
+	async commit(request: CommitRequest, options?: MessageOptions): Promise<CommitResult> {
+		// TODO: Verify that we are a proximate node for all block IDs in the request
+
+		// Extract all block IDs affected by this commit operation
+		const blockIds = request.blockIds;
+
+    const peerCount = await this.coordinator.getClusterSize(blockIds[0]!)
+    if (peerCount <= 1) {
+      return await this.storageRepo.commit(request, options)
+    }
+
+		// Create a single message for the entire commit operation
+		const message: RepoMessage = {
+			operations: [{ commit: request }],
+			expiration: options?.expiration ?? Date.now() + this.DEFAULT_TIMEOUT
+		};
+
+    try {
+			// Execute cluster transaction using the first block ID
+			// All blocks in this operation should map to the same cluster
+			await this.coordinator.executeClusterTransaction(blockIds[0]!, message, options);
+			return await this.storageRepo.commit(request, options);
+    } catch (error) {
+      console.error('Failed to complete commit operation:', error)
+      throw error
+    }
+	}
+}

package/src/repo/redirect.ts

@@ -0,0 +1,17 @@
+export type RedirectPayload = {
+  redirect: {
+    peers: Array<{ id: string, addrs: string[] }>
+    reason: 'not_in_cluster'
+  }
+}
+
+export function encodePeers(peers: Array<{ id: string, addrs: string[] }>): RedirectPayload {
+  return {
+    redirect: {
+      peers,
+      reason: 'not_in_cluster'
+    }
+  }
+}
+
+

package/src/repo/service.ts

@@ -0,0 +1,219 @@
+import { pipe } from 'it-pipe'
+import { decode as lpDecode, encode as lpEncode } from 'it-length-prefixed'
+import type { Startable, Logger, IncomingStreamData } from '@libp2p/interface'
+import type { IRepo, RepoMessage } from '@optimystic/db-core'
+import { computeResponsibility } from '../routing/responsibility.js'
+import { peersEqual } from '../peer-utils.js'
+import { sha256 } from 'multiformats/hashes/sha2'
+import { buildKnownPeers } from '../routing/libp2p-known-peers.js'
+import { encodePeers } from './redirect.js'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+// Define Components interface
+interface BaseComponents {
+	logger: { forComponent: (name: string) => Logger },
+	registrar: {
+		handle: (protocol: string, handler: (data: IncomingStreamData) => void, options: any) => Promise<void>
+		unhandle: (protocol: string) => Promise<void>
+	}
+}
+
+export type RepoServiceComponents = BaseComponents & {
+	repo: IRepo
+}
+
+export type RepoServiceInit = {
+	protocol?: string,
+	protocolPrefix?: string,
+	maxInboundStreams?: number,
+	maxOutboundStreams?: number,
+	logPrefix?: string,
+	kBucketSize?: number,
+}
+
+export function repoService(init: RepoServiceInit = {}): (components: RepoServiceComponents) => RepoService {
+	return (components: RepoServiceComponents) => new RepoService(components, init);
+}
+
+/**
+ * A libp2p service that handles repo protocol messages
+ */
+export class RepoService implements Startable {
+	private readonly protocol: string
+	private readonly maxInboundStreams: number
+	private readonly maxOutboundStreams: number
+	private readonly log: Logger
+	private readonly repo: IRepo
+	private readonly components: RepoServiceComponents
+	private running: boolean
+	private readonly k: number
+
+	constructor(components: RepoServiceComponents, init: RepoServiceInit = {}) {
+		this.components = components
+		const computed = init.protocol ?? (init.protocolPrefix ?? '/db-p2p') + '/repo/1.0.0'
+		this.protocol = computed
+		this.maxInboundStreams = init.maxInboundStreams ?? 32
+		this.maxOutboundStreams = init.maxOutboundStreams ?? 64
+		this.log = components.logger.forComponent(init.logPrefix ?? 'db-p2p:repo-service')
+		this.repo = components.repo
+		this.running = false
+		this.k = init.kBucketSize ?? 10
+	}
+
+	readonly [Symbol.toStringTag] = '@libp2p/repo-service'
+
+	/**
+	 * Start the service
+	 */
+	async start(): Promise<void> {
+		if (this.running) {
+			return
+		}
+
+		await this.components.registrar.handle(this.protocol, this.handleIncomingStream.bind(this), {
+			maxInboundStreams: this.maxInboundStreams,
+			maxOutboundStreams: this.maxOutboundStreams
+		})
+
+		this.running = true
+	}
+
+	/**
+	 * Stop the service
+	 */
+	async stop(): Promise<void> {
+		if (!this.running) {
+			return
+		}
+
+		await this.components.registrar.unhandle(this.protocol)
+		this.running = false
+	}
+
+	/**
+	 * Handle incoming streams on the repo protocol
+	 */
+	private handleIncomingStream(data: IncomingStreamData): void {
+		const { stream, connection } = data
+		const peerId = connection.remotePeer
+
+		const processStream = async function* (this: RepoService, source: AsyncIterable<Uint8ArrayList>) {
+			for await (const msg of source) {
+				// Decode the message
+				const decoded = new TextDecoder().decode(msg.subarray())
+				const message = JSON.parse(decoded) as RepoMessage
+
+				// Process each operation
+				const operation = message.operations[0]
+				let response: any
+
+				if ('get' in operation) {
+					{
+						// Use sha256 digest of block id string for consistent key space
+						const mh = await sha256.digest(new TextEncoder().encode(operation.get.blockIds[0]!))
+						const key = mh.digest
+						const nm: any = (this.components as any).libp2p?.services?.networkManager
+						if (nm?.getCluster) {
+							const cluster: any[] = await nm.getCluster(key);
+							(message as any).cluster = (cluster as any[]).map(p => p.toString?.() ?? String(p))
+							const selfId = (this.components as any).libp2p.peerId
+							const isMember = cluster.some((p: any) => peersEqual(p, selfId))
+							const smallMesh = cluster.length < this.k
+							if (!smallMesh && !isMember) {
+								const peers = cluster.filter((p: any) => !peersEqual(p, selfId))
+								console.debug('repo-service:redirect', {
+									peerId: selfId.toString(),
+									reason: 'not-cluster-member',
+									operation: 'get',
+									blockId: operation.get.blockIds[0],
+									cluster: cluster.map((p: any) => p.toString?.() ?? String(p))
+								})
+								response = encodePeers(peers.map((pid: any) => ({ id: pid.toString(), addrs: [] })))
+							} else {
+								response = await this.repo.get(operation.get, { expiration: message.expiration })
+							}
+						} else {
+							response = await this.repo.get(operation.get, { expiration: message.expiration })
+						}
+					}
+				} else if ('pend' in operation) {
+					{
+						const id = Object.keys(operation.pend.transforms)[0]!
+						const mh = await sha256.digest(new TextEncoder().encode(id))
+						const key = mh.digest
+						const nm: any = (this.components as any).libp2p?.services?.networkManager
+						if (nm?.getCluster) {
+							const cluster: any[] = await nm.getCluster(key)
+								; (message as any).cluster = (cluster as any[]).map(p => p.toString?.() ?? String(p))
+							const selfId = (this.components as any).libp2p.peerId
+							const isMember = cluster.some((p: any) => peersEqual(p, selfId))
+							const smallMesh = cluster.length < this.k
+							if (!smallMesh && !isMember) {
+								const peers = cluster.filter((p: any) => !peersEqual(p, selfId))
+								console.debug('repo-service:redirect', {
+									peerId: selfId.toString(),
+									reason: 'not-cluster-member',
+									operation: 'pend',
+									blockId: id,
+									cluster: cluster.map((p: any) => p.toString?.() ?? String(p))
+								})
+								response = encodePeers(peers.map((pid: any) => ({ id: pid.toString(), addrs: [] })))
+							} else {
+								response = await this.repo.pend(operation.pend, { expiration: message.expiration })
+							}
+						} else {
+							response = await this.repo.pend(operation.pend, { expiration: message.expiration })
+						}
+					}
+				} else if ('cancel' in operation) {
+					response = await this.repo.cancel(operation.cancel.actionRef, {
+						expiration: message.expiration
+					})
+				} else if ('commit' in operation) {
+					{
+						const mh = await sha256.digest(new TextEncoder().encode(operation.commit.tailId))
+						const key = mh.digest
+						const nm: any = (this.components as any).libp2p?.services?.networkManager
+						if (nm?.getCluster) {
+							const cluster: any[] = await nm.getCluster(key)
+								; (message as any).cluster = (cluster as any[]).map(p => p.toString?.() ?? String(p))
+							const selfId = (this.components as any).libp2p.peerId
+							const isMember = cluster.some((p: any) => peersEqual(p, selfId))
+							const smallMesh = cluster.length < this.k
+							if (!smallMesh && !isMember) {
+								const peers = cluster.filter((p: any) => !peersEqual(p, selfId))
+								console.debug('repo-service:redirect', {
+									peerId: selfId.toString(),
+									reason: 'not-cluster-member',
+									operation: 'commit',
+									tailId: operation.commit.tailId,
+									cluster: cluster.map((p: any) => p.toString?.() ?? String(p))
+								})
+								response = encodePeers(peers.map((pid: any) => ({ id: pid.toString(), addrs: [] })))
+							} else {
+								response = await this.repo.commit(operation.commit, { expiration: message.expiration })
+							}
+						} else {
+							response = await this.repo.commit(operation.commit, { expiration: message.expiration })
+						}
+					}
+				}
+
+				// Encode and yield the response
+				yield new TextEncoder().encode(JSON.stringify(response))
+			}
+		}
+
+		Promise.resolve().then(async () => {
+			await pipe(
+				stream,
+				(source) => lpDecode(source),
+				processStream.bind(this),
+				(source) => lpEncode(source),
+				stream
+			)
+		}).catch(err => {
+			this.log.error('error handling repo protocol message from %p - %e', peerId, err)
+		})
+	}
+}

package/src/repo/types.ts

@@ -0,0 +1,7 @@
+export interface ClusterLogPeerOutcome {
+	peerId: string;
+	success: boolean;
+	/** Optional error message that explains why the peer failed. */
+	error?: string;
+}
+

package/src/routing/libp2p-known-peers.ts

@@ -0,0 +1,26 @@
+import type { Libp2p } from 'libp2p'
+import type { PeerId } from '@libp2p/interface'
+import type { KnownPeer } from './responsibility.js'
+
+export function buildKnownPeers(libp2p: Libp2p): KnownPeer[] {
+  const self: KnownPeer = {
+    id: libp2p.peerId as unknown as PeerId,
+    addrs: libp2p.getMultiaddrs().map(ma => ma.toString())
+  }
+
+  const connections = libp2p.getConnections()
+  const byPeer: Record<string, { id: PeerId, addrs: Set<string> }> = {}
+
+  for (const c of connections) {
+    const pid = c.remotePeer
+    const key = pid.toString()
+    const entry = byPeer[key] ?? (byPeer[key] = { id: pid as unknown as PeerId, addrs: new Set() })
+    const addrStr = c.remoteAddr?.toString?.()
+    if (addrStr) entry.addrs.add(addrStr)
+  }
+
+  const others: KnownPeer[] = Object.values(byPeer).map(e => ({ id: e.id, addrs: Array.from(e.addrs) }))
+  return [self, ...others]
+}
+
+

package/src/routing/responsibility.ts

@@ -0,0 +1,63 @@
+import type { PeerId } from '@libp2p/interface'
+
+export type KnownPeer = { id: PeerId, addrs: string[] }
+
+export type ResponsibilityResult = {
+  inCluster: boolean
+  nearest: KnownPeer[]
+}
+
+export function xorDistanceBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const len = Math.max(a.length, b.length)
+  const out = new Uint8Array(len)
+  for (let i = 0; i < len; i++) {
+    const ai = a[a.length - 1 - i] ?? 0
+    const bi = b[b.length - 1 - i] ?? 0
+    out[len - 1 - i] = ai ^ bi
+  }
+  return out
+}
+
+export function lessThanLex(a: Uint8Array, b: Uint8Array): boolean {
+  const len = Math.max(a.length, b.length)
+  for (let i = 0; i < len; i++) {
+    const av = a[i] ?? 0
+    const bv = b[i] ?? 0
+    if (av < bv) return true
+    if (av > bv) return false
+  }
+  return false
+}
+
+export function sortPeersByDistance(peers: KnownPeer[], key: Uint8Array): KnownPeer[] {
+  return peers
+    .map(p => ({ p, d: xorDistanceBytes(p.id.toMultihash().bytes, key) }))
+    .sort((a, b) => (lessThanLex(a.d, b.d) ? -1 : 1))
+    .map(x => x.p)
+}
+
+export function computeResponsibility(
+  key: Uint8Array,
+  self: KnownPeer,
+  others: KnownPeer[],
+  k: number
+): ResponsibilityResult {
+  const all = [self, ...others]
+  const sorted = sortPeersByDistance(all, key)
+
+  // For small meshes, use a different strategy
+  if (all.length <= 3) {
+    // With 3 or fewer nodes, the first node in XOR order handles it
+    // This ensures only ONE node considers itself responsible
+    const inCluster = sorted[0]!.id.equals(self.id)
+    return { inCluster, nearest: sorted }
+  }
+
+  // For larger meshes, use traditional k-nearest
+  const effectiveK = Math.min(k, Math.max(1, Math.floor(all.length / 2)))
+  const topK = sorted.slice(0, effectiveK)
+  const inCluster = topK.some(p => p.id.equals(self.id))
+  return { inCluster, nearest: topK }
+}
+
+

package/src/routing/simple-cluster-coordinator.ts

@@ -0,0 +1,70 @@
+import type { PeerId } from '@libp2p/interface'
+import { sha256 } from 'multiformats/hashes/sha2'
+
+export interface SimpleClusterCoordinator {
+  selectCoordinator(key: Uint8Array, peers: PeerId[]): Promise<PeerId>
+  selectReplicas(key: Uint8Array, peers: PeerId[], replicationFactor: number): Promise<PeerId[]>
+}
+
+/**
+ * Simple consistent hashing for small clusters
+ * Uses modulo arithmetic instead of XOR distance
+ */
+export class ModuloCoordinator implements SimpleClusterCoordinator {
+  async hashPeer(peerId: PeerId): Promise<bigint> {
+    const mh = await sha256.digest(peerId.toMultihash().bytes)
+    // Take first 8 bytes as bigint
+    const view = new DataView(mh.digest.buffer, mh.digest.byteOffset, 8)
+    return view.getBigUint64(0, false)
+  }
+
+  async hashKey(key: Uint8Array): Promise<bigint> {
+    const mh = await sha256.digest(key)
+    const view = new DataView(mh.digest.buffer, mh.digest.byteOffset, 8)
+    return view.getBigUint64(0, false)
+  }
+
+  async selectCoordinator(key: Uint8Array, peers: PeerId[]): Promise<PeerId> {
+    if (peers.length === 0) throw new Error('No peers available')
+    if (peers.length === 1) return peers[0]!
+
+    // Simple modulo selection - deterministic but not distance-based
+    const keyHash = await this.hashKey(key)
+    const index = Number(keyHash % BigInt(peers.length))
+    return peers[index]!
+  }
+
+  async selectReplicas(key: Uint8Array, peers: PeerId[], replicationFactor: number): Promise<PeerId[]> {
+    if (peers.length <= replicationFactor) return [...peers]
+
+    const coordinator = await this.selectCoordinator(key, peers)
+    const replicas = [coordinator]
+    const remaining = peers.filter(p => !p.equals(coordinator))
+
+    // Select additional replicas deterministically
+    for (let i = 1; i < replicationFactor && remaining.length > 0; i++) {
+      const subKey = new Uint8Array([...key, i])
+      const replica = await this.selectCoordinator(subKey, remaining)
+      replicas.push(replica)
+      remaining.splice(remaining.findIndex(p => p.equals(replica)), 1)
+    }
+
+    return replicas
+  }
+}
+
+/**
+ * For very small clusters, just replicate everywhere
+ */
+export class FullReplicationCoordinator implements SimpleClusterCoordinator {
+  async selectCoordinator(key: Uint8Array, peers: PeerId[]): Promise<PeerId> {
+    // Always select first peer as primary
+    if (peers.length === 0) throw new Error('No peers available')
+    return peers[0]!
+  }
+
+  async selectReplicas(key: Uint8Array, peers: PeerId[], replicationFactor: number): Promise<PeerId[]> {
+    // Replicate to all peers in small clusters
+    return [...peers]
+  }
+}

package/src/storage/arachnode-fret-adapter.ts

@@ -0,0 +1,128 @@
+import type { FretService } from 'p2p-fret';
+
+/**
+ * Arachnode ring membership information.
+ * Stored in FRET's generic metadata field.
+ */
+export interface ArachnodeInfo {
+	/** Ring depth: 0 = full keyspace, N = 2^N partitions */
+	ringDepth: number;
+
+	/** Partition this node covers (undefined if ringDepth = 0) */
+	partition?: {
+		prefixBits: number;
+		prefixValue: number;
+	};
+
+	/** Storage capacity in bytes */
+	capacity: {
+		total: number;
+		used: number;
+		available: number;
+	};
+
+	/** Ring membership status */
+	status: 'joining' | 'active' | 'moving' | 'leaving';
+}
+
+/**
+ * Adapter that provides Arachnode-specific methods on top of FRET's generic metadata.
+ *
+ * FRET remains a pure DHT, while this adapter layers Arachnode semantics.
+ */
+export class ArachnodeFretAdapter {
+	private static readonly ARACHNODE_KEY = 'arachnode';
+
+	constructor(private readonly fret: FretService) {}
+
+	/**
+	 * Set this node's Arachnode ring membership.
+	 */
+	setArachnodeInfo(info: ArachnodeInfo): void {
+		this.fret.setMetadata({
+			[ArachnodeFretAdapter.ARACHNODE_KEY]: info
+		});
+	}
+
+	/**
+	 * Get Arachnode info for a specific peer.
+	 */
+	getArachnodeInfo(peerId: string): ArachnodeInfo | undefined {
+		const metadata = this.fret.getMetadata(peerId);
+		return metadata?.[ArachnodeFretAdapter.ARACHNODE_KEY] as ArachnodeInfo | undefined;
+	}
+
+	/**
+	 * Get my own Arachnode info.
+	 */
+	getMyArachnodeInfo(): ArachnodeInfo | undefined {
+		const myPeerId = (this.fret as any).node?.peerId?.toString();
+		if (!myPeerId) return undefined;
+		return this.getArachnodeInfo(myPeerId);
+	}
+
+	/**
+	 * Find all peers at a specific ring depth.
+	 */
+	findPeersAtRing(ringDepth: number): string[] {
+		const peers = this.fret.listPeers();
+		return peers
+			.filter(peer => {
+				const arachnode = peer.metadata?.[ArachnodeFretAdapter.ARACHNODE_KEY] as ArachnodeInfo | undefined;
+				return arachnode?.ringDepth === ringDepth;
+			})
+			.map(peer => peer.id);
+	}
+
+	/**
+	 * Find all known storage rings (unique ring depths).
+	 */
+	getKnownRings(): number[] {
+		const peers = this.fret.listPeers();
+		const rings = new Set<number>();
+
+		for (const peer of peers) {
+			const arachnode = peer.metadata?.[ArachnodeFretAdapter.ARACHNODE_KEY] as ArachnodeInfo | undefined;
+			if (arachnode?.ringDepth !== undefined) {
+				rings.add(arachnode.ringDepth);
+			}
+		}
+
+		return Array.from(rings).sort((a, b) => a - b);
+	}
+
+	/**
+	 * Get statistics about discovered rings.
+	 */
+	getRingStats(): Array<{ ringDepth: number; peerCount: number; avgCapacity: number }> {
+		const peers = this.fret.listPeers();
+		const ringMap = new Map<number, { count: number; totalCapacity: number }>();
+
+		for (const peer of peers) {
+			const arachnode = peer.metadata?.[ArachnodeFretAdapter.ARACHNODE_KEY] as ArachnodeInfo | undefined;
+			if (arachnode) {
+				const existing = ringMap.get(arachnode.ringDepth) ?? { count: 0, totalCapacity: 0 };
+				ringMap.set(arachnode.ringDepth, {
+					count: existing.count + 1,
+					totalCapacity: existing.totalCapacity + arachnode.capacity.available
+				});
+			}
+		}
+
+		return Array.from(ringMap.entries())
+			.map(([ringDepth, stats]) => ({
+				ringDepth,
+				peerCount: stats.count,
+				avgCapacity: stats.totalCapacity / stats.count
+			}))
+			.sort((a, b) => a.ringDepth - b.ringDepth);
+	}
+
+	/**
+	 * Access the underlying FRET service.
+	 */
+	getFret(): FretService {
+		return this.fret;
+	}
+}
+