trac-msb 0.2.5 → 0.2.7

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

@@ -1,121 +1,313 @@
-import { MAX_VALIDATORS, MAX_REQUEST_COUNT } from "../../../utils/constants.js"
+import { MAX_VALIDATORS_IN_CONNECTION_POOL } from "../../../utils/constants.js"
 import b4a from 'b4a'
 import PeerWallet from "trac-wallet"
 import { TRAC_NETWORK_MSB_MAINNET_PREFIX } from 'trac-wallet/constants.js';
 
+// -- Debug Mode --
+// TODO: Implement a better debug system in the future. This is just temporary.
+const DEBUG = false;
+const debugLog = (...args) => {
+    if (DEBUG) {
+        console.log('DEBUG [ConnectionManager] ==> ', ...args);
+    }
+};
+
 class ConnectionManager {
     #validators
-    #validatorsIndex
-    #currentValidatorIndex
-    #requestCount
     #maxValidators
 
-    constructor({ maxValidators })  {
-        this.#validators = {}
-        this.#validatorsIndex = []
-        this.#currentValidatorIndex = 0
-        this.#requestCount = 0
-        this.#maxValidators = maxValidators || MAX_VALIDATORS
+    // Note: #validators is using publicKey (Buffer) as key
+    // As Buffers are objects, we will rely on internal conversions done by JS to compare them.
+    // It would be better to handle these conversions manually by using hex strings as keys to avoid issues
+
+    constructor({ maxValidators }) {
+        this.#validators = new Map();
+        this.#maxValidators = maxValidators || MAX_VALIDATORS_IN_CONNECTION_POOL
     }
 
-    send(message, retries = 3) {
-        if (this.#requestCount >= MAX_REQUEST_COUNT) {
-            this.#requestCount = 0
-            this.#updateNext()
+    /**
+     * Sends a message to a single randomly selected connected validator.
+     * Returns the public key (buffer) of the validator used, or throws
+     * if the specified validator is unavailable.
+     * @param {Object} message - The message to send to the validator
+     * @returns {String} - The public key of the validator used
+     */
+    send(message) {
+        const connectedValidators = this.connectedValidators();
+
+        if (connectedValidators.length === 0) {
+            throw new Error('ConnectionManager: no connected validators available to send message');
         }
-        this.#requestCount++
+
+        const target = this.pickRandomValidator(connectedValidators);
+        const entry = this.#validators.get(target);
+        if (!entry || !entry.connection || !entry.connection.messenger) return null;
 
         try {
-            this.#getConnection().messenger.send(message)
-        } catch (e) { // Some retrying mechanism before reacting to close
-            if (retries > 0) {
-                this.rotate()
-                this.send(message, retries - 1)
-            }
+            entry.connection.messenger.send(message);
+            entry.sent = (entry.sent || 0) + 1;
+        } catch (e) {
+            // Swallow individual send errors.
         }
+
+        return target;
     }
 
+    /**
+     * Sends a message through a specific validator without increasing sent messages count.
+     * @param {Object} message - The message to send to the validator
+     * @param {String | Buffer} publicKey - A validator public key hex string to be fetched from the pool.
+     * @returns {Boolean} True if the message was sent, false otherwise.
+     */
+    sendSingleMessage(message, publicKey) {
+        let publicKeyHex = this.#toHexString(publicKey);
+        if (!this.exists(publicKeyHex) || !this.connected(publicKeyHex)) return false; // Fail silently
+
+        const validator = this.#validators.get(publicKeyHex);
+        if (!validator || !validator.connection || !validator.connection.messenger) return false;
+        try {
+            validator.connection.messenger.send(message);
+        } catch (e) {
+            // Swallow individual send errors.
+        }
+        return true; // TODO: Implement better success/failure reporting
+    }
+
+    /**
+     * Creates a blank entry for a validator in the pool without a connection.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator to whitelist
+     */
+    // TODO: Deprecated/Unused - remove if not needed
     whiteList(publicKey) {
-        this.#validators[publicKey] = null
+        let publicKeyHex = this.#toHexString(publicKey);
+        this.#validators.set(publicKeyHex, { connection: null, sent: 0 });
     }
 
+    /**
+     * Adds a validator to the pool if not already present.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator to add
+     * @param {Object} connection - The connection object associated with the validator
+     * @returns {Boolean} - Returns true if the validator was added or updated, false otherwise
+     */
     addValidator(publicKey, connection) {
-        if (!this.exists(publicKey) && !this.maxConnections()) {
-            return this.#append(publicKey, connection)
-        } else if (!this.connected(publicKey)) {
-            return this.#update(publicKey, connection)
+        let publicKeyHex = this.#toHexString(publicKey);
+        if (this.maxConnectionsReached()) {
+            debugLog(`addValidator: max connections reached.`);
+            return false;
         }
-
-        return false
+        debugLog(`addValidator: adding validator ${this.#toAddress(publicKeyHex)}`);
+        if (!this.exists(publicKeyHex)) {
+            debugLog(`addValidator: appending validator ${this.#toAddress(publicKeyHex)}`);
+            this.#append(publicKeyHex, connection);
+            return true;
+        } else if (!this.connected(publicKeyHex)) {
+            debugLog(`addValidator: updating validator ${this.#toAddress(publicKeyHex)}`);
+            this.#update(publicKeyHex, connection);
+            return true;
+        }
+        debugLog(`addValidator: didn't add validator ${this.#toAddress(publicKeyHex)}`);
+        return false; // TODO: Implement better success/failure reporting
     }
 
+    /**
+     * Removes a validator from the pool.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator to remove
+     */
     remove(publicKey) {
-        const index = this.#validatorsIndex.findIndex(current => b4a.equals(publicKey, current));
-        if (index !== -1) {
-            this.#validatorsIndex.splice(index, 1);
-            delete this.#validators[publicKey]
+        debugLog(`remove: removing validator ${this.#toAddress(publicKey)}`);
+        const publicKeyHex = this.#toHexString(publicKey);
+        if (this.exists(publicKeyHex)) {
+            // Close the connection socket
+            const entry = this.#validators.get(publicKeyHex);
+            if (entry && entry.connection && typeof entry.connection.end === 'function') {
+                try {
+                    entry.connection.end();
+                } catch (e) {
+                    // Ignore errors on connection end
+                    // TODO: Consider logging these errors here in verbose mode
+                }
+            }
+            debugLog(`remove: removing validator from map: ${this.#toAddress(publicKeyHex)}. Map size before removal: ${this.#validators.size}.`);
+            this.#validators.delete(publicKeyHex);
+            debugLog(`remove: validator removed successfully. Map size is now ${this.#validators.size}.`);
         }
     }
 
-    maxConnections() {
+    /**
+     * 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.#maxValidators
     }
 
+    /**
+     * Gets a list of all currently connected validators' public keys.
+     * @returns {Array} - An array of public key hex strings of connected validators
+     */
+    connectedValidators() {
+        return Array.from(this.#validators.keys()).filter(pk => this.connected(pk));
+    }
+
+    /**
+     * Gets the current number of connected validators.
+     * @returns {Number} - The count of connected validators
+     */
     connectionCount() {
-        return this.#validatorsIndex.filter(_ => this.connected(_)).length
+        return this.connectedValidators().length;
     }
 
+    /**
+     * Checks if a validator is currently connected.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator to check
+     * @returns {Boolean} - Returns true if the validator is connected, false otherwise
+     */
     connected(publicKey) {
-        return this.exists(publicKey) && this.#validators[publicKey]?.connected
+        const publicKeyHex = this.#toHexString(publicKey);
+        return this.exists(publicKeyHex) && this.#validators.get(publicKeyHex).connection !== null;
     }
 
-    rotate() {
-        this.#updateNext()
-        this.#requestCount = 0
+    /**
+     * Checks if a validator exists in the pool.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator to check
+     * @returns {Boolean} - Returns true if the validator exists, false otherwise
+     */
+    exists(publicKey) {
+        const publicKeyHex = this.#toHexString(publicKey);
+        return this.#validators.has(publicKeyHex);
     }
 
-    exists(publicKey) {
-        return !!this.#validators[publicKey]
+    /**
+     * Gets the number of messages sent through a validator.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator
+     * @returns {Number} - The count of messages sent
+     */
+    getSentCount(publicKey) {
+        const publicKeyHex = this.#toHexString(publicKey);
+        const entry = this.#validators.get(publicKeyHex);
+        return entry ? (entry.sent || 0) : 0;
+    }
+
+    /**
+     * Increments the count of messages sent through a validator.
+     * @param {String | Buffer} publicKey - The public key hex string of the validator
+     */
+    incrementSentCount(publicKey) {
+        const publicKeyHex = this.#toHexString(publicKey);
+        const entry = this.#validators.get(publicKeyHex);
+        if (entry) {
+            entry.sent = (entry.sent || 0) + 1;
+        }
     }
 
     prettyPrint() {
         console.log('Connection count: ', this.connectionCount())
-        console.log('Current connection: ', this.#currentValidator())
-        console.log('Validators: ', this.#validatorsIndex.map(val => PeerWallet.encodeBech32m(TRAC_NETWORK_MSB_MAINNET_PREFIX, val)))
+        console.log('Validator map keys count: ', this.#validators.size)
+        console.log('Validator map keys: ', Array.from(this.#validators.keys()).map(val => this.#toAddress(val)).join(', '))
     }
 
-    #currentValidator() {
-        return this.#validatorsIndex[this.#currentValidatorIndex]
+    // Note 1: This method shuffles the whole array (in practice, probably around 50 elements)
+    //      just to fetch a small subset of it (most times, 1 element).
+    //      There are more efficient ways to pick a small subset of validators. Consider optimizing.
+    // Note 2: This method is unused now, but will be kept here for future reference
+    // TODO: Deprecated/Unused - remove if not needed
+    pickRandomSubset(validators, maxTargets) {
+        const copy = validators.slice();
+        const count = Math.min(maxTargets, copy.length);
+
+        for (let i = copy.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [copy[i], copy[j]] = [copy[j], copy[i]];
+        }
+
+        return copy.slice(0, count);
     }
 
-    #getConnection() {
-        return this.#validators[this.#currentValidator()]
+    /**
+     * Picks a random validator from the given array of validator public keys.
+     * @param {String[]} validatorPubKeys - An array of validator public key hex strings
+     * @returns {String|null} - A randomly selected validator public key
+     */
+    pickRandomValidator(validatorPubKeys) {
+        if (validatorPubKeys.length === 0) {
+            return null;
+        }
+        const index = Math.floor(Math.random() * validatorPubKeys.length);
+        return validatorPubKeys[index];
     }
 
-    #append(publicKey, connection) {
-        this.#validatorsIndex.push(publicKey)
-        this.#validators[publicKey] = connection
+    /**
+     * Picks a random connected validator.
+     * @returns {String|null} - A randomly selected connected validator public key, or null if none are connected
+     */
+    pickRandomConnectedValidator() {
+        const connected = this.connectedValidators();
+        if (connected.length === 0) return null;
+        return this.pickRandomValidator(connected);
+    }
 
+    /**
+     * Appends a new validator connection.
+     * @param {String|Buffer} publicKey - The public key hex string of the validator
+     * @param {Object} connection - The connection object
+     */
+    #append(publicKey, connection) {
+        debugLog(`#append: appending validator ${this.#toAddress(publicKey)}`);
+        const publicKeyHex = this.#toHexString(publicKey);
+        if (this.#validators.has(publicKeyHex)) {
+            // This should never happen, but just in case, we log it
+            debugLog(`#append: tried to append existing validator: ${this.#toAddress(publicKey)}`);
+            return;
+        }
+        this.#validators.set(publicKeyHex, { connection, sent: 0 });
         connection.on('close', () => {
-            if (this.#isRemoteEqual(publicKey)) {
-                this.remove(publicKey)
-            }
-        })
+            debugLog(`#append: connection closing for validator ${this.#toAddress(publicKey)}`);
+            this.remove(publicKeyHex);
+            debugLog(`#append: connection closed for validator ${this.#toAddress(publicKey)}`);
+        });
     }
 
+    /**
+     * Updates an existing validator connection or adds it if not present.
+     * @param {String|Buffer} publicKey - The public key hex string of the validator
+     * @param {Object} connection - The connection object
+     */
     #update(publicKey, connection) {
-        this.#validators[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);
+        debugLog(`#update: updating validator ${this.#toAddress(publicKey)}`);
+        if (this.#validators.has(publicKeyHex)) {
+            this.#validators.get(publicKeyHex).connection = connection;
+        } else {
+            this.#validators.set(publicKeyHex, { connection, sent: 0 });
+        }
     }
 
-    #updateNext() {
-        const next = this.#currentValidatorIndex + 1
-        this.#currentValidatorIndex = next < this.#validatorsIndex.length ? next : 0
+    #evictRandomValidator() {
+        const connected = this.connectedValidators();
+        if (connected.length === 0) return;
+
+        const idx = Math.floor(Math.random() * connected.length);
+        const toRemove = connected[idx];
+        this.remove(toRemove);
     }
 
+    #toAddress(publicKey) {
+        const keyHex = b4a.isBuffer(publicKey) ? publicKey : b4a.from(publicKey, 'hex');
+        return PeerWallet.encodeBech32m(
+            TRAC_NETWORK_MSB_MAINNET_PREFIX, // TODO: This won't work for other networks. Make it dynamic after configuration is available.
+            keyHex
+        );
+    }
 
-    #isRemoteEqual(publicKey) {
-        return !!publicKey && !!this.#validators[publicKey]?.remotePublicKey && b4a.equals(this.#validators[publicKey]?.remotePublicKey, publicKey)
+    #toHexString(publicKey) {
+        return b4a.isBuffer(publicKey) ? publicKey.toString('hex') : publicKey;
     }
 }
 
-export default ConnectionManager;
+export default ConnectionManager;

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

@@ -0,0 +1,95 @@
+import { sleep } from '../../../utils/helpers.js';
+import {
+    MAX_MESSAGE_SEND_ATTEMPTS,
+    MAX_SUCCESSIVE_MESSAGES_PER_VALIDATOR,
+    MESSAGE_VALIDATOR_RESPONSE_TIMEOUT_MS,
+    MESSAGE_VALIDATOR_RETRY_DELAY_MS
+} from '../../../utils/constants.js';
+
+/**
+ * MessageOrchestrator coordinates message submission, retry, and validator management.
+ * It works with ConnectionManager and ledger state to ensure reliable message delivery.
+ */
+class MessageOrchestrator {
+    /**
+     * Attempts to send a message to validators with retries and state checks.
+     * @param {ConnectionManager} connectionManager - The connection manager instance
+     * @param {object} state - The state to look for the message outcome
+     * @param {object} options - { messageThreshold: number, maxRetries: number, retryDelay: number (milliseconds), timeout: number (milliseconds) }
+     * messageThreshold: How many successful sends before removing a validator from the pool
+     * maxRetries: How many times to retry sending a message to a single validator
+     * retryDelay: How long to wait between retries (ms)
+     * timeout: Overall timeout for sending a message (ms)
+     */
+    constructor(connectionManager, state, options = {}) {
+        this.connectionManager = connectionManager;
+        this.state = state;
+        // TODO: Adjust these default values or fetch them from config
+        this.messageThreshold = options.messageThreshold || MAX_SUCCESSIVE_MESSAGES_PER_VALIDATOR;
+        this.maxRetries = options.maxRetries || MAX_MESSAGE_SEND_ATTEMPTS; // Amount of retries for a single validator
+        this.retryDelay = options.retryDelay || MESSAGE_VALIDATOR_RETRY_DELAY_MS; // How long to wait before retrying (ms)
+        this.timeout = options.timeout || MESSAGE_VALIDATOR_RESPONSE_TIMEOUT_MS; // Overall timeout for sending a message (ms)
+    }
+
+    /**
+     * Sends a message to a single randomly selected connected validator.
+     * @param {object} message - The message object to be sent
+     * @returns {Promise<boolean>} - true if successful, false otherwise
+     */
+    async send(message) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < this.timeout) {
+            const validator = this.connectionManager.pickRandomConnectedValidator();
+            if (!validator) return false;
+
+            const success = await this.#attemptSendMessage(validator, message);
+            if (success) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    async #attemptSendMessage(validator, message) {
+        let attempts = 0;
+        while (attempts < this.maxRetries) {
+            this.connectionManager.sendSingleMessage(message, validator);
+
+            const appeared = await this.waitForUnsignedState(message.tro.tx, this.retryDelay);
+            if (appeared) {
+                this.incrementSentCount(validator);
+                if (this.shouldRemove(validator)) {
+                    this.connectionManager.remove(validator);
+                }
+                return true;
+            }
+            attempts++;
+        }
+
+        // If all retries fail, remove validator from pool
+        this.connectionManager.remove(validator);
+        return false;
+    }
+
+    async waitForUnsignedState(txHash, timeout) {
+        // Polls state for the transaction hash for up to timeout ms
+        const start = Date.now();
+        let entry = null;
+        while (Date.now() - start < timeout) {
+            await sleep(200);
+            entry = await this.state.get(txHash)
+            if (entry) return true;
+        }
+        return false;
+    }
+
+    incrementSentCount(validatorPubKey) {
+        this.connectionManager.incrementSentCount(validatorPubKey);
+    }
+
+    shouldRemove(validatorPubKey) {
+        return this.connectionManager.getSentCount(validatorPubKey) >= this.messageThreshold;
+    }
+}
+
+export default MessageOrchestrator;

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

@@ -8,6 +8,15 @@ import Scheduler from "../../../utils/Scheduler.js";
 const POLL_INTERVAL = 3500 // This was increase since the iterations dont wait for the execution its about 10 * DELAY_INTERVAL
 const DELAY_INTERVAL = 250
 
+// -- Debug Mode --
+// TODO: Implement a better debug system in the future. This is just temporary.
+const DEBUG = false;
+const debugLog = (...args) => {
+    if (DEBUG) {
+        console.log('DEBUG [ValidatorObserverService] ==> ', ...args);
+    }
+};
+
 class ValidatorObserverService {
     #enable_validator_observer;
     #state;
@@ -55,36 +64,65 @@ class ValidatorObserverService {
     }
 
     async #worker(next) {
-        if (!this.#network.validatorConnectionManager.maxConnections()) {
+        if (!this.#network.validatorConnectionManager.maxConnectionsReached()) {
             const length = await this.#lengthEntry()
 
             const promises = [];
             for (let i = 0; i < 10; i++) {
-                promises.push(this.#findValidator(this.#address, length));
+                promises.push(this.#findValidator(this.#address, length + 1));
                 await sleep(DELAY_INTERVAL); // Low key dangerous as the network progresses
             }
             await Promise.all(promises);
+
+            next(POLL_INTERVAL)
         }
-        next(POLL_INTERVAL)
     }
 
-    async #findValidator(address, length) {
-        if (this.#network.validatorConnectionManager.maxConnections() || !this.#shouldRun()) return;
+    async #findValidator(address, validatorListLength) {
+        if (!this.#shouldRun()) return;
+        const maxAttempts = 50; // TODO: make configurable
+        let attempts = 0;
+        let isValidatorValid = false;
+        let validatorAddressBuffer = b4a.alloc(0);
+
+        while (attempts < maxAttempts && !isValidatorValid) {
+            const rndIndex = Math.floor(Math.random() * validatorListLength);
+            validatorAddressBuffer = await this.state.getWriterIndex(rndIndex);
+            isValidatorValid = await this.#isValidatorValid(address, validatorAddressBuffer, validatorListLength);
+            attempts++;
+        }
 
-        const rndIndex = Math.floor(Math.random() * length);
-        const validatorAddressBuffer = await this.state.getWriterIndex(rndIndex);
+        if (attempts >= maxAttempts) {
+            debugLog('Max attempts reached without finding a valid validator.');
+        }
+        else {
+            debugLog(`Found valid validator to connect after ${attempts} attempts.`);
+        }
+        
+        if (!isValidatorValid) return;
+        
+        const validatorAddress = bufferToAddress(validatorAddressBuffer);
+        const validatorPubKeyBuffer = PeerWallet.decodeBech32m(validatorAddress);
+        const validatorPubKeyHex = validatorPubKeyBuffer.toString('hex');
+        const adminEntry = await this.state.getAdminEntry();
 
-        if (validatorAddressBuffer === null || b4a.byteLength(validatorAddressBuffer) !== TRAC_ADDRESS_SIZE) return;
 
+        if (validatorAddress !== adminEntry?.address || validatorListLength < MAX_WRITERS_FOR_ADMIN_INDEXER_CONNECTION) {
+            await this.#network.tryConnect(validatorPubKeyHex, 'validator');
+        }
+    };
+
+    async #isValidatorValid(forbiddenAddress, validatorAddressBuffer, validatorListLength) {
+        if (validatorAddressBuffer === null || b4a.byteLength(validatorAddressBuffer) !== TRAC_ADDRESS_SIZE) return false;
+        
         const validatorAddress = bufferToAddress(validatorAddressBuffer);
-        if (validatorAddress === address) return;
+        if (validatorAddress === forbiddenAddress) return false;
 
-        const validatorPubKey = PeerWallet.decodeBech32m(validatorAddress).toString('hex');
+        const validatorPubKeyBuffer = PeerWallet.decodeBech32m(validatorAddress);
         const validatorEntry = await this.state.getNodeEntry(validatorAddress);
         const adminEntry = await this.state.getAdminEntry();
 
-        if (validatorAddress === adminEntry?.address && length >= MAX_WRITERS_FOR_ADMIN_INDEXER_CONNECTION) {
-            const validatorPubKeyBuffer = b4a.from(validatorPubKey, 'hex')
+        if (validatorAddress === adminEntry?.address && validatorListLength >= MAX_WRITERS_FOR_ADMIN_INDEXER_CONNECTION) {
             if (this.#network.validatorConnectionManager.exists(validatorPubKeyBuffer)) {
                 this.#network.validatorConnectionManager.remove(validatorPubKeyBuffer)
             }
@@ -95,19 +133,17 @@ class ValidatorObserverService {
         // - Validator must exist and be a writer
         // - Cannot connect to indexers, except for admin-indexer
         // - Admin-indexer connection is allowed only when writers length has less than 10 writers
-        if (
-            this.#network.validatorConnectionManager.connected(validatorPubKey) ||
+        if (this.#network.validatorConnectionManager.connected(validatorPubKeyBuffer) ||
+            this.#network.validatorConnectionManager.maxConnectionsReached() ||
             validatorEntry === null ||
             !validatorEntry.isWriter ||
-            (validatorEntry.isIndexer && (validatorAddress !== adminEntry?.address || length >= MAX_WRITERS_FOR_ADMIN_INDEXER_CONNECTION))
+            (validatorEntry.isIndexer && (validatorAddress !== adminEntry?.address || validatorListLength >= MAX_WRITERS_FOR_ADMIN_INDEXER_CONNECTION))
         ) {
-            return;
+            return false;
         }
 
-        if (validatorAddress !== adminEntry?.address || length < MAX_WRITERS_FOR_ADMIN_INDEXER_CONNECTION) {
-            await this.#network.tryConnect(validatorPubKey, 'validator');
-        }
-    };
+        return true;
+    }
 
     #shouldRun() {
         if (!this.#enable_validator_observer || this.#isInterrupted) {