@optimystic/db-p2p 0.13.4 → 0.14.0

package/src/dispute/dispute-service.ts

@@ -1,4 +1,6 @@
-import type { ClusterRecord, ITransactionValidator } from '@optimystic/db-core';
+import type { ClusterRecord, ITransactionValidator, InvalidateRequest, CommitRequest, PendRequest, CollectionId } from '@optimystic/db-core';
+import { blockIdsForTransforms } from '@optimystic/db-core';
+import { buildDisputeResolutionProof, computeTargetHash, computeArbitratorSetHash, voteSigningPayload, arbitratorSetSigningPayload, VOTE_VERSION, type CertificateTarget } from './invalidation.js';
 import type { PeerId, PrivateKey } from '@libp2p/interface';
 import { sha256 } from 'multiformats/hashes/sha2';
 import { base58btc } from 'multiformats/bases/base58';
@@ -39,6 +41,15 @@ export interface DisputeServiceInit {
 	config?: Partial<DisputeConfig>;
 	/** Select arbitrators for a dispute (next K peers beyond the original cluster) */
 	selectArbitrators: (blockId: string, excludePeers: string[], count: number) => Promise<PeerId[]>;
+	/**
+	 * Originates the durable reversal when a dispute resolves `challenger-wins`. The dissent
+	 * coordinator (the node that initiated the dispute, holding the original record) builds the
+	 * {@link InvalidateRequest} and hands it here to be driven through the critical cluster as a
+	 * consensus-ordered invalidation; every member then applies it deterministically. Absent on
+	 * nodes not wired to originate invalidations (today's default) — the in-memory status still flips,
+	 * but nothing durable is written until this is supplied.
+	 */
+	onInvalidation?: (request: InvalidateRequest) => Promise<void> | void;
 }
 
 /**
@@ -57,6 +68,7 @@ export class DisputeService {
 	private readonly config: DisputeConfig;
 	private readonly engineHealth: EngineHealthMonitor;
 	private readonly selectArbitrators: DisputeServiceInit['selectArbitrators'];
+	private readonly onInvalidation?: DisputeServiceInit['onInvalidation'];
 
 	/** Active disputes initiated by this node */
 	private activeDisputes: Map<string, DisputeChallenge> = new Map();
