trac-msb 0.2.24 → 0.3.0-beta.1

package/src/core/network/services/{MessageOrchestrator.js → ValidatorMessageOrchestrator.js}

@@ -4,15 +4,15 @@ import { networkMessageFactory } from "../../../messages/network/v1/networkMessa
 import { NETWORK_CAPABILITIES, ResultCode } from "../../../utils/constants.js";
 import {
     unsafeEncodeApplyOperation
-} from "../../../utils/protobuf/operationHelpers.js";
+} from "../../../codecs/apply/applyOperationCodec.js";
 import { normalizeMessageByOperationType } from "../../../utils/normalizers.js";
-import { resultToValidatorAction, SENDER_ACTION } from "../protocols/connectionPolicies.js";
-import { ConnectionManagerError } from './ConnectionManager.js';
+import { resultToValidatorAction, SENDER_ACTION } from "../protocols/validators/v1/connectionPolicies.js";
+import { isPeerConnectionError } from '../shared/PeerConnectionManager.js';
 /**
- * MessageOrchestrator coordinates message submission, retry, and validator management.
- * It works with ConnectionManager and ledger state to ensure reliable message delivery.
+ * ValidatorMessageOrchestrator coordinates message submission, retry, and validator management.
+ * It works with ValidatorConnectionManager and ledger state to ensure reliable message delivery.
  */
