@optimystic/db-p2p 0.2.3 → 0.3.0

package/src/repo/service.ts

@@ -1,11 +1,14 @@
 import { pipe } from 'it-pipe'
 import { decode as lpDecode, encode as lpEncode } from 'it-length-prefixed'
-import type { Startable, Logger, Stream, Connection, StreamHandler } from '@libp2p/interface'
+import type { Startable, Logger, Stream, Connection, StreamHandler, PeerId } from '@libp2p/interface'
 import type { IRepo, RepoMessage } from '@optimystic/db-core'
 import { peersEqual } from '../peer-utils.js'
 import { sha256 } from 'multiformats/hashes/sha2'
-import { encodePeers } from './redirect.js'
+import { encodePeers, type RedirectPayload } from './redirect.js'
 import type { Uint8ArrayList } from 'uint8arraylist'
+import { createLogger } from '../logger.js'
+
+const debugLog = createLogger('repo-service')
 
 // Define Components interface
 interface BaseComponents {
@@ -16,8 +19,15 @@ interface BaseComponents {
 	}
 }
 
+export interface NetworkManagerLike {
+	getCluster(key: Uint8Array): Promise<PeerId[]>
+}
+
 export type RepoServiceComponents = BaseComponents & {
 	repo: IRepo
+	networkManager?: NetworkManagerLike
+	peerId?: PeerId
+	getConnectionAddrs?: (peerId: PeerId) => string[]
 }
 
 export type RepoServiceInit = {
@@ -100,6 +110,61 @@ export class RepoService implements Startable {
 		this.running = false
 	}
 
+	private getNetworkManager(): NetworkManagerLike | undefined {
+		if (this.components.networkManager) return this.components.networkManager
+		return (this.components as any).libp2p?.services?.networkManager as NetworkManagerLike | undefined
+	}
+
+	private getSelfId(): PeerId | undefined {
+		if (this.components.peerId) return this.components.peerId
+		return (this.components as any).libp2p?.peerId as PeerId | undefined
+	}
+
+	private getPeerAddrs(peerId: PeerId): string[] {
+		if (this.components.getConnectionAddrs) return this.components.getConnectionAddrs(peerId)
+		const libp2p = (this.components as any).libp2p
+		if (!libp2p?.getConnections) return []
+		const conns: any[] = libp2p.getConnections(peerId) ?? []
+		const addrs: string[] = []
+		for (const c of conns) {
+			const addr = c.remoteAddr?.toString?.()
+			if (addr) addrs.push(addr)
+		}
+		return addrs
+	}
+
+	/**
+	 * Check if this node should redirect the request for a given key.
+	 * Returns a RedirectPayload if not responsible, null if should handle locally.
+	 * Also attaches cluster info to the message for downstream use.
+	 */
+	async checkRedirect(blockKey: string, opName: string, message: RepoMessage): Promise<RedirectPayload | null> {
+		const nm = this.getNetworkManager()
+		if (!nm) return null
+
+		const mh = await sha256.digest(new TextEncoder().encode(blockKey))
+		const key = mh.digest
+		const cluster = await nm.getCluster(key)
+		;(message as any).cluster = cluster.map((p: PeerId) => p.toString?.() ?? String(p))
+
+		const selfId = this.getSelfId()
+		if (!selfId) return null
+
+		const isMember = cluster.some((p: PeerId) => peersEqual(p, selfId))
+		const smallMesh = cluster.length < this.responsibilityK
+
+		if (!smallMesh && !isMember) {
+			const peers = cluster.filter((p: PeerId) => !peersEqual(p, selfId))
+			debugLog('redirect op=%s blockKey=%s cluster=%d', opName, blockKey, cluster.length)
+			return encodePeers(peers.map((pid: PeerId) => ({
+				id: pid.toString(),
+				addrs: this.getPeerAddrs(pid)
+			})))
+		}
+
+		return null
+	}
+
 	/**
 	 * Handle incoming streams on the repo protocol
 	 */
@@ -117,97 +182,40 @@ export class RepoService implements Startable {
 				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))
