trac-msb 0.2.12 → 0.2.13

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

@@ -0,0 +1,91 @@
+import {ResultCode} from '../../../../utils/constants.js';
+
+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;
+}
+
+/** 
+ * 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
+ * - `endConnection`: a transport hint (close peer connection after responding)
+ */
+export class V1ProtocolError extends Error {
+    /**
+     * @param {number} resultCode Stable rejection reason (a `ResultCode` enum value).
+     * @param {string} message Human-readable error message.
+     * @param {boolean} [endConnection=false] Whether the transport should end the connection after responding.
+     */
+    constructor(resultCode, message, endConnection = false) {
+        super(message);
+        this.name = this.constructor.name;
+        this.resultCode = resultCode;
+        this.endConnection = Boolean(endConnection);
+    }
+}
+
+export class V1InvalidPayloadError extends V1ProtocolError {
+    constructor(message = 'Invalid payload', endConnection = false) {
+        super(ResultCode.INVALID_PAYLOAD, message, endConnection);
+    }
+}
+
+export class V1TxInvalidPayloadError extends V1ProtocolError {
+    constructor(message = 'Invalid tx payload', endConnection = false) {
+        super(ResultCode.TX_INVALID_PAYLOAD, message, endConnection);
+    }
+}
+
+export class V1SignatureInvalidError extends V1ProtocolError {
+    constructor(message = 'Signature invalid', endConnection = true) {
+        super(ResultCode.SIGNATURE_INVALID, message, endConnection);
+    }
+}
+
+export class V1RateLimitedError extends V1ProtocolError {
+    constructor(message = 'Rate limited', endConnection = true) {
+        super(ResultCode.RATE_LIMITED, message, endConnection);
+    }
+}
+
+export class V1UnexpectedError extends V1ProtocolError {
+    constructor(message = 'Unexpected error', endConnection = true) {
+        super(ResultCode.UNEXPECTED_ERROR, message, endConnection);
+    }
+}
+
+export class V1TimeoutError extends V1ProtocolError {
+    constructor(message = 'Request timed out', endConnection = false) {
+        super(ResultCode.TIMEOUT, message, endConnection);
+    }
+}
+
+export class V1NodeHasNoWriteAccess extends V1ProtocolError {
+    constructor(message = 'Node has no write access', endConnection = true) {
+        super(ResultCode.NODE_HAS_NO_WRITE_ACCESS, message, endConnection);
+    }
+}
+
+export class V1TxAcceptedProofUnavailable extends V1ProtocolError {
+    constructor(message = 'Transaction accepted but proof is unavailable', endConnection = false, timestamp = 0) {
+        super(ResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE, message, endConnection);
+        this.timestamp = Number.isSafeInteger(timestamp) && timestamp > 0 ? timestamp : 0;
+    }
+}
+
+export class V1NodeOverloadedError extends V1ProtocolError {
+    constructor(message = 'Commit queue is full', endConnection = true) {
+        super(ResultCode.NODE_OVERLOADED, message, endConnection);
+    }
+}
+
+export class V1TxAlreadyPendingError extends V1ProtocolError {
+    constructor(message = 'Transaction is already pending', endConnection = false) {
+        super(ResultCode.TX_ALREADY_PENDING, message, endConnection);
+    }
+}

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

@@ -0,0 +1,65 @@
+import {publicKeyToAddress} from "../../../../../utils/helpers.js";
+import {V1ProtocolError, V1UnexpectedError} 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 V1UnexpectedError(error?.message ?? 'Unexpected error');
+    }
+}
+
+export default V1BaseOperationHandler;

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