@@ -66,6 +78,8 @@ export class DisputeService {
 	private resolvedChallenges: Map<string, DisputeChallenge> = new Map();
 	/** Track which transactions we've already disputed (prevent spam) */
 	private disputedTransactions: Set<string> = new Set();
+	/** Track which transactions we've already originated an invalidation for (fire once per messageHash) */
+	private invalidatedTransactions: Set<string> = new Set();
 
 	constructor(init: DisputeServiceInit) {
 		this.peerId = init.peerId;
@@ -76,6 +90,7 @@ export class DisputeService {
 		this.config = { ...DEFAULT_DISPUTE_CONFIG, ...init.config };
 		this.engineHealth = new EngineHealthMonitor(this.config);
 		this.selectArbitrators = init.selectArbitrators;
+		this.onInvalidation = init.onInvalidation;
 	}
 
 	/** Get the engine health monitor */
@@ -141,21 +156,8 @@ export class DisputeService {
 			: this.config.disputeArbitrationTimeoutMs * 2;
 		const expiration = timestamp + Math.max(defaultTtl, this.config.disputeArbitrationTimeoutMs);
 
-		const challenge: DisputeChallenge = {
-			disputeId,
-			originalMessageHash: record.messageHash,
-			originalRecord: record,
-			challengerPeerId: this.peerId.toString(),
-			challengerEvidence: evidence,
-			signature,
-			timestamp,
-			expiration,
-		};
-
-		this.activeDisputes.set(disputeId, challenge);
-		log('dispute-initiated', { disputeId, messageHash: record.messageHash });
-
-		// Select arbitrators and collect votes
+		// Select the arbitrator set FIRST so the challenge can carry it: each arbitrator folds the set's
+		// digest into the v3 vote it signs, binding every vote to the legitimately-selected set (#1).
 		const blockIds = record.coordinatingBlockIds ?? [];
 		const blockId = blockIds[0] ?? record.messageHash;
 		const originalPeers = Object.keys(record.peers);
@@ -166,16 +168,31 @@ export class DisputeService {
 			arbitrators = await this.selectArbitrators(blockId, originalPeers, arbitratorCount);
 		} catch (err) {
 			log('dispute-arbitrator-selection-failed', { disputeId, error: err instanceof Error ? err.message : String(err) });
-			this.activeDisputes.delete(disputeId);
 			return undefined;
 		}
 
 		if (arbitrators.length === 0) {
 			log('dispute-no-arbitrators', { disputeId });
-			this.activeDisputes.delete(disputeId);
 			return undefined;
 		}
 
+		const arbitratorSet = arbitrators.map(a => a.toString());
+
+		const challenge: DisputeChallenge = {
+			disputeId,
+			originalMessageHash: record.messageHash,
+			originalRecord: record,
+			challengerPeerId: this.peerId.toString(),
+			challengerEvidence: evidence,
+			signature,
+			timestamp,
+			expiration,
+			arbitratorSet,
+		};
+
+		this.activeDisputes.set(disputeId, challenge);
+		log('dispute-initiated', { disputeId, messageHash: record.messageHash });
+
 		// Send challenge to all arbitrators and collect votes
 		const votes = await this.collectVotes(challenge, arbitrators);
 		const resolution = this.resolveDispute(challenge, votes);
@@ -187,6 +204,10 @@ export class DisputeService {
 		// Apply reputation effects
 		this.applyReputationEffects(resolution, record);
 
+		// On a proven-invalid transaction, originate the durable reversal through the cluster. The
+		// challenger-selected `arbitratorSet` is bound into the proof (#1).
+		await this.maybeInvalidate(resolution, record, arbitratorSet);
+
 		// Broadcast resolution
 		await this.broadcastResolution(resolution, arbitrators, originalPeers);
 
@@ -207,6 +228,12 @@ export class DisputeService {
 	async handleChallenge(challenge: DisputeChallenge): Promise<ArbitrationVote> {
 		log('dispute-handle-challenge', { disputeId: challenge.disputeId });
 
+		// Bind every vote to the disputed transaction AND the legitimately-selected arbitrator set: derive
+		// the reversal target the same way the originator/apply path does (so the verifier recomputes an
+		// identical targetHash), digest the set the challenger carried, and sign over both (#1, #2).
+		const targetHash = await this.computeChallengeTargetHash(challenge);
+		const setHash = await computeArbitratorSetHash(challenge.arbitratorSet ?? []);
+
 		// Verify the challenge signature
 		const validSignature = await this.verifyDisputeSignature(
 			challenge.disputeId,
@@ -221,7 +248,7 @@ export class DisputeService {
 				engineId: 'unknown',
 				schemaHash: '',
 				blockStateHashes: {},
-			});
+			}, targetHash, setHash);
 		}
 
 		// Re-execute the transaction to produce our own evidence
@@ -244,7 +271,7 @@ export class DisputeService {
 				engineId: 'unknown',
 				schemaHash: '',
 				blockStateHashes: {},
-			});
+			}, targetHash, setHash);
 		}
 
 		// Compare our evidence with the challenger's
@@ -257,7 +284,22 @@ export class DisputeService {
 			vote = 'agree-with-majority';
 		}
 
