trac-msb 0.2.26 → 0.3.0-beta.1

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

@@ -0,0 +1,87 @@
+/**
+ * @typedef {object} VdfWorkerResponse
+ * @property {{challenge: Buffer, difficulty: number, discriminantSizeBits: number, solution: Buffer}} [result] Successful calculation.
+ * @property {Error|string} [error] Error from the worker, connection or cancellation.
+ *
+ * @typedef {object} VdfWorkerPort
+ * @property {function({challenge: Buffer, difficulty: number, discriminantSizeBits: number}): Promise<void>} write Start a calculation.
+ * @property {function(): Promise<VdfWorkerResponse>} read Wait for that calculation's response.
+ * @property {function(Error): Promise<void>} close Cancels pending reads and closes the worker port.
+ */
+import ReadyResource from 'ready-resource';
+
+/**
+ * Runs VDF calculations one at a time through the worker port. The Node and Bare services manage their
+ * workers. This class queues calculations and returns results and errors in the same format.
+ */
+export class VDFService extends ReadyResource {
+    #workerPort = null;
+    #calculationQueue = Promise.resolve();
+
+    /**
+     * Sets the worker port opened by the Node or Bare service.
+     *
+     * @param {VdfWorkerPort} workerPort Worker port used by this service.
+     * @protected
+     */
+    _setPort(workerPort) {
+        this.#workerPort = workerPort;
+    }
+
+    /**
+     * Closes the worker port and waits for queued calculations to finish.
+     *
+     * @returns {Promise<void>}
+     * @protected
+     */
+    async _close() {
+        const workerPort = this.#workerPort;
+        this.#workerPort = null;
+
+        const [closeResult] = await Promise.allSettled([
+            workerPort?.close(new Error('VDF service closed')),
+            this.#calculationQueue,
+        ]);
+
+        if (closeResult.status === 'rejected') throw closeResult.reason;
+    }
+
+    /**
+     * Queues a calculation with the signed VDF parameters. Requests made after shutdown return an
+     * error without reaching the worker.
+     *
+     * @param {Buffer} challenge Encoded epoch challenge.
+     * @param {number} difficulty VDF iteration count.
+     * @param {number} discriminantSizeBits Discriminant size in bits.
+     * @returns {Promise<VdfWorkerResponse>} Response containing the result or an error.
+     */
+    async calculateVDF(challenge, difficulty, discriminantSizeBits) {
+        if (this.closing !== null || this.closed) {
+            return { error: new Error('VDF service is closed') };
+        }
+
+        const calculationPromise = this.#calculationQueue.then(() => this.#calculateWithWorker(challenge, difficulty, discriminantSizeBits));
+        this.#calculationQueue = calculationPromise.catch(() => {});
+        return calculationPromise;
+    }
+
+    /**
+     * Sends one calculation to the worker. Returns connection failures as response errors.
+     *
+     * @param {Buffer} challenge Encoded epoch challenge.
+     * @param {number} difficulty VDF iteration count.
+     * @param {number} discriminantSizeBits Discriminant size in bits.
+     * @returns {Promise<VdfWorkerResponse>} Response containing the result or an error.
+     */
+    async #calculateWithWorker(challenge, difficulty, discriminantSizeBits) {
+        const workerPort = this.#workerPort;
+        if (!workerPort) return { error: new Error('VDF service is not ready') };
+
+        try {
+            await workerPort.write({ challenge, difficulty, discriminantSizeBits });
+            return await workerPort.read();
+        } catch (error) {
+            return { error };
+        }
+    }
+}

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