@@ -0,0 +1,389 @@
+import {networkMessageFactory} from "../../../../../messages/network/v1/networkMessageFactory.js";
+import {
+    NETWORK_CAPABILITIES,
+    OperationType,
+    ResultCode
+} from "../../../../../utils/constants.js";
+import {
+    getResultCode,
+    V1TxInvalidPayloadError,
+    V1NodeHasNoWriteAccess,
+    shouldEndConnection,
+    V1TxAcceptedProofUnavailable,
+    V1UnexpectedError,
+    V1NodeOverloadedError,
+    V1TxAlreadyPendingError,
+    V1TimeoutError,
+    V1ProtocolError
+} from "../V1ProtocolError.js";
+import V1BroadcastTransactionRequest from "../validators/V1BroadcastTransactionRequest.js";
+import {
+    unsafeDecodeApplyOperation,
+    unsafeEncodeApplyOperation
+} from "../../../../../utils/protobuf/operationHelpers.js";
+import {isBootstrapDeployment, isRoleAccess, isTransaction, isTransfer} from '../../../../../utils/applyOperations.js';
+import PartialRoleAccessValidator from "../../shared/validators/PartialRoleAccessValidator.js";
+import PartialBootstrapDeploymentValidator from "../../shared/validators/PartialBootstrapDeploymentValidator.js";
+import PartialTransactionValidator from "../../shared/validators/PartialTransactionValidator.js";
+import PartialTransferValidator from "../../shared/validators/PartialTransferValidator.js";
+import {applyStateMessageFactory} from "../../../../../messages/state/applyStateMessageFactory.js";
+import V1BroadcastTransactionResponse from "../validators/V1BroadcastTransactionResponse.js";
+import V1BaseOperationHandler from "./V1BaseOperationHandler.js";
+import {
+    TransactionPoolMissingCommitReceiptError,
+    TransactionPoolProofUnavailableError,
+    TransactionPoolFullError, TransactionPoolInvalidIncomingDataError, TransactionPoolAlreadyQueuedError
+} from "../../../services/TransactionPoolService.js";
+import {
+    PendingCommitInvalidTxHashError,
+    PendingCommitAlreadyExistsError,
+    PendingCommitBufferFullError, PendingCommitTimeoutError
+} from "../../../services/TransactionCommitService.js";
+import b4a from "b4a";
+
+class V1BroadcastTransactionOperationHandler extends V1BaseOperationHandler {
+    #state;
+    #wallet;
+    #txPoolService;
+    #broadcastTransactionRequestValidator;
+    #broadcastTransactionResponseValidator;
+    #partialRoleAccessValidator;
+    #partialBootstrapDeploymentValidator;
+    #partialTransactionValidator;
+    #partialTransferValidator;
+    #transactionCommitService;
+
+    constructor(state, wallet, rateLimiterService, txPoolService, pendingRequestService, transactionCommitService, config) {
+        super(rateLimiterService, pendingRequestService, config);
+        this.#state = state;
+        this.#wallet = wallet;
+        this.#txPoolService = txPoolService;
+        this.#broadcastTransactionRequestValidator = new V1BroadcastTransactionRequest(config);
+        this.#partialRoleAccessValidator = new PartialRoleAccessValidator(state, this.#wallet.address, config);
+        this.#partialBootstrapDeploymentValidator = new PartialBootstrapDeploymentValidator(state, this.#wallet.address, config);
+        this.#partialTransactionValidator = new PartialTransactionValidator(state, this.#wallet.address, config);
+        this.#partialTransferValidator = new PartialTransferValidator(state, this.#wallet.address, config);
+        this.#broadcastTransactionResponseValidator = new V1BroadcastTransactionResponse(state, config);
+        this.#transactionCommitService = transactionCommitService;
+    }
+
+    async handleRequest(message, connection) {
+        let resultCode = ResultCode.OK;
+        let endConnection = false;
+        let proof = null
+        let timestamp = 0;
+
+        try {
+            this.applyRateLimit(connection);
+            await this.#broadcastTransactionRequestValidator.validate(message, connection.remotePublicKey);
+            await this.#validationCapability();
+            this.#isTxPoolFull();
+            const decodedTransaction = this.decodeApplyOperation(message.broadcast_transaction_request.data);
+            this.#sanitizeDecodedPartialTransaction(decodedTransaction);
+            const receipt = await this.dispatchTransaction(decodedTransaction);
+            proof = receipt.proof;
+            timestamp = receipt.timestamp;
+        } catch (error) {
+            const protocolError = error instanceof V1ProtocolError
+                ? error
+                : new V1UnexpectedError(error?.message ?? 'Unexpected error', true);
+            resultCode = getResultCode(protocolError);
+            if (
+                resultCode === ResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE &&
+                Number.isSafeInteger(protocolError.timestamp) &&
+                protocolError.timestamp > 0
+            ) {
+                timestamp = protocolError.timestamp;
+            }
+            endConnection = shouldEndConnection(protocolError);
+            this.displayError(
+                "failed to process broadcast transaction request from sender",
+                connection.remotePublicKey,
+                protocolError
+            );
+        }
+
+        try {
+            const response = await this.#buildBroadcastTransactionResponse(
+                message.id,
+                NETWORK_CAPABILITIES,
+                proof,
+                timestamp,
+                resultCode,
+            );
+
+            await this.sendResponseAndMaybeClose(
+                connection,
+                response,
+                endConnection
+            );
+        } catch (error) {
+            this.displayError(
+                "failed to build/send response to sender",
+                connection.remotePublicKey,
+                error
+            );
+            connection.end();
+        }
+    }
+
+    async handleResponse(message, connection) {
+        try {
+            this.applyRateLimit(connection);
+            await this.resolvePendingResponse(
+                message,
+                connection,
+                this.#broadcastTransactionResponseValidator,
+                this.#extractBroadcastResultCode,
+            );
+        } catch (error) {
+            this.handlePendingResponseError(
+                message.id,
+                connection,
+                error,
+                "failed to process broadcast transaction response from sender"
+            );
+        }
+    }
+
+    async #buildBroadcastTransactionResponse(id, capabilities, proof, timestamp = null, resultCode) {
+        try {
+            return await networkMessageFactory(this.#wallet, this.config).buildBroadcastTransactionResponse(
+                id,
+                capabilities,
+                resultCode,
+                proof,
+                timestamp
+            );
+        } catch (error) {
+            throw new V1UnexpectedError(`Failed to build broadcast transaction response: ${error.message}`);
+        }
+    }
+
+    decodeApplyOperation(message) {
+        try {
+            return unsafeDecodeApplyOperation(message);
+        } catch (error) {
+            throw new V1UnexpectedError(`Failed to decode apply operation from message: ${error.message}`);
+        }
+    }
+
+    #sanitizeDecodedPartialTransaction(decodedTransaction) {
+        // Protobuf decode sets optional completion fields as null, but partial validators expect those fields to be absent.
+        // Otherwise, the presence of null fields causes validation to fail with "Expected type X but got null" errors.
+
+        const type = decodedTransaction?.type;
+        const operationKey = this.#getOperationPayloadKey(type);
+
+        if (!operationKey || !decodedTransaction?.[operationKey] || typeof decodedTransaction[operationKey] !== 'object') {
+            return;
+        }
+
+        for (const completionField of ['va', 'vn', 'vs']) {
+            if (decodedTransaction[operationKey][completionField] === null) {
+                delete decodedTransaction[operationKey][completionField];
+            }
+        }
+    }
+
+    #getOperationPayloadKey(type) {
+        if (isRoleAccess(type)) return 'rao';
+        if (isTransaction(type)) return 'txo';
+        if (isBootstrapDeployment(type)) return 'bdo';
+        if (isTransfer(type)) return 'tro';
+        return null;
+    }
+
+    #isTxPoolFull() {
+        try {
+            this.#txPoolService.validateEnqueue();
+        } catch (error) {
+            if (error instanceof TransactionPoolFullError) {
+                throw new V1NodeOverloadedError('Transaction pool is full, ignoring incoming transaction.');
+            }
+            throw error;
+        }
+    }
+
+    async #validationCapability() {
+        const isAllowedToValidate = await this.#state.allowedToValidate(this.#wallet.address);
+        const isAdminAllowedToValidate = await this.#state.isAdminAllowedToValidate();
+        const canValidate = isAllowedToValidate || isAdminAllowedToValidate;
+        if (!canValidate) {
+            throw new V1NodeHasNoWriteAccess('State is not writable or is an indexer without admin privileges.');
+        }
+    }
+
+    async dispatchTransaction(decodedTransaction) {
+        if (!decodedTransaction || !Number.isInteger(decodedTransaction.type) || decodedTransaction.type === 0) {
+            throw new V1TxInvalidPayloadError('Decoded transaction type is missing.', false);
+        }
+        if (!this.#transactionCommitService) {
+            throw new V1UnexpectedError('TransactionCommitService is not configured.');
+        }
+
+        const type = decodedTransaction.type;
+        let completeTransactionOperation;
+
+        // TODO: Consider moving logic below to strategy design pattern.
+        if (isRoleAccess(type)) {
+            await this.#partialRoleAccessValidator.validate(decodedTransaction);
+            completeTransactionOperation = await this.#buildCompleteRoleAccessOperation(decodedTransaction);
+        } else if (isTransaction(type)) {
+            await this.#partialTransactionValidator.validate(decodedTransaction);
+            completeTransactionOperation = await this.#buildCompleteTransactionOperation(decodedTransaction);
+        } else if (isBootstrapDeployment(type)) {
+            await this.#partialBootstrapDeploymentValidator.validate(decodedTransaction);
+            completeTransactionOperation = await this.#buildCompleteBootstrapDeploymentOperation(decodedTransaction);
+        } else if (isTransfer(type)) {
+            await this.#partialTransferValidator.validate(decodedTransaction);
+            completeTransactionOperation = await this.#buildCompleteTransferOperation(decodedTransaction);
+        } else {
+            throw new V1TxInvalidPayloadError(`Unsupported transaction type: ${type}`, false);
+        }
+
+        const payloadKey = this.#getOperationPayloadKey(type);
+        const txHash = b4a.toString(decodedTransaction[payloadKey].tx, 'hex');
+
+        const encodedCompleteTransaction = unsafeEncodeApplyOperation(completeTransactionOperation);
+        let pendingCommit;
+
+        try {
+            pendingCommit = this.#transactionCommitService.registerPendingCommit(txHash);
+            pendingCommit.catch(() => {});
+        } catch (error) {
+            if (error instanceof PendingCommitInvalidTxHashError) {
+                throw new V1ProtocolError(ResultCode.TX_HASH_INVALID_FORMAT, error.message, false);
+            }
+            if (error instanceof PendingCommitAlreadyExistsError) {
+                throw new V1TxAlreadyPendingError(error.message);
+            }
+            if (error instanceof PendingCommitBufferFullError) {
+                throw new V1NodeOverloadedError(error.message);
+            }
+            throw error;
+        }
+
+        try {
+            this.#txPoolService.addTransaction(txHash, encodedCompleteTransaction);
+        } catch (error) {
+            let err = error;
+            if (error instanceof TransactionPoolFullError) {
+                err = new V1NodeOverloadedError(error.message);
+            } else if (error instanceof TransactionPoolAlreadyQueuedError) {
+                err = new V1TxAlreadyPendingError(error.message);
+            } else if (error instanceof TransactionPoolInvalidIncomingDataError) {
+                err = new V1ProtocolError(
+                    ResultCode.INTERNAL_ENQUEUE_VALIDATION_FAILED,
+                    `Internal enqueue validation failed: ${error.message}`,
+                    false
+                );
+            }
+            this.#transactionCommitService.rejectPendingCommit(txHash, err);
+            throw err; // will be mapped anyway on lower level.
+        }
+
+        let receipt;
+        try {
+            receipt = await pendingCommit;
+        } catch (error) {
+            if (error instanceof TransactionPoolProofUnavailableError) {
+                throw new V1TxAcceptedProofUnavailable(error.message, false, error.timestamp);
+            }
+            if (error instanceof TransactionPoolMissingCommitReceiptError) {
+                throw new V1ProtocolError(ResultCode.TX_COMMITTED_RECEIPT_MISSING, error.message, false);
+            }
+            if (error instanceof PendingCommitTimeoutError) {
+                throw new V1TimeoutError(error.message);
+            }
+            throw error;
+        }
+
+        return receipt;
+    }
+
+
+    //TODO: Move responsibility to new class (next 4 functions)
+    async #buildCompleteRoleAccessOperation(decodedTransaction) {
+        const factory = applyStateMessageFactory(this.#wallet, this.config);
+
+        switch (decodedTransaction.type) {
+            case OperationType.ADD_WRITER:
+                return factory.buildCompleteAddWriterMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.rao.tx,
+                    decodedTransaction.rao.txv,
+                    decodedTransaction.rao.iw,
+                    decodedTransaction.rao.in,
+                    decodedTransaction.rao.is
+                );
+            case OperationType.REMOVE_WRITER:
+                return factory.buildCompleteRemoveWriterMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.rao.tx,
+                    decodedTransaction.rao.txv,
+                    decodedTransaction.rao.iw,
+                    decodedTransaction.rao.in,
+                    decodedTransaction.rao.is
+                );
+            case OperationType.ADMIN_RECOVERY:
+                return factory.buildCompleteAdminRecoveryMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.rao.tx,
+                    decodedTransaction.rao.txv,
+                    decodedTransaction.rao.iw,
+                    decodedTransaction.rao.in,
+                    decodedTransaction.rao.is
+                );
+            default:
+                throw new V1TxInvalidPayloadError(`Unsupported role access transaction type: ${decodedTransaction.type}`, false);
+        }
+    }
+
+    async #buildCompleteTransactionOperation(decodedTransaction) {
+        return applyStateMessageFactory(this.#wallet, this.config)
+            .buildCompleteTransactionOperationMessage(
+                decodedTransaction.address,
+                decodedTransaction.txo.tx,
+                decodedTransaction.txo.txv,
+                decodedTransaction.txo.iw,
+                decodedTransaction.txo.in,
+                decodedTransaction.txo.ch,
+                decodedTransaction.txo.is,
+                decodedTransaction.txo.bs,
+                decodedTransaction.txo.mbs
+            );
+    }
+
+    async #buildCompleteBootstrapDeploymentOperation(decodedTransaction) {
+        return applyStateMessageFactory(this.#wallet, this.config)
+            .buildCompleteBootstrapDeploymentMessage(
+                decodedTransaction.address,
+                decodedTransaction.bdo.tx,
+                decodedTransaction.bdo.txv,
+                decodedTransaction.bdo.bs,
+                decodedTransaction.bdo.ic,
+                decodedTransaction.bdo.in,
+                decodedTransaction.bdo.is
+            );
+    }
+
+    async #buildCompleteTransferOperation(decodedTransaction) {
+        return applyStateMessageFactory(this.#wallet, this.config)
+            .buildCompleteTransferOperationMessage(
+                decodedTransaction.address,
+                decodedTransaction.tro.tx,
+                decodedTransaction.tro.txv,
+                decodedTransaction.tro.in,
+                decodedTransaction.tro.to,
+                decodedTransaction.tro.am,
+                decodedTransaction.tro.is
+            );
+    }
+
+    #extractBroadcastResultCode(payload) {
+        return payload.broadcast_transaction_response.result;
+    }
+}
+
+export default V1BroadcastTransactionOperationHandler;

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

