trac-msb 0.2.17 → 0.2.19

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

@@ -1,11 +1,24 @@
-import { sleep } from '../../../utils/helpers.js';
+import { generateUUID, publicKeyToAddress } from '../../../utils/helpers.js';
 import { operationToPayload } from '../../../utils/applyOperations.js';
+import { networkMessageFactory } from "../../../messages/network/v1/networkMessageFactory.js";
+import { NETWORK_CAPABILITIES, ResultCode } from "../../../utils/constants.js";
+import {
+    unsafeEncodeApplyOperation
+} from "../../../utils/protobuf/operationHelpers.js";
+import { normalizeMessageByOperationType } from "../../../utils/normalizers.js";
+import { resultToValidatorAction, SENDER_ACTION } from "../protocols/connectionPolicies.js";
+import { ConnectionManagerError } from './ConnectionManager.js';
 /**
  * MessageOrchestrator coordinates message submission, retry, and validator management.
  * It works with ConnectionManager and ledger state to ensure reliable message delivery.
  */
 class MessageOrchestrator {
     #config;
+    #wallet;
+    #idempotentSuccessCodes = new Set([
+        ResultCode.TX_ALREADY_EXISTS,
+        ResultCode.OPERATION_ALREADY_COMPLETED,
+    ]);
     /**
      * Attempts to send a message to validators with retries and state checks.
      * @param {ConnectionManager} connectionManager - The connection manager instance
@@ -16,57 +29,204 @@ class MessageOrchestrator {
         this.connectionManager = connectionManager;
         this.state = state;
         this.#config = config;
+        this.#wallet = null;
+    }
+
+    setWallet(wallet) {
+        this.#wallet = wallet;
+    }
+
+    /**
+     * Picks a validator for an outgoing message while avoiding requester self-validation.
+     *
+     * ValidatorObserverService already prevents connecting to the local node itself.
+     * This method handles a different case: for a given message, we avoid selecting
+     * a validator whose address equals `message.address` (requester), because
+     * validator-side checks reject that flow.
+     *
+     * @param {object} [message] Outgoing operation payload.
+     * @param {string} [message.address] Requester address (bech32m).
+     * @returns {string|null} Selected validator public key hex, or null when unavailable.
+     */
+    #pickValidatorForMessage(message) {
+        const requesterAddress = message?.address;
+        if (!requesterAddress || typeof this.connectionManager.connectedValidators !== 'function') {
+            return this.connectionManager.pickRandomConnectedValidator();
+        }
+
+        const connected = this.connectionManager.connectedValidators();
+        if (!Array.isArray(connected) || connected.length === 0) {
+            return null;
+        }
+
+        const eligible = connected.filter((publicKey) => {
+            return publicKeyToAddress(publicKey, this.#config) !== requesterAddress;
+        });
+
+        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;
     }
 
     /**
      * Sends a message to a single randomly selected connected validator.
      * @param {object} message - The message object to be sent
+     * @param retries - The current retry count for this message
      * @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;
-            }
+    async send(message, retries = 0) {
+        if (retries > this.#config.maxRetries) {
+            console.warn(`MessageOrchestrator: Max retries reached for message ${JSON.stringify(message)}. Aborting send.`);
+            return false;
         }
-        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;
+        const validatorPublicKey = this.#pickValidatorForMessage(message);
+        if (!validatorPublicKey) return false;
+        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.
+        * 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.
+        * 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;
+        let success = false;
+        if (preferredProtocol === validatorConnection.protocolSession.supportedProtocols.LEGACY) {
+
+            try {
+                success = await this.#attemptSendMessageForLegacy(validatorPublicKey, message);
+            } catch {
+                success = await this.send(message, retries + 1);
+            }
+            if (!success) {
+                // Remove validator and retry
+                this.connectionManager.remove(validatorPublicKey);
+                success = await this.send(message, retries + 1);
             }
-            attempts++;
+        } else if (preferredProtocol === validatorConnection.protocolSession.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 
+            const normalizedMessage = normalizeMessageByOperationType(message, this.#config)
+            const encodedTransaction = unsafeEncodeApplyOperation(normalizedMessage)
+            const v1Message = await networkMessageFactory(this.#wallet, this.#config)
+                .buildBroadcastTransactionRequest(
+                    generateUUID(),
+                    encodedTransaction,
+                    NETWORK_CAPABILITIES
+                );
+
+            await this.connectionManager.sendSingleMessage(v1Message, validatorPublicKey)
+                .then(
+                    async (resultCode) => {
+                        if (await this.#isIdempotentSuccess(resultCode, message)) {
+                            success = true;
+                            return;
+                        }
+
+                        // TODO: When we will deprecate the legacy protocol, we should refactor this scope, to propagate domain-error with result code.
+                        const action = resultToValidatorAction(resultCode);
+                        switch (action) {
+                            case SENDER_ACTION.SUCCESS:
+                                success = true;
+                                //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);
+                                }
+                                break;
+                            case SENDER_ACTION.ROTATE:
+                                this.connectionManager.remove(validatorPublicKey);
+                                break;
+                            case SENDER_ACTION.NO_ROTATE:
+                                // ignore
+                                break;
+                            default:
+                                this.connectionManager.remove(validatorPublicKey);
+                                console.warn(
+                                    `MessageOrchestrator: Unrecognized action from connectionPolicies: ${action}.
+                                     ResultCode was: ${resultCode}. Removing validator ${publicKeyToAddress(validatorPublicKey, this.#config)}`
+                                );
+                                break;
+                        }
+                    }
+                )
+                .catch(
+                    async (err) => {
+                        if (err instanceof ConnectionManagerError) {
+                            success = await this.send(message, retries + 1);
+                            console.warn(`MessageOrchestrator: Connection Error: ${err.message}`);
+                        } else {
+                            this.connectionManager.remove(validatorPublicKey);
+                            success = await this.send(message, retries + 1);
+                        }
+                    }
+                )
+
         }
+        return success;
+    }
 
-        // If all retries fail, remove validator from pool
-        this.connectionManager.remove(validator);
-        return false;
+    /**
+     * Determines whether a non-OK result code should be treated as a success due to idempotency.
+     *
+     * This handles the retry scenario where a requester did not receive or accept the response
+     * from the first validator that committed the transaction. On retry, a second validator may
+     * return TX_ALREADY_EXISTS or OPERATION_ALREADY_COMPLETED because the tx was already
+     * processed. Those codes are not errors — they confirm the operation succeeded.
+     *
+     * To safely treat these as success, we check whether the local unsigned state for the tx
+     * has been committed. This ensures we only acknowledge idempotent success when the state
+     * change is actually observable locally, not just because the result code matched.
+     */
+    async #isIdempotentSuccess(resultCode, message) {
+        if (!this.#idempotentSuccessCodes.has(resultCode)) return false;
+
+        const txHash = this.#extractTxHash(message);
+        if (!txHash) return false;
+
+        // A short wait covers the race where a first validator committed the tx
+        // and a retried validator only observes it as "already exists/completed".
+        const timeout = this.#config.messageValidatorResponseTimeout ?? 2000;
+        return await this.waitForUnsignedState(txHash, timeout);
     }
 
     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 this.state.waitForUnsigned(txHash, timeout);