@@ -0,0 +1,147 @@
+import { createVDFService } from './createVDFService.js';
+import { EpochCoordinatorOperations } from './EpochCoordinatorOperations.js';
+
+/**
+ * Manages the VDF worker and the epoch operations that use it. Opens, replaces and closes workers one
+ * at a time so config changes cannot start overlapping workers.
+ */
+export class VDFServiceManager {
+    #state;
+    #wallet;
+    #config;
+    #vdfService = null;
+    #operations = null;
+    #lifecycleQueue = Promise.resolve();
+
+    /**
+     * Creates the manager. open() starts the first VDF service.
+     *
+     * @param {import('../../state/State.js').default} state Ledger access used by epoch operations.
+     * @param {object} wallet Local proof signing identity.
+     * @param {object} config Message and network configuration.
+     */
+    constructor(state, wallet, config) {
+        this.#state = state;
+        this.#wallet = wallet;
+        this.#config = config;
+    }
+
+    /** @returns {EpochCoordinatorOperations|null} operations using the current VDF service */
+    get operations() {
+        return this.#operations;
+    }
+
+    /**
+     * Returns operations for the current VDF service. Starts a service if needed.
+     *
+     * @returns {Promise<EpochCoordinatorOperations>}
+     */
+    open() {
+        return this.#enqueueLifecycleChange(() => this.#openVdfService());
+    }
+
+    /**
+     * Closes the current VDF service and starts a new one.
+     *
+     * @returns {Promise<EpochCoordinatorOperations>}
+     */
+    replace() {
+        return this.#enqueueLifecycleChange(async () => {
+            await this.#closeVdfService();
+            return this.#openVdfService();
+        });
+    }
+
+    /**
+     * Closes the current VDF service. The manager can be opened again later.
+     *
+     * @returns {Promise<void>}
+     */
+    close() {
+        return this.#enqueueLifecycleChange(() => this.#closeVdfService());
+    }
+
+    /**
+     * Starts a VDF service and creates the operations that use it. If startup fails, closes the
+     * service before returning the error.
+     *
+     * @returns {Promise<EpochCoordinatorOperations>}
+     */
+    async #openVdfService() {
+        if (this.#operations) return this.#operations;
+        if (this.#vdfService) throw new Error('Previous VDF service is still open');
+
+        const vdfService = await createVDFService();
+
+        try {
+            await vdfService.ready();
+            const epochOperations = new EpochCoordinatorOperations(
+                this.#state,
+                vdfService,
+                this.#wallet,
+                this.#config,
+            );
+
+            this.#vdfService = vdfService;
+            this.#operations = epochOperations;
+            return epochOperations;
+        } catch (error) {
+            await this.#closeUnusedService(vdfService);
+            throw error;
+        }
+    }
+
+    /**
+     * Closes the current VDF service. If closing fails, keeps it registered so another worker cannot
+     * start while it may still be running.
+     *
+     * @returns {Promise<void>}
+     */
+    async #closeVdfService() {
+        const vdfService = this.#vdfService;
+        if (!vdfService) return;
+
+        this.#operations = null;
+
+        try {
+            await vdfService.close();
+        } catch {
+            throw new Error('Failed to close VDF service');
+        }
+
+        if (this.#vdfService === vdfService) this.#vdfService = null;
+    }
+
+    /**
+     * Closes a service that failed during startup. If closing also fails, keeps the service registered
+     * because its worker may still be running.
+     *
+     * @param {import('./VDFService.js').VDFService} vdfService Service whose startup failed.
+     * @returns {Promise<void>}
+     */
+    async #closeUnusedService(vdfService) {
+        try {
+            await vdfService.close();
+        } catch {
+            this.#vdfService = vdfService;
+            this.#operations = null;
+            throw new Error('Failed to close VDF service');
+        }
+    }
+
+    /**
+     * Runs worker startup, replacement and shutdown one at a time. An error does not block the next
+     * operation in the queue.
+     *
+     * @param {() => Promise<unknown>} lifecycleChange Worker startup, replacement or shutdown to queue.
+     * @returns {Promise<unknown>}
+     */
+    #enqueueLifecycleChange(lifecycleChange) {
+        const lifecyclePromise = this.#lifecycleQueue.then(lifecycleChange);
+
+        // Keep the internal queue usable after a failed operation.
+        this.#lifecycleQueue = lifecyclePromise.catch(() => {});
+
+        return lifecyclePromise;
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Creates the VDF service for the current runtime. Bare and Pear use separate processes. Node uses a
+ * worker thread. The caller waits for ready() before use and calls close() when the service is no
+ * longer needed.
+ *
+ * @returns {Promise<import('./VDFService.js').VDFService>} VDF service ready to be opened.
+ */
+export async function createVDFService() {
+    if (typeof globalThis.Bare !== 'undefined') {
+        const { VDFBare } = await import('./VDFBare.js');
+        return new VDFBare();
+    } else {
+        const { VDFNode } = await import('./VDFNode.js');
+        return new VDFNode();
+    }
+}

package/src/core/consensus/services/vdf-guardian.js

@@ -0,0 +1,32 @@
+import Pipe from 'bare-pipe';
+import { kill, pid } from 'bare-os';
+import { self } from 'bare-thread';
+import { VDF_PROGRESS_PHASES } from './VDFProgressWatchdog.js';
+
+// This thread never executes WASM: its event loop remains responsive while the
+// solver blocks the subprocess's main thread. EOF also works after parent SIGKILL.
+const owner = new Pipe(3);
+const die = () => kill(pid(), 'SIGKILL');
+owner.on('end', die);
+owner.on('close', die);
+owner.on('error', die);
+owner.resume();
+
+const ready = new Int32Array(self.data, 0, 1);
+const counters = new BigUint64Array(self.data, 8, VDF_PROGRESS_PHASES.length);
+let previous = VDF_PROGRESS_PHASES.map(() => '0');
+let writable = true;
+owner.on('drain', () => { writable = true; });
+
+setInterval(() => {
+    if (!writable) return;
+    const progress = previous.map((_, i) => Atomics.load(counters, i).toString());
+    if (progress.every((count, i) => count === previous[i])) return;
+    previous = progress;
+    writable = owner.write(JSON.stringify({ progress }) + '\n');
+}, 100);
+
+// Arm ownership monitoring before the main thread enters the native solver.
+owner.write(JSON.stringify({ ready: true }) + '\n');
+Atomics.store(ready, 0, 1);
+Atomics.notify(ready, 0);