@@ -0,0 +1,87 @@
+import { networkMessageFactory } from "../../../../../messages/network/v1/networkMessageFactory.js";
+import { NETWORK_CAPABILITIES, ResultCode } from "../../../../../utils/constants.js";
+import V1LivenessRequest from "../validators/V1LivenessRequest.js";
+import {getResultCode, shouldEndConnection, V1UnexpectedError} from "../V1ProtocolError.js";
+import V1LivenessResponse from "../validators/V1LivenessResponse.js";
+import V1BaseOperationHandler from "./V1BaseOperationHandler.js";
+
+class V1LivenessOperationHandler extends V1BaseOperationHandler {
+    #wallet;
+    #v1LivenessRequestValidator;
+    #v1LivenessResponseValidator;
+
+    constructor(wallet, rateLimiterService, pendingRequestService, config) {
+        super(rateLimiterService, pendingRequestService, config);
+        this.#wallet = wallet;
+        this.#v1LivenessRequestValidator = new V1LivenessRequest(config);
+        this.#v1LivenessResponseValidator = new V1LivenessResponse(config);
+    }
+
+    async handleRequest(message, connection) {
+        let resultCode = ResultCode.OK;
+        let endConnection = false;
+        try {
+            this.applyRateLimit(connection);
+            await this.#v1LivenessRequestValidator.validate(message, connection.remotePublicKey);
+        } catch (error) {
+            resultCode = getResultCode(error);
+            endConnection = shouldEndConnection(error);
+            this.displayError("failed to process liveness request from sender",
+                connection.remotePublicKey,
+                error
+            );
+        }
+
+        try {
+            const response = await this.#buildLivenessResponsePayload(message.id, NETWORK_CAPABILITIES, resultCode);
+            await this.sendResponseAndMaybeClose(
+                connection,
+                response,
+                endConnection
+            );
+        } catch (error) {
+            this.displayError("failed to build/send response to sender",
+                connection.remotePublicKey,
+                error
+            );
+            connection.end();
+        }
+    }
+
+    async handleResponse(message, connection) {
+        try {
+            this.applyRateLimit(connection);
+            await this.resolvePendingResponse(
+                message,
+                connection,
+                this.#v1LivenessResponseValidator,
+                this.#extractLivenessResultCode
+            );
+        } catch (error) {
+            this.handlePendingResponseError(
+                message.id,
+                connection,
+                error,
+                "Failed to process liveness response from sender"
+            );
+        }
+    }
+
+    async #buildLivenessResponsePayload(id, capabilities, resultCode) {
+        try {
+            return await networkMessageFactory(this.#wallet, this.config).buildLivenessResponse(
+                id,
+                capabilities,
+                resultCode
+            );
+        } catch (error) {
+            throw new V1UnexpectedError(`Failed to build liveness response: ${error.message}`);
+        }
+    }
+
+    #extractLivenessResultCode(payload) {
+        return payload.liveness_response.result;
+    }
+}
+
+export default V1LivenessOperationHandler;