-							// Use responsibilityK to determine if we're in the responsible set
-							const smallMesh = cluster.length < this.responsibilityK
-							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, skipClusterFetch: true } as any)
-							}
-						} else {
-							response = await this.repo.get(operation.get, { expiration: message.expiration, skipClusterFetch: true } as any)
-						}
+					const blockKey = operation.get.blockIds[0]!
+					const redirect = await this.checkRedirect(blockKey, 'get', message)
+					if (redirect) {
+						response = redirect
+					} else {
+						response = await this.repo.get(operation.get, { expiration: message.expiration, skipClusterFetch: true } as any)
 					}
 				} 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))
-							// Use responsibilityK to determine if we're in the responsible set
-							const smallMesh = cluster.length < this.responsibilityK
-							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 })
-						}
+					const blockKey = Object.keys(operation.pend.transforms)[0]!
+					const redirect = await this.checkRedirect(blockKey, 'pend', message)
+					if (redirect) {
+						response = redirect
+					} 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))
-							// Use responsibilityK to determine if we're in the responsible set
-							const smallMesh = cluster.length < this.responsibilityK
-							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 })
-							}
+					const blockKey = operation.cancel.actionRef.blockIds[0]
+					if (blockKey) {
+						const redirect = await this.checkRedirect(blockKey, 'cancel', message)
+						if (redirect) {
+							response = redirect
 						} else {
-							response = await this.repo.commit(operation.commit, { expiration: message.expiration })
+							response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
 						}
+					} else {
+						response = await this.repo.cancel(operation.cancel.actionRef, { expiration: message.expiration })
+					}
+				} else if ('commit' in operation) {
+					const blockKey = operation.commit.tailId
+					const redirect = await this.checkRedirect(blockKey, 'commit', message)
+					if (redirect) {
+						response = redirect
+					} else {
+						response = await this.repo.commit(operation.commit, { expiration: message.expiration })
 					}
 				}
 

package/src/reputation/index.ts

@@ -0,0 +1,12 @@
+export { PeerReputationService } from './peer-reputation.js';
+export {
+	PenaltyReason,
+	DEFAULT_PENALTY_WEIGHTS,
+	DEFAULT_THRESHOLDS,
+	type IPeerReputation,
+	type PeerReputationSummary,
+	type ReputationConfig,
+	type ReputationThresholds,
+	type PenaltyRecord,
+	type PeerRecord,
+} from './types.js';

package/src/reputation/peer-reputation.ts