-class MessageOrchestrator {
+class ValidatorMessageOrchestrator {
     #config;
     #wallet;
     #idempotentSuccessCodes = new Set([
@@ -21,18 +21,14 @@ class MessageOrchestrator {
     ]);
     /**
      * Attempts to send a message to validators with retries and state checks.
-     * @param {ConnectionManager} connectionManager - The connection manager instance
+     * @param {ValidatorConnectionManager} validatorConnectionManager - The connection manager instance
      * @param {object} state - The state to look for the message outcome
      * @param {Config} config - Configuration options:
      */
-    constructor(connectionManager, state, config) {
-        this.connectionManager = connectionManager;
+    constructor(validatorConnectionManager, state, config, wallet) {
+        this.validatorConnectionManager = validatorConnectionManager;
         this.state = state;
         this.#config = config;
-        this.#wallet = null;
-    }
-
-    setWallet(wallet) {
         this.#wallet = wallet;
     }
 
@@ -50,11 +46,10 @@ class MessageOrchestrator {
      */
     #pickValidatorForMessage(message) {
         const requesterAddress = message?.address;
-        if (!requesterAddress || typeof this.connectionManager.connectedValidators !== 'function') {
-            return this.connectionManager.pickRandomConnectedValidator();
-        }
 
-        const connected = this.connectionManager.connectedValidators();
+        if (!requesterAddress) return null
+        
+        const connected = this.validatorConnectionManager.connectedPeers();
         if (!Array.isArray(connected) || connected.length === 0) {
             return null;
         }
@@ -64,9 +59,6 @@ class MessageOrchestrator {
         });
 
         const pool = eligible.length > 0 ? eligible : connected;
-        if (typeof this.connectionManager.pickRandomValidator === 'function') {
-            return this.connectionManager.pickRandomValidator(pool);
-        }
 
         const index = Math.floor(Math.random() * pool.length);
         return pool[index] ?? null;
@@ -80,7 +72,7 @@ class MessageOrchestrator {
      */
     async send(message, retries = 0) {
         if (retries > this.#config.maxRetries) {
-            console.warn(`MessageOrchestrator: Max retries reached for message ${JSON.stringify(message)}. Aborting send.`);
+            console.warn(`ValidatorMessageOrchestrator: Max retries reached for message ${JSON.stringify(message)}. Aborting send.`);
             return false;
         }
 
@@ -89,19 +81,19 @@ class MessageOrchestrator {
         console.log("Sending message to validator:", publicKeyToAddress(validatorPublicKey, this.#config));
 
         /* NOTE: Since the retry logic for Legacy is handled here, and is very unique to the protocol,
-        * it was decided to not change MessageOrchestrator send method in the refactor to make protocols transparent.
+        * it was decided to not change ValidatorMessageOrchestrator send method in the refactor to make protocols transparent.
         * As the Legacy protocol is going to be deprecated soon, it was decided to keep the retry logic 
         * here instead of abstracting it in the protocol implementation. 
-        * If we were to abstract it, we would need to add protocol-specific logic in the ProtocolSession
-        * or ProtocolInterface, which would make them less clean and more coupled with the specifics of the protocols.
+        * If we were to abstract it, we would need to add protocol-specific logic in the ValidatorProtocolSession
+        * or ValidatorProtocolInterface, which would make them less clean and more coupled with the specifics of the protocols.
         * The parts to be refactored in the future are marked with TODO comments.
         */
 
         // TODO: After Legacy is deprecated, we don't need to check preferred protocol here.
-        const validatorConnection = this.connectionManager.getConnection(validatorPublicKey);
-        const preferredProtocol = validatorConnection.protocolSession.preferredProtocol;
+        const validatorConnection = this.validatorConnectionManager.getConnection(validatorPublicKey);
+        const preferredProtocol = validatorConnection.protocolSessions.validator.preferredProtocol;
         let success = false;
-        if (preferredProtocol === validatorConnection.protocolSession.supportedProtocols.LEGACY) {
+        if (preferredProtocol === validatorConnection.protocolSessions.validator.supportedProtocols.LEGACY) {
 
             try {
                 success = await this.#attemptSendMessageForLegacy(validatorPublicKey, message);
@@ -110,10 +102,10 @@ class MessageOrchestrator {
             }
             if (!success) {
                 // Remove validator and retry
-                this.connectionManager.remove(validatorPublicKey);
+                this.validatorConnectionManager.remove(validatorPublicKey);
                 success = await this.send(message, retries + 1);
             }
-        } else if (preferredProtocol === validatorConnection.protocolSession.supportedProtocols.V1) {
+        } else if (preferredProtocol === validatorConnection.protocolSessions.validator.supportedProtocols.V1) {
             // TODO: This is probably better placed inside the V1 protocol definition.
             // Both protocols should receive a 'canonical' message and solve the encodings internally
             // Refactor 
@@ -126,7 +118,7 @@ class MessageOrchestrator {
                     NETWORK_CAPABILITIES
                 );
 
-            await this.connectionManager.sendSingleMessage(v1Message, validatorPublicKey)
+            await this.validatorConnectionManager.sendSingleMessage(v1Message, validatorPublicKey)
                 .then(
                     async (resultCode) => {
                         if (await this.#isIdempotentSuccess(resultCode, message)) {
@@ -142,19 +134,19 @@ class MessageOrchestrator {
                                 //TODO: Create a function for action below, and replace it also in legacy flow.
                                 this.incrementSentCount(validatorPublicKey);
                                 if (this.shouldRemove(validatorPublicKey)) {
-                                    this.connectionManager.remove(validatorPublicKey);
+                                    this.validatorConnectionManager.remove(validatorPublicKey);
                                 }
                                 break;
                             case SENDER_ACTION.ROTATE:
-                                this.connectionManager.remove(validatorPublicKey);
+                                this.validatorConnectionManager.remove(validatorPublicKey);
                                 break;
                             case SENDER_ACTION.NO_ROTATE:
                                 // ignore
                                 break;
                             default:
-                                this.connectionManager.remove(validatorPublicKey);
+                                this.validatorConnectionManager.remove(validatorPublicKey);
                                 console.warn(
-                                    `MessageOrchestrator: Unrecognized action from connectionPolicies: ${action}.
+                                    `ValidatorMessageOrchestrator: Unrecognized action from connectionPolicies: ${action}.
                                      ResultCode was: ${resultCode}. Removing validator ${publicKeyToAddress(validatorPublicKey, this.#config)}`
                                 );
                                 break;
@@ -163,11 +155,11 @@ class MessageOrchestrator {
                 )
                 .catch(
                     async (err) => {
-                        if (err instanceof ConnectionManagerError) {
+                        if (isPeerConnectionError(err)) {
                             success = await this.send(message, retries + 1);
-                            console.warn(`MessageOrchestrator: Connection Error: ${err.message}`);
+                            console.warn(`ValidatorMessageOrchestrator: Connection Error: ${err.message}`);
                         } else {
-                            this.connectionManager.remove(validatorPublicKey);
+                            this.validatorConnectionManager.remove(validatorPublicKey);
                             success = await this.send(message, retries + 1);
                         }
                     }
@@ -216,7 +208,7 @@ class MessageOrchestrator {
     // TODO: Delete this function after legacy protocol is deprecated
     async #attemptSendMessageForLegacy(validatorPublicKey, message) {
         const deductedTxType = operationToPayload(message.type);
-        await this.connectionManager.sendSingleMessage(message, validatorPublicKey);
+        await this.validatorConnectionManager.sendSingleMessage(message, validatorPublicKey);
         const appeared = await this.state.waitForUnsigned(
             message[deductedTxType].tx,
             this.#config.messageValidatorResponseTimeout
@@ -224,7 +216,7 @@ class MessageOrchestrator {
         if (appeared) {
             this.incrementSentCount(validatorPublicKey);
             if (this.shouldRemove(validatorPublicKey)) {
-                this.connectionManager.remove(validatorPublicKey);
+                this.validatorConnectionManager.remove(validatorPublicKey);
             }
             return true;
         }
@@ -232,12 +224,12 @@ class MessageOrchestrator {
     }
 
     incrementSentCount(validatorPubKey) {
-        this.connectionManager.incrementSentCount(validatorPubKey);
+        this.validatorConnectionManager.incrementSentCount(validatorPubKey);
     }
 
     shouldRemove(validatorPubKey) {
-        return this.connectionManager.getSentCount(validatorPubKey) >= this.#config.messageThreshold;
+        return this.validatorConnectionManager.getSentCount(validatorPubKey) >= this.#config.messageThreshold;
     }
 }
 
-export default MessageOrchestrator;
+export default ValidatorMessageOrchestrator;

package/src/core/network/services/ValidatorObserverService.js

@@ -1,4 +1,4 @@
-import Scheduler from "../../../utils/Scheduler.js";
+import SchedulableService from "../../../utils/scheduler/SchedulableService.js";
 import { Logger } from "../../../utils/logger.js";
 import b4a from "b4a";
 import { bufferToAddress } from "../../../core/state/utils/address.js";
@@ -9,18 +9,16 @@ import { WRITER_BYTE_LENGTH, CONNECTION_STATUS } from "../../../utils/constants.
 const VALIDATOR_CANDIDATES_PER_CYCLE = 10;
 const MAX_KEY_DECODE_CACHE_SIZE = 10_000;
 
-class ValidatorObserverService {
+class ValidatorObserverService extends SchedulableService {
     #network;
     #state;
     #address;
     #config;
-    #scheduler;
     #logger;
     #hasBootstrapped;    // Whether initial connection phase is complete
     #bootstrapStartedAt; // Timestamp to enforce bootstrap timeout
     #adminCache;         // Cached admin entry with TTL
     #writersCache;       // Cached writer list with dynamic TTL
-    #isInterrupted;      // Used to stop execution mid-cycle
     #keyDecodeCache;
 
     /**
@@ -30,6 +28,7 @@ class ValidatorObserverService {
      * @param {Object} config - The application configuration object.
      */
     constructor(network, state, address, config) {
+        super();
         this.#network = network;
         this.#state = state;
         this.#address = address;
@@ -39,18 +38,9 @@ class ValidatorObserverService {
         this.#bootstrapStartedAt = 0;
         this.#adminCache = { entry: null, lastUpdated: 0 };
         this.#writersCache = { list: [], lastUpdated: 0 };
-        this.#isInterrupted = false;
         this.#keyDecodeCache = new Map();
     }
 
-    /**
-     * Returns configurable poll interval.
-     * @returns {number} The poll interval in milliseconds.
-     */
-    #getPollInterval() {
-        return this.#config.pollInterval;
-    }
-    
     /**
      * Selects a subset of valid validator candidates to connect to.
      *
@@ -79,7 +69,7 @@ class ValidatorObserverService {
         const target = Math.min(networkSize, this.#config.maxValidators);
         
         const isSelfAdmin = this.#address === adminEntry?.address;
-        const totalConnected = manager.connectedValidators().length;
+        const totalConnected = manager.connectionCount();
 
         const available = writers.filter((w) => {
             if (w.address === this.#address) return false;
@@ -144,7 +134,7 @@ class ValidatorObserverService {
         // Non-admin nodes: ensure the admin is not kept as a validator connection
         const adminWriter = writers.find((w) => w.address === adminEntry?.address);
         if (adminWriter?.publicKey) {
-            this.#network.validatorConnectionManager.remove(adminWriter.publicKey, { endConnection: false });
+            this.#network.validatorConnectionManager.remove(adminWriter.publicKey);
         }
     }
 
@@ -157,7 +147,7 @@ class ValidatorObserverService {
 
         if (manager.connected(publicKey)) {
             // leave the transport to the swarm
-            manager.remove(publicKey, { endConnection: false });
+            manager.remove(publicKey);
             this.#logger.debug(`Removed stale validator connection: ${b4a.toString(publicKey, "hex")}`);
         }
     }
@@ -168,7 +158,7 @@ class ValidatorObserverService {
      * @returns {boolean} True if the observer is enabled and not interrupted.
      */
     #shouldRun() {
-        return this.#config.enableValidatorObserver && !this.#isInterrupted;
+        return !this.isInterrupted;
     }
     
     /**
@@ -214,18 +204,10 @@ class ValidatorObserverService {
             this.#logger.info('ValidatorObserverService can not start. Disabled by configuration.');
             return;
         }
-        
-        if (this.#scheduler && this.#scheduler.isRunning) {
-            this.#logger.info('ValidatorObserverService is already started');
-            return;
-        }
 
-        const interval = this.#getPollInterval();
-        this.#scheduler = new Scheduler((next) => this.#worker(next), interval);
         this.#bootstrapStartedAt = Date.now();
         this.#hasBootstrapped = false;
-        this.#isInterrupted = false;
-        this.#scheduler.start();
+        super.start();
         this.#logger.debug("ValidatorObserverService started");
     }
 
@@ -234,13 +216,9 @@ class ValidatorObserverService {
      * Prevents new work and waits for the current cycle to finish if requested.
      * @param {boolean} [waitForCurrent=true] - Whether to wait for the current worker cycle to finish.
      */
-    async stopValidatorObserver(waitForCurrent = true) {
-        if (!this.#scheduler) return;
-
-        this.#isInterrupted = true;
-
-        await this.#scheduler.stop(waitForCurrent);
-        this.#scheduler = null;
+    async stop(waitForCurrent = true) {
+        const stopped = await super.stop(waitForCurrent);
+        if (!stopped) return;
         this.#logger.debug("ValidatorObserverService stopped");
     }
 
@@ -255,9 +233,16 @@ class ValidatorObserverService {
      * 5. Attempt connections (with pacing).
      * @param {Function} next - Callback to schedule the next execution.
      */
-    async #worker(next) {
-        const interval = this.#getPollInterval();
-        if (!this.#shouldRun()) return next(interval);
+    getScheduleInterval() {
+        return this.#config.pollInterval;
+    }
+
+    async worker(next) {
+        const interval = this.#config.pollInterval;
+        if (!this.#shouldRun()) {
+            next(interval);
+            return;
+        }
 
         try {
             const adminEntry = await this.#getAdminEntryCached();

package/src/core/network/shared/BasePendingRequestService.js

@@ -0,0 +1,67 @@
+export default class BasePendingRequestService {
+    _pendingRequests = new Map();
+
+    has(id) {
+        return this._pendingRequests.has(id);
+    }
+
+    getAndDeletePendingRequest(id) {
+        const entry = this._pendingRequests.get(id);
+        if (!entry) return null;
+
+        clearTimeout(entry.timeoutId);
+        this._pendingRequests.delete(id);
+        return entry;
+    }
+
+    getPendingRequest(id) {
+        const entry = this._pendingRequests.get(id);
+        if (!entry) return null;
+        return entry;
+    }
+
+    rejectPendingRequest(id, error) {
+        const entry = this.getAndDeletePendingRequest(id);
+        if (!entry) return false;
+        entry.reject(error instanceof Error ? error : new Error(error?.message ?? 'Unexpected error'));
+        return true;
+    }
+
+    rejectPendingRequestsForPeer(peerPubKeyHex, error) {
+        const idsToReject = [];
+        for (const [id, entry] of this._pendingRequests) {
+            if (entry.requestedTo === peerPubKeyHex) idsToReject.push(id);
+        }
+
+        for (const id of idsToReject) {
+            this.rejectPendingRequest(id, error);
+        }
+
+        return idsToReject.length;
+    }
+    
+    stopPendingRequestTimeout(id) {
+        const entry = this._pendingRequests.get(id);
+        if (!entry) return false;
+
+        clearTimeout(entry.timeoutId);
+        entry.timeoutId = null;
+        return true;
+    }
+    
+    close() {
+        for (const [id, entry] of this._pendingRequests) {
+            clearTimeout(entry.timeoutId);
+            try {
+                entry.reject(this._createShutdownError(id));
+            } catch (error) {
+                console.error(`${this.constructor.name}.close: failed to reject pending request ${id}:`, error);
+            }
+        }
+        this._pendingRequests.clear();
+    }    
+    
+    _createShutdownError(id) {
+        return new Error(`Pending request ${id} cancelled (shutdown).`);
+    }
+}

package/src/core/network/shared/PeerConnectionManager.js

@@ -0,0 +1,185 @@
+import ReadyResource from "ready-resource"
+import { toHex } from "../../../utils/buffer.js";
+import { publicKeyToAddress } from "../../../utils/helpers.js";
+
+export class PeerConnectionManagerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+
+export class PeerConnectionManager extends ReadyResource {
+    _connections = new Map();
+    _max;
+
+    constructor(max, config, logger) {
+        super();
+        this._max = max;
+        this._config = config;
+        this._logger = logger
+    }
+    
+
+    setMax(maxPeers) {
+        this._max = maxPeers;
+    }
+
+    _toHexString(publicKey) {
+        return toHex(publicKey);
+    }
+
+    /**
+     * Adds a peer to the pool if not already present.
+     * @param {String | Buffer} publicKey - The public key hex string of the peer to add
+     * @param {Object} connection - The connection object associated with the peer
+     * @returns {Boolean} - Returns true if the peer was added or updated, false otherwise
+     */
+    _add(publicKey, connection) {
+        const publicKeyHex = this._toHexString(publicKey);
+        if (this.maxConnectionsReached()) {
+            this._logger.debug('add: max connections reached.');
+            return false;
+        }
+        this._logger.debug(`add: adding peer ${publicKeyToAddress(publicKeyHex, this._config)}`);
+        if (!this.exists(publicKeyHex)) {
+            this._logger.debug(`add: appending peer ${publicKeyToAddress(publicKeyHex, this._config)}`);
+            this.#append(publicKeyHex, connection);
+            return true;
+        } else if (!this.connected(publicKeyHex)) {
+            this._logger.debug(`add: updating peer ${publicKeyToAddress(publicKeyHex, this._config)}`);
+            this.#update(publicKeyHex, connection);
+            return true;
+        }
+
+        this._logger.debug(`add: didn't add peer ${publicKeyToAddress(publicKeyHex, this._config)}`);
+        return false; // TODO: Implement better success/failure reporting
+    }
+
+    /**
+     * Checks if a peer exists in the pool.
+     * @param {String | Buffer} publicKey - The public key hex string of the peer to check
+     * @returns {Boolean} - Returns true if the peer exists, false otherwise
+    */
+    exists(publicKey) {
+        const publicKeyHex = this._toHexString(publicKey);
+        return this._connections.has(publicKeyHex);
+    }
+
+    /**
+     * Checks if a peer is currently connected.
+     * @param {String | Buffer} publicKey - The public key hex string of the peer to check
+     * @returns {Boolean} - Returns true if the peer is connected, false otherwise
+     */
+    connected(publicKey) {
+        const publicKeyHex = this._toHexString(publicKey);
+        return this.exists(publicKeyHex) && this._connections.get(publicKeyHex).connection !== null;
+    }
+    
+    /**
+     * Retrieves the connection object for a given peer public key.
+     * @param {String | Buffer} publicKey - The public key (Buffer or hex string) of the peer.
+     * @returns {Connection|undefined} - The connection object if found, otherwise undefined.
+     */
+    getConnection(publicKey) {
+        const publicKeyHex = this._toHexString(publicKey);
+        const entry = this._connections.get(publicKeyHex);
+        return entry ? entry.connection : undefined;
+    }
+    
+    /**
+     * Gets a list of all currently connected peers' public keys.
+     * @returns {Array} - An array of public key hex strings of connected peers
+     */
+    connectedPeers() {
+        return Array.from(this._connections.keys()).filter(pk => this.connected(pk));
+    }
+
+    /**
+     * Gets the current number of connected peers.
+     * @returns {Number} - The count of connected peers
+     */
+    connectionCount() {
+        return this.connectedPeers().length;
+    }
+    
+    /**
+     * Checks if the maximum number of connections has been reached.
+     * @returns {Boolean} - Returns true if the maximum number of connections has been reached, false otherwise.
+     */
+    // Note: this function name is a bit misleading. It checks if we have reached max connections and returns boolean
+    // The name leads to think it returns the number of max connections
+    maxConnectionsReached() {
+        return this.connectionCount() >= this._max;
+    }
+    
+    clear() {
+        this._connections.clear()
+    }
+
+    /**
+     * Appends a new peer connection.
+     * @param {String|Buffer} publicKey - The public key hex string of the peer
+     * @param {Object} connection - The connection object
+     */
+    #append(publicKey, connection) {
+        this._logger.debug(`#append: appending peer ${publicKeyToAddress(publicKey, this._config)}`);
+        const publicKeyHex = this._toHexString(publicKey);
+        if (this._connections.has(publicKeyHex)) {
+            this._logger.debug(`#append: tried to append existing peer: ${publicKeyToAddress(publicKey, this._config)}`);
+            return;
+        }
+        this._connections.set(publicKeyHex, {connection, sent: 0});
+        connection.on('close', () => {
+            this._logger.debug(`#append: connection closing for peer ${publicKeyToAddress(publicKey, this._config)}`);
+            this.remove(publicKeyHex, connection);
+            this._logger.debug(`#append: connection closed for peer ${publicKeyToAddress(publicKey, this._config)}`);
+        });
+    }
+
+    /**
+     * Updates an existing peer connection or adds it if not present.
+     * @param {String|Buffer} publicKey - The public key hex string of the peer
+     * @param {Object} connection - The connection object
+     */
+    #update(publicKey, connection) {
+        // Note: Is there a good reason for the function 'update' to exist separately from 'append'?
+        // It seems that both could be merged into a single function that either adds or updates the entry.
+        // It would be preferable to keep them separated though, but we would need to review all usages to ensure correctness.
+        // Also, we should remove the 'else' branch below if we decide to keep 'update' and 'append' separated.
+        const publicKeyHex = this._toHexString(publicKey);
+        this._logger.debug(`#update: updating peer ${publicKeyToAddress(publicKey, this._config)}`);
+        if (this._connections.has(publicKeyHex)) {
+            this._connections.get(publicKeyHex).connection = connection;
+        } else {
+            this._connections.set(publicKeyHex, {connection, sent: 0});
+        }
+    }
+
+    /**
+     * Gets the number of messages sent through a peer.
+     * @param {String | Buffer} publicKey - The public key hex string of the peer
+     * @returns {Number} - The count of messages sent
+     */
+    getSentCount(publicKey) {
+        const publicKeyHex = this._toHexString(publicKey);
+        const entry = this._connections.get(publicKeyHex);
+        return entry ? (entry.sent || 0) : 0;
+    }
+
+    /**
+     * Increments the count of messages sent through a peer.
+     * @param {String | Buffer} publicKey - The public key hex string of the peer
+     */
+    incrementSentCount(publicKey) {
+        const publicKeyHex = this._toHexString(publicKey);
+        const entry = this._connections.get(publicKeyHex);
+        if (entry) {
+            entry.sent = (entry.sent || 0) + 1;
+        }
+    }
+}
+
+export function isPeerConnectionError(err) {
+    return (err instanceof PeerConnectionManagerError)
+}

package/src/core/state/ConfirmationWatch.js

@@ -0,0 +1,82 @@
+const DEFAULT_CHECK_INTERVAL = 15_000;
+
+/**
+ * Autobase starts a follower's fast-forward only when the network's signed length is at least
+ * 16 entries past the follower's total length, unconfirmed entries included. After a writer is
+ * removed in the middle of a batch, a follower that already holds unconfirmed entries can stay
+ * above that mark: its confirmed length then stops for good, and a restart does not help.
+ *
+ * This watch forces one fast-forward when the confirmed length has not moved for `timeout` ms
+ * while unconfirmed entries wait. It never runs on an indexer and does not change how entries are
+ * applied.
+ */
+export class ConfirmationWatch {
+    #base;
+    #timeout;
+    #interval;
+    #now;
+    #log;
+    #timer = null;
+    #mark = null;
+    #running = false;
+
+    constructor(base, { timeout, interval = DEFAULT_CHECK_INTERVAL, now = Date.now, log = console.log } = {}) {
+        this.#base = base;
+        this.#timeout = timeout;
+        this.#interval = Math.min(interval, timeout);
+        this.#now = now;
+        this.#log = log;
+    }
+
+    get enabled() {
+        return Number.isFinite(this.#timeout) && this.#timeout > 0;
+    }
+
+    start() {
+        if (!this.enabled || this.#timer !== null) return;
+        this.#timer = setInterval(() => { this.check().catch(() => {}) }, this.#interval);
+        this.#timer.unref?.();
+    }
+
+    stop() {
+        if (this.#timer !== null) clearInterval(this.#timer);
+        this.#timer = null;
+    }
+
+    /** @returns {Promise<boolean>} true when a fast-forward was forced */
+    async check() {
+        const base = this.#base;
+        if (this.#running || base.closing || base.isIndexer) return false;
+        if (base.isFastForwarding?.()) {
+            this.#mark = null;
+            return false;
+        }
+
+        const confirmed = base.view.core.signedLength;
+        const total = base.view.core.length;
+        const now = this.#now();
+
+        if (total <= confirmed) {
+            this.#mark = null;
+            return false;
+        }
+        if (this.#mark === null || this.#mark.confirmed !== confirmed) {
+            this.#mark = { confirmed, since: now };
+            return false;
+        }
+        if (now - this.#mark.since < this.#timeout) return false;
+
+        this.#running = true;
+        try {
+            this.#log(`[MSB] Confirmed length stuck at ${confirmed} (local ${total}) for ${Math.round((now - this.#mark.since) / 1000)} s; forcing a fast-forward`);
+            await base.forceFastForward();
+            this.#log(`[MSB] Fast-forward finished: confirmed ${base.view.core.signedLength}, local ${base.view.core.length}`);
+        } catch (error) {
+            this.#log(`[MSB] Fast-forward failed: ${error?.message ?? error}`);
+        } finally {
+            this.#running = false;
+            this.#mark = { confirmed: base.view.core.signedLength, since: this.#now() };
+        }
+        return true;
+    }
+}