+    }
+
+    #extractTxHash(message) {
+        if (!message || !Number.isInteger(message.type)) return null;
+
+        const payloadKey = operationToPayload(message.type);
+        const txHash = message?.[payloadKey]?.tx;
+        return typeof txHash === 'string' && txHash.length > 0 ? txHash : null;
+    }
+
+    // TODO: Delete this function after legacy protocol is deprecated
+    async #attemptSendMessageForLegacy(validatorPublicKey, message) {
+        const deductedTxType = operationToPayload(message.type);
+        await this.connectionManager.sendSingleMessage(message, validatorPublicKey);
+        const appeared = await this.state.waitForUnsigned(
+            message[deductedTxType].tx,
+            this.#config.messageValidatorResponseTimeout
+        );
+        if (appeared) {
+            this.incrementSentCount(validatorPublicKey);
+            if (this.shouldRemove(validatorPublicKey)) {
+                this.connectionManager.remove(validatorPublicKey);
+            }
+            return true;
         }
         return false;
     }

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

@@ -0,0 +1,175 @@
+import {NetworkOperationType, ResultCode} from '../../../utils/constants.js';
+import {isHexString, publicKeyToAddress} from '../../../utils/helpers.js';
+import {V1ProtocolError} from "../protocols/v1/V1ProtocolError.js";
+import b4a from 'b4a';
+
+const PEER_PUBLIC_KEY_HEX_LENGTH = 64;
+
+export class PendingRequestServiceTimeoutError extends Error {
+    constructor(requestId, peerAddress, timeoutMs) {
+        super(`Pending request ${requestId} to peer ${peerAddress} timed out after ${timeoutMs} ms.`);
+        this.name = this.constructor.name;
+    }
+}
+
+export default class PendingRequestService {
+    #pendingRequests;
+    #requestMessageTypes = [NetworkOperationType.LIVENESS_REQUEST, NetworkOperationType.BROADCAST_TRANSACTION_REQUEST];
+    #config;
+
+    constructor(config) {
+        this.#pendingRequests = new Map(); // Map<id, pendingRequestEntry>
+        this.#config = config;
+    }
+
+    has(id) {
+        return this.#pendingRequests.has(id);
+    }
+
+    isProbePending(peerPubKeyHex) {
+        for (const [, entry] of this.#pendingRequests) {
+            if (entry.requestedTo === peerPubKeyHex && entry.requestType === NetworkOperationType.LIVENESS_REQUEST) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    #validateRegisterInput(peerPubKeyHex, message) {
+        if (!isHexString(peerPubKeyHex) || peerPubKeyHex.length !== PEER_PUBLIC_KEY_HEX_LENGTH) {
+            throw new Error('Invalid peer public key. Expected 32-byte hex string.');
+        }
+
+        if (!message || typeof message !== 'object') {
+            throw new Error('Pending request message must be an object.');
+        }
+
+        if (typeof message.id !== 'string' || message.id.length === 0) {
+            throw new Error('Pending request ID must be a non-empty string.');
+        }
+
+        if (!this.#requestMessageTypes.includes(message.type)) {
+            throw new Error('Unsupported pending request type.');
+        }
+    }
+
+    /*
+    @returns {Promise}
+    */
+    registerPendingRequest(peerPubKeyHex, message) {
+        this.#validateRegisterInput(peerPubKeyHex, message);
+        const id = message.id;
+        const peerAddress = publicKeyToAddress(peerPubKeyHex, this.#config);
+        if (this.#pendingRequests.size >= this.#config.maxPendingRequestsInPendingRequestsService) {
+            throw new Error('Maximum number of pending requests reached.');
+        }
+
+        if (this.#pendingRequests.has(id)) {
+            throw new Error(`Pending request with ID ${id} from peer ${peerPubKeyHex} already exists.`);
+        }
+
+        const entry = {
+            id: id,
+            requestType: message.type,
+            requestTxData: this.#extractRequestTxData(message),
+            requestedTo: peerPubKeyHex,
+            timeoutId: null,
+            resolve: null,
+            reject: null,
+        }
+
+        const promise = new Promise((resolve, reject) => {
+            entry.resolve = resolve;
+            entry.reject = reject;
+        });
+
+        entry.timeoutId = setTimeout(() => {
+            this.rejectPendingRequest(
+                id,
+                new PendingRequestServiceTimeoutError(
+                    id,
+                    peerAddress,
+                    this.#config.pendingRequestTimeout
+                )
+            );
+
+        }, this.#config.pendingRequestTimeout);
+
+        this.#pendingRequests.set(id, entry);
+        return promise;
+    }
+
+    #extractRequestTxData(message) {
+        if (message.type !== NetworkOperationType.BROADCAST_TRANSACTION_REQUEST) return null;
+        const txData = message.broadcast_transaction_request?.data;
+        return b4a.isBuffer(txData) ? txData : null;
+    }
+
+    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;
+    }
+
+    // for now, we are resolving only resultCode, but we can extend it in the future if needed...
+    resolvePendingRequest(id, resultCode = ResultCode.OK) {
+        const entry = this.getAndDeletePendingRequest(id);
+        if (!entry) return false;
+        entry.resolve(resultCode);
+        return true;
+    }
+
+    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(
+                    new V1ProtocolError(
+                        ResultCode.UNEXPECTED_ERROR,
+                        `Pending request ${id} cancelled (shutdown).`)
+                );
+            } catch (error) {
+                console.error(`PendingRequestService.close: failed to reject pending request ${id}:`, error);
+            }
+        }
+        this.#pendingRequests.clear();
+    }
+}

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