@@ -0,0 +1,147 @@
+import {
+	type IPeerReputation,
+	type PeerRecord,
+	type PenaltyRecord,
+	type PeerReputationSummary,
+	type ReputationConfig,
+	type ReputationThresholds,
+	PenaltyReason,
+	DEFAULT_PENALTY_WEIGHTS,
+	DEFAULT_THRESHOLDS,
+} from './types.js';
+import { createLogger } from '../logger.js';
+
+const log = createLogger('peer-reputation');
+
+export class PeerReputationService implements IPeerReputation {
+	private readonly peers = new Map<string, PeerRecord>();
+	private readonly halfLifeMs: number;
+	private readonly thresholds: ReputationThresholds;
+	private readonly weights: Record<PenaltyReason, number>;
+	private readonly maxPenaltiesPerPeer: number;
+
+	constructor(config?: ReputationConfig) {
+		this.halfLifeMs = config?.halfLifeMs ?? 30 * 60_000;
+		this.thresholds = {
+			...DEFAULT_THRESHOLDS,
+			...config?.thresholds,
+		};
+		this.weights = {
+			...DEFAULT_PENALTY_WEIGHTS,
+			...config?.weights,
+		};
+		this.maxPenaltiesPerPeer = config?.maxPenaltiesPerPeer ?? 100;
+	}
+
+	reportPeer(peerId: string, reason: PenaltyReason, context?: string): void {
+		const record = this.getOrCreateRecord(peerId);
+		const weight = this.weights[reason];
+		const penalty: PenaltyRecord = {
+			reason,
+			weight,
+			timestamp: Date.now(),
+			context,
+		};
+		record.penalties.push(penalty);
+		record.lastPenalty = penalty.timestamp;
+		this.pruneRecord(record);
+
+		const score = this.computeScore(record);
+		log('report peerId=%s reason=%s weight=%d score=%d context=%s',
+			peerId.substring(0, 12), reason, weight, Math.round(score), context ?? '');
+	}
+
+	recordSuccess(peerId: string): void {
+		const record = this.getOrCreateRecord(peerId);
+		record.successCount++;
+		record.lastSuccess = Date.now();
+	}
+
+	getScore(peerId: string): number {
+		const record = this.peers.get(peerId);
+		if (!record) return 0;
+		return this.computeScore(record);
+	}
+
+	isBanned(peerId: string): boolean {
+		return this.getScore(peerId) >= this.thresholds.ban;
+	}
+
+	isDeprioritized(peerId: string): boolean {
+		return this.getScore(peerId) >= this.thresholds.deprioritize;
+	}
+
+	getReputation(peerId: string): PeerReputationSummary {
+		const score = this.getScore(peerId);
+		const record = this.peers.get(peerId);
+		return {
+			peerId,
+			effectiveScore: score,
+			isBanned: score >= this.thresholds.ban,
+			isDeprioritized: score >= this.thresholds.deprioritize,
+			penaltyCount: record?.penalties.length ?? 0,
+			successCount: record?.successCount ?? 0,
+			lastPenalty: record?.lastPenalty ?? 0,
+			lastSuccess: record?.lastSuccess ?? 0,
+		};
+	}
+
+	getAllReputations(): Map<string, PeerReputationSummary> {
+		const result = new Map<string, PeerReputationSummary>();
+		for (const peerId of this.peers.keys()) {
+			result.set(peerId, this.getReputation(peerId));
+		}
+		return result;
+	}
+
+	resetPeer(peerId: string): void {
+		this.peers.delete(peerId);
+		log('reset peerId=%s', peerId.substring(0, 12));
+	}
+
+	private getOrCreateRecord(peerId: string): PeerRecord {
+		let record = this.peers.get(peerId);
+		if (!record) {
+			record = {
+				penalties: [],
+				successCount: 0,
+				lastSuccess: 0,
+				lastPenalty: 0,
+			};
+			this.peers.set(peerId, record);
+		}
+		return record;
+	}
+
+	private computeScore(record: PeerRecord): number {
+		const now = Date.now();
+		let score = 0;
+		for (const penalty of record.penalties) {
+			score += penalty.weight * this.decayFactor(now, penalty.timestamp);
+		}
+		return score;
+	}
+
+	private decayFactor(now: number, timestamp: number): number {
+		const elapsed = now - timestamp;
+		if (elapsed <= 0) return 1;
+		return Math.pow(0.5, elapsed / this.halfLifeMs);
+	}
+
+	/** Remove penalties that have decayed below significance (< 1% of original weight) */
+	private pruneRecord(record: PeerRecord): void {
+		const now = Date.now();
+		const cutoff = this.halfLifeMs * 7; // 2^-7 ≈ 0.8% — below significance
+		record.penalties = record.penalties.filter(p => (now - p.timestamp) < cutoff);
+
+		// Hard cap to prevent unbounded growth
+		if (record.penalties.length > this.maxPenaltiesPerPeer) {
+			record.penalties = record.penalties.slice(-this.maxPenaltiesPerPeer);
+		}
+
+		// Remove peer records with no significant penalties
+		if (record.penalties.length === 0 && record.successCount === 0) {
+			// Don't remove — the caller may still be using this record
+		}
+	}
+}

package/src/reputation/types.ts

