trac-msb 0.2.26 → 0.3.0-beta.1

package/src/core/consensus/services/EpochStateMachine.js

@@ -0,0 +1,141 @@
+/**
+ * Stores the data used by one epoch round. Each approval attempt gets a new collection. Late callbacks
+ * must check that their collection is still current and open.
+ *
+ * @typedef {object} EpochRoundContext
+ * @property {function(number): Promise<boolean>} finishAndScheduleNextRound Closes this round and schedules the next one.
+ * @property {bigint} [currentEpoch] Signed parent epoch used to build the proof.
+ * @property {Buffer} [currentEpochHash] Hash of that parent record.
+ * @property {number} [vdfDifficulty] Signed VDF iteration count.
+ * @property {number} [vdfDiscriminantSize] Signed discriminant size in bits.
+ * @property {import('./EpochCoordinatorOperations.js').EpochVdfProof} [vdf] Local proof that can be reused while the parent epoch stays the same.
+ * @property {object} [proofProposalMessage] Signed message containing the local proof.
+ * @property {object} [proofProposal] Proof proposal fields from the signed message.
+ * @property {Set<string>} [indexerKeys] Writer keys captured for this attempt, encoded as hex.
+ * @property {number} [requiredProofSignatures] Proof quorum including the proposer's signature.
+ * @property {Array<{key: Buffer}>} [approvers] Other indexers that can sign this proof.
+ * @property {import('./EpochCoordinatorOperations.js').EpochApprovalCollection|null} [approvalCollection] This attempt's proof approvals.
+ * @property {Buffer} [setEpochPayload] Complete SET_EPOCH operation bytes.
+ * @property {boolean} [remoteProposalReceived] A validated proposal matches this epoch and parent.
+ * @property {boolean} [appendElectionRetry] Use the shorter election backoff for the next retry.
+ */
+import { StateMachine } from "../../../utils/StateMachine.js";
+
+export const EPOCH_STATES = Object.freeze({
+    LOAD_EPOCH_CONTEXT: "LOAD_EPOCH_CONTEXT",
+    INITIALIZE_VDF: "INITIALIZE_VDF",
+    BUILD_AND_SIGN_PROOF_PROPOSAL: "BUILD_AND_SIGN_PROOF_PROPOSAL",
+    SEND_PROPOSAL_TO_INDEXERS: "SEND_PROPOSAL_TO_INDEXERS",
+    COLLECT_APPROVALS: "COLLECT_APPROVALS",
+    QUORUM_DECISION: "QUORUM_DECISION",
+    BUILD_SET_EPOCH: "BUILD_SET_EPOCH",
+    WAIT_FOR_APPEND_REPLIES: "WAIT_FOR_APPEND_REPLIES",
+    REFRESH_SIGNED_STATE_BEFORE_APPEND: "REFRESH_SIGNED_STATE_BEFORE_APPEND",
+    APPEND_SET_EPOCH: "APPEND_SET_EPOCH",
+    WAIT_FOR_APPEND_OUTCOME: "WAIT_FOR_APPEND_OUTCOME",
+    REFRESH_SIGNED_STATE: "REFRESH_SIGNED_STATE",
+    BACKOFF: "BACKOFF",
+    RELOAD_SIGNED_CONTEXT: "RELOAD_SIGNED_CONTEXT",
+});
+
+export const EPOCH_EVENTS = Object.freeze({
+    START: "START",
+    LOCAL_PROOF_READY: "LOCAL_PROOF_READY",
+    PROPOSAL_BUILT: "PROPOSAL_BUILT",
+    EXTERNAL_APPROVALS_REQUIRED: "EXTERNAL_APPROVALS_REQUIRED",
+    EXTERNAL_APPROVALS_NOT_REQUIRED: "EXTERNAL_APPROVALS_NOT_REQUIRED",
+    PROPOSAL_BROADCAST: "PROPOSAL_BROADCAST",
+    QUORUM_REACHED: "QUORUM_REACHED",
+    APPROVAL_COLLECTION_FAILED: "APPROVAL_COLLECTION_FAILED",
+    SET_EPOCH_BUILT: "SET_EPOCH_BUILT",
+    APPEND_REPLIES_COLLECTED: "APPEND_REPLIES_COLLECTED",
+    APPEND_REPLY_COLLECTION_FAILED: "APPEND_REPLY_COLLECTION_FAILED",
+    APPEND_STARTED: "APPEND_STARTED",
+    APPEND_REJECTED: "APPEND_REJECTED",
+    APPENDER_SELECTION_EXPIRED: "APPENDER_SELECTION_EXPIRED",
+    TARGET_EPOCH_ABSENT: "TARGET_EPOCH_ABSENT",
+    TARGET_EPOCH_ALREADY_SIGNED: "TARGET_EPOCH_ALREADY_SIGNED",
+    TARGET_EPOCH_CONFIRMED: "TARGET_EPOCH_CONFIRMED",
+    BACKOFF_ELAPSED: "BACKOFF_ELAPSED",
+    EPOCH_UNCHANGED_WITHOUT_LOCAL_PROOF: "EPOCH_UNCHANGED_WITHOUT_LOCAL_PROOF",
+    EPOCH_UNCHANGED_WITH_LOCAL_PROOF: "EPOCH_UNCHANGED_WITH_LOCAL_PROOF",
+    NEW_EPOCH_DISCOVERED: "NEW_EPOCH_DISCOVERED",
+    SOLVER_FAILURE: "SOLVER FAILURE",
+    INDEXERS_CHANGED: "INDEXERS_CHANGED",
+});
+
+const TRANSITIONS = {
+    [EPOCH_STATES.LOAD_EPOCH_CONTEXT]: Object.freeze({
+        [EPOCH_EVENTS.START]: EPOCH_STATES.INITIALIZE_VDF,
+    }),
+    [EPOCH_STATES.INITIALIZE_VDF]: Object.freeze({
+        [EPOCH_EVENTS.LOCAL_PROOF_READY]: EPOCH_STATES.BUILD_AND_SIGN_PROOF_PROPOSAL,
+        [EPOCH_EVENTS.SOLVER_FAILURE]: EPOCH_STATES.BACKOFF,
+    }),
+    [EPOCH_STATES.BUILD_AND_SIGN_PROOF_PROPOSAL]: Object.freeze({
+        [EPOCH_EVENTS.PROPOSAL_BUILT]: EPOCH_STATES.QUORUM_DECISION,
+    }),
+    [EPOCH_STATES.QUORUM_DECISION]: Object.freeze({
+        [EPOCH_EVENTS.EXTERNAL_APPROVALS_NOT_REQUIRED]: EPOCH_STATES.BUILD_SET_EPOCH,
+        [EPOCH_EVENTS.EXTERNAL_APPROVALS_REQUIRED]: EPOCH_STATES.SEND_PROPOSAL_TO_INDEXERS,
+        [EPOCH_EVENTS.TARGET_EPOCH_ALREADY_SIGNED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+    }),
+    [EPOCH_STATES.SEND_PROPOSAL_TO_INDEXERS]: Object.freeze({
+        [EPOCH_EVENTS.PROPOSAL_BROADCAST]: EPOCH_STATES.COLLECT_APPROVALS,
+        [EPOCH_EVENTS.APPROVAL_COLLECTION_FAILED]: EPOCH_STATES.BACKOFF,
+    }),
+    [EPOCH_STATES.COLLECT_APPROVALS]: Object.freeze({
+        [EPOCH_EVENTS.QUORUM_REACHED]: EPOCH_STATES.BUILD_SET_EPOCH,
+        [EPOCH_EVENTS.APPROVAL_COLLECTION_FAILED]: EPOCH_STATES.BACKOFF,
+    }),
+    [EPOCH_STATES.BUILD_SET_EPOCH]: Object.freeze({
+        [EPOCH_EVENTS.SET_EPOCH_BUILT]: EPOCH_STATES.WAIT_FOR_APPEND_REPLIES,
+    }),
+    [EPOCH_STATES.WAIT_FOR_APPEND_REPLIES]: Object.freeze({
+        [EPOCH_EVENTS.APPEND_REPLIES_COLLECTED]: EPOCH_STATES.REFRESH_SIGNED_STATE_BEFORE_APPEND,
+        [EPOCH_EVENTS.APPEND_REPLY_COLLECTION_FAILED]: EPOCH_STATES.BACKOFF,
+        [EPOCH_EVENTS.TARGET_EPOCH_ALREADY_SIGNED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+    }),
+    [EPOCH_STATES.REFRESH_SIGNED_STATE_BEFORE_APPEND]: Object.freeze({
+        [EPOCH_EVENTS.TARGET_EPOCH_ABSENT]: EPOCH_STATES.APPEND_SET_EPOCH,
+        [EPOCH_EVENTS.TARGET_EPOCH_ALREADY_SIGNED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+        [EPOCH_EVENTS.INDEXERS_CHANGED]: EPOCH_STATES.QUORUM_DECISION,
+    }),
+    [EPOCH_STATES.APPEND_SET_EPOCH]: Object.freeze({
+        [EPOCH_EVENTS.APPEND_STARTED]: EPOCH_STATES.WAIT_FOR_APPEND_OUTCOME,
+        [EPOCH_EVENTS.APPEND_REJECTED]: EPOCH_STATES.BACKOFF,
+        [EPOCH_EVENTS.TARGET_EPOCH_CONFIRMED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+        [EPOCH_EVENTS.TARGET_EPOCH_ALREADY_SIGNED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+    }),
+    [EPOCH_STATES.WAIT_FOR_APPEND_OUTCOME]: Object.freeze({
+        [EPOCH_EVENTS.TARGET_EPOCH_CONFIRMED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+        [EPOCH_EVENTS.APPEND_REJECTED]: EPOCH_STATES.BACKOFF,
+        [EPOCH_EVENTS.APPENDER_SELECTION_EXPIRED]: EPOCH_STATES.BACKOFF,
+        [EPOCH_EVENTS.TARGET_EPOCH_ALREADY_SIGNED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+    }),
+    [EPOCH_STATES.REFRESH_SIGNED_STATE]: Object.freeze({
+        [EPOCH_EVENTS.EPOCH_UNCHANGED_WITHOUT_LOCAL_PROOF]: EPOCH_STATES.INITIALIZE_VDF,
+        [EPOCH_EVENTS.EPOCH_UNCHANGED_WITH_LOCAL_PROOF]: EPOCH_STATES.BUILD_AND_SIGN_PROOF_PROPOSAL,
+        [EPOCH_EVENTS.NEW_EPOCH_DISCOVERED]: EPOCH_STATES.RELOAD_SIGNED_CONTEXT,
+    }),
+    [EPOCH_STATES.BACKOFF]: Object.freeze({
+        [EPOCH_EVENTS.BACKOFF_ELAPSED]: EPOCH_STATES.REFRESH_SIGNED_STATE,
+    }),
+};
+
+/**
+ * Defines the states and transitions for one epoch round. EpochCoordinationRound supplies the
+ * handlers. Proof approvals, appender selection and append confirmation are separate steps.
+ * WAIT_FOR_APPEND_OUTCOME waits for a signed result or selection expiry after the local append starts.
+ */
+export class EpochStateMachine extends StateMachine {
+    /**
+     * Connects the round handlers to the transition table. Entering LOAD_EPOCH_CONTEXT clears the
+     * previous context.
+     *
+     * @param {Object<string, function(EpochRoundContext, EpochStateMachine): Promise<void>>} [handlers={}] Handlers indexed by EPOCH_STATES.
+     */
+    constructor(handlers = {}) {
+        super(TRANSITIONS, EPOCH_STATES.LOAD_EPOCH_CONTEXT, EPOCH_STATES.LOAD_EPOCH_CONTEXT, handlers);
+    }
+}

package/src/core/consensus/services/VDFBare.js

@@ -0,0 +1,291 @@
+import { VDFService } from './VDFService.js';
+import { VDFProgressWatchdog } from './VDFProgressWatchdog.js';
+
+let bareBinaryPathPromise = null;
+
+/**
+ * Finds the bundled Bare executable and saves its path for later calls. Pear needs the actual file
+ * path to start this worker. Sets the executable permission before using it.
+ *
+ * @returns {Promise<string>} Absolute executable path.
+ */
+async function resolveBareBinaryPath() {
+    if (!bareBinaryPathPromise) {
+        bareBinaryPathPromise = (async () => {
+            const { fileURLToPath } = await import('bare-url');
+            const fs = await import('bare-fs');
+
+            const nodeModulesUrl = typeof globalThis.Pear !== 'undefined'
+                ? `file://${globalThis.Pear.config.dir}/node_modules/`
+                : new URL('../../../../node_modules/', import.meta.url).href;
+            
+            const binaryPath = fileURLToPath(
+                new URL(`./bare-runtime-${Bare.platform}-${Bare.arch}/bin/bare`, nodeModulesUrl) // eslint-disable-line no-undef
+            );
+
+            // npm doesn't reliably preserve the executable bit on this binary across installs.
+            await fs.promises.chmod(binaryPath, 0o755);
+
+            return binaryPath;
+        })();
+    }
+    return bareBinaryPathPromise;
+}
+
+/**
+ * Runs each VDF calculation in a separate Bare process. This lets the parent stop the solver by
+ * closing the process. Requests and responses use one JSON object per line. The service uses the same
+ * write, read and close methods as the Node worker.
+ */
+class SubprocessPort {
+    #workerScriptUrl;
+    #workerProcess = null;
+    #workerExitPromise = null;
+    #workerResponsePromise = null;
+    #resolvePendingResponse = null;
+    #closed = false;
+
+    /** @param {string} workerFileUrl file URL of the VDF worker script */
+    constructor(workerFileUrl) {
+        this.#workerScriptUrl = workerFileUrl;
+    }
+
+    /**
+     * Starts a Bare process and sends the calculation to its standard input. Checks whether the port
+     * was closed during setup before starting the process.
+     *
+     * @param {object} calculationRequest Worker calculation data.
+     * @param {Buffer} calculationRequest.challenge Encoded epoch challenge.
+     * @param {number} calculationRequest.difficulty VDF iteration count.
+     * @param {number} calculationRequest.discriminantSizeBits Discriminant size in bits.
+     * @returns {Promise<void>} Resolves after sending the request. Call read() for the result.
+     */
+    async write({ challenge, difficulty, discriminantSizeBits }) {
+        if (this.#closed) throw new Error('VDF subprocess is closed');
+
+        const { spawn } = await import('bare-subprocess');
+        const { fileURLToPath } = await import('bare-url');
+        const { default: hrtime } = await import('bare-hrtime');
+
+        const bareBinaryPath = await resolveBareBinaryPath();
+        if (this.#closed) throw new Error('VDF subprocess is closed');
+
+        const workerProcess = spawn(
+            bareBinaryPath,
+            [fileURLToPath(new URL(this.#workerScriptUrl))],
+            { stdio: ['pipe', 'pipe', 'pipe', 'pipe'] }
+        );
+        this.#workerProcess = workerProcess;
+
+        let resolveChildExit;
+        this.#workerExitPromise = new Promise(resolve => {
+            resolveChildExit = resolve;
+        });
+        const workerPipesClosed = Promise.all(workerProcess.stdio.map(pipe => (
+            new Promise(resolve => pipe.once('close', resolve))
+        )));
+
+        // Attached synchronously, right after spawn, in the same tick as the write below -
+        // no await/gap in between where a fast response or an unexpected early exit could
+        // fire before a listener exists to catch it.
+        this.#workerResponsePromise = new Promise(resolve => {
+            let responseBuffer = '';
+            let settled = false;
+            let watchdog;
+
+            const resolveWorkerResponse = (workerResponse) => {
+                if (settled) return;
+                settled = true;
+                watchdog?.stop();
+                resolve(workerResponse);
+                // Deferred to the next tick: killing the child synchronously here, in the
+                // same tick as resolve(), was empirically linked to a downstream deadlock
+                // elsewhere in the process (unrelated pending autobase/hyperbee work never
+                // resolving) - reproduced and fixed by decoupling the kill from the resolve.
+                setImmediate(() => workerProcess.kill('SIGKILL'));
+            };
+            this.#resolvePendingResponse = resolveWorkerResponse;
+            watchdog = new VDFProgressWatchdog({
+                now: () => Number(hrtime.bigint() / 1_000_000n),
+                onStall: error => resolveWorkerResponse({ error }),
+            });
+
+            let progressBuffer = '';
+            const ownership = workerProcess.stdio[3];
+            ownership.on('data', chunk => {
+                if (settled) return;
+                progressBuffer += chunk.toString();
+                try {
+                    if (progressBuffer.length > 64 * 1024) throw new Error('VDF progress message is too large');
+                    let newline;
+                    while ((newline = progressBuffer.indexOf('\n')) !== -1) {
+                        const message = JSON.parse(progressBuffer.slice(0, newline));
+                        progressBuffer = progressBuffer.slice(newline + 1);
+                        if (message.ready === true) watchdog.ready();
+                        else watchdog.progress(message.progress);
+                    }
+                } catch (error) {
+                    resolveWorkerResponse({ error });
+                }
+            });
+            ownership.on('end', () => resolveWorkerResponse({ error: 'VDF guardian disconnected' }));
+
+            for (const pipe of workerProcess.stdio) {
+                pipe.on('error', error => resolveWorkerResponse({ error }));
+            }
+            // An unread stderr pipe can block the worker when its buffer fills.
+            workerProcess.stderr.resume();
+
+            workerProcess.stdout.on('data', (chunk) => {
+                if (settled) return;
+                responseBuffer += chunk.toString();
+                const newlineIndex = responseBuffer.indexOf('\n');
+                if (newlineIndex === -1) return;
+                const responseLine = responseBuffer.slice(0, newlineIndex);
+                try {
+                    const encodedResponse = JSON.parse(responseLine);
+                    resolveWorkerResponse(decodeWorkerResponse(encodedResponse));
+                } catch {
+                    // Not a Bare.Thread/bare-subprocess assumption - stdout is a boundary to an
+                    // external process, so unexpected content there (e.g. a CLI usage error
+                    // from spawning the wrong binary, as happened in manual QA) must fail the
+                    // request instead of crashing the caller.
+                    resolveWorkerResponse({ error: `VDF worker returned an invalid response: ${responseLine}` });
+                    return;
+                }
+            });
+
+            workerProcess.on('exit', (exitCode, signalCode) => {
+                resolveWorkerResponse({ error: `VDF worker process exited unexpectedly (code ${exitCode}, signal ${signalCode})` });
+                // bare-subprocess does not close every pipe when the process exits.
+                // Await their native handles too, before allowing another calculation.
+                for (const pipe of workerProcess.stdio) pipe.destroy();
+                workerPipesClosed.then(resolveChildExit);
+            });
+        });
+
+        try {
+            workerProcess.stdin.write(JSON.stringify({
+                challenge: challenge.toString('hex'),
+                difficulty,
+                discriminantSizeBits
+            }) + '\n');
+        } catch (error) {
+            this.#resolvePendingResponse?.({ error });
+            // read() still waits for process and pipe cleanup before the queue advances.
+        }
+    }
+
+    /**
+     * Waits for the response and for the process to exit. Clears the references only if they still
+     * belong to this calculation.
+     *
+     * @returns {Promise<import('./VDFService.js').VdfWorkerResponse>}
+     */
+    async read() {
+        const workerResponse = this.#workerResponsePromise;
+        const workerExitPromise = this.#workerExitPromise;
+        if (!workerResponse) return { error: 'No pending VDF request' };
+
+        try {
+            const calculationResponse = await workerResponse;
+            await workerExitPromise;
+            return calculationResponse;
+        } finally {
+            if (this.#workerResponsePromise === workerResponse) {
+                this.#workerProcess = null;
+                this.#workerExitPromise = null;
+                this.#workerResponsePromise = null;
+                this.#resolvePendingResponse = null;
+            }
+        }
+    }
+
+    /**
+     * Returns an error to the pending calculation, stops the process and waits for it to exit.
+     *
+     * @param {Error} error cancellation reason returned to the waiting calculation
+     * @returns {Promise<void>}
+     */
+    async close(error = new Error('VDF subprocess closed')) {
+        this.#closed = true;
+
+        const workerProcess = this.#workerProcess;
+        const workerExitPromise = this.#workerExitPromise;
+        const workerResponse = this.#workerResponsePromise;
+
+        this.#resolvePendingResponse?.({ error });
+        workerProcess?.kill('SIGKILL');
+
+        try {
+            await Promise.all([workerResponse, workerExitPromise]);
+        } finally {
+            if (this.#workerProcess === workerProcess) this.#workerProcess = null;
+            if (this.#workerExitPromise === workerExitPromise) this.#workerExitPromise = null;
+            if (this.#workerResponsePromise === workerResponse) this.#workerResponsePromise = null;
+            this.#resolvePendingResponse = null;
+        }
+    }
+}
+
+/**
+ * Converts the challenge and solution in the worker response from hex to buffers.
+ *
+ * @param {object} encodedResponse Parsed JSON worker response.
+ * @returns {import('./VDFService.js').VdfWorkerResponse}
+ */
+function decodeWorkerResponse(encodedResponse) {
+    if (encodedResponse.error) return { error: encodedResponse.error };
+    const { challenge, difficulty, discriminantSizeBits, solution } = encodedResponse.result;
+    return {
+        result: {
+            challenge: Buffer.from(challenge, 'hex'),
+            difficulty,
+            discriminantSizeBits,
+            solution: Buffer.from(solution, 'hex')
+        }
+    };
+}
+
+/**
+ * Runs VDF calculations in Bare and Pear using separate processes. Messages use JSON between processes
+ * and buffers inside the consensus module.
+ */
+export class VDFBare extends VDFService {
+    #workerURL; // for test injection
+
+    /**
+     * Creates the Bare VDF service. A different worker URL can be provided for tests.
+     *
+     * @param {URL} workerURL Script to run in the worker process.
+     */
+    constructor(workerURL = new URL('./vdf-worker.js', import.meta.url)) {
+        super();
+        this.#workerURL = workerURL;
+    }
+
+    /** Creates the worker port used by VDFService. */
+    async _open() {
+        this._setPort(new SubprocessPort(this.#resolveWorkerFileUrl()));
+    }
+
+    /**
+     * Returns the worker file URL that Bare or Pear can open.
+     *
+     * @returns {string}
+     */
+    #resolveWorkerFileUrl() {
+        // Pear's `pear://dev/` module protocol isn't registered inside a freshly
+        // spawned subprocess, so a pear:// reference (e.g. import.meta.url under
+        // `pear run`) fails with UNKNOWN_PROTOCOL there. Pear.config.dir is the
+        // real on-disk path this app runs from (trac-msb is always run via a
+        // local directory link, not a seeded pear:// app), so build a plain
+        // file:// URL from it instead. Outside Pear (plain `bare`), the injected/default
+        // worker URL is already a file:// URL and works as-is.
+        if (typeof globalThis.Pear !== 'undefined') {
+            const applicationDirectory = globalThis.Pear.config.dir;
+            return new URL('./vdf-worker.js', `file://${applicationDirectory}/src/core/consensus/services/`).href;
+        }
+        return this.#workerURL.href;
+    }
+}

package/src/core/consensus/services/VDFNode.js

@@ -0,0 +1,111 @@
+import { VDFService } from './VDFService.js';
+
+/**
+ * Runs VDF calculations in a Node worker thread. Provides the write, read and close methods used by
+ * VDFService.
+ */
+export class VDFNode extends VDFService {
+    #workerThread = null;
+    #workerURL; // for test injection
+
+    /**
+     * Creates the Node VDF service. A different worker URL can be provided for tests.
+     *
+     * @param {URL} workerURL Script to run in the worker thread.
+     */
+    constructor (workerURL = new URL('./vdf-worker.js', import.meta.url)) {
+        super();
+        this.#workerURL = workerURL;
+    }
+
+    /**
+     * Starts a worker thread and connects its MessagePort to VDFService.
+     *
+     * @returns {Promise<void>}
+     * @protected
+     */
+    async _open() {
+        const { Worker, MessageChannel } = await import('worker_threads');
+        const { port1, port2 } = new MessageChannel();
+        const workerPortAdapter = this.#createWorkerPortAdapter(port1);
+        this._setPort(workerPortAdapter);
+        this.#workerThread = new Worker(this.#workerURL, {
+            workerData: { port: port2 },
+            transferList: [port2],
+        });
+        this.#workerThread.on('error', (workerError) => workerPortAdapter.fail(workerError));
+        this.#workerThread.on('exit', (exitCode) => {
+            workerPortAdapter.fail(new Error(`VDF worker exited with code ${exitCode}`));
+        });
+    }
+
+    /**
+     * Cancels pending reads and stops the worker thread.
+     *
+     * @returns {Promise<void>}
+     * @protected
+     */
+    async _close() {
+        await super._close();
+        await this.#workerThread?.terminate();
+        this.#workerThread = null;
+    }
+
+    /**
+     * Keeps worker responses until read() is called. If the worker fails or closes, returns the same
+     * error to all pending reads and clears stored responses.
+     *
+     * @param {import('worker_threads').MessagePort} messagePort Node message port used by the parent process.
+     * @returns {import('./VDFService.js').VdfWorkerPort & {fail: function(Error): void}} Worker port with a callback for reporting worker errors.
+     */
+    #createWorkerPortAdapter(messagePort) {
+        const bufferedResponses = [];
+        const pendingReaders = [];
+        let closed = false;
+        let closeError = null;
+
+        const failPendingReads = (error) => {
+            if (closed) return;
+
+            closed = true;
+            closeError = error instanceof Error ? error : new Error(String(error));
+            bufferedResponses.length = 0;
+            for (const resolve of pendingReaders) resolve({ error: closeError });
+            pendingReaders.length = 0;
+            messagePort.close();
+        };
+
+        messagePort.on('message', (workerResponse) => {
+            if (closed) return;
+
+            if (pendingReaders.length > 0) {
+                pendingReaders.shift()(workerResponse);
+            } else {
+                bufferedResponses.push(workerResponse);
+            }
+        });
+        messagePort.on('close', () => failPendingReads(new Error('VDF worker port closed')));
+
+        return {
+            write: (calculationRequest) => {
+                if (closed) return Promise.reject(closeError);
+                messagePort.postMessage(calculationRequest);
+                return Promise.resolve();
+            },
+            read: () => new Promise(resolve => {
+                if (bufferedResponses.length > 0) {
+                    resolve(bufferedResponses.shift());
+                } else if (closed) {
+                    resolve({ error: closeError });
+                } else {
+                    pendingReaders.push(resolve);
+                }
+            }),
+            close: (error = new Error('VDF worker closed')) => {
+                failPendingReads(error);
+                return Promise.resolve();
+            },
+            fail: failPendingReads,
+        };
+    }
+}

package/src/core/consensus/services/VDFProgressWatchdog.js

@@ -0,0 +1,79 @@
+// These counters describe completed work, not timer heartbeats. Keep the order in
+// sync between the solver thread and its guardian.
+export const VDF_PROGRESS_PHASES = [
+    'discriminant-sieve', 'discriminant-candidates', 'squaring', 'challenge-prime',
+    'proof-setup', 'proof-blocks', 'proof-aggregation', 'serialization',
+];
+
+const MIN_PROGRESS_TIMEOUT_MS = 30_000;
+
+/** Detects silence without imposing a deadline on the complete calculation. */
+export class VDFProgressWatchdog {
+    #now;
+    #onStall;
+    #timer;
+    #lastProgress;
+    #longestGap = 0;
+    #counts = VDF_PROGRESS_PHASES.map(() => 0n);
+    #stopped = false;
+    #phase = 'startup';
+    #ready = false;
+
+    constructor({ now, onStall }) {
+        this.#now = now;
+        this.#onStall = onStall;
+        this.#lastProgress = now();
+        // Before the first observation there is no measured pace. This is a
+        // startup allowance, not a limit derived from VDF difficulty or length.
+        this.#arm(MIN_PROGRESS_TIMEOUT_MS);
+    }
+
+    ready() {
+        if (this.#ready || this.#stopped) return;
+        this.#ready = true;
+        // Process/thread startup is separate from the native solver's pace.
+        this.#lastProgress = this.#now();
+    }
+
+    progress(counts) {
+        if (this.#stopped) return;
+        if (!Array.isArray(counts) || counts.length !== this.#counts.length) {
+            throw new Error('Invalid VDF progress counters');
+        }
+        const next = counts.map(count => {
+            if (typeof count !== 'string' || !/^\d{1,20}$/.test(count)) {
+                throw new Error('Invalid VDF progress counter');
+            }
+            return BigInt(count);
+        });
+        let advanced = false;
+        for (let i = 0; i < next.length; i++) {
+            if (next[i] < this.#counts[i]) throw new Error('VDF progress moved backwards');
+            if (next[i] > this.#counts[i]) {
+                advanced = true;
+                this.#phase = VDF_PROGRESS_PHASES[i];
+            }
+        }
+        if (!advanced) return;
+        const now = this.#now();
+        this.#longestGap = Math.max(this.#longestGap, now - this.#lastProgress);
+        this.#lastProgress = now;
+        this.#counts = next;
+        this.#arm(Math.max(MIN_PROGRESS_TIMEOUT_MS, this.#longestGap * 8));
+    }
+
+    stop() {
+        this.#stopped = true;
+        clearTimeout(this.#timer);
+    }
+
+    #arm(delay) {
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => {
+            this.stop();
+            const error = new Error(`VDF stopped making progress (${this.#phase})`);
+            error.code = 'VDF_STALLED';
+            this.#onStall(error);
+        }, Math.min(delay, 2_147_483_647));
+    }
+}