trac-msb 0.2.17 → 0.2.19

package/src/core/network/protocols/shared/validators/{PartialRoleAccess.js → PartialRoleAccessValidator.js}

@@ -1,10 +1,11 @@
 import b4a from 'b4a';
-import {OperationType} from "../../../../../utils/constants.js";
+import {OperationType, ResultCode} from "../../../../../utils/constants.js";
 import {bufferToAddress} from "../../../../state/utils/address.js";
-import PartialOperation from './base/PartialOperation.js';
+import PartialOperationValidator from './PartialOperationValidator.js';
 import {bufferToBigInt} from "../../../../../utils/amountSerialization.js";
+import {V1ProtocolError} from '../../v1/V1ProtocolError.js';
 
-class PartialRoleAccess extends PartialOperation {
+class PartialRoleAccessValidator extends PartialOperationValidator {
     #config;
 
     constructor(state, selfAddress, config) {
@@ -42,17 +43,26 @@ class PartialRoleAccess extends PartialOperation {
             const nodeAddress = bufferToAddress(payload.address, this.#config.addressPrefix);
             const nodeEntry = await this.state.getNodeEntry(nodeAddress);
             if (!nodeEntry) {
-                throw new Error(`Node with address ${nodeAddress} entry does not exist.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_NODE_ENTRY_NOT_FOUND,
+                    `Node with address ${nodeAddress} entry does not exist.`
+                );
             }
 
             const isNodeAlreadyWriter = nodeEntry.isWriter;
             if (isNodeAlreadyWriter) {
-                throw new Error(`Node with address ${nodeAddress} is already a writer.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_NODE_ALREADY_WRITER,
+                    `Node with address ${nodeAddress} is already a writer.`
+                );
             }
 
             const isNodeWhitelisted = nodeEntry.isWhitelisted;
             if (!isNodeWhitelisted) {
-                throw new Error(`Node with address ${nodeAddress} is not whitelisted.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_NODE_NOT_WHITELISTED,
+                    `Node with address ${nodeAddress} is not whitelisted.`
+                );
             }
             return;
 
@@ -60,24 +70,33 @@ class PartialRoleAccess extends PartialOperation {
             const nodeAddress = bufferToAddress(payload.address, this.#config.addressPrefix);
             const nodeEntry = await this.state.getNodeEntry(nodeAddress);
             if (!nodeEntry) {
-                throw new Error(`Node with address ${nodeAddress} entry does not exist.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_NODE_ENTRY_NOT_FOUND,
+                    `Node with address ${nodeAddress} entry does not exist.`
+                );
             }
 
             const isAlreadyWriter = nodeEntry.isWriter;
             if (!isAlreadyWriter) {
-                throw new Error(`Node with address ${nodeAddress} is not a writer.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_NODE_NOT_WRITER,
+                    `Node with address ${nodeAddress} is not a writer.`
+                );
             }
 
             const isAlreadyIndexer = nodeEntry.isIndexer;
             if (isAlreadyIndexer) {
-                throw new Error(`Node with address ${nodeAddress} is an indexer.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_NODE_IS_INDEXER,
+                    `Node with address ${nodeAddress} is an indexer.`
+                );
             }
             return;
 
         } else if (type === OperationType.ADMIN_RECOVERY) {
             const adminEntry = await this.state.getAdminEntry();
             if (!adminEntry) {
-                throw new Error('Admin entry does not exist.');
+                throw new V1ProtocolError(ResultCode.ROLE_ADMIN_ENTRY_MISSING, 'Admin entry does not exist.');
             }
 
             const adminAddressBuffer = payload.address;
@@ -87,20 +106,29 @@ class PartialRoleAccess extends PartialOperation {
                 !b4a.equals(payload.rao.iw, adminEntry.wk)
             );
             if (!isRecoveryCase) {
-                throw new Error(`Node with address ${adminAddress} is not a valid recovery case.`);
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_INVALID_RECOVERY_CASE,
+                    `Node with address ${adminAddress} is not a valid recovery case.`
+                );
             }
 
             return;
         }
 
-        throw new Error(`Unknown role access operation type: ${type}`);
+        throw new V1ProtocolError(
+            ResultCode.ROLE_UNKNOWN_OPERATION,
+            `Unknown role access operation type: ${type}`
+        );
     }
 
     async validateWriterKey(payload) {
         const requesterAddress = bufferToAddress(payload.address, this.#config.addressPrefix);
         const nodeEntry = await this.state.getNodeEntry(requesterAddress);
         if (!nodeEntry) {
-            throw new Error(`Node entry not found for address ${requesterAddress}`);
+            throw new V1ProtocolError(
+                ResultCode.REQUESTER_NOT_FOUND,
+                `Node entry not found for address ${requesterAddress}`
+            );
         }
 
         const writerKey = payload.rao.iw.toString('hex');
@@ -111,7 +139,10 @@ class PartialRoleAccess extends PartialOperation {
             const isOwner = b4a.equals(addressFromRegisteredWritingKey, payload.address);
 
             if (!isCurrentWk || !isOwner) {
-                throw new Error('Invalid writer key: either not owned by requester or different from assigned key');
+                throw new V1ProtocolError(
+                    ResultCode.ROLE_INVALID_WRITER_KEY,
+                    'Invalid writer key: either not owned by requester or different from assigned key'
+                );
             }
         }
     }
@@ -126,15 +157,18 @@ class PartialRoleAccess extends PartialOperation {
         }
 
         if (!requesterEntry) {
-            throw new Error('Requester address not found in state');
+            throw new V1ProtocolError(ResultCode.REQUESTER_NOT_FOUND, 'Requester address not found in state');
         }
         const requesterBalance = bufferToBigInt(requesterEntry.balance);
 
         const requiredBalance = this.fee * 11n;
         if (requesterBalance < requiredBalance) {
-            throw new Error('Insufficient requester balance to cover role access operation FEE.');
+            throw new V1ProtocolError(
+                ResultCode.ROLE_INSUFFICIENT_FEE_BALANCE,
+                'Insufficient requester balance to cover role access operation FEE.'
+            );
         }
     }
 }
 
-export default PartialRoleAccess;
+export default PartialRoleAccessValidator;

package/src/core/network/protocols/shared/validators/{PartialTransaction.js → PartialTransactionValidator.js}

@@ -1,9 +1,11 @@
 import b4a from 'b4a';
 import {safeDecodeApplyOperation} from "../../../../../utils/protobuf/operationHelpers.js";
 import deploymentEntryUtils from "../../../../state/utils/deploymentEntry.js";
-import PartialOperation from './base/PartialOperation.js';
+import PartialOperationValidator from './PartialOperationValidator.js';
+import {ResultCode} from "../../../../../utils/constants.js";
+import {V1ProtocolError} from '../../v1/V1ProtocolError.js';
 
-class PartialTransaction extends PartialOperation {
+class PartialTransactionValidator extends PartialOperationValidator {
     #config
 
     constructor(state, selfAddress, config) {
@@ -32,14 +34,20 @@ class PartialTransaction extends PartialOperation {
 
     validateMsbBootstrap(payload) {
         if (!b4a.equals(this.#config.bootstrap, payload.txo.mbs)) {
-            throw new Error(`Declared MSB bootstrap is different than network bootstrap in transaction operation: ${payload.txo.mbs.toString('hex')}`);
+            throw new V1ProtocolError(
+                ResultCode.MSB_BOOTSTRAP_MISMATCH,
+                `Declared MSB bootstrap is different than network bootstrap in transaction operation: ${payload.txo.mbs.toString('hex')}`
+            );
         }
     }
 
     async validateIfExternalBootstrapHasBeenDeployed(payload) {
         const externalBootstrapResult = await this.state.getRegisteredBootstrapEntry(payload.txo.bs.toString('hex'));
         if (externalBootstrapResult === null) {
-            throw new Error(`External bootstrap with hash ${payload.txo.bs.toString('hex')} is not registered as deployment entry.`);
+            throw new V1ProtocolError(
+                ResultCode.EXTERNAL_BOOTSTRAP_NOT_DEPLOYED,
+                `External bootstrap with hash ${payload.txo.bs.toString('hex')} is not registered as deployment entry.`
+            );
         }
 
         const decodedPayload = deploymentEntryUtils.decode(externalBootstrapResult, this.#config.addressLength);
@@ -47,17 +55,23 @@ class PartialTransaction extends PartialOperation {
         const getBootstrapTransactionTxPayload = await this.state.get(txHash.toString('hex'));
 
         if (getBootstrapTransactionTxPayload === null) {
-            throw new Error(`External bootstrap is not registered as usual tx ${externalBootstrapResult.toString('hex')}: ${payload}`);
+            throw new V1ProtocolError(
+                ResultCode.EXTERNAL_BOOTSTRAP_TX_MISSING,
+                `External bootstrap is not registered as usual tx ${externalBootstrapResult.toString('hex')}: ${payload}`
+            );
         }
 
         const decodedBootstrapDeployment = safeDecodeApplyOperation(getBootstrapTransactionTxPayload)
 
         // edge case
         if (!b4a.equals(decodedBootstrapDeployment.bdo.bs, payload.txo.bs)) {
-            throw new Error(`External bootstrap does not match the one in the transaction payload: ${decodedBootstrapDeployment.bdo.bs.toString('hex')} !== ${payload.txo.bs.toString('hex')}`);
+            throw new V1ProtocolError(
+                ResultCode.EXTERNAL_BOOTSTRAP_MISMATCH,
+                `External bootstrap does not match the one in the transaction payload: ${decodedBootstrapDeployment.bdo.bs.toString('hex')} !== ${payload.txo.bs.toString('hex')}`
+            );
         }
     }
 
 }
 
-export default PartialTransaction;
+export default PartialTransactionValidator;

package/src/core/network/protocols/shared/validators/{PartialTransfer.js → PartialTransferValidator.js}

@@ -1,10 +1,13 @@
-import PeerWallet from 'trac-wallet';
-
 import {bufferToAddress} from "../../../../state/utils/address.js";
 import {bufferToBigInt} from "../../../../../utils/amountSerialization.js";
-import PartialOperation from './base/PartialOperation.js';
-
-class PartialTransfer extends PartialOperation {
+import {ResultCode} from "../../../../../utils/constants.js";
+import { NULL_BUFFER } from '../../../../../utils/buffer.js';
+import PartialOperationValidator from './PartialOperationValidator.js';
+import {V1ProtocolError} from '../../v1/V1ProtocolError.js';
+import tracCryptoApi from "trac-crypto-api";
+import b4a from 'b4a';
+
+class PartialTransferValidator extends PartialOperationValidator {
     #config
 
     constructor(state, selfAddress, config) {
@@ -31,12 +34,18 @@ class PartialTransfer extends PartialOperation {
     #validateRecipientAddress(payload) {
         const incomingAddress = bufferToAddress(payload.tro.to, this.#config.addressPrefix);
         if (!incomingAddress) {
-            throw new Error('Invalid recipient address in transfer payload.');
+            throw new V1ProtocolError(
+                ResultCode.TRANSFER_RECIPIENT_ADDRESS_INVALID,
+                'Invalid recipient address in transfer payload.'
+            );
         }
 
-        const incomingPublicKey = PeerWallet.decodeBech32mSafe(incomingAddress);
-        if (incomingPublicKey === null) {
-            throw new Error('Invalid recipient public key in transfer payload.');
+        const incomingPublicKey = tracCryptoApi.address.decodeSafe(incomingAddress);
+        if (b4a.equals(incomingPublicKey, NULL_BUFFER)) {
+            throw new V1ProtocolError(
+                ResultCode.TRANSFER_RECIPIENT_PUBLIC_KEY_INVALID,
+                'Invalid recipient public key in transfer payload.'
+            );
         }
 
     }
@@ -47,7 +56,10 @@ class PartialTransfer extends PartialOperation {
 
         const transferAmount = bufferToBigInt(payload.tro.am);
         if (transferAmount > this.max_amount) {
-            throw new Error('Transfer amount exceeds maximum allowed value');
+            throw new V1ProtocolError(
+                ResultCode.TRANSFER_AMOUNT_TOO_LARGE,
+                'Transfer amount exceeds maximum allowed value'
+            );
         }
 
         const isSelfTransfer = senderAddress === recipientAddress;
@@ -55,12 +67,15 @@ class PartialTransfer extends PartialOperation {
 
         const senderEntry = await this.state.getNodeEntryUnsigned(senderAddress);
         if (!senderEntry) {
-            throw new Error('Sender account not found');
+            throw new V1ProtocolError(ResultCode.TRANSFER_SENDER_NOT_FOUND, 'Sender account not found');
         }
 
         const senderBalance = bufferToBigInt(senderEntry.balance);
         if (!(senderBalance >= totalDeductedAmount)) {
-            throw new Error('Insufficient balance for transfer' + (isSelfTransfer ? ' fee' : ' + fee'));
+            throw new V1ProtocolError(
+                ResultCode.TRANSFER_INSUFFICIENT_BALANCE,
+                'Insufficient balance for transfer' + (isSelfTransfer ? ' fee' : ' + fee')
+            );
         }
 
         if (!isSelfTransfer) {
@@ -69,11 +84,14 @@ class PartialTransfer extends PartialOperation {
                 const recipientBalance = bufferToBigInt(recipientEntry.balance);
                 const newRecipientBalance = recipientBalance + transferAmount;
                 if (newRecipientBalance > this.max_amount) {
-                    throw new Error('Transfer would cause recipient balance to exceed maximum allowed value');
+                    throw new V1ProtocolError(
+                        ResultCode.TRANSFER_RECIPIENT_BALANCE_OVERFLOW,
+                        'Transfer would cause recipient balance to exceed maximum allowed value'
+                    );
                 }
             }
         }
     }
 }
 
-export default PartialTransfer;
+export default PartialTransferValidator;

package/src/core/network/protocols/v1/NetworkMessageRouter.js

@@ -1,15 +1,99 @@
-import { MessageHeader } from '../../../../utils/protobuf/network.cjs';
+import { decodeV1networkOperation } from '../../../../utils/protobuf/operationHelpers.js'
+import b4a from 'b4a'
+import { NetworkOperationType, V1_PROTOCOL_PAYLOAD_MAX_SIZE } from '../../../../utils/constants.js'
+import { publicKeyToAddress } from '../../../../utils/helpers.js'
+import V1LivenessOperationHandler from './handlers/V1LivenessOperationHandler.js'
+import V1BroadcastTransactionOperationHandler from './handlers/V1BroadcastTransactionOperationHandler.js'
 
 class NetworkMessageRouterV1 {
-    #config;
+    #config
+    #livenessRequestHandler
+    #broadcastTransactionHandler
 
-    constructor(config) {
-        this.#config = config;
+    constructor(
+        state,
+        wallet,
+        rateLimiterService,
+        txPoolService,
+        pendingRequestsService,
+        transactionCommitService,
+        config
+    ) {
+        this.#config = config
+        this.#livenessRequestHandler = new V1LivenessOperationHandler(
+            wallet,
+            rateLimiterService,
+            pendingRequestsService,
+            config
+        );
+        this.#broadcastTransactionHandler = new V1BroadcastTransactionOperationHandler(
+            state,
+            wallet,
+            rateLimiterService,
+            txPoolService,
+            pendingRequestsService,
+            transactionCommitService,
+            config
+        );
     }
 
-    async route(incomingMessage) {
-        MessageHeader.decode(incomingMessage);
+    async route(incomingMessage, connection) {
+        if (!this.#preValidate(incomingMessage)) {
+            this.#disconnect(connection, 'Pre-validation failed for incoming V1 message')
+            return;
+        }
+        let decodedMessage;
+
+        try {
+            decodedMessage = decodeV1networkOperation(incomingMessage)
+        } catch (error) {
+            this.#disconnect(connection, `Failed to decode incoming V1 message: ${error.message}`)
+            return;
+        }
+
+        // TODO: Decide if we really need to check decodedMessage.type here, since this is done
+        // again in the next switch statement
+        if (!decodedMessage || !Number.isInteger(decodedMessage.type) || decodedMessage.type <= 0) {
+            this.#disconnect(connection, `Invalid V1 message type: ${decodedMessage?.type}`)
+            return;
+        }
+
+        // We received a v1 message, so we set the connection protocol accordingly
+        connection.protocolSession.setV1AsPreferredProtocol()
+
+        try {
+            switch (decodedMessage.type) {
+                case NetworkOperationType.LIVENESS_REQUEST:
+                    await this.#livenessRequestHandler.handleRequest(decodedMessage, connection);
+                    break;
+                case NetworkOperationType.LIVENESS_RESPONSE:
+                    await this.#livenessRequestHandler.handleResponse(decodedMessage, connection);
+                    break;
+
+                case NetworkOperationType.BROADCAST_TRANSACTION_REQUEST:
+                    await this.#broadcastTransactionHandler.handleRequest(decodedMessage, connection);
+                    break;
+
+                case NetworkOperationType.BROADCAST_TRANSACTION_RESPONSE:
+                    await this.#broadcastTransactionHandler.handleResponse(decodedMessage, connection);
+                    break;
+                default:
+                    this.#disconnect(connection, `Unsupported V1 message type: ${decodedMessage.type}`)
+            }
+        } catch (error) {
+            this.#disconnect(connection, `Unhandled error while routing V1 message: ${error.message}`)
+        }
+    }
+
+    #preValidate(incomingMessage) {
+        return !(!incomingMessage || !b4a.isBuffer(incomingMessage) || incomingMessage.length === 0 || incomingMessage.length > V1_PROTOCOL_PAYLOAD_MAX_SIZE);
+    }
+
+    #disconnect(connection, reason) {
+        const sender = publicKeyToAddress(connection.remotePublicKey, this.#config)
+        console.error(`NetworkMessageRouterV1: ${reason}, sender: ${sender}`)
+        connection.end();
     }
 }
 
-export default NetworkMessageRouterV1;
+export default NetworkMessageRouterV1

package/src/core/network/protocols/v1/V1ProtocolError.js

@@ -0,0 +1,27 @@
+import {ResultCode} from '../../../../utils/constants.js';
+
+/** 
+ * V1 protocol error type.
+ *
+ * `V1ProtocolError` is the v1 base class used by handlers/validators to attach:
+ * - `resultCode`: a stable `ResultCode` enum value for programmatic handling
+ */
+export class V1ProtocolError extends Error {
+    /**
+     * @param {number} resultCode Stable rejection reason (a `ResultCode` enum value).
+     * @param {string} message Human-readable error message.
+     */
+    constructor(resultCode, message) {
+        super(message);
+        this.name = this.constructor.name;
+        this.resultCode = resultCode;
+    }
+}
+
+export function getResultCode(err) {
+    return err instanceof V1ProtocolError ? err.resultCode : ResultCode.UNEXPECTED_ERROR;
+}
+
+export function shouldEndConnection(err) {
+    return err instanceof V1ProtocolError ? Boolean(err.endConnection) : false;
+}

package/src/core/network/protocols/v1/handlers/V1BaseOperationHandler.js

@@ -0,0 +1,66 @@
+import {ResultCode} from "../../../../../utils/constants.js";
+import {publicKeyToAddress} from "../../../../../utils/helpers.js";
+import {V1ProtocolError} from "../V1ProtocolError.js";
+
+class V1BaseOperationHandler {
+    #rateLimiterService;
+    #pendingRequestService;
+    #config;
+
+    constructor(rateLimiterService, pendingRequestService, config) {
+        this.#rateLimiterService = rateLimiterService;
+        this.#pendingRequestService = pendingRequestService;
+        this.#config = config;
+    }
+
+    get config() {
+        return this.#config;
+    }
+
+    applyRateLimit(connection) {
+        if (!this.#config.disableRateLimit) {
+            this.#rateLimiterService.v1HandleRateLimit(connection);
+        }
+    }
+
+    async resolvePendingResponse(message, connection, validator, extractResultCode) {
+        const pendingRequestServiceEntry = this.#pendingRequestService.getPendingRequest(message.id);
+        if (!pendingRequestServiceEntry) return false;
+
+        this.#pendingRequestService.stopPendingRequestTimeout(message.id);
+        await validator.validate(message, connection, pendingRequestServiceEntry);
+
+        const resultCode = extractResultCode(message);
+        this.#pendingRequestService.resolvePendingRequest(message.id, resultCode);
+        return true;
+    }
+
+    handlePendingResponseError(messageId, connection, error, step) {
+        const protocolError = this.#toProtocolError(error);
+        const rejected = this.#pendingRequestService.rejectPendingRequest(messageId, protocolError);
+        if (!rejected) return;
+        this.displayError(step, connection.remotePublicKey, protocolError);
+    }
+
+    async sendResponseAndMaybeClose(connection, response, endConnection) {
+        connection.protocolSession.sendAndForget(response);
+        if (!endConnection) return;
+
+        await connection.flush();
+        connection.end();
+    }
+
+    displayError(step = "undefined step", senderPublicKey, error) {
+        const errorMessage = error?.message ?? 'Unexpected error';
+        console.error(`${this.constructor.name}: ${step} ${publicKeyToAddress(senderPublicKey, this.#config)}: ${errorMessage}`);
+    }
+
+    #toProtocolError(error) {
+        if (error instanceof V1ProtocolError) {
+            return error;
+        }
+        return new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, error?.message ?? 'Unexpected error');
+    }
+}
+
+export default V1BaseOperationHandler;