@@ -0,0 +1,117 @@
+/** Categories of peer misbehavior with associated severity */
+export enum PenaltyReason {
+	/** Peer sent a signature that failed cryptographic verification */
+	InvalidSignature = 'invalid-signature',
+	/** Peer promised conflicting transactions (equivocation) */
+	Equivocation = 'equivocation',
+	/** Peer's validation logic rejected a valid transaction (repeated false rejections) */
+	FalseRejection = 'false-rejection',
+	/** Peer failed to respond within timeout during consensus */
+	ConsensusTimeout = 'consensus-timeout',
+	/** Peer sent a message with mismatched hash */
+	InvalidMessageHash = 'invalid-message-hash',
+	/** Peer sent an expired transaction */
+	ExpiredTransaction = 'expired-transaction',
+	/** Generic protocol violation */
+	ProtocolViolation = 'protocol-violation',
+	/** Connection-level failures (lighter weight) */
+	ConnectionFailure = 'connection-failure',
+	/** Majority peer approved a transaction that was later found invalid via dispute */
+	FalseApproval = 'false-approval',
+	/** Challenger lost a dispute (their rejection was wrong) */
+	DisputeLost = 'dispute-lost',
+}
+
+/** Default penalty weights by reason */
+export const DEFAULT_PENALTY_WEIGHTS: Record<PenaltyReason, number> = {
+	[PenaltyReason.InvalidSignature]: 50,
+	[PenaltyReason.Equivocation]: 100,
+	[PenaltyReason.FalseRejection]: 10,
+	[PenaltyReason.ConsensusTimeout]: 5,
+	[PenaltyReason.InvalidMessageHash]: 50,
+	[PenaltyReason.ExpiredTransaction]: 3,
+	[PenaltyReason.ProtocolViolation]: 30,
+	[PenaltyReason.ConnectionFailure]: 2,
+	[PenaltyReason.FalseApproval]: 40,
+	[PenaltyReason.DisputeLost]: 30,
+};
+
+/** Thresholds controlling graduated reputation responses */
+export interface ReputationThresholds {
+	/** Score above which peer is deprioritized in coordinator selection. Default: 20 */
+	deprioritize: number;
+	/** Score above which peer is excluded from cluster operations. Default: 80 */
+	ban: number;
+}
+
+export const DEFAULT_THRESHOLDS: ReputationThresholds = {
+	deprioritize: 20,
+	ban: 80,
+};
+
+/** Configuration for the reputation service */
+export interface ReputationConfig {
+	/** Half-life for exponential decay of penalties (ms). Default: 30 minutes */
+	halfLifeMs?: number;
+	/** Thresholds for deprioritize/ban. Uses DEFAULT_THRESHOLDS if not provided */
+	thresholds?: Partial<ReputationThresholds>;
+	/** Custom penalty weights. Merged with DEFAULT_PENALTY_WEIGHTS */
+	weights?: Partial<Record<PenaltyReason, number>>;
+	/** Maximum penalty records per peer before pruning. Default: 100 */
+	maxPenaltiesPerPeer?: number;
+}
+
+/** A single recorded penalty event */
+export interface PenaltyRecord {
+	reason: PenaltyReason;
+	weight: number;
+	timestamp: number;
+	context?: string;
+}
+
+/** Internal record for a tracked peer */
+export interface PeerRecord {
+	penalties: PenaltyRecord[];
+	successCount: number;
+	lastSuccess: number;
+	lastPenalty: number;
+}
+
+/** Summary of a peer's reputation for diagnostics */
+export interface PeerReputationSummary {
+	peerId: string;
+	effectiveScore: number;
+	isBanned: boolean;
+	isDeprioritized: boolean;
+	penaltyCount: number;
+	successCount: number;
+	lastPenalty: number;
+	lastSuccess: number;
+}
+
+/** Interface for reputation scoring consumed by other components */
+export interface IPeerReputation {
+	/** Record a misbehavior incident */
+	reportPeer(peerId: string, reason: PenaltyReason, context?: string): void;
+
+	/** Record successful interaction */
+	recordSuccess(peerId: string): void;
+
+	/** Get effective score for a peer (0 = clean) */
+	getScore(peerId: string): number;
+
+	/** Check if peer should be excluded from operations */
+	isBanned(peerId: string): boolean;
+
+	/** Check if peer should be deprioritized */
+	isDeprioritized(peerId: string): boolean;
+
+	/** Get summary for diagnostics */
+	getReputation(peerId: string): PeerReputationSummary;
+
+	/** Get all tracked peers and their statuses */
+	getAllReputations(): Map<string, PeerReputationSummary>;
+
+	/** Reset a peer's reputation (admin/testing) */
+	resetPeer(peerId: string): void;
+}

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

@@ -118,6 +118,17 @@ export class ArachnodeFretAdapter {
 			.sort((a, b) => a.ringDepth - b.ringDepth);
 	}
 
+	/**
+	 * Update the status field of this node's ArachnodeInfo.
+	 * No-op if no ArachnodeInfo has been set yet.
+	 */
+	setStatus(status: ArachnodeInfo['status']): void {
+		const current = this.getMyArachnodeInfo();
+		if (current) {
+			this.setArachnodeInfo({ ...current, status });
+		}
+	}
+
 	/**
 	 * Access the underlying FRET service.
 	 */

