trac-msb 0.2.6 → 0.2.8

package/src/core/network/messaging/validators/base/PartialOperation.js

@@ -1,13 +1,11 @@
 import b4a from 'b4a';
 import PeerWallet from 'trac-wallet';
-
 import Check from '../../../../../utils/check.js';
-import { bufferToAddress } from "../../../../state/utils/address.js";
-import { createMessage } from "../../../../../utils/buffer.js";
-import { OperationType, NETWORK_ID } from "../../../../../utils/constants.js";
-import { blake3Hash } from "../../../../../utils/crypto.js";
-import { bufferToBigInt } from "../../../../../utils/amountSerialization.js";
-import { FEE } from "../../../../state/utils/transaction.js";
+import {bufferToAddress} from "../../../../state/utils/address.js";
+import {createMessage} from "../../../../../utils/buffer.js";
+import {OperationType} from "../../../../../utils/constants.js";
+import {bufferToBigInt} from "../../../../../utils/amountSerialization.js";
+import {FEE} from "../../../../state/utils/transaction.js";
 import * as operationsUtils from '../../../../../utils/operations.js';
 
 const MAX_AMOUNT = BigInt('0xffffffffffffffffffffffffffffffff');
@@ -17,12 +15,16 @@ const PUBLIC_KEY_LENGTH = 32;
 class PartialOperation {
     #state;
     #check;
+    #config
+    #wallet
 
-    constructor(state) {
+    constructor(state, wallet, config) {
         this.#state = state;
-        this.#check = new Check();
+        this.#config = config;
+        this.#check = new Check(this.#config);
         this.max_amount = MAX_AMOUNT;
         this.fee = FEE_BIGINT;
+        this.#wallet = wallet;
     }
 
     get state() {
@@ -33,7 +35,9 @@ class PartialOperation {
         return this.#check;
     }
 
-    async validate(payload) { throw new Error("Method 'validate()' must be implemented."); }
+    async validate(payload) {
+        throw new Error("Method 'validate()' must be implemented.");
+    }
 
     isPayloadSchemaValid(payload) {
         if (!payload || !payload.type) {
@@ -65,7 +69,7 @@ class PartialOperation {
     }
 
     validateRequesterAddress(payload) {
-        const incomingAddress = bufferToAddress(payload.address);
+        const incomingAddress = bufferToAddress(payload.address, this.#config.addressPrefix);
         if (!incomingAddress) {
             throw new Error('Invalid requesting address in payload.');
         }
@@ -87,7 +91,7 @@ class PartialOperation {
             case OperationType.REMOVE_WRITER:
             case OperationType.ADMIN_RECOVERY:
                 return [
-                    NETWORK_ID,
+                    this.#config.networkId,
                     operation.txv,
                     operation.iw,
                     operation.in,
@@ -95,7 +99,7 @@ class PartialOperation {
                 ];
             case OperationType.BOOTSTRAP_DEPLOYMENT:
                 return [
-                    NETWORK_ID,
+                    this.#config.networkId,
                     operation.txv,
                     operation.bs,
                     operation.ic,
@@ -104,7 +108,7 @@ class PartialOperation {
                 ];
             case OperationType.TX:
                 return [
-                    NETWORK_ID,
+                    this.#config.networkId,
                     operation.txv,
                     operation.iw,
                     operation.ch,
@@ -115,7 +119,7 @@ class PartialOperation {
                 ];
             case OperationType.TRANSFER:
                 return [
-                    NETWORK_ID,
+                    this.#config.networkId,
                     operation.txv,
                     operation.to,
                     operation.am,
@@ -131,12 +135,12 @@ class PartialOperation {
         const operationKey = operationsUtils.operationToPayload(payload.type);
         const operation = payload[operationKey];
 
-        const incomingPublicKey = PeerWallet.decodeBech32mSafe(bufferToAddress(payload.address));
+        const incomingPublicKey = PeerWallet.decodeBech32mSafe(bufferToAddress(payload.address, this.#config.addressPrefix));
         const incomingSignature = operation.is;
         const messageComponents = this.#getMessageComponents(payload);
 
         const message = createMessage(...messageComponents);
-        const messageHash = await blake3Hash(message);
+        const messageHash = await PeerWallet.blake3(message);
         const payloadHash = operation.tx;
         if (!b4a.equals(payloadHash, messageHash)) {
             throw new Error('Regenerated transaction does not match incoming transaction in payload.');
@@ -172,16 +176,16 @@ class PartialOperation {
     isOperationNotCompleted(payload) {
         const operationKey = operationsUtils.operationToPayload(payload.type);
         const operation = payload[operationKey];
-        const { va, vn, vs } = operation;
+        const {va, vn, vs} = operation;
 
-        const condition = !!(va === undefined && vn === undefined && vs === undefined);
+        const condition = va === undefined && vn === undefined && vs === undefined
         if (!condition) {
             throw new Error('Transfer operation must not be completed already (va, vn, vs must be undefined).');
         }
     }
 
     async validateRequesterBalance(payload, signed = false) {
-        const requesterAddress = bufferToAddress(payload.address);
+        const requesterAddress = bufferToAddress(payload.address, this.#config.addressPrefix);
         let requesterEntry;
         if (signed) {
             requesterEntry = await this.state.getNodeEntry(requesterAddress);
@@ -204,11 +208,23 @@ class PartialOperation {
         const operationKey = operationsUtils.operationToPayload(payload.type);
         const operation = payload[operationKey];
         const bs = operation.bs;
-        if (b4a.equals(this.state.bootstrap, bs)) {
+        if (b4a.equals(this.#config.bootstrap, bs)) {
             throw new Error(`External bootstrap is the same as MSB bootstrap: ${bs.toString('hex')}`);
         }
     }
 
+    /*
+     * Guard against self-validation (RPC/orchestrator loop): a validator may receive its own submitted tx for validation.
+     * Even if unlikely, this must be rejected to avoid incorrect failures/punishments.
+     * Flow: Validator -> submits tx with tap-wallet -> RPC-> Validator -validates tx-> REJECT (self-validation)
+     */
+    validateNoSelfValidation(payload) {
+        const requesterAddress = bufferToAddress(payload.address, this.#config.addressPrefix);
+        if (this.#wallet.address === requesterAddress) {
+            throw new Error('Requester address cannot be the same as the validator wallet address.');
+        }
+    }
+
 }
 
 export default PartialOperation;

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

@@ -1,121 +1,307 @@
-import { MAX_VALIDATORS, MAX_REQUEST_COUNT } 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
+    #config
 
-    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
+    /**
+     * @param {object} config
+     **/
+    constructor(config)  {
+        this.#validators = new Map();
+        this.#config = config
+        this.#maxValidators = config.maxValidators
     }
 
-    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(', '))
+    }
+
+    // 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);
     }
 
-    #currentValidator() {
-        return this.#validatorsIndex[this.#currentValidatorIndex]
+    /**
+     * 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];
     }
 
-    #getConnection() {
-        return this.#validators[this.#currentValidator()]
+    /**
+     * 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) {
-        this.#validatorsIndex.push(publicKey)
-        this.#validators[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
+    #toAddress(publicKey) {
+        const keyHex = b4a.isBuffer(publicKey) ? publicKey : b4a.from(publicKey, 'hex');
+        return PeerWallet.encodeBech32m(
+            this.#config.addressPrefix,
+            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,83 @@
+import { sleep } from '../../../utils/helpers.js';
+import { operationToPayload } from '../../../utils/operations.js';
+/**
+ * MessageOrchestrator coordinates message submission, retry, and validator management.
+ * It works with ConnectionManager and ledger state to ensure reliable message delivery.
+ */
+class MessageOrchestrator {
+    #config;
+    /**
+     * 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} config - Configuration options:
+     */
+    constructor(connectionManager, state, config) {
+        this.connectionManager = connectionManager;
+        this.state = state;
+        this.#config = config;
+    }
+
+    /**
+     * 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.#config.messageValidatorResponseTimeout) {
+            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;
+        const deductedTxType = operationToPayload(message.type);
+        while (attempts <= this.#config.maxRetries) {
+            this.connectionManager.sendSingleMessage(message, validator);
+
+            const appeared = await this.waitForUnsignedState(message[deductedTxType].tx, this.#config.messageValidatorRetryDelay);
+            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.#config.messageThreshold;
+    }
+}
+
+export default MessageOrchestrator;

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

@@ -5,14 +5,19 @@ import Scheduler from '../../../utils/Scheduler.js';
 class TransactionPoolService {
     #state;
     #address;
-    #options;
+    #config;
     #tx_pool = [];
     #scheduler = null;
 
-    constructor(state, address, options = {}) {
+    /**
+     * @param {State} state
+     * @param {string} address
+     * @param {object} config
+     **/
+    constructor(state, address, config) {
         this.#state = state;
         this.#address = address;
-        this.#options = options;
+        this.#config = config;
     }
 
     get tx_pool() {
@@ -27,12 +32,8 @@ class TransactionPoolService {
         return this.#address;
     }
 
-    get options() {
-        return this.#options;
-    }
-
     async start() {
-        if (!this.options.enable_wallet) {
+        if (!this.#config.enableWallet) {
             console.info('TransactionPoolService can not start. Wallet is not enabled');
             return;
         }