@@ -0,0 +1,149 @@
+import {isHexString} from '../../../utils/helpers.js';
+import {TRANSACTION_COMMIT_SERVICE_BUFFER_SIZE} from '../../../utils/constants.js';
+
+const TX_HASH_HEX_STRING_LENGTH = 64;
+
+export class PendingCommitInvalidTxHashError extends Error {
+    constructor(txHash) {
+        super(`Invalid txHash format: ${txHash}`);
+    }
+}
+
+export class PendingCommitBufferFullError extends Error {
+    constructor(limit) {
+        super(`Maximum number of pending commits reached (limit=${limit}).`);
+    }
+}
+
+export class PendingCommitAlreadyExistsError extends Error {
+    constructor(txHash) {
+        super(`Pending commit for txHash ${txHash} already exists.`);
+    }
+}
+
+export class PendingCommitTimeoutError extends Error {
+    constructor(txHash, timeoutMs) {
+        super(`Pending commit for txHash ${txHash} timed out after ${timeoutMs} ms.`);
+    }
+}
+
+export class PendingCommitCancelledError extends Error {
+    constructor(txHash) {
+        super(`Pending commit ${txHash} cancelled (shutdown).`);
+    }
+}
+
+export class PendingCommitUnexpectedError extends Error {
+    constructor(message = 'Unexpected commit error') {
+        super(message);
+    }
+}
+
+class TransactionCommitService {
+    #pendingCommits;
+    #config;
+
+    constructor(config) {
+        this.#pendingCommits = new Map(); // Map<txHash, pendingCommitEntry>
+        this.#config = config;
+    }
+
+    #assertTxHash(txHash) {
+        if (!isHexString(txHash) || txHash.length !== TX_HASH_HEX_STRING_LENGTH) {
+            throw new PendingCommitInvalidTxHashError(txHash);
+        }
+    }
+
+    has(txHash) {
+        this.#assertTxHash(txHash);
+        return this.#pendingCommits.has(txHash);
+    }
+
+    /*
+        @returns {Promise}
+    */
+    registerPendingCommit(txHash) {
+        this.#assertTxHash(txHash);
+
+        if (this.#pendingCommits.size >= TRANSACTION_COMMIT_SERVICE_BUFFER_SIZE) {
+            throw new PendingCommitBufferFullError(TRANSACTION_COMMIT_SERVICE_BUFFER_SIZE);
+        }
+
+        if (this.#pendingCommits.has(txHash)) {
+            throw new PendingCommitAlreadyExistsError(txHash);
+        }
+
+        const timeoutMs = this.#config.txCommitTimeout;
+
+        const entry = {
+            txHash,
+            timeoutMs,
+            timeoutId: null,
+            resolve: null,
+            reject: null,
+        };
+
+        const promise = new Promise((resolve, reject) => {
+            entry.resolve = resolve;
+            entry.reject = reject;
+        });
+
+        entry.timeoutId = setTimeout(() => {
+            this.rejectPendingCommit(
+                txHash,
+                new PendingCommitTimeoutError(txHash, timeoutMs)
+            );
+        }, timeoutMs);
+
+        this.#pendingCommits.set(txHash, entry);
+        return promise;
+    }
+
+    getAndDeletePendingCommit(txHash) {
+        this.#assertTxHash(txHash);
+        const entry = this.#pendingCommits.get(txHash);
+        if (!entry) return null;
+
+        clearTimeout(entry.timeoutId);
+        this.#pendingCommits.delete(txHash);
+        return entry;
+    }
+
+    resolvePendingCommit(txHash, receipt = null) {
+        this.#assertTxHash(txHash);
+        const entry = this.getAndDeletePendingCommit(txHash);
+        if (!entry) return false;
+        entry.resolve(receipt);
+        return true;
+    }
+
+    rejectPendingCommit(txHash, error) {
+        this.#assertTxHash(txHash);
+        const entry = this.getAndDeletePendingCommit(txHash);
+        if (!entry) return false;
+
+        entry.reject(
+            error instanceof Error
+                ? error
+                : new PendingCommitUnexpectedError('Unexpected commit error')
+        );
+
+        return true;
+    }
+
+    close() {
+        for (const [txHash, entry] of this.#pendingCommits) {
+            clearTimeout(entry.timeoutId);
+            try {
+                entry.reject(
+                    new PendingCommitCancelledError(txHash)
+                );
+            } catch (error) {
+                console.error(`TransactionCommitService.close: failed to reject pending commit ${txHash}:`, error);
+            }
+        }
+        this.#pendingCommits.clear();
+    }
+}
+
+export default TransactionCommitService;