package/src/storage/block-storage.ts

@@ -4,6 +4,9 @@ import type { BlockArchive, BlockMetadata, RestoreCallback, RevisionRange } from
 import type { IRawStorage } from "./i-raw-storage.js";
 import { mergeRanges } from "./helpers.js";
 import type { IBlockStorage } from "./i-block-storage.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('block-storage');
 
 export class BlockStorage implements IBlockStorage {
 	constructor(
@@ -45,6 +48,7 @@ export class BlockStorage implements IBlockStorage {
 	}
 
 	async savePendingTransaction(actionId: ActionId, transform: Transform): Promise<void> {
+		log('pend blockId=%s actionId=%s', this.blockId, actionId);
 		let meta = await this.storage.getMetadata(this.blockId);
 		if (!meta) {
 			meta = { latest: undefined, ranges: [[0]] };
@@ -54,6 +58,7 @@ export class BlockStorage implements IBlockStorage {
 	}
 
 	async deletePendingTransaction(actionId: ActionId): Promise<void> {
+		log('cancel blockId=%s actionId=%s', this.blockId, actionId);
 		await this.storage.deletePendingTransaction(this.blockId, actionId);
 	}
 
@@ -70,6 +75,7 @@ export class BlockStorage implements IBlockStorage {
 	}
 
 	async promotePendingTransaction(actionId: ActionId): Promise<void> {
+		log('commit blockId=%s actionId=%s', this.blockId, actionId);
 		await this.storage.promotePendingTransaction(this.blockId, actionId);
 	}
 

package/src/storage/storage-repo.ts

@@ -11,6 +11,9 @@ import {
 } from "@optimystic/db-core";
 import { asyncIteratorToArray } from "../it-utility.js";
 import type { IBlockStorage } from "./i-block-storage.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('storage-repo');
 
 export type StorageRepoOptions = {
 	/** Optional hook to validate transactions in PendRequests */
@@ -29,6 +32,7 @@ export class StorageRepo implements IRepo {
 
 	async get({ blockIds, context }: BlockGets, options?: MessageOptions): Promise<GetBlockResults> {
 		const distinctBlockIds = Array.from(new Set(blockIds));
+		log('get blockIds=%d', distinctBlockIds.length);
 		const results = await Promise.all(distinctBlockIds.map(async (blockId) => {
 			const blockStorage = this.createBlockStorage(blockId);
 
@@ -92,6 +96,7 @@ export class StorageRepo implements IRepo {
 		}
 
 		const blockIds = blockIdsForTransforms(request.transforms);
+		log('pend actionId=%s blockIds=%d rev=%s', request.actionId, blockIds.length, request.rev);
 		const pendings: ActionPending[] = [];
 		const missing: ActionTransforms[] = [];
 
@@ -131,6 +136,7 @@ export class StorageRepo implements IRepo {
 		}
 
 		if (missing.length) {
+			log('pend:stale actionId=%s missing=%d', request.actionId, missing.length);
 			return {
 				success: false,
 				missing
@@ -175,6 +181,7 @@ export class StorageRepo implements IRepo {
 	}
 
 	async cancel(actionRef: ActionBlocks, _options?: MessageOptions): Promise<void> {
+		log('cancel actionId=%s blockIds=%d', actionRef.actionId, actionRef.blockIds.length);
 		await Promise.all(actionRef.blockIds.map(blockId => {
 			const blockStorage = this.createBlockStorage(blockId);
 			return blockStorage.deletePendingTransaction(actionRef.actionId);
@@ -182,6 +189,7 @@ export class StorageRepo implements IRepo {
 	}
 
 	async commit(request: CommitRequest, options?: MessageOptions): Promise<CommitResult> {
+		log('commit actionId=%s rev=%d blockIds=%d', request.actionId, request.rev, request.blockIds.length);
 		const uniqueBlockIds = Array.from(new Set(request.blockIds)).sort();
 		const releases: (() => void)[] = [];
 
@@ -222,6 +230,7 @@ export class StorageRepo implements IRepo {
 			}
 
 			if (missedCommits.length) {
+				log('commit:stale actionId=%s missed=%d', request.actionId, missedCommits.length);
 				return { // Return directly, locks will be released in finally
 					success: false,
 					missing: perBlockActionTransformsToPerAction(missedCommits)