package/src/core/consensus/services/vdf-worker.js

@@ -0,0 +1,90 @@
+/**
+ * Receives calculations and returns their results. Node uses workerData.port to pass binary messages.
+ * Bare reads one JSON request per line from standard input and writes the response to standard output.
+ * Solver errors are included in the response.
+ */
+import { VDF_PROGRESS_PHASES } from './VDFProgressWatchdog.js';
+const { solveWesolowski } = await import('@tracsystems/trac-vdf');
+
+/**
+ * Runs the Wesolowski solver and returns the proof with its input parameters.
+ *
+ * @param {Buffer} challenge Encoded epoch challenge.
+ * @param {number} difficulty VDF iteration count.
+ * @param {number} discriminantSizeBits Discriminant size in bits.
+ * @param {function({phase: string, completed: bigint}): void} [onProgress] Native progress observer.
+ * @returns {Promise<import('./VDFService.js').VdfWorkerResponse>}
+ */
+async function solveVdfChallenge(challenge, difficulty, discriminantSizeBits, onProgress) {
+    try {
+        const solution = await solveWesolowski(challenge, difficulty, discriminantSizeBits, { onProgress });
+        return { result: { challenge, difficulty, discriminantSizeBits, solution } };
+    } catch (error) {
+        return { error: error.message };
+    }
+}
+
+if (typeof globalThis.Bare !== 'undefined') {
+    // Runs as a standalone OS subprocess (spawned via bare-subprocess by VDFBare), not a
+    // Bare.Thread: a real solveWesolowski() call leaves native/WASM state that crashes
+    // Bare.Thread's teardown (V8's internal WASM compiler threads never rejoin cleanly), so
+    // each computation gets its own disposable process instead - see VDFBare.js.
+    const { default: Pipe } = await import('bare-pipe');
+    const { default: Thread } = await import('bare-thread');
+    const shared = new SharedArrayBuffer(8 + VDF_PROGRESS_PHASES.length * 8);
+    const ready = new Int32Array(shared, 0, 1);
+    const counters = new BigUint64Array(shared, 8, VDF_PROGRESS_PHASES.length);
+    // Keep the guardian alive for the whole disposable process. It owns fd 3.
+    const guardian = new Thread(new URL('./vdf-guardian.js', import.meta.url).href, { data: shared });
+    while (Atomics.load(ready, 0) === 0) Atomics.wait(ready, 0, 0);
+    if (guardian.joined) throw new Error('VDF guardian exited before calculation');
+    const onProgress = ({ phase, completed }) => {
+        const index = VDF_PROGRESS_PHASES.indexOf(phase);
+        if (index === -1) throw new Error(`Unknown VDF progress phase: ${phase}`);
+        Atomics.store(counters, index, completed);
+    };
+    const stdin = new Pipe(0);
+    const stdout = new Pipe(1);
+
+    let requestBuffer = '';
+    stdin.on('data', async (chunk) => {
+        requestBuffer += chunk.toString();
+        const newlineIndex = requestBuffer.indexOf('\n');
+        if (newlineIndex === -1) return;
+        stdin.pause();
+        const calculationRequest = JSON.parse(requestBuffer.slice(0, newlineIndex));
+        const calculationResponse = await solveVdfChallenge(
+            Buffer.from(calculationRequest.challenge, 'hex'),
+            calculationRequest.difficulty,
+            calculationRequest.discriminantSizeBits,
+            onProgress
+        );
+        stdout.write(JSON.stringify(encodeWorkerResponse(calculationResponse)) + '\n');
+    });
+
+    /**
+     * Converts buffers to hex so the Bare worker can send the response as JSON.
+     *
+     * @param {import('./VDFService.js').VdfWorkerResponse} calculationResponse Worker result.
+     * @returns {object} Response that can be encoded as JSON.
+     */
+    function encodeWorkerResponse(calculationResponse) {
+        if (calculationResponse.error) return { error: calculationResponse.error };
+        const { challenge, difficulty, discriminantSizeBits, solution } = calculationResponse.result;
+        return {
+            result: {
+                challenge: challenge.toString('hex'),
+                difficulty,
+                discriminantSizeBits,
+                solution: solution.toString('hex')
+            }
+        };
+    }
+} else {
+    const { workerData } = await import('worker_threads');
+    const workerPort = workerData.port;
+
+    workerPort.on('message', async (calculationRequest) => {
+        workerPort.postMessage(await solveVdfChallenge(calculationRequest.challenge, calculationRequest.difficulty, calculationRequest.discriminantSizeBits));
+    });
+}