-		return this.makeVote(challenge.disputeId, vote, evidence);
+		return this.makeVote(challenge.disputeId, vote, evidence, targetHash, setHash);
+	}
+
+	/**
+	 * Derives the v2 target hash binding a vote to the disputed transaction: its `messageHash` plus the
+	 * reversal target (the committed action being reversed and the blocks it wrote), extracted from the
+	 * challenge's `originalRecord` exactly as {@link extractInvalidationTarget} does on the originate/apply
+	 * side. A record with no extractable target yields an empty target — the resulting vote still verifies
+	 * self-consistently but will not match a real reversal, which is correct (no real reversal exists).
+	 */
+	private async computeChallengeTargetHash(challenge: DisputeChallenge): Promise<string> {
+		const target = DisputeService.extractInvalidationTarget(challenge.originalRecord);
+		const certTarget: CertificateTarget = target
+			? { invalidatedActionId: target.actionId, blockIds: target.blockIds }
+			: { invalidatedActionId: '', blockIds: [] };
+		return computeTargetHash(challenge.originalRecord.messageHash, certTarget);
 	}
 
 	/**
@@ -373,6 +415,96 @@ export class DisputeService {
 		}
 	}
 
+	/**
+	 * When a dispute resolves `challenger-wins`, originate the durable invalidation. Builds the
+	 * independently-verifiable {@link buildDisputeResolutionProof proof} and the {@link InvalidateRequest}
+	 * from the disputed transaction, then hands it to the injected `onInvalidation` originator (which
+	 * drives it through the critical cluster). Fires at most once per disputed transaction. A no-op
+	 * when no originator is wired (the in-memory status still flips via {@link getDisputeStatus}).
+	 */
+	private async maybeInvalidate(resolution: DisputeResolution, record: ClusterRecord, arbitratorSet: string[]): Promise<void> {
+		if (resolution.outcome !== 'challenger-wins' || !this.onInvalidation) {
+			return;
+		}
+		if (this.invalidatedTransactions.has(record.messageHash)) {
+			return;
+		}
+
+		const target = DisputeService.extractInvalidationTarget(record);
+		if (!target) {
+			log('dispute-invalidation-no-target', { disputeId: resolution.disputeId, messageHash: record.messageHash });
+			return;
+		}
+
+		// Bind the legitimately-selected arbitrator set (#1): the challenger signs (disputeId, target, set)
+		// so a third-party relay cannot swap in its own cohort. Same target derivation as the apply path.
+		const certTarget: CertificateTarget = { invalidatedActionId: target.actionId, blockIds: target.blockIds };
+		const targetHash = await computeTargetHash(record.messageHash, certTarget);
+		const setHash = await computeArbitratorSetHash(arbitratorSet);
+		const arbitratorSetSignature = await this.signArbitratorSet(resolution.disputeId, targetHash, setHash);
+
+		this.invalidatedTransactions.add(record.messageHash);
+		const request: InvalidateRequest = {
+			invalidatedActionId: target.actionId,
+			invalidatedRev: target.rev,
+			blockIds: target.blockIds,
+			collectionId: target.collectionId,
+			resolution: buildDisputeResolutionProof(resolution, record.messageHash, {
+				arbitratorSet,
+				challengerPeerId: this.peerId.toString(),
+				arbitratorSetSignature,
+			}),
+		};
+
+		try {
+			await this.onInvalidation(request);
+			log('dispute-invalidation-originated', {
+				disputeId: resolution.disputeId,
+				invalidatedActionId: target.actionId,
+				blockCount: target.blockIds.length,
+			});
+		} catch (err) {
+			// Roll back the once-guard so a retry can re-originate.
+			this.invalidatedTransactions.delete(record.messageHash);
+			log('dispute-invalidation-originate-failed', {
+				disputeId: resolution.disputeId,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+
+	/**
+	 * Derives the invalidation target — the committed action, its revision, the blocks it wrote, and
+	 * its owning collection — from the disputed record. Prefers the commit operation (the disputed
+	 * transaction is committed); falls back to the pend operation defensively.
+	 */
+	private static extractInvalidationTarget(record: ClusterRecord): { actionId: string; rev: number; blockIds: string[]; collectionId: CollectionId } | undefined {
+		for (const operation of record.message.operations) {
+			if ('commit' in operation) {
+				const commit = operation.commit as CommitRequest;
+				return {
+					actionId: commit.actionId,
+					rev: commit.rev,
+					blockIds: commit.blockIds,
+					collectionId: commit.headerId ?? record.coordinatingBlockIds?.[0] ?? commit.blockIds[0]!,
+				};
+			}
+		}
+		for (const operation of record.message.operations) {
+			if ('pend' in operation) {
+				const pend = operation.pend as PendRequest;
+				const blockIds = blockIdsForTransforms(pend.transforms);
+				return {
+					actionId: pend.actionId,
+					rev: pend.rev ?? 0,
+					blockIds,
+					collectionId: record.coordinatingBlockIds?.[0] ?? blockIds[0]!,
+				};
+			}
+		}
+		return undefined;
+	}
+
 	/** Broadcast resolution to all interested parties */
 	private async broadcastResolution(
 		resolution: DisputeResolution,
@@ -405,13 +537,18 @@ export class DisputeService {
 	private async makeVote(
 		disputeId: string,
 		vote: ArbitrationVote['vote'],
-		evidence: ValidationEvidence
+		evidence: ValidationEvidence,
+		targetHash: string,
+		setHash: string
 	): Promise<ArbitrationVote> {
-		const payload = `${disputeId}:${vote}:${evidence.computedHash}`;
-		const payloadBytes = new TextEncoder().encode(payload);
+		// Target- and set-bound v3 payload: binds the vote to the specific transaction being reversed (#2)
+		// AND the legitimately-selected arbitrator set (#1) so a genuine vote can neither be replayed against
+		// an unrelated transaction nor presented under a swapped cohort.
+		const payloadBytes = voteSigningPayload(disputeId, vote, evidence.computedHash, targetHash, setHash);
 		const sigBytes = await this.privateKey.sign(payloadBytes);
 
 		return {
+			version: VOTE_VERSION,
 			disputeId,
 			arbitratorPeerId: this.peerId.toString(),
 			vote,
@@ -433,6 +570,16 @@ export class DisputeService {
 		return uint8ArrayToString(sigBytes, 'base64url');
 	}
 
+	/**
+	 * Sign the arbitrator-set binding `(disputeId, target, arbitratorSet)` with the challenger's key.
+	 * Carried on the proof as {@link DisputeResolutionProof.arbitratorSetSignature}; a verifier validates
+	 * it against this peer's embedded key (`challengerPeerId`), so a relay cannot substitute its own cohort.
+	 */
+	private async signArbitratorSet(disputeId: string, targetHash: string, setHash: string): Promise<string> {
+		const sigBytes = await this.privateKey.sign(arbitratorSetSigningPayload(disputeId, targetHash, setHash));
+		return uint8ArrayToString(sigBytes, 'base64url');
+	}
+
 	private async verifyDisputeSignature(
 		disputeId: string,
 		signature: string,

package/src/dispute/index.ts

@@ -15,3 +15,45 @@ export {
 	DEFAULT_DISPUTE_CONFIG,
 } from './types.js';
 export { selectArbitrators } from './arbitrator-selection.js';
+export {
+	buildDisputeResolutionProof,
+	verifyInvalidationCertificate,
+	computeRevertedBlock,
+	computeTargetHash,
+	computeArbitratorSetHash,
+	voteSigningPayload,
+	arbitratorSetSigningPayload,
+	applyInvalidation,
+	hashBlockContent,
+	DELETED_BLOCK_RESTORE,
+	VOTE_VERSION,
+	type CertificateTarget,
+	type ArbitratorSetBinding,
+	type ArbitratorSetRecompute,
+	type ArbitratorSetRecomputeContext,
+	type ArbitratorSetVerdict,
+	type UnanchoredAcceptanceInfo,
+	type VerifyCertificateOptions,
+	type RevertedComputation,
+	type InvalidationContext,
+	type ApplyInvalidationParams,
+	type ApplyInvalidationResult,
+} from './invalidation.js';
+
+export {
+	cascadeInvalidate,
+	contentEqualityReevaluator,
+	DEFAULT_CASCADE_CONFIG,
+	type CascadeConfig,
+	type CollectionEnv,
+	type InvalidatedPair,
+	type CascadeCandidate,
+	type CascadeVerdict,
+	type Reevaluate,
+	type CascadeSeed,
+	type CascadeInput,
+	type CascadeChild,
+	type CascadeStanding,
+	type CascadeEscalation,
+	type CascadeResult,
+} from './cascade.js';